# 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.