mirror of
https://github.com/bilawalsidhu/gods-eye-view.git
synced 2026-11-17 08:42:21 +00:00
- src/geo drops the ported debug argument checks and the tests that bitExact already covers; package boundaries accept a directory entry, so src/geo/ is listed once per group. - Cesium no longer carries movers and lines nobody draws with: they are optional engine capabilities. The fake engine and the Cesium camera use the shared cameraMath; unused contract tables, clock.ticked, the 'finest' surface detail and Navara click statistics are gone. - ALPR keeps one overlay core and one presentation model for both engines, bikeshare one station bookkeeping, the Navara ground effects one definition helper; image atlases, view centres, mover banks and colours are shared. - The legacy switch route, the clock offset and rate controls and other unused exports are removed. - The acceptance runs the Navara draw, geo import and scope checks; scenarios use the harness switch and page helpers; the main chunk check keeps the size budget only and runs once in CI.
325 lines
11 KiB
JavaScript
325 lines
11 KiB
JavaScript
// The page's engine switch: one layer session, one engine at a time.
|
|
//
|
|
// The address (?engine=) is the source of truth, except while a picked
|
|
// engine starts: that choice lives here until the engine runs, and only then
|
|
// is written to the address as a new history entry. A switch from the picker
|
|
// (select) and a history visit (Back/Forward, a pasted address) both hand the
|
|
// session off: the running engine is released, the requested engine starts on
|
|
// the retained session. They differ in what the incoming engine shows: a pick
|
|
// keeps the running view and layers, a visit restores the entry's view and
|
|
// the layers its entry changed (as a same-engine Back does) on the retained
|
|
// layer models.
|
|
// Requests that arrive while a switch or a recovery runs are never dropped:
|
|
// once the current attempt settles, the address is read again and reconciled.
|
|
|
|
const ENGINES = Object.freeze(['cesium', 'navara']);
|
|
|
|
/** A started engine whose first frame takes longer than this is shown anyway. */
|
|
const FIRST_FRAME_WAIT_MS = 10_000;
|
|
|
|
/**
|
|
* Drive engine switches for one page session.
|
|
*
|
|
* A failed attempt rolls back to the last engine that actually started
|
|
* (never to the one that just failed) and, when that recovery fails too,
|
|
* leaves the page without an engine but still able to take the next request. A page lifetime abort (pagehide) stops the
|
|
* machine: nothing starts after it.
|
|
*
|
|
* @param {object} options
|
|
* @param {string} options.kind The engine already running.
|
|
* @param {() => string} options.requested The engine the address asks for now.
|
|
* @param {AbortSignal} options.signal The page lifetime.
|
|
* @param {(from: string, to: string, change: {visit: boolean}) => Promise<void>} options.leave
|
|
* Hand the session off from the running engine and release that engine.
|
|
* @param {(kind: string, attempt: {recovery: boolean}) => Promise<void>} options.enter
|
|
* Start an engine on the retained session. It resolves once the engine runs
|
|
* with the session attached; when it rejects it has already released what
|
|
* it started.
|
|
* @param {{select: (from: ?string) => *, commit: (token: *, kind: string) => void, restore: (kind: string) => void}} options.address
|
|
* @param {(state: {failed: boolean}) => Promise<void>|void} [options.settle] Runs
|
|
* once the address is reconciled, before the machine reports idle.
|
|
* @param {(kind: string) => void} [options.remember] Store a picked engine.
|
|
* @param {(state: object) => void} [options.onChange]
|
|
* @param {(error: unknown, outcome: {recovered: boolean, kind: ?string}) => void} [options.onFailure]
|
|
*/
|
|
export function createEngineSwitch({
|
|
kind,
|
|
requested,
|
|
signal,
|
|
leave,
|
|
enter,
|
|
address,
|
|
settle,
|
|
remember,
|
|
onChange,
|
|
onFailure,
|
|
}) {
|
|
// The engine whose session is live, null while none is.
|
|
let current = kind;
|
|
// The engine attached to the application or starting to attach: what a
|
|
// history visit would leave.
|
|
let live = kind;
|
|
// The last engine that started successfully: the rollback target.
|
|
let working = kind;
|
|
let failed = false;
|
|
let busy = false;
|
|
// Every request (select or address visit) bumps this; a visit also bumps
|
|
// `visits`.
|
|
let requests = 0;
|
|
let visits = 0;
|
|
let queued = null;
|
|
// The pick being started, held here rather than in the address: a visit
|
|
// made meanwhile retires it and leaves every entry as it was.
|
|
let pending = null;
|
|
let running = null;
|
|
|
|
const state = () =>
|
|
Object.freeze({
|
|
kind: current ?? working,
|
|
engine: live,
|
|
busy,
|
|
failed,
|
|
});
|
|
const publish = () => onChange?.(state());
|
|
|
|
function prepare(next) {
|
|
pending = { to: next, token: address.select(current) };
|
|
}
|
|
|
|
/** The picker's choice. While a switch runs it is queued, not dropped. */
|
|
function select(next) {
|
|
if (!ENGINES.includes(next) || signal.aborted) return null;
|
|
requests++;
|
|
if (busy) {
|
|
queued = next;
|
|
return running;
|
|
}
|
|
if (next === current) return null;
|
|
prepare(next);
|
|
return run();
|
|
}
|
|
|
|
/** The address changed (history visit) or should be checked again. */
|
|
function reconcile() {
|
|
if (signal.aborted) return Promise.resolve();
|
|
requests++;
|
|
visits++;
|
|
// A later visit supersedes a pick queued or starting before it.
|
|
queued = null;
|
|
pending = null;
|
|
return busy ? running : run();
|
|
}
|
|
|
|
function run() {
|
|
busy = true;
|
|
publish();
|
|
running = drive()
|
|
.catch((error) =>
|
|
onFailure?.(error, { recovered: current !== null, kind: current }),
|
|
)
|
|
.finally(() => {
|
|
busy = false;
|
|
running = null;
|
|
publish();
|
|
});
|
|
return running;
|
|
}
|
|
|
|
async function drive() {
|
|
for (;;) {
|
|
await reconcileAddress();
|
|
if (signal.aborted) return;
|
|
const seen = requests;
|
|
try {
|
|
await settle?.({ failed });
|
|
} catch (error) {
|
|
// Revealing the globe is cosmetic; the engine runs either way.
|
|
console.error('The globe switch could not settle:', error);
|
|
}
|
|
if (signal.aborted || seen === requests) return;
|
|
}
|
|
}
|
|
|
|
async function reconcileAddress() {
|
|
let handled = null;
|
|
for (;;) {
|
|
if (signal.aborted) return;
|
|
if (queued !== null) {
|
|
const next = queued;
|
|
queued = null;
|
|
if (next !== current) prepare(next);
|
|
}
|
|
const target = pending?.to ?? requested();
|
|
if (target === current) return;
|
|
// After a failed recovery, wait for the person's next request instead
|
|
// of retrying the same address in a loop.
|
|
if (failed && handled === requests) return;
|
|
handled = requests;
|
|
await attempt(target);
|
|
}
|
|
}
|
|
|
|
async function attempt(target) {
|
|
const visitsAtStart = visits;
|
|
const visit = pending?.to !== target;
|
|
publish();
|
|
try {
|
|
if (current !== null) {
|
|
const from = current;
|
|
try {
|
|
await leave(from, target, { visit });
|
|
} finally {
|
|
current = null;
|
|
}
|
|
}
|
|
if (signal.aborted) return;
|
|
live = target;
|
|
await enter(target, { recovery: false });
|
|
if (signal.aborted) return;
|
|
current = working = target;
|
|
failed = false;
|
|
if (!visit && pending?.to === target) {
|
|
address.commit(pending.token, target);
|
|
remember?.(target);
|
|
}
|
|
pending = null;
|
|
} catch (error) {
|
|
if (signal.aborted) return;
|
|
pending = null;
|
|
// A failed pick never touched the address. A failed visit points its
|
|
// entry at the working engine, unless the person has since moved on.
|
|
if (visit && visits === visitsAtStart && requested() === target)
|
|
address.restore(working);
|
|
if (working === target) {
|
|
live = null;
|
|
failed = true;
|
|
onFailure?.(error, { recovered: false, kind: null });
|
|
return;
|
|
}
|
|
live = working;
|
|
try {
|
|
await enter(working, { recovery: true });
|
|
if (signal.aborted) return;
|
|
current = working;
|
|
failed = false;
|
|
onFailure?.(error, { recovered: true, kind: working });
|
|
} catch (recoveryError) {
|
|
if (signal.aborted) return;
|
|
live = null;
|
|
failed = true;
|
|
onFailure?.(recoveryError, { recovered: false, kind: null });
|
|
}
|
|
}
|
|
}
|
|
|
|
return Object.freeze({ select, reconcile, state });
|
|
}
|
|
|
|
/**
|
|
* The engine choice in the page address. A pick leaves the address alone
|
|
* while its engine starts; a successful one adds the history entry (the
|
|
* earlier entry keeps the outgoing engine and view), so Back returns to the
|
|
* previous engine, and a failed or superseded pick changes no entry.
|
|
*/
|
|
export function createEngineAddress({ location, history, flush = () => {} }) {
|
|
const withEngine = (engine) => {
|
|
const url = new URL(location.href);
|
|
url.searchParams.set('engine', engine);
|
|
return url.href;
|
|
};
|
|
return Object.freeze({
|
|
/** Snapshot the outgoing entry: its engine and its latest view. */
|
|
select(from) {
|
|
flush();
|
|
return from ? withEngine(from) : null;
|
|
},
|
|
commit(previous, engine) {
|
|
const next = withEngine(engine);
|
|
// Without a running engine to return to, the pick names this entry.
|
|
if (!previous) return history.replaceState(history.state, '', next);
|
|
history.replaceState(history.state, '', previous);
|
|
history.pushState(null, '', next);
|
|
},
|
|
restore(engine) {
|
|
history.replaceState(history.state, '', withEngine(engine));
|
|
},
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Hand the session off before the running engine is released: record the
|
|
* layer models so the next engine retains them, and park the cameras and the
|
|
* Director scene instead of ending them. Every engine change in this page
|
|
* hands off, whatever started it. The incoming engine reads the view
|
|
* (camera, style, map) from the address it starts with. Each layer records
|
|
* whether it runs and whether the outgoing address listed it
|
|
* (`addressLayerIds`): the layer-state coordinator keeps it running as it
|
|
* was where the incoming address agrees (always after a pick) and follows a
|
|
* visited entry where it differs (handoffTargetEnabled).
|
|
*/
|
|
export function handOffSession(session, { addressLayerIds = null } = {}) {
|
|
const manager = session.manager;
|
|
const listed = addressLayerIds ? new Set(addressLayerIds) : null;
|
|
session.handoffLayers = new Map(
|
|
[...manager.layers].map(([id, entry]) => [
|
|
id,
|
|
{
|
|
entry: entry.module.attachRenderer ? entry : null,
|
|
enabled: manager.isEffectivelyEnabled(id),
|
|
durable: listed ? listed.has(id) : undefined,
|
|
},
|
|
]),
|
|
);
|
|
manager.layers.get('directions')?.module.suspendCamera?.();
|
|
manager.layers.get('satellites')?.module.suspendCamera?.();
|
|
session.director?.suspendScene();
|
|
}
|
|
|
|
/** Resume what handOffSession parked, once the incoming view is restored. */
|
|
export function resumeSession(session) {
|
|
for (const { module } of session.manager.layers.values())
|
|
module.resumeViewport?.();
|
|
if (session.handoffLayers)
|
|
session.manager.layers.get('directions')?.module.resumeCamera?.();
|
|
session.director?.resumeScene();
|
|
}
|
|
|
|
/**
|
|
* Wait for a started engine's first frame before the cover over it goes.
|
|
*
|
|
* A switch succeeds when the engine has started with the session attached;
|
|
* this wait never fails it. It resolves true on the first drawn frame and
|
|
* false when the tab is hidden (a hidden tab draws nothing and shows nothing,
|
|
* so there is nothing to wait for) or after `timeoutMs` of visible time
|
|
* without a frame, so a slow GPU leaves the new globe uncovered rather than
|
|
* rolling a healthy engine back.
|
|
*/
|
|
export function waitForFirstFrame(
|
|
engine,
|
|
{
|
|
document = globalThis.document,
|
|
timeoutMs = FIRST_FRAME_WAIT_MS,
|
|
setTimer = setTimeout,
|
|
clearTimer = clearTimeout,
|
|
} = {},
|
|
) {
|
|
if (document?.hidden) return Promise.resolve(false);
|
|
return new Promise((resolve) => {
|
|
let timer = null;
|
|
let remove = () => {};
|
|
const finish = (drawn) => {
|
|
remove();
|
|
clearTimer(timer);
|
|
document?.removeEventListener?.('visibilitychange', hidden);
|
|
resolve(drawn);
|
|
};
|
|
function hidden() {
|
|
if (document.hidden) finish(false);
|
|
}
|
|
remove = engine.frames.postRender.addEventListener(() => finish(true));
|
|
timer = setTimer(() => finish(false), timeoutMs);
|
|
document?.addEventListener?.('visibilitychange', hidden);
|
|
engine.render.request('engine-switch');
|
|
});
|
|
}
|