From a8a9cc73a4efab52a9e2b5bb4741868d188253b1 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 9 Nov 2026 12:11:42 -0800 Subject: [PATCH 1/4] Map stacks off the Cesium allow-list: providers move into the Cesium adapter The map stacks' imagery, terrain and Google 3D factories move into the Cesium adapter (src/render/cesium/mapImagery.js, mapTerrain.js, google3d.js); the ./maps/imagery, ./maps/terrain and ./maps/3d exports point there. The catalog names its ion stacks by asset number, and the map source controller and default sources are Cesium-free: they build providers and switch imagery layers, terrain, tilesets and the globe's visibility through a map engine (src/maps/engine.js) that the Cesium adapter provides as it loads (mapEngine.js), through the application's renderer or the ./render/cesium/unbound export. The controller and createDefaultMapSources also take it as an `engine` option. src/maps/catalog.js, controller.js, imagery.js, terrain.js and google3d.js leave the allow-list. --- docs/CODE-BOUNDARIES.md | 9 ++ docs/CURRENT-STATE.md | 13 +- package.json | 6 +- scripts/format-scope.json | 12 +- scripts/package-boundaries.json | 43 ++++-- scripts/qa-terrain-429.mjs | 2 +- src/app/mapLifecycle.test.mjs | 1 + src/app/scene.js | 2 +- .../telegeographySubmarineCables.test.mjs | 2 + src/layers/recentImagery/index.test.mjs | 1 + src/mapStartup.js | 5 +- src/mapStartup.test.mjs | 6 +- src/maps/attribution.js | 8 ++ src/maps/catalog.js | 10 +- src/maps/controller.js | 135 ++++++++++-------- src/maps/controller.test.mjs | 2 + src/maps/defaultSources.js | 29 ++-- src/maps/engine.js | 33 +++++ src/maps/map-subscription-ownership.test.mjs | 2 + src/maps/startupRoute.js | 20 +++ src/maps/terrainRetry.test.mjs | 2 +- src/render/cesium/appRenderer.js | 2 + src/render/cesium/globe.js | 2 +- src/{maps => render/cesium}/google3d.js | 19 +-- src/render/cesium/mapEngine.js | 80 +++++++++++ .../cesium/mapImagery.js} | 9 +- .../cesium/mapSources.test.mjs} | 27 +++- .../cesium/mapTerrain.js} | 8 +- src/render/cesium/unbound.js | 6 +- src/render/cesiumAllowList.json | 5 - src/render/unboundCamera.test.mjs | 3 + 31 files changed, 364 insertions(+), 140 deletions(-) create mode 100644 src/maps/attribution.js create mode 100644 src/maps/engine.js create mode 100644 src/maps/startupRoute.js rename src/{maps => render/cesium}/google3d.js (91%) create mode 100644 src/render/cesium/mapEngine.js rename src/{maps/imagery.js => render/cesium/mapImagery.js} (89%) rename src/{maps/sourceFactories.test.mjs => render/cesium/mapSources.test.mjs} (93%) rename src/{maps/terrain.js => render/cesium/mapTerrain.js} (87%) diff --git a/docs/CODE-BOUNDARIES.md b/docs/CODE-BOUNDARIES.md index 3e4378fe2..c8cdf742b 100644 --- a/docs/CODE-BOUNDARIES.md +++ b/docs/CODE-BOUNDARIES.md @@ -505,6 +505,15 @@ perform no network requests and discover no additional modules. standard sources and their setup/fallback policy. The standalone facade wires these to the application's render governor. +`maps/imagery`, `maps/terrain` and `maps/3d` are the Cesium renderer's +(`src/render/cesium/`). `maps/controller` and `maps/defaults` are +Cesium-free: they make their scene changes and build their providers +through the map engine the renderer provides as it loads +(`src/maps/engine.js`). The application's renderer provides it; with a +viewer with no renderer bound, load `./render/cesium/unbound` once first, or pass the +engine as the controller's and `createDefaultMapSources`' `engine` option. +Without one, constructing a controller throws, naming that export. + A registry supplies `sources`, `defaultId`, `unknownId` and optional `recoveryId`. Each source has a user-facing `descriptor`, availability/reason, and either an `imagery({ signal })` factory or a supplied `tileset`/`createTileset({ signal })`. diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index f765849d7..8987bd96e 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -558,7 +558,7 @@ Keyless terrain tiles retry when Re:Earth throttles them. The browser fetches `terrain.reearth.land/cesium-mesh/ellipsoid/{z}/{x}/{y}.terrain` directly; no proxy in this repository sees those requests (`/api/terrain/heights` is the separate point-height endpoint), and the upstream edge answers zoom-out bursts -with HTTP 429 under load. `src/maps/terrain.js` hands Cesium a `Resource` +with HTTP 429 under load. `src/render/cesium/mapTerrain.js` hands Cesium a `Resource` whose retry policy (`src/maps/terrainRetry.js`) every derived tile fetch inherits: 429, 502, 503 and 504 replies retry up to three times, 750 ms doubling to a 15 s cap, with every retry waiting behind one shared cooldown @@ -6650,6 +6650,17 @@ request HTTPS tiles even on HTTP localhost, with the existing Content Security Policy unchanged. Ion attribution and Bing's per-tile credits are preserved; other ion imagery assets continue through the SDK's standard ion factory. +The imagery, terrain and 3D factories are the Cesium renderer's +(`src/render/cesium/mapImagery.js`, `mapTerrain.js`, `google3d.js`; the +package exports `./maps/imagery`, `./maps/terrain` and `./maps/3d` point +there). The catalog, the default registry and the controller are +Cesium-free: they reach those factories, and the viewer operations a +switch makes (imagery layers, terrain, the globe's visibility, tilesets), +through the map engine (`src/maps/engine.js`), which the Cesium renderer +provides as it loads (`src/render/cesium/mapEngine.js`). A viewer with no +renderer bound gets it, with the other unbound ports, from the package's +`./render/cesium/unbound` export. + The controller accepts other source registries without adding provider branches. Each instance caches source construction, ignores superseded scene changes and releases imagery layers/listeners on replacement. Destroy invalidates pending diff --git a/package.json b/package.json index 89ef24474..b3869d6cd 100644 --- a/package.json +++ b/package.json @@ -197,9 +197,9 @@ "./geography/neighborhoods": "./src/data/neighborhoodPolygons.js", "./maps/controller": "./src/maps/controller.js", "./maps/catalog": "./src/maps/catalog.js", - "./maps/imagery": "./src/maps/imagery.js", - "./maps/terrain": "./src/maps/terrain.js", - "./maps/3d": "./src/maps/google3d.js", + "./maps/imagery": "./src/render/cesium/mapImagery.js", + "./maps/terrain": "./src/render/cesium/mapTerrain.js", + "./maps/3d": "./src/render/cesium/google3d.js", "./maps/defaults": "./src/maps/defaultSources.js", "./voice/controller": "./src/voice/realtimeController.js", "./voice/control": "./src/voice/control.js", diff --git a/scripts/format-scope.json b/scripts/format-scope.json index e998893e2..7a27f1494 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -665,10 +665,14 @@ "src/maps/imageryComparison.js", "src/maps/credits.js", "src/maps/defaultSources.js", - "src/maps/google3d.js", - "src/maps/imagery.js", + "src/render/cesium/google3d.js", + "src/render/cesium/mapImagery.js", "src/maps/registry.js", - "src/maps/terrain.js", + "src/render/cesium/mapTerrain.js", + "src/maps/engine.js", + "src/maps/startupRoute.js", + "src/maps/attribution.js", + "src/render/cesium/mapEngine.js", "src/maps/terrainRetry.js", "src/maps/terrainRetry.test.mjs", "src/mapStackController.js", @@ -676,7 +680,7 @@ "src/mapStackChips.test.mjs", "src/mapStackUnavailableReason.test.mjs", "src/mapStartup.test.mjs", - "src/maps/sourceFactories.test.mjs", + "src/render/cesium/mapSources.test.mjs", "src/search/geospatial.js", "src/search/http.js", "src/search/defaults.js", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index 1a4e5ca21..dbe74defb 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -1052,7 +1052,8 @@ "src/render/baseTilesets.js", "src/render/cesium/imagery.js", "src/render/cesium/tileRequests.js", - "src/maps/google3d.js", + "src/render/cesium/google3d.js", + "src/maps/startupRoute.js", "src/sky/stars.js", "src/renderGovernor.js", "src/data/bundledJson.js", @@ -1839,7 +1840,7 @@ "src/render/cesium/unbound.js", "src/render/cesium/globe.js", "src/render/baseTilesets.js", - "src/maps/google3d.js", + "src/render/cesium/google3d.js", "src/render/cesium/imagery.js", "src/render/cesium/tileRequests.js", "src/render/cesium/iconSetPrimitive.js", @@ -1892,7 +1893,14 @@ "src/render/cesium/nativeClick.js", "src/render/input/router.js", "src/render/input/wheel.js", - "src/render/cesium/input.js" + "src/render/cesium/input.js", + "src/maps/engine.js", + "src/maps/attribution.js", + "src/maps/startupRoute.js", + "src/render/cesium/mapImagery.js", + "src/maps/terrainRetry.js", + "src/render/cesium/mapTerrain.js", + "src/render/cesium/mapEngine.js" ], "external": ["cesium"] }, @@ -2398,7 +2406,7 @@ "src/layers/traffic/lifecycle.js", "src/render/cesium/globe.js", "src/render/baseTilesets.js", - "src/maps/google3d.js", + "src/render/cesium/google3d.js", "src/render/cesium/imagery.js", "src/render/cesium/tileRequests.js", "src/layers/traffic/model.js", @@ -2538,7 +2546,7 @@ "cctv-layer": { "exports": ["./layers/cctv"], "modules": [ - "src/maps/google3d.js", + "src/render/cesium/google3d.js", "src/render/cesium/globe.js", "src/render/cesium/imagery.js", "src/render/cesium/tileRequests.js", @@ -3092,10 +3100,10 @@ "src/render/creditMarkup.js", "src/maps/defaultSources.js", "src/render/cesium/imagery.js", - "src/maps/google3d.js", - "src/maps/imagery.js", + "src/render/cesium/google3d.js", + "src/render/cesium/mapImagery.js", "src/maps/registry.js", - "src/maps/terrain.js", + "src/render/cesium/mapTerrain.js", "src/maps/terrainRetry.js", "src/keySetupCore.mjs", "src/localRequestGate.mjs", @@ -3120,7 +3128,10 @@ "src/data/pickRegistry.js", "src/render/cesium/input.js", "src/render/cesium/pickMemo.js", - "src/render/cesium/nativeClick.js" + "src/render/cesium/nativeClick.js", + "src/maps/attribution.js", + "src/maps/startupRoute.js", + "src/maps/engine.js" ], "external": ["cesium"] }, @@ -3733,10 +3744,10 @@ "src/maps/credits.js", "src/maps/defaultSources.js", "src/render/cesium/imagery.js", - "src/maps/google3d.js", - "src/maps/imagery.js", + "src/render/cesium/google3d.js", + "src/render/cesium/mapImagery.js", "src/maps/registry.js", - "src/maps/terrain.js", + "src/render/cesium/mapTerrain.js", "src/maps/terrainRetry.js", "src/navigationPolicy.js", "src/orbit.js", @@ -4273,7 +4284,11 @@ "src/render/cesium/internals.js", "src/render/cesium/tileRequests.js", "src/render/cesium/nativeClick.js", - "src/render/cesium/pickMemo.js" + "src/render/cesium/pickMemo.js", + "src/maps/startupRoute.js", + "src/maps/engine.js", + "src/maps/attribution.js", + "src/render/cesium/mapEngine.js" ], "external": [ "hls.js", @@ -4331,7 +4346,7 @@ "src/render/cesium/gpuIcons.js", "src/render/motion/iconMotion.js", "src/render/cesium/imagery.js", - "src/maps/google3d.js", + "src/render/cesium/google3d.js", "src/render/cesium/cameraControls.js", "src/render/cesium/follow.js", "src/data/bhoteKoshiIncidentPlaces.js", diff --git a/scripts/qa-terrain-429.mjs b/scripts/qa-terrain-429.mjs index 8164e34b5..8db513d2c 100644 --- a/scripts/qa-terrain-429.mjs +++ b/scripts/qa-terrain-429.mjs @@ -8,7 +8,7 @@ * answers HTTP 429 for most of them. This harness drives that burst, counts the * throttled responses, keeps the first 429's headers as evidence, and then * checks whether every throttled tile eventually loaded — the contract the - * client-side retry in `src/maps/terrain.js` provides. + * client-side retry in `src/render/cesium/mapTerrain.js` provides. * * Run against a keyless dev server (no Google or ion credentials): * env -u GOOGLE_MAPS_API_KEY -u CESIUM_ION_TOKEN npm run dev -- --port 4180 diff --git a/src/app/mapLifecycle.test.mjs b/src/app/mapLifecycle.test.mjs index 0ab2e7f39..6286ca71d 100644 --- a/src/app/mapLifecycle.test.mjs +++ b/src/app/mapLifecycle.test.mjs @@ -1,6 +1,7 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { MapStackController } from '../mapStackController.js'; +import '../render/cesium/mapEngine.js'; import { installRenderGovernor, uninstallRenderGovernor, diff --git a/src/app/scene.js b/src/app/scene.js index b4a397013..00057f3e4 100644 --- a/src/app/scene.js +++ b/src/app/scene.js @@ -8,7 +8,7 @@ import { trimStaleSceneCommands } from '../render/cesium/sceneCommandRelease.js' import { registerDataCredits } from '../data/dataCredits.js'; import { configureCreditKeyboardAccess } from '../creditKeyboard.js'; import { MapStackController } from '../mapStackController.js'; -import { loadPhotorealisticTileset } from '../mapStartup.js'; +import { loadPhotorealisticTileset } from '../render/cesium/google3d.js'; import { initLogoGaze } from '../logoGaze.js'; import { inputFor } from '../input/dispatcher.js'; import { diff --git a/src/data/telegeographySubmarineCables.test.mjs b/src/data/telegeographySubmarineCables.test.mjs index 16ddc73d4..870b5a925 100644 --- a/src/data/telegeographySubmarineCables.test.mjs +++ b/src/data/telegeographySubmarineCables.test.mjs @@ -5,6 +5,8 @@ import * as Cesium from 'cesium'; import { MAP_STACKS } from '../mapStackController.js'; import { fromDegrees, toLonLatH } from '../geo/ellipsoid.js'; import { bindRenderer } from '../render/rendererOf.js'; +// A viewer with no renderer bound reads its globe through the unbound port. +import '../render/cesium/globe.js'; import { bindFakeDraw } from '../testSupport/fakeDrawPort.mjs'; import { fakeCameraPort } from '../testSupport/fakeCameraPort.mjs'; import { fakeSceneFrame } from '../testSupport/fakeCesiumScene.mjs'; diff --git a/src/layers/recentImagery/index.test.mjs b/src/layers/recentImagery/index.test.mjs index 71cc71f4a..54f5145b3 100644 --- a/src/layers/recentImagery/index.test.mjs +++ b/src/layers/recentImagery/index.test.mjs @@ -4,6 +4,7 @@ import assert from 'node:assert/strict'; import { NO_IMAGERY_HOST } from '../../maps/imageryHost.js'; import { acquireImageryComparison } from '../../maps/imageryComparison.js'; import { MapSourceController } from '../../maps/controller.js'; +import '../../render/cesium/mapEngine.js'; import { createDefaultMapSources } from '../../maps/defaultSources.js'; import { resetPointerOwnership } from '../../data/inputOwnership.js'; import { initImageryBoxTool } from '../../ui/imageryBoxTool.js'; diff --git a/src/mapStartup.js b/src/mapStartup.js index 48f56b125..dc5c1ac0f 100644 --- a/src/mapStartup.js +++ b/src/mapStartup.js @@ -1,4 +1 @@ -export { - selectMapStartupRoute, - loadPhotorealisticTileset, -} from './maps/google3d.js'; +export { selectMapStartupRoute } from './maps/startupRoute.js'; diff --git a/src/mapStartup.test.mjs b/src/mapStartup.test.mjs index 9d438643d..f95d09780 100644 --- a/src/mapStartup.test.mjs +++ b/src/mapStartup.test.mjs @@ -3,10 +3,8 @@ import assert from 'node:assert/strict'; import { readFileSync } from 'node:fs'; import vm from 'node:vm'; import { createGoogleTokenSource } from './maps/googleTokens.js'; -import { - loadPhotorealisticTileset, - selectMapStartupRoute, -} from './mapStartup.js'; +import { selectMapStartupRoute } from './mapStartup.js'; +import { loadPhotorealisticTileset } from './render/cesium/google3d.js'; function fakeCesium(outcomes = []) { const calls = []; diff --git a/src/maps/attribution.js b/src/maps/attribution.js new file mode 100644 index 000000000..71f5a201e --- /dev/null +++ b/src/maps/attribution.js @@ -0,0 +1,8 @@ +/** + * @module maps/attribution + * @description The on-map credits of the map stacks' sources. + */ + +// Attribution and service rights are documented in DATA_SOURCES.md. +export const ESRI_ATTRIBUTION_HTML = + 'Powered by Esri'; diff --git a/src/maps/catalog.js b/src/maps/catalog.js index 238263ba9..d437d7134 100644 --- a/src/maps/catalog.js +++ b/src/maps/catalog.js @@ -1,4 +1,8 @@ -import * as Cesium from 'cesium'; +/** + * The map stacks the maps panel offers, free of renderer code: an `ion` stack's + * `style` is the Cesium ion world imagery asset it shows (2, aerial; 3, + * aerial with labels), the values of Cesium's `IonWorldImageryStyle`. + */ export const MAP_STACKS = [ { id: 'photoreal', @@ -12,7 +16,7 @@ export const MAP_STACKS = [ label: 'Bing Aerial', // i18n-ignore: imagery product name shortLabel: 'Aerial', kind: 'ion', - style: Cesium.IonWorldImageryStyle.AERIAL, + style: 2, requiresIon: true, }, { @@ -20,7 +24,7 @@ export const MAP_STACKS = [ label: 'Bing Labels', // i18n-ignore: imagery product name shortLabel: 'Labels', kind: 'ion', - style: Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS, + style: 3, requiresIon: true, }, { diff --git a/src/maps/controller.js b/src/maps/controller.js index 2b43de4ee..97aa9ceb7 100644 --- a/src/maps/controller.js +++ b/src/maps/controller.js @@ -1,10 +1,7 @@ import { indexMapSources } from './registry.js'; -import * as Cesium from 'cesium'; import { createMapCredits } from './credits.js'; -// A viewer of a caller's own gets its credits port (and camera) from the -// factories this loads. -import '../render/cesium/camera.js'; -import { markBaseTileset } from '../render/cesium/globe.js'; +import { mapEngine } from './engine.js'; +import { markBaseTileset } from '../render/baseTilesets.js'; import { acquireImageryComparison } from './imageryComparison.js'; /** @@ -25,7 +22,12 @@ const resolved = (provider, effectiveStackId) => ({ fallbackMessage: null, }); -/** Coordinate source lifetimes and scene changes; the registry owns provider choices. */ +/** + * Coordinate source lifetimes and scene changes; the registry owns provider + * choices. The scene changes go through the renderer's map engine + * (`engine.js`), which a viewer with no renderer bound gets once its owner + * has loaded the package's `./render/cesium/unbound` export. + */ export class MapSourceController { constructor( viewer, @@ -34,11 +36,13 @@ export class MapSourceController { initialStack, onChange = null, onError = null, - requestRender = () => viewer?.scene?.requestRender?.(), - createImageryLayer = (provider) => new Cesium.ImageryLayer(provider), + engine = mapEngine(), + requestRender = () => engine.requestRender(viewer), + createImageryLayer = (provider) => engine.createImageryLayer(provider), }, ) { this.viewer = viewer; + this._engine = engine; this._registry = registry; this._sources = indexMapSources(registry.sources); this._activeId = this.isStackAvailable(initialStack) @@ -110,10 +114,11 @@ export class MapSourceController { /** Return the shown supplied or controller-owned tileset, if any. */ getImageryHostTileset() { if (this._destroyed) return null; + const shown = this._engine.tilesetShown; for (const source of this._sources.values()) - if (source.tileset?.show === true) return source.tileset; + if (shown(source.tileset)) return source.tileset; for (const tileset of this._ownedTilesets) - if (tileset.show === true) return tileset; + if (shown(tileset)) return tileset; return null; } /** @@ -124,9 +129,9 @@ export class MapSourceController { */ getDrapeSurface() { if (this._destroyed) return null; - if (this.viewer?.scene?.globe?.show === true) return 'globe'; + if (this._engine.globeShown(this.viewer)) return 'globe'; const tileset = this.getImageryHostTileset(); - return tileset && !tileset.isDestroyed?.() ? 'tileset' : 'none'; + return tileset && !this._engine.isDestroyed(tileset) ? 'tileset' : 'none'; } getActiveId() { return this._activeId; @@ -285,23 +290,24 @@ export class MapSourceController { } if (gen !== this._switchGen) return; if (!source.tileset && !this._ownedTilesets.has(tileset)) { - tileset.show = false; + this._engine.showTileset(tileset, false); markBaseTileset(tileset); - this.viewer.scene.primitives.add(tileset); + this._engine.addTileset(this.viewer, tileset); this._ownedTilesets.add(tileset); } this._removeImageryLayer(); this._credits.show(source.credit || null); this._showTileset(tileset); - this.viewer.scene.globe.show = false; + this._engine.setGlobeShown(this.viewer, false); // Terrain is intentionally untouched while the globe is hidden. } _showTileset(active) { + const show = this._engine.showTileset; for (const source of this._sources.values()) - if (source.tileset) source.tileset.show = source.tileset === active; + if (source.tileset) show(source.tileset, source.tileset === active); for (const tileset of this._ownedTilesets) - tileset.show = tileset === active; + show(tileset, tileset === active); } async _activateGlobeStack(stack, gen) { @@ -317,7 +323,7 @@ export class MapSourceController { this._removeImageryLayer(); this._imageryLayer = this._createImageryLayer(resolution.provider); this._activeImageryProvider = resolution.provider; - this.viewer.imageryLayers.add(this._imageryLayer, 0); + this._engine.addImageryLayer(this.viewer, this._imageryLayer, 0); } const source = this._sources.get(resolution.effectiveStackId); this._credits.show(source?.credit || null); @@ -327,7 +333,7 @@ export class MapSourceController { this._removeImageryErrorListener = null; this._watchProvider(resolution, gen); this._showTileset(null); - this.viewer.scene.globe.show = true; + this._engine.setGlobeShown(this.viewer, true); this._activeId = resolution.effectiveStackId; this._activeResolution = resolution; if (source?.terrain && source.terrain.id !== this._terrainMode) { @@ -349,8 +355,7 @@ export class MapSourceController { } _applyTerrain(result) { - if (result.terrain) this.viewer.scene.setTerrain(result.terrain); - else this.viewer.terrainProvider = result.provider; + this._engine.applyTerrain(this.viewer, result); this._terrainFallback = result.fallback ? result : null; if (this._replacedTerrain && this._replacedTerrain !== result) { this._dispose(this._replacedTerrain.provider); @@ -379,7 +384,9 @@ export class MapSourceController { async _retryFallbacks() { const resolution = this._activeResolution; - const flat = this.viewer.scene.globe.show ? this._terrainFallback : null; + const flat = this._engine.globeShown(this.viewer) + ? this._terrainFallback + : null; const id = resolution?.fallbackFor; let terrain = flat && this._sources.get(this._activeId)?.terrain; if (terrain?.id !== this._terrainMode) terrain = null; @@ -460,7 +467,10 @@ export class MapSourceController { return Boolean(real && !real.fallback); } this._terrainProviders.set(terrain.id, Promise.resolve(real)); - if (this._terrainFallback === flat && this.viewer.scene.globe.show) { + if ( + this._terrainFallback === flat && + this._engine.globeShown(this.viewer) + ) { this._applyTerrain(real); this._dispose(flat.provider); this._requestRender('map-stack'); @@ -540,50 +550,52 @@ export class MapSourceController { const fallback = this._sources.get( resolution.effectiveStackId, )?.tileFailureFallback; - const errorEvent = resolution.provider?.errorEvent; - if (!fallback || !errorEvent?.addEventListener) return; + if (!fallback) return; let failures = 0; let pending = false; - this._removeImageryErrorListener = errorEvent.addEventListener((error) => { - if ( - gen !== this._switchGen || - this._activeImageryProvider !== resolution.provider - ) - return; - const retryCount = Number(error?.timesRetried); - failures = - Number.isInteger(retryCount) && retryCount >= 0 - ? Math.max(failures + 1, retryCount + 1) - : failures + 1; - if (failures < fallback.threshold || pending) return; - pending = true; - this._onError?.( - fallback.message, - this.getStack(resolution.effectiveStackId), - ); - const expectedGen = this._switchGen + 1; - void this.setStack(fallback.id, { silent: true, [AUTOMATIC]: true }) - .then((state) => { - if ( - !this._destroyed && - this._switchGen === expectedGen && - state?.activeId === fallback.id - ) { - this._lastError = fallback.message; - this._emitChange('error'); - } - }) - .finally(() => { - pending = false; - }); - }); + this._removeImageryErrorListener = this._engine.onTileError( + resolution.provider, + (error) => { + if ( + gen !== this._switchGen || + this._activeImageryProvider !== resolution.provider + ) + return; + const retryCount = Number(error?.timesRetried); + failures = + Number.isInteger(retryCount) && retryCount >= 0 + ? Math.max(failures + 1, retryCount + 1) + : failures + 1; + if (failures < fallback.threshold || pending) return; + pending = true; + this._onError?.( + fallback.message, + this.getStack(resolution.effectiveStackId), + ); + const expectedGen = this._switchGen + 1; + void this.setStack(fallback.id, { silent: true, [AUTOMATIC]: true }) + .then((state) => { + if ( + !this._destroyed && + this._switchGen === expectedGen && + state?.activeId === fallback.id + ) { + this._lastError = fallback.message; + this._emitChange('error'); + } + }) + .finally(() => { + pending = false; + }); + }, + ); } _removeImageryLayer() { this._removeImageryErrorListener?.(); this._removeImageryErrorListener = null; if (this._imageryLayer) - this.viewer.imageryLayers.remove(this._imageryLayer, true); + this._engine.removeImageryLayer(this.viewer, this._imageryLayer); this._imageryLayer = null; this._activeImageryProvider = null; this._activeResolution = null; @@ -591,8 +603,7 @@ export class MapSourceController { _dispose(value) { if (!value || this._disposed.has(value)) return; this._disposed.add(value); - if (typeof value.destroy === 'function' && !value.isDestroyed?.()) - value.destroy(); + this._engine.release(value); } destroy() { if (this._destroyed) return; @@ -620,7 +631,7 @@ export class MapSourceController { () => {}, ); for (const tileset of this._ownedTilesets) { - this.viewer.scene.primitives.remove(tileset); + this._engine.removeTileset(this.viewer, tileset); this._dispose(tileset); } for (const promise of this._tilesets.values()) diff --git a/src/maps/controller.test.mjs b/src/maps/controller.test.mjs index 657257b6a..ccd9ba673 100644 --- a/src/maps/controller.test.mjs +++ b/src/maps/controller.test.mjs @@ -1,6 +1,8 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { MapSourceController } from './controller.js'; +// The controller switches stacks through the Cesium map engine. +import '../render/cesium/mapEngine.js'; import { createDefaultMapSources } from './defaultSources.js'; import { bindRenderer } from '../render/rendererOf.js'; diff --git a/src/maps/defaultSources.js b/src/maps/defaultSources.js index a12aea29a..75b14d78a 100644 --- a/src/maps/defaultSources.js +++ b/src/maps/defaultSources.js @@ -2,28 +2,31 @@ import { MAP_STACKS } from './catalog.js'; import { photorealUnavailableReason } from './availability.js'; import { keySetupRequirementEnvVars } from '../keySetupCore.mjs'; import { t } from '../i18n/index.js'; -import { - createOsmImagery, - createEsriImagery, - createIonImagery, - ESRI_ATTRIBUTION_HTML, -} from './imagery.js'; -import { createWorldTerrain, createKeylessTerrain } from './terrain.js'; +import { mapEngine } from './engine.js'; +import { ESRI_ATTRIBUTION_HTML } from './attribution.js'; -/** Select sources and setup guidance without putting provider branches in the controller. */ +/** + * Select sources and setup guidance without putting provider branches in the + * controller. Each source builds its imagery and terrain through the + * renderer's map engine (`engine.js`), or the `engine` given, when it is + * first shown. + */ export function createDefaultMapSources({ googleTileset = null, cesiumToken = '', googleApiKey = '', + engine = null, } = {}) { + // The engine given, else the one the renderer provided, read when used. + const engineOf = () => engine ?? mapEngine(); const ionToken = String(cesiumToken || '').trim(); const hasIon = Boolean(ionToken); const hasGoogle = Boolean(String(googleApiKey || '').trim()); const terrain = { id: hasIon ? 'world' : 'keyless', create: hasIon - ? (request) => createWorldTerrain(ionToken, request) - : createKeylessTerrain, + ? (request) => engineOf().terrain.world(ionToken, request) + : () => engineOf().terrain.keyless(), }; return { defaultId: googleTileset ? 'photoreal' : 'esri-imagery', @@ -52,10 +55,10 @@ export function createDefaultMapSources({ }; const imagery = descriptor.kind === 'ion' - ? () => createIonImagery(descriptor.style, ionToken) + ? () => engineOf().imagery.ion(descriptor.style, ionToken) : descriptor.id === 'osm' - ? createOsmImagery - : createEsriImagery; + ? () => engineOf().imagery.osm() + : () => engineOf().imagery.esri(); return { ...common, imagery, diff --git a/src/maps/engine.js b/src/maps/engine.js new file mode 100644 index 000000000..73530852f --- /dev/null +++ b/src/maps/engine.js @@ -0,0 +1,33 @@ +/** + * @module maps/engine + * @description What the map stacks need from the renderer that no contract + * port gives yet: the providers each stack's imagery and terrain come from, + * and the scene operations the map source controller (`controller.js`) + * switches stacks with. Cesium-free: the renderer adapter provides it + * as it loads (the Cesium one in `src/render/cesium/mapEngine.js`, loaded by + * the application's renderer and by the package's `./render/cesium/unbound` + * export), and the map code asks for it when it first needs it. + */ + +let provided = null; + +/** + * Provide the map engine; a later call replaces it. + * @param {object} engine + */ +export function provideMapEngine(engine) { + provided = engine; +} + +/** + * The map engine the renderer adapter provided. + * @returns {object} + * @throws {Error} When no adapter has provided one yet. + */ +export function mapEngine() { + if (!provided) + throw new Error( + 'No map engine: load the renderer, or the package export ./render/cesium/unbound, first', + ); + return provided; +} diff --git a/src/maps/map-subscription-ownership.test.mjs b/src/maps/map-subscription-ownership.test.mjs index bd10cce60..943d67ce6 100644 --- a/src/maps/map-subscription-ownership.test.mjs +++ b/src/maps/map-subscription-ownership.test.mjs @@ -1,6 +1,8 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { MapSourceController } from './controller.js'; +// The controller switches stacks through the Cesium map engine. +import '../render/cesium/mapEngine.js'; function fixture() { return new MapSourceController( { diff --git a/src/maps/startupRoute.js b/src/maps/startupRoute.js new file mode 100644 index 000000000..6a175f2b4 --- /dev/null +++ b/src/maps/startupRoute.js @@ -0,0 +1,20 @@ +/** + * @module maps/startupRoute + * @description Which route the photoreal base starts on, from the + * credentials configured; Cesium-free. + */ +const clean = (value) => String(value || '').trim(); + +/** + * Decide which map provider can deliver the best startup experience. + * @param {{googleApiKey?: string, cesiumToken?: string}} credentials + * @returns {'google-direct'|'google-ion'|'osm'} + */ +export function selectMapStartupRoute({ + googleApiKey = '', + cesiumToken = '', +} = {}) { + if (clean(googleApiKey)) return 'google-direct'; + if (clean(cesiumToken)) return 'google-ion'; + return 'osm'; +} diff --git a/src/maps/terrainRetry.test.mjs b/src/maps/terrainRetry.test.mjs index 69ed532b6..297dc2eed 100644 --- a/src/maps/terrainRetry.test.mjs +++ b/src/maps/terrainRetry.test.mjs @@ -12,7 +12,7 @@ import { import { KEYLESS_TERRAIN_URL, createKeylessTerrainResource, -} from './terrain.js'; +} from '../render/cesium/mapTerrain.js'; const START = 1_700_000_000_000; diff --git a/src/render/cesium/appRenderer.js b/src/render/cesium/appRenderer.js index 05c7a2acf..6d4bdd6ce 100644 --- a/src/render/cesium/appRenderer.js +++ b/src/render/cesium/appRenderer.js @@ -22,6 +22,8 @@ import { CONTRACT_VERSION } from '../contract/index.js'; import { bindRenderer } from '../rendererOf.js'; import { createCesiumInput } from './input.js'; import { cesiumCapabilities, createCesiumPorts } from './ports.js'; +// The application's map stacks switch through the Cesium map engine. +import './mapEngine.js'; /** @typedef {import('../contract/renderer').Renderer} TransitionalRenderer */ diff --git a/src/render/cesium/globe.js b/src/render/cesium/globe.js index 00ef48dd7..9b35cd495 100644 --- a/src/render/cesium/globe.js +++ b/src/render/cesium/globe.js @@ -15,7 +15,7 @@ * the scene has no part for (stars without a sky box, say) is kept as set. */ import * as Cesium from 'cesium'; -import { loadPhotorealisticTileset } from '../../maps/google3d.js'; +import { loadPhotorealisticTileset } from './google3d.js'; import { provideUnboundGlobe } from '../rendererOf.js'; import { isBaseTileset, markBaseTileset } from '../baseTilesets.js'; import { listenerList, uncaught } from './common.js'; diff --git a/src/maps/google3d.js b/src/render/cesium/google3d.js similarity index 91% rename from src/maps/google3d.js rename to src/render/cesium/google3d.js index aab45ea35..fc578ec56 100644 --- a/src/maps/google3d.js +++ b/src/render/cesium/google3d.js @@ -1,18 +1,11 @@ -const clean = (value) => String(value || '').trim(); - /** - * Decide which map provider can deliver the best startup experience. - * @param {{googleApiKey?: string, cesiumToken?: string}} credentials - * @returns {'google-direct'|'google-ion'|'osm'} + * @module render/cesium/google3d + * @description Google Photorealistic 3D Tiles for the Cesium renderer, by + * the routes `selectMapStartupRoute` (`src/maps/startupRoute.js`) names. */ -export function selectMapStartupRoute({ - googleApiKey = '', - cesiumToken = '', -} = {}) { - if (clean(googleApiKey)) return 'google-direct'; - if (clean(cesiumToken)) return 'google-ion'; - return 'osm'; -} +export { selectMapStartupRoute } from '../../maps/startupRoute.js'; + +const clean = (value) => String(value || '').trim(); /** * Load Google Photorealistic 3D Tiles through direct Google access when diff --git a/src/render/cesium/mapEngine.js b/src/render/cesium/mapEngine.js new file mode 100644 index 000000000..490a14556 --- /dev/null +++ b/src/render/cesium/mapEngine.js @@ -0,0 +1,80 @@ +/** + * @module render/cesium/mapEngine + * @description The Cesium map engine (`src/maps/engine.js`): the providers + * the map stacks' imagery and terrain come from (`mapImagery.js`, + * `mapTerrain.js`), and the viewer operations the map source controller + * switches stacks with. Provided as this module loads. + */ +import * as Cesium from 'cesium'; +import { provideMapEngine } from '../../maps/engine.js'; +import { + createEsriImagery, + createIonImagery, + createOsmImagery, +} from './mapImagery.js'; +import { createKeylessTerrain, createWorldTerrain } from './mapTerrain.js'; + +export const cesiumMapEngine = Object.freeze({ + imagery: Object.freeze({ + osm: createOsmImagery, + esri: createEsriImagery, + /** `style`: the ion world imagery asset (`MAP_STACKS`' `style`). */ + ion: createIonImagery, + }), + terrain: Object.freeze({ + world: createWorldTerrain, + keyless: createKeylessTerrain, + }), + /** The layer a globe stack's imagery provider draws through. */ + createImageryLayer: (provider) => new Cesium.ImageryLayer(provider), + requestRender(viewer) { + viewer?.scene?.requestRender?.(); + }, + globeShown: (viewer) => viewer?.scene?.globe?.show === true, + setGlobeShown(viewer, shown) { + viewer.scene.globe.show = shown; + }, + addTileset(viewer, tileset) { + viewer.scene.primitives.add(tileset); + }, + removeTileset(viewer, tileset) { + viewer.scene.primitives.remove(tileset); + }, + tilesetShown: (tileset) => tileset?.show === true, + showTileset(tileset, shown) { + tileset.show = shown; + }, + /** Below every other imagery layer, at `index`. */ + addImageryLayer(viewer, layer, index) { + viewer.imageryLayers.add(layer, index); + }, + /** Removed and destroyed. */ + removeImageryLayer(viewer, layer) { + viewer.imageryLayers.remove(layer, true); + }, + /** A terrain factory's result: `{terrain}` or `{provider}`. */ + applyTerrain(viewer, result) { + if (result.terrain) viewer.scene.setTerrain(result.terrain); + else viewer.terrainProvider = result.provider; + }, + /** + * Hear an imagery provider's failed tile requests, each with the times + * Cesium retried it; null when the provider reports none. + * @returns {(() => void) | null} Stop hearing them. + */ + onTileError(provider, listener) { + const errorEvent = provider?.errorEvent; + if (!errorEvent?.addEventListener) return null; + return errorEvent.addEventListener((error) => + listener({ timesRetried: error?.timesRetried }), + ); + }, + isDestroyed: (value) => value?.isDestroyed?.() === true, + /** Destroy a provider or tileset unless it is already destroyed. */ + release(value) { + if (typeof value?.destroy === 'function' && !value.isDestroyed?.()) + value.destroy(); + }, +}); + +provideMapEngine(cesiumMapEngine); diff --git a/src/maps/imagery.js b/src/render/cesium/mapImagery.js similarity index 89% rename from src/maps/imagery.js rename to src/render/cesium/mapImagery.js index d151b6ce6..bd07a4ea4 100644 --- a/src/maps/imagery.js +++ b/src/render/cesium/mapImagery.js @@ -1,8 +1,11 @@ +/** + * @module render/cesium/mapImagery + * @description The map stacks' imagery for the Cesium renderer: OSM, Esri + * World Imagery and Cesium ion's world imagery (Bing over HTTPS). + */ import * as Cesium from 'cesium'; -// Attribution and service rights are documented in DATA_SOURCES.md. -export const ESRI_ATTRIBUTION_HTML = - 'Powered by Esri'; +export { ESRI_ATTRIBUTION_HTML } from '../../maps/attribution.js'; export function createOsmImagery() { return new Cesium.OpenStreetMapImageryProvider({ diff --git a/src/maps/sourceFactories.test.mjs b/src/render/cesium/mapSources.test.mjs similarity index 93% rename from src/maps/sourceFactories.test.mjs rename to src/render/cesium/mapSources.test.mjs index 3f1edc7ba..6aeb9d546 100644 --- a/src/maps/sourceFactories.test.mjs +++ b/src/render/cesium/mapSources.test.mjs @@ -1,9 +1,29 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import * as Cesium from 'cesium'; -import { createIonImagery } from './imagery.js'; -import { createWorldTerrain, createKeylessTerrain } from './terrain.js'; -import { createDefaultMapSources } from './defaultSources.js'; +import { createIonImagery } from './mapImagery.js'; +import { createWorldTerrain, createKeylessTerrain } from './mapTerrain.js'; +import { createDefaultMapSources } from '../../maps/defaultSources.js'; +import { MAP_STACKS } from '../../maps/catalog.js'; +import { mapEngine } from '../../maps/engine.js'; +import { cesiumMapEngine } from './mapEngine.js'; + +test('loading the Cesium map engine provides it to the map stacks', () => { + assert.equal(mapEngine(), cesiumMapEngine); +}); + +test('ion stacks name the Cesium ion world imagery assets', () => { + const styles = Object.fromEntries( + MAP_STACKS.filter(({ kind }) => kind === 'ion').map(({ id, style }) => [ + id, + style, + ]), + ); + assert.deepEqual(styles, { + 'bing-aerial': Cesium.IonWorldImageryStyle.AERIAL, + 'bing-labels': Cesium.IonWorldImageryStyle.AERIAL_WITH_LABELS, + }); +}); test('Esri uses Re:Earth without keys and preserves ion terrain when configured', async () => { const originalTerrain = Cesium.CesiumTerrainProvider.fromUrl; @@ -22,7 +42,6 @@ test('Esri uses Re:Earth without keys and preserves ion terrain when configured' ); assert.equal(esri.available, true); assert.equal(esri.terrain.id, 'keyless'); - assert.equal(esri.terrain.create, createKeylessTerrain); await esri.terrain.create(); // A Resource, not a bare URL: the retry policy rides on it (terrainRetry.js). assert.equal(calls.length, 1); diff --git a/src/maps/terrain.js b/src/render/cesium/mapTerrain.js similarity index 87% rename from src/maps/terrain.js rename to src/render/cesium/mapTerrain.js index d2f214700..d062655cd 100644 --- a/src/maps/terrain.js +++ b/src/render/cesium/mapTerrain.js @@ -1,5 +1,11 @@ +/** + * @module render/cesium/mapTerrain + * @description The map stacks' terrain for the Cesium renderer: Cesium + * World Terrain through ion, or Re:Earth's keyless terrain with its tile + * retry policy (`src/maps/terrainRetry.js`). + */ import * as Cesium from 'cesium'; -import { createTerrainRetryPolicy } from './terrainRetry.js'; +import { createTerrainRetryPolicy } from '../../maps/terrainRetry.js'; /** Re:Earth / Mapterhorn ellipsoidal quantized mesh, CC BY 4.0. */ export const KEYLESS_TERRAIN_URL = diff --git a/src/render/cesium/unbound.js b/src/render/cesium/unbound.js index e308bb488..b05d0be6b 100644 --- a/src/render/cesium/unbound.js +++ b/src/render/cesium/unbound.js @@ -3,13 +3,15 @@ * @description What to load, once, before handing the Cesium-free * layers a Cesium viewer with no renderer bound: the factories * that build a camera, credits, effects, draw, frame, globe, input and query - * port over such a viewer when code first asks for one, and a click's own - * Cesium picks (`rendererOf.js`). + * port over such a viewer when code first asks for one, a click's own + * Cesium picks (`rendererOf.js`), and the map engine the map stacks switch + * through (`src/maps/engine.js`). */ import './camera.js'; import './effects.js'; import './frame.js'; import './globe.js'; import './input.js'; +import './mapEngine.js'; import './nativeClick.js'; import './query.js'; diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 727c91d18..1e84430f1 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -4,11 +4,6 @@ "src/app/scene.js", "src/app/viewer.js", "src/data/geoImportPins.js", - "src/maps/catalog.js", - "src/maps/controller.js", - "src/maps/google3d.js", - "src/maps/imagery.js", - "src/maps/terrain.js", "src/sky/starrySky.js", "src/ui/applicationShell.js" ] diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index 30d38452f..0fe6536dc 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -171,6 +171,9 @@ const CAMERA_FROM_CALLER = new Set([ // Its ground snap, mesh floor sampler, annotation resolver and location // framing ask the camera, globe and query ports; it loads no factory. './application/operations', + // It shows its source's credit through `findCredits`, and switches stacks + // through the map engine that `./render/cesium/unbound` provides too. + './maps/controller', ]); const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')); From e6d9ec06369dcbf9fd375cb4936287c049aeb753 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 9 Nov 2026 12:31:46 -0800 Subject: [PATCH 2/4] Starry sky and the application viewer move into the Cesium adapter src/sky/starrySky.js and src/app/viewer.js are Cesium through and through, so they move into the adapter as src/render/cesium/starrySky.js and applicationViewer.js; the ./application/viewer export points there. The celestial ring's precise ICRF rotation reaches the shell through a Cesium-free registry (src/sky/icrf.js) that the sky provides as it loads; the application's renderer loads it, and so does ./render/cesium/unbound. Both files leave the Cesium allow-list. --- docs/CODE-BOUNDARIES.md | 4 +++ docs/CURRENT-STATE.md | 5 ++-- package.json | 2 +- scripts/format-scope.json | 5 ++-- scripts/package-boundaries.json | 25 +++++++++++------ scripts/qa-sky-model-lighting.mjs | 6 ++-- src/app/application.test.mjs | 5 ++-- src/data/local_data/sky/README.md | 2 +- src/render/cesium/appRenderer.js | 2 +- .../cesium/applicationViewer.js} | 4 +-- src/{sky => render/cesium}/starrySky.js | 24 +++++++++------- src/{sky => render/cesium}/starrySky.test.mjs | 24 ++++++++++++++++ src/render/cesium/unbound.js | 6 ++-- src/render/cesiumAllowList.json | 2 -- src/sky/icrf.js | 28 +++++++++++++++++++ src/ui/applicationShell.js | 2 +- src/ui/visualEffects.test.mjs | 2 +- 17 files changed, 110 insertions(+), 38 deletions(-) rename src/{app/viewer.js => render/cesium/applicationViewer.js} (94%) rename src/{sky => render/cesium}/starrySky.js (95%) rename src/{sky => render/cesium}/starrySky.test.mjs (90%) create mode 100644 src/sky/icrf.js diff --git a/docs/CODE-BOUNDARIES.md b/docs/CODE-BOUNDARIES.md index c8cdf742b..3df85b7a4 100644 --- a/docs/CODE-BOUNDARIES.md +++ b/docs/CODE-BOUNDARIES.md @@ -468,6 +468,10 @@ release listeners; pending action feedback is limited to its current owner. rendering, HUD and share operations. `src/standalone/controls.js` provides the running application's instances. The shell imports no standalone bootstrap or concrete live layer implementation. +The celestial ring's precise ICRF rotation comes from the renderer +(`src/sky/icrf.js`): the application's renderer provides it; a shell given a +viewer with no renderer bound gets it once `./render/cesium/unbound` has loaded, and +falls back to the TEME approximation until then. Panel layout, position/drag, notices, recording and deferred UI work have separate owners with synchronous cleanup. Existing scene, share and HUD engines retain their entry points. `ui/styles` loads the ordered stylesheet entry; component diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 8987bd96e..36999824d 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1502,10 +1502,11 @@ The clear control presents busy state while its existing action owns the transac ## Sky background -`src/sky/starrySky.js` fills Cesium's `Scene#skyBox` slot with 9,096 Yale +`src/render/cesium/starrySky.js` fills Cesium's `Scene#skyBox` slot with 9,096 Yale Bright Star Catalogue stars and a soft ESO/S. Brunier Milky Way. Both layers rotate from ICRF/J2000 into the Earth-fixed frame at the scene clock, with -a TEME fallback while Cesium's IAU 2006 tables load. Bundled assets and +a TEME fallback while Cesium's IAU 2006 tables load. The precise rotation reaches +Cesium-free code (the celestial ring) through `src/sky/icrf.js`. Bundled assets and their provenance are documented in `src/data/local_data/sky/README.md`. Anime fades out the Milky Way with its style intensity to avoid cel-shaded diff --git a/package.json b/package.json index b3869d6cd..3938f784f 100644 --- a/package.json +++ b/package.json @@ -89,7 +89,7 @@ "./infrastructure/geojson": "./src/data/localGeojsonCore.js", "./infrastructure/lod": "./src/data/localGeojsonLod.js", "./application": "./src/app/application.js", - "./application/viewer": "./src/app/viewer.js", + "./application/viewer": "./src/render/cesium/applicationViewer.js", "./build/vite": { "node": "./build/vite.js" }, diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 7a27f1494..d025857ca 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -84,7 +84,8 @@ "src/app/application.test.mjs", "src/app/mapLifecycle.test.mjs", "src/app/startupCamera.test.mjs", - "src/app/viewer.js", + "src/render/cesium/applicationViewer.js", + "src/sky/icrf.js", "src/app/atmosphereCompat.test.mjs", "src/standalone/application.js", "src/standalone/controls.js", @@ -1145,7 +1146,7 @@ "scripts/build-bright-stars.mjs", "scripts/build-milky-way.mjs", "src/sky/stars.test.mjs", - "src/sky/starrySky.test.mjs", + "src/render/cesium/starrySky.test.mjs", "src/tooling/skyAssets.test.mjs", "src/tooling/skyAssets.paintOut.test.mjs", "scripts/qa-anime-sky.mjs", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index dbe74defb..adeec3baa 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -204,12 +204,13 @@ "viewer": { "exports": ["./application/viewer"], "modules": [ - "src/app/viewer.js", + "src/render/cesium/applicationViewer.js", "src/app/atmosphereCompat.js", - "src/sky/starrySky.js", + "src/render/cesium/starrySky.js", "src/sky/stars.js", "src/data/bundledJson.js", - "src/renderGovernor.js" + "src/renderGovernor.js", + "src/sky/icrf.js" ], "external": ["cesium"] }, @@ -1045,7 +1046,6 @@ "src/styles/surveillance.js", "src/styles/thermal.js", "src/ui/applicationShell.js", - "src/sky/starrySky.js", "src/render/cesium/effects.js", "src/render/cesium/screenModulation.js", "src/render/cesium/globe.js", @@ -1286,7 +1286,8 @@ "src/render/cesium/input.js", "src/render/input/wheel.js", "src/render/cesium/ctrlWheelZoom.js", - "src/render/input/router.js" + "src/render/input/router.js", + "src/sky/icrf.js" ], "external": ["cesium", "vue", "pinia", "vue-i18n"] }, @@ -1900,7 +1901,12 @@ "src/render/cesium/mapImagery.js", "src/maps/terrainRetry.js", "src/render/cesium/mapTerrain.js", - "src/render/cesium/mapEngine.js" + "src/render/cesium/mapEngine.js", + "src/data/bundledJson.js", + "src/renderGovernor.js", + "src/sky/icrf.js", + "src/sky/stars.js", + "src/render/cesium/starrySky.js" ], "external": ["cesium"] }, @@ -3342,9 +3348,9 @@ "src/app/surfaceServices.js", "src/app/tools.js", "src/data/followed.js", - "src/app/viewer.js", + "src/render/cesium/applicationViewer.js", "src/render/cesium/ctrlWheelZoom.js", - "src/sky/starrySky.js", + "src/render/cesium/starrySky.js", "src/sky/stars.js", "src/app/atmosphereCompat.js", "src/bloom.js", @@ -4288,7 +4294,8 @@ "src/maps/startupRoute.js", "src/maps/engine.js", "src/maps/attribution.js", - "src/render/cesium/mapEngine.js" + "src/render/cesium/mapEngine.js", + "src/sky/icrf.js" ], "external": [ "hls.js", diff --git a/scripts/qa-sky-model-lighting.mjs b/scripts/qa-sky-model-lighting.mjs index 2f401506b..74514842c 100644 --- a/scripts/qa-sky-model-lighting.mjs +++ b/scripts/qa-sky-model-lighting.mjs @@ -32,13 +32,15 @@ try { const results = await page.evaluate(async () => { window.CESIUM_BASE_URL = '/cesium/'; // Use StarrySky's exact Vite dependency URL, including its version query. - const source = await fetch('/src/sky/starrySky.js').then((r) => r.text()); + const source = await fetch('/src/render/cesium/starrySky.js').then((r) => + r.text(), + ); const cesiumUrl = source.match( /from ["']([^"']*\/cesium\.js[^"']*)["']/, )?.[1]; if (!cesiumUrl) throw new Error('run against the Vite dev server'); const C = await import(cesiumUrl); - const { StarrySky } = await import('/src/sky/starrySky.js'); + const { StarrySky } = await import('/src/render/cesium/starrySky.js'); const time = C.JulianDate.fromIso8601('2026-10-19T00:00:00Z'); const results = {}; for (const kind of ['black', 'starry', 'white']) { diff --git a/src/app/application.test.mjs b/src/app/application.test.mjs index d756e967c..88722edff 100644 --- a/src/app/application.test.mjs +++ b/src/app/application.test.mjs @@ -222,8 +222,9 @@ test('the separate viewer export imports without constructing a browser viewer', }); test('the viewer gets the starry sky as an option, which keeps the Sun and Moon', async () => { - const { applicationViewerOptions } = await import('./viewer.js'); - const { StarrySky } = await import('../sky/starrySky.js'); + const { applicationViewerOptions } = + await import('../render/cesium/applicationViewer.js'); + const { StarrySky } = await import('../render/cesium/starrySky.js'); const creditContainer = {}; const options = applicationViewerOptions(creditContainer); // CesiumWidget skips scene.sun and scene.moon when skyBox is false. diff --git a/src/data/local_data/sky/README.md b/src/data/local_data/sky/README.md index 9bf106d31..0f468ee62 100644 --- a/src/data/local_data/sky/README.md +++ b/src/data/local_data/sky/README.md @@ -1,6 +1,6 @@ # Sky background -Catalogue stars over a soft Milky Way, drawn by `src/sky/starrySky.js` in +Catalogue stars over a soft Milky Way, drawn by `src/render/cesium/starrySky.js` in place of Cesium's blocky Tycho-2 sky box. | File | Content | Size | diff --git a/src/render/cesium/appRenderer.js b/src/render/cesium/appRenderer.js index 6d4bdd6ce..18251d251 100644 --- a/src/render/cesium/appRenderer.js +++ b/src/render/cesium/appRenderer.js @@ -17,7 +17,7 @@ * crosses the contract and each call marks code still to port. Ported code * that still holds the viewer reaches the renderer through `rendererOf`. */ -import { createApplicationViewer } from '../../app/viewer.js'; +import { createApplicationViewer } from './applicationViewer.js'; import { CONTRACT_VERSION } from '../contract/index.js'; import { bindRenderer } from '../rendererOf.js'; import { createCesiumInput } from './input.js'; diff --git a/src/app/viewer.js b/src/render/cesium/applicationViewer.js similarity index 94% rename from src/app/viewer.js rename to src/render/cesium/applicationViewer.js index 550363ddd..cc32e069b 100644 --- a/src/app/viewer.js +++ b/src/render/cesium/applicationViewer.js @@ -1,6 +1,6 @@ import * as Cesium from 'cesium'; -import { applyModelAtmosphereWorkaround } from './atmosphereCompat.js'; -import { StarrySky } from '../sky/starrySky.js'; +import { applyModelAtmosphereWorkaround } from '../../app/atmosphereCompat.js'; +import { StarrySky } from './starrySky.js'; // Dev convenience: expose the app's Cesium instance for console/preview probing // (single shared module instance — avoids dual-Cesium state bugs when testing). diff --git a/src/sky/starrySky.js b/src/render/cesium/starrySky.js similarity index 95% rename from src/sky/starrySky.js rename to src/render/cesium/starrySky.js index cbf9d2044..868139f85 100644 --- a/src/sky/starrySky.js +++ b/src/render/cesium/starrySky.js @@ -1,7 +1,8 @@ import * as Cesium from 'cesium'; -import { loadBundledJson } from '../data/bundledJson.js'; -import { governorRequestRender } from '../renderGovernor.js'; -import { buildStarVertices, STAR_VERTEX_FLOATS } from './stars.js'; +import { loadBundledJson } from '../../data/bundledJson.js'; +import { governorRequestRender } from '../../renderGovernor.js'; +import { buildStarVertices, STAR_VERTEX_FLOATS } from '../../sky/stars.js'; +import { provideIcrfToFixed } from '../../sky/icrf.js'; /** * Space background in the `Scene#skyBox` slot: catalogue stars as point @@ -18,32 +19,32 @@ export const MILKY_WAY_INTENSITY = 0.4; export const SKY_ROTATION_EPSILON_SECONDS = 1; const STAR_PACK_URL = new URL( - '../data/local_data/sky/bright_stars.json', + '../../data/local_data/sky/bright_stars.json', import.meta.url, ); const MILKY_WAY_FACE_URLS = Object.freeze({ positiveX: new URL( - '../data/local_data/sky/milkyway_px.webp', + '../../data/local_data/sky/milkyway_px.webp', import.meta.url, ), negativeX: new URL( - '../data/local_data/sky/milkyway_nx.webp', + '../../data/local_data/sky/milkyway_nx.webp', import.meta.url, ), positiveY: new URL( - '../data/local_data/sky/milkyway_py.webp', + '../../data/local_data/sky/milkyway_py.webp', import.meta.url, ), negativeY: new URL( - '../data/local_data/sky/milkyway_ny.webp', + '../../data/local_data/sky/milkyway_ny.webp', import.meta.url, ), positiveZ: new URL( - '../data/local_data/sky/milkyway_pz.webp', + '../../data/local_data/sky/milkyway_pz.webp', import.meta.url, ), negativeZ: new URL( - '../data/local_data/sky/milkyway_nz.webp', + '../../data/local_data/sky/milkyway_nz.webp', import.meta.url, ), }); @@ -151,6 +152,9 @@ export function icrfToFixedAxes(ms) { }; } +// Cesium-free code asks for it through `src/sky/icrf.js`. +provideIcrfToFixed(icrfToFixedAxes); + /** Whether a cached rotation at `cachedTime` still serves `time`. */ export function isSkyRotationCurrent(cachedTime, time) { return ( diff --git a/src/sky/starrySky.test.mjs b/src/render/cesium/starrySky.test.mjs similarity index 90% rename from src/sky/starrySky.test.mjs rename to src/render/cesium/starrySky.test.mjs index 42b08fecc..c1dc5b080 100644 --- a/src/sky/starrySky.test.mjs +++ b/src/render/cesium/starrySky.test.mjs @@ -10,6 +10,7 @@ import { icrfToFixedAxes, isSkyRotationCurrent, } from './starrySky.js'; +import * as neutral from '../../sky/icrf.js'; const close = (actual, expected, epsilon = 1e-9) => assert.ok(Math.abs(actual - expected) <= epsilon, `${actual} vs ${expected}`); @@ -221,3 +222,26 @@ test('the precise frame is given as its axes once its tables answer', (t) => { ); assert.equal(icrfToFixedAxes(ms), null); }); + +test('loading the sky provides its precise rotation to Cesium-free code', () => { + const ms = Date.parse('2026-10-19T00:00:00Z'); + const original = Cesium.Transforms.computeIcrfToFixedMatrix; + Cesium.Transforms.computeIcrfToFixedMatrix = (_time, result) => + Cesium.Matrix3.clone(Cesium.Matrix3.fromRotationZ(0.3), result); + try { + const axes = neutral.icrfToFixedAxes(ms); + assert.notEqual(axes, null); + assert.deepEqual(axes, icrfToFixedAxes(ms)); + } finally { + Cesium.Transforms.computeIcrfToFixedMatrix = original; + } +}); + +test('the neutral rotation answers null with nothing provided', () => { + neutral.provideIcrfToFixed(null); + try { + assert.equal(neutral.icrfToFixedAxes(0), null); + } finally { + neutral.provideIcrfToFixed(icrfToFixedAxes); + } +}); diff --git a/src/render/cesium/unbound.js b/src/render/cesium/unbound.js index b05d0be6b..54fa4892c 100644 --- a/src/render/cesium/unbound.js +++ b/src/render/cesium/unbound.js @@ -4,8 +4,9 @@ * layers a Cesium viewer with no renderer bound: the factories * that build a camera, credits, effects, draw, frame, globe, input and query * port over such a viewer when code first asks for one, a click's own - * Cesium picks (`rendererOf.js`), and the map engine the map stacks switch - * through (`src/maps/engine.js`). + * Cesium picks (`rendererOf.js`), the map engine the map stacks switch + * through (`src/maps/engine.js`), and the sky's precise ICRF rotation + * (`src/sky/icrf.js`). */ import './camera.js'; import './effects.js'; @@ -15,3 +16,4 @@ import './input.js'; import './mapEngine.js'; import './nativeClick.js'; import './query.js'; +import './starrySky.js'; diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 1e84430f1..b234f44d5 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -2,8 +2,6 @@ "dev/conformance/main.js", "src/app/embed.js", "src/app/scene.js", - "src/app/viewer.js", "src/data/geoImportPins.js", - "src/sky/starrySky.js", "src/ui/applicationShell.js" ] diff --git a/src/sky/icrf.js b/src/sky/icrf.js new file mode 100644 index 000000000..41b18d72a --- /dev/null +++ b/src/sky/icrf.js @@ -0,0 +1,28 @@ +/** + * @module sky/icrf + * @description The precise ICRF-to-fixed rotation, from the renderer that + * has the tables for it (the Cesium adapter's starry sky provides it as it + * loads, `src/render/cesium/starrySky.js`). Cesium-free: with none + * provided, or before its tables load, it answers null and callers fall + * back to `temeToPseudoFixed` (`src/geo/frames.js`). + */ + +let provided = null; + +/** + * Provide the precise rotation; a later call replaces it. + * @param {(ms: number) => ({x: object, y: object, z: object} | null)} axesAt + */ +export function provideIcrfToFixed(axesAt) { + provided = axesAt; +} + +/** + * The precise ICRF-to-fixed rotation at `ms` (epoch milliseconds) as its + * axes (the matrix's columns), or null while it is unknown. + * @param {number} ms + * @returns {{x: object, y: object, z: object} | null} + */ +export function icrfToFixedAxes(ms) { + return provided ? provided(ms) : null; +} diff --git a/src/ui/applicationShell.js b/src/ui/applicationShell.js index 2b5d61fd1..f3e663e7a 100644 --- a/src/ui/applicationShell.js +++ b/src/ui/applicationShell.js @@ -63,7 +63,7 @@ import { applicationPinia, createUiRuntime } from './vueRuntime.js'; import { useContextStore } from './stores/context.js'; import { useMissionReplayStore } from './stores/missionReplay.js'; import { useCelestialRingStore } from './stores/celestialRing.js'; -import { icrfToFixedAxes } from '../sky/starrySky.js'; +import { icrfToFixedAxes } from '../sky/icrf.js'; import { useWorldOverlayActionsStore } from './stores/worldOverlayActions.js'; import { useAwarenessDirectionStore } from './stores/awarenessDirection.js'; import { useHudStore } from './stores/hud.js'; diff --git a/src/ui/visualEffects.test.mjs b/src/ui/visualEffects.test.mjs index bd0cb8b4c..264befdb7 100644 --- a/src/ui/visualEffects.test.mjs +++ b/src/ui/visualEffects.test.mjs @@ -4,7 +4,7 @@ import { VisualEffects } from './visualEffects.js'; import { createCesiumEffects } from '../render/cesium/effects.js'; import { styleStagesOf } from '../styles/styleStages.js'; import { createCesiumGlobe } from '../render/cesium/globe.js'; -import { MILKY_WAY_INTENSITY, StarrySky } from '../sky/starrySky.js'; +import { MILKY_WAY_INTENSITY, StarrySky } from '../render/cesium/starrySky.js'; import { GLOBAL_POST_DEFAULTS, STYLE_PRESET_DEFAULTS, From 26665e8390e6965ea9020538c93c2c604a3ad59e Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 9 Nov 2026 12:43:36 -0800 Subject: [PATCH 3/4] Embed views and the application shell leave the Cesium allow-list The embed views fly through rendererOf's camera port with geo maths, and the panel render loop that keeps an inline panel drawing moves into the Cesium adapter (src/render/cesium/panelRendering.js); the application scene hands it to the embed views as `keepRendering`. The shell reaches the camera, effects and globe through rendererOf and loads no Cesium factories; whether Cockpit's aircraft is an entity of the viewer's own comes from the scene's `viewerDrawsEntity`, wired in through the controls. Callers handing the shell or the application tools a viewer of their own load ./render/cesium/unbound once, as the ports' unbound check now records. --- docs/CODE-BOUNDARIES.md | 11 ++- docs/CURRENT-STATE.md | 9 ++- scripts/format-scope.json | 2 + scripts/package-boundaries.json | 3 +- src/app/controls.js | 6 +- src/app/data.js | 2 +- src/app/embed.js | 92 ++++------------------- src/app/embed.test.mjs | 76 ++----------------- src/app/scene.js | 7 ++ src/app/tools.js | 3 +- src/hud.js | 2 +- src/render/cesium/panelRendering.js | 69 +++++++++++++++++ src/render/cesium/panelRendering.test.mjs | 70 +++++++++++++++++ src/render/cesiumAllowList.json | 8 +- src/render/unboundCamera.test.mjs | 28 +++++-- src/ui/applicationShell.js | 19 ++--- 16 files changed, 222 insertions(+), 185 deletions(-) create mode 100644 src/render/cesium/panelRendering.js create mode 100644 src/render/cesium/panelRendering.test.mjs diff --git a/docs/CODE-BOUNDARIES.md b/docs/CODE-BOUNDARIES.md index 3df85b7a4..25fe503c4 100644 --- a/docs/CODE-BOUNDARIES.md +++ b/docs/CODE-BOUNDARIES.md @@ -468,10 +468,13 @@ release listeners; pending action feedback is limited to its current owner. rendering, HUD and share operations. `src/standalone/controls.js` provides the running application's instances. The shell imports no standalone bootstrap or concrete live layer implementation. -The celestial ring's precise ICRF rotation comes from the renderer -(`src/sky/icrf.js`): the application's renderer provides it; a shell given a -viewer with no renderer bound gets it once `./render/cesium/unbound` has loaded, and -falls back to the TEME approximation until then. +The shell reaches the renderer through its ports alone, and loads no +renderer: given a viewer with no renderer bound, load +`./render/cesium/unbound` once first, which also provides the celestial +ring's precise ICRF rotation (`src/sky/icrf.js`; until then the ring uses +the TEME approximation). Whether Cockpit's aircraft is an entity of the +viewer's own is the `viewerDrawsEntity` service's to say; the application +scene supplies it. Panel layout, position/drag, notices, recording and deferred UI work have separate owners with synchronous cleanup. Existing scene, share and HUD engines retain their entry points. `ui/styles` loads the ordered stylesheet entry; component diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index 36999824d..7f8b07b02 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -881,7 +881,9 @@ unchanged. Polled layer refreshes and the HUD's camera readout pause while the page is hidden. An app embedded inline in a panel keeps both running, because the panel's host can report the page as hidden while it is on screen. This is the -same rule the render loop follows (`keepPanelRendering` in `app/embed.js`). +same rule the render loop follows (`keepPanelRendering` in +`render/cesium/panelRendering.js`, which the application scene hands the embed +views). Application scene setup owns request services, terrain/floor caches and annotation lookup state. Controls, layers and voice share those owners, and cancellation @@ -1128,8 +1130,9 @@ port's `preUpdate`, with the shared geo maths, and no longer loads the Cesium camera factory: a caller handing it a Cesium viewer, with no renderer bound, loads the `./render/cesium/unbound` export once first, or its controller throws naming it. Whether the aircraft it flies still draws comes -from its `trackedEntityDrawn` service (the application asks the viewer's -entities); without one, Cockpit takes the aircraft as drawn. +from its `trackedEntityDrawn` service (the shell asks the entity's record, +and the application scene's `viewerDrawsEntity` for an entity of the viewer's +own); without one, Cockpit takes the aircraft as drawn. ## Rendered-mesh floor cells — November 8, 2026 diff --git a/scripts/format-scope.json b/scripts/format-scope.json index d025857ca..91e2ef225 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1130,6 +1130,8 @@ "src/view/index.test.mjs", "src/tools/views.test.mjs", "src/app/embed.test.mjs", + "src/render/cesium/panelRendering.js", + "src/render/cesium/panelRendering.test.mjs", "src/tools/globePanel.test.mjs", "src/costEndpointThrottle.test.mjs", "src/sources/gbfsStations.test.mjs", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index adeec3baa..b44a0c021 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -4295,7 +4295,8 @@ "src/maps/engine.js", "src/maps/attribution.js", "src/render/cesium/mapEngine.js", - "src/sky/icrf.js" + "src/sky/icrf.js", + "src/render/cesium/panelRendering.js" ], "external": [ "hls.js", diff --git a/src/app/controls.js b/src/app/controls.js index ecf52f302..36d25651a 100644 --- a/src/app/controls.js +++ b/src/app/controls.js @@ -8,10 +8,10 @@ import { t } from '../i18n/index.js'; * Construct the existing controls and camera presentation. `initialShareCode` * opens a share code (the `` of `/share/`) at start-up, for a host * whose address does not carry one. `localePicker: false` removes the language - * picker, for a host that does not initialize Core's locale. + * picker, for a page that does not initialize the app's locale. */ export function createApplicationControls({ - scene: { viewer, mapStackController, operations }, + scene: { viewer, mapStackController, operations, viewerDrawsEntity }, loaderStatus, Controls = StyleManager, services, @@ -30,6 +30,8 @@ export function createApplicationControls({ fetchRegionalBrief: (...args) => operations.requests.regional.getBrief(...args), ...catalogControlServices(catalog), + // Whether an entity is one of the viewer's own; the scene answers it. + viewerDrawsEntity: viewerDrawsEntity ?? services?.viewerDrawsEntity, }, requestServices: operations.requests, mapStackController, diff --git a/src/app/data.js b/src/app/data.js index 022839cd2..45ce29b6d 100644 --- a/src/app/data.js +++ b/src/app/data.js @@ -15,7 +15,7 @@ export function createApplicationData({ const dataManager = new LayerLifecycle(viewer, { allowQaRegistration, // A panel's host may report it hidden while it is on screen; its layers - // keep polling (see keepPanelRendering in embed.js). + // keep polling (see keepPanelRendering in render/cesium/panelRendering.js). visibilityTarget: panelAwareVisibility(document), getSourceAvailability: catalog?.getSourceAvailability, }); diff --git a/src/app/embed.js b/src/app/embed.js index bd46485ba..1803114cd 100644 --- a/src/app/embed.js +++ b/src/app/embed.js @@ -11,16 +11,9 @@ * embedded or not. */ -import * as Cesium from 'cesium'; import { announceNavigationAuthority } from '../navigationPolicy.js'; -import { cameraOf } from '../render/cesium/camera.js'; -// The application's tools reach `findGlobe` callers too (the Recent Imagery -// panel, Import and others): a viewer with no renderer bound gets its globe -// port from here, as it gets its camera. -import '../render/cesium/globe.js'; -// The application's data reaches `findEffects` (the cyber contact sweep): -// such a viewer gets its effects port from here too. -import '../render/cesium/effects.js'; +import { toRadians } from '../geo/index.js'; +import { cameraOf } from '../render/rendererOf.js'; import { annotationsFromParams, createView } from '../view/index.js'; const EMBED_VIEW_MESSAGE = 'gev:view'; @@ -55,7 +48,8 @@ export function isEmbeddedInline() { /** * `doc`'s visibility for work that pauses in a hidden page. A panel's host - * may report it hidden while it is on screen (see keepPanelRendering), so an + * may report it hidden while it is on screen (see keepPanelRendering in + * render/cesium/panelRendering.js), so an * inline panel always reads as visible. */ export function panelAwareVisibility(doc = globalThis.document) { @@ -75,69 +69,6 @@ export function panelAwareVisibility(doc = globalThis.document) { }; } -// A panel keeps drawing at about this rate when its host stops animation -// frames; see keepPanelRendering. -const PANEL_FRAME_MS = 33; -const MISSED_FRAMES_MS = 250; - -/** A render error's details, including the plain objects workers report. */ -function describeError(error) { - if (error instanceof Error) - return `${error.name}: ${error.message}\n${error.stack}`; - try { - return JSON.stringify(error, Object.getOwnPropertyNames(error ?? {})); - } catch { - return String(error); - } -} - -/** - * Keep the globe drawing in an inline panel. Some hosts report a panel on - * screen as hidden, which stops the browser's animation frames and with them - * Cesium's render loop; while frames stop arriving, draw from a timer. - * Returns a function that stops it. - */ -export function keepPanelRendering( - viewer, - { windowRef = globalThis.window, now = () => performance.now() } = {}, -) { - let lastFrame = now(); - let frameRequest = null; - const onFrame = () => { - lastFrame = now(); - frameRequest = windowRef.requestAnimationFrame(onFrame); - }; - frameRequest = windowRef.requestAnimationFrame(onFrame); - // Cesium stops drawing after a render error, and so does the timer. - // Report the error in full: workers report plain objects, which Cesium - // prints as [object Object]. - let failed = false; - const removeErrorListener = viewer.scene?.renderError?.addEventListener( - (_scene, error) => { - failed = true; - console.error( - "[God's Eye View panel] render error:", - describeError(error), - ); - }, - ); - const timer = windowRef.setInterval(() => { - if ( - failed || - now() - lastFrame < MISSED_FRAMES_MS || - viewer.isDestroyed?.() - ) - return; - viewer.resize(); - viewer.render(); - }, PANEL_FRAME_MS); - return () => { - windowRef.clearInterval(timer); - windowRef.cancelAnimationFrame(frameRequest); - removeErrorListener?.(); - }; -} - const delay = (ms, signal) => new Promise((resolve) => { const timer = setTimeout(resolve, ms); @@ -159,8 +90,8 @@ function flyTo(viewer, camera) { { lon: camera.lon, lat: camera.lat, height: camera.altitude_m }, { orientation: { - heading: Cesium.Math.toRadians(camera.heading_deg), - pitch: Cesium.Math.toRadians(camera.pitch_deg), + heading: toRadians(camera.heading_deg), + pitch: toRadians(camera.pitch_deg), roll: 0, }, durationS: FLIGHT_SECONDS, @@ -249,6 +180,9 @@ export async function applyView( /** * Install embed mode when the page asks for it, and draw any annotations the * opening link carries. Returns a function that removes the message handler. + * `keepRendering({windowRef})` keeps the globe drawing in an inline panel + * whose host stops animation frames, and returns a function that stops it; + * the application scene gives it (`keepPanelRendering`). */ export function installViews({ shell, @@ -256,6 +190,7 @@ export function installViews({ dataManager, run, signal, + keepRendering = null, location = globalThis.location, windowRef = globalThis.window, }) { @@ -271,9 +206,10 @@ export function installViews({ windowRef.document.body.classList.add('ui-embed'); shell.setCleanView?.(true); - const stopRendering = isEmbeddedInline() - ? keepPanelRendering(viewer, { windowRef }) - : () => {}; + const stopRendering = + isEmbeddedInline() && keepRendering + ? keepRendering({ windowRef }) + : () => {}; // A framing page talks to the app across frames; an inline panel shares // the page with it and talks through the page's own window. const peer = isEmbeddedInline() ? windowRef : windowRef.parent; diff --git a/src/app/embed.test.mjs b/src/app/embed.test.mjs index 3f48d2e97..8a0d2cded 100644 --- a/src/app/embed.test.mjs +++ b/src/app/embed.test.mjs @@ -5,7 +5,6 @@ import { applyView, installViews, isEmbedded, - keepPanelRendering, panelAwareVisibility, } from './embed.js'; import { LayerLifecycle } from '../data/lifecycle.js'; @@ -203,6 +202,7 @@ test('an app loaded inline into a panel page talks through its own window', asyn globalThis.GEV_EMBED_INLINE = true; try { assert.equal(isEmbedded({ search: '' }), true); + const kept = []; const remove = installViews({ shell: { initialRestorePromise: Promise.resolve() }, viewer: fakeViewer(), @@ -210,7 +210,13 @@ test('an app loaded inline into a panel page talks through its own window', asyn run: recorder().run, location: { search: '', hash: '' }, windowRef, + // The scene's panel rendering, kept on while the views are installed. + keepRendering: (options) => { + kept.push(options.windowRef === windowRef); + return () => kept.push('stopped'); + }, }); + assert.deepEqual(kept, [true]); await new Promise((resolve) => setTimeout(resolve, 0)); assert.deepEqual(posted, [{ type: 'gev:ready' }]); const event = new Event('message'); @@ -223,6 +229,7 @@ test('an app loaded inline into a panel page talks through its own window', asyn assert.equal(posted[1].id, 7); assert.equal(posted[1].ok, true); remove(); + assert.deepEqual(kept, [true, 'stopped']); } finally { delete globalThis.GEV_EMBED_INLINE; } @@ -301,73 +308,6 @@ test('annotations in a link are drawn after it restores, embedded or not', async ]); }); -test('a panel keeps drawing from a timer while animation frames stop', () => { - let clock = 0; - let tick = null; - let frame = null; - const windowRef = { - requestAnimationFrame: (fn) => ((frame = fn), 1), - cancelAnimationFrame: () => (frame = null), - setInterval: (fn) => ((tick = fn), 1), - clearInterval: () => (tick = null), - }; - const drawn = []; - const viewer = { - resize: () => drawn.push('resize'), - render: () => drawn.push('render'), - }; - const stop = keepPanelRendering(viewer, { windowRef, now: () => clock }); - // Frames arrive: the render loop draws, so the timer does nothing. - clock = 100; - frame(); - tick(); - assert.deepEqual(drawn, []); - // Frames stop, as in a panel its host reports hidden: the timer draws. - clock = 400; - tick(); - assert.deepEqual(drawn, ['resize', 'render']); - stop(); - assert.equal(tick, null); - assert.equal(frame, null); -}); - -test('a panel reports a render error in full and stops drawing', () => { - let listener = null; - let tick = null; - const windowRef = { - requestAnimationFrame: () => 1, - cancelAnimationFrame() {}, - setInterval: (fn) => ((tick = fn), 1), - clearInterval() {}, - }; - const drawn = []; - const viewer = { - resize() {}, - render: () => drawn.push('render'), - scene: { - renderError: { - addEventListener: (fn) => ((listener = fn), () => (listener = null)), - }, - }, - }; - const logged = []; - const original = console.error; - console.error = (...args) => logged.push(args.join(' ')); - try { - let clock = 0; - const stop = keepPanelRendering(viewer, { windowRef, now: () => clock }); - listener(viewer.scene, { name: 'RuntimeError', message: 'worker failed' }); - assert.match(logged[0], /render error: .*"message":"worker failed"/); - clock = 1000; - tick(); - assert.deepEqual(drawn, []); - stop(); - assert.equal(listener, null); - } finally { - console.error = original; - } -}); - test('a followed aircraft owns the camera, and cockpit view is entered after it', async () => { const viewer = fakeViewer(); const { calls, run } = recorder(); diff --git a/src/app/scene.js b/src/app/scene.js index 00057f3e4..e4f018a94 100644 --- a/src/app/scene.js +++ b/src/app/scene.js @@ -5,6 +5,7 @@ import { cesiumViewerOf, } from '../render/cesium/appRenderer.js'; import { trimStaleSceneCommands } from '../render/cesium/sceneCommandRelease.js'; +import { keepPanelRendering } from '../render/cesium/panelRendering.js'; import { registerDataCredits } from '../data/dataCredits.js'; import { configureCreditKeyboardAccess } from '../creditKeyboard.js'; import { MapStackController } from '../mapStackController.js'; @@ -169,5 +170,11 @@ export async function createApplicationScene({ // Drops the draw commands the scene keeps after it stops drawing them; // run after a drawn frame (see src/sceneCommandRelease.js). trimStaleCommands: () => trimStaleSceneCommands(viewer.scene), + // Keeps the globe drawing in an inline panel whose host stops animation + // frames (embed mode, src/app/embed.js). + keepPanelRendering: (options) => keepPanelRendering(viewer, options), + // Whether an entity is one of the viewer's own (Cockpit asks whether + // the aircraft it flies still draws). + viewerDrawsEntity: (entity) => viewer.entities.contains(entity), }; } diff --git a/src/app/tools.js b/src/app/tools.js index 8cfa2be05..2169f6ed8 100644 --- a/src/app/tools.js +++ b/src/app/tools.js @@ -165,7 +165,7 @@ export function createApplicationTools({ // the loop, refresh the one DOM surface we gated, render a frame. const syncVisibilitySuspension = () => { // A panel's host may report it hidden while it is on screen; the panel - // keeps drawing itself (see keepPanelRendering in embed.js). + // keeps drawing itself (see keepPanelRendering in render/cesium/panelRendering.js). const hidden = document.hidden && !isEmbeddedInline(); renderer.frame.suspend(hidden); cockpitCloudEffects?.setSuspended?.(hidden); @@ -232,6 +232,7 @@ export function createApplicationTools({ dataManager, run: (name, args) => voiceCommands.runner(name, args, { signal }), signal, + keepRendering: scene.keepPanelRendering, }), ); return { sceneDirector, annotations, voiceCommands }; diff --git a/src/hud.js b/src/hud.js index 9d5a80a14..2b6e34dc2 100644 --- a/src/hud.js +++ b/src/hud.js @@ -441,7 +441,7 @@ export class IntelHUD { // Camera-derived data — 4 updates/second (250ms). Skipped in a hidden // page, except an inline panel, whose host may report it hidden while it - // is on screen (see keepPanelRendering in app/embed.js). + // is on screen (see keepPanelRendering in render/cesium/panelRendering.js). this._updateInterval = setInterval(() => { if (!this._visible || (document.hidden && !isEmbeddedInline())) return; this._updateCameraData(); diff --git a/src/render/cesium/panelRendering.js b/src/render/cesium/panelRendering.js new file mode 100644 index 000000000..2d16b3848 --- /dev/null +++ b/src/render/cesium/panelRendering.js @@ -0,0 +1,69 @@ +/** + * @module render/cesium/panelRendering + * @description Keeping the Cesium viewer drawing in an inline panel whose + * host stops animation frames (`src/app/embed.js`, embed mode). The + * application scene hands it to the embed views (`src/app/scene.js`). + */ + +// A panel keeps drawing at about this rate when its host stops animation +// frames; see keepPanelRendering. +const PANEL_FRAME_MS = 33; +const MISSED_FRAMES_MS = 250; + +/** A render error's details, including the plain objects workers report. */ +function describeError(error) { + if (error instanceof Error) + return `${error.name}: ${error.message}\n${error.stack}`; + try { + return JSON.stringify(error, Object.getOwnPropertyNames(error ?? {})); + } catch { + return String(error); + } +} + +/** + * Keep the globe drawing in an inline panel. Some hosts report a panel on + * screen as hidden, which stops the browser's animation frames and with them + * Cesium's render loop; while frames stop arriving, draw from a timer. + * Returns a function that stops it. + */ +export function keepPanelRendering( + viewer, + { windowRef = globalThis.window, now = () => performance.now() } = {}, +) { + let lastFrame = now(); + let frameRequest = null; + const onFrame = () => { + lastFrame = now(); + frameRequest = windowRef.requestAnimationFrame(onFrame); + }; + frameRequest = windowRef.requestAnimationFrame(onFrame); + // Cesium stops drawing after a render error, and so does the timer. + // Report the error in full: workers report plain objects, which Cesium + // prints as [object Object]. + let failed = false; + const removeErrorListener = viewer.scene?.renderError?.addEventListener( + (_scene, error) => { + failed = true; + console.error( + "[God's Eye View panel] render error:", + describeError(error), + ); + }, + ); + const timer = windowRef.setInterval(() => { + if ( + failed || + now() - lastFrame < MISSED_FRAMES_MS || + viewer.isDestroyed?.() + ) + return; + viewer.resize(); + viewer.render(); + }, PANEL_FRAME_MS); + return () => { + windowRef.clearInterval(timer); + windowRef.cancelAnimationFrame(frameRequest); + removeErrorListener?.(); + }; +} diff --git a/src/render/cesium/panelRendering.test.mjs b/src/render/cesium/panelRendering.test.mjs new file mode 100644 index 000000000..0b3b7a34f --- /dev/null +++ b/src/render/cesium/panelRendering.test.mjs @@ -0,0 +1,70 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { keepPanelRendering } from './panelRendering.js'; + +test('a panel keeps drawing from a timer while animation frames stop', () => { + let clock = 0; + let tick = null; + let frame = null; + const windowRef = { + requestAnimationFrame: (fn) => ((frame = fn), 1), + cancelAnimationFrame: () => (frame = null), + setInterval: (fn) => ((tick = fn), 1), + clearInterval: () => (tick = null), + }; + const drawn = []; + const viewer = { + resize: () => drawn.push('resize'), + render: () => drawn.push('render'), + }; + const stop = keepPanelRendering(viewer, { windowRef, now: () => clock }); + // Frames arrive: the render loop draws, so the timer does nothing. + clock = 100; + frame(); + tick(); + assert.deepEqual(drawn, []); + // Frames stop, as in a panel its host reports hidden: the timer draws. + clock = 400; + tick(); + assert.deepEqual(drawn, ['resize', 'render']); + stop(); + assert.equal(tick, null); + assert.equal(frame, null); +}); + +test('a panel reports a render error in full and stops drawing', () => { + let listener = null; + let tick = null; + const windowRef = { + requestAnimationFrame: () => 1, + cancelAnimationFrame() {}, + setInterval: (fn) => ((tick = fn), 1), + clearInterval() {}, + }; + const drawn = []; + const viewer = { + resize() {}, + render: () => drawn.push('render'), + scene: { + renderError: { + addEventListener: (fn) => ((listener = fn), () => (listener = null)), + }, + }, + }; + const logged = []; + const original = console.error; + console.error = (...args) => logged.push(args.join(' ')); + try { + let clock = 0; + const stop = keepPanelRendering(viewer, { windowRef, now: () => clock }); + listener(viewer.scene, { name: 'RuntimeError', message: 'worker failed' }); + assert.match(logged[0], /render error: .*"message":"worker failed"/); + clock = 1000; + tick(); + assert.deepEqual(drawn, []); + stop(); + assert.equal(listener, null); + } finally { + console.error = original; + } +}); diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index b234f44d5..13b681f44 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -1,7 +1 @@ -[ - "dev/conformance/main.js", - "src/app/embed.js", - "src/app/scene.js", - "src/data/geoImportPins.js", - "src/ui/applicationShell.js" -] +["dev/conformance/main.js", "src/app/scene.js", "src/data/geoImportPins.js"] diff --git a/src/render/unboundCamera.test.mjs b/src/render/unboundCamera.test.mjs index 0fe6536dc..03a9d79bc 100644 --- a/src/render/unboundCamera.test.mjs +++ b/src/render/unboundCamera.test.mjs @@ -49,13 +49,11 @@ const UNBOUND = 'src/render/cesium/unbound.js'; /** * Entries that take their Cesium code injected: the module named here is * GEV's Cesium side for them, and must load the factories. Given another, the - * entry's flight finds no camera (`findCamera`) and does nothing. Visual - * settings are given their viewer by the application shell, which loads - * both factories; without it, their styles keep records and draw nothing. + * entry's flight finds no camera (`findCamera`) and does nothing. None is + * left: visual settings, once given their viewer by the application shell, + * now leave the factories to their caller as the shell does. */ -const INJECTED = { - './ui/visual-settings': 'src/ui/applicationShell.js', -}; +const INJECTED = {}; /** * Modules whose use of the bridge holds up without the factory: with no @@ -141,6 +139,10 @@ const DRAW_FROM_CALLER = new Set([ // eye and shade the globe through the ports alone. './application/layers', './standalone/catalog', + // The application's tools (scene director, annotations, embed views): + // they draw, fly and take clicks through the ports; only Import's pins + // (`src/data/geoImportPins.js`, still on the Cesium list) drive Cesium. + './application/tools', ]); /** @@ -174,6 +176,16 @@ const CAMERA_FROM_CALLER = new Set([ // It shows its source's credit through `findCredits`, and switches stacks // through the map engine that `./render/cesium/unbound` provides too. './maps/controller', + // The application shell and what assembles it: their controls fly, read + // the eye, shade the globe and set styles through the ports alone; the + // application's renderer is bound to its viewer, and a viewer of the + // renderer bound gets its ports from `./render/cesium/unbound`. + './ui/shell', + './ui/composition', + './ui/hud', + './ui/visual-settings', + './application/controls', + './application/data', ]); const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')); @@ -343,8 +355,8 @@ function checkLookupFactory( ); } -test('every public entry that reaches a findEffects caller loads the unbound effects factory', () => { - checkLookupFactory('findEffects', EFFECTS_FACTORY); +test('every public entry that reaches a findEffects caller loads the unbound effects factory, or its caller can', () => { + checkLookupFactory('findEffects', EFFECTS_FACTORY, { fromCaller: true }); }); test('every public entry that reaches a findGlobe caller loads the unbound globe factory', () => { diff --git a/src/ui/applicationShell.js b/src/ui/applicationShell.js index f3e663e7a..b2194560e 100644 --- a/src/ui/applicationShell.js +++ b/src/ui/applicationShell.js @@ -32,13 +32,9 @@ import { } from './cyberSonarControls.js'; import { toDegrees, toRadians } from '../geo/index.js'; -import { cameraOf, findCamera } from '../render/cesium/camera.js'; -// Loads the effects factory, so visual settings on a viewer with no renderer -// bound still get an effects port. Loading the camera and effects factories, -// and asking the viewer's entities whether Cockpit's aircraft still draws, -// keep this module on the Cesium allow-list. -import '../render/cesium/effects.js'; -import '../render/cesium/globe.js'; +// A viewer with no renderer bound gets its ports (camera, effects, globe) +// once its owner has loaded the package's `./render/cesium/unbound` export. +import { cameraOf, canvasOf, findCamera } from '../render/rendererOf.js'; import { aircraftTrackingTarget } from '../cockpitTracking.js'; @@ -380,10 +376,11 @@ export class StyleManager extends ShellFacade { warmGroundFloor: services.warmGroundFloor, sampleMeshFloorCells: services.sampleMeshFloorCells, // Whether the aircraft Cockpit flies still draws: an entity of the - // viewer's own, or a tracked contact whose layer draws it through - // the draw port and says so in its entity record. + // viewer's own (the scene's `viewerDrawsEntity` says), or a tracked + // contact whose layer draws it through the draw port and says so in + // its entity record. trackedEntityDrawn: (entity) => - viewer.entities.contains(entity) || + services.viewerDrawsEntity?.(entity) === true || readEntityRecord(entity)?.drawn?.() === true, holdContinuousRender: services.holdContinuousRender, releaseContinuousRender: services.releaseContinuousRender, @@ -1030,7 +1027,7 @@ export class StyleManager extends ShellFacade { _radioVolumeValue: this._radioVolumeValue, }, radio: radioLayer, - canvas: this.viewer?.canvas, + canvas: canvasOf(this.viewer) ?? undefined, actions: { isRegistered: () => this._dataManager?.layers?.has('radio'), isEnabled: () => this._dataManager?.isEnabled('radio'), From 4c587a6d0f53f41747f1ddbab85671c773df971b Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 9 Nov 2026 12:58:45 -0800 Subject: [PATCH 4/4] Application scene and conformance page leave the Cesium allow-list The application scene is the composition root: it now takes everything it needs from one adapter module (src/render/cesium/application.js), which loads, shows and releases the photoreal tileset and hands out the viewer hooks. The conformance page keeps importing the adapter's harness and scene renderer, since running the suite on Cesium is its purpose. Both are named in the ratchet as the only files outside the adapter that may import it, each limited to those modules, by name only, and the modules may not hand out the Cesium namespace. Only geoImportPins stays on the allow-list. --- docs/RENDERER-CONTRACT.md | 8 +- scripts/format-scope.json | 1 + scripts/package-boundaries.json | 3 +- src/app/scene.js | 34 ++--- src/render/cesium/application.js | 59 +++++++++ src/render/cesiumAllowList.json | 2 +- src/render/noCesiumOutsideRender.test.mjs | 148 ++++++++++++++++++++-- 7 files changed, 222 insertions(+), 33 deletions(-) create mode 100644 src/render/cesium/application.js diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 2b8fee12b..fadafebd3 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -153,7 +153,13 @@ back to Cesium. Both lists only ever shrink. - `src/render/cesiumAllowList.json` lists the files outside the Cesium adapter (`src/render/cesium/`) that may still import or be handed Cesium (`src/render/noCesiumOutsideRender.test.mjs`). A file leaves the list - when it no longer drives Cesium at all; nothing is added. + when it no longer drives Cesium at all; nothing is added. Two files name + the adapter by design and are not on it: the application scene + (`src/app/scene.js`), the composition root that picks the Cesium renderer, + may import `src/render/cesium/application.js` and nothing else of the + adapter; the conformance page (`dev/conformance/main.js`) may import the + adapter's harness and scene renderer. The test names both + (`ADAPTER_ENTRIES`), and that list is never grown. - `src/render/viewerAccessAllowList.json` counts, per file off that list, the Cesium-shaped accesses through the viewer it still makes (`src/render/viewerAccess.test.mjs`): the viewer's `entities`, diff --git a/scripts/format-scope.json b/scripts/format-scope.json index 91e2ef225..936deec39 100644 --- a/scripts/format-scope.json +++ b/scripts/format-scope.json @@ -1131,6 +1131,7 @@ "src/tools/views.test.mjs", "src/app/embed.test.mjs", "src/render/cesium/panelRendering.js", + "src/render/cesium/application.js", "src/render/cesium/panelRendering.test.mjs", "src/tools/globePanel.test.mjs", "src/costEndpointThrottle.test.mjs", diff --git a/scripts/package-boundaries.json b/scripts/package-boundaries.json index b44a0c021..6e7b87af7 100644 --- a/scripts/package-boundaries.json +++ b/scripts/package-boundaries.json @@ -4296,7 +4296,8 @@ "src/maps/attribution.js", "src/render/cesium/mapEngine.js", "src/sky/icrf.js", - "src/render/cesium/panelRendering.js" + "src/render/cesium/panelRendering.js", + "src/render/cesium/application.js" ], "external": [ "hls.js", diff --git a/src/app/scene.js b/src/app/scene.js index e4f018a94..d6dfa4495 100644 --- a/src/app/scene.js +++ b/src/app/scene.js @@ -1,15 +1,17 @@ import { createApplicationOperations } from './operations.js'; -import * as Cesium from 'cesium'; +// The application's composition root: it picks the Cesium renderer, and +// this is the only part of the adapter it imports. import { + applicationViewerHooks, cesiumRenderer, cesiumViewerOf, -} from '../render/cesium/appRenderer.js'; -import { trimStaleSceneCommands } from '../render/cesium/sceneCommandRelease.js'; -import { keepPanelRendering } from '../render/cesium/panelRendering.js'; + loadApplicationPhotoreal, + releaseApplicationPhotoreal, + showApplicationPhotoreal, +} from '../render/cesium/application.js'; import { registerDataCredits } from '../data/dataCredits.js'; import { configureCreditKeyboardAccess } from '../creditKeyboard.js'; import { MapStackController } from '../mapStackController.js'; -import { loadPhotorealisticTileset } from '../render/cesium/google3d.js'; import { initLogoGaze } from '../logoGaze.js'; import { inputFor } from '../input/dispatcher.js'; import { @@ -97,21 +99,17 @@ export async function createApplicationScene({ googleApiKey || googleTokens || cesiumToken ? t('Loading Google 3D Tiles...') : t('Loading the keyless globe...'); - const photoreal = await loadPhotorealisticTileset(Cesium, { + const photoreal = await loadApplicationPhotoreal({ googleApiKey, googleTokens, cesiumToken, }); const tileset = photoreal.tileset; // A provider can finish after cancellation; retain ownership of its result. - defer(() => { - if (tileset && !tileset.isDestroyed()) { - if (!viewer.scene.primitives.remove(tileset)) tileset.destroy(); - } - }); + defer(() => releaseApplicationPhotoreal(viewer, tileset)); signal.throwIfAborted(); if (tileset) { - viewer.scene.primitives.add(tileset); + showApplicationPhotoreal(viewer, tileset); // NOTE: Cesium World Terrain intentionally disabled — conflicts with Google 3D Tiles at high zoom. // Google Photorealistic 3D Tiles provide their own terrain/elevation. renderer.globe.setGlobeVisible(false); @@ -167,14 +165,8 @@ export async function createApplicationScene({ mapStackController, operations, input, - // Drops the draw commands the scene keeps after it stops drawing them; - // run after a drawn frame (see src/sceneCommandRelease.js). - trimStaleCommands: () => trimStaleSceneCommands(viewer.scene), - // Keeps the globe drawing in an inline panel whose host stops animation - // frames (embed mode, src/app/embed.js). - keepPanelRendering: (options) => keepPanelRendering(viewer, options), - // Whether an entity is one of the viewer's own (Cockpit asks whether - // the aircraft it flies still draws). - viewerDrawsEntity: (entity) => viewer.entities.contains(entity), + // Trims stale draw commands, keeps an inline panel drawing, and says + // whether an entity is the viewer's own (render/cesium/application.js). + ...applicationViewerHooks(viewer), }; } diff --git a/src/render/cesium/application.js b/src/render/cesium/application.js new file mode 100644 index 000000000..c423fb095 --- /dev/null +++ b/src/render/cesium/application.js @@ -0,0 +1,59 @@ +/** + * @module render/cesium/application + * @description The Cesium adapter's side of the application scene + * (`src/app/scene.js`), its composition root: the default renderer plugin, + * the viewer behind a renderer it made, the photoreal base tileset the scene + * loads into that viewer, and the viewer hooks the scene hands the + * application (stale command trimming, inline panel rendering, whether an + * entity is the viewer's own). The scene imports this module and no other + * part of the adapter (`src/render/noCesiumOutsideRender.test.mjs`). + */ +import * as Cesium from 'cesium'; +import { cesiumRenderer, cesiumViewerOf } from './appRenderer.js'; +import { loadPhotorealisticTileset } from './google3d.js'; +import { keepPanelRendering } from './panelRendering.js'; +import { trimStaleSceneCommands } from './sceneCommandRelease.js'; + +export { cesiumRenderer, cesiumViewerOf }; + +/** + * Load Google Photorealistic 3D Tiles for the application, by the best route + * the credentials allow (`google3d.js`). + * @param {{googleApiKey?: string, googleTokens?: object|null, cesiumToken?: string}} credentials + * @returns {Promise<{tileset: object|null, route: string, errors: Error[]}>} + */ +export const loadApplicationPhotoreal = (credentials) => + loadPhotorealisticTileset(Cesium, credentials); + +/** Draw the loaded photoreal tileset in `viewer`. */ +export function showApplicationPhotoreal(viewer, tileset) { + viewer.scene.primitives.add(tileset); +} + +/** + * Release the photoreal tileset: out of `viewer`, which destroys it, or + * destroyed by itself when the viewer never held it. + */ +export function releaseApplicationPhotoreal(viewer, tileset) { + if (tileset && !tileset.isDestroyed()) { + if (!viewer.scene.primitives.remove(tileset)) tileset.destroy(); + } +} + +/** + * What the application scene hands the application about its viewer. + * @param {object} viewer + */ +export function applicationViewerHooks(viewer) { + return { + // Drops the draw commands the scene keeps after it stops drawing them; + // run after a drawn frame (see sceneCommandRelease.js). + trimStaleCommands: () => trimStaleSceneCommands(viewer.scene), + // Keeps the globe drawing in an inline panel whose host stops animation + // frames (embed mode, src/app/embed.js). + keepPanelRendering: (options) => keepPanelRendering(viewer, options), + // Whether an entity is one of the viewer's own (Cockpit asks whether + // the aircraft it flies still draws). + viewerDrawsEntity: (entity) => viewer.entities.contains(entity), + }; +} diff --git a/src/render/cesiumAllowList.json b/src/render/cesiumAllowList.json index 13b681f44..723a28c2f 100644 --- a/src/render/cesiumAllowList.json +++ b/src/render/cesiumAllowList.json @@ -1 +1 @@ -["dev/conformance/main.js", "src/app/scene.js", "src/data/geoImportPins.js"] +["src/data/geoImportPins.js"] diff --git a/src/render/noCesiumOutsideRender.test.mjs b/src/render/noCesiumOutsideRender.test.mjs index c0670a85b..cbb312e8b 100644 --- a/src/render/noCesiumOutsideRender.test.mjs +++ b/src/render/noCesiumOutsideRender.test.mjs @@ -19,6 +19,9 @@ * file. Any name `cesium` counts, so a config field of that name would * over-report rather than slip through. * + * Two files name the adapter by design and are not on the list: + * `ADAPTER_ENTRIES` below allows each exactly the adapter modules it needs. + * * Runtime code is every `.js`, `.mjs`, `.cjs` and `.vue` file under `src/`, * `server/` and `dev/`, except tests and test support. */ import assert from 'node:assert/strict'; @@ -52,6 +55,25 @@ const isTestSupport = (file) => TEST_ONLY.has(file); const isAdapter = (file) => file.startsWith('src/render/cesium/'); +/** + * The two places outside the adapter that name it by design, each limited + * to the adapter modules listed here; any other way they reach Cesium + * counts as above. Neither is a file still to port, so neither is on the + * allow-list; this list is never grown. + * - The application scene is the composition root: it picks the Cesium + * renderer as the default and takes the viewer hooks it hands the + * application from the adapter's application module. + * - The conformance page runs the suite on the Cesium adapter's harness + * and draws the reference scenes on its scene renderer. + */ +const ADAPTER_ENTRIES = { + 'src/app/scene.js': ['src/render/cesium/application.js'], + 'dev/conformance/main.js': [ + 'src/render/cesium/harness.js', + 'src/render/cesium/sceneRenderer.js', + ], +}; + const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }); const tracked = git( @@ -70,19 +92,27 @@ const runtimeFiles = tracked.filter( /\.(?:[cm]?js|vue)$/.test(file) && !isTestSupport(file) && !isAdapter(file), ); -/** Whether an import specifier from `file` reaches Cesium. */ -function reachesCesium(file, specifier) { +/** + * The repository path a relative or root-relative specifier names. Vite + * reads `/x` from the project root, not the filesystem's. + */ +function targetOf(file, specifier) { const bare = specifier.replace(/[?#].*$/, ''); - if (/^(?:cesium|@cesium\/[^/]+)(?:\/|$)/.test(bare)) return true; - if (!bare.startsWith('.') && !bare.startsWith('/')) return false; - // Vite reads `/x` from the project root, not the filesystem's. + if (!bare.startsWith('.') && !bare.startsWith('/')) return null; const from = bare.startsWith('/') ? root : path.join(root, path.dirname(file)); - const target = path - .relative(root, path.join(from, bare)) - .split(path.sep) - .join('/'); + return path.relative(root, path.join(from, bare)).split(path.sep).join('/'); +} + +/** Whether an import specifier from `file` reaches Cesium. */ +function reachesCesium(file, specifier) { + const allowed = ADAPTER_ENTRIES[file]; + if (allowed?.includes(targetOf(file, specifier))) return false; + const bare = specifier.replace(/[?#].*$/, ''); + if (/^(?:cesium|@cesium\/[^/]+)(?:\/|$)/.test(bare)) return true; + const target = targetOf(file, specifier); + if (target === null) return false; return ( isAdapter(target) || /^node_modules\/(?:cesium|@cesium\/[^/]+)(?:\/|$)/.test(target) @@ -233,6 +263,106 @@ test('every allow-listed file still reaches Cesium', () => { assert.deepEqual(stale, [], `Remove these from ${LIST}.`); }); +test('the files that name the adapter by design import exactly what they are allowed', () => { + const present = new Set(runtimeFiles); + for (const [file, modules] of Object.entries(ADAPTER_ENTRIES)) { + assert.ok(present.has(file), `${file} is gone: drop it from the list`); + assert.ok(!allowList.includes(file), `${file} is on ${LIST} too`); + const { imports } = scan(readFileSync(path.join(root, file), 'utf8')); + const named = new Set(imports.map((s) => targetOf(file, s))); + for (const module of modules) + assert.ok(named.has(module), `${file} no longer imports ${module}`); + } +}); + +/** Every node under `node`, with its parent. */ +function* nodesOf(node, parent = null) { + if (!node || typeof node !== 'object') return; + if (Array.isArray(node)) { + for (const child of node) yield* nodesOf(child, parent); + return; + } + if (typeof node.type === 'string') yield [node, parent]; + for (const [key, value] of Object.entries(node)) + if (!['loc', 'comments', 'tokens', 'extra'].includes(key)) + yield* nodesOf(value, typeof node.type === 'string' ? node : parent); +} + +test('the files that name the adapter by design take named exports, never Cesium itself', () => { + for (const [file, modules] of Object.entries(ADAPTER_ENTRIES)) { + const parsed = parsers.babel.parse( + readFileSync(path.join(root, file), 'utf8'), + ); + // A static import by name only: no namespace or default binding, no + // dynamic import, and no forwarding of the module. + for (const [node] of nodesOf(parsed.program)) { + const source = node.source?.value; + if (typeof source !== 'string') continue; + if (!modules.includes(targetOf(file, source))) continue; + assert.equal( + node.type, + 'ImportDeclaration', + `${file} must import ${source} statically and not forward it`, + ); + assert.deepEqual( + node.specifiers + .filter((s) => s.type !== 'ImportSpecifier') + .map((s) => s.local.name), + [], + `${file} must import ${source} by name`, + ); + } + // The allowed modules hand out no Cesium namespace: no export from the + // package, and no exported value that is the namespace itself (members + // of it, such as `Cesium.Math`, are the adapter's own business). + for (const module of modules) { + const program = parsers.babel.parse( + readFileSync(path.join(root, module), 'utf8'), + ).program; + const fromCesium = ({ source }) => { + if (typeof source?.value !== 'string') return false; + const bare = source.value.replace(/[?#].*$/, ''); + const target = targetOf(module, bare) ?? ''; + return /^(?:(?:node_modules\/)?(?:cesium|@cesium\/[^/]+))(?:\/|$)/.test( + target || bare, + ); + }; + const namespaces = new Set( + program.body + .filter((n) => n.type === 'ImportDeclaration' && fromCesium(n)) + .flatMap((n) => n.specifiers.map((s) => s.local.name)), + ); + for (const node of program.body) { + if (!node.type.startsWith('Export')) continue; + assert.ok(!fromCesium(node), `${module} must not re-export Cesium`); + for (const [inner, parent] of nodesOf(node)) { + if (inner.type !== 'Identifier' || !namespaces.has(inner.name)) + continue; + // Handing the namespace to the adapter's own functions is fine; + // giving it out as a value is not. + const handedOut = + [ + 'ExportSpecifier', + 'ExportDefaultDeclaration', + 'ReturnStatement', + 'SpreadElement', + 'ArrayExpression', + ].includes(parent?.type) || + (parent?.type === 'VariableDeclarator' && parent.init === inner) || + (parent?.type === 'ObjectProperty' && parent.value === inner) || + (parent?.type === 'ArrowFunctionExpression' && + parent.body === inner) || + (parent?.type === 'AssignmentExpression' && parent.right === inner); + assert.ok( + !handedOut, + `${module} must not export ${inner.name} itself`, + ); + } + } + } + } +}); + test('the allow-list only shrinks', (t) => { // Any git failure fails the check: only the list's confirmed absence on // origin/main (before it lands) skips it.