diff --git a/IMPROVEMENTS/01-observation-ledger.md b/IMPROVEMENTS/01-observation-ledger.md new file mode 100644 index 0000000..071478f --- /dev/null +++ b/IMPROVEMENTS/01-observation-ledger.md @@ -0,0 +1,64 @@ +# Observation Ledger and Provenance Timeline + +## Feature + +Add a local-first observation ledger that records every accepted external +observation with its source, acquisition time, source timestamp, freshness, +transformations, uncertainty, and lifecycle state. The ledger would power a +timeline drawer, per-entity provenance panels, and truthful “last seen” labels +across flights, vessels, satellites, fires, earthquakes, CCTV, traffic, and +mapped context. + +## Why it is valuable + +The globe currently combines live, cached, modeled, bundled, and inferred data. +The UI already works hard to distinguish `LOADING`, `STALE`, `FALLBACK`, and +`UNKNOWN`; a durable ledger would make that distinction inspectable instead of +leaving it only in transient chips. It would answer the questions a curious +user immediately has: “When was this position observed?”, “Did this come from +OpenSky or a fallback?”, “Was this route inferred?”, and “What changed while I +was looking away?” It also creates the foundation for history, export, replay, +and reproducible bug reports. + +## Implementation + +Create `src/observations/` with a schema version, normalizers, an append-only +writer, retention policy, and query helpers. A normalized record should contain +`observationId`, `entityKey`, `entityType`, `sourceId`, `sourceVersion`, +`observedAt`, `receivedAt`, `validUntil`, `geometry`, `properties`, +`derivation[]`, `uncertainty`, `quality`, and `status`. `derivation` must name +operations such as “adsb.lol regional fallback”, “route estimated from callsign”, +or “CCTV pose calibrated by operator”; it must never imply certainty the source +does not provide. + +Adapt the manager and each layer at its ingestion boundary rather than logging +Cesium primitives. The layer remains responsible for source-specific parsing; +the ledger receives the canonical record after validation and before rendering. +Use IndexedDB, not `localStorage`, with object stores for observations, source +metadata, spatial buckets, and schema migrations. Keep a bounded default such as +24 hours or 250 MB, expose retention controls, and discard raw provider payloads +unless the user explicitly enables diagnostic capture. + +Add a `PROVENANCE` action to entity cards and tracked readouts. The panel should +show source, source time, receive time, age, cache/fallback state, and a compact +confidence explanation. A timeline scrubber should query ledger records without +pretending that missing observations mean no activity. “No observation in this +window” must remain visibly different from “observed absent.” + +## Testing and rollout + +Unit-test schema migration, clock skew, duplicate observation IDs, out-of-order +updates, retention, quota exhaustion, and every source-to-provenance mapping. +Add contract tests asserting that stale cached OpenSky data, modeled traffic, +bundled infrastructure, and inferred CCTV projections receive distinct labels. +Use a feature flag for writes first, then enable the drawer, then make selected +entity provenance visible. Add a synthetic fixture mode so QA can inspect a +complete timeline without network access. + +## Definition of done + +An entity can be selected, its provenance can be read, and its observation age +survives a reload. A source outage preserves the last known record with a clear +stale state. Exported records contain enough source and transformation metadata +for another user to understand what the app knew and when, while no private +credentials or raw provider secrets enter the ledger. diff --git a/IMPROVEMENTS/02-time-machine.md b/IMPROVEMENTS/02-time-machine.md new file mode 100644 index 0000000..ea69265 --- /dev/null +++ b/IMPROVEMENTS/02-time-machine.md @@ -0,0 +1,62 @@ +# Time Machine and Deterministic World Replay + +## Feature + +Add a time controller that lets users move from live mode into a recorded time +window, scrub observations, pause, change playback speed, and return to live +without losing the current camera, style, or layer intent. The first release +should replay normalized ledger observations rather than attempting to archive +every provider payload or reproduce a provider's historical API. + +## Why it is valuable + +The project already has a strong present-tense experience and a cinematic +director. Time is the missing dimension: a user should be able to see an +airport change, compare a fire perimeter, follow a launch, or explain why a +contact appeared and disappeared. Replay also makes QA repeatable. A captured +ledger slice can reproduce a rendering issue without waiting for a live source +to enter the right state. + +## Implementation + +Build `src/time/timeController.js` around explicit modes: `LIVE`, `PAUSED_LIVE`, +`REPLAY`, and `RETURNING_TO_LIVE`. It owns a monotonic playhead, a selected +window, playback rate, and a replay session ID. Every consumer receives a +read-only clock and a stream cursor; it must not call `Date.now()` to decide +whether a replayed observation is current. + +Add a replay adapter to `DataLayerManager`. In live mode layers keep their +existing lifecycle and polling. In replay mode, polling is suspended, network +requests are not silently made, and adapters consume records from the ledger. +Layers that cannot replay should remain enabled only if they declare a static +or unavailable replay policy. For example, a bundled boundary can remain +visible, while a live CCTV frame should say `NO FRAME AT PLAYHEAD` rather than +showing a current image under historical geometry. + +The UI needs a bottom time rail with live/recorded status, a visible date and +UTC time, play/pause, speed, range selection, and a “return to live” action. +The camera should hold its pose while scrubbing unless the user chooses +“follow selected entity.” Entity trails need a clear distinction between +observed positions and interpolated segments. Interpolation may be offered for +visual continuity, but its styling and metadata must say `INTERPOLATED`. + +Extend share links with a versioned time window and playhead, bounded to a +portable ledger export or a server-hosted recording ID. Never put arbitrary +history claims in a URL that another machine cannot access. + +## Tests and failure behavior + +Test clock monotonicity, reverse scrubbing, source timestamps that arrive out +of order, daylight-saving boundaries, missing intervals, layer opt-out, and +return-to-live while an update is in flight. A replay session must cancel old +cursor callbacks just as existing camera and radio flows cancel stale work. +When the ledger is empty, the controller should explain that no recording is +available; it must not show an empty globe as historical truth. + +## Definition of done + +A user can record or import a bounded session, scrub it offline, see truthful +observed/interpolated/unavailable states, and return to a fresh live session +without reloading the page. A replay can be run twice from the same export and +produce the same entity positions, layer statuses, camera events, and screenshot +timestamps. diff --git a/IMPROVEMENTS/03-event-correlation.md b/IMPROVEMENTS/03-event-correlation.md new file mode 100644 index 0000000..ef613bd --- /dev/null +++ b/IMPROVEMENTS/03-event-correlation.md @@ -0,0 +1,60 @@ +# Explainable Event Correlation Board + +## Feature + +Add a user-authored correlation workspace that groups related public signals +around a place and time: for example, a launch window with satellite passes, +nearby aircraft, a reported earthquake, or a fire detection near a road closure. +The board should present hypotheses and evidence, never declare intelligence +judgments as facts. + +## Why it is valuable + +The app already places many signals on one globe, but the user must mentally +remember relationships. A correlation board turns that visual fusion into a +repeatable investigation artifact while respecting the project's public-data +and responsible-use boundary. It is useful for education, journalism, +geospatial exploration, and debugging source disagreement. + +## Implementation + +Create `src/correlation/` with a typed `CorrelationWorkspace`, `EvidenceRef`, +and `Hypothesis` model. Evidence references should point to ledger observation +IDs, not copy mutable layer objects. A workspace contains an area geometry, +time interval, selected entity IDs, user notes, and optional rules such as +“within 25 km” or “within 30 minutes.” + +Add a right-rail mode with an evidence table, a map highlight group, a compact +timeline, and a note editor. Selecting a row should focus the globe without +changing the underlying layer visibility. Each evidence row shows source, +freshness, and uncertainty. A generated summary, if voice/AI is enabled, must +be constrained to the evidence payload and use wording such as “may be related” +or “co-occurs in this window.” It must never identify a person or infer intent. + +Implement deterministic local correlation functions first: spatial distance, +temporal overlap, heading similarity, source agreement, and shared route or +location identifiers. Keep an explicit `explanation[]` with each match so the +UI can say why two records were grouped. Later, a server-side or model-assisted +ranker may suggest candidates, but suggestions must remain unaccepted until the +user pins them as evidence. + +Support JSON and Markdown export with a source manifest, UTC timestamps, map +center, and a “limitations” section. Persist workspaces in IndexedDB and add a +share-link mode only for explicitly exported, bounded workspaces; never expose +API keys or private notes by default. + +## Testing and rollout + +Test geodesic edge cases near the antimeridian and poles, time-window +boundaries, stale evidence, deleted ledger records, duplicate entities, and +the rule that people are not a searchable entity type. Add visual tests for +highlight coexistence with tracking, detection overlays, cockpit mode, and +Context isolation. Start with a read-only “group these selected records” flow +before adding saved hypotheses. + +## Definition of done + +Users can create a workspace from visible public observations, see every match's +mathematical explanation and source age, annotate it locally, and export a +portable artifact that another person can audit without trusting an opaque +score. diff --git a/IMPROVEMENTS/04-adaptive-scene-budget.md b/IMPROVEMENTS/04-adaptive-scene-budget.md new file mode 100644 index 0000000..b59f42b --- /dev/null +++ b/IMPROVEMENTS/04-adaptive-scene-budget.md @@ -0,0 +1,64 @@ +# Adaptive Scene Budget and Global Level-of-Detail Planner + +## Feature + +Add a centralized scene-budget planner that allocates a frame-time and memory +budget across all visible layers based on camera altitude, viewport area, +interaction state, and measured performance. It should make dense combinations +such as infrastructure, traffic, vessels, labels, and detections usable without +requiring every layer to invent its own cap. + +## Why it is valuable + +The current render governor correctly prevents unnecessary continuous rendering, +and individual layers already have caps, LOD rules, clustering, and allocation +tests. The remaining problem is global competition: turning on many honest +layers can still overwhelm a laptop because each layer optimizes locally. The +current state explicitly notes that bundled infrastructure is too dense for a +first-run mission. A shared planner would make that mode viable and make the +performance contract easier to reason about. + +## Implementation + +Create `src/performance/sceneBudget.js` with a frame sampler that tracks rolling +CPU frame time, GPU timing when available, entity counts, draw-call proxies, +and memory-pressure signals. Add a declarative layer budget descriptor: +`priority`, `minimumVisibleCount`, `maxVisibleCount`, `costEstimate`, `supportsLOD`, +`supportsClustering`, and `degradationSteps`. The planner emits a read-only +allocation to each layer; it never mutates layer state or quietly disables a +user-selected source. + +Define degradation steps such as full geometry, simplified geometry, clustered +points, labels off, distant entities off, and paused refresh. Preserve a minimum +honest representation and expose the active step in the layer row as +`DECLUTTERED`, `REDUCED`, or `PAUSED BY PERFORMANCE`. Tracked entities, active +selection, and explicit cockpit subjects receive reserved budget and must not +disappear because of a global cap. + +Integrate with `renderGovernor.js`, `labelArbiter.js`, `focusAllocations.js`, +traffic's per-road budget, AIS caps, and infrastructure loaders. At global scale, +use a coarse spatial index and tile-level summaries; load detailed entities only +inside the camera's priority cone and a small prefetch ring. The planner should +adapt slowly with hysteresis so panning does not cause visible oscillation. + +Add a diagnostics popover showing frame time, active budget, per-layer cost, +visible count, and the reason for each reduction. Include a “quality lock” for +recording and a “performance first” mode for weak devices. Quality lock should +warn when the chosen target cannot be maintained instead of lying about capture +quality. + +## Tests and rollout + +Use deterministic synthetic layer descriptors to test fairness, priority, +hysteresis, minimum guarantees, and tracked-subject reservation. Extend +`qa-perf` to assert no new per-frame loop bypasses the governor. Capture a +baseline on Node 24 and representative browsers, but treat browser GPU results +as environment evidence rather than a universal threshold. + +## Definition of done + +The infrastructure combination can be enabled without freezing the scene, every +degradation is visible and reversible, tracked subjects remain present, and the +diagnostics view explains which budget decision is active. Existing allocation +tests remain green and no layer is allowed to silently turn a source into an +empty green state. diff --git a/IMPROVEMENTS/05-source-pack-sdk.md b/IMPROVEMENTS/05-source-pack-sdk.md new file mode 100644 index 0000000..a201cae --- /dev/null +++ b/IMPROVEMENTS/05-source-pack-sdk.md @@ -0,0 +1,59 @@ +# Data Source Pack SDK and Capability Registry + +## Feature + +Create a documented, validated SDK for adding third-party data source packs and +city packs without editing the central `main.js`, giant UI surfaces, or the +server proxy by hand. A pack could add public cameras, a regional transit feed, +weather stations, ports, or a licensed local dataset. + +## Why it is valuable + +The project already has a clear layer interface and explicitly encourages new +layers and CCTV packs. Today, contributors still need to understand many +implicit registries, attribution paths, voice enums, UI controls, and proxy +security rules. A pack manifest can make the extension seam discoverable while +preserving reviewable source, licensing, and safety boundaries. + +## Implementation + +Define `src/plugins/packSchema.js` and a manifest format with `id`, `version`, +`displayName`, `description`, `provider`, `license`, `attributionUrl`, +`capabilities`, `layerFactory`, `configurationSchema`, `refreshPolicy`, and +`privacyClass`. Capabilities should be explicit: `map-entities`, `routes`, +`imagery`, `video`, `audio`, or `annotations`. Require a stable entity schema, +source health states, and a declared maximum resource cost. + +Add a build-time registry loader that imports local packs from a configured +directory and rejects duplicate IDs, unsupported schema versions, missing +attribution, undeclared network destinations, and layers that do not implement +the lifecycle contract. Keep remote code loading out of the default product; +installation should mean adding reviewed local code, not executing arbitrary +URLs in the browser. + +Expose pack layers through the existing manager and layer-state registry. Render +their controls using a small data-driven section component, but allow a pack to +provide richer UI only through constrained extension points. Route all private +keys through explicitly registered server adapters with host allowlists, +response-size caps, timeout limits, and per-provider rate controls. A manifest +must be able to say “client-visible key” versus “server-only key.” + +Provide a `createSourcePack` test harness with fake clock, fake fetch, fake +Cesium collection, and failure injection. Add a generator command that produces +a pack skeleton, data-source attribution template, unit-test fixtures, and a +`DATA_SOURCES.md` fragment. + +## Testing and rollout + +First migrate one existing bundled layer and one CCTV source pack to the +registry without changing behavior. Test malformed manifests, lifecycle +rollback, disabled packs, license rendering, capability enforcement, and +server-host allowlists. The app should show a rejected pack as a precise setup +error, never as a successful empty layer. + +## Definition of done + +A contributor can generate, implement, test, and locally install a public-data +pack using documented interfaces. The pack appears with attribution and health +state, can be disabled cleanly, and cannot expand the app's network or secret +access beyond what its reviewed manifest declares. diff --git a/IMPROVEMENTS/06-offline-snapshot-export.md b/IMPROVEMENTS/06-offline-snapshot-export.md new file mode 100644 index 0000000..832e2be --- /dev/null +++ b/IMPROVEMENTS/06-offline-snapshot-export.md @@ -0,0 +1,60 @@ +# Offline Snapshot, Session Export, and Portable Briefings + +## Feature + +Add a “capture session” workflow that packages a bounded scene snapshot into a +portable archive for offline viewing, citation, and bug reports. The archive +should include normalized observations, camera/style/layer state, attribution, +health statuses, user annotations, and optional thumbnails—not provider secrets +or unlicensed raw media. + +## Why it is valuable + +The app is local-first, but a live scene is difficult to share reproducibly. +Share links describe state while most data remains ephemeral. A snapshot lets a +teacher send a lesson, a journalist preserve the context of a public event, a +contributor attach a failing scene to an issue, and a user reopen a favorite +view during an outage. It also creates a safer boundary than asking another +machine to hit the same third-party APIs. + +## Implementation + +Create `src/export/sessionArchive.js` with a versioned manifest and ZIP writer +(or a streamed JSON + asset directory for the first release). Include a +`scene.json`, `observations.ndjson`, `annotations.json`, `sources.json`, and +optional `thumbnails/`. Record camera destination/orientation, map stack, +visual style, scope settings, selected entity, detection settings, UTC capture +range, and exact app revision. Each observation retains provenance and license +metadata. + +Add two modes: `DIAGNOSTIC` captures more state but redacts notes by default; +`PRESENTATION` captures only the visible and selected data. Let users choose a +time range and whether to include CCTV thumbnails, since those may have +provider-specific reuse constraints. Never capture `.env`, Pinokio environment +files, ephemeral OpenAI tokens, private URLs, or full server logs. + +Implement an import route that validates archive size, manifest schema, source +licenses, entity count, and coordinate bounds before writing to IndexedDB. Load +archives in an isolated replay namespace. A broken or partially imported +archive must be discarded atomically. Show archive age and “offline snapshot” +in the HUD so an imported world cannot be mistaken for live state. + +Add a one-click “copy issue bundle” action that creates a redacted diagnostic +archive and prints a manifest summary suitable for a GitHub issue. Provide +GeoJSON/CSV exports for selected entities and Markdown briefing export for the +correlation board. + +## Testing and rollout + +Test round-trip fidelity, schema migration, zip bombs and oversized input, +Unicode names, antimeridian coordinates, missing thumbnails, license refusal, +redaction, and offline startup. Add fixtures for each current layer's canonical +record. Verify imports do not activate network polling or restore a private +provider key. + +## Definition of done + +A user can capture a bounded scene, open it on a machine without network access, +see the same camera and observations with honest offline labels, and export +selected public records without leaking credentials or silently redistributing +provider-prohibited media. diff --git a/IMPROVEMENTS/07-alert-rules.md b/IMPROVEMENTS/07-alert-rules.md new file mode 100644 index 0000000..54934e0 --- /dev/null +++ b/IMPROVEMENTS/07-alert-rules.md @@ -0,0 +1,51 @@ +# Local Alert Rules and Change Detection + +## Feature + +Add local, user-defined alerts over public entities and layer health: a vessel +enters a radius, a tracked aircraft changes altitude regime, a fire appears in a +saved area, a camera goes stale, or a provider switches to fallback. Alerts +should be event-oriented and bounded, not person-oriented surveillance. + +## Why it is valuable + +Live data is useful even when the user is not staring at the globe. Alerts make +the project a monitoring instrument while preserving its public-data boundary. +They also expose the value of honest source states: “no aircraft observed” and +“aircraft feed unavailable” must not trigger the same rule. + +## Implementation + +Create `src/alerts/` with a declarative rule schema: `id`, `name`, `enabled`, +`entityTypes`, `area`, `predicate`, `debounce`, `cooldown`, `severity`, and +`delivery`. Predicates should include enter/exit, property threshold, change, +appearance/disappearance, source health, and freshness. Require a bounded area, +bounded entity type, and maximum evaluation rate. Explicitly reject person +identifiers, face or biometric fields, and unconstrained global high-frequency +rules. + +Evaluate rules against normalized ledger updates, not rendered primitives. Keep +per-rule state in IndexedDB so reloads do not create duplicate “entered” alerts. +Use a transition table with `UNKNOWN` as a first-class state: an unavailable +source suspends an alert and produces a health notice instead of an exit event. +Expose event evidence with the source observation IDs and the before/after +values that caused the match. + +Add an Alerts drawer with rule creation from the current viewport or selected +entity, a test-preview button, mute/cooldown controls, and an event history. +Use browser notifications only after permission; default to in-app toasts and +an accessible alert region. Optional webhooks should be an explicit advanced +feature with URL validation, timeout, redaction, and a local-only default. + +## Testing and rollout + +Test enter/exit hysteresis, antimeridian areas, stale-source suspension, +duplicate updates, clock skew, reload persistence, cooldowns, notification +permission denial, and malicious webhook URLs. Include a privacy review and +test that no alert payload contains provider secrets or hidden raw records. + +## Definition of done + +Users can create a bounded public-data alert, receive one honest event with +auditable evidence, survive a reload without duplicates, and understand whether +silence means “nothing matched” or “the source could not answer.” diff --git a/IMPROVEMENTS/08-cctv-coverage-calibration.md b/IMPROVEMENTS/08-cctv-coverage-calibration.md new file mode 100644 index 0000000..93ed5e3 --- /dev/null +++ b/IMPROVEMENTS/08-cctv-coverage-calibration.md @@ -0,0 +1,50 @@ +# Multi-Camera Coverage and Calibration Workspace + +## Feature + +Turn the existing CCTV frames, camera poses, calibration gizmo, and viewsheds +into a coverage workspace that compares cameras, tracks calibration confidence, +and shows blind spots without implying that an estimated frustum is verified +surveillance coverage. + +## Why it is valuable + +The project already projects public camera imagery into 3D and exposes estimated +viewsheds. The next useful step is to make the uncertainty and relationships +first-class: compare feeds covering the same intersection, see when a pose was +last calibrated, and understand whether a gap is a camera blind spot, terrain +occlusion, or simply missing imagery. + +## Implementation + +Extend the CCTV source schema with calibration version, pose source, horizontal +and vertical field-of-view ranges, heading confidence, elevation datum, +calibration sample points, and frame freshness. Store operator calibration in a +versioned local record, never overwrite the source catalog. Compute coverage as +an estimated volume with a confidence band and terrain-occlusion status. + +Create `src/data/cctvCoverage.js` for spatial indexing, overlap calculations, +and a bounded coverage query. Add a “coverage” panel listing cameras in the +current area, freshness, provider, calibration confidence, overlap count, and +blind-spot reasons. Selecting two cameras can show synchronized thumbnails or +the latest available frame side by side; if one frame is unavailable, retain +the pose view but label the image state clearly. + +Add a calibration workflow with reference landmarks, heading/pitch/FOV sliders, +before/after projection, reset, and an exportable calibration record. The +workflow should preserve the existing map-stack and ground-height boundaries, +and it must not claim metric accuracy from a manually aligned image alone. + +## Testing and rollout + +Test source normalization, missing fields, stale frames, FOV extremes, terrain +occlusion, antimeridian queries, calibration migration, and concurrent frame +updates. Add screenshot QA for the existing Austin, Caltrans, and TfL packs. +Require every label and export to say `ESTIMATED` unless the source explicitly +provides a verified pose. + +## Definition of done + +A user can compare nearby public cameras, inspect the provenance and age of each +pose/frame, calibrate locally with reversible changes, and distinguish estimated +coverage from a real observed image. diff --git a/IMPROVEMENTS/09-mission-authoring.md b/IMPROVEMENTS/09-mission-authoring.md new file mode 100644 index 0000000..8ec9c61 --- /dev/null +++ b/IMPROVEMENTS/09-mission-authoring.md @@ -0,0 +1,54 @@ +# Mission Authoring and Reproducible Scene Director + +## Feature + +Expand the current scene director into a mission authoring system: a sequence +of named steps that can enable layers, fly to locations, select public entities, +change visual styles, pause for narration, and capture a deterministic replay or +presentation. + +## Why it is valuable + +The first-run launcher already frames the app as missions, and the project has +camera tours, share links, voice actions, safe frames, and recording QA. A +structured mission format would connect those systems into reusable lessons, +demos, regression cases, and community-authored stories without hard-coding a +new script for every sequence. + +## Implementation + +Define a versioned mission JSON schema with metadata, requirements, initial +state, steps, assertions, and cleanup policy. Steps include `setLayers`, +`flyTo`, `selectEntity`, `enterCockpit`, `setStyle`, `waitForHealth`, `narrate`, +`captureMarker`, and `end`. Assertions should check observable facts such as +layer health or selection identity, not pixel-perfect provider content. + +Implement `src/scenes/missionRunner.js` as a cancellable state machine with an +operation epoch. It must use existing manager/context transactions, camera +verbs, and voice action functions rather than duplicating them. A failed step +pauses with a clear reason; it must not advance as though a network-backed +layer loaded. Cleanup restores the exact pre-mission layer and camera snapshot +unless the user chooses “keep final scene.” + +Add an authoring drawer with a step list, record-current-view button, timing +controls, requirement editor, preview, save/export, and accessibility-friendly +text alternatives. Imported missions run in a sandboxed capability set: no +arbitrary JavaScript, no arbitrary fetch URL, no secret access, and no automatic +external webhook. Voice can start named local missions but cannot invent +unreviewed tool actions from mission text. + +Support deterministic synthetic data and ledger snapshots as mission fixtures. +That makes a mission useful even when OpenSky, CCTV, or Overpass is down. + +## Testing and rollout + +Test cancellation at every await boundary, rollback after partial layer enable, +camera supersession, missing requirements, replay fixture determinism, and +import validation. Add a small built-in “show the globe / select a contact / +return home” mission and migrate one existing QA flow to prove the format. + +## Definition of done + +A user can author, save, share, and replay a mission with explicit requirements, +truthful pauses, reversible cleanup, and no executable content. The same mission +can serve as a demo, a lesson, or a regression fixture. diff --git a/IMPROVEMENTS/10-provider-health-cost-center.md b/IMPROVEMENTS/10-provider-health-cost-center.md new file mode 100644 index 0000000..fb7ebba --- /dev/null +++ b/IMPROVEMENTS/10-provider-health-cost-center.md @@ -0,0 +1,54 @@ +# Provider Health, Quota, and Cost Center + +## Feature + +Add a local diagnostics center that unifies provider health, cache age, fallback +reason, request counts, approximate model/tiles usage, and configured app-level +rate limits. It should explain capability loss and help users avoid accidental +quota spend without pretending to be a billing system. + +## Why it is valuable + +The project already has many careful proxy safeguards, source-specific statuses, +OpenSky cache headers, TomTom budgets, optional OpenAI rate limits, and Provider +Settings. Those signals are distributed across chips, logs, and environment +variables. A single health center would make setup and troubleshooting much less +opaque, especially for self-hosters sharing a local instance. + +## Implementation + +Define a server `/api/health/providers` endpoint that returns sanitized, +non-secret telemetry: configured/not configured, last attempt, last success, +cache status, stale age, retry-after, request counts, limiter state, and safe +error categories. Never return keys, upstream URLs containing credentials, raw +provider response bodies, or unrestricted log paths. Add process-local counters +with bounded retention and reset-on-restart semantics explicitly shown in the +UI. + +Create a client `ProviderHealthStore` that polls slowly, merges layer +`getStats()` data, and distinguishes source health from capability configuration. +Add a panel with sections for maps, live data, media, voice, and optional keys. +Each row should link to the responsible layer or setup instruction. Include +“pause expensive sources,” “clear cache,” and “copy sanitized diagnostics,” with +confirmation for actions that change behavior. + +For OpenAI and paid tile routes, show an estimate based on locally counted +requests and configured model pricing metadata, clearly labeled approximate and +not a provider invoice. Keep pricing in a versioned registry so drift is visible. +Expose the existing daily TomTom budget and per-minute app throttles without +calling them hard billing caps. + +## Testing and rollout + +Unit-test redaction, counter rollover, stale transitions, provider failure +classification, and privacy of copied diagnostics. Add middleware contract tests +for every endpoint. Test with all keys absent, one key invalid, a stale cache, +and a shared-host configuration. Verify the panel itself never fetches a +provider directly. + +## Definition of done + +From one panel, a user can tell what is configured, what last succeeded, what is +cached or degraded, and what the app estimates it has spent. The information is +useful without exposing secrets and clearly distinguishes application telemetry +from provider billing truth. diff --git a/IMPROVEMENTS/11-accessibility-and-input-modes.md b/IMPROVEMENTS/11-accessibility-and-input-modes.md new file mode 100644 index 0000000..05ab671 --- /dev/null +++ b/IMPROVEMENTS/11-accessibility-and-input-modes.md @@ -0,0 +1,55 @@ +# Accessible Command Surface and Alternate Input Modes + +## Feature + +Make the globe operable with a complete keyboard, screen-reader, reduced-motion, +high-contrast, touch, and gamepad input layer. The 3D scene remains visual, but +its meaningful state—selected entity, layer health, camera location, time, and +available actions—must be available as a navigable semantic surface. + +## Why it is valuable + +The application has a dense cockpit UI, many custom panels, voice controls, +keyboard shortcuts, draggable positions, and multiple exclusive surfaces. A +consistent input model makes it usable for people who cannot use a mouse or +microphone and makes automated QA more reliable. It also reduces the risk that +important truth states exist only as color, animation, or a tiny Cesium pick. + +## Implementation + +Create `src/input/inputController.js` with an input-independent command model: +focus next layer, toggle layer, move camera north/south/east/west, zoom, +select next visible entity, open provenance, enter/exit cockpit, change style, +pause replay, and announce status. Map keyboard, pointer, touch, gamepad, and +voice actions to the same commands. Preserve existing shortcuts through a +versioned keymap and provide conflict warnings. + +Add a semantic “scene list” panel that contains the selected entity, visible +layers, health states, nearby contacts, and current camera locality. Cesium +canvas gets a clear accessible label and live announcements only for meaningful +changes, with a user-controlled verbosity level. Do not stream every telemetry +tick into an aria-live region. Add visible focus rings, roving tabindex in +toolbars, proper dialog focus traps, and escape arbitration consistent with the +existing first-run surface rules. + +Respect `prefers-reduced-motion` by disabling decorative shader transitions, +camera easing where appropriate, animated split-flap effects, and auto-rotating +briefings. Add a high-contrast theme that preserves source-state distinctions +with text and icons, not color alone. Touch controls need large hit targets, +pinch/rotate gestures, and an explicit “pick mode” so a drag never accidentally +selects an entity. + +## Testing and rollout + +Add unit tests for command routing and shortcut precedence. Use Puppeteer checks +for focus order, dialog return focus, accessible names, reduced motion, and +keyboard-only completion of common missions. Run axe-style audits where tooling +permits and manually test VoiceOver/NVDA because canvas semantics need human +verification. Add a non-visual state snapshot for every major scene surface. + +## Definition of done + +A keyboard-only user can launch a mission, enable a layer, select a contact, +read its source state, change the camera, and exit. Screen-reader users receive +the same meaningful state without telemetry spam, and reduced-motion/high- +contrast modes preserve both function and truth labels. diff --git a/IMPROVEMENTS/12-network-optional-edge-cache.md b/IMPROVEMENTS/12-network-optional-edge-cache.md new file mode 100644 index 0000000..abc2b3f --- /dev/null +++ b/IMPROVEMENTS/12-network-optional-edge-cache.md @@ -0,0 +1,52 @@ +# Optional Local Edge Cache and Resilient Sync Queue + +## Feature + +Add an opt-in cache service for self-hosters that stores normalized public data +and proxy responses with explicit freshness, bounded disk use, and source-aware +retention. The browser should remain fully functional without it; the cache is a +resilience and multi-tab optimization, not a silent server requirement. + +## Why it is valuable + +The current Vite middleware already uses carefully bounded caches, stale-last- +good behavior, request coalescing, mirror rotation, and source-specific retry +logic. A small cache service would extend those strengths across browser reloads, +multiple tabs, and short upstream outages. It could also support the observation +ledger and time-machine features without forcing every layer to reinvent disk +storage. + +## Implementation + +Create an optional `scripts/cache-server.mjs` or Vite plugin backed by SQLite or +a similarly small local store. Records need source ID, normalized request key, +payload hash, acquired time, source time, expiry, stale-until, byte size, and +license class. Store normalized payloads by default; retain raw responses only +for sources whose terms permit it and only when diagnostics are enabled. + +Expose `/api/cache/status`, `/api/cache/export`, and source-scoped invalidation. +Keep the current in-process behavior as the default and make the edge cache +explicit in setup. The client should receive cache headers and use the same +truthful `FRESH`, `STALE`, `DEGRADED`, and `UNAVAILABLE` vocabulary. A stale +response can preserve continuity, but it must never be presented as current. + +Use request coalescing across tabs with a small lease/lock record, bounded +concurrency, response-size caps, and per-source policies. For WebSocket AIS, +store a compact last-seen snapshot and track history only when the user opts in; +do not pretend a snapshot is a continuous track. Add a sync queue for ledger +records and exports, not for mutating third-party providers. + +## Security and testing + +Bind to localhost by default, require an explicit shared-host setting, and reuse +the existing SSRF, allowlist, rate-limit, and redaction rules. Test disk full, +corrupt records, lock expiry, process restart, cache poisoning via keys, source +license retention, and two simultaneous browser tabs. Verify invalid upstream +payloads are never admitted merely because an old cache entry exists. + +## Definition of done + +With the optional cache enabled, a reload and a second local tab reuse bounded, +source-labeled data; short outages preserve last-good context; invalid or +over-age data stays visibly stale; cache status and deletion are inspectable; +and the app's safe localhost default remains unchanged when the feature is off. diff --git a/IMPROVEMENTS/13-global-open-camera-atlas.md b/IMPROVEMENTS/13-global-open-camera-atlas.md new file mode 100644 index 0000000..109098c --- /dev/null +++ b/IMPROVEMENTS/13-global-open-camera-atlas.md @@ -0,0 +1,73 @@ +# Global Open Camera Atlas + +## Feature + +Build a world-wide catalog of openly published public camera feeds: municipal +traffic cameras, webcams from parks and universities, harbor views, ski-area +cameras, weather cameras, wildlife observation cameras, public transit cameras, +and other feeds intentionally made available by their operators. + +This is not an arbitrary URL viewer. Every camera must come from a reviewed +source catalog with a public landing page, identifiable operator, usage terms, +geographic location, feed type, and an attribution requirement. + +## Why it is valuable + +The current CCTV experience is compelling but geographically concentrated. A +global atlas would make the globe feel alive in every region and let users move +from a satellite-scale view into ordinary public scenes: a harbor in Rotterdam, +a mountain pass in Chile, a traffic interchange in Tokyo, or a weather camera +on a Pacific island. + +It also turns the existing source-pack architecture into a community-sized +feature. Contributors could add a city or region without modifying the core +camera renderer. + +## Implementation + +Create a versioned camera catalog schema under `config/camera-packs/`. Each pack +should contain: + +- Camera ID, operator, country, city/region, latitude, longitude, elevation, + heading, approximate field of view, and optional orientation metadata. +- Feed type: JPEG snapshot, MJPEG, HLS, DASH, embedded public player, or a + metadata-only camera with no direct frame endpoint. +- Public source page, terms/license URL, attribution text, update cadence, + contact/reporting URL, and last catalog review date. +- Whether frames may be proxied, cached, displayed in thumbnails, projected + into 3D, or exported. These are separate permissions. +- A privacy classification: scenic, traffic, weather, wildlife, transit, or + mixed public-space view. + +Add `src/data/openCameraAtlas.js` as a layer built on the current CCTV card, +projection, viewshed, ground-floor, and calibration systems. It should load a +small spatial index first, then fetch metadata and frames only for cameras near +the active viewport or selected region. At global scale, render clustered camera +nodes and counts rather than thousands of billboards. + +Add a source selector with region, camera type, freshness, and “currently +available” filters. The camera card must show operator, source page, frame age, +catalog review date, and whether the projection is estimated. A missing or +blocked frame should leave the catalog point visible with `FRAME UNAVAILABLE`, +not remove the camera or show a stale image as live. + +For direct feeds, use server-side adapters with strict host allowlists generated +from the reviewed catalog. Reject client-supplied proxy URLs, redirects to +unapproved hosts, private IP ranges, oversized responses, and unsupported +content types. Keep credentials out of the browser; if a source requires an +account or private token, it does not belong in the open atlas. + +## Testing and rollout + +Start with three source packs covering different protocols and continents. +Contract-test catalog validation, attribution rendering, frame age, redirects, +content-type checks, disabled sources, and operator takedown. Add a catalog +review script that flags expired terms, dead URLs, missing landing pages, and +coordinates outside valid bounds. + +## Definition of done + +Users can browse public cameras across multiple continents from the globe, +open the operator's source page, see honest freshness and projection status, +and understand why a feed is unavailable. No camera is accepted solely because +someone pasted a URL into a text box. diff --git a/IMPROVEMENTS/14-camera-handoff-and-world-mosaic.md b/IMPROVEMENTS/14-camera-handoff-and-world-mosaic.md new file mode 100644 index 0000000..d579e29 --- /dev/null +++ b/IMPROVEMENTS/14-camera-handoff-and-world-mosaic.md @@ -0,0 +1,54 @@ +# Camera Handoff Trails and World Mosaic View + +## Feature + +Add a “camera handoff” experience that moves through nearby public cameras as a +user travels across a city or coastline. A mosaic mode can show several nearby +feeds at once, ordered by direction, distance, freshness, and scene similarity. + +## Why it is valuable + +One camera is an interesting endpoint; a network of public cameras becomes a +way to understand a place. Users could follow a road toward a harbor, compare +weather across a mountain range, or inspect a transit corridor without treating +any individual feed as a complete view of reality. This makes the map-camera +relationship more spatial and less like a list of unrelated thumbnails. + +## Implementation + +Create `src/data/cameraHandoff.js` with a camera graph. Nodes are catalog camera +IDs. Edges are created only from geographic distance, compatible orientation, +operator-provided coverage, or an explicit source-pack relationship. Each edge +stores the reason it exists; never imply that two cameras are continuous views +unless the catalog says so. + +Add `NEXT CAMERA`, `PREVIOUS CAMERA`, and `MOSAIC` controls to the CCTV panel. +The next-camera ranking should be deterministic: selected route direction, +heading alignment, distance, frame freshness, calibration quality, then stable +camera ID. A handoff animates the globe to the next camera, preserves the +current map style, and transfers selection only after the target metadata has +loaded. A failed target leaves the current camera selected and reports the +reason. + +Mosaic mode should be a bounded grid, initially four or six tiles. Each tile +shows a frame, source, age, and camera ID. Tiles must have independent loading +and failure states. The map highlights all tile locations, while selecting a +tile can promote it to the main projection. Do not automatically fetch every +camera in a region; use an explicit tile budget and pause off-screen tiles. + +For a scenic or weather route, add a “follow daylight” option that ranks cameras +by local solar elevation and freshness. This can create a visually delightful +world tour without pretending the feeds are a continuous video stream. + +## Testing and rollout + +Test ranking ties, antimeridian distance, unavailable frames, camera removal, +rapid next/previous clicks, cancellation during camera flight, and stale mosaic +tiles. Add performance tests proving off-screen tiles stop fetching and that +camera handoff does not interfere with aircraft tracking or Context isolation. + +## Definition of done + +A user can move through a lawful public camera network or compare a small set of +nearby feeds, with every transition attributable and cancellable. Missing feeds +do not break the mosaic or silently substitute another camera. diff --git a/IMPROVEMENTS/15-public-camera-rights-and-privacy-gate.md b/IMPROVEMENTS/15-public-camera-rights-and-privacy-gate.md new file mode 100644 index 0000000..649add4 --- /dev/null +++ b/IMPROVEMENTS/15-public-camera-rights-and-privacy-gate.md @@ -0,0 +1,55 @@ +# Public Camera Rights, Privacy, and Takedown Gate + +## Feature + +Add a formal review and runtime rights gate for public camera sources. The gate +would make the camera layer useful at global scale while preventing the project +from becoming an indiscriminate index of streams that were not intended for +redistribution or projection. + +## Why it is valuable + +“Publicly reachable” is not the same as “licensed for reuse.” Cameras may show +private homes, identifiable people, restricted facilities, or feeds whose terms +allow viewing but not caching, embedding, or transformation. The project already +has strong source attribution and security rules; this feature turns those +principles into an operational workflow for a much larger camera catalog. + +## Implementation + +Create a source-review manifest with required fields: operator identity, source +landing page, terms URL, permission basis, permitted display modes, caching +policy, retention policy, geographic precision, privacy review, review owner, +review date, expiry date, and takedown contact. A camera cannot enter the +production catalog without a passing manifest. + +Define display permissions separately: `link-only`, `thumbnail`, `live-frame`, +`3d-projection`, `cache`, and `export`. The runtime adapter must enforce the +most restrictive permission. For example, a feed may be displayed as a link but +not proxied or included in an offline archive. + +Add a visible `REPORT SOURCE` action that records the catalog ID, source page, +and reason without exposing private user information. Maintain a signed or +versioned denylist/takedown file that disables a source immediately at startup. +The disable state should say `WITHHELD BY SOURCE REVIEW`, not “offline.” + +Never add face recognition, license-plate recognition, person search, or +behavioral tracking. Add configurable privacy masks only when the source +operator permits transformed display; masks should be conservative and should +not be presented as a guarantee of anonymity. The default should avoid storing +frames and should not write raw video into diagnostics or the observation ledger. + +## Testing and rollout + +Build a linter that rejects missing terms, expired reviews, ambiguous operators, +unbounded redirects, and unsupported permissions. Test that link-only feeds +never enter frame fetch code, withheld cameras disappear from active rendering, +and exported snapshots honor the source permission. Include a tabletop takedown +exercise and document the response SLA for maintainers. + +## Definition of done + +Every camera visible in the app has a reviewable source record and explicit +display permissions. Users can report a source, maintainers can withdraw it +without a code release, and the system never treats technical accessibility as +permission to republish. diff --git a/IMPROVEMENTS/16-public-camera-weather-nowcast.md b/IMPROVEMENTS/16-public-camera-weather-nowcast.md new file mode 100644 index 0000000..02b72bb --- /dev/null +++ b/IMPROVEMENTS/16-public-camera-weather-nowcast.md @@ -0,0 +1,53 @@ +# Camera Weather and Visibility Nowcast + +## Feature + +Use openly published weather and scenic cameras as a visual conditions layer. +The feature would estimate broad scene conditions—clear, cloudy, foggy, snowy, +night, glare, rain-obscured, or stale—from camera metadata and optional public +weather observations, then show that state on the globe and in camera cards. + +## Why it is valuable + +It is a creative use of public cameras that does not require inspecting people: +users can see where it is daylight, where visibility is poor, where snow is +falling, or which coastal views are currently stormy. It complements the +existing weather effects and cockpit briefing while remaining explicitly +non-operational and approximate. + +## Implementation + +Create `src/data/cameraConditions.js` with a conservative condition vocabulary +and evidence model. Evidence can include camera-provided weather tags, nearby +public weather station readings, image timestamp, solar position, and optionally +an on-device lightweight image classifier restricted to scene-level categories. +Do not infer identity, demographics, activity, or individual behavior. + +Every condition must include `observedAt`, `sourceIds`, `confidenceBand`, and +`method`. A stale frame may still show `LAST OBSERVED: SNOW`, but it must not +contribute to a “current” world condition map. Conflicting evidence should +produce `MIXED` rather than selecting a confident-looking answer. + +Add a weather/visibility filter to the camera atlas and a global “conditions +ring” that clusters counts by broad category. Selecting a category flies to a +representative camera only after showing that it is a sampled example, not a +guarantee for the whole region. In Cockpit, a camera-derived condition can be +shown as contextual public imagery beside actual weather observations, never as +flight guidance. + +For privacy and cost, prefer provider metadata and local feature extraction. +If a server-side classifier is ever offered, frames must be opt-in, transient, +redacted from logs, and processed only for the allowed category set. + +## Testing and rollout + +Test solar day/night boundaries, stale images, conflicting station readings, +missing EXIF, camera timezone conversion, low-confidence classification, and +category leakage. Use synthetic frames and metadata fixtures rather than +shipping real people's images in tests. + +## Definition of done + +Users can browse broad, source-backed public scene conditions around the world +and see exactly when and how each condition was determined. The feature never +claims operational weather certainty and never analyzes people. diff --git a/IMPROVEMENTS/17-community-camera-pack-workbench.md b/IMPROVEMENTS/17-community-camera-pack-workbench.md new file mode 100644 index 0000000..baa52e5 --- /dev/null +++ b/IMPROVEMENTS/17-community-camera-pack-workbench.md @@ -0,0 +1,51 @@ +# Community Camera Pack Workbench + +## Feature + +Add a local workbench for contributors to assemble, validate, preview, and +submit regional public-camera packs before they become part of the shared +catalog. + +## Why it is valuable + +A global atlas will only stay healthy if adding cameras is easy and removing +broken or unauthorized cameras is equally easy. A workbench turns the existing +configuration files and QA scripts into an approachable contribution path for +municipal open-data users, geography enthusiasts, and maintainers. + +## Implementation + +Create `scripts/camera-pack-doctor.mjs` and an optional in-app development panel. +The doctor should validate schema, coordinate bounds, duplicate IDs, source +landing pages, terms metadata, feed type, content type, redirect policy, +attribution, FOV ranges, and privacy classification. It should generate a +human-readable report with `PASS`, `WARN`, and `BLOCKED` outcomes. + +The workbench preview should render camera points, estimated viewsheds, cards, +freshness, and attribution without requiring the pack to be merged. It should +support a mocked frame server and a “feed unavailable” mode so contributors can +verify all UI states. Calibration edits should export a minimal patch against +the pack rather than modifying generated catalogs. + +Add a pack README template containing operator, license, source URLs, permission +decisions, review date, known limitations, and removal contact. Generate unit +fixtures and a catalog fragment from the validated manifest. A CI job should +run the doctor, reject new unreviewed direct URLs, and check that every pack +has at least one attribution and rights test. + +Provide a maintainer command to mark a source withdrawn while preserving its +history and reason. The workbench should make it possible to test a replacement +feed without resurrecting the old source ID. + +## Testing and rollout + +Use malformed-pack fixtures, hostile URLs, redirect chains, stale terms, invalid +coordinates, duplicate IDs, and mixed protocols. Add a smoke pack containing +one valid camera, one link-only camera, one stale camera, and one blocked camera. +Require the doctor to produce stable output for review diffs. + +## Definition of done + +A contributor can create a regional pack, run one command to find errors, preview +it locally, see all attribution and failure states, and produce a reviewable +change without editing unrelated core runtime files. diff --git a/IMPROVEMENTS/18-camera-motion-events.md b/IMPROVEMENTS/18-camera-motion-events.md new file mode 100644 index 0000000..56d5e96 --- /dev/null +++ b/IMPROVEMENTS/18-camera-motion-events.md @@ -0,0 +1,54 @@ +# Privacy-Preserving Camera Motion Events + +## Feature + +Add an optional scene-level motion-events layer that reports broad public-camera +changes such as `ROADWAY BUSY`, `WATER LEVEL CHANGED`, `SNOW ACCUMULATION`, +`VISIBILITY REDUCED`, or `FRAME STATIC`. It should compare frames or provider +metadata without identifying, counting, or following people. + +## Why it is valuable + +Users often need to know whether a public camera is changing before opening a +feed. Scene-level events could help find active storms, traffic disruptions, +harbor conditions, or dead feeds across a global atlas. This adds utility while +remaining much safer than object-level surveillance. + +## Implementation + +Create `src/data/cameraMotionEvents.js` with a fixed, reviewed taxonomy of +scene-level events. Compute simple features such as perceptual frame difference, +sky/ground color distribution, waterline movement, snow/visibility changes, and +camera freeze detection. Run processing locally where practical and retain only +the event type, score band, source frame timestamps, and short expiry—not raw +frames or crops. + +The event engine must include a privacy guard that rejects face, body, plate, +weapon, identity, and individual-track outputs. It should not expose generic +“objects detected” counts, because those are easily repurposed for people +tracking. Camera packs can opt out entirely or restrict which event classes are +allowed. + +Add event badges to camera clusters and a filter such as `SHOW ACTIVE WEATHER +CHANGES`. Cards should say `SCENE CHANGE ESTIMATE`, show the comparison times, +method, and confidence band, and link to the public source. Events should expire +quickly and never be presented as an incident or emergency determination. + +For operators with their own feeds, offer a local-only mode that never sends +frames to the project server. For catalog feeds, do not bypass a source's +caching or transformation permissions; a camera that permits link-only display +cannot participate in frame comparison. + +## Testing and rollout + +Test static feeds, camera exposure changes, time-of-day transitions, rain, +compression noise, reconnects, duplicate frames, and false positives. Add a +privacy review test that inspects serialized event payloads for forbidden fields. +Keep the taxonomy small until human QA shows that labels are understandable and +not overconfident. + +## Definition of done + +Users can discover broad, temporary changes in lawful public scenes without the +system producing person-level detections, identity claims, or retained video. +Every event is time-bounded, source-linked, and clearly labeled as an estimate. diff --git a/IMPROVEMENTS/19-public-osint-api-research.md b/IMPROVEMENTS/19-public-osint-api-research.md new file mode 100644 index 0000000..8b35a78 --- /dev/null +++ b/IMPROVEMENTS/19-public-osint-api-research.md @@ -0,0 +1,408 @@ +# Public OSINT Expansion: A Research-Backed World Observatory + +## Executive direction + +God's Eye View should evolve from a globe with many live layers into a public +world observatory: a system that lets someone ask what is happening at a place, +what changed, which independent sources agree, and how confident the answer is. +The strongest expansion is not simply adding more aircraft or more map points. +It is adding a shared observation model that fuses physical-world events, +Earth-observation imagery, environmental measurements, infrastructure status, +humanitarian reporting, and Internet reachability while keeping every claim +source-stamped and uncertainty-aware. + +This report was researched against public API documentation and data portals on +September 9, 2026. “Open” below means technically accessible or publicly +documented; it does not automatically mean unrestricted redistribution, +commercial use, unlimited rate, or suitability for a public hosted service. +Every integration would still need a source-specific license and quota review. + +## The most important architectural move + +Add a common `Observation` envelope before adding many more providers: + +```js +{ + observationId, + entityKey, + entityType, + geometry, + observedAt, + receivedAt, + source: { id, url, license, attribution }, + status: 'OBSERVED' | 'MODELED' | 'INFERRED' | 'STALE' | 'UNKNOWN', + confidence: { band, basis }, + values, + derivation: [] +} +``` + +The existing layer contract and `DataLayerManager` can remain intact. Each new +provider gets a source adapter and a normalizer; rendering, provenance, +timeline, correlation, alerts, exports, and voice context consume normalized +observations. This prevents every layer from inventing different meanings for +“live,” “current,” “nearby,” and “no data.” + +## Tier 1: highest-value integrations + +These are the best first additions because they have strong public +documentation, map naturally onto the existing application, and can be useful +without building a large proprietary backend. + +### 1. Global natural-event radar + +Combine the existing USGS earthquakes and NASA FIRMS fires with NASA EONET, +GDACS, USGS volcanoes, and selected national alert feeds. NASA EONET v3 +provides event objects and GeoJSON endpoints for natural events, with an +explicit disclaimer that event metadata may be incomplete. GDACS provides free +geospatial disaster data and event searches for earthquakes, tropical cyclones, +and floods, with source acknowledgement required. The USGS Volcano API exposes +monitored and elevated volcano states, including CAP-style alert information. +[ NASA EONET ](https://eonet.gsfc.nasa.gov/docs/v3), +[ GDACS API quick start ](https://gdacs.org/Documents/2025/GDACS_API_quickstart_v1.pdf), +[ USGS Volcano API ](https://volcanoes.usgs.gov/hans-public/api/volcano/default) + +Feature: an `EVENT RADAR` layer with event tracks, affected-area polygons, +alert severity, source agreement, and a time window. Clicking an event opens a +source card rather than claiming that a colored alert is ground truth. EONET +and GDACS should remain separate evidence streams even when they describe the +same event. + +Implementation: `src/data/worldEvents.js`, `/api/eonet`, `/api/gdacs`, and +`/api/usgs-volcanoes`. Use a deduplication key based on event type, location, +time, and source—not title similarity alone. Add a conflict state when sources +disagree on severity or closure. This immediately enables features such as +“show all active natural hazards within 100 km of the camera” and “replay the +first 48 hours of an event.” + +### 2. Earth-observation change lens + +Integrate NASA GIBS and Copernicus Data Space imagery as time-aware raster +layers. GIBS exposes public WMTS, WMS, TMS, and related services with a time +dimension and near-real-time visualization products. Copernicus Data Space +provides STAC, openEO, Sentinel Hub, catalog, visualization, and processing +APIs; Copernicus describes Sentinel data as free and open, but individual +services, credentials, quotas, and downstream terms still need checking. +[ NASA GIBS access basics ](https://nasa-gibs.github.io/gibs-api-docs/access-basics/), +[ Copernicus Data Space APIs ](https://dataspace.copernicus.eu/), +[ Sentinel Hub API reference ](https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/ApiReference.html) + +Feature: `BEFORE / AFTER` satellite mode. A user selects an area and date +window; the app finds low-cloud imagery, renders a swipe comparison, and +computes only conservative scene-level products such as burn scar, flood-water +extent, vegetation change, snow cover, turbidity, or construction footprint +change. It must display acquisition dates, sensor, resolution, cloud cover, +processing method, and a “not independently verified” label. + +Implementation: use GIBS first for low-friction visual overlays. Add a server +proxy for Copernicus catalog search and bounded image/statistical requests; +never let a browser submit arbitrary processing expressions or unbounded AOIs. +Cache tiles by source, date, layer, and projection. Add a small raster-analysis +worker that operates on requested tiles, not the entire globe. Put derived +change detections into the observation ledger with `derivation` explaining the +algorithm and input scenes. + +### 3. Weather, air, and atmospheric observatory + +The existing cockpit weather effects can become evidence-backed environmental +context. Open-Meteo offers forecast, historical, marine, air-quality, elevation, +and flood APIs without an API key for its non-commercial use case. OpenAQ v3 +provides global public air-quality measurements, including PM2.5, PM10, ozone, +NO2, CO, SO2, black carbon, humidity, and temperature. The US National Weather +Service API provides forecasts, alerts, observations, and other weather data +for the United States. +[ Open-Meteo documentation ](https://open-meteo.com/en/docs), +[ OpenAQ API overview ](https://docs.openaq.org/about/about), +[ NWS API ](https://www.weather.gov/documentation/services-web-api) + +Feature: `ATMOSPHERE` mode with wind vectors, temperature, precipitation, +cloud base, lightning/alert context where available, air-quality stations, and +vertical slices around the selected aircraft or camera. The app can show +“model forecast,” “station observation,” and “satellite-derived” as different +visual channels instead of blending them into one fake current condition. + +Implementation: use Open-Meteo for global keyless defaults, OpenAQ for station +observations, and NWS for US authoritative alert geometry. Add a model-versus- +observation comparison panel. This creates an unusually good educational +feature: “the model predicted this,” “the station measured this,” and “the +camera visually suggests this” can be compared without pretending any one +source is perfect. + +### 4. Ocean state and maritime environment + +Add Copernicus Marine Service data for currents, sea-surface height, waves, +temperature, salinity, sea ice, and biogeochemistry. The official service +documents a Toolbox API plus OGC endpoints, and its global products include +physics forecasts and reanalysis. The Toolbox supports metadata discovery and +spatial/time subsetting; account requirements and access mode should be handled +server-side rather than placing credentials in the client. +[ Copernicus Marine programmatic services ](https://help.marine.copernicus.eu/en/articles/4794731-which-programmatic-services-are-available), +[ Copernicus Marine Toolbox ](https://help.marine.copernicus.eu/en/articles/7949409-copernicus-marine-toolbox-introduction), +[ Global ocean products ](https://data.marine.copernicus.eu/) + +Feature: an animated ocean surface with current streamlines, wave direction, +sea-ice edge, SST anomaly, and a “maritime conditions” card beside AIS tracks. +Correlate vessel motion with current and weather as context, never as a claim +that a ship is behaving suspiciously. Use Global Fishing Watch separately for +fishing-effort and encounter analysis; its API is explicitly non-commercial and +requires a token. +[ Global Fishing Watch APIs ](https://globalfishingwatch.org/our-apis/documentation/) + +### 5. Flood, river, and water-system layer + +Use the modern USGS Water Data APIs for real-time sensors, daily values, +monitoring locations, water quality, basin navigation, and gage imagery. The +modern API is important because USGS says the legacy WaterServices family is +scheduled for decommissioning in early 2027. The USGS OGC APIs and NLDI also +support standardized geospatial queries and network navigation. +[ USGS Water API documentation ](https://api.waterdata.usgs.gov/docs/), +[ USGS Water API migration notice ](https://www.usgs.gov/tools/usgs-water-data-apis) + +Feature: click a river, dam, or city and see upstream/downstream gauges, +recent stage change, basin extent, flood observations, and nearby camera feeds. +For global coverage, add Copernicus flood products and GDACS flood events as +separate sources. A “water system view” would be one of the most distinctive +features in the entire product: it links terrain, infrastructure, rain, +reservoirs, rivers, and public imagery in a single explorable system. + +## Tier 2: the genuinely surprising layers + +### 6. Global Internet observatory + +Treat the Internet as another physical-ish world system. IODA exposes signals, +outage events, outage alerts, summaries, and entity metadata. RIPEstat exposes +routing status for prefixes and ASNs, RIPE Atlas provides active measurement +data, RIS Live provides real-time BGP JSON over WebSocket, and RouteViews +provides current routing and RPKI-related APIs. These are excellent for showing +Internet outages, routing instability, submarine-cable context, and regional +connectivity changes without probing private systems. +[ IODA API ](https://api.ioda.inetintel.cc.gatech.edu/v2/), +[ RIPE routing status ](https://stat.ripe.net/docs/data-api/api-endpoints/routing-status), +[ RIS Live ](https://ris-live.ripe.net/manual/), +[ RouteViews API ](https://api.routeviews.org/docs/) + +Feature: `CONNECTIVITY WEATHER`. The globe shows regional outage halos, +affected autonomous systems, BGP announcement changes, and measurement probes. +Selecting a city can answer “is this place reachable from the public Internet?” +without scanning endpoints. Add a time slider because BGP and outage data are +most interesting as change histories. + +Guardrails: only consume published aggregate signals. Do not add port scanning, +credential testing, exploit feeds, or tooling that targets individual hosts. +Show measurement vantage points and distinguish “not observed by this network” +from “offline.” + +### 7. Global news and event geography + +GDELT 2.0 provides event and knowledge-graph data derived from global news, +with multilingual coverage and frequent updates. The direct GDELT project +documents GEO, event, mention, and GKG data; GDELT Cloud offers a newer +structured Events/Stories/Entities REST surface but requires API access under +its current product model. ReliefWeb provides a read-only, curated humanitarian +archive with reports, disasters, countries, sources, and other endpoints. +[ GDELT project data documentation ](https://gdeltproject.org/data.html), +[ GDELT DOC 2.0 API ](https://blog.gdeltproject.org/gdelt-doc-2-0-api-debuts/), +[ ReliefWeb API ](https://apidoc.reliefweb.int/index.html) + +Feature: `WORLD BRIEFING MAP`. Cluster geographically anchored event reports, +show source diversity, publication age, language, and story volume. Clicking a +cluster opens source links and a short neutral summary. “Media attention” must +not be rendered as “event severity”; high coverage can reflect interest rather +than scale. + +Add source-diversity scoring: an event supported by multiple independent +publishers is different from five articles repeating one wire report. Keep the +underlying links visible and never make a model-generated summary the only +representation of evidence. + +### 8. Conflict and humanitarian context, carefully scoped + +ACLED offers an API for political violence, demonstrations, and strategic +development events, but access requires an account and authentication. It is +valuable as historical/contextual data, not as a tactical targeting feed. +ReliefWeb is the better low-friction starting point for humanitarian reports +and disasters. +[ ACLED API documentation ](https://acleddata.com/api-documentation), +[ ACLED access model ](https://acleddata.com/api-documentation/getting-started) + +Feature: a `CIVILIAN CONTEXT` layer that displays event locations, dates, +categories, displacement/humanitarian reports, and uncertainty bands. Keep it +historical and aggregate by default. Disable exact-person records, tactical +recommendations, target ranking, and automated “threat” scores. Every card +should include the source's own caveat and a prominent “not operational” label. + +### 9. Global power and industrial infrastructure + +Global Energy Monitor publishes open-access datasets covering global power +plants and related energy infrastructure. Its Global Integrated Power Tracker +describes facilities, capacity, technology, status, and owners across many +countries. This complements the project's existing datacenters, dams, and +submarine cables. +[ GEM open data ](https://globalenergymonitor.org/download-data), +[ Global Integrated Power Tracker ](https://globalenergymonitor.org/projects/global-integrated-power-tracker) + +Feature: `ENERGY SYSTEMS` mode with generation facilities, transmission context +where licensed, construction/retirement status, energy technology, and a +time-lapse of the global energy transition. Add Open Charge Map for charging +stations and OpenStreetMap/GBFS for local mobility context. +[ Open Charge Map API ](https://www.openchargemap.org/develop/api) + +This is a strong visual differentiator because it turns “infrastructure mode” +from a dense pile of points into a system: source, fuel, capacity, status, +nearby weather, grid geography, and imagery. + +### 10. Biodiversity and living-world layer + +GBIF provides occurrence search, species matching, species profiles, media, +maps, and spatially binned occurrence layers. It supports global biodiversity +records but warns that high-volume queries can be rate-limited; map tiles and +bounded queries are preferable for an interactive globe. +[ GBIF occurrence API ](https://techdocs.gbif.org/en/openapi/v1/occurrence), +[ GBIF maps API ](https://techdocs.gbif.org/en/openapi/v2/maps) + +Feature: `LIVING EARTH`. Show species observations, migration corridors, +protected areas, flowering/seasonality signals, and acoustic or camera-trap +datasets where licensed. A time slider can show how observations move with +seasons and climate. Use coarse aggregation and location uncertainty for +sensitive species; never expose precise nests or endangered-animal locations +when the source applies protection rules. + +### 11. Public knowledge graph for place intelligence + +Wikidata's SPARQL service can retrieve structured entities with coordinates, +relationships, dates, identifiers, and multilingual labels. OpenAlex and +Crossref provide scholarly metadata, institutions, funding, licenses, and +linked identifiers. These are not live sensors, but they let a selected place +explain itself: nearby observatories, universities, dams, ports, research +stations, protected sites, historic events, and public datasets. +[ Wikidata SPARQL service ](https://www.wikidata.org/wiki/Help%3AQueries), +[ OpenAlex API ](https://help.openalex.org/api/), +[ Crossref REST API ](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) + +Feature: `PLACE DOSSIER`. One click on a region produces a source-linked graph +of public institutions, infrastructure, environmental datasets, observatories, +and relevant research. This is a much safer and more useful AI context layer +than asking a model to hallucinate what a location contains. + +Implementation: precompute bounded place packs and cache query results. Do not +run unconstrained SPARQL from the browser; the public endpoint has query-load +constraints. Require explicit user action before expensive knowledge-graph +queries. + +## Feature concepts that emerge from these APIs + +### A. The World State Graph + +Create a graph view where nodes are public entities or events and edges are +observed relationships: “camera near flood gauge,” “vessel crossed current,” +“fire near road,” “satellite passed over event,” “facility in basin,” or “news +cluster references disaster.” Every edge needs a provenance list and a rule +explanation. The graph is not an AI oracle; it is a transparent composition of +public evidence. + +### B. Change detection as the primary interaction + +Make “what changed?” a first-class button. Compare current and previous +observations for imagery, fire, water, traffic, flights, vessels, Internet +reachability, air quality, and event reports. The result should be a ranked +change queue with evidence age, magnitude, and confidence—not an unbounded +stream of notifications. + +### C. Independent-source agreement meter + +For any selected event, show which sources agree, which are stale, which are +modeled, and which are silent. This would be a signature feature of the app: +the globe visualizes not only the world but also the limits of knowing it. + +### D. Public-data mission generator + +Turn the existing scene director into research missions: + +- “Follow a flood from rainfall to river gauge to public camera.” +- “Compare a wildfire's thermal anomaly, smoke, weather, and road network.” +- “Trace an Internet outage from IODA signal to BGP visibility and submarine + cable geography.” +- “Watch a volcanic alert alongside seismicity, satellite imagery, and public + reports.” +- “Compare ocean currents, AIS density, fishing effort, and sea-surface + temperature.” + +Each mission should use a ledger snapshot and source manifest so it is +repeatable and educational rather than dependent on a lucky live moment. + +### E. Open-source provider marketplace + +The existing source-pack idea can grow into a signed catalog of reviewed public +data packs. Each pack declares API host, license, attribution, refresh rate, +maximum cost, privacy class, and failure states. Installers can choose “natural +events,” “Internet observatory,” “marine,” “biodiversity,” or “energy” packs +without enabling everything at once. + +## Recommended build order + +### Phase 1: high leverage, low integration risk + +1. Observation envelope and provenance ledger. +2. NASA EONET + GDACS + USGS volcano layer. +3. NASA GIBS dated raster overlay. +4. Open-Meteo + OpenAQ atmosphere panel. +5. ReliefWeb/GDELT geographically clustered briefing layer. + +### Phase 2: distinctive systems view + +6. USGS modern water data and basin navigation. +7. Copernicus Marine current/wave layer. +8. IODA + RIPE routing/connectivity observatory. +9. Global Energy Monitor infrastructure pack. +10. Change detection and source-agreement UI. + +### Phase 3: heavier and permissioned + +11. Copernicus Sentinel search and bounded processing. +12. Global Fishing Watch integration under its non-commercial terms. +13. ACLED contextual layer for approved users. +14. GBIF living-world layer with sensitive-location handling. +15. World State Graph and mission authoring over all of the above. + +## What not to integrate + +Do not add arbitrary camera scraping, private feeds, leaked credentials, facial +recognition, license-plate recognition, people search, device tracking, port +scanning, exploit databases used for targeting, or person-level “threat” scores. +Do not turn aggregate public events into claims about individual intent. Do not +make a map look more certain by hiding source age, model status, spatial error, +or contradictory observations. + +The product can feel like a god's-eye view while remaining responsible if its +central promise is: **see more of the public world, understand where each fact +came from, and see the uncertainty instead of hiding it.** + +## Sources + +1. [NASA EONET v3 documentation](https://eonet.gsfc.nasa.gov/docs/v3) +2. [GDACS API quick start](https://gdacs.org/Documents/2025/GDACS_API_quickstart_v1.pdf) +3. [USGS Volcano API](https://volcanoes.usgs.gov/hans-public/api/volcano/default) +4. [NASA GIBS access basics](https://nasa-gibs.github.io/gibs-api-docs/access-basics/) +5. [Copernicus Data Space Ecosystem](https://dataspace.copernicus.eu/) +6. [Sentinel Hub API reference](https://documentation.dataspace.copernicus.eu/APIs/SentinelHub/ApiReference.html) +7. [Open-Meteo API documentation](https://open-meteo.com/en/docs) +8. [OpenAQ API overview](https://docs.openaq.org/about/about) +9. [National Weather Service API](https://www.weather.gov/documentation/services-web-api) +10. [Copernicus Marine programmatic access](https://help.marine.copernicus.eu/en/articles/4794731-which-programmatic-services-are-available) +11. [Global Fishing Watch API documentation](https://globalfishingwatch.org/our-apis/documentation/) +12. [USGS Water Data API documentation](https://api.waterdata.usgs.gov/docs/) +13. [IODA HTTP API](https://api.ioda.inetintel.cc.gatech.edu/v2/) +14. [RIPE routing status API](https://stat.ripe.net/docs/data-api/api-endpoints/routing-status) +15. [RIS Live manual](https://ris-live.ripe.net/manual/) +16. [RouteViews API documentation](https://api.routeviews.org/docs/) +17. [GDELT Project data documentation](https://gdeltproject.org/data.html) +18. [ReliefWeb API documentation](https://apidoc.reliefweb.int/index.html) +19. [ACLED API documentation](https://acleddata.com/api-documentation) +20. [Global Energy Monitor open data](https://globalenergymonitor.org/download-data) +21. [Global Integrated Power Tracker](https://globalenergymonitor.org/projects/global-integrated-power-tracker) +22. [Open Charge Map API](https://www.openchargemap.org/develop/api) +23. [GBIF occurrence API](https://techdocs.gbif.org/en/openapi/v1/occurrence) +24. [GBIF maps API](https://techdocs.gbif.org/en/openapi/v2/maps) +25. [Wikidata SPARQL service](https://www.wikidata.org/wiki/Help%3AQueries) +26. [OpenAlex API](https://help.openalex.org/api/) +27. [Crossref REST API](https://www.crossref.org/documentation/retrieve-metadata/rest-api/) diff --git a/IMPROVEMENTS/20-emerging-conflict-observatory.md b/IMPROVEMENTS/20-emerging-conflict-observatory.md new file mode 100644 index 0000000..04870d7 --- /dev/null +++ b/IMPROVEMENTS/20-emerging-conflict-observatory.md @@ -0,0 +1,271 @@ +# Emerging Conflict Observatory + +## Feature + +Add a public-data Conflict Observatory for discovering, contextualizing, and +tracking emerging conflict zones and humanitarian crises. It should combine +georeferenced event data, humanitarian reports, displacement indicators, +protests, disaster conditions, media attention, and infrastructure disruption +into an explainable evidence view. + +## Product charter + +This is a public, educational feature for laypeople who want to monitor and +understand ongoing situations in the world. God's Eye View is not a tactical +battlefield map, is not intended for use in a conflict, and must not provide +operational or conflict-support capabilities. The feature exists to make public +evidence, humanitarian impact, source disagreement, and uncertainty easier to +understand. + +This is deliberately not a battlefield command layer. It should not provide +target recommendations, individual tracking, weapon-effects analysis, tactical +route planning, live unit locations, or predictions about where a person or +force will move next. + +## Why it belongs in God's Eye View + +The project already visualizes aircraft, vessels, fires, earthquakes, public +cameras, installations, satellites, and communications infrastructure. An +emerging conflict is rarely represented by one feed. It appears as a changing +pattern across reported events, displacement, communications, infrastructure +damage, weather, public imagery, and humanitarian response. + +The valuable product is therefore not “the red zone map.” It is a transparent +answer to: + +- What public evidence suggests that conditions are changing? +- When did each source observe or report it? +- Which sources independently agree? +- What is known about civilian and humanitarian impact? +- What remains unknown, stale, disputed, or underreported? + +## Recommended source stack + +### UCDP Georeferenced Event Dataset + +UCDP provides a REST API for georeferenced conflict events and related conflict +datasets. It is useful for historical baselines, event-rate changes, conflict +geography, and retrospective validation. It is not a second-by-second live feed, +so the UI must label its publication cadence and revision date. + +[UCDP API documentation](https://ucdp.uu.se/apidocs/) + +### ACLED + +ACLED provides political-violence, demonstration, and related event data. Its +API requires account authentication, and its CAST endpoint provides monthly +country/territory-level forecasts of political-violence event counts up to six +months ahead. Forecasts must be presented as forecasts with model/source +metadata, never as certainties or tactical warnings. + +[ACLED access documentation](https://acleddata.com/api-documentation/getting-started) · +[ACLED CAST endpoint](https://acleddata.com/api-documentation/cast-endpoint) + +### ReliefWeb + +ReliefWeb's read-only v2 API provides curated reports, disasters, countries, +sources, and related content. It requires an application name, limits results +and daily calls, and warns that contributed reports may retain the original +source's copyright. The integration should display report metadata and link to +the original rather than bulk-republish report bodies. + +[ReliefWeb API documentation](https://apidoc.reliefweb.int/index.html) · +[ReliefWeb endpoints](https://apidoc.reliefweb.int/endpoints) + +### HDX HAPI + +HDX HAPI is designed to standardize humanitarian indicators from multiple +partners. Relevant datasets include conflict events, food security, internally +displaced people, operational presence, humanitarian needs, and population +context. HAPI requires an app identifier and should be treated as a metadata or +indicator source rather than universal ground truth. + +[HDX HAPI getting started](https://hdx-hapi.readthedocs.io/en/latest/getting-started/) · +[HDX HAPI overview](https://centre.humdata.org/ufaqs/about-the-humanitarian-api-hapi/) + +### GDELT and public reporting + +GDELT can provide multilingual news/event geography and media-volume context. +Use it to detect that reporting about a place is changing, not to assert that +the most-mentioned claim is true. Keep article links and publisher diversity +visible. Combine it with ReliefWeb and official sources rather than allowing +media volume to become a conflict-severity score. + +[GDELT data documentation](https://gdeltproject.org/data.html) + +### Supporting context + +Use NASA EONET and GDACS for overlapping natural disasters, Open-Meteo or +official national weather for environmental conditions, IODA/RIPE for aggregate +Internet disruption, Copernicus or NASA imagery for dated change evidence, and +the existing aircraft, vessel, fire, camera, road, and infrastructure layers. +Each remains a separate evidence stream with its own freshness and uncertainty. + +## Core experience + +### Conflict watchlist + +Add a `CONFLICTS` mode to the right rail. It shows a ranked but explainable list +of regions where one or more indicators changed recently. A row should include +the region, latest event/report dates, event-rate change against baseline, +humanitarian indicators, source count, source diversity, connectivity or +infrastructure changes, and a confidence band. + +Do not show one opaque “threat score.” If ranking is needed, use visible factors +such as `EVENT ACTIVITY`, `HUMANITARIAN PRESSURE`, `REPORTING CHANGE`, and +`SOURCE AGREEMENT`, each linked to underlying records. + +### Evidence timeline + +Selecting a region opens a timeline with separate lanes for UCDP/ACLED events, +ReliefWeb reports, HAPI indicators, GDELT media clusters, Internet signals, +imagery acquisitions, and relevant natural hazards. Every item shows event time, +publication time, source time, and ingestion time where available. + +The timeline distinguishes a directly reported event, a later revision, a +forecast, a model-derived indicator, a media-volume change, and a missing or +stale source. This is where the existing Observation Ledger and Time Machine +proposals become essential. + +### Civilian context panel + +Make humanitarian impact a first-class surface. Show available displacement, +food-security, shelter, health, access, and operational-presence indicators with +their geographic granularity and reporting date. Add public infrastructure such +as hospitals, roads, water systems, and power facilities only as context, never +as targetable objects. + +If a source is silent, state `NO PUBLIC INDICATOR AVAILABLE`; never interpret +absence of humanitarian data as absence of harm. + +### Source agreement and dispute view + +For every event cluster, show which sources corroborate it, which merely repeat +one another, and which disagree on date, location, severity, or status. Articles +that cite the same wire report must not count as independent corroboration. + +An event with one unverified report can be shown as `REPORTED / UNCORROBORATED`. +After independent confirmation it may become `MULTI-SOURCE REPORTED`; it should +not become `CONFIRMED` unless the source methodology supports that word. + +## Transparent emergence detection + +Define emergence as a visible combination of changes, not a hidden model +intuition. Candidate signals include: + +1. Event-count acceleration against a region's own historical baseline. +2. Geographic spread into adjacent cells. +3. Increased event-type diversity. +4. Independent source arrival or source-diversity increase. +5. Humanitarian reporting or displacement change. +6. Communications disruption from aggregate Internet systems. +7. Dated imagery change or natural-hazard overlap. +8. A sharp difference from the prior 30/90-day norm. + +The detector should emit structured explanations rather than a bare score: + +```js +{ + regionId, + window: { from, to }, + indicators: [ + { id: 'event-acceleration', value, baseline, sourceIds }, + { id: 'humanitarian-pressure', value, sourceIds }, + { id: 'source-diversity', value, sourceIds } + ], + state: 'WATCH' | 'CHANGING' | 'ESTABLISHED' | 'UNCERTAIN', + limitations: [] +} +``` + +Use hysteresis and minimum evidence thresholds so one sensational article or +one provider outage cannot flip a region into an alert state. A source outage +must produce `UNKNOWN`, not a false decrease in conflict activity. + +## Architecture + +Add `src/data/conflictObservatory.js` as a coordinator, keeping provider +adapters separate: + +- `src/data/ucdp.js` +- `src/data/acled.js` +- `src/data/reliefWeb.js` +- `src/data/hdxHapi.js` +- `src/data/gdelt.js` +- `src/data/conflictChange.js` + +Each adapter normalizes into the common Observation envelope. Authenticated +providers such as ACLED belong behind server-side proxies with rate limits, +cache headers, and sanitized errors. ReliefWeb's `appname` should identify the +application. Large historical pulls should run as scheduled imports or bounded +server jobs, not on every browser pan. + +Initially render coarse hexagons, region boundaries, and event clusters. Exact +point display should be restricted by source precision and a privacy/safety +policy. Store source attribution and terms beside each observation so exports +do not detach evidence from its conditions of use. + +Voice commands can include “show emerging conflict contexts in the last 30 +days,” “why is this region on the watchlist,” “compare humanitarian reports with +event data,” and “show only multi-source reported events.” Responses must cite +the evidence state and say when a result is inferred, forecast, stale, or +contested. + +## Safe public-imagery context + +Allow dated satellite imagery, public cameras, and terrain context only when +source rights and privacy rules permit it. Imagery comparisons can show broad +urban damage, smoke, flooding, road blockage, or fire extent, but the UI should +avoid exact tactical interpretation and avoid exposing sensitive locations at +unnecessary precision. + +## Safety and responsible-use boundaries + +- No individual people, biometric data, phone identifiers, or social-graph + tracking. +- No targeting, target ranking, strike support, weapon effects, or tactical + route features. +- No automated actor-intent classification. +- No live unit tracking or prediction of force movement. +- No exact-location amplification when a source intentionally generalizes it. +- No raw user-generated imagery redistribution without rights. +- No alerts that imply emergency authority or operational certainty. +- Clear delays, spatial aggregation, and source-specific precision controls for + rapidly changing or sensitive events. + +The app should include a “why this is limited” disclosure. Public OSINT should +make evidence easier to examine, not make uncertain claims look like classified +truth. + +## Testing and QA + +Build fixtures for a single uncorroborated report, multiple reports copied from +one source, independent sources with conflicting coordinates, a revised event, +a delayed humanitarian indicator, a forecast that does not materialize, an +Internet outage with no conflict evidence, a conflict event with no humanitarian +data, provider failure, stale-cache states, and a sensitive location requiring +aggregation. + +Add visual QA for the watchlist, timeline, source graph, civilian context panel, +and globe overlays. Test that Context isolation and existing tracked aircraft, +vessel, satellite, and camera selections survive entry and exit. Add a red-team +review specifically for accidental tactical affordances and misleading color +semantics. + +## Suggested delivery sequence + +1. UCDP historical layer and evidence timeline. +2. ReliefWeb reports and disaster grouping. +3. HDX HAPI humanitarian indicators. +4. ACLED authenticated integration and CAST forecasts. +5. GDELT media-volume and source-diversity context. +6. Transparent emergence indicators and watchlist. +7. Dated imagery and aggregate connectivity context. +8. Correlation workspaces and replayable conflict briefings. + +## Definition of done + +A user can open a region, see a dated and source-linked account of changing +public evidence, compare conflict events with humanitarian conditions, inspect +source disagreement, and understand what is unknown. The app never turns that +context into a tactical targeting system or presents a forecast as a fact. diff --git a/IMPROVEMENTS/21-what-changed-mode.md b/IMPROVEMENTS/21-what-changed-mode.md new file mode 100644 index 0000000..dfcaabd --- /dev/null +++ b/IMPROVEMENTS/21-what-changed-mode.md @@ -0,0 +1,57 @@ +# What Changed Mode + +## Feature + +Add a first-class `WHAT CHANGED?` mode that compares a selected place, region, +or viewport across two time windows and produces an evidence-backed change +queue. It should answer “what is different?” rather than forcing users to +remember the prior state of every layer. + +## Why it is useful + +God's Eye View already has live layers, a proposed observation ledger, time +replay, conflict context, satellite imagery, public cameras, and environmental +data. Change detection is the interaction that turns those ingredients into a +daily-use observatory. It is useful for ordinary changes as well as crises: +weather shifts, traffic patterns, fires, floods, construction, changing camera +availability, altered air quality, new reports, or unusual connectivity. + +## User experience + +The user chooses a comparison window such as: + +- Now versus one hour ago +- Today versus yesterday +- This week versus last week +- Current month versus the same month last year +- A custom ledger or satellite-image interval + +The right rail shows ranked cards such as `NEW`, `REMOVED`, `INCREASED`, +`DECREASED`, `MOVED`, `RECLASSIFIED`, `SOURCE CHANGED`, and `UNKNOWN`. Every +card includes the affected layer, before/after values, source timestamps, +confidence, and an action to inspect the underlying observations. + +The globe supports a difference mode: fading old observations, highlighting new +ones, animating movement, and showing a split-screen or swipe comparison for +imagery. Modeled or interpolated changes use a different visual treatment from +directly observed changes. + +## Implementation + +Create `src/change/changeDetector.js` with layer-specific comparators and a +common result schema. Comparators should include entity appearance/disappearance, +numeric delta, geometry displacement, density change, categorical transition, +source-health transition, and raster difference. Each result references ledger +observation IDs and includes an explanation rather than an opaque anomaly score. + +Use the ledger's spatial index to compare only the selected area and time range. +Add hysteresis and minimum thresholds so telemetry jitter does not create a +constant stream of meaningless changes. Keep a clear distinction between “no +change observed,” “no observation available,” and “the source was unavailable.” + +## Testing and definition of done + +Test clock boundaries, stale records, out-of-order observations, antimeridian +geometry, duplicate events, sparse sampling, source outages, and provider +revisions. A user should be able to open a place, select two periods, see a +ranked and explainable list of changes, and trace every result to its sources. diff --git a/IMPROVEMENTS/22-place-briefing.md b/IMPROVEMENTS/22-place-briefing.md new file mode 100644 index 0000000..6ef9947 --- /dev/null +++ b/IMPROVEMENTS/22-place-briefing.md @@ -0,0 +1,51 @@ +# Place Briefing and Public Context Dossier + +## Feature + +Add a structured briefing for every city, region, selected coordinate, or event. +The briefing should assemble current conditions, recent changes, relevant public +events, nearby infrastructure, humanitarian context, source health, and known +limitations into a readable public-data dossier. + +## Why it is useful + +The current application is excellent at showing a scene but asks users to know +which layer to activate and how to interpret it. A place briefing gives a +layperson an entry point without hiding the underlying evidence. It also creates +a natural surface for voice: “Explain this place,” “What changed here?”, and +“What should I be uncertain about?” + +## Briefing structure + +Every briefing should use the same sections: + +1. **Where** — locality, region, coordinates, time zone, and map scale. +2. **Now** — weather, air, traffic, visible cameras, and active public signals. +3. **Recent change** — the most important ledger changes for the chosen window. +4. **Events** — natural, humanitarian, civic, or media-reported events. +5. **Systems** — transport, energy, water, communications, and infrastructure. +6. **Evidence** — sources, timestamps, agreement, and freshness. +7. **Limitations** — missing, stale, modeled, disputed, or low-resolution data. + +The briefing should never summarize a place as safe, dangerous, normal, or +clear based on incomplete feeds. Use neutral language such as “no matching +public observations were found in the selected sources.” + +## Implementation + +Create `src/briefing/placeBriefing.js` with a deterministic section builder. +Each section returns structured facts and source references before any language +generation occurs. The voice or text summarizer receives only that structured +payload and must preserve uncertainty labels and links. + +Add a cache keyed by place geometry, time window, enabled source versions, and +ledger generation. Briefings should be reproducible from an offline snapshot. +Allow users to expand every sentence into its supporting records and export the +briefing as Markdown with a source manifest. + +## Testing and definition of done + +Test empty regions, conflicting sources, missing locality names, stale weather, +offline snapshots, long place names, language fallback, and source-link +preservation. A user should be able to select any place and receive a useful, +readable, source-linked briefing without the app inventing facts. diff --git a/IMPROVEMENTS/23-everyday-world-context.md b/IMPROVEMENTS/23-everyday-world-context.md new file mode 100644 index 0000000..e5a4901 --- /dev/null +++ b/IMPROVEMENTS/23-everyday-world-context.md @@ -0,0 +1,42 @@ +# Everyday World and Continuity Layer + +## Feature + +Add an “everyday world” layer that shows ordinary civic and community activity +alongside crisis, infrastructure, and environmental layers. It can include +public transit, schools, universities, hospitals, markets, parks, cultural +venues, libraries, sports events, public webcams, bikeshare, and open community +spaces. + +## Why it is useful + +A world observatory should not define places only through disasters, conflict, +military installations, or infrastructure. Showing ordinary life gives users +geographic and human context, reduces sensationalism, and makes the globe +interesting even when no major event is occurring. + +It also creates better briefings: a city is not just a coordinate with traffic; +it has institutions, routines, public services, and changing patterns of use. + +## Implementation + +Build this as a curated category registry over existing OSM, GBFS, public-event, +and source-pack data. Every category declares whether it is static, scheduled, +observed, or inferred. Use clustered symbols at global scale and richer cards +only near the camera. + +Add a `CONTINUITY` preset that activates a balanced set of civic layers without +turning on every dataset. The preset should be reversible and should not alter +the user's explicit layer choices permanently. A daily panel can show public +activity such as transit service, open-air markets, events, and public cameras. + +Keep sensitive facilities generalized where appropriate. Do not expose personal +attendance, individual movement, or private event-participant data. Public venue +records are context, not a people-tracking system. + +## Testing and definition of done + +Test category licensing, stale schedules, duplicate OSM entities, global LOD, +accessibility labels, and interactions with conflict and humanitarian modes. A +user should be able to explore a place through ordinary civic context without +the map becoming a dense unreadable inventory. diff --git a/IMPROVEMENTS/24-public-street-time-travel.md b/IMPROVEMENTS/24-public-street-time-travel.md new file mode 100644 index 0000000..e6d43fb --- /dev/null +++ b/IMPROVEMENTS/24-public-street-time-travel.md @@ -0,0 +1,41 @@ +# Public Street-Level Time Travel + +## Feature + +Add an historical street-imagery experience using openly accessible, +rights-reviewed sources such as KartaView, Mapillary, and local public imagery +packs. Users can select a road or neighborhood, browse available sequences by +date, and compare how the visible environment changed over time. + +## Why it is useful + +Satellite imagery gives broad coverage but little street-level context. Public +street sequences make the globe tangible: users can see road construction, +seasonal change, flood aftermath, new buildings, changing signage, or how a +neighborhood grows. This is also useful for map literacy and historical +exploration without requiring a proprietary street-view license. + +## Implementation + +Create `src/data/streetImagery.js` with provider adapters, a sequence index, and +a rights-aware frame loader. KartaView provides public photos and sequences +with geographic and date search; Mapillary requires registered API access. The +catalog must preserve attribution, capture date, contributor/source, and image +license. + +The UI should offer a road ribbon, date slider, sequence playback, side-by-side +comparison, and a “show on globe” action. Frames should remain attached to their +original capture location; interpolating a camera path between images must be +visibly marked as approximate. + +Do not run generic object recognition over the imagery. If a provider supplies +its own scene metadata, display it as provider metadata with provenance. Do not +retain downloaded frames in the observation ledger unless the source permits +caching and export. + +## Testing and definition of done + +Test sparse sequences, gaps, duplicate captures, privacy masks, expired imagery, +provider outages, date/time zones, and license restrictions. A user should be +able to compare public street-level views across time without the feature +pretending that sparse imagery is continuous surveillance. diff --git a/IMPROVEMENTS/25-community-map-verification.md b/IMPROVEMENTS/25-community-map-verification.md new file mode 100644 index 0000000..995f824 --- /dev/null +++ b/IMPROVEMENTS/25-community-map-verification.md @@ -0,0 +1,40 @@ +# Community Map Verification Workspace + +## Feature + +Add a workspace for users to flag stale, incorrect, or incomplete public map +context and prepare evidence-backed OpenStreetMap Notes or source-pack reports. +The workspace should help users contribute corrections without granting the app +automatic editing authority. + +## Why it is useful + +Live data and bundled datasets inevitably contain errors. The project already +surfaces cameras, roads, installations, facilities, and infrastructure from +public sources. A verification workflow turns users from passive viewers into +careful contributors while keeping edits reviewable by the appropriate +community. + +## Implementation + +Add `src/verification/` with a local evidence bundle containing selected entity, +map position, observation timestamps, source links, optional user note, and +before/after imagery references. Provide templates for “wrong location,” “no +longer exists,” “new feature,” “stale feed,” and “source attribution issue.” + +For OpenStreetMap, generate a reviewable note draft and link to the official +OSM note flow. The app should not automatically create or close notes by +default. OSM documentation explicitly recommends contextual analysis because +notes can be misleading or false, so the UI should require a confirmation step +and show the evidence bundle before submission. + +For internal catalog sources, export a maintainer-ready JSON or Markdown report. +Keep user identity and private annotations local unless the user explicitly +submits them. + +## Testing and definition of done + +Test coordinate precision, attachment redaction, offline drafts, duplicate +reports, source takedown, and submission cancellation. A user should be able to +produce a useful correction report without the application silently editing +third-party databases. diff --git a/IMPROVEMENTS/26-uncertainty-literacy-mode.md b/IMPROVEMENTS/26-uncertainty-literacy-mode.md new file mode 100644 index 0000000..2f97126 --- /dev/null +++ b/IMPROVEMENTS/26-uncertainty-literacy-mode.md @@ -0,0 +1,44 @@ +# Uncertainty Literacy Mode + +## Feature + +Add an educational mode that explains how public data works while users explore +the globe. It should turn source age, missing data, modeled values, spatial +uncertainty, source disagreement, and confidence bands into understandable +interactive lessons. + +## Why it is useful + +The project's visual language can make uncertain data look authoritative. A +layperson may interpret a glowing marker as a precise fact even when it is a +cached estimate or a coarse model. Teaching users how to read the evidence is a +core part of making this a responsible public observatory. + +## Implementation + +Create short contextual explainers for concepts such as: + +- Observation time versus publication time +- Stale data versus no data +- Modeled traffic versus observed traffic +- Interpolated tracks versus measured positions +- Media volume versus event severity +- Source outage versus quiet conditions +- Spatial precision and aggregation +- Forecast versus retrospective record +- Corroboration versus repeated reporting + +Add a `WHY THIS?` button to selected cards and a global “evidence labels” mode +that expands compact chips into plain-language explanations. Include a guided +tutorial using synthetic data so users can see how a false all-clear appears +when a source fails, and how the correct UI preserves `UNKNOWN`. + +The mode should be available in simple language, with keyboard and screen-reader +support. It must never turn caveats into a wall of technical text; use one-line +explanations with expandable detail. + +## Testing and definition of done + +Test every visible source-state label for a plain-language explanation, reduced +motion, translation fallback, and no color-only meaning. A first-time user +should understand why an empty layer does not automatically mean an empty world. diff --git a/IMPROVEMENTS/27-region-comparison-studio.md b/IMPROVEMENTS/27-region-comparison-studio.md new file mode 100644 index 0000000..bede215 --- /dev/null +++ b/IMPROVEMENTS/27-region-comparison-studio.md @@ -0,0 +1,42 @@ +# Region Comparison Studio + +## Feature + +Add a synchronized comparison workspace for two locations, regions, time +windows, or source configurations. Users can compare places using the same +categories and scales instead of mentally switching between separate globe +views. + +## Useful comparisons + +- Two cities during the same weather event +- Two river basins during flooding +- Two ports during a shipping change +- Two regions with different air-quality conditions +- Two places before and after a major event +- Current conditions versus a historical baseline +- Two conflict-affected regions using humanitarian indicators +- Satellite imagery versus public street imagery + +## Implementation + +Create `src/comparison/` with two independent scene contexts sharing a clock, +style, source-health store, and comparison schema. The primary globe remains +interactive; the secondary view can be a split globe, synchronized inset, or +2D evidence panel depending on screen size. + +Each metric must define its unit, time basis, spatial aggregation, and missing- +data behavior. Never compare raw counts from regions with radically different +coverage without showing normalization. For example, a higher news count can +mean greater media attention, not greater event severity. + +Add difference cards for density, change rate, freshness, source coverage, and +selected environmental values. Export comparisons as a source-linked Markdown +briefing or portable snapshot. + +## Testing and definition of done + +Test different time zones, unequal observation coverage, missing secondary +data, antimeridian regions, rapid location swaps, and camera synchronization. A +user should be able to compare two places without losing track of which source +or time window each value represents. diff --git a/IMPROVEMENTS/28-world-pulse-briefing.md b/IMPROVEMENTS/28-world-pulse-briefing.md new file mode 100644 index 0000000..77dbb46 --- /dev/null +++ b/IMPROVEMENTS/28-world-pulse-briefing.md @@ -0,0 +1,44 @@ +# World Pulse Daily Briefing + +## Feature + +Add an optional daily and hourly “World Pulse” surface that presents a small, +ranked set of notable public changes around the globe. It should be a doorway +into the observatory, not a sensationalist breaking-news feed. + +## Content + +Possible cards include: + +- Newly detected natural events +- Environmental changes +- Humanitarian reporting changes +- Significant connectivity disruptions +- Interesting satellite or orbital events +- Public-camera scenes with changing conditions +- Major infrastructure or transport changes +- A region with unusually sparse or conflicting data +- A place whose public systems returned to normal after an outage + +Every card should show the reason it was selected, source age, source diversity, +and a direct action to open the evidence view. “Most discussed” and “most +severe” must remain separate concepts. + +## Implementation + +Build a server-side or local digest generator over Observation Ledger changes, +event clusters, provider health, and user watchlists. Use a bounded daily +generation job rather than making every browser independently query all feeds. +Store the digest as a signed/versioned snapshot with source references so a user +can revisit yesterday's briefing. + +Allow filters for environment, humanitarian context, infrastructure, space, +Internet, and public cameras. Let users mute categories and choose a calmer +“quiet mode” that shows slow changes rather than alerts. + +## Testing and definition of done + +Test duplicate stories, source outages, stale inputs, time zones, empty days, +and sensational-card suppression. A user should receive a concise, source-linked +overview that leads into the globe and remains understandable when no major +event occurred. diff --git a/IMPROVEMENTS/29-data-coverage-gaps.md b/IMPROVEMENTS/29-data-coverage-gaps.md new file mode 100644 index 0000000..cb61e25 --- /dev/null +++ b/IMPROVEMENTS/29-data-coverage-gaps.md @@ -0,0 +1,46 @@ +# Data Coverage and Blind-Spot Atlas + +## Feature + +Add a layer that visualizes where the observatory has strong, weak, stale, or +missing public data. The map should show the limits of observation as clearly as +it shows observations. + +## Why it is useful + +Users naturally mistake a quiet map for a quiet world. Coverage differs sharply +by country, provider, language, wealth, weather, Internet connectivity, and +political access. Showing the coverage surface helps prevent false conclusions +and gives contributors a way to improve source packs. + +## Implementation + +Create `src/coverage/coverageAtlas.js` that aggregates per-cell metadata: + +- Last successful observation by source family +- Number of independent sources +- Average observation age +- Spatial precision +- Percentage of entities with provenance +- Public-camera availability +- Satellite acquisition recency +- Air-quality/weather station density +- Humanitarian reporting availability +- Internet measurement presence +- Conflict/event source coverage + +Render this as a selectable “coverage confidence” layer with separate maps for +freshness, source diversity, precision, and missingness. Avoid a single global +coverage score unless users can inspect its components. A dark region should +mean “low available public coverage,” not “safe,” “empty,” or “inactive.” + +Add a contributor view showing where a new source pack, camera catalog, weather +station, or map correction would improve coverage. Connect gaps to the +Community Map Verification and Source Pack Workbench proposals. + +## Testing and definition of done + +Test sparse regions, source outages, global wraparound, stale caches, unequal +cell sizes, and transitions between coverage levels. A user should be able to +look at any quiet area and immediately understand whether it is quiet or simply +poorly observed. diff --git a/IMPROVEMENTS/README.md b/IMPROVEMENTS/README.md new file mode 100644 index 0000000..7b151fa --- /dev/null +++ b/IMPROVEMENTS/README.md @@ -0,0 +1,44 @@ +# Proposed Improvements + +These proposals are deliberately implementation-oriented. They treat the current +Vite + vanilla JavaScript + Cesium application as the starting point, preserve +the local-first and public-data boundaries, and assume the existing layer +contract (`init`, `enable`, `disable`, `update`, `destroy`, `getStats`) remains +the primary extension seam. + +## Product charter + +God's Eye View is a public, educational observatory for laypeople who want to +understand ongoing situations in the world through openly available data. It is +not a tactical battlefield map, is not intended for use in a conflict, and must +not provide operational or conflict-support capabilities. Proposed features +should improve public understanding, source transparency, humanitarian context, +and uncertainty awareness. + +The proposals are independent enough to be delivered separately, but they form +an especially strong long-term sequence: + +1. Make observations durable and explainable with the Observation Ledger. +2. Add time navigation and deterministic replay on top of those observations. +3. Add event correlation and user-authored alert rules without identifying + people. +4. Add a plugin/source-pack SDK so the ecosystem can contribute layers safely. +5. Add the adaptive LOD and offline/export features to make large scenes useful + on more machines and in more contexts. + +The public-camera proposals extend the existing CCTV layer into a world-wide +atlas while keeping each feed's publication terms, attribution, freshness, and +privacy posture visible. + +The public-conflict proposal applies the same discipline to emerging crises: +source triangulation, humanitarian context, historical trends, and uncertainty +instead of a tactical live-battle map. + +Additional observatory proposals cover the user-facing layer above the feeds: +change detection, place briefings, public street imagery, community map +verification, everyday-world context, uncertainty education, comparisons, daily +briefings, and visible data-coverage gaps. + +Each file describes one feature, why it belongs in God's Eye View, a concrete +implementation design, UI behavior, tests, rollout risks, and a definition of +done. These are proposals, not claims that the features already exist.