NODEDC_DESIGN_GUIDELINE/docs/MAP_CESIUM_REACT_ADAPTER.md

Shared Cesium React adapter

@nodedc/map-cesium-react 0.1.0 is the shared renderer boundary for the canonical Map Page 0.1.0 and CesiumJS 1.143.0.

It is not a Foundry application component and does not own product navigation, Inspector fields, tokens, provider allowlists, TileCache storage or admin settings. A product supplies a same-origin BFF runtime contract and persisted provider-neutral view state.

Canonical presentation contract

The adapter accepts the complete provider-neutral Map Page presentation state used by the Foundry DC Default profile: imagery color correction, globe and background colors, atmosphere, fog, sun, shadows, terrain exaggeration, building style/detail and the elevated grid with camera-height LOD. Consumers must persist and pass those values explicitly; the adapter does not invent a second product-specific visual profile.

The canonical black-and-white scene keeps imagery enabled and sets imagery saturation to zero. monochrome_enabled is a separate solid-globe mode and must not be used as a substitute for the DC Default treatment.

Security and runtime contract

• The browser receives only same-origin BFF paths.
• Runtime config must use missioncore.map-runtime/v1, Map Page 0.1.0 and Cesium 1.143.0.
• Canonical assets are fixed to imagery 2, terrain 1 and buildings 96188.
• Provider endpoint documents must declare credentialMode=gateway.
• Every provider resource uses the BFF cache proxy through Cesium DefaultProxy.
• Direct provider credentials, Gateway origins and arbitrary proxy paths are rejected.
• Imagery, terrain and buildings start independently. One failed provider yields a degraded scene when another provider remains ready.
• Render-loop recovery is bounded to one request; a repeated fault becomes cesium_render_error.
• Provider attribution is always registered with Cesium. An internal sandbox may route the visual credit overlay into a hidden dedicated container only through the explicit optional runtime flag sandbox.hide_credit_overlay=true. The flag is absent or false by default and must remain false for every external or production release.

Asset delivery

The package keeps Cesium in a dynamic import so the application receives it as a lazy chunk only when the map renderer mounts. Consumers import @nodedc/map-cesium-react/widgets.css and copy the four runtime directories from cesium/Build/Cesium into the deployed CESIUM_BASE_URL:

• Assets;
• ThirdParty;
• Widgets;
• Workers.

The build/runtime integration must not copy Cesium credentials or NODE.DC TileCache data. Those remain outside application artifacts.

Cache intent

cacheIntent.enabled=false adds nodedc_cache_mode=passthrough while preserving the Gateway security boundary. Enabled mode selects the shared live profile. no_overwrite=false or a separate explicit cache-refresh request adds nodedc_cache_refresh=1. Changing rendererGeneration only recreates the local Cesium viewer and never changes the TileCache write intent.

The package never creates browser, application, Docker or per-user TileCache storage.

Optional synthetic target layer

The adapter accepts an optional provider-neutral Ghost Pin layer for bounded product sandboxes. It uses the canonical elevated-spike presentation: terrain-relative stem, outlined head, label plate and independent camera-height visibility for target and label. The layer is controlled by the existing targets visibility flag and does not create a Data Product, Engine command or authoritative map.moving_object.

Consumers own generation, persistence and explicit removal of synthetic positions. The adapter only:

• resolves the centre of the current visible globe through its imperative getViewAnchor() handle;
• renders declared numeric positions;
• advances optional motion inside the declared radius; and
• returns the current positions through snapshotGhostPins() for an explicit product save.

The elevated head and stem use non-constant Cesium properties so their ground height is resolved again after asynchronous terrain tiles arrive. The stem also keeps the same material as its depth-fail fallback; an early ellipsoid height must not leave a visible head with its stem hidden below terrain.

Motion never recreates the Cesium viewer or any provider. A renderer teardown stops its single animation frame loop.