Scope world overlays to each scene attachment

Move the world overlay into scene.services.overlay. Each attachment owns its
sources, collision domains, paint lanes, canvases, observers, timers and
accessible action subscribers. Keep both canvases inside the engine container,
with detection beside the card root so its screen blend still reaches the
scene. Release shared font measurements only after the last host detaches.

Resolve retained layer publications against their attached engine, clear the
outgoing source before releasing its renderer, and reconnect the shell's action
subscription on attachment. Keep destroyed hosts inert and give parked engines
fresh services. Bind annotation rectangles and the existing tracked bridge to
their engine's overlay. The tracked bridge itself remains page-owned.

Preserve Cesium's projection, card placement, arbitration, fades, hit tests,
blend order and render demand. Navara keeps the same shared behaviour. No
user-visible change is intended. Exercise simultaneous hosts, either teardown,
stale handles, reattachment and a retained selected card on the fake and
headless Cesium engines. Update QA reads and package ownership for the service.

No coupling metric falls or grows: renderer lines remain 0 Cesium and 189
Navara; external Cesium import files 3; viewer lines 891; Navara kind checks 1;
engine sniff calls 0; extension reads 3; ground passes 1; SDK loads 3;
ScreenSpaceEventHandler files 4; engine-name lines 32.

Each host now takes the page's overlay ids from the host it replaces and gives
them back to a remaining host when destroyed, and the chrome's static overlay
placeholders are gone. The new hosts had left the ids on those empty
placeholders, so the voice pointer policy, the id selectors and the QA probes
that read #world-overlay-canvas missed the drawn canvas.

Checked in the browser, keyless: the overlay baselines on both engines, CCTV
v2 (58 checks), military names, and the engine, voice, ground-layer and Ghost
Maps switches pass. The transit script fails the same 25 checks as before.
This commit is contained in:
German Khokhlov committed 2026-11-07 19:27:31 +04:00
1 parent 26597ad25c
commit 3814221cbc
62 files changed
+3148 -2655

No files matched your search

+4
View File
@@ -1,3 +1,5 @@
import { bindOverlayHost } from '../overlays/bindOverlayHost.js';
import { worldOverlayFor } from '../overlays/worldOverlay.js';
import { waitForSignal } from '../sources/requestDeadline.js';
import * as Cesium from 'cesium';
import { cesiumSdkReady, loadCesiumSdk } from '../app/loadCesium.js';
@@ -106,6 +108,7 @@ const PASSIVE_ENABLE_ORIGINS = new Set([
]);
const DEFAULT_OVERLAY_HOST = Object.freeze({
forEngine: worldOverlayFor,
setEntries: setOverlayEntries,
setVisible: setOverlaySourceVisible,
clearSource: clearOverlaySource,
@@ -1019,6 +1022,7 @@ export function createBhoteKoshiEventLayer({
panelStore = useBhoteKoshiPanelStore(applicationPinia()),
} = {}) {
let _viewer = null;
overlayHost = bindOverlayHost(overlayHost, () => _engine);
let _engine = null;
let _native = null;
let _nativeFlood = null;
+4
View File
@@ -1,3 +1,5 @@
import { bindOverlayHost } from '../overlays/bindOverlayHost.js';
import { worldOverlayFor } from '../overlays/worldOverlay.js';
import * as Cesium from 'cesium';
import { cesiumSdkReady, loadCesiumSdk } from '../app/loadCesium.js';
import {
@@ -151,6 +153,7 @@ const INCIDENT_ACCENT = '#ffad55';
const INCIDENT_COLOR = () => Cesium.Color.fromCssColorString(INCIDENT_ACCENT);
const DEFAULT_OVERLAY_HOST = Object.freeze({
forEngine: worldOverlayFor,
setEntries: setOverlayEntries,
clearSource: clearOverlaySource,
});
@@ -287,6 +290,7 @@ export function createBhoteKoshiLocatorLayer({
cancelDelay = (handle) => clearTimeout(handle),
} = {}) {
let _viewer = null;
overlayHost = bindOverlayHost(overlayHost, () => _engine);
let _engine = null;
let _native = null;
let _pausedApproach = null;
+21 -11
View File
@@ -315,21 +315,31 @@ export function initDetection(engine, layers, onModeChange) {
);
_hostLayoutRevision = -1;
_calloutCount = 0;
_hostLane = registerWorldOverlayPaintLane('detection', _paintDetectionLane, {
id: 'detection',
active: _mode !== MODE_OFF && !_suspended,
target: 'detection',
shouldPaint: _shouldPaintDetectionLane,
});
_hostLane = registerWorldOverlayPaintLane(
engine,
'detection',
_paintDetectionLane,
{
id: 'detection',
active: _mode !== MODE_OFF && !_suspended,
target: 'detection',
shouldPaint: _shouldPaintDetectionLane,
},
);
// Registered AFTER the sensor lane so it replays the callouts that lane just
// solved. Both sit in the 'detection' lane — the host's bottom slot — so
// callouts still paint under every ordinary overlay card and under the
// tracked readout, exactly where they sat before.
_calloutLane = registerWorldOverlayPaintLane('detection', _paintCalloutLane, {
id: 'detection-callouts',
active: _mode !== MODE_OFF && !_suspended,
target: 'shared',
});
_calloutLane = registerWorldOverlayPaintLane(
engine,
'detection',
_paintCalloutLane,
{
id: 'detection-callouts',
active: _mode !== MODE_OFF && !_suspended,
target: 'shared',
},
);
_hostSurface = _hostLane.surface;
_cockpitModeListener = (event) => {
_cockpitActive = event?.detail?.active === true;
+24 -28
View File
@@ -1,3 +1,4 @@
let overlayEngine;
import { readShellSource } from '../testSupport/readShellSource.mjs';
import test from 'node:test';
import assert from 'node:assert/strict';
@@ -232,12 +233,6 @@ function installEnvironment({ width = 800, height = 600, dpr = 2, search = '' }
const container = new MockElement('div');
container.id = 'cesiumContainer';
body.appendChild(container);
const root = new MockElement('div');
root.id = 'world-overlay-root';
body.appendChild(root);
const canvas = new MockElement('canvas');
canvas.id = 'world-overlay-canvas';
root.appendChild(canvas);
const postRender = new MockEvent();
const viewer = {
@@ -255,6 +250,7 @@ function installEnvironment({ width = 800, height = 600, dpr = 2, search = '' }
// Shell modules take the globe engine; the Cesium engine runs on the mock.
const engine = createCesiumEngine(viewer);
overlayEngine = engine;
return {
viewer,
engine,
@@ -267,7 +263,7 @@ function installEnvironment({ width = 800, height = 600, dpr = 2, search = '' }
setPerformanceStep(ms) { performanceStep = ms; },
cleanup() {
destroyDetection();
destroyWorldOverlay();
destroyWorldOverlay(overlayEngine);
engine.destroy();
Date.now = originalDateNow;
if (originalPath2D === undefined) delete globalThis.Path2D;
@@ -363,7 +359,7 @@ test('detection lifecycle re-hosts unchanged painters behind the sole host liste
const env = installEnvironment({ search: '?detectDebug=1' });
const modes = [];
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [detectableLayer()], (mode) => modes.push(mode));
assert.equal(env.postRender.listeners.size, 1);
assert.equal(env.document.getElementById('detection-overlay'), null);
@@ -493,7 +489,7 @@ test('detection lifecycle re-hosts unchanged painters behind the sole host liste
setMode('DENSE');
env.postRender.raise();
assert.equal(env.document.getElementById('detection-overlay'), null);
destroyWorldOverlay();
destroyWorldOverlay(overlayEngine);
assert.equal(env.postRender.listeners.size, 0);
assert.equal(env.document.getElementById('world-overlay-canvas'), null);
assert.equal(env.document.getElementById('world-overlay-detection-surface'), null);
@@ -517,7 +513,7 @@ test('callouts stop painting the moment the last detectable object goes away', (
type: 'AIR',
}];
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [{ id: 'flights', getDetectableObjects: () => objects }], () => {});
setMode('DENSE');
env.advance(250);
@@ -553,7 +549,7 @@ test('every style paints its OWN plate token through the production callout path
// path once per style and reads the fill style the shared canvas received.
const env = installEnvironment();
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [mixedTierLayer()], () => {});
setMode('DENSE');
settleFrame(env);
@@ -591,7 +587,7 @@ test('space-tier callouts take the heavier plate while air contacts keep the lig
// tiers at once can show it.
const env = installEnvironment();
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [mixedTierLayer()], () => {});
setDetectionStyle('surveillance');
setMode('DENSE');
@@ -619,7 +615,7 @@ test('space-tier callouts take the heavier plate while air contacts keep the lig
test('surveillance military tier reaches the dedicated render target as shipped red', () => {
const env = installEnvironment();
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [militaryLayer()], () => {});
setDetectionStyle('surveillance');
setMode('DENSE');
@@ -659,7 +655,7 @@ test('Global Context echo brackets reach the canvas in the detection style colou
pulse: { count: 1000, periodMs: 1000, startFraction: 0 },
echo,
});
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [militaryLayer()], () => {});
setMode('DENSE');
setDetectionStyle('normal');
@@ -705,7 +701,7 @@ test('a Global Context echo bracket is drawn outside its contact bracket and dim
echo,
level: () => 0.5,
});
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [militaryLayer()], () => {});
setMode('DENSE');
setDetectionStyle('normal');
@@ -777,7 +773,7 @@ test('under the Cyber sonar sweep an echo is never brighter than its own bracket
echo,
level: () => 1,
});
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [contact], () => {});
setMode('DENSE');
setDetectionStyle('normal');
@@ -839,7 +835,7 @@ test('resting Global Context pulses skip echo work for the whole frame, not per
return 0;
},
});
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [layer], () => {});
setMode('DENSE');
settleFrame(env);
@@ -866,9 +862,9 @@ test('pathological detection paint holds alternate frames without freezing share
// Opts into the telemetry banner: the held-frame assertions count banner paints.
const env = installEnvironment({ search: '?detectDebug=1' });
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [detectableLayer()], () => {});
setOverlayEntries('valve-card', [{
setOverlayEntries(overlayEngine, 'valve-card', [{
id: 'ambient-card',
position: new Cesium.Cartesian3(0, 0, 0),
variant: 'label',
@@ -929,7 +925,7 @@ test('detection cannot resurrect a private canvas, listener, matrix, resize, cle
assert.match(source, /const LABEL_SOLVE_INTERVAL_MS = 125;/);
assert.match(source, /const _labelArbiter = new LabelArbiter\(\);/);
assert.match(source, /const clipW = vp3 \* px \+ vp7 \* py \+ vp11 \* pz \+ vp15;/);
assert.match(source, /registerWorldOverlayPaintLane\('detection', _paintDetectionLane/);
assert.match(source, /registerWorldOverlayPaintLane\(\s*engine,\s*'detection',\s*_paintDetectionLane/);
assert.match(source, /target: 'detection'/);
assert.match(source, /shouldPaint: _shouldPaintDetectionLane/);
// The three military styles used to carry three copies of these numbers.
@@ -973,7 +969,7 @@ test('the mode banner is absent by default and present behind the flag', () => {
const painted = (search) => {
const env = installEnvironment({ search });
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [detectableLayer()], () => {});
setMode('DENSE');
env.advance(250);
@@ -986,7 +982,7 @@ test('the mode banner is absent by default and present behind the flag', () => {
return bannerPaints(env);
} finally {
destroyDetection();
destroyWorldOverlay();
destroyWorldOverlay(overlayEngine);
env.cleanup();
}
};
@@ -1000,7 +996,7 @@ test('detection telemetry stays reachable programmatically with the banner hidde
// is the supported way to read them, and is what the QA harnesses use.
const env = installEnvironment();
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [detectableLayer()], () => {});
setMode('DENSE');
env.advance(250);
@@ -1012,7 +1008,7 @@ test('detection telemetry stays reachable programmatically with the banner hidde
assert.equal(typeof diagnostics.densityPct, 'number');
} finally {
destroyDetection();
destroyWorldOverlay();
destroyWorldOverlay(overlayEngine);
env.cleanup();
}
});
@@ -1028,7 +1024,7 @@ test('civilian and military AIR brackets cover front, left, and right at Sparse
metric: 'FL120',
type: 'AIR',
}));
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [{ id: layerId, getDetectableObjects: () => objects }], () => {});
setDetectionTuning({ densityPct: 25 });
setMode('SPARSE');
@@ -1046,7 +1042,7 @@ test('civilian and military AIR brackets cover front, left, and right at Sparse
'Sparse keeps its documented budget instead of silently becoming Dense');
} finally {
destroyDetection();
destroyWorldOverlay();
destroyWorldOverlay(overlayEngine);
env.cleanup();
}
}
@@ -1086,7 +1082,7 @@ test('the backdrop feather reaches the canvas as a lighter plate against sky', (
// the shared canvas actually received for each plate.
const env = installEnvironment();
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(env.engine, [backdropLayer()], () => {});
setDetectionStyle('normal');
setMode('DENSE');
@@ -1144,7 +1140,7 @@ test('a transit vehicle is a contact: box, route, mode and operator on the share
},
];
try {
initWorldOverlay(env.engine);
initWorldOverlay(overlayEngine = env.engine);
initDetection(
env.engine,
[{ id: 'transit', getDetectableObjects: () => objects }],
+1
View File
@@ -198,6 +198,7 @@ test('consumer build includes only infrastructure code and engine-free geometry,
'src/layers/infrastructure/index.js',
'src/layers/infrastructure/render/display.js',
'src/layers/shared/color.js',
'src/overlays/bindOverlayHost.js',
'src/sources/infrastructureData.js',
'src/sources/requestDeadline.js',
]);
+4
View File
@@ -1,3 +1,4 @@
import { createWorldOverlay } from '../overlays/worldOverlay.js';
import { createRenderGovernor } from '../renderGovernor.js';
import { createPickRegistry } from './pickRegistry.js';
import { createSelectionDispatcher } from './selectionDispatcher.js';
@@ -9,6 +10,7 @@ const scenes = new WeakMap();
/** Create the services for one attachment, including reuse of a parked engine. */
export function createSceneServices(engine, options = {}) {
scenes.get(engine)?.destroy();
const overlay = createWorldOverlay(engine);
const render = createRenderGovernor(engine);
const picking = createPickRegistry();
const selection = createSelectionDispatcher(engine, { ...options, picking });
@@ -17,11 +19,13 @@ export function createSceneServices(engine, options = {}) {
picking,
selection,
render,
overlay,
destroy() {
if (destroyed) return;
destroyed = true;
selection.destroy();
picking.destroy();
overlay.destroy();
render.destroy();
},
};
+59
View File
@@ -1,3 +1,5 @@
import { createDroneAirspaceLayer } from '../layers/droneAirspace/index.js';
import { overlayHost } from '../app/layers/overlayHost.js';
import assert from 'node:assert/strict';
import test from 'node:test';
import { GROUND_HARNESSES } from '../testSupport/groundDisplayEngines.mjs';
@@ -135,3 +137,60 @@ for (const makeHarness of GROUND_HARNESSES) {
assert.equal(b.picking.findPickOwner('shared-id'), 'flights');
});
}
for (const makeHarness of GROUND_HARNESSES) {
test(`${makeHarness.name}: a retained selected airspace card moves between overlay services`, async (t) => {
const first = makeHarness();
const second = makeHarness();
const a = createSceneServices(first.engine);
const b = createSceneServices(second.engine);
let requests = 0;
const ring = [
[-77.04, 38.89],
[-77.03, 38.89],
[-77.03, 38.9],
[-77.04, 38.89],
];
const layer = createDroneAirspaceLayer({
source: {
async getSnapshot() {
requests++;
return [
{
stableId: '310',
name: 'P-56',
typeCode: 'P',
type: 'Prohibited',
polygons: [[ring]],
},
];
},
},
overlayHost,
picking,
pointer: { isPointerFree: () => true },
});
t.after(() => {
layer.destroy();
a.destroy();
b.destroy();
first.destroy();
second.destroy();
});
layer.init(null, { engine: first.engine });
layer.enable();
await layer.update();
first.click({ id: 'drone-airspace:310:0' });
assert.equal(a.overlay.getDiagnostics().entryCount, 1);
assert.equal(b.overlay.getDiagnostics().entryCount, 0);
layer.detachRenderer();
assert.equal(a.overlay.getDiagnostics().entryCount, 0);
layer.attachRenderer(null, { engine: second.engine });
assert.equal(requests, 1);
assert.equal(b.overlay.getDiagnostics().entryCount, 1);
a.destroy();
assert.equal(b.overlay.getDiagnostics().entryCount, 1);
layer.disable();
assert.equal(b.overlay.getDiagnostics().entryCount, 0);
});
}
+2 -2
View File
@@ -1,5 +1,5 @@
import { createApplicationCables } from '../app/layers/submarineCables.js';
import { overlayHost } from '../app/layers/overlayHost.js';
import { worldOverlayFor } from '../overlays/worldOverlay.js';
import { createCableOverlayPublisher as createPublisher } from '../layers/submarineCables/index.js';
import { createBundledCableSource } from '../layers/submarineCables/bundledSource.js';
export function createTeleGeographySubmarineCableLayer(options = {}) {
@@ -9,7 +9,7 @@ export function createTeleGeographySubmarineCableLayer(options = {}) {
});
}
export function createCableOverlayPublisher(options = {}) {
return createPublisher({ host: overlayHost, ...options });
return createPublisher({ host: worldOverlayFor(options.engine), ...options });
}
export {
CABLE_REFERENCE_LABEL_WINNER_CAP,
+3 -3
View File
@@ -28,9 +28,9 @@ const TRACKED_BILLBOARD_SCALE = Object.freeze({
});
const DEFAULT_TRACKED_OVERLAY_HOST = Object.freeze({
setEntries: setOverlayEntries,
setVisible: setOverlaySourceVisible,
clearSource: clearOverlaySource,
setEntries: (...args) => setOverlayEntries(_engine, ...args),
setVisible: (...args) => setOverlaySourceVisible(_engine, ...args),
clearSource: (...args) => clearOverlaySource(_engine, ...args),
});
// The globe engine: the followed target is engine.camera.following().