mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-05 10:53:59 +00:00
Merge branch 'main' into main
This commit is contained in:
692 files changed
+198677
-69710
No files matched your search
@@ -0,0 +1,102 @@
|
||||
# Application construction
|
||||
|
||||
`gods-eye-view/application` exports `createApplication`. Importing it does not
|
||||
create a viewer, discover configuration, start requests, or attach browser
|
||||
listeners. Construction is also inactive until the caller invokes `start()`.
|
||||
|
||||
The caller supplies four constructors, in this order:
|
||||
|
||||
| Constructor | Receives | Standalone implementation |
|
||||
| ---------------- | ---------------------------------------------- | --------------------------------------------- |
|
||||
| `createScene` | `signal`, `defer` | Viewer, attribution and initial map |
|
||||
| `createControls` | `scene`, `signal`, `defer` | Style manager and camera presentation |
|
||||
| `createData` | `scene`, `controls`, `signal`, `defer` | Layer catalog, registration and restoration |
|
||||
| `createTools` | `scene`, `controls`, `data`, `signal`, `defer` | Scenes, annotations, voice and page listeners |
|
||||
|
||||
Each constructor returns its component object, or a promise for that object.
|
||||
Those objects are passed unchanged to later constructors. Configuration and
|
||||
service instances belong in the caller's closures; the application does not
|
||||
interpret provider names, environment variables, endpoints, or module paths.
|
||||
There is no module discovery or automatic import mechanism.
|
||||
|
||||
```js
|
||||
import { createApplication } from 'gods-eye-view/application';
|
||||
import { createApplicationViewer } from 'gods-eye-view/application/viewer';
|
||||
|
||||
const app = createApplication({
|
||||
createScene({ defer }) {
|
||||
const viewer = createApplicationViewer({ container, creditContainer });
|
||||
defer(() => viewer.destroy());
|
||||
return { viewer };
|
||||
},
|
||||
createControls,
|
||||
createData,
|
||||
createTools,
|
||||
});
|
||||
const unsubscribe = app.subscribe(({ status, phase }) => {
|
||||
// Update the caller's startup presentation.
|
||||
});
|
||||
await app.start();
|
||||
// When the application is no longer needed:
|
||||
unsubscribe();
|
||||
await app.destroy();
|
||||
```
|
||||
|
||||
The example's containers and three remaining constructors are supplied by the
|
||||
consumer. The viewer helper preserves the standalone viewer's render settings;
|
||||
it neither selects map sources nor reads keys. Supply a visible credit container
|
||||
and retain all attribution required by the chosen sources. Cesium is external to
|
||||
this export: the consuming build must provide the same instance used elsewhere
|
||||
in its application.
|
||||
|
||||
## Lifecycle and ownership
|
||||
|
||||
Register `defer(cleanup)` immediately after acquiring each resource, before any
|
||||
`await`. Cleanup registration remains open until that constructor settles. Each
|
||||
callback may return a promise. Within a phase, callbacks run in reverse order.
|
||||
Across phases, teardown runs **tools, controls, data, scene**: controls must cancel
|
||||
restoration while their data manager and viewer are still alive.
|
||||
|
||||
`start()` returns the same promise on repeated calls. `destroy()` is terminal and
|
||||
also returns the same promise on repeated calls. It aborts the shared signal
|
||||
immediately, waits for an in-flight constructor to settle, and runs all registered
|
||||
cleanup callbacks. Constructors must forward the signal to cancellable operations
|
||||
and check it after awaits. If a provider cannot cancel construction, register
|
||||
cleanup for its late result before returning. Destruction waits for that result;
|
||||
it does not pretend a pending resource has already been released.
|
||||
|
||||
A constructor failure triggers the same cleanup before rejecting startup.
|
||||
Cleanup failures do not stop the remaining callbacks; they are reported through
|
||||
an `AggregateError`. Constructors own cleanup for resources created internally,
|
||||
including anything allocated before their own construction throws.
|
||||
|
||||
`getState()` returns a frozen `{ status, phase }` snapshot. Status is `created`,
|
||||
`starting`, `ready`, `destroying`, `destroyed`, or `failed`. `phase` identifies the
|
||||
constructor during startup. `subscribe(listener)` immediately reports the current
|
||||
snapshot and returns an unsubscribe function. Install observers before `start()`
|
||||
to receive every startup phase. Observer failures cannot interrupt startup or
|
||||
teardown. `getComponents()` returns a frozen, shallow snapshot of the currently
|
||||
constructed component objects; the component instances themselves remain mutable.
|
||||
|
||||
`ready` means all constructors have returned. Background feed activity and the
|
||||
standalone share-restoration result keep their existing separate contracts.
|
||||
|
||||
## Standalone wiring
|
||||
|
||||
`src/main.js` reads the existing browser configuration and starts
|
||||
`src/standalone/application.js`. That module selects the four implementations
|
||||
in its directory. Scene setup, controls, layer registration, tools and loading
|
||||
chrome have separate owners. The existing `window.__godsEyeView` debugging shape
|
||||
is preserved while the app is running.
|
||||
|
||||
The standalone controls and layer modules still contain page-scoped state.
|
||||
Only one standalone application may be constructed per page. Shutdown releases
|
||||
its runtime resources and debugging handles; reload the page to start again.
|
||||
It is not an embeddable, removable HTML shell or a multiple-viewer implementation.
|
||||
Consumers of the small application export supply their own component ownership;
|
||||
the lifecycle controller itself has no shared instance state.
|
||||
|
||||
Later component extractions can replace a constructor's internals without
|
||||
changing the startup contract or moving standalone imports into the package.
|
||||
Run the unit suite, package boundary gate, build, tracking and first-run browser
|
||||
checks when changing this wiring.
|
||||
@@ -0,0 +1,387 @@
|
||||
# Formatting and component boundaries
|
||||
|
||||
Run `npm run format` to format the files in `scripts/format-scope.json` and
|
||||
`npm run format:check` to check that same list without writing. CI checks the
|
||||
entire adopted list on Linux and Windows. Prettier is pinned in the development
|
||||
dependencies; use the installed version so local and CI output agree. The shared
|
||||
configuration specifies two spaces, single quotes, semicolons and LF endings.
|
||||
|
||||
Add new reusable modules and their tests to the list as they are extracted.
|
||||
Keep mechanical formatting in its own commit after behavior is stable. Existing
|
||||
source-text regression assertions still apply; investigate failures and preserve
|
||||
their behavioral coverage when a move or line wrap changes a tested shape.
|
||||
Files outside the list retain their surrounding style until deliberately adopted.
|
||||
Generated output, local configuration, browser evidence and bundled datasets are
|
||||
excluded. The formatter validates every entry before writing any file.
|
||||
|
||||
## Current component ownership
|
||||
|
||||
| Surface | Owns | Receives from its caller |
|
||||
| -------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| `gods-eye-view/infrastructure` | Datacenter/dam definitions and fresh layer construction | Context, overlay and render operations |
|
||||
| `gods-eye-view/infrastructure/geojson` | Data loading, Cesium entities, selection handling and resource cleanup | A viewer and those same operations |
|
||||
| `gods-eye-view/infrastructure/lod` | Pure visibility budgets and selection policy | Position/visibility records and camera measurements |
|
||||
| `src/data/localGeojson.js` | Standalone compatibility wiring | The application's existing shared services |
|
||||
| `src/main.js` and `src/standalone/` | Standalone browser startup | Local configuration |
|
||||
|
||||
The application and infrastructure exports are browser source modules. Use their documented
|
||||
exports instead of importing standalone startup or reaching into internal files.
|
||||
The application owns the viewer, context store, overlay host and render scheduler;
|
||||
layers use the supplied callbacks. See [the infrastructure contract](INFRASTRUCTURE-LAYERS.md).
|
||||
|
||||
`npm run check:boundaries` builds every declared package export, with app Vite
|
||||
configuration disabled. `scripts/package-boundaries.json` lists each export's
|
||||
component, owned modules and external runtime dependencies. A new export must be
|
||||
classified. Imports outside the declared modules fail, including unused and
|
||||
literal dynamic imports. Cesium stays external so the consuming application
|
||||
supplies the same compatible instance as its viewer. Existing consumer tests
|
||||
also check import-time inactivity and asset URLs under a non-root base.
|
||||
|
||||
These checks cover the declared exports, not every import in the application.
|
||||
They check build-time imports, not arbitrary runtime-generated module URLs.
|
||||
Keep runtime module discovery out of these exports. When extracting another
|
||||
component, add its ownership and consumer tests together. Node services must use
|
||||
separate entry points and their own checks when they become reusable; importing
|
||||
them into a browser component is not supported.
|
||||
|
||||
`gods-eye-view/application` owns construction order, startup state, cancellation
|
||||
and disposal of caller-supplied components. Its only owned module is
|
||||
`src/app/application.js`. `gods-eye-view/application/viewer` separately owns the
|
||||
standard Cesium viewer configuration in `src/app/viewer.js`; Cesium stays external.
|
||||
Neither export imports standalone UI, layers, tools or configuration. See
|
||||
[application construction](APPLICATION.md) for the contracts and current limits.
|
||||
|
||||
UI panels and individual source adapters remain future extractions. They should
|
||||
become smaller modules with explicit lifecycle owners as their callers migrate.
|
||||
|
||||
## Build and standalone server configuration
|
||||
|
||||
`gods-eye-view/build/vite` is a separate Node-only export. `build/vite.js`
|
||||
creates standard Cesium/Vite browser settings from explicit inputs. It imports
|
||||
only the declared `vite-plugin-cesium` build dependency, discovers no environment,
|
||||
and constructs no provider middleware. Call it from a Vite configuration:
|
||||
|
||||
```js
|
||||
import { createBrowserViteConfig } from 'gods-eye-view/build/vite';
|
||||
|
||||
export default createBrowserViteConfig({
|
||||
plugins: [],
|
||||
googleApiKey: undefined,
|
||||
cesiumToken: undefined,
|
||||
});
|
||||
```
|
||||
|
||||
Consumers supply compatible Vite and vite-plugin-cesium development dependencies.
|
||||
The package's `node` export condition has no browser fallback. The boundary gate
|
||||
builds this group for Node, with the declared build dependency external; its
|
||||
owned module list is checked just like browser groups. Browser groups cannot
|
||||
use build-only dependency exceptions.
|
||||
|
||||
`server/standalone/vite.config.js` loads the root environment and passes selected
|
||||
browser keys, host/port and the ordered local provider plugins to this helper.
|
||||
`server/providers/local.js` composes provider factories and re-exports existing
|
||||
helpers for compatibility. Provider Settings lives in `server/standalone/key-setup.js`
|
||||
and writes to the same root `.env` or Pinokio store as before. `vite.config.js`
|
||||
preserves the default configuration and named provider exports for tools/tests.
|
||||
|
||||
## Aircraft and vessel providers
|
||||
|
||||
`server/providers/live.js` exports the existing Node middleware factories and
|
||||
request helpers. `aircraft/` owns OpenSky state/fallback, military positions,
|
||||
enrichment and track endpoints in separate files. `vessels/ais-live.js` owns
|
||||
websocket setup and route responses; `vessels/ais-store.js` owns record ingestion,
|
||||
static metadata and recent-track storage. Neither area imports globe rendering.
|
||||
`common/http.js` owns capped reads/coalescing; `common/query.js` owns query values.
|
||||
|
||||
These plugins retain their existing process-scoped caches and server lifetime.
|
||||
Importing the entry does not start acquisition. The AIS plugin disposes its
|
||||
socket/watchdog on server close and re-reads configuration after restart.
|
||||
The portable `gods-eye-view/sources/adsb-lol` export normalizes existing aircraft
|
||||
records without importing Node middleware or a renderer. Browser layer/controller
|
||||
separation is outside this server extraction.
|
||||
|
||||
## Place-search and routing providers
|
||||
|
||||
`gods-eye-view/server/providers/places` exports the Google nearby-place and
|
||||
text-search plugin, OSRM route registration, and their shared Node helpers.
|
||||
The existing Overpass plugin still mounts `/api/route` in its original order.
|
||||
Google credentials are resolved on each request; the default uses the existing
|
||||
server-key precedence, and callers may supply `resolveApiKey`.
|
||||
|
||||
`gods-eye-view/sources/places` exports portable response projections for Google
|
||||
place results and OSRM route results/profile aliases. These functions own no
|
||||
credentials, requests, caches, environment loading, or rendering. Callers retain
|
||||
input validation and upstream-response acceptance. The boundary check builds
|
||||
this entry independently and rejects Node imports.
|
||||
|
||||
The browser's direct geocoding, annotation rendering and full Overpass query
|
||||
service remain in their existing modules.
|
||||
|
||||
## Satellite and launch providers
|
||||
|
||||
`gods-eye-view/server/providers/space` is a Node-only entry for the CelesTrak
|
||||
and Launch Library 2 middleware. Separate files under `server/providers/space/`
|
||||
own each feed's acquisition, memory/disk cache and error handling. The existing
|
||||
local composition mounts them in the same order. Importing the entry performs
|
||||
no acquisition; factory calls create independent cache state.
|
||||
|
||||
`gods-eye-view/sources/space` owns only fixed upstream URL construction: the
|
||||
CelesTrak group/TLE query and Launch Library's recent 30-day detailed feed.
|
||||
Callers supply the group or end date and own validation, credentials, transport,
|
||||
response limits and cache policy. The boundary gate checks this portable entry
|
||||
separately from the Node providers. Satellite rendering and launch replay remain
|
||||
in their existing browser modules.
|
||||
|
||||
## Terrain, traffic, fires and bike-share providers
|
||||
|
||||
`gods-eye-view/server/providers/terrain`, `/traffic`, `/firms` and `/gbfs`
|
||||
are separate Node-only entries. Each owns its existing middleware and
|
||||
process-scoped cache or request handling. Standalone composition mounts them in
|
||||
the original order; their imports do not start acquisition.
|
||||
|
||||
`gods-eye-view/sources/terrain` exports existing point-key, retry and cache
|
||||
reconstruction mechanics with injectable acquisition dependencies.
|
||||
`gods-eye-view/sources/traffic` exports tile math and budget calculations.
|
||||
`gods-eye-view/sources/gbfs` exports host/path acceptance and cache-header rules.
|
||||
These entries import no Node middleware, application configuration or rendering.
|
||||
Callers retain their request admission and transport policy. FIRMS CSV parsing
|
||||
remains an owned dependency of the FIRMS Node provider. The boundary gate
|
||||
checks each entry independently.
|
||||
|
||||
Browser terrain sampling, traffic matching/drawing, fire overlays and bike-share
|
||||
layer lifecycle remain in their current modules. This extraction changes no
|
||||
source defaults, credentials, quotas, data interpretation or visual behavior.
|
||||
|
||||
## Local search, regional context, voice and setup
|
||||
|
||||
Node-only exports `server/providers/overpass`, `server/providers/military-installations`,
|
||||
`server/providers/regional` and `server/providers/openai` own request handling
|
||||
without importing the standalone configuration or browser rendering. Overpass
|
||||
separates query admission, geometry simplification, cache and transport; military
|
||||
search shares the bounded transport. Regional place/news/weather acquisition is
|
||||
separate from briefing and weather-effect response caches. Voice handlers share
|
||||
existing rate limits and request reading; schemas and instructions are separate.
|
||||
|
||||
`server/standalone/key-setup` is explicitly standalone Node functionality.
|
||||
Its factory and the local voice factory accept `sourceRoot` for application-owned
|
||||
configuration/log files; defaults resolve the repository root. Local voice also
|
||||
accepts an optional `annotationGuidance` paragraph. Neither factory starts
|
||||
acquisition on import. Setup retains its pre-environment-load provenance capture
|
||||
and development-only registration. Package checks enumerate every owned module
|
||||
and reject browser imports of these Node entries.
|
||||
|
||||
## Browser place search
|
||||
|
||||
`gods-eye-view/search` exports an explicit geocoding service and Google/Photon
|
||||
adapters. The entry owns normalization, bounded caches, deadlines and fallback
|
||||
sequencing. It imports no application state, environment configuration, rendering
|
||||
or Node server code. Google transport is supplied by its caller.
|
||||
|
||||
`src/standalone/placeSearch.js` constructs the configured Google request and
|
||||
keyless Photon fallback. The application passes this service to location
|
||||
controls, annotation resolution and voice/radio actions. Those consumers retain
|
||||
framing, landmark recovery, footprint matching and playback decisions. Existing
|
||||
reverse geocoding and nearby/text-search routes remain separate.
|
||||
|
||||
## Panel controls
|
||||
|
||||
`gods-eye-view/ui/panels` owns collapse-button binding, nearest-panel Escape
|
||||
handling, hover delays and delayed content-focus handoff. It accepts existing
|
||||
DOM elements and callbacks; importing it creates no browser state. `destroy()`
|
||||
removes owned listeners and cancels pending work without changing saved state
|
||||
or moving focus. Call it before removing or replacing the controls.
|
||||
|
||||
`src/ui.js` retains panel layout, persistence, share restoration and application
|
||||
reactions to state changes. Map Source selection and Location draft cleanup are
|
||||
provided through callbacks. The component imports no globe, data, application
|
||||
or server modules. Package checks and scoped formatting cover this entry.
|
||||
|
||||
## Surface keyboard handling
|
||||
|
||||
`gods-eye-view/ui/surfaces` exports `createSurfaceKeyboard` from
|
||||
`src/ui/surfaceKeyboard.js`. It receives a root DOM node, an optional document,
|
||||
an `isActive` predicate, an `onEscape` action and an optional return-focus fallback.
|
||||
Construction is inert. `activate()` remembers the opener and installs one capture
|
||||
listener; repeated activation is harmless. `deactivate({ restoreFocus: true })`
|
||||
removes that listener and restores the opener when connected, otherwise invoking
|
||||
the supplied fallback. Omit return focus when yielding to another surface.
|
||||
`destroy()` permanently releases ownership without moving focus.
|
||||
|
||||
The welcome launcher and Provider Settings retain content, visibility, initial
|
||||
focus, animation and screen-specific policy. Tab boundaries are read from the
|
||||
current visible/enabled controls for each key; ordinary movement within those
|
||||
boundaries remains native. The component honors already-handled keys and has no
|
||||
app, server, storage or network dependencies. Its package boundary is checked
|
||||
independently from the standalone screens that consume it.
|
||||
|
||||
## Panel rail layout
|
||||
|
||||
`gods-eye-view/ui/layout` exports synchronous `layoutLeftPanelRail` and
|
||||
`layoutRightPanelRail` passes, `measurePanelNaturalHeight`, and the existing pure
|
||||
corridor/allocation helpers. Separate modules own left placement, right placement,
|
||||
DOM height measurement and rail geometry. They import no application, renderer,
|
||||
server, storage or network modules; package checks build this entry independently.
|
||||
|
||||
Callers supply rail/obstacle DOM nodes, the viewport, HUD state, the preferred
|
||||
panel, disclosure/retry callbacks and the left measurement cache. Right layout
|
||||
reads the caller's Display scroll value at measurement time and restores it
|
||||
within the resulting scroll range. The left pass notifies its caller after
|
||||
alignment so the right pass can follow. Neither pass installs listeners, timers
|
||||
or observers; construction/import does no work. Scheduling, preference writes,
|
||||
share restoration and movement of controls between containers remain caller-owned.
|
||||
Existing helper imports from `cockpitMath.js` and `rightRailPolicy.js` remain
|
||||
compatible through re-exports.
|
||||
|
||||
## Visual input
|
||||
|
||||
`gods-eye-view/ui/input` exports `bindApplicationShortcuts` and
|
||||
`createStyleParameters`. The shortcut binder owns one bubbling keydown listener
|
||||
and receives the document, editing target and explicit action callbacks.
|
||||
Parameter controls own only the supplied container's generated rows/listeners;
|
||||
uniform metadata and read/write/change operations come from the caller.
|
||||
Clearing permits reuse; destruction is final. Neither module imports the app,
|
||||
renderer, persistence or services. The facade retains panel visibility, share
|
||||
restore claims and render scheduling. Both controls are destroyed before the
|
||||
facade's asynchronous teardown can yield.
|
||||
|
||||
## Display controls
|
||||
|
||||
`ui/display` owns Display button, selector and slider subscriptions. It receives
|
||||
DOM elements and explicit actions, imports no application or effect singleton,
|
||||
and releases every listener on destruction. Settings and rendering remain with
|
||||
the caller.
|
||||
|
||||
## Visual effects
|
||||
|
||||
`ui/effects` exports the effects controller and existing preset definitions.
|
||||
It owns shader stages and their clock, with explicit render ownership callbacks.
|
||||
Construction installs no stages or frame callbacks. Stop animation before
|
||||
releasing UI consumers, then destroy to remove owned stages and restore the
|
||||
borrowed bloom state. `ui/effects/bloom` exposes the pure intensity/version helpers
|
||||
without loading the renderer. UI presentation and product-action coordination
|
||||
remain in their callers.
|
||||
|
||||
## Map Source controls
|
||||
|
||||
`ui/maps` owns source-chip presentation, selection feedback and its subscription
|
||||
lifetime. It receives the existing controller and explicit state/action callbacks;
|
||||
it imports no renderer or application. Source construction and availability policy
|
||||
remain with the map controller. Rebuilding controls removes their previous chip
|
||||
listeners, and destruction suppresses late completions without owning or destroying
|
||||
the supplied controller.
|
||||
|
||||
## Layer panel
|
||||
|
||||
`ui/layers` exports the Layers panel and clear-control binding. Callers supply
|
||||
snapshots, row descriptors, subscriptions and actions; the component imports no
|
||||
layer implementation or application bootstrap. Layer transactions remain with
|
||||
the caller. Hidden-page refresh scheduling remains an explicit callback.
|
||||
|
||||
`ui/layers/feedback` exposes the existing pure loading/notice reducers separately
|
||||
from DOM controls. Scheduling and presentation stay with their callers.
|
||||
|
||||
## Location controls
|
||||
|
||||
`ui/location` exports Location controls, the cancellable lookup controller and
|
||||
the existing location-status formatter. Callers supply city data, search and
|
||||
navigation operations. The component owns DOM listeners and pending expansion;
|
||||
it imports no geocoder, camera engine, layer or application bootstrap. Existing
|
||||
camera authority and search providers remain supplied by the application.
|
||||
|
||||
### Radio controls
|
||||
|
||||
`ui/radio` owns Radio input, disclosures, tuner state and presentation. It
|
||||
receives the existing Radio port and explicit layer/layout actions, without
|
||||
importing the renderer or station providers. Pure tuner calculations retain
|
||||
compatibility exports from the data layer. Disposal revokes DOM listeners and
|
||||
subscriptions before ending the active tuning interaction.
|
||||
|
||||
### Camera panel controls
|
||||
|
||||
`ui/cctv` composes camera controls, frame loading, calibration editing and status
|
||||
presentation. It receives DOM elements, the existing camera port and explicit
|
||||
application actions; it imports no provider, layer or camera engine. Selection,
|
||||
placement, navigation and storage policy remain outside the component family.
|
||||
|
||||
### Context coordination
|
||||
|
||||
`ui/context` owns mode controls, transactions, session restoration and manager
|
||||
subscriptions. Composition supplies the manager, installations search and
|
||||
explicit visual/panel actions. `ui/context/policy` exposes the existing pure
|
||||
mode and restoration rules. No source transport or renderer is imported by
|
||||
these components; initial state and action results retain their existing shape.
|
||||
|
||||
## Cockpit controls
|
||||
|
||||
`ui/cockpit` supplies the Cockpit controller and Display portal. Camera updates,
|
||||
instruments, Context readouts, briefings, signals, layout and input have separate
|
||||
modules. Composition supplies the existing aircraft/awareness operations, terrain
|
||||
cache and sampling operations, continuous-render owner and regional briefing
|
||||
service. Pure math, utility layout and vision helpers have explicit exports.
|
||||
Disposal releases subscriptions and pending work; portal moves preserve the
|
||||
original Display groups, independent scroll positions and current focus owner.
|
||||
|
||||
## Scene controls
|
||||
|
||||
`ui/scenes` owns Scene prompts, panel input, project/shot rows, playback button and runtime
|
||||
presentation. It receives project reads and explicit actions, with no imports of
|
||||
the director, source modules, camera engine or storage. Replacement and disposal
|
||||
release listeners; pending action feedback is limited to its current owner.
|
||||
|
||||
## UI assembly and styles
|
||||
|
||||
`ui/shell` assembles controls from supplied existing layer, navigation, terrain,
|
||||
rendering, HUD and share operations. `src/standalone/ui.js` provides the running
|
||||
application's instances; `src/ui.js` remains the compatibility entry. The shell
|
||||
imports no standalone bootstrap or concrete live layer implementation.
|
||||
Panel layout, position/drag, notices, recording and deferred UI work have separate
|
||||
owners with synchronous cleanup. Existing scene, share and HUD engines retain
|
||||
their entry points. `ui/styles` loads the ordered stylesheet entry; component
|
||||
files retain the original cascade, including responsive and dock refinements.
|
||||
|
||||
## UI state and Scene actions
|
||||
|
||||
`StyleManager.subscribeShareState(listener)` supplies the current shareable
|
||||
visual preferences and subsequent settings changes. The built-in share manager
|
||||
consumes the same updates. `subscribeLocationSearch(listener)` follows the
|
||||
current lookup owner across control replacement. `LocationSearch.subscribe`
|
||||
provides the corresponding per-owner contract. Changes identify `started`,
|
||||
`found`, `missing`, `failed`, `settled`, and the shell's `reset`; request IDs
|
||||
belong to their lookup owner. Only current requests publish accepted results.
|
||||
|
||||
`gods-eye-view/scenes` exports `SceneDirector`. Its `subscribe(listener)` supplies
|
||||
small playback snapshots plus editing outcomes. Scene controls consume these
|
||||
updates to render the affected presentation; progress does not copy the project
|
||||
or rebuild shot rows. Project import/export outcomes include the project;
|
||||
shot editing outcomes include the affected shot and its index before deletion.
|
||||
Camera, layer sequencing, storage and run-file download retain their existing
|
||||
owners. Cesium remains an external dependency supplied by the application.
|
||||
|
||||
Each listener receives `{ state, change, revision, initial }` and subscriptions
|
||||
return an unsubscribe function. Initial state is emitted by default; pass
|
||||
`{ emitCurrent: false }` to receive only changes. Snapshots and outcomes are
|
||||
immutable plain data. Reentrant publications retain delivery order; removing a
|
||||
listener or destroying its owner prevents further queued delivery. These APIs
|
||||
perform no network requests and discover no additional modules.
|
||||
|
||||
## Maps
|
||||
|
||||
`maps/controller` coordinates scene changes and lifetimes. `maps/imagery`,
|
||||
`maps/terrain` and `maps/3d` supply constructors; `maps/defaults` selects the
|
||||
standard sources and their setup/fallback policy. The standalone facade wires
|
||||
these to the application's render governor.
|
||||
|
||||
A registry supplies `sources`, `defaultId`, `unknownId` and optional `recoveryId`.
|
||||
Each source has a user-facing `descriptor`, availability/reason, and either an
|
||||
`imagery({ signal })` factory or a supplied `tileset`/`createTileset({ signal })`.
|
||||
Imagery sources can share a terrain definition with a stable `id` and
|
||||
`create({ signal })` returning `{ provider }` or `{ terrain }`. Cache IDs must
|
||||
identify the same source for the lifetime of that registry. Sources may supply
|
||||
trusted credit markup and construction/tile-error fallback policy. Provider
|
||||
configuration stays in factories; descriptor values are the presentation API.
|
||||
|
||||
Factories should honor cancellation where their SDK supports it. The controller
|
||||
also checks scene ownership after asynchronous work, so late results cannot
|
||||
replace a newer selection. Supplied tilesets are caller-owned; factory-created
|
||||
tilesets and provider caches are controller-owned. Construct a fresh controller
|
||||
for a new viewer or configuration lifetime.
|
||||
+787
-14
@@ -1,7 +1,669 @@
|
||||
# God's Eye View Current State
|
||||
|
||||
The optional **ALPR Cameras** layer shows community-mapped OpenStreetMap locations,
|
||||
not camera footage or plate records. City-scale queries use the existing Overpass
|
||||
provider, with capped results, retry, cached-data and incomplete-coverage notices.
|
||||
Its `./layers/alpr` entry exposes a per-instance layer factory and bounded source
|
||||
adapter. Sources return normalized records, stale/coverage flags and their own
|
||||
attribution; rendering does not parse Overpass payloads. The standalone
|
||||
registration supplies selection, picking, terrain and
|
||||
render services. Selected cards and Data attribution identify OpenStreetMap.
|
||||
Layer state and the existing voice layer tools include `alpr-cameras`.
|
||||
The row count explicitly says **nearby**: loaded records can be outside the
|
||||
screen. A purple-dot legend identifies the fixed 8-pixel markers (12 pixels when
|
||||
selected). **SHOW NEAREST** frames and selects the nearest loaded camera; it is
|
||||
disabled with no loaded cameras or while following a tracked entity. This action
|
||||
chooses from the current source snapshot and uses rendered surface height from
|
||||
3D tiles or globe terrain when available.
|
||||
Coverage follows a bounded neighborhood around the screen-center ground point,
|
||||
with a radius of twice the camera-to-ground range (at least 1 km), rather than
|
||||
extending to the horizon. Sky, dateline-crossing and wider-than-city views do not
|
||||
query. Movement within an accepted or pending query reuses it. Markers retain
|
||||
their Cesium identity and ground clamping while their geometry is unchanged;
|
||||
refreshes preserve selection without replaying a click event.
|
||||
|
||||
Data Centers, Dams and Submarine Cables release their built Cesium data sources
|
||||
and record references when disabled. Parsed datasets remain cached for the layer
|
||||
lifetime, so re-enable rebuilds entities without downloading or parsing again;
|
||||
this can take longer than simply revealing hidden entities. Destruction clears
|
||||
the parsed cache as well. A disable during loading cannot leave a completed
|
||||
build hidden in the scene.
|
||||
|
||||
CCTV exposes a factory through `./layers/cctv`. Catalog and health requests,
|
||||
frame/media URLs, camera records, ground placement, geometry queues, playback,
|
||||
projection, cards, calibration and interaction have separate components. The
|
||||
standalone entry supplies application-owned scene, ground and activation services.
|
||||
Each layer owns its state and visibility listener; destruction cancels source
|
||||
reads and pending initialization. Malformed health responses retain prior health.
|
||||
Existing catalog fallback, camera poses, frame pacing and coverage controls remain.
|
||||
|
||||
Traffic and bikeshare expose factories through `./layers/traffic` and
|
||||
`./layers/bikeshare`. Traffic separates road requests, ingestion, animation,
|
||||
flow matching, styling, viewport lifecycle and development timing. Each source
|
||||
owns its decoded flow cache; cancelled bodies cannot refill it. Bikeshare
|
||||
separates its city registry, station source, parsing, rendering, selection and
|
||||
proximity lifecycle. Existing standalone sources, live/simulated labels, road
|
||||
budgets, station availability and polling behavior are retained.
|
||||
|
||||
Installations and proximity context now expose `./layers/installations` and
|
||||
`./layers/awareness` factories. Each owns its records, selection, presentation,
|
||||
navigation and lifecycle. The standalone entries supply existing scene operations
|
||||
and the aircraft/vessel/installation instances used for proximity queries.
|
||||
Installation requests use a bounded source adapter; explicit nearby-place search
|
||||
remains separate from ordinary mapped-site loading. Invalid snapshots retain the
|
||||
previous display, and cancelled requests cannot publish a later failure state.
|
||||
Viewport limits, saturation retry, placement, query caps and controls are retained.
|
||||
|
||||
Satellite and mission layers expose separate factories through `./layers/satellites`
|
||||
and `./layers/launches`. Each owns its catalog, render state, tracking, interaction
|
||||
and teardown. Source adapters retain the existing CelesTrak and Launch Library
|
||||
endpoints; standalone entries provide scene services and the satellite dependency.
|
||||
The mission factory separates paths, replay, camera, panel, overlays and placement.
|
||||
Pending mission requests abort on disable/destruction and malformed launch
|
||||
snapshots preserve the last accepted display. Catalog groups, propagation cadence,
|
||||
tracking intent, replay timing, controls and source attribution remain unchanged.
|
||||
|
||||
The fire layer now exposes `./layers/firms`: an instance factory with separate
|
||||
snapshot requests, records, rendering, cards, selection, viewport scheduling and
|
||||
terrain-anchor batching. The standalone entry supplies the existing FIRMS source
|
||||
and scene services. Disable and teardown cancel pending refreshes; malformed
|
||||
snapshots preserve the last good display. Refresh restoration keeps selection
|
||||
identity without announcing a new user selection. Source/label, LOD thresholds,
|
||||
card limits, fire identities, altitude placement and analyst records are retained.
|
||||
|
||||
Earthquake rendering is exposed through `./layers/earthquakes`. The layer owns
|
||||
its entities and request lifecycle; the application supplies the overlay host
|
||||
and snapshot source. The standalone adapter keeps the existing USGS daily feed,
|
||||
M2.5+ filtering, static discs, magnitude labels and analyst records. Disabling or
|
||||
destroying the layer cancels pending work and ignores late results.
|
||||
|
||||
## Vessel components and sources
|
||||
|
||||
`src/data/aisLiveVessels.js` assembles `createVesselLayer` from the
|
||||
`./layers/vessels` package entry. The factory owns feed lifecycle, keyed records,
|
||||
rendering, selection, trails and cards in separate components. The standalone
|
||||
entry supplies its AISStream source, scene services and existing row limits.
|
||||
|
||||
Incomplete observations retain missing keyed vessels for at most five minutes
|
||||
since their last accepted receipt, within the renderer's row budget (plus the
|
||||
existing selected-contact pin). Complete observations keep the existing removal
|
||||
policy. Empty or failed observations preserve warm data with the existing feed
|
||||
health warning and first-connect grace period. Source timestamps remain source
|
||||
timestamps; receipt does not turn an unknown epoch into a fresh update.
|
||||
|
||||
A refreshed record keeps its identity while updating its history reference.
|
||||
Selection changes, disable and destruction cancel pending trail requests; late
|
||||
responses cannot refill a cleared or replacement trail. Heading and course,
|
||||
sea-surface placement, click ownership and card selection policy are unchanged.
|
||||
|
||||
|
||||
## Military-flight components and aircraft mechanics
|
||||
|
||||
`gods-eye-view/layers/military` exports `createMilitaryFlightLayer`. It uses the
|
||||
same normalized observation contract as civil flights, with separate military
|
||||
classification, styling, model and tracking policy. Each instance owns its
|
||||
contacts, history, scratch objects, model loads and cancellation lifetime.
|
||||
Applications supply the existing scene services and resolve model asset URLs;
|
||||
`src/data/militaryFlights.js` keeps the standalone layer API and adsb.lol source.
|
||||
A source may retain a bounded stale-status reason; the standalone cached-feed
|
||||
behavior remains unchanged.
|
||||
|
||||
`gods-eye-view/aircraft` exports the existing shared classification, icon,
|
||||
metadata, motion, altitude, model-anchor, proximity and selection calculations.
|
||||
It also exports `createMilitaryRegistry`, an explicitly constructed owner for
|
||||
known military identities and active-layer transitions. Its optional background
|
||||
poll consumes the optional `getIdentities` capability, falling back to normalized
|
||||
positioned records when a source has no identity-only capability. The adsb.lol
|
||||
adapter preserves known identities without requiring positions; those entries
|
||||
still cannot enter the renderer. Source replacement
|
||||
and disposal abort pending work and clear retained identities; construction
|
||||
starts no network request. Both standalone aircraft layers use one registry.
|
||||
|
||||
## Civil-flight components
|
||||
|
||||
`gods-eye-view/layers/flights` exports `createCivilFlightLayer`. Each instance
|
||||
owns its contacts, histories, model collections, scratch objects and lifecycle.
|
||||
State, ingestion, enrichment, motion/floor interpolation, rendering, tracking and
|
||||
queries live in separate files under `src/layers/flights`. The standalone
|
||||
`src/data/flights.js` assembles the existing OpenSky source and scene services.
|
||||
|
||||
Applications supply the existing floor/snap, geoid, picking, sprite, camera,
|
||||
trail, focus, readout, context, aircraft presentation and render services.
|
||||
The factory never constructs a second application registry. Configure a source
|
||||
before initialization; replacing it while initialized is rejected. Model loads
|
||||
use the supplied asset resolver, including the preload path. Enrichment receives
|
||||
an abort signal and cannot update a later lifecycle after destruction. Existing
|
||||
camera, terrain floor, trail, selection and measured model-size policies remain.
|
||||
|
||||
## Browser live-source observations
|
||||
|
||||
Flights, Military Flights and AIS Vessels obtain snapshots and optional history
|
||||
through `gods-eye-view/sources/live`. The standalone adapters use the existing
|
||||
same-origin routes. Aircraft observations distinguish barometric metres from
|
||||
WGS84 ellipsoid metres and retain source position/contact epochs; vessel records
|
||||
retain separate heading/course and sea-surface datum. History is a best-effort
|
||||
addition to the locally accumulated trail, never a promise of complete coverage.
|
||||
|
||||
Snapshot coverage, completeness and freshness are separate fields. A partially
|
||||
admitted aircraft snapshot retains absent contacts for up to five minutes before
|
||||
the usual missed-poll eviction. Unknown snapshot times remain unknown in stats. An invalid nonempty
|
||||
snapshot retains the previous display. Empty vessel refreshes retain the existing
|
||||
first-connect grace and warm-data behavior. Known source failures have bounded
|
||||
messages; arbitrary HTTP response bodies are not surfaced as diagnostics.
|
||||
Sources receive cancellation signals and check them after body parsing. The
|
||||
layer's existing lifecycle and selection guards continue to reject late work.
|
||||
|
||||
|
||||
## State and action outcomes
|
||||
|
||||
Share preferences, place lookups and Scene playback expose immutable snapshots
|
||||
and disposable subscriptions. Share settings drive URL updates; lookup outcomes
|
||||
drive Location labels and busy/error feedback. Superseded or disposed lookups
|
||||
cannot publish accepted destinations. Each completion carries its own request
|
||||
identity so an older completion cannot clear the current search indicator.
|
||||
|
||||
Scene controls consume playback state and editing outcomes from the director.
|
||||
Progress updates carry a small playback snapshot and preserve shot-row identity;
|
||||
editing outcomes include a copy of the affected scene or shot. Subscriptions
|
||||
start with current state, isolate listener failures and stop on disposal.
|
||||
`gods-eye-view/scenes` exports the same director used by the standalone app.
|
||||
|
||||
## UI shell and component ownership
|
||||
|
||||
The standalone entry composes the UI with the application's existing layer,
|
||||
terrain, navigation and rendering operations. The shell receives those instances
|
||||
and assembles the controls. Panel layout scheduling, position preferences and
|
||||
active drags, loading notices, recording presentation and DOM lookup have focused
|
||||
owners. Disposal revokes queued presentation and listeners before asynchronous
|
||||
Context restoration, cancels an unfinished drag without saving it, restores the
|
||||
recording HUD and releases status decoration without replacing accessible text.
|
||||
The ordinary control snapshot includes the current 3D model toggle and mode.
|
||||
|
||||
`style.css` imports component styles in their original cascade order. Scene,
|
||||
share, HUD and layer engines retain their existing behavior and entry points.
|
||||
|
||||
## Scene control ownership
|
||||
|
||||
Scene controls own creation/deletion prompts, panel listeners, shot rows, playback/recording presentation
|
||||
and keyboard cancellation. The director supplies project reads and explicit
|
||||
editing/playback actions while retaining persistence, camera and layer sequencing.
|
||||
Shot selection updates the highlight without replacing the row, preserving
|
||||
native double-click rename. Replacing rows revokes their old listeners. Disposal stops controls immediately;
|
||||
late file and failed-action completions cannot update removed presentation.
|
||||
|
||||
## Cockpit component ownership
|
||||
|
||||
Cockpit presentation is separated from its camera/controller behavior. Existing
|
||||
layer, terrain and rendering operations are supplied by composition, retaining
|
||||
the same tracked identity, ground acquisition, motion correction and cadence.
|
||||
The Display portal owns group anchors, focus/scroll restoration and listeners.
|
||||
Superseded portal frames cannot repaint old state or steal focus after disposal;
|
||||
retained Cockpit actions cannot restart a disposed controller. Input, subscriptions
|
||||
and queued panel work stop before asynchronous layer restoration; final camera
|
||||
and portal cleanup follows that restoration.
|
||||
|
||||
|
||||
## Context coordination
|
||||
|
||||
Context controls own Contacts/Space Missions state, entry and exit transactions,
|
||||
layer snapshots and restoration. The application supplies the existing manager,
|
||||
installations search and camera/panel actions. Tab listeners and pending
|
||||
presentation work stop during disposal; layer restoration retains its existing
|
||||
compensation and latest-intent rules. Clear Selected Layers shares this owner,
|
||||
so an older restore cannot replay over a newer Clear action.
|
||||
|
||||
|
||||
## Camera panel ownership
|
||||
|
||||
CCTV controls receive the existing camera port and explicit application actions.
|
||||
Frame loading, calibration editing and status display have separate modules;
|
||||
providers, camera placement and navigation policy retain their existing owners.
|
||||
Changing cameras invalidates old image callbacks and cancels an unfinished
|
||||
calibration edit. Failed refreshes preserve settled pixels for the same camera,
|
||||
while a newly selected camera never shows the prior camera's image. Disposal
|
||||
releases listeners, subscriptions, image handlers, summary timers and chip-hide timers.
|
||||
|
||||
|
||||
## UI disposal
|
||||
|
||||
UI disposal releases the CCTV subscription, command-dock observer, legacy drag
|
||||
resize observer and window resize listener. These remain independent of the
|
||||
Location component and are included in whole-UI browser teardown acceptance.
|
||||
|
||||
## Radio controls
|
||||
|
||||
Radio panel, compact controls and tuner presentation have a dedicated owner.
|
||||
It receives playback, layer actions and layout callbacks; station ingestion,
|
||||
marker placement, audio playback and camera policy stay with their existing
|
||||
owners. Tuner calculations have a pure entry, with existing layer exports
|
||||
preserved. Destruction removes listeners and state subscriptions before ending
|
||||
tuning; a delayed Enable result cannot reveal or refocus removed controls.
|
||||
|
||||
## DriveBC CCTV source pack
|
||||
|
||||
The CCTV catalog adds DriveBC highway cameras for British Columbia alongside the
|
||||
Austin, Caltrans and TfL packs. The server reads the keyless camera list that
|
||||
DriveBC.ca serves at `https://www.drivebc.ca/api/webcams/` and keeps cameras that
|
||||
are switched on and published. Frame URLs are built from each numeric camera id
|
||||
under `https://www.drivebc.ca/images/`; they are never taken from the payload.
|
||||
DriveBC's eight compass orientations become high-confidence heading priors, and
|
||||
its elevation (metres above sea level) seeds the ground height.
|
||||
|
||||
By default the 250 cameras nearest downtown Vancouver and Victoria load.
|
||||
`CCTV_DRIVEBC_MAX_SOURCES` sets the pack cap (8–1200) and
|
||||
`CCTV_DRIVEBC_ENABLED=0` turns the pack off. The default catalog cap rises from
|
||||
900 to 1,050, the sum of the default pack caps, so no default camera is dropped.
|
||||
The Open Government Licence – British Columbia attribution is registered in the
|
||||
Data attribution popover.
|
||||
|
||||
## Location control ownership
|
||||
|
||||
City/POI rows, search/reset bindings, location readouts and the orbit indicator
|
||||
have a dedicated component with explicit navigation actions. A separate lookup
|
||||
controller cancels superseded searches and checks camera authority before flight
|
||||
and result presentation. Existing search providers and camera handoff policy are
|
||||
preserved. Replacing or closing a POI row cancels its pending expansion frame;
|
||||
destruction releases listeners, pending searches and the orbit indicator.
|
||||
|
||||
|
||||
## Layer panel ownership
|
||||
|
||||
Layer rows, feed feedback, counts, focus-preserving chips and toggle listeners
|
||||
are owned by a renderer-free panel component. The layer manager supplies current
|
||||
snapshots, lifecycle actions and row descriptors. Remount and teardown remove
|
||||
listeners and row subscriptions; obsolete completions do not repaint old rows.
|
||||
The clear control presents busy state while its existing action owns the transaction.
|
||||
|
||||
|
||||
## Map Source control ownership
|
||||
|
||||
Map Source controls own chip listeners, source-state subscriptions and selection
|
||||
feedback. Loading remains with the supplied map controller. The active chip
|
||||
follows the source actually displayed, including fallback; obsolete completions
|
||||
cannot overwrite a newer selection. Refresh and destruction revoke old listeners
|
||||
and destruction suppresses late UI updates. Available choices and setup behavior
|
||||
remain unchanged.
|
||||
|
||||
## Visual effects ownership
|
||||
|
||||
VisualEffects owns style-stage creation, crossfades, animation scheduling, bloom
|
||||
and sharpen. Display supplies actions and renders settings; effect execution has
|
||||
no DOM dependency. Existing presets and the 500 ms transition remain unchanged.
|
||||
Stopping the controller revokes animation before asynchronous UI teardown; final
|
||||
destruction removes its stages and restores the borrowed bloom configuration.
|
||||
|
||||
## Display control ownership
|
||||
|
||||
Display button, selector and slider listeners have a single destroyable owner.
|
||||
The application supplies actions and retains effect settings, restore claims and
|
||||
rendering. Native keyboard editing, model modes and current defaults are preserved.
|
||||
Destroying the UI removes these listeners before asynchronous teardown.
|
||||
|
||||
## Application shortcuts and shader parameter controls
|
||||
|
||||
`ui/input` supplies the bubbling application shortcut listener and generated
|
||||
shader-parameter rows. Number/style keys, H/O/V/F/D/C actions, native form-control
|
||||
typing and Escape behavior retain their existing mappings. Capture-phase
|
||||
surfaces continue to arbitrate their own keyboard events first.
|
||||
|
||||
The UI facade retains shader values, share-restore authority, render requests,
|
||||
search dismissal, visibility and Cockpit portal policy. Parameter rows preserve
|
||||
labels, bounds, steps and precision. Rebuilding rows removes their previous
|
||||
listeners; disposal removes shortcuts and parameter listeners synchronously
|
||||
before asynchronous application teardown.
|
||||
|
||||
## Adaptive panel rail layout
|
||||
|
||||
`ui/layout` supplies the left/right rail layout passes, natural-height
|
||||
measurement and pure corridor/allocation helpers. The UI facade passes live DOM
|
||||
nodes, obstacle nodes, HUD presentation, preferred panels and callbacks. It
|
||||
retains observers, frame scheduling, saved/share preferences and Cockpit portals.
|
||||
|
||||
The left rail keeps its measured collapsed heights and obstacle-safe corridor;
|
||||
the right rail follows its top baseline and preserves Display's scroll owner.
|
||||
Automatic collapse remains presentation only, prioritizes the latest explicit
|
||||
panel, and honors keyboard focus on the right. Mobile layout still releases
|
||||
desktop allocation styles. Stable Display allocation avoids unnecessary style
|
||||
writes. This extraction does not change panel positions or layout defaults.
|
||||
|
||||
|
||||
## Surface keyboard lifecycle
|
||||
|
||||
`ui/surfaces` owns the capture-phase keyboard listener, Tab cycling and return
|
||||
focus shared by the first-run launcher and Provider Settings. Each caller
|
||||
activates it while open and deactivates it on dismissal; destruction releases
|
||||
keyboard ownership without moving focus. Reopening captures the current opener.
|
||||
The launcher retains its hit-test/exclusive-surface arbitration and dismissal
|
||||
preferences. Provider Settings retains its existing visibility and save policy.
|
||||
Initial focus, transitions and DOM content remain with each screen. This
|
||||
component does not add modal semantics or make the map inert.
|
||||
|
||||
|
||||
## Panel disclosure lifecycle
|
||||
|
||||
Panel collapse buttons, nested Escape handling and dock hover/focus timing now
|
||||
use `ui/panels`. The component receives existing DOM elements and callbacks for
|
||||
state changes and content focus. Panel layout, saved state, share restoration,
|
||||
Location draft cleanup and Map Source selection remain with their existing
|
||||
callers. Listener and timer cleanup is synchronous when controls are replaced
|
||||
or disposed, preventing old hover or focus work from changing a later view.
|
||||
|
||||
|
||||
## Military feed cooldown and loading guidance
|
||||
|
||||
The adsb.lol military proxy reuses its last response during upstream 429/5xx
|
||||
failures and observes Retry-After, bounded to 5–120 seconds (defaults: 30 seconds
|
||||
for rate limits, 15 seconds for server errors). A failure with no cached data
|
||||
still reports an error. Cached responses carry their age; the browser preserves
|
||||
observation timestamps and marks fallback data stale instead of inventing fresh
|
||||
positions or reporting a failed load. Fresh responses clear that stale state.
|
||||
|
||||
Mapped-installation zoom guidance appears in the layer row without counting as
|
||||
a global loading failure. Guidance statuses do not suppress independent refresh
|
||||
errors.
|
||||
|
||||
|
||||
## Places and CCTV request bounds
|
||||
|
||||
With a Google key configured, nearby and text search reject missing, blank,
|
||||
non-numeric and out-of-range coordinates before the opt-in limiter and upstream
|
||||
request. Text search also requires a nonblank query. Keyless requests retain
|
||||
their `configured: false` response.
|
||||
|
||||
CCTV media waits at most 15 seconds for upstream response headers and returns
|
||||
504 on timeout. Its timer stops when headers arrive, so live bodies can continue
|
||||
streaming; body idle deadlines are separate from this header deadline. Error
|
||||
responses are cancelled. Buffered snapshots have a 16 MiB streaming cap; an
|
||||
oversized image remains an upstream miss and uses the normal fallback chain.
|
||||
The existing declared media size ceiling remains 64 MiB.
|
||||
|
||||
|
||||
## GBFS upstream bounds
|
||||
|
||||
GBFS refuses upstream redirects and enforces its 5 MiB response cap while
|
||||
streaming. The 12-second deadline includes reading the body, and rejected or
|
||||
stalled downloads are cancelled. Development and preview use the same handler.
|
||||
|
||||
|
||||
## Remaining local service modules
|
||||
|
||||
Overpass query validation, geometry simplification, disk caching and upstream
|
||||
transport now have separate modules; military-installation search reuses that
|
||||
transport. Regional briefing combines separate place, news and weather sources,
|
||||
while weather effects uses only the weather source. Existing process-scoped
|
||||
caches, rate limits, stale fallbacks and route ordering are preserved.
|
||||
|
||||
Local voice has separate HUD-summary, debug-log and Realtime-token handlers,
|
||||
with tool definitions and instructions in dedicated files. The factory accepts
|
||||
an optional `annotationGuidance` paragraph; its default instructions and all 28
|
||||
tool definitions remain unchanged. `sourceRoot` resolves debug logs against the
|
||||
application directory. Standalone key setup accepts the same directory option
|
||||
for its environment store and preserves boot provenance, loopback/origin guards,
|
||||
atomic credential writes and development-only registration.
|
||||
|
||||
Node-only package entries expose Overpass, military installations, regional
|
||||
services, local voice and standalone key setup. Importing them starts no network
|
||||
acquisition. Browser layer lifecycle, rendering and voice execution stay in their
|
||||
existing modules.
|
||||
|
||||
## Local build preview
|
||||
|
||||
After `npm run build`, `npm run preview` serves the built app with the same data
|
||||
provider routes as development, including aircraft, satellites, terrain, traffic,
|
||||
FIRMS, GBFS, Overpass and CCTV/media. Unmatched `/api` requests return a JSON 404
|
||||
in both modes instead of the application HTML. Browser routes retain SPA fallback.
|
||||
Credential editing (`/api/setup/*` and Provider Settings) is development-only;
|
||||
preview returns JSON 404 for those endpoints. Server credentials come from the
|
||||
local environment; browser keys are captured at build time. Rebuild after changing
|
||||
a browser key. Preview is for local build verification, not a production server.
|
||||
|
||||
|
||||
## CCTV and radio provider modules
|
||||
|
||||
CCTV catalog acquisition, source normalization and frame/media delivery now live
|
||||
in separate modules. Each CCTV factory owns its catalog and health state; its
|
||||
`sourceRoot` option resolves relative source files against the application root.
|
||||
Radio Browser station normalization, restricted outbound transport and directory
|
||||
caching are separate modules. Node-only package entries expose both provider
|
||||
factories. Routes, payloads, fallback behavior and existing dev/preview hook
|
||||
registration are preserved; browser rendering is unchanged.
|
||||
|
||||
## Terrain, traffic, fire and bike-share provider modules
|
||||
|
||||
Local composition now imports separate Node modules for Re:Earth heights,
|
||||
TomTom flow tiles, NASA FIRMS detections and GBFS station feeds. Existing routes,
|
||||
plugin order, server-key selection, validation, disk caches, budgets, retries
|
||||
and stale/error responses remain unchanged. Each has a Node-only package entry
|
||||
under `gods-eye-view/server/providers/`. Portable terrain mechanics, traffic tile
|
||||
math and GBFS source rules are available under `gods-eye-view/sources/`.
|
||||
The browser layers and their rendering remain in their existing modules.
|
||||
|
||||
## Landmark annotation identity
|
||||
|
||||
When a landmark geocode contains only address components, annotations retain
|
||||
its requested name for outline matching. A city or neighborhood address no
|
||||
longer replaces the landmark's identity. Without a canonical feature name,
|
||||
outline candidates must contain the geocoded anchor or closely match the
|
||||
requested name; otherwise the annotation stays at its geocoded point.
|
||||
Genuine feature-name components and existing administrative/monument matching
|
||||
retain their established behavior.
|
||||
|
||||
## Satellite and launch provider modules
|
||||
|
||||
`server/providers/space/` owns the CelesTrak TLE and Launch Library 2 Node
|
||||
proxies. Their routes, six-hour/15-minute caches, disk storage, stale fallback,
|
||||
request coalescing and optional LL2 server token retain existing behavior.
|
||||
The Node-only `gods-eye-view/server/providers/space` export supplies factories;
|
||||
`sources/space` supplies fixed upstream URL builders with no I/O or environment
|
||||
access. Callers retain validation, transport and response policy.
|
||||
|
||||
## Build configuration and local provider boundaries
|
||||
|
||||
`vite.config.js` delegates to `server/standalone/vite.config.js`, which loads
|
||||
this checkout's environment and constructs the local providers in their existing
|
||||
order. `server/providers/local.js` is the composition and compatibility entry;
|
||||
provider families own their middleware and process state in focused modules.
|
||||
Provider URLs, key selection, cache behavior, setup restrictions and routes are
|
||||
unchanged.
|
||||
|
||||
`gods-eye-view/build/vite` is a Node-only export for explicit browser build
|
||||
settings: Cesium assets, caller-supplied plugins, browser key defines, server
|
||||
binding and document/credential protections. It never reads an environment file
|
||||
or constructs providers. The standalone caller owns those choices.
|
||||
|
||||
Browser startup now lives in `src/standalone/`. That directory contains only
|
||||
browser code; Node configuration remains under `server/`. Application lifecycle
|
||||
and viewer export paths are unchanged.
|
||||
|
||||
## Application startup and shutdown
|
||||
|
||||
The standalone entry now composes scene setup, controls, layer registration and
|
||||
tools through the reusable application lifecycle. Map defaults, layer order,
|
||||
share restoration, voice setup and the running debug handle retain their behavior.
|
||||
The welcome card still waits for restoration and the loading-cover transition.
|
||||
|
||||
Startup failure cleans up acquired resources. Explicit application destruction
|
||||
aborts construction, cancels pending playback/annotations and delayed welcome UI,
|
||||
then releases controls, layers and the viewer. Destruction is terminal; the
|
||||
standalone page must be reloaded to start again. The exported lifecycle and viewer
|
||||
helpers do not import the standalone entry or discover configuration. See
|
||||
[application construction](APPLICATION.md).
|
||||
|
||||
## Scoped formatting and package checks
|
||||
|
||||
`npm run format` and `npm run format:check` operate on the explicit adopted-file
|
||||
list. `npm run check:boundaries` checks the dependency graph of all
|
||||
current package exports in their declared browser or Node runtime; infrastructure owns its three implementation modules
|
||||
and takes Cesium from the consumer. CI runs both checks on Linux and Windows.
|
||||
The standalone app, layer behavior and public export paths remain unchanged.
|
||||
See [component ownership and adoption](CODE-BOUNDARIES.md).
|
||||
|
||||
## Google browser and server keys
|
||||
|
||||
Local Places nearby/text search and the CCTV Street View fallback prefer
|
||||
`GOOGLE_MAPS_SERVER_API_KEY`, falling back to `GOOGLE_MAPS_API_KEY` when the
|
||||
server key is blank or absent. Only the browser key is injected into client
|
||||
code. POWER UP presents one Google Maps entry for the browser key. The optional
|
||||
server key is configured manually in the same ignored root `.env`, or Pinokio's
|
||||
ignored `pinokio/ENVIRONMENT`; it is omitted from Provider Settings and its
|
||||
missing-key count. Existing server keys and the single-key fallback remain
|
||||
supported. `.env.example` and `pinokio/_ENVIRONMENT` document both entries.
|
||||
The Street View headings tool uses the same server-first selection after
|
||||
resolving environment overrides per variable; its explicit `--key` wins.
|
||||
|
||||
|
||||
## Infrastructure marker visibility
|
||||
|
||||
Datacenter/dam registration uses fresh reusable factories with the application's
|
||||
existing context, overlay and render functions. The scoped package exports do
|
||||
not import standalone application globals; see
|
||||
[the infrastructure interface](INFRASTRUCTURE-LAYERS.md) for lifecycle and asset
|
||||
requirements.
|
||||
|
||||
Local GeoJSON layers coalesce concurrent enables into one load. Disabling while
|
||||
loading keeps the result hidden; destruction aborts the fetch and rejects late
|
||||
parse/add results. Destruction and failed setup remove owned context records,
|
||||
so replacing a layer cannot retain stale entities or listeners.
|
||||
|
||||
Datacenters and dams retain their full datasets while limiting active marker
|
||||
stems per layer: 80 at camera heights of 3,000 km or above, 200 from 200 km,
|
||||
and 420 below 200 km. Selection favors existing label priority and nearby
|
||||
features, retains stable choices across small camera movements, and refreshes
|
||||
during continuous motion. Disable/re-enable resets selection cleanly.
|
||||
Close-up stem sizing uses camera-to-feature distance without a 5 km minimum.
|
||||
Unchanged overlay entries do not request another frame; moved positions,
|
||||
changed membership and re-enabling still publish. Ground sampling waits for
|
||||
visible globe tiles to settle and uses valid loaded terrain as a floor while
|
||||
retaining rooftop and below-sea-level elevations. A hidden globe does not
|
||||
constrain photoreal geometry, and retry work remains bounded. Already sampled
|
||||
nearby markers follow higher settled terrain on existing bounded walks, without
|
||||
additional GPU samples or timers, when close-up tile detail refines the floor.
|
||||
The submarine-cable renderer is unchanged. These limits bound active stem work;
|
||||
they do not reduce the materialized entity count or establish an FPS gain.
|
||||
|
||||
## Keyboard interaction and focus
|
||||
|
||||
- Enter on the map-source disclosure opens immediately. A short Space press
|
||||
opens it on key release. Either route focuses the selected source once visible;
|
||||
a bounded retry handles delayed opening transitions, and closing the tray or
|
||||
moving focus elsewhere cancels the handoff.
|
||||
- Keyboard focus rings are a global interface state and stay visible when a
|
||||
button is active or selected. Visual Styles, Location suboptions, Context and
|
||||
mission actions, Cockpit utilities, native fields, and sliders use the same
|
||||
visible-ring contract.
|
||||
- A short Space press on a focused control keeps its native key-release action.
|
||||
If it remains held for 500 ms, focus is checked again, the control is blurred,
|
||||
and push-to-talk starts; releasing a claimed hold cannot activate the old
|
||||
control. The same hold works on the map and page background. Text-entry
|
||||
controls remain protected.
|
||||
- The Location disclosure is reachable with Tab or Shift+Tab and shows a
|
||||
keyboard focus ring. Its city, point-of-interest, search-toggle, and search
|
||||
field controls show inset rings, including selected items. Enter toggles its
|
||||
tray immediately, while Space does so on release; either route makes the revealed controls immediately reachable by Tab;
|
||||
Escape closes it and clears any unfinished search. Escape from a tray control
|
||||
returns focus to the disclosure; Escape on the disclosure clears focus after closing.
|
||||
- Data Layers ON/OFF buttons show a visible keyboard focus ring without
|
||||
changing their enabled state or feed-status presentation.
|
||||
- Display controls and shader-parameter sliders show keyboard focus in both
|
||||
the map panel and Cockpit Display. Arrow keys retain native range adjustment.
|
||||
The enabled CCTV camera dropdown shows keyboard focus as well.
|
||||
- Tab reaches both Contacts and Space Missions in sequence in every Context
|
||||
state. Left/Right arrows also switch them; the focused tab has a distinct ring
|
||||
even when selected.
|
||||
- Keyboard focus on a Space Missions roster item uses the same temporary globe
|
||||
rotation and mission-marker highlight as pointer hover. Focus alone does not
|
||||
select the mission; Enter or Space performs selection. Keyboard and pointer
|
||||
preview ownership remain independent when the pointer is parked over the list.
|
||||
- Radio power controls in the full, compact, and Cockpit surfaces, Search Nearby
|
||||
Sites, and Clear Selected Layers remain focusable while lifecycle work is in
|
||||
progress. They announce busy/disabled semantics and ignore repeat activation
|
||||
until the operation settles, so async work cannot drop the keyboard ring.
|
||||
- Normal-mode Contacts results preserve the focused action or contact by stable
|
||||
identity while live counts, distance order, and pages refresh. If that contact
|
||||
departs or rotates off the visible page, focus moves to a stable continuation
|
||||
point on the named explanatory note at the end of the list and remains there
|
||||
through later repaints. The following Tab proceeds beyond the results instead
|
||||
of restarting at Contacts or silently focusing another contact.
|
||||
- Cockpit Live Signals updates existing contact buttons without replacing or
|
||||
disconnecting the focused one. Tab can continue through the briefing footer
|
||||
to Display and Radio. If the focused contact leaves the list, focus moves
|
||||
once to the current briefing tab; later refreshes do not reclaim it.
|
||||
- Cockpit-only Display and Radio launcher icons show a complete inset keyboard
|
||||
ring in their collapsed and expanded states.
|
||||
- Escape collapses the nearest expanded panel containing focus before any
|
||||
containing panel acts. Closing from panel content returns focus to that panel's
|
||||
disclosure; closing from the disclosure itself clears focus so the collapsed
|
||||
button does not retain its ring. This includes standard panels, nested
|
||||
Parameters, Cockpit Contact and Live Signals, and Cockpit Display/Radio utilities.
|
||||
- The required bottom-left Data attribution control is a named popup button in
|
||||
the Tab order. Enter opens immediately and Space opens on release, then the
|
||||
credit lightbox focuses Close;
|
||||
Close, Escape, or backdrop dismissal restores focus to Data attribution.
|
||||
|
||||
## CCTV launcher and proxy failure responses
|
||||
|
||||
`scripts/dev-cctv.sh` delegates startup to `scripts/dev-fresh.sh`. It retains
|
||||
its Austin source file, Austin preference, 36-camera Austin limit, and 48-camera
|
||||
total limit, with environment overrides. Keys are optional; credential loading
|
||||
and names-only provider provenance follow the normal launcher. The default
|
||||
binding is localhost. An explicit `HOST=0.0.0.0` uses the same LAN warning as
|
||||
normal startup.
|
||||
|
||||
The CelesTrak, Launch Library, terrain-height, and ADSBDB middleware return
|
||||
fixed messages for unexpected failures. Launch Library retains its upstream
|
||||
HTTP failure status and no-store policy but does not forward the upstream body.
|
||||
Existing successful, in-flight, missing-data, and stale-cache behavior remains
|
||||
in place. Failure diagnostics identify the service and, for Launch Library,
|
||||
HTTP status without printing raw exception text or upstream bodies.
|
||||
|
||||
## Map Source keyboard focus
|
||||
|
||||
Keyboard opening focuses the selected map-source tile, falling back to the first
|
||||
only when no source is selected. A bounded retry handles delayed tray visibility.
|
||||
Moving focus away, pointer interaction, closing the tray, or disposing the UI
|
||||
cancels pending work; a later reopening cannot inherit an old focus request.
|
||||
|
||||
## September 8, 2026
|
||||
|
||||
Earthquake refreshes validate the complete feed and construct replacement entities before clearing the previous snapshot. Malformed rows and duplicate rendered IDs retain the last good entities, overlays, count and timestamp and report a malformed response; unknown magnitude is excluded from M2.5+ rendering.
|
||||
|
||||
Non-object or array-valued properties reject the response instead of being treated as an unknown magnitude.
|
||||
|
||||
Launch payloads with missing records now say PAYLOAD DATA UNAVAILABLE. Missing names use Unnamed payload; absent or invalid mass stays unknown instead of appearing as 0 KG.
|
||||
|
||||
Updated: August 24, 2026
|
||||
|
||||
## Aircraft and vessel server modules
|
||||
|
||||
Standalone aircraft routes now live in `server/providers/aircraft/`: OpenSky
|
||||
state vectors and regional fallback, adsb.lol military positions, ADSBDB
|
||||
enrichment and track backfill. Vessel routes and websocket/watchdog setup live
|
||||
in `server/providers/vessels/ais-live.js`; AIS records and recent tracks live
|
||||
in `ais-store.js`. Common response caps, request coalescing and query parsing
|
||||
have their own modules. `server/providers/local.js` composes these with the
|
||||
remaining providers and retains existing named compatibility exports.
|
||||
|
||||
`gods-eye-view/server/providers/live` is a Node-only entry for the existing
|
||||
plugins and shared request helpers. Importing it starts no sockets or timers.
|
||||
The existing aircraft normalizer is separately available through the portable
|
||||
`gods-eye-view/sources/adsb-lol` export. Provider URLs, local credentials, cache
|
||||
policy, fallback behavior, response shapes and rendering remain unchanged.
|
||||
|
||||
|
||||
## Control names for assistive technology
|
||||
|
||||
Scope, Bloom, Sharpen and location search have explicit accessible names.
|
||||
Generated style sliders use the same name as their visible parameter label.
|
||||
The first-run suppression checkbox keeps its native wrapping label, so its
|
||||
accessible name remains "Don't show this again". Control behavior is unchanged.
|
||||
|
||||
## FIRMS source status
|
||||
|
||||
The FIRMS proxy records source success after appending its rows. If aggregation
|
||||
throws, that source reports failure without a contradictory success entry.
|
||||
The existing per-record append continues to support large feeds; sequential
|
||||
fetching, trailing-24-hour filtering and partial-success caching are unchanged.
|
||||
|
||||
## Installations and map-source guidance
|
||||
|
||||
- On an uncached Overpass failure, mapped installations keep their existing
|
||||
@@ -748,7 +1410,7 @@ This is the current runtime/source-of-truth snapshot for the project.
|
||||
> corridor. Layer toggles stay live from there, and collapsing returns the
|
||||
> plain launcher. The map-only Clear, Share, and Reset Globe actions are hidden
|
||||
> for the duration of Cockpit, both as a group and as individual controls.
|
||||
> It uses the `radar` symbol and provides roving keyboard tab navigation. Its action row
|
||||
> It uses the `radar` symbol; both tabs are reachable with Tab and Left/Right arrows switch between them. Its action row
|
||||
> places the single Cockpit entry before Search Nearby Sites. Cockpit removes
|
||||
> the duplicate floating map entry and topline exit; the bottom-center
|
||||
> `EXIT COCKPIT` control (offset downward by a `-95px` bottom margin) plus `Escape`/`C` own exit, with entry/exit focus
|
||||
@@ -934,12 +1596,20 @@ This is the current runtime/source-of-truth snapshot for the project.
|
||||
> settled dim contact always completes its release after tracking ends.
|
||||
> - **Terrain-height resilience:** `/api/terrain/heights` caches canonical
|
||||
> 5-decimal points individually, reconstructs reordered/overlapping batches
|
||||
> in exact request order, and refreshes only missing or stale points. Network,
|
||||
> 429, and 5xx failures receive bounded jittered retries with `Retry-After`;
|
||||
> stale real heights remain usable per point, while an uncached absent height
|
||||
> still returns 502 rather than becoming a fabricated ground value. Client
|
||||
> geoid fallbacks wait 60 seconds before retrying and self-heal to Re:Earth on
|
||||
> the first later successful fetch.
|
||||
> in exact request order, and refreshes only missing or stale points. Upstream
|
||||
> calls and browser requests are both chunked at 64 points, sized to fit
|
||||
> their 30s deadlines across Re:Earth's observed 87-186 ms/point range; a chunk
|
||||
> that still fails contributes nulls for its own positions instead of
|
||||
> discarding the chunks that resolved. Network, 429, and 5xx failures receive
|
||||
> bounded jittered retries with `Retry-After`; stale real heights remain
|
||||
> usable per point, while an uncached absent height still returns 502 rather
|
||||
> than becoming a fabricated ground value. A position the upstream answers
|
||||
> with a null ellipsoid is reported as an absent height rather than a refresh
|
||||
> failure, and is left uncached so a later poll re-asks it. Client geoid
|
||||
> fallbacks wait 60 seconds before retrying and self-heal to Re:Earth on the
|
||||
> first later successful fetch. Smaller chunks reduce timeout risk; complete
|
||||
> camera batches still wait for their sequential requests, and unresolved
|
||||
> placement continues to use the existing prior until real heights arrive.
|
||||
> - **Overpass cache admission:** `/api/overpass` parses and sanitizes requests,
|
||||
> then checks fresh memory, identical in-flight work, and fresh disk entries
|
||||
> before invoking its local 90/min limiter. Cache and single-flight responses
|
||||
@@ -1618,7 +2288,7 @@ its criteria cannot be silently ignored.
|
||||
| Satellites | CelesTrak | `src/data/satellites.js` | `/api/celestrak` | 120s |
|
||||
| Space Missions (30d) | Launch Library 2 + CelesTrak | `src/data/rocketLaunches.js` | `/api/launches` + `/api/celestrak/active` | 5 min |
|
||||
| Traffic | OSM Overpass (+ optional TomTom live flow) | `src/data/traffic.js` | `/api/overpass` + `/api/tomtom` | viewport-driven |
|
||||
| CCTV | Austin + Caltrans (CA) + TfL London Open Data + Street View fallback | `src/data/cctv.js` | `/api/cctv` | 10s (active) |
|
||||
| CCTV | Austin + Caltrans (CA) + TfL London + Ontario 511 + Fintraffic (FI) + DriveBC (BC) + TxDOT (TX) + Estonia (Tallinn, Tarktee) + Live Traffic NSW Open Data + Street View fallback | `src/data/cctv.js` | `/api/cctv` | 10s (active) |
|
||||
| Radio | Radio Browser (public-domain station directory) | `src/data/radio.js` | `/api/radio/stations`, `/api/radio/click/:uuid` | 45 min directory refresh |
|
||||
| Bikeshare 🚲 | GBFS (Lyft + BCycle) | `src/data/bikeshare.js` | `/api/gbfs` | 60s |
|
||||
| Datacenters ▣ | OSM extract (bundled) | `src/data/localLayers.js` | — | static |
|
||||
@@ -1684,9 +2354,11 @@ preserves object identity for an idempotent repeat of the same generation, and
|
||||
degrades without replacement if a fresh response presents an older generation.
|
||||
Snapshot records mark community metadata as untrusted, and Radio tool results
|
||||
omit station names so directory text never becomes model instruction context.
|
||||
One bounded country parser maps recognized ISO codes and English/common names
|
||||
through proxy metadata and final station selection, while malformed, non-ISO,
|
||||
control-containing, and oversized inputs fail closed. Literal or resolved
|
||||
One bounded country parser maps recognized ISO codes and English/common names —
|
||||
including widely used exonyms the Intl display label omits (Turkey, Holland,
|
||||
Burma, and similar) — through proxy metadata and final station selection, while
|
||||
malformed, non-ISO, control-containing, ambiguous, and oversized inputs fail
|
||||
closed. Literal or resolved
|
||||
non-global IPv4/IPv6 targets are refused. Destroy fully releases the Radio audio
|
||||
session, voice ducking/restoration, request state, filter, selection, volume,
|
||||
accepted snapshot, and feed telemetry before re-initialization; monotonic
|
||||
@@ -1967,7 +2639,16 @@ silently demoting every later lookup for the session.
|
||||
default 36 → 250, hard bound 300), filtered to `camera_status === TURNED_ON` (~815 live of
|
||||
1,003 rows). City packs (2026-07-04): Caltrans (districts 4/7/11/3 — SF, LA, San Diego,
|
||||
Sacramento; cap 300) and TfL London JamCams (cap 250) join Austin (cap 250) as keyless default
|
||||
sources — ~800 cameras total, all RAW PRIOR poses, stills-first.
|
||||
sources. Ontario 511 (2026-09-12) adds keyless highway cameras including Kitchener-area routes
|
||||
(cap 1,000, all enabled rows from the current ~944-camera catalog). All sources are RAW PRIOR
|
||||
poses, and the layer is stills-first.
|
||||
sources. Fintraffic Finland road weather cameras (2026-09-13; cap 300, `CCTV_FINTRAFFIC_MAX_SOURCES`,
|
||||
kill switch `CCTV_FINTRAFFIC_ENABLED=0`) are the fourth pack: one keyless GeoJSON station list
|
||||
covering the whole country, where one *preset* (a station's fixed view) is one camera — 806
|
||||
GATHERING stations carry 2,256 in-collection presets, prioritized to 300 against seven anchors
|
||||
on the main road spine. `CCTV_MAX_SOURCES` is a 4,000 catalog-wide ceiling shared round-robin
|
||||
across packs, so a lower global cap thins every region instead of starving the last pack.
|
||||
~1,100 cameras total, all RAW PRIOR poses, stills-first.
|
||||
- **CCTV v3 UX — viewshed + calibration gizmo** (built 2026-07-05 and field
|
||||
validated 2026-07-21): the COVERAGE toggle is a
|
||||
tri-state cycle `OFF → ON → VIEWSHED`; viewshed mode renders each visible camera's frustum
|
||||
@@ -2000,7 +2681,8 @@ silently demoting every later lookup for the session.
|
||||
2026-08-02): the LOD-selected nearby static cameras (20/28/40 by zoom,
|
||||
`cctvLod.js`) get **screen-space thumbnail cards** through the shared world-overlay host
|
||||
showing paced static frames — reselection on `camera.moveEnd` only, at most one frame fetch
|
||||
per second layer-wide, per-source cadences (Austin 5 min, TfL/Caltrans 3 min). Zero-flicker:
|
||||
per second layer-wide, per-source cadences (Austin 5 min, TfL/Caltrans 3 min, Fintraffic 10 min
|
||||
— its stations publish on a 600 s collection interval). Zero-flicker:
|
||||
a card renders nothing until its first frame, a drawn frame persists through failed fetches,
|
||||
and eviction grace (2-pass/5 s) stops budget-edge churn. Camera icons stay visible at every
|
||||
zoom. Eligible candidates are filtered to in-view stills with valid IDs,
|
||||
@@ -2200,6 +2882,29 @@ silently demoting every later lookup for the session.
|
||||
- Input is the live basemap label context (place/street/nearby-place labels + enabled layers) — the model is instructed not to infer from coordinates.
|
||||
- Output is sanitized to exactly five words; falls back to the deterministic telemetry summary on error/timeout (5s abort); typewriter animation on update.
|
||||
|
||||
### Place-search providers
|
||||
|
||||
Location search/fly-to, annotations and Radio location lookup receive one
|
||||
`placeSearch.geocode(query, { bias, signal })` service. `src/standalone` composes
|
||||
Google first when configured and Photon/OpenStreetMap as fallback, including
|
||||
Google transport failures or declined requests. The portable `./search` export
|
||||
provides the service and adapters; it reads no environment or application state.
|
||||
Existing browser/server key setup is unchanged.
|
||||
|
||||
Providers normalize coordinates, canonical name, label, place types and optional
|
||||
bounds. Camera framing, nearby landmark recovery and footprint selection remain
|
||||
in their consumers, including the Capitol identity/containment safeguards.
|
||||
Radio keeps localized country names in labels rather than station filters.
|
||||
Reverse geocoding and nearby/text-search endpoints retain their existing behavior.
|
||||
|
||||
Only valid answers and definitive misses enter bounded caches; malformed replies,
|
||||
HTTP refusals and outages remain retryable. Searches share a 12-second total
|
||||
deadline, with Photon requests capped at six seconds each. Caller/application
|
||||
cancellation stops retries and late cache writes. Replacing a location search
|
||||
cancels the previous lookup; disposing its controls cancels the active lookup. Photon uses a soft proximity bias, up to five
|
||||
candidates, and an unbiased retry for name mismatches. Invalid/wrapped bounds
|
||||
are omitted rather than framing the wrong part of the globe.
|
||||
|
||||
### Map Stack Switcher (June 2026)
|
||||
|
||||
- `src/mapStackController.js` switches between Google Photorealistic 3D (`photoreal`, the default when a Google or ion key is present), keyless Esri World Imagery (the zero-key default landing, with keyless terrain), Bing Aerial / Aerial-with-Labels via Cesium ion world imagery (require `CESIUM_ION_TOKEN`), and OSM tile fallback. Bing Road is **retired**: it is gone from `MAP_STACKS`, from the `set_map_stack` enum, and from the voice aliases (road phrasings now resolve to OSM, the one shipped road basemap). An old `map=bing-road` link is simply an unknown id and takes `setStack()`'s existing photoreal fallback with the Google 3D tile lit — pinned live in `scripts/qa-map-source-tray.mjs`.
|
||||
@@ -2298,7 +3003,7 @@ silently demoting every later lookup for the session.
|
||||
eight-second timeout; the timer is cleared on every success or failure path.
|
||||
- OpenSky response cache stores successful upstream responses only; OAuth token refresh calls are coalesced.
|
||||
- A cold OpenSky failure uses the current camera subpoint only to request a cached adsb.lol point fallback capped at 250 nm. A fresh OpenSky response or last-good cache wins; a nominally successful worldwide snapshot more than two minutes old prefers viewport-scoped adsb.lol when available, otherwise the stale source is reported honestly. The fallback is visibly source-labeled and is never presented as a worldwide snapshot.
|
||||
- GBFS response size is capped; CCTV health map is bounded.
|
||||
- GBFS proxy refuses upstream redirects (`redirect: 'manual'`; any 3xx becomes a 502 and the redirect target is logged server-side only) and enforces its 5 MB response cap while the body streams, cancelling the upstream read past the cap; CCTV health map is bounded.
|
||||
- Proxy error payloads are sanitized (no internal error details returned to clients).
|
||||
- `OPENAI_API_KEY` is server-side only; the browser receives ephemeral Realtime client secrets from `/api/realtime/token`.
|
||||
- `AISSTREAM_API_KEY` is server-side only; the browser reads the same-origin `/api/ais-live` cache.
|
||||
@@ -2611,3 +3316,71 @@ Replay transport uses one Play/Pause toggle plus Cancel. During ascent only the
|
||||
## Maintenance Rule
|
||||
|
||||
When runtime behavior or architecture changes, update this file in the same change set as code updates.
|
||||
|
||||
## Dependency security baseline
|
||||
|
||||
The lockfile uses DOMPurify 3.4.15, protobufjs 8.8.0, PostCSS 8.5.28, and
|
||||
nanoid 3.3.19. Cesium remains on 1.138.0. Browser QA uses Puppeteer 25.10.0;
|
||||
image-processing tools use Sharp 0.35.4. QA scripts await Puppeteer's asynchronous
|
||||
executable-path lookup before testing or passing the path to Chrome. Supported Node versions remain
|
||||
24.14.x and 26.x. Use `npm ci` to reproduce the checked-in dependency tree.
|
||||
|
||||
### Traffic city navigation
|
||||
|
||||
Traffic checks the final camera view on arrival and retries a failed road request
|
||||
while the camera is stationary, backing off from 1.5 to 30 seconds. Failed road
|
||||
requests report an unavailable source. Leaving the traffic altitude range or
|
||||
disabling the layer cancels pending work; superseded road and flow requests cannot
|
||||
release the current request or keep its loading indicator active.
|
||||
|
||||
### Optional frame-rate readout
|
||||
|
||||
Backtick (`) toggles an FPS readout beneath the title logo. It counts actual
|
||||
Cesium post-render events over one-second windows and does not request extra
|
||||
frames. Typing fields, modified keys and key repeats do not toggle it. The
|
||||
readout starts hidden each session and releases its timer and frame listener
|
||||
when hidden or when the application is disposed.
|
||||
|
||||
|
||||
## Radio components
|
||||
|
||||
The radio entry composes one layer from directory ingestion, station queries,
|
||||
selection, globe rendering and playback modules. Its source supplies directory
|
||||
metadata and click reporting; scene, ground and overlay services are provided
|
||||
explicitly. Each constructed layer owns its catalog, audio and lifecycle state.
|
||||
Existing catalog validation, category filters, tuning and voice playback behavior
|
||||
remain unchanged. Audio connects directly to the broadcaster after an explicit
|
||||
play action; the source does not relay or record streams.
|
||||
|
||||
## Bundled geography and submarine cable components
|
||||
|
||||
Submarine cables use separate source, geometry, rendering, interaction and
|
||||
lifecycle modules. The layer factory accepts cable and landing-point GeoJSON
|
||||
collections from a source with `fetch(signal)` and a display label. The default
|
||||
source loads the same bundled TeleGeography files. Disabling still removes all
|
||||
three Cesium data sources; enabling rebuilds from the accepted parsed cache,
|
||||
and destroying clears it. Load ownership prevents cancelled work from adding
|
||||
entities after teardown.
|
||||
|
||||
Natural Earth regions and neighborhood polygon lookup are package exports.
|
||||
Their existing lazy loaders, retry behavior, bundled datasets and attribution
|
||||
are unchanged. The cable dataset remains CC BY-NC-SA 3.0 and is not covered by
|
||||
the project's MIT license; see `DATA_SOURCES.md`.
|
||||
|
||||
## Map source factories and coordination
|
||||
|
||||
Map selection is composed from separate imagery, terrain and 3D factories.
|
||||
The default registry retains Google 3D, Bing Aerial/Labels, Esri Satellite and
|
||||
OSM, including their setup guidance and existing preset/share IDs. Esri still
|
||||
falls back to OSM on construction failure or two active tile failures, and
|
||||
credits follow the source actually displayed. Terrain remains lazy while the
|
||||
photoreal globe is hidden.
|
||||
|
||||
Map credentials are passed to each source constructor rather than changing SDK-wide Google or ion defaults.
|
||||
|
||||
The controller accepts other source registries without adding provider branches.
|
||||
Each instance caches source construction, ignores superseded scene changes and
|
||||
releases imagery layers/listeners on replacement. Destroy invalidates pending
|
||||
work and releases owned resources, including late factory results. Supplied 3D
|
||||
tilesets remain owned by the caller; tilesets created through the controller's
|
||||
factory are added to its viewer and removed on destruction.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Reusing infrastructure layers
|
||||
|
||||
`gods-eye-view/infrastructure` exports `createInfrastructureLayers(services)`.
|
||||
It returns fresh datacenter and dam layers in that order, with the existing IDs,
|
||||
appearance, label budgets and bundled public datasets. Importing the module or
|
||||
calling the factory does not load data, create a viewer, or start the application.
|
||||
The asset URLs resolve relative to the module; Vite rewrites them for production
|
||||
base paths. This browser source export expects a Vite-compatible asset build.
|
||||
|
||||
Pass the application's existing functions:
|
||||
|
||||
```js
|
||||
import { createInfrastructureLayers } from 'gods-eye-view/infrastructure';
|
||||
|
||||
const layers = createInfrastructureLayers({
|
||||
overlayHost: { setEntries, setVisible, clearSource },
|
||||
registerEntityContext,
|
||||
selectEntityContext,
|
||||
clearSelectedEntityContextForLayer,
|
||||
removeEntityContextsForLayer,
|
||||
governorRequestRender,
|
||||
});
|
||||
|
||||
// Register these layers with the existing data-layer manager and viewer.
|
||||
```
|
||||
|
||||
| Function | Arguments / responsibility |
|
||||
| --- | --- |
|
||||
| `overlayHost.setEntries` | `(sourceId, entries, options)`; publish the existing infrastructure overlay records and paint budget |
|
||||
| `overlayHost.setVisible` | `(sourceId, visible)`; toggle a source |
|
||||
| `overlayHost.clearSource` | `(sourceId)`; remove that source's overlay entries |
|
||||
| `registerEntityContext` | `(entity, metadata)`; register selectable feature metadata, including the owning layer and data source |
|
||||
| `selectEntityContext` | `(entity)`; select that registered feature |
|
||||
| `clearSelectedEntityContextForLayer` | `(layerId)`; clear selection only if owned by this layer |
|
||||
| `removeEntityContextsForLayer` | `(layerId)`; remove records owned by the layer on destruction or failed setup |
|
||||
| `governorRequestRender` | `(reason)`; request a frame through the existing render scheduler |
|
||||
|
||||
Each returned layer supports `init(viewer)`, `enable(viewer)`, `disable(viewer)`,
|
||||
`update(viewer)`, `destroy(viewer)`, `getStats()` and `getLodDiagnostics()`.
|
||||
Use the same viewer for the instance's entire lifetime. Each viewer/context/overlay
|
||||
host permits one live instance per layer ID; destroy an old instance before
|
||||
replacing it. Separate applications may use identical IDs with separate hosts.
|
||||
Callbacks must be ready before enable and remain usable through destruction.
|
||||
|
||||
Disable retains the loaded dataset for reuse and clears selection and listeners.
|
||||
Concurrent enables share one load. Destroy is permanent, aborts pending fetches,
|
||||
discards late results, and clears the owned data source, context records, overlays,
|
||||
input handler and listeners. The layer never creates an application context store,
|
||||
overlay host, viewer, or render scheduler. The consumer must resolve one compatible
|
||||
Cesium installation shared with its viewer; it must not bundle separate copies.
|
||||
|
||||
`gods-eye-view/infrastructure/geojson` exports the lower-level
|
||||
`createLocalGeoJsonLayer(options, services)` and existing infrastructure overlay
|
||||
helpers. `gods-eye-view/infrastructure/lod` exports the existing LOD policy helpers.
|
||||
The standalone app's `src/data/localGeojson.js` keeps its original single-argument
|
||||
factory and supplies its existing functions. Other consumers should use the package
|
||||
exports, which do not import standalone application globals.
|
||||
|
||||
Dataset files and source/license notices remain under `src/data/local_data/`.
|
||||
Their input counts are 4,351 datacenter features and 704 dam features. Cesium may
|
||||
expand multipart geometries into multiple entities; entity and stem counts are
|
||||
different measurements. This change does not refresh or relicense the datasets.
|
||||
Reference in new issue
Block a user