@zephytiju/prism-geovision-embed 0.1.0 → 0.2.0

package/README.md

@@ -7,26 +7,44 @@ component of the CLOSED dossier-embed contract (GeoVision ↔ Dossier Editor coo
 control (compact layer rail, video-like replay, …) stays inside it — nothing an embed does
 navigates away.
 
+**The embed is a DISPATCHER**: one invocation renders exactly ONE variant — never a stacked
+dashboard. The saved view's `previewKind` selects it:
+
+| `previewKind` | Renders | Chrome |
+| --- | --- | --- |
+| `map` | the **Cesium engine** map (default, `engine="cesium"`): the same zoom/rotate/tilt/pan camera as the globe viewport on an ION-FREE CesiumJS/Resium viewer — an SVG snapshot placeholder crossfading into the lazily-mounted engine with the video-like replay control on top | replay control only — no tools, no rail, no floatboxes, no fusion board, no view-mode cycling, no SAVE |
+| `map` (`engine="svg"`) | the lighter static SVG map (markers / heat / side coloring + video-like replay) | compact layer rail + replay control |
+| `relational` | `@zephytiju/prism-relation-fluxboard` | none — rendered as-is |
+| `timeline` | `@zephytiju/prism-timeline-board` | none — rendered as-is |
+| `stats` | `@zephytiju/prism-stats-panel` | none — rendered as-is |
+
+Whatever renders fills the slot's full width/height (a scoped fit rule widens the packages'
+intrinsic standalone widths to the slot); unknown or missing `previewKind` renders the localized
+UNSUPPORTED PREVIEW KIND frame.
+
 ## The contract (implemented exactly)
 
 ```tsx
-<GeovisionEmbed sourceFileRef viewId mode? interactionMode? locale? width height />
+<GeovisionEmbed sourceFileRef viewId mode? interactionMode? engine? resolutionScale? locale? width height />
 ```
 
 | Prop | Type | Default | Contract |
 | --- | --- | --- | --- |
 | `sourceFileRef` | `string` | — | stable ref addressing the saved geovision-view file (`IFileEntry.read`) |
-| `viewId` | `string` | — | the saved view to render; a file carries exactly one view, so the viewId is the file ref itself — a mismatch renders the localized UNKNOWN VIEW frame |
+| `viewId` | `string` | — | the saved view to render — `${sourceFileRef}#${previewKind}`, exactly as `describeViews` lists it; a viewId addressing another file renders UNKNOWN VIEW, and one with an unknown/missing previewKind renders UNSUPPORTED PREVIEW KIND |
 | `mode` | `"static" \| "live"` | `"static"` | v1: `live` is reserved and behaves as `static` (no live fetches) |
 | `interactionMode` | `"rich" \| "static"` | `"rich"` | `rich` captures pointer events inside the slot for inline interactions; `static` renders a static frame (also forced below 240 px height) |
+| `engine` | `"cesium" \| "svg"` | `"cesium"` | the MAP variant's render engine: the CesiumJS engine embed (same zoom/rotate as the globe) or the lighter static SVG variant. Ignored by the other preview kinds; the degradation paths always fall back to the SVG snapshot |
+| `resolutionScale` | `number` | `0.75` | the Cesium engine's render resolution scale — the embed's GPU/retina footprint cap. Ignored by the `"svg"` engine |
 | `locale` | `"en" \| "zh-CN"` | `"en"` | the embed renders in the editor's active locale (unknown locales fall back to en) |
 | `width` / `height` | `number \| string` | `"100%"` / `"100%"` | slot size; below 240 px height the embed degrades to a static frame with no pointer capture |
 
 `GeovisionEmbed.describeViews(sourceFileRef)` feeds the editor's VIEW ▾ dropdown: it reads +
-validates the file and returns `{ viewId, name, previewKind }[]` (one saved view per file; the name
-is derived from the file's recorded provenance — `savedBy · save time` — because the format carries
-no name field; `previewKind` summarizes the painted map variant: `normal` / `heat` /
-`side-color`). Fails closed to an empty list for unreadable or invalid files.
+validates the file and returns `{ viewId, name, previewKind }[]` — ONE view per previewKind
+(`map` / `relational` / `timeline` / `stats`), `viewId = ${fileRef}#${previewKind}` (the file
+format is closed and carries no extension fields, so the per-kind views are addressed by
+convention over the stable file ref; the name derives from the recorded provenance because the
+format carries no name field). Fails closed to an empty list for unreadable or invalid files.
 
 Agreed coordination record: task list
 https://applink.feishu.cn/client/todo/task_list?guid=33ec590f-7c59-4ace-b069-53c649fc55ab and the
@@ -42,60 +60,136 @@ authoritative designs:
    no live fetches occur beyond the host's own routes.
 2. **Validate** fail-closed through the authoritative format
    (`@zephytiju/lattice-common-bundle/geovisionView`): structure AND digest. Failures render
-   localized frames (`not-found` / `invalid` / `unknown-view`).
+   localized frames (`not-found` / `invalid` / `unknown-view` / `unknown-preview`).
 3. **Seed** an isolated `<ChannelScope>` — `query-box.entity-results` carries the snapshot
    projection, `search-results.selected-entity` the workspace's selected entity — so every embed
-   renders its own file and nothing leaks across embeds on the same page.
-4. **Mount the REAL packages inside the scope**: `@zephytiju/prism-relation-fluxboard`,
-   `@zephytiju/prism-timeline-board` and `@zephytiju/prism-stats-panel` (their internal fetches
-   flow through the host transport; in the demo the mock executor answers from the file's
-   snapshot), plus the NEW simplified map:
-   - a static equirectangular SVG mini-map over the snapshot's located entities;
-   - layers from the file — normal markers (overlay), kernel-density blobs per enabled heat layer
-     (simplified variant of the globe's heat kernel), side-color mapping applied to marker
-     fills/outlines (`solid` / `stripe` / `accent`). Tag matchers apply to the item's stream
-     `type` (the kinds≡tags convention the recorded behavior uses for heat selections) because
-     the format's `EntityResultItem` declares only `id/type/label/lat/lon`;
-   - the compact layer rail — the same click/long-press contract as the globe's rail at compact
-     density (click toggles, long-press/right-click opens the anchored opacity options; changes
-     are local to the surface, persisted only via the editor's block config);
-   - the VIDEO-LIKE replay control — play/pause + progress scrubbing entity positions across the
-     snapshot's time-windowed timeline events (tracks interpolate linearly by time between
-     deterministic waypoints derived from the events; display-only).
+   renders its own file and nothing leaks across embeds on the same page (the 2×2 demo grid runs
+   four of them side by side).
+4. **Dispatch** on the view's `previewKind` — exactly ONE of:
+   - **map, Cesium engine (default)** — the SAME engine/zoom/rotate as the globe viewport
+     (`cesium` 1.143.0 + `resium` 1.24.0, identical to `@zephytiju/prism-globe-viewport`),
+     wrapped in an EMBED-BUDGET architecture:
+     - **snapshot placeholder** — the existing SVG mini-map renders from the same snapshot data
+       the moment the embed mounts (zero Cesium cost — the instant visual; see the performance
+       strategy below for the lazy handover);
+     - **lazy mount** — an `IntersectionObserver` on the embed container boots the Cesium
+       `Viewer` only while the slot is on screen (deferred off the observer's own path, so the
+       WebGL boot never blocks the interaction that revealed it); once the viewer element
+       exists the layers crossfade (SVG out, canvas in). Scrolling the slot out of view — or
+       unmounting — unmounts the Resium `<Viewer>`, whose teardown **destroys** the WebGL
+       context/workers; re-entry re-observes and boots again;
+     - **idle GPU** — `requestRenderMode: true` + `maximumRenderTimeChange: Infinity` keep the
+       render loop asleep when nothing changes (Cesium's camera input handlers request renders
+       themselves on zoom/rotate/tilt/pan, which stay fully enabled — the
+       `ScreenSpaceCameraController` is untouched); `resolutionScale` 0.75 (the embed prop) caps
+       the raster footprint, `scene.globe.tileCacheSize` 10 bounds the tile memory, every UI
+       widget is disabled (animation/timeline/baseLayerPicker/geocoder/homeButton/
+       sceneModePicker/navigationHelpButton/fullscreenButton/infoBox/selectionIndicator) and the
+       sky is off (`skyBox: false`, `skyAtmosphere: false`). CesiumJS 1.143 carries no
+       `creditsDisplay` constructor option, so the credit strip (the only chrome Cesium still
+       paints with everything else disabled) is suppressed by a rule scoped to the embed's
+       stage; the imagery credit stays attached to the provider;
+     - **ion-free imagery + camera restore** — the saved view's `baseLayer.urlTemplate` (with its
+       credit) feeds a `UrlTemplateImageryProvider`, falling back to the
+       `OpenStreetMapImageryProvider` default — never a Cesium ion asset; terrain is the default
+       ellipsoid. The camera is restored from the saved view's `camera` state
+       `{lon, lat, height}` — the same `IGeoView` serialization the globe viewport saves;
+     - **markers + replay** — entity markers derive from the snapshot (the same side-color
+       derivation the SVG mini-map paints: token-colored points + mono labels, the workspace's
+       selected entity emphasized). The video-like replay control overlays the canvas; each
+       scrub tick re-derives the marker positions with the SAME track math as the SVG variant
+       (linear interpolation between deterministic waypoints) and explicitly calls
+       `scene.requestRender()` — under `requestRenderMode` a scrub tick renders exactly one
+       frame;
+     - **no other chrome** — no tools, no layer rail, no floatboxes, no fusion board, no
+       view-mode cycling, no SAVE: just basemap + markers + replay;
+   - **map, SVG engine (`engine="svg"`)** — the lighter static variant hosts opt into: the
+     static equirectangular SVG mini-map filling the slot with
+     - layers from the file — normal markers (overlay), kernel-density blobs per enabled heat
+       layer (simplified variant of the globe's heat kernel), side-color mapping applied to marker
+       fills/outlines (`solid` / `stripe` / `accent`). Tag matchers apply to the item's stream
+       `type` (the kinds≡tags convention the recorded behavior uses for heat selections) because
+       the format's `EntityResultItem` declares only `id/type/label/lat/lon`;
+     - the compact layer rail — the same click/long-press contract as the globe's rail at compact
+       density (click toggles, long-press/right-click opens the anchored opacity options; changes
+       are local to the surface, persisted only via the editor's block config);
+     - the VIDEO-LIKE replay control — play/pause + progress scrubbing entity positions across the
+       snapshot's time-windowed timeline events (tracks interpolate linearly by time between
+       deterministic waypoints derived from the events; display-only);
+   - **relational / timeline / stats** — the REAL packages mounted inside the scope, rendered
+     as-is (their internal fetches flow through the host transport; in the demo the mock executor
+     answers from the file's snapshot).
+
+### Degradation path
+
+`engine="svg"`, `interactionMode="static"` and slots below `MIN_RICH_HEIGHT` (240 px) NEVER
+mount Cesium: the map variant renders the SVG snapshot only (the SVG mini-map plus, on the
+rich-SVG path, its rail/replay chrome), and static frames additionally capture no pointer events.
+Off-screen rich Cesium embeds hold no GPU resources either — the observer gate is the second
+half of the degradation story (visible ⇒ engine, invisible ⇒ destroyed).
+
+### Performance strategy (the Cesium engine in one paragraph)
+
+Instant SVG from the snapshot (no engine cost at first paint) → the engine boots only when the
+slot is actually visible (IntersectionObserver, boot deferred to an idle callback) → once booted
+the render loop sleeps (`requestRenderMode` + `maximumRenderTimeChange: Infinity`; Cesium's own
+camera handlers wake it for zoom/rotate/tilt/pan) → replay ticks and marker moves render exactly
+one explicit `scene.requestRender()` frame each → the raster is capped (`resolutionScale` 0.75,
+configurable) and tile memory bounded (`tileCacheSize` 10) → leaving the viewport destroys the
+viewer outright (WebGL context + workers freed), and re-entry rebuilds it.
 
 ## Peer dependencies / registry status
 
-The three mounted component packages are REGISTRY PEERS (`>=0.1.0`). They are not yet on npm —
-their tag-triggered trusted-publishing runs returned 404 (the npm-side trusted-publisher
-registration for the new package names appears pending; `v0.1.0` tags are already pushed), and
-the ambient npm auth is expired, so they could not be published from this work. Until the first
-release the dev surface installs them from **vendored tarballs** produced by `npm pack` in the
-sibling repos (`vendor/*.tgz`, referenced as `file:` devDependencies):
+The three mounted component packages are REGISTRY PEERS (`>=0.1.0`) and are published on npm;
+the dev surface pins the same registry specifiers as devDependencies (no vendored tarballs
+since 0.2.0):
 
-- `.npmrc` sets `legacy-peer-deps=true` so npm never auto-installs the peers;
+- `.npmrc` keeps `legacy-peer-deps=true` so npm never auto-installs the peers on top of the
+  explicit dev pins;
 - typecheck/tests/demo run against the REAL packaged output (dist) of the siblings, exactly what
-  the registry will serve once published — the jsdom run inlines them and stubs the
-  `@xyflow/react` stylesheet (`vitest.config.ts`);
-- the EMITTED package keeps the registry specifiers (`import … from
-  "@zephytiju/prism-relation-fluxboard"`), so hosts resolve them normally once published;
-- when the siblings land on npm, drop `vendor/`, pin registry versions in devDependencies and
-  remove `legacy-peer-deps`.
+  the registry serves — the jsdom run inlines them and stubs the `@xyflow/react` stylesheet
+  (`vitest.config.ts`).
 
-Per the owner gate this package is NOT published or tagged from this work.
+The Cesium engine comes from the REGISTRY as regular dependencies — `cesium` 1.143.0 +
+`resium` 1.24.0 (the same versions and `@cesium/*` overrides as
+`@zephytiju/prism-globe-viewport`), so hosts install the identical engine the globe runs. The
+demo's vite config serves Cesium's static asset tree (Workers/Assets/ThirdParty/Widgets)
+straight from `node_modules` via `publicDir` with `CESIUM_BASE_URL="/"` — nothing is bundled or
+vendored, and no ion endpoint is configured anywhere.
+
+Per the owner gate this package is NOT published or tagged from this work (the npm `0.1.0` is the
+superseded stacked-dashboard build; `0.2.0` is the dispatcher fix, published only after owner
+confirmation).
 
 ## Development
 
 ```bash
-npm install        # legacy-peer-deps (see .npmrc); peers come from vendor/*.tgz
-npm run typecheck  # tsc
-npm test           # vitest (jsdom) — 26 tests
-npm run dev        # vite demo (two embeds, two files, EN/中文, dark × light)
+npm install        # registry peers pinned as devDependencies (see .npmrc) + cesium/resium
+npm run typecheck  # tsc (against the REAL cesium/resium types)
+npm test           # vitest (jsdom) — 56 tests; cesium/resium stubbed at the resolver level
+npm run dev        # vite demo (2×2 grid: map on the Cesium engine + relational/timeline/stats,
+                   #   plus the engine="svg" fallback panel; EN/中文, dark × light)
 npm run build      # emits dist/ with registry peer imports
+npm run shot-demo  # captures /tmp/guanlan-review/demo-geovision-embed-v3.png
 ```
 
+**Tests** follow the globe viewport's mocking strategy: jsdom cannot host the ~30MB WebGL
+engine, so `vitest.config.ts` aliases `cesium`/`resium` to `test/stubs/` — plain surface stubs
+that record the Viewer constructor props, `camera.setView` calls, `scene.requestRender` counts,
+the `globe.tileCacheSize` assignment and viewer destroys. The library build (tsc) still
+typechecks against the real packages. `test/setup.ts` additionally installs an always-visible
+IntersectionObserver default; the cesium-engine suite installs its own controllable mock to
+drive enter/exit visibility transitions.
+
 Source layout (each module ≤250 lines): `src/GeovisionEmbed.tsx` (contract + failure frames),
-`src/resolveView.ts` (IFileEntry.read + fail-closed validation), `src/seed.ts` (ChannelScope
-seeding), `src/EmbedBody.tsx` (scoped composition of the real packages + map + rail + replay),
-`src/describeViews.ts`, `src/map/` (projection, replay math, heat blobs, side coloring, tokens,
-MiniMap, ReplayControl), `src/rail/LayerRailCompact.tsx`, `src/locales/` (en + zh-CN with exact
-key parity; `stringsForLocale` falls back to en).
+`src/resolveView.ts` (IFileEntry.read + fail-closed validation + previewKind resolution),
+`src/views.ts` (view-id addressing: `viewIdFor` / `previewKindOf` / `resolveViewKind`),
+`src/seed.ts` (ChannelScope seeding), `src/EmbedBody.tsx` (the DISPATCHER — one variant per
+invocation), `src/map/CesiumMapVariant.tsx` (the map variant's engine dispatch: SVG-only
+degradation paths + the Cesium engine surface — observer gate, ready-gate crossfade, replay
+wiring), `src/map/CesiumMarkersLayer.tsx` (the Resium entity layer),
+`src/map/cesiumModel.ts` (pure marker/camera/imagery derivations),
+`src/map/MapVariant.tsx` (the SVG variant + its chrome), `src/map/railState.ts` (shared
+initial-rail derivation), `src/describeViews.ts`, `src/map/` (projection, replay math, heat
+blobs, side coloring, tokens, MiniMap, ReplayControl), `src/rail/LayerRailCompact.tsx`,
+`src/locales/` (en + zh-CN with exact key parity; `stringsForLocale` falls back to en).

package/dist/EmbedBody.d.ts

@@ -1,17 +1,30 @@
 import type { GeovisionViewFile } from "@zephytiju/lattice-common-bundle/geovisionView";
+import type { GeovisionPreviewKind, GeovisionMapEngine } from "./types.js";
 import type { GeovisionEmbedStrings } from "./locales/index.js";
 /**
- * The seeded render surface: an ISOLATED ChannelScope carrying the file's
- * snapshot channels wraps the REAL packages (relation-fluxboard,
- * timeline-board, stats-panel) and the simplified mini-map. Every internal
- * control — the compact layer rail and the video-like replay — stays inside
- * the slot; nothing an embed does navigates away. Static frames wrap the
- * whole body with pointerEvents none (no pointer capture at all).
+ * The DISPATCHER: ONE invocation renders exactly ONE variant, selected by
+ * the saved view's previewKind —
+ *  - "map"        → the Cesium engine map (default) — an SVG snapshot
+ *                   placeholder crossfading into the lazily-mounted ION-FREE
+ *                   Cesium viewer with the video-like replay control on top;
+ *                   engine="svg" opts into the lighter static SVG map (the
+ *                   variant carrying the compact layer rail);
+ *  - "relational" → the real prism-relation-fluxboard, rendered as-is;
+ *  - "timeline"   → the real prism-timeline-board, rendered as-is;
+ *  - "stats"      → the real prism-stats-panel, rendered as-is.
+ * Whatever renders fills the slot's full width/height — no stacking, no
+ * sections, no tabs. An ISOLATED ChannelScope seeded from the view's
+ * snapshot wraps the variant, so every embed renders its own file and
+ * nothing leaks across embeds. Static frames wrap the body with
+ * pointerEvents none (no pointer capture at all).
  */
-export declare function EmbedBody({ file, locale, staticFrame, strings, }: {
+export declare function EmbedBody({ file, previewKind, locale, staticFrame, engine, resolutionScale, strings, }: {
     readonly file: GeovisionViewFile;
+    readonly previewKind: GeovisionPreviewKind;
     readonly locale: "en" | "zh-CN";
     readonly staticFrame: boolean;
+    readonly engine: GeovisionMapEngine;
+    readonly resolutionScale?: number;
     readonly strings: GeovisionEmbedStrings;
 }): React.ReactElement;
 //# sourceMappingURL=EmbedBody.d.ts.map

package/dist/EmbedBody.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmbedBody.d.ts","sourceRoot":"","sources":["../src/EmbedBody.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AAUxF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,MAAM,EACN,WAAW,EACX,OAAO,GACR,EAAE;IACD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;CACzC,GAAG,KAAK,CAAC,YAAY,CAiJrB"}
+{"version":3,"file":"EmbedBody.d.ts","sourceRoot":"","sources":["../src/EmbedBody.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AAMxF,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAyBhE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,WAAW,EACX,MAAM,EACN,WAAW,EACX,MAAM,EACN,eAAe,EACf,OAAO,GACR,EAAE;IACD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;CACzC,GAAG,KAAK,CAAC,YAAY,CA6DrB"}

package/dist/EmbedBody.js

@@ -1,81 +1,69 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useMemo } from "react";
 import { ChannelScope } from "@zephytiju/prism-react";
 import { RelationFluxboard } from "@zephytiju/prism-relation-fluxboard";
 import { TimelineBoard } from "@zephytiju/prism-timeline-board";
 import { StatsPanel } from "@zephytiju/prism-stats-panel";
 import { seedFromFile } from "./seed.js";
-import { MiniMap } from "./map/MiniMap.js";
-import { ReplayControl } from "./map/ReplayControl.js";
-import { hasMotion, buildTracks } from "./map/replay.js";
-import { LayerRailCompact } from "./rail/LayerRailCompact.js";
+import { CesiumMapVariant } from "./map/CesiumMapVariant.js";
 /**
- * The seeded render surface: an ISOLATED ChannelScope carrying the file's
- * snapshot channels wraps the REAL packages (relation-fluxboard,
- * timeline-board, stats-panel) and the simplified mini-map. Every internal
- * control — the compact layer rail and the video-like replay — stays inside
- * the slot; nothing an embed does navigates away. Static frames wrap the
- * whole body with pointerEvents none (no pointer capture at all).
+ * Scoped fit rules (unique to this component's slots): the mounted packages
+ * carry their own INTRINSIC inline root widths (460/540/360 px — their
+ * standalone panel sizes). Inside an embed the ONE dispatched variant must
+ * fill the slot's full width/height, so the direct package root yields to
+ * the slot contract (`!important` overrides their inline widths; the
+ * packages themselves render as-is, unmodified and un-wrapped in chrome).
  */
-export function EmbedBody({ file, locale, staticFrame, strings, }) {
+const FIT_CSS = [
+    ".geovision-embed-fit{width:100%;height:100%;min-width:0;min-height:0;overflow:hidden;}",
+    '.geovision-embed-fit>[data-testid="relation-fluxboard"],',
+    '.geovision-embed-fit>[data-testid="timeline-board"],',
+    '.geovision-embed-fit>[data-testid="stats-panel"]',
+    "{width:100% !important;height:100% !important;}",
+].join("");
+/** Full-slot wrapper — the ONE rendered variant fills the embed's width/height. */
+function variantSlot(children) {
+    return (_jsx("div", { className: "geovision-embed-fit", children: children }));
+}
+/**
+ * The DISPATCHER: ONE invocation renders exactly ONE variant, selected by
+ * the saved view's previewKind —
+ *  - "map"        → the Cesium engine map (default) — an SVG snapshot
+ *                   placeholder crossfading into the lazily-mounted ION-FREE
+ *                   Cesium viewer with the video-like replay control on top;
+ *                   engine="svg" opts into the lighter static SVG map (the
+ *                   variant carrying the compact layer rail);
+ *  - "relational" → the real prism-relation-fluxboard, rendered as-is;
+ *  - "timeline"   → the real prism-timeline-board, rendered as-is;
+ *  - "stats"      → the real prism-stats-panel, rendered as-is.
+ * Whatever renders fills the slot's full width/height — no stacking, no
+ * sections, no tabs. An ISOLATED ChannelScope seeded from the view's
+ * snapshot wraps the variant, so every embed renders its own file and
+ * nothing leaks across embeds. Static frames wrap the body with
+ * pointerEvents none (no pointer capture at all).
+ */
+export function EmbedBody({ file, previewKind, locale, staticFrame, engine, resolutionScale, strings, }) {
     const seeded = useMemo(() => seedFromFile(file), [file]);
-    const containerRef = useRef(null);
     // The mounted packages accept only en | "zh-CN" — unknown locales resolve
     // onto the en fallback before crossing the seam.
     const innerLocale = locale === "zh-CN" ? "zh-CN" : "en";
-    const initialRail = useMemo(() => file.view.layers.map((layer, index) => {
-        if (layer.kind === "overlay") {
-            return { id: `overlay-${String(index)}`, kind: "overlay", name: "markers", enabled: true, opacity: layer.opacity };
-        }
-        if (layer.kind === "heat") {
-            return { id: `heat-${String(index)}`, kind: "heat", name: layer.selection.name, enabled: true, opacity: layer.intensity };
-        }
-        return { id: `side-color-${String(index)}`, kind: "side-color", name: "sides", enabled: true, opacity: 1 };
-    }), [file]);
-    const [rail, setRail] = useState(initialRail);
-    const railForFile = useMemo(() => (rail.length === initialRail.length ? rail : initialRail), [rail, initialRail]);
-    const replayWindow = useMemo(() => {
-        const start = Date.parse(seeded.window.start);
-        const end = Date.parse(seeded.window.end);
-        return Number.isFinite(start) && Number.isFinite(end) && end > start
-            ? { startMs: start, endMs: end }
-            : { startMs: 0, endMs: 3600_000 };
-    }, [seeded]);
-    const [fraction, setFraction] = useState(0);
-    const [playing, setPlaying] = useState(false);
-    const onFraction = useCallback((next) => {
-        const clamped = Math.min(1, Math.max(0, next));
-        setFraction(clamped);
-        if (clamped >= 1)
-            setPlaying(false);
-    }, []);
-    const located = useMemo(() => (file.snapshot.entityResults?.items ?? []).filter((item) => item.lat !== undefined && item.lon !== undefined), [file]);
-    const motion = useMemo(() => hasMotion(buildTracks(located, file.snapshot.timelineEvents, replayWindow)), [located, file, replayWindow]);
-    const toggleLayer = useCallback((id) => {
-        setRail((previous) => previous.map((layer) => (layer.id === id ? { ...layer, enabled: !layer.enabled } : layer)));
-    }, []);
-    const setOpacity = useCallback((id, opacity) => {
-        setRail((previous) => previous.map((layer) => (layer.id === id ? { ...layer, opacity } : layer)));
-    }, []);
-    return (_jsx(ChannelScope, { seed: seeded.seed, children: _jsxs("div", { ref: containerRef, "data-testid": "geovision-embed-body", style: {
+    return (_jsx(ChannelScope, { seed: seeded.seed, children: _jsxs("div", { "data-testid": "geovision-embed-body", "data-preview-kind": previewKind, style: {
                 width: "100%",
                 height: "100%",
-                display: "flex",
-                flexDirection: "column",
                 overflow: "hidden",
+                position: "relative",
                 ...(staticFrame ? { pointerEvents: "none" } : {}),
-            }, children: [_jsxs("div", { style: { position: "relative", flex: "1 1 46%", minHeight: 120 }, children: [_jsx(MiniMap, { file: file, container: containerRef.current, rail: railForFile, replayFraction: fraction, replayWindow: replayWindow, strings: strings }), _jsx(LayerRailCompact, { layers: railForFile, disabled: staticFrame, strings: strings, onToggle: toggleLayer, onOpacity: setOpacity }), staticFrame ? (_jsx("div", { "data-testid": "geovision-embed-static-chip", style: {
-                                position: "absolute",
-                                right: 6,
-                                top: 6,
-                                fontSize: 8,
-                                padding: "1px 6px",
-                                borderRadius: 3,
-                                fontFamily: "var(--mantine-font-family-monospace)",
-                                background: "var(--mantine-color-input-filled)",
-                                color: "var(--mantine-color-muted-filled)",
-                                border: "1px solid var(--mantine-color-border-filled)",
-                            }, children: strings.staticFrame })) : null] }), _jsx(ReplayControl, { fraction: fraction, playing: playing, disabled: staticFrame || !motion, timeWindow: replayWindow, strings: strings, onFraction: onFraction, onTogglePlay: () => {
-                        setPlaying((value) => !value);
-                    } }), _jsxs("div", { style: { display: "flex", gap: 4, flex: "1 1 30%", minHeight: 96, padding: 4 }, children: [_jsx("div", { style: { flex: 1, minWidth: 0, overflow: "hidden" }, children: _jsx(RelationFluxboard, { locale: innerLocale, title: strings.fluxTitle, subtitle: strings.fluxSubtitle }) }), _jsx("div", { style: { width: 210, flexShrink: 0, overflow: "hidden" }, children: _jsx(StatsPanel, { locale: innerLocale, window: seeded.window, title: strings.statsTitle, subtitle: strings.statsSubtitle }) })] }), _jsx("div", { style: { height: 108, flexShrink: 0, padding: 4, overflow: "hidden" }, children: _jsx(TimelineBoard, { locale: innerLocale, defaultWindow: seeded.window, live: false, title: strings.timelineTitle, subtitle: strings.timelineSubtitle }) })] }) }));
+            }, children: [_jsx("style", { children: FIT_CSS }), previewKind === "map" ? (variantSlot(_jsx(CesiumMapVariant, { file: file, seed: seeded, staticFrame: staticFrame, engine: engine, resolutionScale: resolutionScale, strings: strings }))) : previewKind === "relational" ? (variantSlot(_jsx(RelationFluxboard, { locale: innerLocale }))) : previewKind === "timeline" ? (variantSlot(_jsx(TimelineBoard, { locale: innerLocale, defaultWindow: seeded.window, live: false }))) : (variantSlot(_jsx(StatsPanel, { locale: innerLocale, window: seeded.window }))), staticFrame ? (_jsx("div", { "data-testid": "geovision-embed-static-chip", style: {
+                        position: "absolute",
+                        right: 6,
+                        top: 6,
+                        fontSize: 8,
+                        padding: "1px 6px",
+                        borderRadius: 3,
+                        fontFamily: "var(--mantine-font-family-monospace)",
+                        background: "var(--mantine-color-input-filled)",
+                        color: "var(--mantine-color-muted-filled)",
+                        border: "1px solid var(--mantine-color-border-filled)",
+                        zIndex: 5,
+                    }, children: strings.staticFrame })) : null] }) }));
 }

package/dist/GeovisionEmbed.d.ts

@@ -3,18 +3,20 @@ import type { GeovisionEmbedProps } from "./types.js";
 export declare const MIN_RICH_HEIGHT = 240;
 /**
  * Platform Prism geovision-embed micro-UI (component id "geovision-embed")
- * — the agreed dossier-embed render component:
+ * — the agreed dossier-embed render component, as a DISPATCHER:
  * `<GeovisionEmbed sourceFileRef viewId mode? interactionMode? locale? width height />`.
  *
  * The component resolves { sourceFileRef, viewId } through the HOST-supplied
  * Lattice transport (IFileEntry.read — the embed installs NO executor of
  * its own, so in static mode no live fetches occur beyond the host's own
  * routes), validates the file against the authoritative geovision-view
- * format (fail-closed: structure + digest), then seeds an isolated
- * ChannelScope and mounts the real packages + the simplified SVG map.
- * "live" mode is reserved and behaves as static in v1. Below 240px height
- * or with interactionMode="static" the slot degrades to a static frame
- * (pointer-events captured nowhere).
+ * format (fail-closed: structure + digest), then reads the view's
+ * previewKind and renders exactly ONE variant — the simplified SVG map
+ * (with layers, heat, side coloring and replay) OR the real
+ * relation-fluxboard OR timeline-board OR stats-panel — each filling the
+ * slot's full width/height. "live" mode is reserved and behaves as static
+ * in v1. Below 240px height or with interactionMode="static" the slot
+ * degrades to a static frame (pointer-events captured nowhere).
  */
-export declare function GeovisionEmbed({ sourceFileRef, viewId, mode, interactionMode, locale, width, height, }: GeovisionEmbedProps): React.ReactElement;
+export declare function GeovisionEmbed({ sourceFileRef, viewId, mode, interactionMode, engine, resolutionScale, locale, width, height, }: GeovisionEmbedProps): React.ReactElement;
 //# sourceMappingURL=GeovisionEmbed.d.ts.map

package/dist/GeovisionEmbed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GeovisionEmbed.d.ts","sourceRoot":"","sources":["../src/GeovisionEmbed.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAItD,yFAAyF;AACzF,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,EAC7B,aAAa,EACb,MAAM,EACN,IAAe,EACf,eAAwB,EACxB,MAAa,EACb,KAAc,EACd,MAAM,GACP,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAwD1C"}
+{"version":3,"file":"GeovisionEmbed.d.ts","sourceRoot":"","sources":["../src/GeovisionEmbed.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAItD,yFAAyF;AACzF,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,aAAa,EACb,MAAM,EACN,IAAe,EACf,eAAwB,EACxB,MAAiB,EACjB,eAAe,EACf,MAAa,EACb,KAAc,EACd,MAAM,GACP,EAAE,mBAAmB,GAAG,KAAK,CAAC,YAAY,CAoE1C"}

package/dist/GeovisionEmbed.js

@@ -8,20 +8,22 @@ import { EmbedBody } from "./EmbedBody.js";
 export const MIN_RICH_HEIGHT = 240;
 /**
  * Platform Prism geovision-embed micro-UI (component id "geovision-embed")
- * — the agreed dossier-embed render component:
+ * — the agreed dossier-embed render component, as a DISPATCHER:
  * `<GeovisionEmbed sourceFileRef viewId mode? interactionMode? locale? width height />`.
  *
  * The component resolves { sourceFileRef, viewId } through the HOST-supplied
  * Lattice transport (IFileEntry.read — the embed installs NO executor of
  * its own, so in static mode no live fetches occur beyond the host's own
  * routes), validates the file against the authoritative geovision-view
- * format (fail-closed: structure + digest), then seeds an isolated
- * ChannelScope and mounts the real packages + the simplified SVG map.
- * "live" mode is reserved and behaves as static in v1. Below 240px height
- * or with interactionMode="static" the slot degrades to a static frame
- * (pointer-events captured nowhere).
+ * format (fail-closed: structure + digest), then reads the view's
+ * previewKind and renders exactly ONE variant — the simplified SVG map
+ * (with layers, heat, side coloring and replay) OR the real
+ * relation-fluxboard OR timeline-board OR stats-panel — each filling the
+ * slot's full width/height. "live" mode is reserved and behaves as static
+ * in v1. Below 240px height or with interactionMode="static" the slot
+ * degrades to a static frame (pointer-events captured nowhere).
  */
-export function GeovisionEmbed({ sourceFileRef, viewId, mode = "static", interactionMode = "rich", locale = "en", width = "100%", height, }) {
+export function GeovisionEmbed({ sourceFileRef, viewId, mode = "static", interactionMode = "rich", engine = "cesium", resolutionScale, locale = "en", width = "100%", height, }) {
     const strings = stringsForLocale(locale);
     const transport = useLatticeTransport();
     const resolved = useResolvedView(transport, sourceFileRef, viewId);
@@ -29,7 +31,7 @@ export function GeovisionEmbed({ sourceFileRef, viewId, mode = "static", interac
     const numericHeight = typeof height === "number" ? height : undefined;
     const richHeight = numericHeight === undefined || numericHeight >= MIN_RICH_HEIGHT;
     const staticFrame = interactionMode === "static" || !richHeight;
-    return (_jsxs("div", { ref: containerRef, "data-testid": "geovision-embed", "data-embed-mode": mode, "data-interaction-mode": staticFrame ? "static" : "rich", "data-file-ref": sourceFileRef, "aria-label": strings.slotAria, style: {
+    return (_jsxs("div", { ref: containerRef, "data-testid": "geovision-embed", "data-embed-mode": mode, "data-interaction-mode": staticFrame ? "static" : "rich", "data-file-ref": sourceFileRef, "data-view-id": viewId, "data-preview-kind": resolved.previewKind ?? "", "aria-label": strings.slotAria, style: {
             width,
             height: height ?? "100%",
             position: "relative",
@@ -40,5 +42,7 @@ export function GeovisionEmbed({ sourceFileRef, viewId, mode = "static", interac
                             ? strings.errNotFound
                             : resolved.phase.code === "invalid"
                                 ? strings.errInvalid
-                                : strings.errUnknownView }), _jsx("span", { style: { fontSize: 9, color: "var(--mantine-color-muted-filled)" }, children: resolved.phase.message })] })) : null, resolved.phase.phase === "ready" && resolved.file !== null ? (_jsx(EmbedBody, { file: resolved.file, locale: locale, staticFrame: staticFrame, strings: strings })) : null] }));
+                                : resolved.phase.code === "unknown-preview"
+                                    ? strings.errUnknownPreview
+                                    : strings.errUnknownView }), _jsx("span", { style: { fontSize: 9, color: "var(--mantine-color-muted-filled)" }, children: resolved.phase.message })] })) : null, resolved.phase.phase === "ready" && resolved.file !== null && resolved.previewKind !== null ? (_jsx(EmbedBody, { file: resolved.file, previewKind: resolved.previewKind, locale: locale, staticFrame: staticFrame, engine: engine, resolutionScale: resolutionScale, strings: strings })) : null] }));
 }

package/dist/describeViews.d.ts

@@ -1,26 +1,21 @@
 /**
  * describeViews(sourceFileRef) — the editor's VIEW ▾ dropdown source: reads
  * the file through the host Lattice transport, validates it against the
- * authoritative format, and lists what it contains. A geovision-view file
- * carries exactly ONE saved view, so the descriptor's viewId IS the file
- * ref; the display name is derived from the file's recorded provenance
- * (savedBy + save time — the format carries no name field), and previewKind
- * summarizes the painted map variant.
+ * authoritative format, and lists the views it can embed. A validated file
+ * carries one saved view PER previewKind (map / relational / timeline /
+ * stats — the dispatcher's variants), addressed `${fileRef}#${previewKind}`;
+ * the descriptor's viewId is exactly what the editor passes back to
+ * <GeovisionEmbed viewId=…> and previewKind labels the dropdown row.
  */
 import type { LatticeTransport } from "@zephytiju/prism-react";
 import type { GeovisionViewDescriptor } from "./types.js";
-/** Summarizes the painted map variant from the file's layer set. */
-export declare function previewKindFor(layers: readonly {
-    readonly kind: string;
-}[]): GeovisionViewDescriptor["previewKind"];
-/** Descriptor for a validated file (one saved view per file). */
-export declare function describeFile(sourceFileRef: string, savedBy: string, savedAt: string, layers: readonly {
-    readonly kind: string;
-}[]): GeovisionViewDescriptor;
+/** One descriptor per previewKind — the file's complete embeddable view list. */
+export declare function describeFile(sourceFileRef: string, savedBy: string, savedAt: string): readonly GeovisionViewDescriptor[];
 /**
- * Lists the file's saved views for the editor dropdown. Fails closed: an
- * unreadable or invalid file yields an empty list (the dropdown simply has
- * nothing to offer) — the EMBED surface renders the structured failure.
+ * Lists the file's saved views for the editor dropdown (one per
+ * previewKind). Fails closed: an unreadable or invalid file yields an empty
+ * list (the dropdown simply has nothing to offer) — the EMBED surface
+ * renders the structured failure.
  */
 export declare function describeViews(sourceFileRef: string, transport?: LatticeTransport): Promise<readonly GeovisionViewDescriptor[]>;
 //# sourceMappingURL=describeViews.d.ts.map

package/dist/describeViews.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"describeViews.d.ts","sourceRoot":"","sources":["../src/describeViews.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAe1D,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,uBAAuB,CAAC,aAAa,CAAC,CAInH;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,uBAAuB,CAM3J;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,gBAA2C,GACrD,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAU7C"}
+{"version":3,"file":"describeViews.d.ts","sourceRoot":"","sources":["../src/describeViews.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAK/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAe1D,iFAAiF;AACjF,wBAAgB,YAAY,CAC1B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,SAAS,uBAAuB,EAAE,CAMpC;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,aAAa,EAAE,MAAM,EACrB,SAAS,GAAE,gBAA2C,GACrD,OAAO,CAAC,SAAS,uBAAuB,EAAE,CAAC,CAU7C"}