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

package/dist/runtime/form-contract-reporter.js

@@ -0,0 +1,391 @@
+/**
+ * In-iframe SDK runtime — Form-preview viewport-contract reporter
+ * (ADR-119 D2/D3/D6).
+ *
+ * Form preview (render-mode `'navigation'`) is a live, SDK-cooperative
+ * editorial mini-map. This runtime is the SDK half of the ADR-119
+ * contract; the Studio half is the disciplined controller in
+ * `apps/studio/.../preview-surface.tsx`.
+ *
+ *   1. On `render-mode: 'navigation'` it sets
+ *      `data-storystick-form-preview` on the customer document's
+ *      `<html>`. The migrated starter routes viewport-relative
+ *      primitives (`body { min-height: var(--ss-screen-h, 100dvh) }`,
+ *      `min-h-dvh`/`h-screen` utilities, full-screen sections) through
+ *      `--ss-screen-h`, which `html[data-storystick-form-preview]`
+ *      pins to 800px. This neutralises the EXP-3 cross-doc viewport
+ *      ratchet **at the source**: the customer's own primitives
+ *      resolve to a real 800, never the tall measuring iframe.
+ *
+ *   2. It measures `documentElement.scrollHeight` **under the applied
+ *      contract** and reports it to the Studio parent as
+ *      `{type:'storystick.preview.form-contract', epoch, applied:true,
+ *      pageHeight, viewportHeight}`. The FIRST report after an `epoch`
+ *      change is the
+ *      controller's hard ACK gate (ADR-119 D3 — "NEVER take the first
+ *      measurement without a confirmed ack"). Subsequent same-`epoch`
+ *      reports (layout-observer driven) feed the controller's
+ *      debounced in-doc resize cadence.
+ *
+ *   3. On `render-mode: 'device'` it removes the attribute and reports
+ *      `{applied:false, pageHeight:0}`. Device is strict browser truth
+ *      (1280×800), never virtualised.
+ *
+ * `epoch` is the Studio controller's instance-scoped generation
+ * counter (ADR-119 D1), carried on `MsgRenderMode` and echoed back
+ * verbatim on every report so the controller can discard stale
+ * cross-doc async measurements soundly (the ratchet-class guard).
+ *
+ * Principle (ADR-119 D6 / no-customer-DOM-interference, relaxed for
+ * Form only, contractualised): the ONLY customer-DOM write is the
+ * single `data-storystick-form-preview` attribute on `<html>`, set by
+ * the SDK the customer already embeds — NOT Studio reaching across
+ * origins, NOT CSS injection (the retracted ADR-102/112 §D4 path).
+ * Reads are limited to `documentElement.scrollHeight` and the iframe's own
+ * `window.innerHeight`. No content mutation, no DOM-tree inspection. A site not using the starter
+ * primitives simply gets an honest, slightly-less-faithful overview;
+ * Device stays exact.
+ */
+import { isStudioToIframe, } from '../types.js';
+import { createPreviewObservationScheduler, } from './observation-scheduler.js';
+import { createWindowedMinimapProjection } from './windowed-minimap-projection.js';
+export const FORM_PREVIEW_ATTR = 'data-storystick-form-preview';
+/**
+ * Conceptual viewport for customer JS that needs the Form-preview
+ * height (ADR-119 D5 — explicit helper, NOT a global `window.
+ * innerHeight` shim). When the contract is active the computed
+ * `--ss-screen-h` resolves to `800px` and that is returned as the
+ * height; otherwise the real `innerHeight` (Device / no contract /
+ * non-starter site). Width is always the real `innerWidth` (Form does
+ * not virtualise width — the iframe is a true 1280 logical box).
+ */
+export function getStorystickViewport(win = typeof window === 'undefined'
+    ? undefined
+    : window) {
+    if (!win || typeof win.innerWidth !== 'number') {
+        return { width: 0, height: 0 };
+    }
+    const width = win.innerWidth;
+    const root = win.document?.documentElement;
+    if (root && typeof win.getComputedStyle === 'function') {
+        const raw = win
+            .getComputedStyle(root)
+            .getPropertyValue('--ss-screen-h')
+            .trim();
+        if (raw) {
+            const n = Number.parseFloat(raw);
+            if (Number.isFinite(n) && n > 0)
+                return { width, height: n };
+        }
+    }
+    return { width, height: win.innerHeight };
+}
+export function startFormContractReporter(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));
+    let mode = 'device';
+    let epoch = 0;
+    // ADR-119 §D5-B change #4 — the epoch a pending settle-rAF will
+    // publish under. Without this, `epoch` is a mutable module var read
+    // at rAF FIRE time: if a render-mode bumps `epoch` (D5-B's
+    // `confirmNav` fresh-epoch re-begin) while an OLD-epoch rAF is
+    // pending, that stale measurement would publish under the NEW
+    // epoch → the Studio D1 generation guard could not discard it →
+    // raw-CSS cross-doc ratchet. Stamping the pending measurement with
+    // the epoch it was scheduled for (and re-arming on an epoch change)
+    // makes a pre-confirm measurement publish under its OWN old epoch
+    // → D1-discarded; the new epoch gets its own post-confirm rAF.
+    // The shared observation scheduler owns the rAF handle; this reporter
+    // still owns the epoch stamp because it is part of the form-contract
+    // protocol, not generic DOM observation.
+    let pendingEpoch = null;
+    let last = null;
+    let stopped = false;
+    const windowedProjection = createWindowedMinimapProjection(win, doc);
+    let windowedProjectionRequested = false;
+    let configuredProjectionEpoch = null;
+    function setContract(on) {
+        const root = doc.documentElement;
+        if (!root)
+            return;
+        if (on)
+            root.setAttribute(FORM_PREVIEW_ATTR, '');
+        else
+            root.removeAttribute(FORM_PREVIEW_ATTR);
+    }
+    function publish(applied, epochArg = epoch) {
+        // Reading `scrollHeight` forces a synchronous reflow that accounts
+        // for the just-applied `data-storystick-form-preview` attribute
+        // (hence `--ss-screen-h:800px` → the starter's `body min-height`
+        // pins to a real 800; tall content overflows the measuring iframe
+        // so `scrollHeight` is the true content extent, never the inherited
+        // tall-iframe height — the EXP-4 invariant).
+        const projectedGeometry = windowedProjection.geometry;
+        const pageHeight = applied
+            ? projectedGeometry?.pageHeight ??
+                Math.max(0, doc.documentElement?.scrollHeight ?? 0)
+            : 0;
+        const viewportHeight = applied
+            ? Math.max(0, Number.isFinite(win.innerHeight) ? win.innerHeight : 0)
+            : 0;
+        const report = {
+            epoch: epochArg,
+            applied,
+            pageHeight,
+            viewportHeight,
+            ...(windowedProjectionRequested
+                ? {
+                    windowedProjection: windowedProjection.active
+                        ? configuredProjectionEpoch === epochArg
+                            ? 'active'
+                            : 'pending'
+                        : 'unsupported',
+                    ...(!windowedProjection.active && windowedProjection.stoppedReason
+                        ? {
+                            windowedProjectionReason: windowedProjection.stoppedReason,
+                        }
+                        : {}),
+                    ...(projectedGeometry
+                        ? {
+                            windowStart: projectedGeometry.windowStart,
+                            renderSpan: projectedGeometry.renderSpan,
+                            compression: projectedGeometry.compression,
+                        }
+                        : {}),
+                }
+                : {}),
+        };
+        last = report;
+        const msg = {
+            type: 'storystick.preview.form-contract',
+            epoch: epochArg,
+            applied,
+            pageHeight,
+            viewportHeight,
+            ...(report.windowedProjection
+                ? {
+                    windowedProjection: report.windowedProjection,
+                    ...(report.windowedProjectionReason
+                        ? { windowedProjectionReason: report.windowedProjectionReason }
+                        : {}),
+                    ...(report.windowStart !== undefined
+                        ? { windowStart: report.windowStart }
+                        : {}),
+                    ...(report.renderSpan !== undefined
+                        ? { renderSpan: report.renderSpan }
+                        : {}),
+                    ...(report.compression !== undefined
+                        ? { compression: report.compression }
+                        : {}),
+                }
+                : {}),
+        };
+        // `'*'` mirrors section/snapshot reporters: the payload is UI
+        // geometry, no secrets; Studio's bridge filters by source + origin.
+        win.parent.postMessage(msg, '*');
+        return report;
+    }
+    /**
+     * rAF-coalesced settle-then-publish. One frame lets the just-set
+     * attribute's style/layout flush before we read `scrollHeight`; the
+     * observers below catch the long tail (font swap, image decode).
+     * Only meaningful while in Form (navigation) mode.
+     */
+    const scheduler = createPreviewObservationScheduler({
+        raf,
+        caf,
+        onFlush: () => {
+            const forEpoch = pendingEpoch ?? epoch;
+            pendingEpoch = null;
+            if (mode !== 'navigation')
+                return;
+            if (windowedProjectionRequested)
+                windowedProjection.refresh();
+            // Publish under the epoch this measurement was SCHEDULED for —
+            // never the (possibly newer) live `epoch`.
+            publish(true, forEpoch);
+        },
+    });
+    function schedule(reason = 'form-contract') {
+        if (stopped)
+            return;
+        if (scheduler.isPending()) {
+            // A rAF for the SAME epoch is already pending → coalesce.
+            if (pendingEpoch === epoch)
+                return;
+            // A new render-mode bumped `epoch` while an OLD-epoch rAF is
+            // still pending (D5-B `confirmNav` re-begin) → drop the stale
+            // one and re-arm for the new epoch, so the OLD measurement can
+            // never publish under the NEW epoch.
+            scheduler.cancel();
+            pendingEpoch = null;
+        }
+        const forEpoch = epoch;
+        pendingEpoch = forEpoch;
+        scheduler.request(reason);
+    }
+    // Layout observers — fire while the contract is active so in-doc
+    // content changes (autosave re-render, contentRevision) re-report
+    // the new page height. The Studio controller owns the debounce +
+    // no-reset cadence (ADR-119 D3 cadence note); the SDK just keeps the
+    // feed honest. ResizeObserver on documentElement catches the bulk;
+    // a filtered MutationObserver catches structural swaps that don't
+    // change the root box synchronously.
+    const ro = typeof ResizeObserver !== 'undefined'
+        ? new ResizeObserver(() => {
+            if (mode === 'navigation')
+                schedule('resize');
+        })
+        : null;
+    const mo = typeof MutationObserver !== 'undefined'
+        ? new MutationObserver((records) => {
+            if (mode !== 'navigation')
+                return;
+            if (windowedProjectionRequested &&
+                records.some((record) => record.target === doc.documentElement &&
+                    record.type === 'attributes' &&
+                    record.attributeName === 'style')) {
+                // Mutation delivery precedes paint. Waiting for the measurement
+                // rAF or Studio's post-paint route ACK exposes an unscaled frame
+                // when the router replaces the root layout, including a refresh
+                // after the route has already acknowledged its projection.
+                windowedProjection.reapplyAfterRootReset();
+            }
+            if (windowedProjectionRequested &&
+                records.every((record) => record.target === doc.documentElement &&
+                    record.type === 'attributes' &&
+                    record.attributeName === 'style' &&
+                    windowedProjection.ownsRootStyle())) {
+                return;
+            }
+            schedule('mutation');
+        })
+        : null;
+    const fontsLike = doc.fonts;
+    const onViewportResize = () => {
+        if (mode === 'navigation')
+            schedule('resize');
+    };
+    win.addEventListener('resize', onViewportResize);
+    if (fontsLike && typeof fontsLike.ready?.then === 'function') {
+        void fontsLike.ready.then(() => {
+            if (mode === 'navigation')
+                schedule('fonts-ready');
+        });
+    }
+    function attachObservers() {
+        if (ro) {
+            ro.disconnect();
+            if (doc.documentElement)
+                ro.observe(doc.documentElement);
+            if (doc.body)
+                ro.observe(doc.body);
+        }
+        if (mo && doc.documentElement) {
+            mo.observe(doc.documentElement, {
+                childList: true,
+                subtree: true,
+                attributes: true,
+                attributeFilter: ['style', 'class', 'hidden'],
+            });
+        }
+    }
+    function detachObservers() {
+        ro?.disconnect();
+        mo?.disconnect();
+    }
+    function onMessage(event) {
+        if (event.source !== win.parent)
+            return;
+        if (!isStudioToIframe(event.data))
+            return;
+        const msg = event.data;
+        if (msg.type === 'storystick.preview.windowed-minimap') {
+            if (mode === 'navigation' &&
+                windowedProjectionRequested &&
+                msg.epoch === epoch) {
+                const updated = windowedProjection.update(msg.windowStart, msg.renderSpan);
+                configuredProjectionEpoch = updated ? epoch : null;
+                publish(true);
+            }
+            return;
+        }
+        if (msg.type !== 'render-mode')
+            return;
+        const nextEpoch = msg.epoch ?? 0;
+        if (nextEpoch !== epoch)
+            configuredProjectionEpoch = null;
+        epoch = nextEpoch;
+        if (msg.mode === 'navigation') {
+            mode = 'navigation';
+            windowedProjectionRequested = msg.windowedMinimapProjection === true;
+            // Windowed projection is the canonical Navigation renderer requested by
+            // the current Studio. Older senders that omit the capability can still
+            // ask for the legacy contract explicitly, but a failed windowed
+            // projection must never fall back to it implicitly.
+            setContract(!windowedProjectionRequested);
+            if (windowedProjectionRequested) {
+                windowedProjection.enter();
+            }
+            else {
+                configuredProjectionEpoch = null;
+                windowedProjection.exit();
+            }
+            attachObservers();
+            schedule('render-mode');
+        }
+        else {
+            mode = 'device';
+            detachObservers();
+            configuredProjectionEpoch = null;
+            windowedProjection.exit();
+            windowedProjectionRequested = false;
+            setContract(false);
+            // Immediate (no settle needed — removing the attribute is the
+            // semantic; pageHeight is irrelevant in Device).
+            if (scheduler.isPending()) {
+                scheduler.cancel();
+                pendingEpoch = null;
+            }
+            publish(false);
+        }
+    }
+    win.addEventListener('message', onMessage);
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            if (scheduler.isPending()) {
+                scheduler.cancel();
+                pendingEpoch = null;
+            }
+            detachObservers();
+            windowedProjection.exit();
+            win.removeEventListener('message', onMessage);
+            win.removeEventListener('resize', onViewportResize);
+            // A torn-down SDK must not leave the customer document
+            // virtualised — restore strict truth.
+            setContract(false);
+        },
+        flush() {
+            if (stopped)
+                return last;
+            if (scheduler.isPending()) {
+                scheduler.cancel();
+                pendingEpoch = null;
+            }
+            if (mode === 'navigation')
+                return publish(true);
+            return last;
+        },
+    };
+}

package/dist/runtime/invalidation-adapter.d.ts

@@ -0,0 +1,17 @@
+import type { PreviewContentRefreshEvent } from './content-refresh.js';
+import { type PreviewRuntime } from './store.js';
+/**
+ * Framework seam for preview content invalidation.
+ *
+ * The runtime remains the authority for authenticated content clocks,
+ * deduplication, and refresh decisions. Adapters only translate an accepted
+ * event into the framework's render primitive. Next keeps its richer scheduler;
+ * Astro and other integrations can use this progressive-enhancement seam.
+ */
+export interface PreviewInvalidationAdapter {
+    refresh(event: PreviewContentRefreshEvent): void | Promise<void>;
+}
+export declare function connectPreviewInvalidationAdapter(adapter: PreviewInvalidationAdapter, runtime?: Pick<PreviewRuntime, 'subscribeContentRefresh'>): () => void;
+/** Astro-compatible fallback: preserve the exact URL and reload the document. */
+export declare function createBrowserReloadPreviewInvalidationAdapter(view?: Pick<Window, 'location'>): PreviewInvalidationAdapter;
+export type { PreviewContentRefreshEvent };

package/dist/runtime/invalidation-adapter.js

@@ -0,0 +1,42 @@
+import { previewRuntime } from './store.js';
+export function connectPreviewInvalidationAdapter(adapter, runtime = previewRuntime) {
+    let stopped = false;
+    let refreshing = false;
+    let pending = null;
+    const drain = async (event) => {
+        if (refreshing) {
+            pending = event;
+            return;
+        }
+        refreshing = true;
+        try {
+            await adapter.refresh(event);
+        }
+        finally {
+            refreshing = false;
+            const next = pending;
+            pending = null;
+            if (!stopped && next !== null)
+                void drain(next);
+        }
+    };
+    const unsubscribe = runtime.subscribeContentRefresh((event) => {
+        if (!stopped && event.refresh)
+            void drain(event);
+    });
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        pending = null;
+        unsubscribe();
+    };
+}
+/** Astro-compatible fallback: preserve the exact URL and reload the document. */
+export function createBrowserReloadPreviewInvalidationAdapter(view = window) {
+    return {
+        refresh() {
+            view.location.reload();
+        },
+    };
+}

package/dist/runtime/live-query-overlay.d.ts

@@ -0,0 +1,39 @@
+import { type PreviewLiveQueryProjectionPayload, type PreviewLiveQueryRegisterEnvelope, type PreviewLiveQueryUnregisterEnvelope, type PreviewMessage } from '@storystick/transport-allowlist';
+import type { PreviewQueryReceiptId } from '@storystick/types/preview-query-targeting';
+import type { QueryPageInfo, QueryResult } from '@storystick/types/query-contract';
+export interface PreviewLiveQueryOverlayConfiguration {
+    readonly enabled: boolean;
+    readonly projectId: string | null;
+    readonly sessionId: string | null;
+    readonly parentOrigin: string | null;
+    readonly view?: Window;
+}
+export interface PreviewLiveQueryOverlayHandle {
+    readonly queryInstanceId: string | null;
+    getSnapshot(): PreviewLiveQueryProjectionPayload | null;
+    subscribe(listener: () => void): () => void;
+    updateReceipt(receiptId: PreviewQueryReceiptId | null): void;
+    release(): void;
+}
+export interface PreviewLiveQueryOverlayRuntime {
+    configure(configuration: PreviewLiveQueryOverlayConfiguration): void;
+    retain(queryIdentity: string): PreviewLiveQueryOverlayHandle;
+    clear(): void;
+    /** Internal/test seam after shared envelope validation. */
+    acceptStudioEnvelope(message: PreviewMessage, eventOrigin: string, sourceIsParent: boolean): void;
+    /** Test-only visibility; never content authority. */
+    activeQueryCount(): number;
+}
+interface RuntimeOptions {
+    readonly randomHex?: () => string;
+    readonly now?: () => number;
+    readonly send?: (envelope: PreviewLiveQueryRegisterEnvelope | PreviewLiveQueryUnregisterEnvelope, targetOrigin: string) => void;
+}
+export declare function createPreviewLiveQueryOverlayRuntime(options?: RuntimeOptions): PreviewLiveQueryOverlayRuntime;
+export declare const previewLiveQueryOverlay: PreviewLiveQueryOverlayRuntime;
+/**
+ * Derive a render-only QueryResult. The confirmed object is never mutated and
+ * neither membership, order, pageInfo nor metadata can change.
+ */
+export declare function applyPreviewLiveQueryProjection<TData, TPageInfo extends QueryPageInfo | null>(confirmed: QueryResult<TData, TPageInfo> | undefined, projection: PreviewLiveQueryProjectionPayload | null): QueryResult<TData, TPageInfo> | undefined;
+export {};