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

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

@@ -0,0 +1,55 @@
+/**
+ * ADR-129 — in-iframe atomic-snapshot reporter.
+ *
+ * Runs inside the customer site iframe when embedded by the Studio.
+ * Supersedes the retired section/field-bounds publish: it observes
+ * layout, re-assembles ONE atomic
+ * `MsgPreviewSnapshot` (see `snapshot-assembly`), and posts it to the
+ * Studio. The Studio renders the overlay layer + owns hover/click —
+ * this runtime only observes geometry and reports.
+ *
+ * Observer triptyque (ADR-059 / ADR-112 pattern): ResizeObserver +
+ * MutationObserver + `document.fonts.ready`, all funnelled into ONE
+ * rAF-coalesced `publish()` — never a per-frame storm.
+ */
+import { type MsgPreviewSnapshot } from '../types.js';
+import { type PreviewObservationReason } from './observation-scheduler.js';
+export interface SnapshotReporterOptions {
+    /** Document observed. Defaults to `window.document`. Injectable for tests. */
+    doc?: Document;
+    /** Window for `parent` / listeners. Defaults to `window`. Injectable for tests. */
+    win?: Window;
+    /** rAF override — tests pass a deterministic scheduler. */
+    raf?: (cb: () => void) => number;
+    /** cancelAnimationFrame override. */
+    caf?: (handle: number) => void;
+    /**
+     * Route hash emitted with the snapshot so Studio can keep document
+     * observations scoped to the current customer route.
+     */
+    routeHashRef?: () => string | null;
+    /**
+     * Live customer URL rendered by the iframe. This is emitted so Studio
+     * can scope document observations against the post-redirect route,
+     * not against the preview bootstrap endpoint stored in the iframe
+     * element's `src` attribute.
+     */
+    routeUrlRef?: () => string | null;
+    /** Observe the assembled wire snapshot locally (for standalone adapters). */
+    onSnapshot?: (snapshot: MsgPreviewSnapshot) => void;
+    /** Post snapshots/readiness to `window.parent`. Defaults to true. */
+    postToParent?: boolean;
+}
+export interface SnapshotReporterHandle {
+    /** Tear down observers + listener. */
+    stop(): void;
+    /** Force a flush — returns the snapshot posted (or `null` when there
+     *  is no preview seam on the page). */
+    flush(): MsgPreviewSnapshot | null;
+    /**
+     * Request the reporter to publish on the next rAF tick. Idempotent:
+     * if a publish is already pending, this is a no-op.
+     */
+    kick(reason?: PreviewObservationReason): void;
+}
+export declare function startSnapshotReporter(options?: SnapshotReporterOptions): SnapshotReporterHandle;

package/dist/runtime/snapshot-reporter.js

@@ -0,0 +1,375 @@
+/**
+ * ADR-129 — in-iframe atomic-snapshot reporter.
+ *
+ * Runs inside the customer site iframe when embedded by the Studio.
+ * Supersedes the retired section/field-bounds publish: it observes
+ * layout, re-assembles ONE atomic
+ * `MsgPreviewSnapshot` (see `snapshot-assembly`), and posts it to the
+ * Studio. The Studio renders the overlay layer + owns hover/click —
+ * this runtime only observes geometry and reports.
+ *
+ * Observer triptyque (ADR-059 / ADR-112 pattern): ResizeObserver +
+ * MutationObserver + `document.fonts.ready`, all funnelled into ONE
+ * rAF-coalesced `publish()` — never a per-frame storm.
+ */
+import { isStudioToIframe } from '../types.js';
+import { setRenderMode } from './render-mode-state.js';
+import { assembleSnapshot } from './snapshot-assembly.js';
+import { clearPreviewOverlayRegistry, commitPreviewOverlayRegistryDraft, createPreviewOverlayRegistryDraft, } from './preview-overlay-sidecar.js';
+import { estimatePreviewPayloadBytes, previewPerfNow, recordPreviewPerfMeasure, recordPreviewPerfMetric, } from './perf-metrics.js';
+import { createPreviewObservationScheduler, } from './observation-scheduler.js';
+const SS_SLICE_SELECTOR = '[data-ss-slice]';
+const SS_PREVIEW_SYNTHETIC_OVERLAY_SELECTOR = '[data-ss-preview-field-synthetic-overlay-root],[data-ss-preview-field-synthetic-overlay-box]';
+export function startSnapshotReporter(options = {}) {
+    const win = options.win ?? window;
+    const doc = options.doc ?? win.document;
+    const raf = options.raf ??
+        (typeof win.requestAnimationFrame === 'function'
+            ? win.requestAnimationFrame.bind(win)
+            : (cb) => win.setTimeout(cb, 16));
+    const caf = options.caf ??
+        (typeof win.cancelAnimationFrame === 'function'
+            ? win.cancelAnimationFrame.bind(win)
+            : (h) => win.clearTimeout(h));
+    // The controller generation last sent via `render-mode` (ADR-119 D1).
+    // Echoed on every snapshot so the Studio's anti-bleed gate can
+    // discard stale cross-doc/mode reports. `0` until the first
+    // `render-mode` — boot snapshots are pre-contract.
+    let currentEpoch = 0;
+    function publish() {
+        reconcileResizeObserver();
+        const liveRouteHash = options.routeHashRef?.() ?? null;
+        const liveRouteUrl = options.routeUrlRef?.() ?? null;
+        // Overlay-map paint tuples still carry their own protocol member.
+        // Snapshot cache state is retired; the living painter starts at zero.
+        const overlayMapCacheVersion = 0;
+        const overlayRegistry = createPreviewOverlayRegistryDraft();
+        let assembled = null;
+        let failed = false;
+        const startedAt = previewPerfNow(win);
+        try {
+            assembled = assembleSnapshot(doc, undefined, win.scrollX, win.scrollY, {
+                overlayRegistry,
+            });
+        }
+        catch {
+            // Hostile / mid-mutation DOM — never let the reporter throw.
+            failed = true;
+            assembled = null;
+        }
+        recordPreviewPerfMeasure(win, 'snapshot.assemble.sync', startedAt, {
+            failed,
+            itemCount: assembled?.items.length ?? 0,
+        });
+        commitPreviewOverlayRegistryDraft(overlayRegistry, {
+            renderId: assembled?.renderId ?? '',
+            routeHash: liveRouteHash,
+            codeVersion: readCodeVersionFromWindow(win),
+            cacheVersion: overlayMapCacheVersion,
+        });
+        return emit(assembled, liveRouteHash, liveRouteUrl);
+    }
+    function emit(assembled, 
+    /**
+     * The routeHash captured at the start of assembly.
+     */
+    liveRouteHash, 
+    /**
+     * The routeUrl sampled with the routeHash. It is not part of the
+     * anti-bleed key, but Studio needs the concrete URL to avoid using
+     * the iframe bootstrap URL as the route observation key.
+     */
+    liveRouteUrl) {
+        //   - `codeVersion` (upstream build/schema/config signature per
+        //     §D7.1a; resolved once at boot from `window.__STORYSTICK_CODE_VERSION__`
+        //     OR `''` when absent — the Studio controller treats `''` as
+        //     "indeterminate" and skips redeploy-drift detection).
+        //   - `timestamp` (Date.now() at the producing rAF tick; feeds the
+        //     §D3.2 adaptive correlation window EMA).
+        // No island ⇒ no preview seam on this page. Still post an EMPTY
+        // snapshot so the Studio clears any overlays from a prior render
+        // (anti-bleed on client-nav to a non-SliceZone page).
+        // ADR-131 amendment-003 + ADR-139 §5.5 — share the live routeHash
+        // (passed in from the caller, captured at assembly time so the
+        // (items, routeHash) pair stays consistent across iframe URL
+        // changes during assembly. Optional on the wire; absent while the
+        // route hash is unavailable.
+        const msg = {
+            type: 'storystick.preview.snapshot',
+            epoch: currentEpoch,
+            renderId: assembled?.renderId ?? '',
+            pageDocId: assembled?.pageDocId ?? '',
+            capabilities: {
+                crossDocumentOverlayLabels: true,
+            },
+            // ADR-139 §2.1 + §5 wire-level rename.
+            iframeDeclaredDocumentIdsDebugHint: assembled?.iframeDeclaredDocumentIdsDebugHint ?? [],
+            items: assembled?.items ?? [],
+            codeVersion: readCodeVersionFromWindow(win),
+            timestamp: Date.now(),
+            ...(liveRouteHash !== null && liveRouteHash !== ''
+                ? { routeHash: liveRouteHash }
+                : {}),
+            ...(liveRouteUrl !== null && liveRouteUrl !== ''
+                ? { routeUrl: liveRouteUrl }
+                : {}),
+        };
+        const payloadBytes = estimatePreviewPayloadBytes(win, msg);
+        recordPreviewPerfMetric(win, {
+            name: 'snapshot.emit',
+            detail: {
+                itemCount: msg.items.length,
+                payloadBytes,
+                empty: assembled === null,
+                hasRouteHash: liveRouteHash !== null && liveRouteHash !== '',
+                hasRouteUrl: liveRouteUrl !== null && liveRouteUrl !== '',
+            },
+        });
+        options.onSnapshot?.(msg);
+        if (options.postToParent !== false) {
+            // Parent is the Studio; '*' is acceptable — UI geometry only, no
+            // secrets, and the Studio bridge filters by source + origin.
+            win.parent.postMessage(msg, '*');
+        }
+        return assembled === null ? null : msg;
+    }
+    function readCodeVersionFromWindow(w) {
+        const raw = w
+            .__STORYSTICK_CODE_VERSION__;
+        return typeof raw === 'string' && raw.length > 0 ? raw : '';
+    }
+    let stopped = false;
+    let hostResizeActive = false;
+    let hostResizeDirty = false;
+    let visibilityDirty = false;
+    function flushScheduledSnapshot() {
+        if (doc.visibilityState === 'hidden') {
+            visibilityDirty = true;
+            return;
+        }
+        publish();
+    }
+    const scheduler = createPreviewObservationScheduler({
+        raf,
+        caf,
+        onFlush: flushScheduledSnapshot,
+        onEnqueue: () => {
+            recordPreviewPerfMetric(win, {
+                name: 'snapshot.schedule.enqueue',
+            });
+        },
+        onSkipPending: () => {
+            recordPreviewPerfMetric(win, {
+                name: 'snapshot.schedule.skipPending',
+            });
+        },
+    });
+    function schedule(reason = 'kick') {
+        if (stopped)
+            return;
+        if (doc.visibilityState === 'hidden') {
+            visibilityDirty = true;
+            return;
+        }
+        if (hostResizeActive && isHostResizeDeferredReason(reason)) {
+            markHostResizeDirty(reason);
+            return;
+        }
+        scheduler.request(reason);
+    }
+    function isHostResizeDeferredReason(reason) {
+        return reason === 'resize' || reason === 'mutation';
+    }
+    function markHostResizeDirty(reason) {
+        hostResizeDirty = true;
+        recordPreviewPerfMetric(win, {
+            name: 'snapshot.schedule.deferHostResize',
+            detail: { reason },
+        });
+    }
+    // ─── ResizeObserver — per slice root (primary geometry signal) ─
+    const ro = typeof ResizeObserver !== 'undefined'
+        ? new ResizeObserver(() => schedule('resize'))
+        : null;
+    const observedResizeTargets = new Set();
+    let resizeTargetsDirty = true;
+    function reconcileResizeObserver() {
+        if (!ro || !resizeTargetsDirty)
+            return;
+        resizeTargetsDirty = false;
+        const targets = new Set(doc.querySelectorAll(SS_SLICE_SELECTOR));
+        // Also observe documentElement so a whole-page reflow is caught
+        // even before any slice element resizes.
+        if (doc.documentElement)
+            targets.add(doc.documentElement);
+        for (const target of observedResizeTargets) {
+            if (targets.has(target))
+                continue;
+            ro.unobserve(target);
+            observedResizeTargets.delete(target);
+        }
+        for (const target of targets) {
+            if (observedResizeTargets.has(target))
+                continue;
+            ro.observe(target);
+            observedResizeTargets.add(target);
+        }
+    }
+    function isSyntheticOverlayNode(node) {
+        if (node instanceof Element) {
+            return node.closest(SS_PREVIEW_SYNTHETIC_OVERLAY_SELECTOR) !== null;
+        }
+        const parent = node.parentNode;
+        return (parent instanceof Element &&
+            parent.closest(SS_PREVIEW_SYNTHETIC_OVERLAY_SELECTOR) !== null);
+    }
+    function isSyntheticOverlayOnlyMutation(record) {
+        if (isSyntheticOverlayNode(record.target))
+            return true;
+        if (record.type !== 'childList')
+            return false;
+        const changedNodes = [...record.addedNodes, ...record.removedNodes];
+        return (changedNodes.length > 0 &&
+            changedNodes.every((node) => isSyntheticOverlayNode(node)));
+    }
+    // ─── MutationObserver — structural change (slices appear/move) ─
+    const mo = new MutationObserver((records) => {
+        if (records.every(isSyntheticOverlayOnlyMutation))
+            return;
+        if (records.some((record) => !isSyntheticOverlayOnlyMutation(record) &&
+            (record.type === 'childList' || record.attributeName === 'data-ss-slice')))
+            resizeTargetsDirty = true;
+        if (hostResizeActive) {
+            markHostResizeDirty('mutation');
+            return;
+        }
+        schedule('mutation');
+    });
+    mo.observe(doc.documentElement, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        // `characterData` — a field's text changing without an element
+        // add/remove or attribute change (the common case: an RSC re-render
+        // edits a text node in place) is a pure characterData mutation.
+        // Without this explicit field geometry could stay stale.
+        // rAF-coalesced like every other signal — no storm.
+        characterData: true,
+        // `data-ss-slice` / `data-ss-bind` / `data-ss-model` — a binding or
+        // a slice model toggled/changed without a coincident subtree change
+        // still re-publishes. (`data-ss-model` changes on every customer
+        // re-render — its `renderId` is fresh — so this also guarantees a
+        // re-render always republishes.)
+        attributeFilter: [
+            'style',
+            'class',
+            'hidden',
+            'data-ss-slice',
+            'data-ss-bind',
+            'data-ss-model',
+        ],
+    });
+    // ─── document.fonts.ready — one-shot, font-swap reflow ────────
+    const fontsLike = doc.fonts;
+    if (fontsLike && typeof fontsLike.ready?.then === 'function') {
+        void fontsLike.ready.then(() => schedule('fonts-ready'));
+    }
+    // ─── Studio → iframe message handler ─────────────────────────
+    function onMessage(event) {
+        if (event.source !== win.parent)
+            return;
+        if (!isStudioToIframe(event.data))
+            return;
+        const msg = event.data;
+        switch (msg.type) {
+            case 'render-mode': {
+                doc.body?.setAttribute('data-render-mode', msg.mode);
+                setRenderMode(msg.mode);
+                // ADR-119 D1 — capture the controller generation; a real bump
+                // means a cross-doc / mode change, so the next snapshot must
+                // carry it. Re-publish promptly so the Studio's gate recovers
+                // without waiting for an observer.
+                currentEpoch = msg.epoch ?? currentEpoch;
+                schedule('render-mode');
+                return;
+            }
+            case 'overlay-mode':
+                doc.body?.setAttribute('data-overlay-mode', msg.mode);
+                return;
+            case 'device-width':
+                doc.body?.setAttribute('data-device-width', String(msg.width));
+                return;
+            case 'storystick.preview.host-resize':
+                hostResizeActive = msg.active;
+                if (msg.active) {
+                    hostResizeDirty = false;
+                    return;
+                }
+                if (hostResizeDirty) {
+                    hostResizeDirty = false;
+                    schedule('resize');
+                }
+                return;
+            case 'storystick.preview.windowed-minimap':
+                schedule('kick');
+                return;
+            case 'highlight':
+            case 'scroll':
+                // ADR-129 — highlight + scroll-into-view are Studio-overlay
+                // concerns now (the parent-rendered overlay IS the highlight).
+                // The iframe-side handlers are retired; the cases stay so the
+                // `StudioToIframe` switch remains exhaustive.
+                return;
+            default: {
+                const _exhaustive = msg;
+                void _exhaustive;
+                return;
+            }
+        }
+    }
+    win.addEventListener('message', onMessage);
+    function onVisibilityChange() {
+        if (doc.visibilityState === 'hidden') {
+            // Preserve one catch-up even if a scheduled frame was cancelled.
+            visibilityDirty = true;
+            scheduler.cancel();
+            ro?.disconnect();
+            observedResizeTargets.clear();
+            resizeTargetsDirty = true;
+        }
+        else if (visibilityDirty) {
+            visibilityDirty = false;
+            schedule('kick');
+        }
+    }
+    doc.addEventListener('visibilitychange', onVisibilityChange);
+    // Initial publish + readiness signal.
+    schedule('initial');
+    if (options.postToParent !== false) {
+        const ready = { type: 'ready' };
+        win.parent.postMessage(ready, '*');
+    }
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            scheduler.cancel();
+            mo.disconnect();
+            ro?.disconnect();
+            observedResizeTargets.clear();
+            clearPreviewOverlayRegistry();
+            win.removeEventListener('message', onMessage);
+            doc.removeEventListener('visibilitychange', onVisibilityChange);
+        },
+        flush() {
+            if (stopped)
+                return null;
+            scheduler.cancel();
+            return publish();
+        },
+        kick(reason = 'kick') {
+            schedule(reason);
+        },
+    };
+}

package/dist/runtime/standalone-overlay-controller.d.ts

@@ -0,0 +1,33 @@
+import type { PreviewV2RevealSourceRequest, PreviewV2RevealSliceRequest } from '../provenance/reveal-contract.js';
+import type { PreviewOverlayClickPayload } from '@storystick/transport-allowlist';
+import { type PreviewOverlayClickTarget, type PreviewProvenanceOverlayProjection, type ProvenanceOwnerRejection } from '../provenance/index.js';
+export type StandaloneOverlayMode = 'browse' | 'edit';
+export interface StandaloneOverlaySnapshot {
+    readonly mode: StandaloneOverlayMode;
+    readonly available: boolean;
+    readonly generation: number | null;
+    readonly rejections: readonly ProvenanceOwnerRejection[];
+}
+export declare function readStandaloneOverlaySnapshot(win?: Window): StandaloneOverlaySnapshot;
+export declare function subscribeStandaloneOverlaySnapshot(listener: () => void, win?: Window): () => void;
+export declare function subscribeStandaloneOverlayIntent(listener: (target: PreviewOverlayClickTarget) => void, win?: Window): () => void;
+export declare function setStandaloneOverlayMode(mode: StandaloneOverlayMode, win?: Window): void;
+/** Paint and route the same validated projection used by Studio. The active
+ * projection is re-read on every click; a stale generation cannot become an
+ * edit intent. */
+export declare function startStandaloneOverlayController(args: {
+    readonly sessionId: string;
+    readonly win?: Window;
+}): () => void;
+/** The click identity and its owner are resolved from one current projection.
+ * A host never receives an intent from stale paint or browse mode. */
+export declare function resolveStandaloneOverlayIntent(args: {
+    readonly mode: StandaloneOverlayMode;
+    readonly projection: PreviewProvenanceOverlayProjection | null;
+    readonly click: PreviewOverlayClickPayload;
+}): PreviewOverlayClickTarget | null;
+/** The same provenance resolver and painter as Studio, transported locally. */
+export declare function revealStandaloneSource(request: PreviewV2RevealSourceRequest, win?: Window): boolean;
+export declare function revealStandaloneSlice(request: PreviewV2RevealSliceRequest, win?: Window): boolean;
+/** Admission/render transitions suspend interaction without changing the user's mode. */
+export declare function setStandaloneOverlaySuspended(suspended: boolean, win?: Window): void;