mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-16 16:22:20 +00:00
Enforce engine SDK boundaries and rehearse every layer display
Restrict runtime SDK imports to their engine directories, including package subpaths, re-exports and dynamic imports. Keep three measured, reasoned exceptions for the Bhote Koshi property-record models and reject stale exceptions. Move the Cesium annotation renderers and both wind adapters to their engine folders, preserving their implementations and lazy loading. Load all 35 manifest display entries on a fake engine with an unknown kind and no native extensions. Draw small fixtures and verify resource and subscription cleanup before destroying the engine. Name the three entries without display factories as skips. Update the architecture, infrastructure lifecycle and engine integration documentation to describe the code today. Cesium behavior is unchanged, and Navara keeps its existing behavior. The weather comparison harness supplies the Navara flow-mesh factory and accepts the previous backend location for comparison runs. No user-visible strings change. Cesium layer-renderer lines fall from 14 to 0, Navara layer-renderer lines from 314 to 189, outside-engine Cesium import files from 5 to 3, viewer lines from 933 to 910, extension reads from 4 to 3, and engine-name lines from 36 to 33. No coupling count grows. Targeted checks pass: 845 tests, three named rehearsal skips. Import directions, package boundaries, formatting and syntax checks pass. Checked in the browser, keyless: the contract suite passes on Navara and on Cesium apart from the camera-events check that also fails intermittently before; Navara annotations pass across engine switches; the ground-look comparison is pixel-identical. qa-draw-tool's hidden-line check and the wind engine switch fail the same way before this change.
This commit is contained in:
1 parent
656943641c
commit
52c6f68bd5
31 files changed
+1145
-208
No files matched your search
+40
-3
@@ -30,7 +30,7 @@ export inventory. Use declared exports rather than reaching into internal files.
|
||||
| `src/standalone/` | Select the default catalog, local sources and setup controls |
|
||||
| `src/ui/` | Navigation generations, restoration, visual state, panel snapshots and their subscriptions |
|
||||
| `src/data/` | Lifecycle, context and feed state; legacy default-layer facades |
|
||||
| `src/layers/<family>/` | Source acquisition, records and Cesium resources with explicit controller/renderer owners |
|
||||
| `src/layers/<family>/` | Source acquisition, records and shared contract displays with explicit lifecycle owners |
|
||||
| `src/sources/` | Portable protocols and source contracts; request state belongs to each factory instance |
|
||||
| `src/geo/` | Engine-neutral WGS84 maths, ported from Cesium, never imports Cesium |
|
||||
| `src/globe/` | Engine-neutral globe contract and its test support; engines only in `globe/cesium`, `globe/navara` |
|
||||
@@ -77,6 +77,24 @@ Navara stays out of the Cesium-mode bundle. Common voice controls cannot depend
|
||||
Realtime protocol implementation. Negative fixtures cover indirect helpers,
|
||||
self-package imports, symlinks and unreachable files.
|
||||
|
||||
Runtime SDK imports are restricted by directory, including unreachable modules:
|
||||
`cesium` and `@cesium/*` belong in `src/globe/cesium/`; `three`,
|
||||
`postprocessing` and `@navaramap/*` belong in `src/globe/navara/`. Package
|
||||
subpaths, re-exports and literal dynamic imports obey the same rule. Tests and
|
||||
Node test support retain their existing exemptions. The production script
|
||||
loader is `src/app/loadCesium.js`; it imports no SDK package and needs no
|
||||
exception. There is no blanket exception for layer `render/` directories.
|
||||
|
||||
The temporary `engineImportExceptions` list in `scripts/package-boundaries.json`
|
||||
contains exact file/package pairs with reasons. The checker reports the used
|
||||
entries and rejects duplicates, missing reasons and unused entries. Its three
|
||||
exceptions are the Bhote Koshi event, locator and embedded-media models in
|
||||
`src/data/`, which still construct Cesium property records. Their drawing uses
|
||||
shared displays. Exceptions do not relax the portable, contract or cross-engine
|
||||
graph checks. Cesium annotation renderers live in `src/globe/cesium/annotations/`;
|
||||
wind backend adapters live in their engine folders. Wind's older injected-SDK
|
||||
helpers and the remaining annotation migration are separate debt.
|
||||
|
||||
Source-only factories use dedicated `layers/<family>/source` exports where
|
||||
available, preserving the same factory implementation without loading rendering.
|
||||
Record normalization and endpoint policies have plain owners separate from
|
||||
@@ -560,12 +578,22 @@ services into each family factory. Standalone provider selection lives in
|
||||
`src/standalone/layerSources.js`. The construction export has its own checked
|
||||
dependency graph, excluding standalone setup and compatibility layer instances.
|
||||
|
||||
`src/app/layers/renderers.js` is the layer manifest. Its lazy display loaders
|
||||
resolve the shared factories exported by `displays.js`; `needs` names required
|
||||
contract primitives. The only display backend options are wind streamlines,
|
||||
loaded from the engine folders. A missing wind backend leaves the raster field
|
||||
available. Wildlife Sightings draws itself through the contract; Sea Marks and
|
||||
Ski Pistes use their overlay controller. No layer display imports an engine SDK.
|
||||
`displayRehearsal.test.mjs` loads every manifest display on the fake engine with
|
||||
an unknown kind and no extensions, draws a small fixture and checks cleanup.
|
||||
|
||||
Both aircraft layers share the catalog's classification registry; launches use
|
||||
its satellites and Contacts uses its aircraft, vessels and installations. Data
|
||||
registration, controls and voice actions read those same instances. Destruction
|
||||
remains the manager's responsibility; classification also observes application
|
||||
abort when startup has not reached registration. Scene engines remain page-owned,
|
||||
so this change does not introduce multiple simultaneous viewers.
|
||||
abort when startup has not reached registration. The session retains models while
|
||||
scene attachment builds displays on the active engine. A parked engine can remain
|
||||
allocated for a warm switch; its layer drawing is detached.
|
||||
|
||||
Direct `src/data` compatibility entries retain their old defaults and testing
|
||||
exports. Browser regression probes use the registered instance's testing surface
|
||||
@@ -604,6 +632,15 @@ listener cleanup. Application data assembly constructs both owners explicitly;
|
||||
`data/manager` is the compatibility facade for direct callers. The ordinary
|
||||
state subscriptions retain their existing event contract.
|
||||
|
||||
`data/layerSceneBinding.js` owns renderer attach/detach, asynchronous settlement,
|
||||
parking and failed-release retries. Lifecycle keeps visibility intentions and
|
||||
refresh policy. `app/layerSession.js` defines the retained session fields and
|
||||
handoff predicate. `standalone/sceneSwitcher.js` coordinates page handoff;
|
||||
`ui/shellScene.js` owns scene-bound shell construction, while `applicationShell`
|
||||
keeps page controls and policy. Request, host and shell queues are not yet one
|
||||
queue. Overlay, render-governor, tracked-readout and pick services still include
|
||||
module singletons; debug access still exposes the native viewer and tileset.
|
||||
|
||||
## UI state owners
|
||||
|
||||
- `ui/navigation` owns navigation generations, pending search presentation and
|
||||
|
||||
+22
-12
@@ -260,25 +260,34 @@ one application, and only the globe-bound parts move to the next engine.
|
||||
ground passes, Cesium SDK loads and `ScreenSpaceEventHandler` users.
|
||||
`scripts/engineCoupling.test.mjs` (in `npm test`) fails when a count grows
|
||||
past `scripts/engine-coupling-baseline.json`.
|
||||
- **SDK boundary and display rehearsal.** The import-direction gate permits
|
||||
Cesium packages only in `src/globe/cesium/` and three, postprocessing and
|
||||
Navara packages only in `src/globe/navara/`. The measured temporary exceptions
|
||||
in `scripts/package-boundaries.json` are the three Bhote Koshi model modules:
|
||||
event, locator and embedded media still build Cesium property records. The
|
||||
gate rejects unused exceptions. `src/app/layers/displayRehearsal.test.mjs`
|
||||
loads all 35 display entries from the manifest on a fake engine with an
|
||||
unknown kind and no native extensions, draws fixtures, hides or releases them,
|
||||
and checks primitives, subscriptions and service records before engine
|
||||
destruction. The three self-drawing entries are named skips. This is a
|
||||
display-level rehearsal; application kind registration, scene-service
|
||||
singletons, queue consolidation and native debug access remain work.
|
||||
- **The session owns the state.** Catalog, layer models, sources, selection,
|
||||
camera mode and URL state outlive a switch. A layer that is a session model
|
||||
gets `attachRenderer(engine)` / `detachRenderer()` instead of being rebuilt,
|
||||
gets `attachRenderer(viewer, { engine })` / `detachRenderer()` instead of being rebuilt,
|
||||
so its data is not fetched again. The outgoing globe is parked
|
||||
(`src/standalone/rendererCache.js`), so switching back within three minutes
|
||||
is warm (60-90 ms). After that the parked globe is disposed and its WebGL
|
||||
context lost, which frees about 1.1 GiB for a parked Navara; switching back
|
||||
then builds it cold (1.5-2 s). `?parkedMs=` shortens the delay for QA
|
||||
(`scripts/qa-strict-parked-release.mjs`).
|
||||
- **Renderers per engine.** Each layer keeps its model and display policy in
|
||||
engine-neutral files and draws through `render/cesium*.js` or
|
||||
`render/navara*.js`, or through one `render/display.js` that runs on every
|
||||
engine over the globe contract: the aircraft family (flights, military and
|
||||
local ADS-B) through `src/layers/aircraft/render/display.js`, and AIS
|
||||
vessels, satellites, Space Missions, ALPR, bikeshare, OSM Places,
|
||||
Wildlife Sightings, radio, transit, CCTV, earthquakes, air quality, GNSS
|
||||
Integrity, fire perimeters, Prohibited & Restricted Airspace, Active Fires,
|
||||
S2 GhostMaps, cyclone advisories, submarine cables, Mapped Installations,
|
||||
Global Context, datacenters and dams through their own `render/display.js`;
|
||||
- **Shared layer displays.** Every manifest display draws through the globe
|
||||
contract from `render/display.js`; the aircraft family shares its display
|
||||
implementation. There are 35 display entries (including the three weather
|
||||
products and two infrastructure datasets). Wildlife Sightings draws through
|
||||
the contract inside its layer; Sea Marks and Ski Pistes use their overlay
|
||||
controller. Wind streamlines retain backend adapters in
|
||||
`src/globe/cesium/windFlow.js` and `src/globe/navara/windFlow.js`;
|
||||
the fills of the ground layers, installation outlines and the selection fill
|
||||
are `engine.ground` sets. Global Context's range pulses use
|
||||
`engine.ground.createPulseField`: the same fronts, halos, inward bands,
|
||||
@@ -295,7 +304,8 @@ one application, and only the globe-bound parts move to the next engine.
|
||||
backend per engine. Data packs share `src/scenes/dataPacks/display.js`:
|
||||
movers, lines and world meshes retain authored heights, polygon holes,
|
||||
images and picking across scene detach and reattach. Annotation drapes
|
||||
remain on their existing renderers pending bounded classification support.
|
||||
remain on their existing renderers pending bounded classification support;
|
||||
the Cesium implementations live in `src/globe/cesium/annotations/`.
|
||||
- **One layer manifest.** `LAYER_MANIFEST` in `src/app/layers/renderers.js`
|
||||
says how each directory layer draws: its display with the contract
|
||||
primitives it needs (and an engine-specific backend option keyed by engine
|
||||
|
||||
@@ -489,8 +489,9 @@ near the camera from one 8×8 atlas over the whole view.
|
||||
the globe at order 20, faded with the camera's height while streamlines
|
||||
draw, raised at 5 km on 3D tiles. The streamlines stay each engine's,
|
||||
behind the display's `flow` backend, loaded by the manifest:
|
||||
`render/cesiumFlow.js` supplies Cesium's streamlines (`rendering.js`),
|
||||
and `render/navaraFlow.js` supplies Navara's flow mesh.
|
||||
`src/globe/cesium/windFlow.js` supplies Cesium's streamlines
|
||||
(`src/layers/wind/rendering.js`), and `src/globe/navara/windFlow.js`
|
||||
supplies Navara's flow mesh.
|
||||
- **The Bhote Koshi event imagery** (`src/layers/bhoteKoshi/render/display.js`):
|
||||
two `url` images over the event's rectangle at alpha 0.96, split left
|
||||
and right at the engine's split position, order 15. The event's and the
|
||||
@@ -587,8 +588,8 @@ culling and no depth writes. Colour, image and visibility changes retain the
|
||||
primitive; geometry, pick-id and depth-test changes replace it. The engine
|
||||
requests frames while the primitive or its image is preparing. Navara draws
|
||||
local coordinates relative to a double-precision world origin in its
|
||||
scene pass, with scene depth and triangle picking. Its meshes receive the
|
||||
scene effects, as Cesium primitives do.
|
||||
transparent scene pass after tone mapping, with scene depth and triangle
|
||||
picking. Their authored colours are blended in display space.
|
||||
Both engines own geometry, material and texture disposal. The fake engine
|
||||
keeps the same state and tests triangle intersections for picks.
|
||||
|
||||
@@ -633,3 +634,64 @@ uses the selected colour as well as the visible band. Finished geometry still
|
||||
goes through the annotation board. Detaching the scene releases the claim,
|
||||
listeners and preview while retaining the chosen shape and colour. The
|
||||
page's pointer lease still arbitrates Draw against other tools.
|
||||
|
||||
## How to add an engine
|
||||
|
||||
Put the implementation in a new `src/globe/<name>/` folder. Keep SDK classes,
|
||||
shaders, resource disposal and SDK workarounds there. Use
|
||||
`src/globe/testing/fakeEngine.js` as the contract model, and
|
||||
`src/globe/contract.js` as the authoritative member and data-shape reference.
|
||||
Coordinates, colours, picks and display options crossing the boundary are plain
|
||||
data; displays do not receive native viewers or SDK types.
|
||||
|
||||
Implement the required host, camera, picker, projector, frame, render, surface,
|
||||
input, credit, clock and map interfaces, plus all five drawing primitives:
|
||||
`movers`, `lines`, `ground`, `imagery` and `meshes`. `engineCapabilities(engine)`
|
||||
reports these and the optional visualStyles, bloom, cloudCover and contactSonar
|
||||
groups. An optional group must be complete or absent. Do not advertise a
|
||||
capability with a no-op implementation. Match Cesium's behavior where the
|
||||
contract permits both engines to implement it.
|
||||
|
||||
Run `createContractSuite(engine, { waitFrames, ... })` from
|
||||
`src/globe/testing/contractSuite.mjs`. Supply real pointer delivery, canvases and
|
||||
pixel reads for browser checks; keep the fake-engine tests as fast contract
|
||||
checks. Test ownership and repeated destruction as well as visible output.
|
||||
The browser harness is `scripts/qa-contract-suite.mjs`; ground and imagery pixel
|
||||
checks also run through `scripts/qa-ground-suite.mjs`.
|
||||
|
||||
The application currently registers two kinds: adding another still requires
|
||||
registration in `ENGINE_KINDS`, scene construction/choice and the corresponding
|
||||
QA harnesses. `assertGlobeEngine` currently validates that registration. The
|
||||
folder and passing contract suite are the implementation boundary, not a claim
|
||||
that arbitrary engine folders are auto-discovered today. Layers and their
|
||||
fixtures should need no new drawing implementation.
|
||||
|
||||
The layer manifest (`src/app/layers/renderers.js`) loads shared displays and
|
||||
lists their `needs`. Today every valid engine must implement all five
|
||||
primitives; availability is checked against the registered kind's primitive
|
||||
list. `backends` supplies optional engine-specific display options, currently
|
||||
only wind's `flow`. Load a backend dynamically from its engine folder. A new
|
||||
engine can omit wind streamlines and still draw the shared raster field. Do not
|
||||
copy another engine's extensions into a new engine. The self-drawing map overlay
|
||||
entries currently list supported kinds explicitly and need registration too.
|
||||
|
||||
Run `src/app/layers/displayRehearsal.test.mjs`: it loads every manifest display
|
||||
on the fake engine with an unknown kind and empty extensions. Its small fixtures
|
||||
exercise attachment, drawing, hiding or release, and destruction; primitive
|
||||
registries, frame/camera/input subscriptions, follow state and service records
|
||||
must be clean before the engine itself is destroyed. New display entries need a
|
||||
fixture. Wildlife Sightings and the two map overlays are explicit skips because
|
||||
they have no display factory; their layer tests remain the coverage for those
|
||||
controllers. Native wind streamlines, DOM rasterization and GPU pixels are not
|
||||
covered by this rehearsal.
|
||||
|
||||
`node scripts/check-import-directions.mjs` enforces SDK ownership for static
|
||||
imports, re-exports and literal dynamic imports, including package subpaths.
|
||||
Cesium packages belong in `src/globe/cesium/`; three, postprocessing and Navara
|
||||
packages belong in `src/globe/navara/`. Add the new SDK's ownership rule when
|
||||
registering it. Contract graphs cannot reach any engine, and the existing
|
||||
engines cannot reach one another. The temporary exact file/package exceptions
|
||||
in `scripts/package-boundaries.json` must have reasons and must still be used;
|
||||
the checker prints them. They are migration debt, not a pattern for new layers.
|
||||
Run package boundaries, formatting, the full unit suite and the coupling report
|
||||
as well; engine coupling counts may not grow.
|
||||
@@ -3,7 +3,7 @@
|
||||
`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.
|
||||
calling the factory does not load data, create an engine, 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.
|
||||
|
||||
@@ -21,7 +21,13 @@ const layers = createInfrastructureLayers({
|
||||
governorRequestRender,
|
||||
});
|
||||
|
||||
// Register these layers with the existing data-layer manager and viewer.
|
||||
// Attach each layer to the current engine, then enable it when requested.
|
||||
for (const layer of layers) layer.init(null, { engine });
|
||||
await layers[0].enable();
|
||||
|
||||
// On a scene switch, keep the parsed data and replace only its display.
|
||||
for (const layer of layers) layer.detachRenderer();
|
||||
for (const layer of layers) await layer.attachRenderer(null, { engine: nextEngine });
|
||||
```
|
||||
|
||||
| Function | Arguments / responsibility |
|
||||
@@ -35,28 +41,39 @@ const layers = createInfrastructureLayers({
|
||||
| `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()`, `getLodDiagnostics()` and
|
||||
`getAnalystRecords()`.
|
||||
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.
|
||||
Each returned session layer supports `init(null, { engine })`,
|
||||
`attachRenderer(null, { engine, signal })`, `detachRenderer()`, `enable()`,
|
||||
`disable()`, `update()`, `destroy()`, `getStats()`, `getLodDiagnostics()` and
|
||||
`getAnalystRecords(limit)`. The first argument is retained for lifecycle
|
||||
compatibility; drawing uses the engine passed in the options. Attach once per
|
||||
scene, detach before attaching another engine, and destroy when the session ends.
|
||||
Separate applications may use identical IDs with separate context/overlay hosts.
|
||||
Callbacks must 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.
|
||||
`src/layers/infrastructure/index.js` owns the parsed dataset, shared in-flight
|
||||
load, enabled intention and selection across scene switches. Enable loads on
|
||||
first use. Disable hides the drawing and clears selection but retains parsed
|
||||
data. Detach destroys scene resources and retains the dataset and selected ID;
|
||||
reattach redraws enabled data and restores selection when no other selection
|
||||
owns the context. The attachment signal cancels that scene's wait, not the
|
||||
session's fetch. Destroy aborts the fetch, discards late results and releases
|
||||
both data and drawing.
|
||||
|
||||
`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.
|
||||
Consumers use the package exports, which do not import standalone application
|
||||
globals.
|
||||
`src/layers/infrastructure/render/display.js` draws the same records on every
|
||||
engine: point movers for tips and pins, lines for stems, ground polygons for
|
||||
footprints and ground corridors for paths. It owns the LOD walk, surface-height
|
||||
refresh, picks, context handles and overlay publications. Destruction releases
|
||||
its primitives and frame, camera and input subscriptions. The layer never
|
||||
creates an overlay host, engine or render scheduler and does not import Cesium.
|
||||
|
||||
`gods-eye-view/infrastructure/geojson` exports the overlay publication,
|
||||
selection, label and error helpers in `src/data/localGeojsonCore.js`; it no
|
||||
longer exports `createLocalGeoJsonLayer`. `gods-eye-view/infrastructure/lod`
|
||||
exports the LOD policy helpers. The package exports do not import standalone
|
||||
application globals.
|
||||
|
||||
Dataset files and source/license notices remain under `src/data/local_data/`.
|
||||
Their input counts are 4,352 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.
|
||||
Their input counts are 4,352 datacenter features and 704 dam features. The session
|
||||
splits multipart geometries using Cesium's stable repeated-id suffixes on every
|
||||
engine. Feature, mover and stem counts are different measurements. These files
|
||||
and licenses are independent of the renderer implementation.
|
||||
Reference in new issue
Block a user