feat(map): publish shared Cesium adapter

2026-07-29 16:44:54 +03:00
parent c5a6a58948
commit c293d748f5
11 changed files with 923 additions and 2 deletions
@@ -0,0 +1,52 @@
+# 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.
+
+## 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`.
+
+## 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.