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:
German Khokhlov committed 2026-11-07 16:06:43 +04:00
1 parent 656943641c
commit 52c6f68bd5
31 files changed
+1145 -208

No files matched your search

+40 -3
View File
@@ -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
View File
@@ -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
+66 -4
View File
@@ -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.
+40 -23
View File
@@ -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.