Separate scene handoff and attachment from the page shell

Move the page handoff sequence into SceneSwitcher and include restoration
in the application's candidate attachment. Release a failed candidate once
before the request coordinator recovers the working engine. Keep address
ordering, parked renderers, retained layers and cockpit resumption intact.

Define the layer session and its field owners. Share its retention decision
across teardown paths. Separate layer scene binding from lifecycle policy,
and shell scene composition from page controls. Keep failed renderer
releases in the binding owner, with the existing retry behavior.

Give Director the scene and use the engine host for its canvas and pack
container. Keep the existing tracked-subject interaction guard so neither
engine's behavior changes. Pass startup chrome the first backend's explicit
welcome policy instead of testing for a viewer. Cesium remains the behavior
reference; this restructuring intentionally changes no visible behavior on
either engine.

Viewer references outside the Cesium engine fall from 948 to 933. All other
coupling counts stay unchanged. Scene service ownership, raw debug access,
and the remaining shell and host queues still need consolidation.

Checked in the browser, keyless, on the dev server: the engine switch,
Director engine switch, layer panel and layer visibility on both engines
pass, and 14 of 15 strict scenarios pass (rapid, hidden-tab, context-loss,
parked-release, Navara HD, failure matrix and soak among them). app-once
and the Director next-shot step fail the same way before this change.
This commit is contained in:
German Khokhlov committed 2026-11-07 15:44:03 +04:00
1 parent f385986383
commit 656943641c
23 files changed
+1265 -888

No files matched your search

+259
View File
@@ -0,0 +1,259 @@
// A scene bind or detach waits this long for asynchronous layer attachments.
// A late attachment sees its scene signal aborted and releases its own work.
export const ATTACH_SETTLE_TIMEOUT_MS = 5000;
/** Scene attachment and parked work for the layer lifecycle. */
export class LayerSceneBinding {
constructor(attachSettleTimeoutMs) {
// The bound scene: its signal reaches every attachRenderer() call and is
// aborted when the scene detaches. Asynchronous attachments still running
// are kept here so the detach releases them only after they stopped.
this._failedReleases = new WeakMap();
this._sceneController = null;
this._sceneDetached = false;
this._pendingAttachments = new Set();
this._attachSettleTimeoutMs = attachSettleTimeoutMs;
// Lifecycle work and explicit refreshes that wait for the next scene.
// detachScene() does not wait for parked work, which waits for it.
this._sceneWaiters = new Set();
this._parkListeners = new Set();
}
/**
* Release the scene only. Models with an explicit renderer lifetime keep
* their entry, polling interval, visibility intents and in-flight source.
* Legacy modules use their ordinary teardown until they gain that contract.
*
* Every layer is released even when another one fails, and the manager is
* always left unbound, so the next bindCatalog() can attach a scene. The
* failures are reported together. A layer whose release failed keeps it
* pending: a repeated detachScene(), or the next bindCatalog(), retries it.
* Periodic refreshes, explicit refreshes and enables requested while no
* scene is bound wait for the next one.
*/
async detachScene() {
// Attachments still in flight stop at their next checkpoint; their
// partial work is released below like a finished attachment.
this._sceneController?.abort();
this._sceneController = null;
this._sceneDetached = true;
const viewer = this.viewer;
const errors = [];
const droppedQaLayers = [];
try {
await this._awaitAttachments([...this._pendingAttachments], 'detach');
for (const [id, entry] of [...this.layers]) {
try {
await this._lifecycleIdleOrParked(entry);
if (entry.module.attachRenderer && entry.module.detachRenderer) {
await this._detachEntryRenderer(entry, viewer);
} else {
const qaLayer = this._qaLayerIds.has(id);
if (!(await this.destroyLayer(id))) {
// The next catalog brings a fresh module for this id. A stale
// entry would refuse it, so the failed one is dropped here.
this._stopUpdateLoop(entry);
this.layers.delete(id);
this._qaLayerIds.delete(id);
throw new Error(`Cannot detach layer ${id}`);
}
if (qaLayer) droppedQaLayers.push(id);
}
} catch (error) {
errors.push(error);
}
}
} finally {
this.viewer = null;
this.engine = null;
this._registrationsFinalized = false;
this._registrationDispositions = null;
}
if (droppedQaLayers.length)
console.warn(
`[Data] QA layers do not survive a scene switch; register them again: ${droppedQaLayers.join(', ')}`,
);
if (errors.length) {
for (const error of errors)
console.warn('[Data] scene detach error:', error);
throw new AggregateError(errors, 'Data layers could not detach');
}
}
/** Release one retained layer's renderer, keeping a failure for a retry. */
async _detachEntryRenderer(entry, viewer) {
const pending = this._failedReleases.get(entry);
if (!pending && (!entry.initialized || entry.sceneDetached)) return;
const target = pending ? pending.target : viewer;
this._failedReleases.set(entry, { target });
await entry.module.detachRenderer(target);
this._failedReleases.delete(entry);
entry.sceneDetached = true;
}
/** Bind the next catalog only after the preceding scene released its entries. */
bindCatalog(viewer, engine, catalog, options = {}) {
if (this._registrationsFinalized) throw new Error('Scene already attached');
this.viewer = viewer;
this.engine = engine ?? null;
this._catalogSourceAvailability = catalog.getSourceAvailability;
const scene = new AbortController();
this._sceneController = scene;
// An attachment that is still running when the scene detaches sees this
// signal aborted and must stop touching the scene.
const context = { ...this._moduleContext(scene.signal), ...options };
const attachments = [];
for (const layer of catalog.layers) {
const entry = this.layers.get(layer.id);
if (!entry) this.register(layer);
else {
if (entry.module !== layer)
throw new Error(`Layer owner changed: ${layer.id}`);
if (entry.initialized) {
attachments.push(this._attachEntryRenderer(entry, viewer, context));
}
}
}
// Retained entries may appear anywhere in the directory. Preserve both
// catalog order (panel/serialization) and each live entry's identity.
for (const { id } of catalog.layers) {
const entry = this.layers.get(id);
this.layers.delete(id);
this.layers.set(id, entry);
}
this.finalizeRegistrations(catalog.metadata);
const pending = attachments.filter((ready) => ready?.then);
// The scene counts as bound for refreshes and parked enables once its
// attachments settled (or the wait for them timed out).
const bound = () => {
if (this._sceneController !== scene) return;
this._sceneDetached = false;
this._runDeferredRefreshes();
this._settleSceneWaiters(true);
};
if (!pending.length) {
bound();
return undefined;
}
return this._awaitAttachments(pending, 'bind').then((settled) => {
bound();
const failure = settled?.find(({ status }) => status === 'rejected');
if (failure) throw failure.reason;
});
}
/**
* Wait for attachments to settle, at most attachSettleTimeoutMs. Returns
* their allSettled results, or null when the wait timed out.
*/
async _awaitAttachments(attachments, phase) {
if (!attachments.length) return [];
let timer;
const timedOut = new Promise((resolve) => {
timer = setTimeout(resolve, this._attachSettleTimeoutMs, null);
});
const settled = await Promise.race([
Promise.allSettled(attachments),
timedOut,
]);
clearTimeout(timer);
if (!settled)
console.warn(
`[Data] layer attachments still running after ${this._attachSettleTimeoutMs} ms; scene ${phase} continues without them`,
);
return settled;
}
/**
* Wait until a scene is bound. Resolves true then, or false when the
* signal aborts or the entry is destroyed. `refresh` marks an explicit
* refresh, which replaces the entry's deferred periodic one.
*/
_waitForScene(entry, signal = null, { refresh = false } = {}) {
if (!this._sceneDetached) return Promise.resolve(true);
if (signal?.aborted) return Promise.resolve(false);
return new Promise((resolve) => {
const onAbort = () => waiter.settle(false);
const waiter = {
entry,
refresh,
settle: (bound) => {
if (!this._sceneWaiters.delete(waiter)) return;
if (refresh) entry.sceneRefreshWaiters -= 1;
signal?.removeEventListener?.('abort', onAbort);
resolve(bound);
},
};
if (refresh) entry.sceneRefreshWaiters += 1;
this._sceneWaiters.add(waiter);
signal?.addEventListener?.('abort', onAbort, { once: true });
for (const listener of [...this._parkListeners]) listener(entry);
});
}
_settleSceneWaiters(bound, entry = null) {
for (const waiter of [...this._sceneWaiters])
if (!entry || waiter.entry === entry) waiter.settle(bound);
}
/** The entry's queued lifecycle work settled, or is parked for a scene. */
_lifecycleIdleOrParked(entry) {
const parked = () =>
[...this._sceneWaiters].some(
(waiter) => waiter.entry === entry && !waiter.refresh,
);
if (parked()) return Promise.resolve();
return new Promise((resolve) => {
const done = () => {
this._parkListeners.delete(listener);
resolve();
};
const listener = (parkedEntry) => {
if (parkedEntry === entry && parked()) done();
};
this._parkListeners.add(listener);
entry.toggleChain.catch(() => {}).then(done);
});
}
/**
* Attach one retained layer to the bound scene. A release that failed on
* the previous scene is retried first. Asynchronous attachments are tracked
* so detachScene() releases them only after they stopped.
*/
_attachEntryRenderer(entry, viewer, context) {
let ready;
try {
const pending = this._failedReleases.get(entry);
entry.sceneDetached = false;
if (pending) {
ready = Promise.resolve()
.then(() => entry.module.detachRenderer(pending.target))
.then(() => {
this._failedReleases.delete(entry);
if (context.signal.aborted) return undefined;
return entry.module.attachRenderer(viewer, context);
});
} else ready = entry.module.attachRenderer(viewer, context);
} catch (error) {
ready = Promise.reject(error);
}
if (!ready?.then) return ready;
const tracked = Promise.resolve(ready);
this._pendingAttachments.add(tracked);
const untrack = () => this._pendingAttachments.delete(tracked);
tracked.then(untrack, untrack);
return tracked;
}
/** Run the periodic refreshes that came due while no scene was bound. */
_runDeferredRefreshes() {
for (const [layerId, entry] of this.layers) {
if (!entry.refreshDeferred) continue;
entry.refreshDeferred = false;
// An explicit refresh waiting for this scene runs instead.
if (entry.sceneRefreshWaiters > 0) continue;
void this._runPeriodicUpdate(layerId, entry);
}
}
}
+6 -254
View File
@@ -1,3 +1,7 @@
import {
LayerSceneBinding,
ATTACH_SETTLE_TIMEOUT_MS,
} from './layerSceneBinding.js';
import { cancelCameraArrival } from './cameraArrival.js';
function cloneLayerParams(value) {
@@ -14,9 +18,6 @@ function cloneLayerParams(value) {
}
const SUPERSEDED_VISIBILITY_INTENT = Symbol('superseded-visibility-intent');
// A scene bind or detach waits this long for asynchronous layer attachments.
// A late attachment sees its scene signal aborted and releases its own work.
const ATTACH_SETTLE_TIMEOUT_MS = 5000;
const VALID_LAYER_SERIALIZATION_DISPOSITIONS = new Set([
'enabled-only',
'enabled+options',
@@ -78,7 +79,7 @@ function refreshFailureFromStats(stats, label) {
* Hosts may inject a visibilityTarget with hidden/visibilityState and event
* listener methods. Without one, periodic work retains its headless behavior.
*/
export class LayerLifecycle {
export class LayerLifecycle extends LayerSceneBinding {
/**
* @param {object | null} viewer The Cesium viewer (null on Navara).
* @param {{ engine?: import('../globe/contract.js').GlobeEngine,
@@ -98,6 +99,7 @@ export class LayerLifecycle {
attachSettleTimeoutMs = ATTACH_SETTLE_TIMEOUT_MS,
} = {},
) {
super(attachSettleTimeoutMs);
this._catalogSourceAvailability = getSourceAvailability;
this._visibilityTarget = visibilityTarget;
this.viewer = viewer;
@@ -112,17 +114,6 @@ export class LayerLifecycle {
this._registrationDispositions = null;
this._allowQaRegistration = allowQaRegistration === true;
this._qaLayerIds = new Set();
// The bound scene: its signal reaches every attachRenderer() call and is
// aborted when the scene detaches. Asynchronous attachments still running
// are kept here so the detach releases them only after they stopped.
this._sceneController = null;
this._sceneDetached = false;
this._pendingAttachments = new Set();
this._attachSettleTimeoutMs = attachSettleTimeoutMs;
// Lifecycle work and explicit refreshes that wait for the next scene.
// detachScene() does not wait for parked work, which waits for it.
this._sceneWaiters = new Set();
this._parkListeners = new Set();
}
/** The second argument of every layer module call: `{ signal, engine }`. */
@@ -137,244 +128,6 @@ export class LayerLifecycle {
this._registerLayer(layerModule);
}
/**
* Release the scene only. Models with an explicit renderer lifetime keep
* their entry, polling interval, visibility intents and in-flight source.
* Legacy modules use their ordinary teardown until they gain that contract.
*
* Every layer is released even when another one fails, and the manager is
* always left unbound, so the next bindCatalog() can attach a scene. The
* failures are reported together. A layer whose release failed keeps it
* pending: a repeated detachScene(), or the next bindCatalog(), retries it.
* Periodic refreshes, explicit refreshes and enables requested while no
* scene is bound wait for the next one.
*/
async detachScene() {
// Attachments still in flight stop at their next checkpoint; their
// partial work is released below like a finished attachment.
this._sceneController?.abort();
this._sceneController = null;
this._sceneDetached = true;
const viewer = this.viewer;
const errors = [];
const droppedQaLayers = [];
try {
await this._awaitAttachments([...this._pendingAttachments], 'detach');
for (const [id, entry] of [...this.layers]) {
try {
await this._lifecycleIdleOrParked(entry);
if (entry.module.attachRenderer && entry.module.detachRenderer) {
await this._detachEntryRenderer(entry, viewer);
} else {
const qaLayer = this._qaLayerIds.has(id);
if (!(await this.destroyLayer(id))) {
// The next catalog brings a fresh module for this id. A stale
// entry would refuse it, so the failed one is dropped here.
this._stopUpdateLoop(entry);
this.layers.delete(id);
this._qaLayerIds.delete(id);
throw new Error(`Cannot detach layer ${id}`);
}
if (qaLayer) droppedQaLayers.push(id);
}
} catch (error) {
errors.push(error);
}
}
} finally {
this.viewer = null;
this.engine = null;
this._registrationsFinalized = false;
this._registrationDispositions = null;
}
if (droppedQaLayers.length)
console.warn(
`[Data] QA layers do not survive a scene switch; register them again: ${droppedQaLayers.join(', ')}`,
);
if (errors.length) {
for (const error of errors)
console.warn('[Data] scene detach error:', error);
throw new AggregateError(errors, 'Data layers could not detach');
}
}
/** Release one retained layer's renderer, keeping a failure for a retry. */
async _detachEntryRenderer(entry, viewer) {
const pending = entry.pendingSceneDetach;
if (!pending && (!entry.initialized || entry.sceneDetached)) return;
const target = pending ? pending.viewer : viewer;
entry.pendingSceneDetach = { viewer: target };
await entry.module.detachRenderer(target);
entry.pendingSceneDetach = null;
entry.sceneDetached = true;
}
/** Bind the next catalog only after the preceding scene released its entries. */
bindCatalog(viewer, engine, catalog, options = {}) {
if (this._registrationsFinalized) throw new Error('Scene already attached');
this.viewer = viewer;
this.engine = engine ?? null;
this._catalogSourceAvailability = catalog.getSourceAvailability;
const scene = new AbortController();
this._sceneController = scene;
// An attachment that is still running when the scene detaches sees this
// signal aborted and must stop touching the scene.
const context = { ...this._moduleContext(scene.signal), ...options };
const attachments = [];
for (const layer of catalog.layers) {
const entry = this.layers.get(layer.id);
if (!entry) this.register(layer);
else {
if (entry.module !== layer)
throw new Error(`Layer owner changed: ${layer.id}`);
if (entry.initialized) {
attachments.push(this._attachEntryRenderer(entry, viewer, context));
}
}
}
// Retained entries may appear anywhere in the directory. Preserve both
// catalog order (panel/serialization) and each live entry's identity.
for (const { id } of catalog.layers) {
const entry = this.layers.get(id);
this.layers.delete(id);
this.layers.set(id, entry);
}
this.finalizeRegistrations(catalog.metadata);
const pending = attachments.filter((ready) => ready?.then);
// The scene counts as bound for refreshes and parked enables once its
// attachments settled (or the wait for them timed out).
const bound = () => {
if (this._sceneController !== scene) return;
this._sceneDetached = false;
this._runDeferredRefreshes();
this._settleSceneWaiters(true);
};
if (!pending.length) {
bound();
return undefined;
}
return this._awaitAttachments(pending, 'bind').then((settled) => {
bound();
const failure = settled?.find(({ status }) => status === 'rejected');
if (failure) throw failure.reason;
});
}
/**
* Wait for attachments to settle, at most attachSettleTimeoutMs. Returns
* their allSettled results, or null when the wait timed out.
*/
async _awaitAttachments(attachments, phase) {
if (!attachments.length) return [];
let timer;
const timedOut = new Promise((resolve) => {
timer = setTimeout(resolve, this._attachSettleTimeoutMs, null);
});
const settled = await Promise.race([
Promise.allSettled(attachments),
timedOut,
]);
clearTimeout(timer);
if (!settled)
console.warn(
`[Data] layer attachments still running after ${this._attachSettleTimeoutMs} ms; scene ${phase} continues without them`,
);
return settled;
}
/**
* Wait until a scene is bound. Resolves true then, or false when the
* signal aborts or the entry is destroyed. `refresh` marks an explicit
* refresh, which replaces the entry's deferred periodic one.
*/
_waitForScene(entry, signal = null, { refresh = false } = {}) {
if (!this._sceneDetached) return Promise.resolve(true);
if (signal?.aborted) return Promise.resolve(false);
return new Promise((resolve) => {
const onAbort = () => waiter.settle(false);
const waiter = {
entry,
refresh,
settle: (bound) => {
if (!this._sceneWaiters.delete(waiter)) return;
if (refresh) entry.sceneRefreshWaiters -= 1;
signal?.removeEventListener?.('abort', onAbort);
resolve(bound);
},
};
if (refresh) entry.sceneRefreshWaiters += 1;
this._sceneWaiters.add(waiter);
signal?.addEventListener?.('abort', onAbort, { once: true });
for (const listener of [...this._parkListeners]) listener(entry);
});
}
_settleSceneWaiters(bound, entry = null) {
for (const waiter of [...this._sceneWaiters])
if (!entry || waiter.entry === entry) waiter.settle(bound);
}
/** The entry's queued lifecycle work settled, or is parked for a scene. */
_lifecycleIdleOrParked(entry) {
const parked = () =>
[...this._sceneWaiters].some(
(waiter) => waiter.entry === entry && !waiter.refresh,
);
if (parked()) return Promise.resolve();
return new Promise((resolve) => {
const done = () => {
this._parkListeners.delete(listener);
resolve();
};
const listener = (parkedEntry) => {
if (parkedEntry === entry && parked()) done();
};
this._parkListeners.add(listener);
entry.toggleChain.catch(() => {}).then(done);
});
}
/**
* Attach one retained layer to the bound scene. A release that failed on
* the previous scene is retried first. Asynchronous attachments are tracked
* so detachScene() releases them only after they stopped.
*/
_attachEntryRenderer(entry, viewer, context) {
let ready;
try {
const pending = entry.pendingSceneDetach;
entry.sceneDetached = false;
if (pending) {
ready = Promise.resolve()
.then(() => entry.module.detachRenderer(pending.viewer))
.then(() => {
entry.pendingSceneDetach = null;
if (context.signal.aborted) return undefined;
return entry.module.attachRenderer(viewer, context);
});
} else ready = entry.module.attachRenderer(viewer, context);
} catch (error) {
ready = Promise.reject(error);
}
if (!ready?.then) return ready;
const tracked = Promise.resolve(ready);
this._pendingAttachments.add(tracked);
const untrack = () => this._pendingAttachments.delete(tracked);
tracked.then(untrack, untrack);
return tracked;
}
/** Run the periodic refreshes that came due while no scene was bound. */
_runDeferredRefreshes() {
for (const [layerId, entry] of this.layers) {
if (!entry.refreshDeferred) continue;
entry.refreshDeferred = false;
// An explicit refresh waiting for this scene runs instead.
if (entry.sceneRefreshWaiters > 0) continue;
void this._runPeriodicUpdate(layerId, entry);
}
}
/** Register a synthetic layer after sealing in an explicitly dev-enabled manager. */
registerForQa(layerModule) {
if (!this._allowQaRegistration || !this._registrationsFinalized) {
@@ -456,7 +209,6 @@ export class LayerLifecycle {
// renderer is released, a release that failed and is retried, and a
// periodic refresh that came due while no scene was bound.
sceneDetached: false,
pendingSceneDetach: null,
refreshDeferred: false,
sceneRefreshWaiters: 0,
});