@zephytiju/prism-geovision-embed 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# @zephytiju/prism-geovision-embed
+
+Platform Prism **geovision-embed** micro-UI (component id `"geovision-embed"`) — the render-slot
+component of the CLOSED dossier-embed contract (GeoVision ↔ Dossier Editor coordination,
+2026-09-22; the agreed channel summary lives in the GeoVision wiki docs below). The editor's chrome
+(title / SRC FILE / VIEW ▾ / ↗) is the EDITOR's; this package owns ONLY the slot, and every internal
+control (compact layer rail, video-like replay, …) stays inside it — nothing an embed does
+navigates away.
+
+## The contract (implemented exactly)
+
+```tsx
+<GeovisionEmbed sourceFileRef viewId mode? interactionMode? 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 |
+| `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) |
+| `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.
+
+Agreed coordination record: task list
+https://applink.feishu.cn/client/todo/task_list?guid=33ec590f-7c59-4ace-b069-53c649fc55ab and the
+authoritative designs:
+- https://qcnwge0wy4s0.feishu.cn/wiki/IZ55wbfHPiqag5kT5eGckDlJnXf
+- https://qcnwge0wy4s0.feishu.cn/wiki/DZ78w8NneizBNhkhuE2cCyp5nRb
+- https://qcnwge0wy4s0.feishu.cn/wiki/DOljwdYuRib4uIkbRaGcu1pNnSc
+
+## How it renders
+
+1. **Resolve** `{ sourceFileRef, viewId }` via `createFileEntryClient(useLatticeTransport()).read`
+   — the HOST supplies the transport; the embed installs NO executor of its own, so in static mode
+   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`).
+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).
+
+## 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):
+
+- `.npmrc` sets `legacy-peer-deps=true` so npm never auto-installs the peers;
+- 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`.
+
+Per the owner gate this package is NOT published or tagged from this work.
+
+## 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 run build      # emits dist/ with registry peer imports
+```
+
+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).

package/dist/EmbedBody.d.ts

@@ -0,0 +1,17 @@
+import type { GeovisionViewFile } from "@zephytiju/lattice-common-bundle/geovisionView";
+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).
+ */
+export declare function EmbedBody({ file, locale, staticFrame, strings, }: {
+    readonly file: GeovisionViewFile;
+    readonly locale: "en" | "zh-CN";
+    readonly staticFrame: boolean;
+    readonly strings: GeovisionEmbedStrings;
+}): React.ReactElement;
+//# sourceMappingURL=EmbedBody.d.ts.map

package/dist/EmbedBody.d.ts.map

@@ -0,0 +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"}

package/dist/EmbedBody.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } 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";
+/**
+ * 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).
+ */
+export function EmbedBody({ file, locale, staticFrame, 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: {
+                width: "100%",
+                height: "100%",
+                display: "flex",
+                flexDirection: "column",
+                overflow: "hidden",
+                ...(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 }) })] }) }));
+}

package/dist/GeovisionEmbed.d.ts

@@ -0,0 +1,20 @@
+import type { GeovisionEmbedProps } from "./types.js";
+/** Contract minimum slot height (px) — below it the embed degrades to a static frame. */
+export declare const MIN_RICH_HEIGHT = 240;
+/**
+ * Platform Prism geovision-embed micro-UI (component id "geovision-embed")
+ * — the agreed dossier-embed render component:
+ * `<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).
+ */
+export declare function GeovisionEmbed({ sourceFileRef, viewId, mode, interactionMode, locale, width, height, }: GeovisionEmbedProps): React.ReactElement;
+//# sourceMappingURL=GeovisionEmbed.d.ts.map

package/dist/GeovisionEmbed.d.ts.map

@@ -0,0 +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"}

package/dist/GeovisionEmbed.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { useLatticeTransport } from "@zephytiju/prism-react";
+import { stringsForLocale } from "./locales/index.js";
+import { useResolvedView } from "./resolveView.js";
+import { EmbedBody } from "./EmbedBody.js";
+/** Contract minimum slot height (px) — below it the embed degrades to a static frame. */
+export const MIN_RICH_HEIGHT = 240;
+/**
+ * Platform Prism geovision-embed micro-UI (component id "geovision-embed")
+ * — the agreed dossier-embed render component:
+ * `<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).
+ */
+export function GeovisionEmbed({ sourceFileRef, viewId, mode = "static", interactionMode = "rich", locale = "en", width = "100%", height, }) {
+    const strings = stringsForLocale(locale);
+    const transport = useLatticeTransport();
+    const resolved = useResolvedView(transport, sourceFileRef, viewId);
+    const containerRef = useRef(null);
+    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: {
+            width,
+            height: height ?? "100%",
+            position: "relative",
+            overflow: "hidden",
+            background: "var(--mantine-color-panel-filled)",
+            border: "1px solid var(--mantine-color-border-filled)",
+        }, children: [resolved.phase.phase === "loading" ? (_jsx("div", { "data-testid": "geovision-embed-loading", style: { padding: 12, fontSize: 10, fontFamily: "var(--mantine-font-family-monospace)", color: "var(--mantine-color-muted-filled)" }, children: strings.loading })) : null, resolved.phase.phase === "error" ? (_jsxs("div", { "data-testid": "geovision-embed-error", "data-error-code": resolved.phase.code, style: { padding: 12, display: "flex", flexDirection: "column", gap: 6 }, children: [_jsx("span", { style: { fontSize: 10, fontFamily: "var(--mantine-font-family-monospace)", color: "var(--mantine-color-error-filled)" }, children: resolved.phase.code === "not-found"
+                            ? 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] }));
+}

package/dist/describeViews.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+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;
+/**
+ * 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.
+ */
+export declare function describeViews(sourceFileRef: string, transport?: LatticeTransport): Promise<readonly GeovisionViewDescriptor[]>;
+//# sourceMappingURL=describeViews.d.ts.map

package/dist/describeViews.d.ts.map

@@ -0,0 +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"}

package/dist/describeViews.js

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+import { createFileEntryClient } from "@zephytiju/lattice-common-interfaces";
+import { createLatticeTransport } from "@zephytiju/prism-react";
+import { readGeovisionView } from "@zephytiju/lattice-common-bundle/geovisionView";
+/** UTC "YYYY-MM-DD HH:MM" label for the descriptor name. */
+function savedAtLabel(savedAt) {
+    const ms = Date.parse(savedAt);
+    if (!Number.isFinite(ms))
+        return savedAt;
+    const date = new Date(ms);
+    const yyyy = date.getUTCFullYear();
+    const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const dd = String(date.getUTCDate()).padStart(2, "0");
+    const hh = String(date.getUTCHours()).padStart(2, "0");
+    const mi = String(date.getUTCMinutes()).padStart(2, "0");
+    return `${yyyy}-${mm}-${dd} ${hh}:${mi} UTC`;
+}
+/** Summarizes the painted map variant from the file's layer set. */
+export function previewKindFor(layers) {
+    if (layers.some((layer) => layer.kind === "side-color"))
+        return "side-color";
+    if (layers.some((layer) => layer.kind === "heat"))
+        return "heat";
+    return "normal";
+}
+/** Descriptor for a validated file (one saved view per file). */
+export function describeFile(sourceFileRef, savedBy, savedAt, layers) {
+    return {
+        viewId: sourceFileRef,
+        name: `${savedBy} · ${savedAtLabel(savedAt)}`,
+        previewKind: previewKindFor(layers),
+    };
+}
+/**
+ * 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.
+ */
+export async function describeViews(sourceFileRef, transport = createLatticeTransport()) {
+    try {
+        const result = await createFileEntryClient(transport).read({ ref: sourceFileRef });
+        const check = readGeovisionView(result.content);
+        if (!check.ok)
+            return [];
+        const file = check.file;
+        return [describeFile(sourceFileRef, file.savedBy, file.savedAt, file.view.layers)];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { GeovisionEmbed, MIN_RICH_HEIGHT } from "./GeovisionEmbed.js";
+export { describeViews, describeFile, previewKindFor } from "./describeViews.js";
+export type { GeovisionViewDescriptor } from "./types.js";
+export type { GeovisionEmbedInteractionMode, GeovisionEmbedMode, GeovisionEmbedProps, RailLayerState, EmbedFilePhase, } from "./types.js";
+export { ENTITY_RESULTS_CHANNEL, SELECTED_ENTITY_CHANNEL, seedFromFile } from "./seed.js";
+export { buildTracks, positionAt, replayTimeLabel, hasMotion } from "./map/replay.js";
+export type { ReplayTrack, ReplayWaypoint, ReplayWindow } from "./map/replay.js";
+export { boundsFor, project } from "./map/projection.js";
+export { heatBlobs, matchesSelection, kernelWeight } from "./map/heat.js";
+export { paintFor, withinSideIndices } from "./map/sideColoring.js";
+export { en, zhCN, locales, stringsForLocale } from "./locales/index.js";
+export type { GeovisionEmbedLocale, GeovisionEmbedStrings } from "./locales/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACjF,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,YAAY,EACV,6BAA6B,EAC7B,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC1F,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACtF,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export { GeovisionEmbed, MIN_RICH_HEIGHT } from "./GeovisionEmbed.js";
+export { describeViews, describeFile, previewKindFor } from "./describeViews.js";
+export { ENTITY_RESULTS_CHANNEL, SELECTED_ENTITY_CHANNEL, seedFromFile } from "./seed.js";
+export { buildTracks, positionAt, replayTimeLabel, hasMotion } from "./map/replay.js";
+export { boundsFor, project } from "./map/projection.js";
+export { heatBlobs, matchesSelection, kernelWeight } from "./map/heat.js";
+export { paintFor, withinSideIndices } from "./map/sideColoring.js";
+export { en, zhCN, locales, stringsForLocale } from "./locales/index.js";

package/dist/locales/en.json

@@ -0,0 +1,29 @@
+{
+  "geovision-embed": {
+    "loading": "LOADING VIEW…",
+    "errNotFound": "FILE NOT FOUND",
+    "errInvalid": "FILE FAILED VALIDATION",
+    "errUnknownView": "UNKNOWN VIEW",
+    "retry": "RETRY",
+    "slotAria": "Geovision embed",
+    "mapAria": "Situation mini-map",
+    "railTitle": "LAYERS",
+    "railOverlay": "MARKERS",
+    "railSideColor": "SIDE COLORING",
+    "railHeat": "HEAT",
+    "railOpacity": "OPACITY",
+    "railOptions": "LAYER OPTIONS",
+    "replayPlay": "PLAY",
+    "replayPause": "PAUSE",
+    "replayScrub": "Replay progress",
+    "replayTime": "POSITION",
+    "replayOff": "NO TIMELINE EVENTS",
+    "staticFrame": "STATIC FRAME",
+    "fluxTitle": "RELATIONS",
+    "fluxSubtitle": "SNAPSHOT GRAPH",
+    "timelineTitle": "TIMELINE",
+    "timelineSubtitle": "SNAPSHOT EVENTS",
+    "statsTitle": "STATISTICS",
+    "statsSubtitle": "SNAPSHOT DERIVED"
+  }
+}

package/dist/locales/index.d.ts

@@ -0,0 +1,79 @@
+import enBundle from "./en.json";
+/**
+ * Locales the geovision-embed micro-UI bundles. Every component-authored UI
+ * string is resolved from these bundles (statically imported,
+ * resolveJsonModule); the component never hardcodes copy. Hosts can deep-
+ * merge their own tables over `locales` for composition-level overrides.
+ */
+export type GeovisionEmbedLocale = "en" | "zh-CN";
+/** Per-locale string table — the keys of the en bundle, widened to string. */
+export type GeovisionEmbedStrings = {
+    readonly [K in keyof typeof enBundle["geovision-embed"]]: string;
+};
+/** Parsed en locale bundle (namespaced under the component id "geovision-embed"). */
+export declare const en: {
+    "geovision-embed": {
+        loading: string;
+        errNotFound: string;
+        errInvalid: string;
+        errUnknownView: string;
+        retry: string;
+        slotAria: string;
+        mapAria: string;
+        railTitle: string;
+        railOverlay: string;
+        railSideColor: string;
+        railHeat: string;
+        railOpacity: string;
+        railOptions: string;
+        replayPlay: string;
+        replayPause: string;
+        replayScrub: string;
+        replayTime: string;
+        replayOff: string;
+        staticFrame: string;
+        fluxTitle: string;
+        fluxSubtitle: string;
+        timelineTitle: string;
+        timelineSubtitle: string;
+        statsTitle: string;
+        statsSubtitle: string;
+    };
+};
+/** Parsed zh-CN locale bundle. */
+export declare const zhCN: {
+    "geovision-embed": {
+        loading: string;
+        errNotFound: string;
+        errInvalid: string;
+        errUnknownView: string;
+        retry: string;
+        slotAria: string;
+        mapAria: string;
+        railTitle: string;
+        railOverlay: string;
+        railSideColor: string;
+        railHeat: string;
+        railOpacity: string;
+        railOptions: string;
+        replayPlay: string;
+        replayPause: string;
+        replayScrub: string;
+        replayTime: string;
+        replayOff: string;
+        staticFrame: string;
+        fluxTitle: string;
+        fluxSubtitle: string;
+        timelineTitle: string;
+        timelineSubtitle: string;
+        statsTitle: string;
+        statsSubtitle: string;
+    };
+};
+/** All bundled locale bundles keyed by locale id — for downstream deep-merge. */
+export declare const locales: Record<GeovisionEmbedLocale, {
+    readonly "geovision-embed": GeovisionEmbedStrings;
+}>;
+/** Resolves the string table for a locale, falling back to en. */
+export declare function stringsForLocale(locale: GeovisionEmbedLocale | string | undefined): GeovisionEmbedStrings;
+//# sourceMappingURL=index.d.ts.map

package/dist/locales/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/locales/index.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,WAAW,CAAC;AAGjC;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC;AAElD,8EAA8E;AAC9E,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,EAAE,CAAC,IAAI,MAAM,OAAO,QAAQ,CAAC,iBAAiB,CAAC,GAAG,MAAM;CACjE,CAAC;AAOF,qFAAqF;AACrF,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAW,CAAC;AAE3B,kCAAkC;AAClC,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAa,CAAC;AAE/B,iFAAiF;AACjF,eAAO,MAAM,OAAO;gCAZsD,qBAAqB;EAYjE,CAAC;AAE/B,kEAAkE;AAClE,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,GAChD,qBAAqB,CAGvB"}

package/dist/locales/index.js

@@ -0,0 +1,18 @@
+import enBundle from "./en.json";
+import zhCNBundle from "./zh-CN.json";
+const bundles = {
+    en: enBundle,
+    "zh-CN": zhCNBundle,
+};
+/** Parsed en locale bundle (namespaced under the component id "geovision-embed"). */
+export const en = enBundle;
+/** Parsed zh-CN locale bundle. */
+export const zhCN = zhCNBundle;
+/** All bundled locale bundles keyed by locale id — for downstream deep-merge. */
+export const locales = bundles;
+/** Resolves the string table for a locale, falling back to en. */
+export function stringsForLocale(locale) {
+    if (locale === "zh-CN")
+        return bundles["zh-CN"]["geovision-embed"];
+    return bundles.en["geovision-embed"];
+}

package/dist/locales/zh-CN.json

@@ -0,0 +1,29 @@
+{
+  "geovision-embed": {
+    "loading": "正在加载视图…",
+    "errNotFound": "文件不存在",
+    "errInvalid": "文件校验失败",
+    "errUnknownView": "未知视图",
+    "retry": "重试",
+    "slotAria": "地理视野嵌入",
+    "mapAria": "态势小地图",
+    "railTitle": "图层",
+    "railOverlay": "标记",
+    "railSideColor": "阵营配色",
+    "railHeat": "热力",
+    "railOpacity": "不透明度",
+    "railOptions": "图层选项",
+    "replayPlay": "播放",
+    "replayPause": "暂停",
+    "replayScrub": "回放进度",
+    "replayTime": "位置",
+    "replayOff": "无时间线事件",
+    "staticFrame": "静态帧",
+    "fluxTitle": "关系图",
+    "fluxSubtitle": "快照关系",
+    "timelineTitle": "时间线",
+    "timelineSubtitle": "快照事件",
+    "statsTitle": "统计分析",
+    "statsSubtitle": "快照派生"
+  }
+}

package/dist/map/MiniMap.d.ts

@@ -0,0 +1,21 @@
+import type { GeovisionViewFile } from "@zephytiju/lattice-common-bundle/geovisionView";
+import type { RailLayerState } from "../types.js";
+import { type ReplayWindow } from "./replay.js";
+import type { GeovisionEmbedStrings } from "../locales/index.js";
+/**
+ * The simplified STATIC EQUIRECTANGULAR mini-map: an SVG surface over the
+ * snapshot's located entities — normal markers from the overlay layer,
+ * kernel-density blobs from each enabled heat layer, side-color mapping
+ * applied to marker fills/outlines, and (when the replay is scrubbed) the
+ * entities at their interpolated track positions with the static positions
+ * faded underneath. Display-only; pointer capture stays on the slot.
+ */
+export declare function MiniMap({ file, container, rail, replayFraction, replayWindow, strings, }: {
+    readonly file: GeovisionViewFile;
+    readonly container: HTMLElement | null;
+    readonly rail: readonly RailLayerState[];
+    readonly replayFraction: number;
+    readonly replayWindow: ReplayWindow;
+    readonly strings: GeovisionEmbedStrings;
+}): React.ReactElement;
+//# sourceMappingURL=MiniMap.d.ts.map

package/dist/map/MiniMap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MiniMap.d.ts","sourceRoot":"","sources":["../../src/map/MiniMap.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,OAAO,EAAsC,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAEpF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,EACtB,IAAI,EACJ,SAAS,EACT,IAAI,EACJ,cAAc,EACd,YAAY,EACZ,OAAO,GACR,EAAE;IACD,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IACzC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAC;CACzC,GAAG,KAAK,CAAC,YAAY,CAyHrB"}