@storystick/preview 0.0.0-stage → 0.2.0-rc.0

package/dist/runtime/snapshot-assembly.d.ts

@@ -0,0 +1,104 @@
+/**
+ * ADR-129 — atomic preview-snapshot assembly (pure).
+ *
+ * The atomic snapshot the Studio overlay layer consumes carries every
+ * overlay item for one render — slices + explicitly bound fields.
+ * Fields are discovered through `[data-ss-bind="<fieldId>"]` attributes
+ * on slice subtrees.
+ *
+ * Multi-SliceZone support — chantier S4 (2026-05-27).
+ *
+ * Per-render `renderId` is fresh per `<SliceZone>` call, so a page with
+ * multiple SliceZones (e.g. chrome zone with header slices + body zone
+ * with page slices ; or recursive zone-container sub-SliceZones) emits
+ * slices with N distinct renderIds. Pre-S4 this triggered a global
+ * `return null` degrade. Post-S4 :
+ *
+ *   - DOM-scan entries are grouped by `renderId` ; each group is one
+ *     zone.
+ *   - Per-zone emit (slice + explicit-binding fields) runs in DOM order.
+ *   - `pageDocId` heuristic — picks the most-frequent `model.doc` among
+ *     top-level slices (tiebreak first-in-DOM-order). This is a single-
+ *     string best-effort signal ; the wire shape stays a single `string`
+ *     (the brief carves "single is safer ; array touches the gate
+ *     contract" — wire-shape changes here would require owner
+ *     arbitration via the ADR-137 trigger path).
+ *
+ *     The Studio gate's strict `pageDocId === commandedDocId` resolves
+ *     correctly for :
+ *       (i) single-zone pages (one zone = one doc),
+ *       (ii) single-doc multi-zone (every zone shares the commanded
+ *            doc — recursive zone-containers' inner zones are skipped,
+ *            so only top-level zones count),
+ *       (iii) multi-doc multi-zone with the body zone dominant (e.g.
+ *             1 chrome slice + N body slices, N ≥ 1 — body wins on
+ *             count).
+ *
+ *     Two residual edges that the heuristic CAN'T disambiguate on a
+ *     single string without a Studio-provided hint :
+ *       (a) 1-1 tiebreak — exactly 1 chrome slice + 1 body slice with
+ *           chrome-first DOM order. Heuristic picks chrome ; strict
+ *           gate drops the snapshot ; the page paints no overlays.
+ *           Product-rare (asymmetric counts dominate).
+ *       (b) Embedded-other-doc-larger-than-host — an OLD page has 1
+ *           own slice + a top-level SliceZone surfacing 2+ slices from
+ *           the (newly commanded) doc B. Heuristic picks doc B ; gate
+ *           passes ; a stale pre-nav snapshot might paint briefly
+ *           until the iframe completes navigation. Product-bizarre
+ *           (customers rarely render another page's SliceZone at the
+ *           same level as their own).
+ *
+ *     Both edges are documented as known V1 limitations tied to a
+ *     future ADR for `pageDocId` cardinality (Studio-provided commanded
+ *     -doc hint via render-mode, OR `pageDocId: string[]` ; both are
+ *     wire-shape changes deferred to a separate chantier). Strict
+ *     equality at the gate is non-negotiable per codex S4 R2 P1 — an
+ *     epoch-fresh pre-nav snapshot can surface the commanded doc via
+ *     a chrome/linked SliceZone, so softer "any commanded-doc item"
+ *     checks at the gate admit stale snapshots that the strict check
+ *     correctly drops.
+ *   - Aggregate `renderId` is the joined `|`-separated list of every
+ *     zone's renderId (sorted DOM-order). Any zone re-render produces
+ *     a different aggregate, so downstream renderId-keyed equality
+ *     checks still see a fresh tag on any render.
+ *
+ * C4 anchored path support: new SDK models carry the rendered zone
+ * field plus ordered parent anchors, so nested zone-container slices
+ * emit visual paths such as `sections[0].sidebar[1]` while Studio
+ * navigation gets the mounted path (`sidebar[1]`). Legacy/defaulted
+ * models keep the older single-zone `sections` fallback and same-doc
+ * guard, so older SDKs degrade instead of fabricating nested paths.
+ */
+import type { SnapshotItem } from '../types.js';
+import { type PreviewOverlayRegistryDraft } from './preview-overlay-sidecar.js';
+export interface PlainRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Injected geometry source — `el.getBoundingClientRect()` in the
+ *  live reporter, a deterministic stub in unit tests. */
+export type Measure = (el: Element) => PlainRect;
+export interface AssembledSnapshot {
+    renderId: string;
+    pageDocId: string;
+    /**
+     * ADR-139 §2.1 + §5 — renamed from `visibleDocumentIds`. Iframe-side
+     * "what model islands declared this render" — debug hint only. See
+     * `MsgPreviewSnapshot.iframeDeclaredDocumentIdsDebugHint` doc-comment
+     * for the trust-boundary rationale ; the field is NEVER consulted by
+     * the Studio anti-bleed gate.
+     */
+    iframeDeclaredDocumentIdsDebugHint: string[];
+    items: SnapshotItem[];
+}
+export interface SnapshotAssemblyOptions {
+    overlayRegistry?: PreviewOverlayRegistryDraft;
+}
+/**
+ * Synchronous assemble path — Tier-1 explicit only. Pre-C2 behaviour
+ * preserved verbatim. Returns null when there is no preview seam OR
+ * when the multi-SliceZone guard fires.
+ */
+export declare function assembleSnapshot(doc: Document, measure?: Measure, scrollX?: number, scrollY?: number, options?: SnapshotAssemblyOptions): AssembledSnapshot | null;

package/dist/runtime/snapshot-assembly.js

@@ -0,0 +1,553 @@
+/**
+ * ADR-129 — atomic preview-snapshot assembly (pure).
+ *
+ * The atomic snapshot the Studio overlay layer consumes carries every
+ * overlay item for one render — slices + explicitly bound fields.
+ * Fields are discovered through `[data-ss-bind="<fieldId>"]` attributes
+ * on slice subtrees.
+ *
+ * Multi-SliceZone support — chantier S4 (2026-05-27).
+ *
+ * Per-render `renderId` is fresh per `<SliceZone>` call, so a page with
+ * multiple SliceZones (e.g. chrome zone with header slices + body zone
+ * with page slices ; or recursive zone-container sub-SliceZones) emits
+ * slices with N distinct renderIds. Pre-S4 this triggered a global
+ * `return null` degrade. Post-S4 :
+ *
+ *   - DOM-scan entries are grouped by `renderId` ; each group is one
+ *     zone.
+ *   - Per-zone emit (slice + explicit-binding fields) runs in DOM order.
+ *   - `pageDocId` heuristic — picks the most-frequent `model.doc` among
+ *     top-level slices (tiebreak first-in-DOM-order). This is a single-
+ *     string best-effort signal ; the wire shape stays a single `string`
+ *     (the brief carves "single is safer ; array touches the gate
+ *     contract" — wire-shape changes here would require owner
+ *     arbitration via the ADR-137 trigger path).
+ *
+ *     The Studio gate's strict `pageDocId === commandedDocId` resolves
+ *     correctly for :
+ *       (i) single-zone pages (one zone = one doc),
+ *       (ii) single-doc multi-zone (every zone shares the commanded
+ *            doc — recursive zone-containers' inner zones are skipped,
+ *            so only top-level zones count),
+ *       (iii) multi-doc multi-zone with the body zone dominant (e.g.
+ *             1 chrome slice + N body slices, N ≥ 1 — body wins on
+ *             count).
+ *
+ *     Two residual edges that the heuristic CAN'T disambiguate on a
+ *     single string without a Studio-provided hint :
+ *       (a) 1-1 tiebreak — exactly 1 chrome slice + 1 body slice with
+ *           chrome-first DOM order. Heuristic picks chrome ; strict
+ *           gate drops the snapshot ; the page paints no overlays.
+ *           Product-rare (asymmetric counts dominate).
+ *       (b) Embedded-other-doc-larger-than-host — an OLD page has 1
+ *           own slice + a top-level SliceZone surfacing 2+ slices from
+ *           the (newly commanded) doc B. Heuristic picks doc B ; gate
+ *           passes ; a stale pre-nav snapshot might paint briefly
+ *           until the iframe completes navigation. Product-bizarre
+ *           (customers rarely render another page's SliceZone at the
+ *           same level as their own).
+ *
+ *     Both edges are documented as known V1 limitations tied to a
+ *     future ADR for `pageDocId` cardinality (Studio-provided commanded
+ *     -doc hint via render-mode, OR `pageDocId: string[]` ; both are
+ *     wire-shape changes deferred to a separate chantier). Strict
+ *     equality at the gate is non-negotiable per codex S4 R2 P1 — an
+ *     epoch-fresh pre-nav snapshot can surface the commanded doc via
+ *     a chrome/linked SliceZone, so softer "any commanded-doc item"
+ *     checks at the gate admit stale snapshots that the strict check
+ *     correctly drops.
+ *   - Aggregate `renderId` is the joined `|`-separated list of every
+ *     zone's renderId (sorted DOM-order). Any zone re-render produces
+ *     a different aggregate, so downstream renderId-keyed equality
+ *     checks still see a fresh tag on any render.
+ *
+ * C4 anchored path support: new SDK models carry the rendered zone
+ * field plus ordered parent anchors, so nested zone-container slices
+ * emit visual paths such as `sections[0].sidebar[1]` while Studio
+ * navigation gets the mounted path (`sidebar[1]`). Legacy/defaulted
+ * models keep the older single-zone `sections` fallback and same-doc
+ * guard, so older SDKs degrade instead of fabricating nested paths.
+ */
+import { attachPreviewOverlayRegistryTarget, } from './preview-overlay-sidecar.js';
+import { readWindowedMinimapGeometry } from './windowed-minimap-projection.js';
+// ─── Wire contract (mirrors @storystick/react) ───────────────
+/** Per-slice model attribute — the serialized `SliceModel` JSON, on the
+ *  slice's own root element (ADR-129 D9 — no `<script>` node). */
+const SS_MODEL_ATTR = 'data-ss-model';
+/** Slice-root binding attribute — carries the slice `_key`. */
+const SS_SLICE_ATTR = 'data-ss-slice';
+/** Field binding attribute — carries the schema-relative field path. */
+const SS_BIND_ATTR = 'data-ss-bind';
+/** Legacy/default SliceZone field used only when the producer did not
+ *  prove a concrete zone field. */
+const LEGACY_DEFAULT_ZONE_FIELD = 'sections';
+/**
+ * Read + validate ONE slice element's `data-ss-model` attribute.
+ */
+function readSliceModel(el) {
+    const raw = el.getAttribute(SS_MODEL_ATTR);
+    if (raw === null || raw.length === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const m = parsed;
+    if (m.v !== 129 ||
+        typeof m.renderId !== 'string' ||
+        m.renderId.length === 0 ||
+        typeof m.doc !== 'string' ||
+        typeof m.i !== 'number' ||
+        typeof m.type !== 'string' ||
+        m.fields === null ||
+        typeof m.fields !== 'object' ||
+        Array.isArray(m.fields)) {
+        return null;
+    }
+    if (m.zoneField !== undefined && typeof m.zoneField !== 'string')
+        return null;
+    if (m.zoneFieldSource !== undefined &&
+        m.zoneFieldSource !== 'explicit' &&
+        m.zoneFieldSource !== 'default') {
+        return null;
+    }
+    if (m.parentAnchors !== undefined && !isPathAnchorArray(m.parentAnchors)) {
+        return null;
+    }
+    if (m.source !== undefined) {
+        if (m.source === null || typeof m.source !== 'object')
+            return null;
+        const source = m.source;
+        if (typeof source.path !== 'string' || source.path.length === 0 ||
+            !isPathAnchorArray(source.anchors) || source.anchors.length === 0 ||
+            source.anchors.at(-1)?.key !== el.getAttribute(SS_SLICE_ATTR) ||
+            m.zoneFieldSource !== 'explicit')
+            return null;
+    }
+    return parsed;
+}
+function isPathAnchorArray(value) {
+    return (Array.isArray(value) &&
+        value.every((anchor) => anchor !== null &&
+            typeof anchor === 'object' &&
+            typeof anchor.pathPrefix === 'string' &&
+            typeof anchor.key === 'string'));
+}
+function pathAnchorSignature(documentId, anchors) {
+    return `${documentId}\x01${anchors
+        .map((anchor) => `${anchor.pathPrefix}\x02${anchor.key}`)
+        .join('\x03')}`;
+}
+function anchorsEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        const a = left[index];
+        const b = right[index];
+        if (a.pathPrefix !== b.pathPrefix || a.key !== b.key)
+            return false;
+    }
+    return true;
+}
+function classifyAnchorState(model) {
+    const hasZoneField = model.zoneField !== undefined;
+    const hasSource = model.zoneFieldSource !== undefined;
+    const hasParentAnchors = model.parentAnchors !== undefined;
+    if (!hasZoneField && !hasSource && !hasParentAnchors)
+        return 'legacy';
+    if (hasZoneField && hasSource && hasParentAnchors) {
+        return model.zoneFieldSource === 'explicit' ? 'explicit' : 'default';
+    }
+    return 'partial';
+}
+function nearestSliceAncestor(el) {
+    const parent = el.parentElement;
+    if (parent === null)
+        return null;
+    try {
+        return parent.closest(`[${SS_SLICE_ATTR}]`);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Internal explicit-binding DOM scan.
+ *
+ * Deliberate invariant: this is the single Tier-1 emission path for
+ * authored `data-ss-bind` annotations. Do not add a second resolver or
+ * direct emission path beside it.
+ *
+ * Multi-SliceZone (S4) : entries are grouped by `renderId` (one zone =
+ * one renderId) ; each zone contributes its slice/field items in DOM
+ * order. `pageDocId` uses a most-frequent-doc heuristic with
+ * first-in-DOM-order tiebreak ; the aggregate `renderId` is the joined
+ * list (DOM-order, deduped, `|`-separated) so any zone's fresh re-render
+ * produces a distinct snapshot identity.
+ */
+function assembleTier1(doc, measure, scrollX, scrollY, options = {}) {
+    let sliceEls;
+    try {
+        sliceEls = doc.querySelectorAll(`[${SS_SLICE_ATTR}]`);
+    }
+    catch {
+        return null;
+    }
+    if (sliceEls.length === 0)
+        return null; // no preview seam on this page
+    // DOM-order pass — read every entry, grouping by renderId while
+    // refusing legacy/incomplete nested models before they can fabricate
+    // a visible path.
+    const zones = new Map();
+    let entryCount = 0;
+    let nestedSkipped = false;
+    for (let i = 0; i < sliceEls.length; i++) {
+        const el = sliceEls[i];
+        const key = el.getAttribute(SS_SLICE_ATTR);
+        if (key === null || key.length === 0)
+            continue;
+        const model = readSliceModel(el);
+        if (model === null)
+            continue;
+        const anchorState = classifyAnchorState(model);
+        const nested = nearestSliceAncestor(el) !== null;
+        if (anchorState === 'partial') {
+            nestedSkipped ||= nested;
+            continue;
+        }
+        if (nested && anchorState !== 'explicit') {
+            nestedSkipped = true;
+            continue;
+        }
+        const zoneField = anchorState === 'legacy' ? LEGACY_DEFAULT_ZONE_FIELD : model.zoneField;
+        const parentAnchors = anchorState === 'legacy' ? [] : model.parentAnchors;
+        entryCount++;
+        const bucket = zones.get(model.renderId);
+        const entry = {
+            el,
+            key,
+            model,
+            anchorState,
+            zoneField,
+            parentAnchors,
+            nested,
+        };
+        if (bucket === undefined)
+            zones.set(model.renderId, [entry]);
+        else
+            bucket.push(entry);
+    }
+    if (nestedSkipped)
+        warnNestedZone();
+    if (entryCount === 0)
+        return null;
+    const items = [];
+    const docIds = new Set();
+    // Count `model.doc` occurrences for the pageDocId heuristic + remember
+    // first-in-DOM-order per doc for the tiebreak. `firstOrder` indexes
+    // distinct docs by their FIRST appearance across all zones — a stable
+    // tiebreak that doesn't depend on Map iteration semantics for ties.
+    const docCounts = new Map();
+    const docFirstOrder = new Map();
+    let firstSeenIdx = 0;
+    // Source identity and visual occurrence are separate. Equal, explicitly
+    // proven sources may have several DOM roots; contradictory paths/keys still
+    // fail closed. The overlay registry assigns each root its own snapshot key.
+    const emittedPathsByDoc = new Map();
+    const emittedAnchorSignatures = new Map();
+    // Legacy/defaulted top-level namespaces keep the old same-doc guard:
+    // a second renderId on the same doc can fabricate a non-colliding
+    // `sections[i]` path unless the producer proved the real field.
+    const firstDefaultTopLevelRenderIdByDoc = new Map();
+    const emittedInfoByElement = new Map();
+    let pathCollisionSkipped = false;
+    let duplicateKeySkipped = false;
+    for (const [renderId, entries] of zones) {
+        for (const entry of entries) {
+            const { el, key, model, zoneField } = entry;
+            let slicePath;
+            let anchors;
+            let navigationPath;
+            let navigationAnchors;
+            if (model.source) {
+                slicePath = model.source.path;
+                anchors = model.source.anchors;
+                if (entry.parentAnchors.length) {
+                    navigationPath = `${zoneField}[${model.i}]`;
+                    navigationAnchors = [{ pathPrefix: zoneField, key }];
+                }
+            }
+            else if (entry.nested) {
+                const parentEl = nearestSliceAncestor(el);
+                const parentInfo = parentEl === null ? undefined : emittedInfoByElement.get(parentEl);
+                if (parentInfo === undefined ||
+                    !anchorsEqual(entry.parentAnchors, parentInfo.fromAnchors)) {
+                    pathCollisionSkipped = true;
+                    continue;
+                }
+                const currentPrefix = `${parentInfo.path}.${zoneField}`;
+                slicePath = `${currentPrefix}[${model.i}]`;
+                anchors = [...parentInfo.fromAnchors, { pathPrefix: currentPrefix, key }];
+                navigationPath = `${zoneField}[${model.i}]`;
+                navigationAnchors = [{ pathPrefix: zoneField, key }];
+            }
+            else {
+                if (entry.anchorState !== 'explicit') {
+                    const firstRenderId = firstDefaultTopLevelRenderIdByDoc.get(model.doc);
+                    if (firstRenderId !== undefined && firstRenderId !== renderId) {
+                        pathCollisionSkipped = true;
+                        continue;
+                    }
+                }
+                const currentPrefix = zoneField;
+                slicePath = `${currentPrefix}[${model.i}]`;
+                anchors = [{ pathPrefix: currentPrefix, key }];
+            }
+            const anchorSignature = pathAnchorSignature(model.doc, anchors);
+            if (emittedAnchorSignatures.has(anchorSignature) && (!model.source || emittedAnchorSignatures.get(anchorSignature) !== slicePath)) {
+                duplicateKeySkipped = true;
+                continue;
+            }
+            let emittedPaths = emittedPathsByDoc.get(model.doc);
+            if (emittedPaths === undefined) {
+                emittedPaths = new Map();
+                emittedPathsByDoc.set(model.doc, emittedPaths);
+            }
+            if (emittedPaths.has(slicePath) && (!model.source || emittedPaths.get(slicePath) !== anchorSignature)) {
+                pathCollisionSkipped = true;
+                continue;
+            }
+            emittedPaths.set(slicePath, anchorSignature);
+            emittedAnchorSignatures.set(anchorSignature, slicePath);
+            if (!entry.nested && entry.anchorState !== 'explicit') {
+                firstDefaultTopLevelRenderIdByDoc.set(model.doc, renderId);
+            }
+            docIds.add(model.doc);
+            docCounts.set(model.doc, (docCounts.get(model.doc) ?? 0) + 1);
+            if (!docFirstOrder.has(model.doc)) {
+                docFirstOrder.set(model.doc, firstSeenIdx++);
+            }
+            items.push(attachPreviewOverlayRegistryTarget({
+                kind: 'slice',
+                method: 'explicit',
+                documentId: model.doc,
+                sliceKey: key,
+                path: slicePath,
+                fromAnchors: anchors,
+                ...(navigationPath !== undefined ? { navigationPath } : {}),
+                ...(navigationAnchors !== undefined ? { navigationAnchors } : {}),
+                field: '',
+                documentRect: toDocumentRect(measure(el), scrollX, scrollY),
+                tier: { kind: 'explicit' },
+            }, el, options.overlayRegistry));
+            let bindEls;
+            try {
+                bindEls = Array.from(el.querySelectorAll(`[${SS_BIND_ATTR}]`));
+            }
+            catch {
+                bindEls = [];
+            }
+            if (el.hasAttribute(SS_BIND_ATTR))
+                bindEls.unshift(el);
+            for (let j = 0; j < bindEls.length; j++) {
+                const fieldEl = bindEls[j];
+                // Multi-SliceZone (codex S4 R1 P1#3) — `querySelectorAll` walks
+                // the FULL subtree, so a nested slice's `[data-ss-bind]` would
+                // pollute the parent scope and emit under the parent's slice path.
+                // The DOM ownership rule is "nearest `[data-ss-slice]` ancestor"
+                // — keep the binding ONLY when this slice element IS that
+                // ancestor. Skip silently otherwise (the binding belongs to the
+                // nested slice, which is itself currently skipped). The
+                // slice-root self-binding (added via `bindEls.unshift(el)`) is
+                // exempt because `el.closest('[data-ss-slice]')` matches `el`
+                // itself.
+                const owner = fieldEl.closest(`[${SS_SLICE_ATTR}]`);
+                if (owner !== el)
+                    continue;
+                const field = fieldEl.getAttribute(SS_BIND_ATTR);
+                if (field === null || field.length === 0)
+                    continue;
+                if (field.includes('[')) {
+                    warnNestedBind(field);
+                    continue;
+                }
+                items.push(attachPreviewOverlayRegistryTarget({
+                    kind: 'field',
+                    method: 'explicit',
+                    documentId: model.doc,
+                    sliceKey: key,
+                    path: `${slicePath}.${field}`,
+                    fromAnchors: anchors,
+                    ...(navigationPath !== undefined
+                        ? { navigationPath: `${navigationPath}.${field}` }
+                        : {}),
+                    ...(navigationAnchors !== undefined ? { navigationAnchors } : {}),
+                    field,
+                    documentRect: toDocumentRect(measure(fieldEl), scrollX, scrollY),
+                    tier: { kind: 'explicit' },
+                }, fieldEl, options.overlayRegistry));
+            }
+            const emittedInfo = {
+                path: slicePath,
+                fromAnchors: anchors,
+                ...(navigationPath !== undefined ? { navigationPath } : {}),
+                ...(navigationAnchors !== undefined ? { navigationAnchors } : {}),
+            };
+            emittedInfoByElement.set(el, emittedInfo);
+        }
+    }
+    if (pathCollisionSkipped)
+        warnPathCollision();
+    if (duplicateKeySkipped)
+        warnDuplicateSliceKey();
+    // pageDocId — most-frequent `model.doc` ; ties broken by first
+    // appearance in DOM order. Single-zone collapses to `firstEntry.doc`
+    // (identical to pre-S4). Multi-zone same-doc collapses identically.
+    let pageDocId = '';
+    let pageDocCount = -1;
+    let pageDocOrder = Number.POSITIVE_INFINITY;
+    for (const [doc, count] of docCounts) {
+        if (count > pageDocCount) {
+            pageDocId = doc;
+            pageDocCount = count;
+            pageDocOrder = docFirstOrder.get(doc) ?? 0;
+            continue;
+        }
+        if (count === pageDocCount) {
+            const order = docFirstOrder.get(doc) ?? 0;
+            if (order < pageDocOrder) {
+                pageDocId = doc;
+                pageDocOrder = order;
+            }
+        }
+    }
+    // Aggregate renderId — Map preserves insertion order so the zones
+    // iterate DOM-first-slice. Join with `|` ; single-zone collapses to
+    // the lone renderId (no separator), exactly preserving pre-S4 shape.
+    const renderId = [...zones.keys()].join('|');
+    return {
+        renderId,
+        pageDocId,
+        iframeDeclaredDocumentIdsDebugHint: [...docIds],
+        items,
+    };
+}
+/**
+ * Synchronous assemble path — Tier-1 explicit only. Pre-C2 behaviour
+ * preserved verbatim. Returns null when there is no preview seam OR
+ * when the multi-SliceZone guard fires.
+ */
+export function assembleSnapshot(doc, measure = liveMeasure, scrollX = 0, scrollY = 0, options = {}) {
+    const projection = readWindowedMinimapGeometry(doc);
+    if (!projection) {
+        return assembleTier1(doc, measure, scrollX, scrollY, options);
+    }
+    const inverse = 1 / projection.compression;
+    const unprojectedMeasure = (element) => {
+        const rect = measure(element);
+        return {
+            x: rect.x * inverse,
+            y: rect.y * inverse,
+            width: rect.width * inverse,
+            height: rect.height * inverse,
+        };
+    };
+    return assembleTier1(doc, unprojectedMeasure, scrollX * inverse, scrollY * inverse, options);
+}
+// ─── Helpers ─────────────────────────────────────────────────
+let warnedNestedZone = false;
+/**
+ * Warn (once) that the previewed page contains a nested SliceZone
+ * emitted by a legacy/defaulted producer.
+ *
+ * C4 accepts nested zone-container slices only when the producer proves
+ * the zone field and parent anchor chain. Older payloads are degraded
+ * because their numeric index cannot be placed safely in the mounted
+ * Studio path.
+ */
+function warnNestedZone() {
+    if (warnedNestedZone)
+        return;
+    warnedNestedZone = true;
+    try {
+        console.warn(`[storystick] ADR-129 v1 supports TOP-LEVEL <SliceZone> instances ; ` +
+            `legacy/defaulted nested zone-container <SliceZone>s are degraded ` +
+            `(no overlay). Upgrade @storystick/react to emit anchored zone metadata.`);
+    }
+    catch {
+        // `console` absent — the warning is best-effort.
+    }
+}
+let warnedPathCollision = false;
+/**
+ * Warn (once) that two SliceZones produced the same visual slice path
+ * on the SAME doc. The first safe path wins; the duplicate degrades
+ * rather than overwriting snapshot identity.
+ */
+function warnPathCollision() {
+    if (warnedPathCollision)
+        return;
+    warnedPathCollision = true;
+    try {
+        console.warn(`[storystick] Two <SliceZone>s referencing the SAME document collided ` +
+            `on at least one slice path — the first path wins and the duplicate ` +
+            `is degraded (no overlay).`);
+    }
+    catch {
+        // best-effort
+    }
+}
+let warnedDuplicateSliceKey = false;
+/**
+ * Warn (once) that two SliceZone slices share the same full anchor
+ * signature for one document.
+ *
+ * `_key`s are sibling-unique per ADR-051. C4's route lookup uses the
+ * full keyed-hop chain when it is present; an exact duplicate chain is
+ * still ambiguous and degrades.
+ */
+function warnDuplicateSliceKey() {
+    if (warnedDuplicateSliceKey)
+        return;
+    warnedDuplicateSliceKey = true;
+    try {
+        console.warn(`[storystick] Two <SliceZone> slices share the same full anchor ` +
+            `signature for one document — the duplicate is degraded (no overlay).`);
+    }
+    catch {
+        // best-effort
+    }
+}
+let warnedNestedBind = false;
+function warnNestedBind(field) {
+    if (warnedNestedBind)
+        return;
+    warnedNestedBind = true;
+    try {
+        console.warn(`[storystick] ADR-129 v1 binds simple field paths; the binding ` +
+            `"${field}" uses array syntax. Repeater / nested-array bindings ` +
+            `need the \`fieldPath\` helper + per-row \`_key\` anchors — a ` +
+            `tracked follow-up. No overlay is shown for it.`);
+    }
+    catch {
+        // best-effort
+    }
+}
+function liveMeasure(el) {
+    const r = el.getBoundingClientRect();
+    return { x: r.x, y: r.y, width: r.width, height: r.height };
+}
+function toDocumentRect(r, scrollX, scrollY) {
+    return {
+        x: r.x + scrollX,
+        y: r.y + scrollY,
+        width: r.width,
+        height: r.height,
+    };
+}