@ggts-sh/svelte 0.43.0

package/dist/runtime/runtime.svelte.js

@@ -0,0 +1,233 @@
+/**
+ * Plot runtime: container sizing, model production (runPipeline + scale gate),
+ * strata plan, paint ledger, and readiness. Extracted from GGPlot for S1.
+ *
+ * Effects register at construction (#627)
+ * so relative order vs host effects is preserved.
+ */
+import { installCandidates, planStrata, registerBasic, runPipeline } from "@ggts-sh/core";
+import { untrack } from "svelte";
+// GGPlot default registration contract (#1420): basic geoms/stats +
+// interaction candidates (#1421), so identity charts and hit-testing work out
+// of the box. Temporal scale children self-register full temporal support;
+// spec-driven apps call registerAll(). Calls (not the /render side effect)
+// keep one @ggts-sh/core entry in dev-server prebundles — a /render + barrel
+// split would fork the registries.
+registerBasic();
+installCandidates();
+import { isContainerWidthProp, resolvePlotSize } from "../assembly/layout.js";
+import { createPaintLedger, isPlotReady } from "./paint.js";
+/**
+ * Create the plot runtime. Construction registers ResizeObserver, model
+ * dispose/onrender, and clientFlush effects (#627). Dep getters must not be
+ * invoked during construction for construction-time deriveds.
+ */
+export function createPlotRuntime(deps) {
+    // ------------------------------------------------- container width (RO)
+    let containerWidth = $state(null);
+    let containerHasPositiveWidth = $state(false);
+    $effect(() => {
+        // No-op cleanup keeps every code path returning a teardown (consistent-return).
+        if (!isContainerWidthProp(deps.widthProp()) || deps.root() === null)
+            return () => { };
+        const el = deps.root();
+        let frame = 0;
+        const commitWidth = (nextWidth) => {
+            // Commit readiness and the measured model width in one reactive turn so
+            // data-gg-ready does not flip true on a stale pre-measure fallback.
+            containerHasPositiveWidth = nextWidth > 0;
+            if (nextWidth > 0)
+                containerWidth = nextWidth;
+        };
+        // Synchronous first measure: do not wait a frame (or a late RO delivery)
+        // when the host already has a laid-out width.
+        const initial = Math.round(el.getBoundingClientRect().width);
+        if (initial > 0)
+            commitWidth(initial);
+        const observer = new ResizeObserver((entries) => {
+            // Debounce resize storms through rAF; the pipeline's run-id gate
+            // guarantees only the newest result commits regardless.
+            const nextWidth = Math.round(entries[0]?.contentRect.width ?? 0);
+            cancelAnimationFrame(frame);
+            frame = requestAnimationFrame(() => {
+                commitWidth(nextWidth);
+            });
+        });
+        observer.observe(el);
+        return () => {
+            cancelAnimationFrame(frame);
+            observer.disconnect();
+        };
+    });
+    const resolvedSize = $derived(resolvePlotSize({
+        width: deps.widthProp(),
+        height: deps.heightProp(),
+        containerWidth,
+        assembledWidth: deps.assembled()?.width,
+        assembledHeight: deps.assembled()?.height,
+    }));
+    const resolvedWidth = $derived(resolvedSize.width);
+    const resolvedHeight = $derived(resolvedSize.height);
+    // Authoritative committed scale state: a plain non-reactive box + run-id
+    // gate. Committing only monotonically newer runs keeps stale results from
+    // clobbering the value-stable color assignments. scaleEpoch exists so
+    // resetScales() can force a re-run after clearing the box.
+    const scaleBox = { runId: -1, scales: undefined };
+    let scaleEpoch = $state(0);
+    function resolveModel() {
+        void scaleEpoch;
+        const effectiveSpec = deps.effectiveSpec();
+        if (effectiveSpec === null)
+            return null;
+        const rowFilters = deps.effectiveLegendFilters();
+        const assembled = deps.assembled();
+        let baselineDomains;
+        let effectivePrevScales = scaleBox.scales;
+        if (deps.effectiveZoomDomains() !== null && assembled !== null) {
+            // Scale limits now censor before stats. Train the unzoomed spec in a
+            // separate pure run so Reset keeps the latest natural data/stat domain;
+            // effective zoom rendering still re-stats only the limited subset.
+            const baseline = runPipeline(assembled, {
+                width: resolvedWidth,
+                height: resolvedHeight,
+                ...(scaleBox.scales !== undefined && { prevScales: scaleBox.scales }),
+                ...(rowFilters.length > 0 && { rowFilters }),
+            });
+            baselineDomains = baseline.domains.effective;
+            effectivePrevScales = baseline.scales.state;
+            baseline.dispose();
+        }
+        const m = runPipeline(effectiveSpec, {
+            width: resolvedWidth,
+            height: resolvedHeight,
+            ...(effectivePrevScales !== undefined && { prevScales: effectivePrevScales }),
+            ...(baselineDomains !== undefined && { baselineDomains }),
+            ...(rowFilters.length > 0 && { rowFilters }),
+        });
+        if (m.runId > scaleBox.runId) {
+            scaleBox.runId = m.runId;
+            scaleBox.scales = m.scales.state;
+        }
+        return m;
+    }
+    const model = $derived.by(resolveModel);
+    // SSR: one lazy memo for the whole server pass (#1328). Recomputing on every
+    // model/strata/hasCanvas read re-ran the full pipeline ~20× per render.
+    // Client keeps $derived caching.
+    //
+    // Never latch a null model: Svelte's one-pass SSR can evaluate plot getters
+    // before declaration children register (same reason as ssrSafeDerived). An
+    // early null must not freeze a blank chart for the rest of the pass; only a
+    // non-null result is memoized. Memo is instance-local (one runtime = one
+    // SSR render) and cleared by resetScales.
+    let ssrModel;
+    let ssrStrata;
+    const currentModel = () => {
+        if (typeof window !== "undefined")
+            return model;
+        if (ssrModel !== undefined)
+            return ssrModel;
+        const next = resolveModel();
+        if (next !== null)
+            ssrModel = next;
+        return next;
+    };
+    // ---------------------------------------------------------- strata plan
+    const resolveStrata = () => {
+        const current = currentModel();
+        return current === null ? [] : planStrata(current.scene, current.layerBackends);
+    };
+    const strata = $derived(resolveStrata());
+    const currentStrata = () => {
+        if (typeof window !== "undefined")
+            return strata;
+        // Freeze strata only once the model memo is set — otherwise an early empty
+        // plan would stick after children register and model resolves.
+        if (ssrStrata !== undefined)
+            return ssrStrata;
+        const next = resolveStrata();
+        if (ssrModel !== undefined)
+            ssrStrata = next;
+        return next;
+    };
+    const canvasCount = $derived(currentStrata().filter((s) => s.backend === "canvas").length);
+    const hasCanvas = $derived(canvasCount > 0);
+    // Canvas first-paint tracking: data-gg-ready waits for every distinct
+    // canvas stratum of the CURRENT model to have painted at least once.
+    // paintEpoch bumps so readiness re-derives when the non-reactive ledger
+    // mutates (ledger itself must not be $state — set mutations are invisible).
+    const paintLedger = createPaintLedger();
+    let paintEpoch = $state(0);
+    function notifyPainted(runId, stratumKey) {
+        paintLedger.notify(runId, stratumKey);
+        paintEpoch += 1;
+    }
+    /**
+     * Clear the committed scale state (grow-mode recovery: dropped categories
+     * lose their reserved colors) and any brush zoom. The next render trains
+     * scales fresh from the current data.
+     */
+    function resetScales() {
+        scaleBox.runId = -1;
+        scaleBox.scales = undefined;
+        ssrModel = undefined;
+        ssrStrata = undefined;
+        deps.resetZoom();
+        scaleEpoch++;
+    }
+    // Readiness: clientFlush flips true on first client effect flush (SSR stays false).
+    let clientFlush = $state(false);
+    const ready = $derived.by(() => {
+        void paintEpoch;
+        if (!clientFlush)
+            return false;
+        return isPlotReady({
+            hasModel: model !== null,
+            widthMode: isContainerWidthProp(deps.widthProp()) ? "container" : "fixed",
+            containerHasPositiveWidth,
+            hasCanvas,
+            paintComplete: model !== null && paintLedger.isComplete(model.runId, canvasCount),
+        });
+    });
+    // Memory ownership: dispose the previous model once the DOM has moved on
+    // (effect cleanup runs post-flush), and the last model on unmount.
+    $effect(() => {
+        const m = model;
+        return () => m?.dispose();
+    });
+    $effect(() => {
+        const m = model;
+        const assembled = deps.assembled();
+        if (m !== null && assembled !== null)
+            untrack(() => deps.onrender()?.(m, assembled));
+    });
+    // clientFlush via $effect: never runs during SSR → prerender stays
+    // data-gg-ready="false" until the first client committed flush (decision 0009)
+    $effect(() => {
+        clientFlush = true;
+    });
+    return {
+        get model() {
+            return currentModel();
+        },
+        get resolvedWidth() {
+            return resolvedWidth;
+        },
+        get resolvedHeight() {
+            return resolvedHeight;
+        },
+        get strata() {
+            return currentStrata();
+        },
+        get hasCanvas() {
+            return typeof window === "undefined"
+                ? currentStrata().some((s) => s.backend === "canvas")
+                : hasCanvas;
+        },
+        get ready() {
+            return ready;
+        },
+        notifyPainted,
+        resetScales,
+    };
+}

package/dist/runtime/semantic-candidate-projection.svelte.d.ts

@@ -0,0 +1,29 @@
+import { type BatchInteractionMask, type CandidateFacts, type RenderModel } from "@ggts-sh/core";
+import type { PlotInteractionInterval } from "../interaction/interaction.js";
+import type { IntervalConsumptionCandidate } from "../interval/consumption.js";
+import { type PresentationAnchor, type PresentationInspectionFocus } from "../selection/selection.js";
+export type SemanticCandidateProjectionDeps = {
+    model: () => RenderModel | null;
+    candidateSemanticKeys: (candidate: CandidateFacts) => readonly PropertyKey[];
+    selectedKeys: () => readonly PropertyKey[];
+    intervalKeys: () => readonly PropertyKey[];
+    intervals: () => readonly PlotInteractionInterval<PropertyKey>[];
+    emphasisKeys: () => readonly PropertyKey[];
+    /**
+     * When true, rect inspection builds sibling-mute masks (#386 opt-in).
+     * Default off — tooltip-only hover (#633).
+     */
+    muteSiblingsOnInspect?: () => boolean;
+    inspectionFocus: () => PresentationInspectionFocus | null;
+};
+export type SemanticCandidateProjection = {
+    readonly selectedAnchors: PresentationAnchor[];
+    readonly emphasizedAnchors: PresentationAnchor[];
+    readonly interactionMasks: readonly (BatchInteractionMask | null)[];
+    readonly intervalConsumptionCandidates: readonly IntervalConsumptionCandidate<PropertyKey>[];
+};
+/**
+ * Own the one semantic walk over CandidateStore and all presentation shapes
+ * derived from it. Counts gate the walk so key-only changes reuse projection.
+ */
+export declare function createSemanticCandidateProjection(deps: SemanticCandidateProjectionDeps): SemanticCandidateProjection;

package/dist/runtime/semantic-candidate-projection.svelte.js

@@ -0,0 +1,137 @@
+import { buildInteractionMasks, buildPrimitiveInteractionMasks, } from "@ggts-sh/core";
+import { anchorsFromCandidateKeys, applyEmphasisRingDensityGate, collectCandidates, mergePresentationFocusKeys, } from "../selection/selection.js";
+/** Stable empty masks — avoid fresh `[]` identity churn on tooltip-only hover. */
+const EMPTY_INTERACTION_MASKS = Object.freeze([]);
+/** OR two mask projections per batch (focused if either side is focused). */
+function unionInteractionMasks(left, right) {
+    const length = Math.max(left.length, right.length);
+    const out = [];
+    for (let i = 0; i < length; i++) {
+        const a = left[i] ?? null;
+        const b = right[i] ?? null;
+        if (a === null) {
+            out.push(b);
+            continue;
+        }
+        if (b === null) {
+            out.push(a);
+            continue;
+        }
+        const count = Math.max(a.primitiveCount, b.primitiveCount);
+        const values = new Uint8Array(count);
+        let focusedCount = 0;
+        for (let p = 0; p < count; p++) {
+            const focused = (p < a.primitiveCount && a.isFocused(p)) || (p < b.primitiveCount && b.isFocused(p));
+            if (focused) {
+                values[p] = 1;
+                focusedCount++;
+            }
+        }
+        out.push(Object.freeze({
+            primitiveCount: count,
+            focusedCount,
+            isFocused(primitiveIndex) {
+                return values[primitiveIndex] === 1;
+            },
+        }));
+    }
+    return Object.freeze(out);
+}
+/**
+ * Own the one semantic walk over CandidateStore and all presentation shapes
+ * derived from it. Counts gate the walk so key-only changes reuse projection.
+ */
+export function createSemanticCandidateProjection(deps) {
+    const muteSiblingsOnInspect = $derived(deps.muteSiblingsOnInspect?.() === true);
+    const presentationFocusKeys = $derived(mergePresentationFocusKeys(deps.emphasisKeys(), deps.inspectionFocus(), {
+        muteSiblings: muteSiblingsOnInspect,
+    }));
+    const selectedKeyCount = $derived(deps.selectedKeys().length);
+    const emphasisKeyCount = $derived(deps.emphasisKeys().length);
+    const presentationFocusKeyCount = $derived(presentationFocusKeys.length);
+    const needIntervalConsumptionWalk = $derived(deps.intervals().length > 0 && deps.intervals()[0]?.preset !== "union");
+    // Non-union interval keys consume this projection, so do not read them until
+    // the non-union gate has been handled.
+    const intervalKeyCount = $derived(deps.intervalKeys().length);
+    const sharedCandidateProjection = $derived.by(() => {
+        if (!needIntervalConsumptionWalk &&
+            selectedKeyCount + intervalKeyCount + emphasisKeyCount + presentationFocusKeyCount === 0) {
+            return [];
+        }
+        const model = deps.model();
+        if (model === null)
+            return [];
+        return collectCandidates(model.candidates, (candidate) => {
+            const batch = model.scene.batches[candidate.batchIndex];
+            const width = batch?.kind === "glyphs" ? batch.boxWidths?.[candidate.primitiveIndex] : undefined;
+            const height = batch?.kind === "glyphs" ? batch.boxHeights?.[candidate.primitiveIndex] : undefined;
+            const textAnchor = batch?.kind === "glyphs" ? batch.anchor : undefined;
+            return {
+                x: candidate.x,
+                y: candidate.y,
+                kind: candidate.kind,
+                batchIndex: candidate.batchIndex,
+                primitiveIndex: candidate.primitiveIndex,
+                panelId: candidate.panelId,
+                keys: deps.candidateSemanticKeys(candidate),
+                ...(candidate.xValue !== undefined && { xValue: candidate.xValue }),
+                ...(candidate.yValue !== undefined && { yValue: candidate.yValue }),
+                ...(width !== undefined &&
+                    height !== undefined && {
+                    width,
+                    height,
+                    ...(textAnchor !== undefined && { textAnchor }),
+                }),
+            };
+        });
+    });
+    const intervalConsumptionCandidates = $derived.by(() => needIntervalConsumptionWalk ? sharedCandidateProjection : []);
+    // Selection: point rings stay on even for large sets (D2).
+    const selectedAnchors = $derived(anchorsFromCandidateKeys(sharedCandidateProjection, [
+        ...new Set([...deps.selectedKeys(), ...deps.intervalKeys()]),
+    ]));
+    // Legend/controller emphasis: density-gate rings so dense point series mute
+    // without a dashed-ring field; paths/rects already use chrome "none".
+    const emphasizedAnchors = $derived(applyEmphasisRingDensityGate(anchorsFromCandidateKeys(sharedCandidateProjection, deps.emphasisKeys())));
+    const interactionMasks = $derived.by(() => {
+        const model = deps.model();
+        if (model === null)
+            return EMPTY_INTERACTION_MASKS;
+        const focus = deps.inspectionFocus();
+        // Rect inspection primitives: muteSiblings opt-in, or layer under active
+        // legend/controller emphasis so the seed bar stays focused (#386 / #633).
+        const applyRectInspectionMask = muteSiblingsOnInspect || emphasisKeyCount > 0;
+        const rectPrimitives = applyRectInspectionMask &&
+            focus?.kind === "rects" &&
+            focus.primitives !== undefined &&
+            focus.primitives.length > 0
+            ? focus.primitives
+            : null;
+        let keyMasks = null;
+        if (presentationFocusKeys.length > 0) {
+            keyMasks = buildInteractionMasks(model.scene.batches, presentationFocusKeys, sharedCandidateProjection);
+        }
+        // Keyless rect inspection: layer seed primitives so legend/controller
+        // emphasis keys do not suppress the hovered bar's de-emphasis (#386).
+        if (rectPrimitives === null)
+            return keyMasks ?? EMPTY_INTERACTION_MASKS;
+        const primitiveMasks = buildPrimitiveInteractionMasks(model.scene.batches, rectPrimitives);
+        if (keyMasks === null)
+            return primitiveMasks;
+        return unionInteractionMasks(keyMasks, primitiveMasks);
+    });
+    return {
+        get selectedAnchors() {
+            return selectedAnchors;
+        },
+        get emphasizedAnchors() {
+            return emphasizedAnchors;
+        },
+        get interactionMasks() {
+            return interactionMasks;
+        },
+        get intervalConsumptionCandidates() {
+            return intervalConsumptionCandidates;
+        },
+    };
+}

package/dist/runtime/semantic-data-identity.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pure data/spec identity epoch tokens for inspection reconcile.
+ *
+ * Host-owned source identity comes from semantic-source-identity.ts (or any
+ * stable id function). No runes.
+ */
+/**
+ * O(R) order fingerprint for plot data — row *references* and length, not
+ * deep cell values. In-place reverse bumps the token; in-place cell edits on
+ * the same row objects do not (hosts should replace rows/arrays for identity).
+ *
+ * Avoids the former O(R·F) `JSON.stringify` of every cell on each epoch read.
+ */
+export declare function dataContentOrderToken(data: unknown, sourceIdentity: (value: unknown) => string): string;
+/**
+ * Input bag for {@link dataIdentityEpochToken}. Built by the host (or
+ * {@link buildDataIdentityEpochInput}) so epoch construction stays pure.
+ */
+export type DataIdentityEpochTokenInput = {
+    readonly ready: boolean;
+    readonly dataToken: string;
+    readonly specToken: string;
+    readonly data: unknown;
+    readonly datasets: unknown;
+    readonly layers?: readonly {
+        readonly data?: unknown;
+    }[];
+    readonly sourceIdentity: (value: unknown) => string;
+};
+/**
+ * Host-side assembly of {@link DataIdentityEpochTokenInput} from plot props.
+ *
+ * Pure: no runes, no assembled PortableSpec. Owns the markLayers-vs-layers-prop
+ * guard (#609), the ready-without-assembled rule, and the explicit-spec content
+ * pick (prop `data` is ignored when `spec` is an object — matches
+ * assemblePortableSpec).
+ */
+export declare function buildDataIdentityEpochInput(input: {
+    readonly data: unknown;
+    readonly spec: unknown;
+    readonly layers: readonly {
+        readonly data?: unknown;
+    }[] | undefined;
+    readonly registryMarkLayers: readonly {
+        readonly data?: unknown;
+    }[];
+    readonly sourceIdentity: (value: unknown) => string;
+}): DataIdentityEpochTokenInput;
+/**
+ * Stable data/spec identity token for inspection reconcile epochs.
+ *
+ * Host supplies:
+ * - `dataToken` / `specToken` — WeakMap identity of the raw `data` / `spec` props
+ * - `data` / `datasets` — content to order-fingerprint (prefer **prop** values,
+ *   not a freshly assembled PortableSpec shell, so theme/labs respecs do not
+ *   force a re-walk)
+ * - `layers` — optional geom-child descriptors whose `data` must also bump the
+ *   epoch when plot-level data/spec are absent (#609)
+ * - `sourceIdentity` — stable object ids for the O(R) order fingerprint
+ *
+ * Ready=false (no plot yet) → `"no-data"`. Complexity: O(R) over row refs,
+ * not O(R·F) deep cell serialization.
+ */
+export declare function dataIdentityEpochToken(input: DataIdentityEpochTokenInput): string;

package/dist/runtime/semantic-data-identity.js

@@ -0,0 +1,153 @@
+/**
+ * Pure data/spec identity epoch tokens for inspection reconcile.
+ *
+ * Host-owned source identity comes from semantic-source-identity.ts (or any
+ * stable id function). No runes.
+ */
+/**
+ * O(R) order fingerprint for a row array — length + per-row source ids.
+ * Builds via `join` (one final string) rather than `token +=` growth (#1329).
+ */
+function rowRefOrderToken(rows, sourceIdentity) {
+    if (rows.length === 0)
+        return "v:0";
+    const parts = [`v:${String(rows.length)}`];
+    for (let index = 0; index < rows.length; index++)
+        parts.push(sourceIdentity(rows[index]));
+    return parts.join(":");
+}
+/**
+ * O(R) order fingerprint for plot data — row *references* and length, not
+ * deep cell values. In-place reverse bumps the token; in-place cell edits on
+ * the same row objects do not (hosts should replace rows/arrays for identity).
+ *
+ * Avoids the former O(R·F) `JSON.stringify` of every cell on each epoch read.
+ */
+export function dataContentOrderToken(data, sourceIdentity) {
+    if (data === null || data === undefined)
+        return "null";
+    if (Array.isArray(data))
+        return rowRefOrderToken(data, sourceIdentity);
+    if (typeof data === "object")
+        return objectDataOrderToken(data, sourceIdentity);
+    if (typeof data === "string" || typeof data === "number" || typeof data === "boolean")
+        return `p:${String(data)}`;
+    if (typeof data === "bigint")
+        return `p:${data.toString()}`;
+    return `p:${sourceIdentity(data)}`;
+}
+function objectDataOrderToken(data, sourceIdentity) {
+    const record = data;
+    const fieldKeys = Object.keys(record);
+    // DataRef shapes only when single-key (matches packages/spec isDataRef).
+    // A bare column map may own a field named `values`/`columns` alongside
+    // other arrays and must not short-circuit (Codex P2).
+    if (fieldKeys.length === 1 && fieldKeys[0] === "values" && Array.isArray(record["values"])) {
+        return rowRefOrderToken(record["values"], sourceIdentity);
+    }
+    const columns = record["columns"];
+    if (fieldKeys.length === 1 &&
+        fieldKeys[0] === "columns" &&
+        columns !== null &&
+        typeof columns === "object" &&
+        !Array.isArray(columns))
+        return `c:${columnMapOrderToken(columns, sourceIdentity)}`;
+    if (fieldKeys.length === 1 && fieldKeys[0] === "name" && typeof record["name"] === "string")
+        return `n:${record["name"]}`;
+    // Bare column-oriented object (gg() wraps as { columns }) — fingerprint
+    // each field's array identity so in-place column replacement bumps epoch.
+    if (fieldKeys.length > 0 && fieldKeys.every((key) => Array.isArray(record[key])))
+        return `c:${columnMapOrderToken(record, sourceIdentity)}`;
+    return `o:${sourceIdentity(data)}`;
+}
+/** O(fields) fingerprint: each column array's identity (+ length), not cells. */
+function columnMapOrderToken(columns, sourceIdentity) {
+    const keys = Object.keys(columns).toSorted();
+    let token = `${keys.length}`;
+    for (const key of keys) {
+        const column = columns[key];
+        token += `|${key}=${sourceIdentity(column)}`;
+        if (Array.isArray(column))
+            token += `@${column.length}`;
+    }
+    return token;
+}
+function datasetsOrderToken(datasets, sourceIdentity) {
+    if (datasets === null || datasets === undefined)
+        return "null";
+    if (typeof datasets !== "object")
+        return sourceIdentity(datasets);
+    const keys = Object.keys(datasets).toSorted();
+    let token = `d:${keys.length}`;
+    for (const key of keys) {
+        token += `|${key}=${dataContentOrderToken(datasets[key], sourceIdentity)}`;
+    }
+    return token;
+}
+/**
+ * O(layers) fingerprint of geom-child / layer-local data props.
+ * Missing `layers` → `"null"` so legacy callers keep a stable suffix.
+ */
+function layersDataOrderToken(layers, sourceIdentity) {
+    if (layers === undefined)
+        return "null";
+    let token = `L:${layers.length}`;
+    for (let index = 0; index < layers.length; index++) {
+        token += `|${index}=${dataContentOrderToken(layers[index]?.data, sourceIdentity)}`;
+    }
+    return token;
+}
+/**
+ * Host-side assembly of {@link DataIdentityEpochTokenInput} from plot props.
+ *
+ * Pure: no runes, no assembled PortableSpec. Owns the markLayers-vs-layers-prop
+ * guard (#609), the ready-without-assembled rule, and the explicit-spec content
+ * pick (prop `data` is ignored when `spec` is an object — matches
+ * assemblePortableSpec).
+ */
+export function buildDataIdentityEpochInput(input) {
+    // MUST use markLayers when layers prop is absent: the widened Layer union
+    // has no `.data` at the top level, so reading registry.layers would silently
+    // drop layer-local data from the #609 epoch.
+    const layerDescriptors = input.layers === undefined
+        ? input.registryMarkLayers
+        : input.layers.map((layer) => ({ data: layer.data }));
+    const ready = input.spec !== undefined || layerDescriptors.length > 0;
+    // assemblePortableSpec: explicit `spec` wins and ignores the data prop —
+    // fingerprint the rendered source only.
+    const contentData = input.spec !== undefined && typeof input.spec === "object"
+        ? input.spec.data
+        : input.data;
+    const contentDatasets = input.spec !== undefined && typeof input.spec === "object"
+        ? input.spec.datasets
+        : undefined;
+    return {
+        ready,
+        dataToken: input.sourceIdentity(input.data),
+        specToken: input.sourceIdentity(input.spec),
+        data: contentData ?? null,
+        datasets: contentDatasets ?? null,
+        layers: layerDescriptors,
+        sourceIdentity: input.sourceIdentity,
+    };
+}
+/**
+ * Stable data/spec identity token for inspection reconcile epochs.
+ *
+ * Host supplies:
+ * - `dataToken` / `specToken` — WeakMap identity of the raw `data` / `spec` props
+ * - `data` / `datasets` — content to order-fingerprint (prefer **prop** values,
+ *   not a freshly assembled PortableSpec shell, so theme/labs respecs do not
+ *   force a re-walk)
+ * - `layers` — optional geom-child descriptors whose `data` must also bump the
+ *   epoch when plot-level data/spec are absent (#609)
+ * - `sourceIdentity` — stable object ids for the O(R) order fingerprint
+ *
+ * Ready=false (no plot yet) → `"no-data"`. Complexity: O(R) over row refs,
+ * not O(R·F) deep cell serialization.
+ */
+export function dataIdentityEpochToken(input) {
+    if (!input.ready)
+        return "no-data";
+    return `${input.dataToken}:${input.specToken}:${dataContentOrderToken(input.data, input.sourceIdentity)}:${datasetsOrderToken(input.datasets, input.sourceIdentity)}:${layersDataOrderToken(input.layers, input.sourceIdentity)}`;
+}

package/dist/runtime/semantic-keys-projection.d.ts

@@ -0,0 +1,22 @@
+export type CandidateKeysProjectionCache = {
+    /** Repeat lookup for the same candidate id. */
+    readonly byCandidate: Map<number, PropertyKey[]>;
+    /** Expanded lineage membership (rows + Set) once per lineage id. */
+    readonly lineageRows: Map<number, {
+        rows: readonly number[];
+        set: ReadonlySet<number>;
+    }>;
+    /** Key bag for a membership identity string. */
+    readonly byMembership: Map<string, PropertyKey[]>;
+};
+export declare function createCandidateKeysProjectionCache(): CandidateKeysProjectionCache;
+export type CandidateKeysMembershipRef = {
+    readonly id: number;
+    readonly lineage: number;
+    readonly rowIndex: number | null;
+};
+/**
+ * Resolve semantic keys for one candidate via the epoch cache.
+ * `lineageKeys` is invoked at most once per distinct lineage id in the cache.
+ */
+export declare function candidateSemanticKeysFromCache(candidate: CandidateKeysMembershipRef, cache: CandidateKeysProjectionCache, lineageKeys: (lineageId: number) => Iterable<number>, keyForRow: (rowIndex: number) => PropertyKey | null): PropertyKey[];

package/dist/runtime/semantic-keys-projection.js

@@ -0,0 +1,40 @@
+/**
+ * Epoch-local cache for projecting candidates into semantic key bags.
+ * Smooth eval-grid marks share one lineage of L rows across C candidates —
+ * membership is computed once per (lineage, extra-row) bag, not once per mark.
+ */
+import { uniqueKeysFromRowIndexes } from "../selection/selection.js";
+export function createCandidateKeysProjectionCache() {
+    return {
+        byCandidate: new Map(),
+        lineageRows: new Map(),
+        byMembership: new Map(),
+    };
+}
+/**
+ * Resolve semantic keys for one candidate via the epoch cache.
+ * `lineageKeys` is invoked at most once per distinct lineage id in the cache.
+ */
+export function candidateSemanticKeysFromCache(candidate, cache, lineageKeys, keyForRow) {
+    const hit = cache.byCandidate.get(candidate.id);
+    if (hit !== undefined)
+        return hit;
+    let bag = cache.lineageRows.get(candidate.lineage);
+    if (bag === undefined) {
+        const rows = [...lineageKeys(candidate.lineage)];
+        bag = { rows, set: new Set(rows) };
+        cache.lineageRows.set(candidate.lineage, bag);
+    }
+    const rowIndex = candidate.rowIndex;
+    const membershipKey = rowIndex === null || bag.set.has(rowIndex)
+        ? `L${String(candidate.lineage)}`
+        : `L${String(candidate.lineage)}+${String(rowIndex)}`;
+    let keys = cache.byMembership.get(membershipKey);
+    if (keys === undefined) {
+        const rowList = rowIndex === null || bag.set.has(rowIndex) ? bag.rows : [...bag.rows, rowIndex];
+        keys = uniqueKeysFromRowIndexes(rowList, keyForRow);
+        cache.byMembership.set(membershipKey, keys);
+    }
+    cache.byCandidate.set(candidate.id, keys);
+    return keys;
+}