@storystick/react 0.0.0-stage → 0.2.0-rc.1

package/dist/preview-host/use-standalone-presentation.js

@@ -0,0 +1,223 @@
+'use client';
+import { previewDraftHref } from '@storystick/preview/identity';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { previewRuntime } from '@storystick/preview/runtime/store';
+import { createPreviewRequestId } from '@storystick/preview/runtime/request-id';
+import { getNavigateHandler, hasNavigateHandler, } from '@storystick/preview/nav-handler';
+import { usePreviewPerspectiveIntent, isAcceptedPreviewPerspectiveIntent, } from '@storystick/react/internal/use-preview-perspective-intent';
+import { beginPreviewTransition, advancePreviewTransitionClock, confirmPreviewTransition, } from '@storystick/preview/runtime/preview-transition-state';
+import { previewCurrentPrimaryPage, readPrimaryPagesSnapshot, subscribePrimaryPages, } from './preview-studio-destination.js';
+/** Acceptance releases the editor; render proof releases the page overlays.
+ * No authoring credentials cross this port; the framework uses its Preview cookie. */
+export function useStandalonePresentation(basePath) {
+    const pending = useRef(null);
+    const generation = useRef(0);
+    const completedGeneration = useRef(0);
+    const [transition, setTransition] = useState({
+        kind: 'idle',
+    });
+    const clearPending = useCallback(() => {
+        const flight = pending.current;
+        if (!flight)
+            return;
+        clearTimeout(flight.timer);
+        pending.current = null;
+    }, []);
+    const perspective = usePreviewPerspectiveIntent({
+        getSessionId: () => previewRuntime.getState().sessionId,
+        getReadContext: () => previewRuntime.getState().session?.readContext ?? null,
+        beginTransition: () => ({ generation: generation.current }),
+        registerCommand: () => undefined,
+        clearTransition: () => undefined,
+        dispatch: async (scope) => {
+            const context = previewRuntime.getState().session?.readContext;
+            const flight = pending.current;
+            if (!context || !hasNavigateHandler())
+                return { commandId: null };
+            const commandId = flight?.commandId ?? createPreviewRequestId();
+            await getNavigateHandler()(flight
+                ? previewDraftHref(flight.request.pathname, flight.request.draftDocumentId)
+                : `${window.location.pathname}${window.location.search}`, {
+                scope,
+                commandId,
+                refresh: true,
+                history: 'push',
+                contextCommand: {
+                    expectedContextId: context.contextId,
+                    expectedRevision: context.revision,
+                },
+            });
+            return { commandId };
+        },
+    });
+    const observe = useCallback(() => {
+        const lifecycle = previewRuntime.getLifecycleSnapshot();
+        if (lifecycle)
+            perspective.observeLifecycle(lifecycle);
+        const flight = pending.current;
+        if (!flight?.accepted)
+            return;
+        const state = previewRuntime.getState();
+        const context = state.session?.readContext;
+        if (!context ||
+            context.contextId !== flight.accepted.contextId ||
+            context.revision !== flight.accepted.revision) {
+            clearPending();
+            setTransition({ kind: 'idle' });
+            return;
+        }
+        const committed = flight.committed;
+        const receipt = committed?.presentation;
+        if (receipt && committed.commandId === flight.commandId &&
+            receipt.readContext.contextId === context.contextId &&
+            receipt.readContext.revision === context.revision &&
+            receipt.pathname === flight.request.pathname &&
+            receipt.pathname === (window.location.pathname.slice(basePath.length) || '/')) {
+            // The framework committed a fresh server request in the accepted
+            // context. This proof does not depend on editable fields being present.
+            clearPending();
+            completedGeneration.current = flight.generation;
+            setTransition({ kind: 'idle' });
+            return;
+        }
+        const page = previewCurrentPrimaryPage(readPrimaryPagesSnapshot(), state.sessionId, context, window.location.pathname, basePath);
+        if (!page ||
+            state.renderedReadContext?.contextId !== context.contextId ||
+            state.renderedReadContext.revision !== context.revision)
+            return;
+        const confirmed = confirmPreviewTransition(flight.transition, {
+            kind: 'presentation',
+            pageDocId: page.documentId,
+            locale: page.locale,
+            pathname: window.location.pathname.slice(basePath.length) || '/',
+            context,
+            acceptedContext: flight.accepted,
+        });
+        if (confirmed.kind !== 'idle')
+            return;
+        clearTimeout(flight.timer);
+        pending.current = null;
+        completedGeneration.current = generation.current;
+        setTransition(confirmed);
+    }, [basePath, perspective.observeLifecycle, clearPending]);
+    useEffect(() => {
+        const onCommit = (event) => {
+            const committed = event.detail;
+            if (pending.current && committed?.commandId === pending.current.commandId) {
+                pending.current.committed = committed;
+                observe();
+            }
+        };
+        const stopRuntime = previewRuntime.subscribe(observe);
+        const stopPages = subscribePrimaryPages(observe);
+        window.addEventListener('storystick.preview.location-committed', onCommit);
+        return () => {
+            stopRuntime();
+            stopPages();
+            window.removeEventListener('storystick.preview.location-committed', onCommit);
+            clearPending();
+        };
+    }, [observe, clearPending]);
+    const present = useCallback(async (request) => {
+        if (!hasNavigateHandler())
+            throw new Error('PREVIEW_NAVIGATION_UNAVAILABLE');
+        // The local port has no iframe envelope; validate before invoking the same adapter.
+        if (!request.pathname.startsWith('/') ||
+            request.pathname.startsWith('//') ||
+            /[\\\u0000-\u0020]/.test(request.pathname)) {
+            throw new Error('PREVIEW_DESTINATION_INVALID');
+        }
+        clearPending();
+        perspective.cancelPending();
+        const next = beginPreviewTransition({
+            generation: ++generation.current,
+            reason: 'preview-intent',
+            now: Date.now(),
+            target: {
+                sessionId: previewRuntime.getState().sessionId,
+                editorDocumentId: null,
+                expectedPreviewDocumentId: request.documentId,
+                expectedLocale: request.locale,
+                expectedPathname: request.pathname,
+                expectedPerspective: request.perspective,
+                expectedSearch: '',
+                expectedHash: '',
+                hostStatus: 'valid',
+                sourceOfTruth: 'system',
+            },
+        });
+        setTransition(next);
+        const flight = {
+            request,
+            transition: next,
+            accepted: null,
+            commandId: createPreviewRequestId(),
+            committed: null,
+            generation: generation.current,
+            timer: setTimeout(() => {
+                if (pending.current !== flight)
+                    return;
+                // Keep observing: a slow page may still provide valid proof later.
+                setTransition(advancePreviewTransitionClock(next, Date.now()));
+            }, 12_000),
+        };
+        pending.current = flight;
+        try {
+            const accepted = await perspective.changePerspective(request.perspective);
+            if (pending.current !== flight)
+                throw new Error('PREVIEW_PRESENTATION_SUPERSEDED');
+            if (!isAcceptedPreviewPerspectiveIntent(accepted))
+                throw new Error(`PREVIEW_CONTEXT_${accepted.status}`);
+            flight.accepted = accepted.context;
+            if (accepted.status === 'local-noop') {
+                await getNavigateHandler()(previewDraftHref(request.pathname, request.draftDocumentId), {
+                    scope: accepted.context.perspective,
+                    refresh: true,
+                    history: 'push',
+                    commandId: flight.commandId,
+                });
+            }
+            if (pending.current !== flight && completedGeneration.current !== flight.generation)
+                throw new Error('PREVIEW_PRESENTATION_SUPERSEDED');
+            // Publish acceptedContext even when no render evidence has arrived.
+            if (pending.current === flight)
+                setTransition(current => ({ ...current }));
+            observe();
+            if (pending.current !== flight && completedGeneration.current !== flight.generation)
+                throw new Error('PREVIEW_PRESENTATION_SUPERSEDED');
+            return accepted.context;
+        }
+        catch (cause) {
+            if (pending.current === flight) {
+                clearPending();
+                setTransition(flight.accepted
+                    ? advancePreviewTransitionClock(next, Number.POSITIVE_INFINITY)
+                    : { kind: 'idle' });
+            }
+            throw cause;
+        }
+    }, [
+        observe,
+        perspective.changePerspective,
+        perspective.cancelPending,
+        clearPending,
+    ]);
+    return {
+        present,
+        /** The project menu also exists on routes without an editable document. */
+        async changePerspective(next) {
+            clearPending();
+            perspective.cancelPending();
+            setTransition({ kind: 'idle' });
+            const accepted = await perspective.changePerspective(next);
+            if (!isAcceptedPreviewPerspectiveIntent(accepted))
+                throw new Error(`PREVIEW_CONTEXT_${accepted.status}`);
+            return accepted.context;
+        },
+        transition,
+        completedGeneration: completedGeneration.current,
+        acceptedContext: pending.current?.accepted ?? null,
+        acceptedPresentation: pending.current?.accepted ? pending.current.request : null,
+        isPending: transition.kind !== 'idle',
+    };
+}

package/dist/preview-icons.d.ts

@@ -0,0 +1,10 @@
+import type { SVGProps } from 'react';
+type IconProps = SVGProps<SVGSVGElement> & {
+    size?: number | string;
+    absoluteStrokeWidth?: boolean;
+};
+export declare function X(props: IconProps): import("react").JSX.Element;
+export declare function ArrowUpRight(props: IconProps): import("react").JSX.Element;
+export declare function MessageCircle(props: IconProps): import("react").JSX.Element;
+export declare function SquarePen(props: IconProps): import("react").JSX.Element;
+export {};

package/dist/preview-icons.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function Icon({ size = 24, strokeWidth = 2, absoluteStrokeWidth, children, ...props }) {
+    return _jsx("svg", { xmlns: "http://www.w3.org/2000/svg", width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: absoluteStrokeWidth ? Number(strokeWidth) * 24 / Number(size) : strokeWidth, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", ...props, children: children });
+}
+export function X(props) { return _jsxs(Icon, { ...props, children: [_jsx("path", { d: "M18 6 6 18" }), _jsx("path", { d: "m6 6 12 12" })] }); }
+export function ArrowUpRight(props) { return _jsxs(Icon, { ...props, children: [_jsx("path", { d: "M7 7h10v10" }), _jsx("path", { d: "M7 17 17 7" })] }); }
+export function MessageCircle(props) { return _jsx(Icon, { ...props, children: _jsx("path", { d: "M7.9 20A9 9 0 1 0 4 16.1L2 22Z" }) }); }
+export function SquarePen(props) { return _jsxs(Icon, { ...props, children: [_jsx("path", { d: "M12 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2v-7" }), _jsx("path", { d: "M18.375 2.625a1 1 0 0 1 3 3l-9.013 9.014a2 2 0 0 1-.853.505l-2.873.84a.5.5 0 0 1-.62-.62l.84-2.873a2 2 0 0 1 .506-.852z" })] }); }

package/dist/preview-interaction-control.d.ts

@@ -0,0 +1,6 @@
+export type PreviewInteractionMode = "edit" | "browse";
+/** Lightweight common control: available before loading the authoring runtime. */
+export declare function PreviewInteractionControl({ interactionMode, onChange, }: {
+    interactionMode: PreviewInteractionMode;
+    onChange(mode: PreviewInteractionMode): void;
+}): import("react").JSX.Element;

package/dist/preview-interaction-control.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Radio } from "@base-ui/react/radio";
+import { RadioGroup } from "@base-ui/react/radio-group";
+/** Lightweight common control: available before loading the authoring runtime. */
+export function PreviewInteractionControl({ interactionMode, onChange, }) {
+    return (_jsx(RadioGroup, { value: interactionMode, onValueChange: onChange, "aria-label": "Preview interaction mode", "data-slot": "preview-frame-interaction-mode", style: {
+            display: "inline-flex",
+            alignItems: "center",
+            padding: 4,
+            gap: 2,
+            borderRadius: 999,
+            background: "var(--color-surface-card, #fff)",
+            color: "var(--color-text-primary, #17191b)",
+            boxShadow: "var(--ss-shadow-control, 0 0 0 1px rgb(0 0 0 / 8%), 0 2px 4px rgb(0 0 0 / 5%))",
+        }, children: ["edit", "browse"].map((mode) => (_jsx(Radio.Root, { value: mode, nativeButton: true, render: _jsx("button", { type: "button" }), "data-slot": `preview-frame-interaction-${mode}`, "aria-label": mode === "edit"
+                ? "Inspect: select content to edit"
+                : "Navigate: use site links", title: mode === "edit"
+                ? "Select content to edit"
+                : "Use site links. Hold Option/Alt to navigate temporarily.", style: {
+                appearance: "none",
+                display: "inline-flex",
+                alignItems: "center",
+                justifyContent: "center",
+                height: 28,
+                padding: "0 8px",
+                border: 0,
+                borderRadius: 999,
+                cursor: "pointer",
+                background: interactionMode === mode
+                    ? "var(--color-surface-field, #f0f0f1)"
+                    : "transparent",
+                color: "inherit",
+                fontFamily: "inherit",
+                fontSize: 13,
+                fontWeight: 500,
+                lineHeight: "17px",
+            }, children: mode === "edit" ? (_jsxs("svg", { width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: (1.25 * 24) / 14, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("path", { d: "M2 10h6V4" }), _jsx("path", { d: "m2 4 6 6" }), _jsx("path", { d: "M21 10V7a2 2 0 0 0-2-2h-7" }), _jsx("path", { d: "M3 14v2a2 2 0 0 0 2 2h3" }), _jsx("rect", { x: "12", y: "14", width: "10", height: "7", rx: "1" })] })) : ("Navigate") }, mode))) }));
+}

package/dist/preview-page-state.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from 'react';
+/** One page composition for launch, activation and terminal Preview feedback.
+ * Actions and progress belong to the caller's existing lifecycle. */
+export declare function PreviewPageState({ title, description, role, indicator, actions, children }: {
+    title: string;
+    description: ReactNode;
+    role: 'status' | 'alert';
+    indicator?: ReactNode;
+    actions?: ReactNode;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function PreviewPageProgress(): import("react").JSX.Element;

package/dist/preview-page-state.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { PREVIEW_PAGE_STYLES } from '@storystick/preview/page-presentation';
+import { StorystickMark } from './storystick-mark.js';
+/** One page composition for launch, activation and terminal Preview feedback.
+ * Actions and progress belong to the caller's existing lifecycle. */
+export function PreviewPageState({ title, description, role, indicator, actions, children }) {
+    return _jsxs(_Fragment, { children: [_jsx("style", { children: PREVIEW_PAGE_STYLES }), _jsx("main", { "data-ss-preview-page": "", children: _jsxs("div", { "data-ss-preview-page-content": "", children: [_jsxs("div", { "data-ss-preview-page-brand": "", children: [_jsx(StorystickMark, {}), _jsx("span", { children: "Storystick" })] }), _jsxs("div", { role: role, children: [_jsxs("div", { "data-ss-preview-page-heading": "", children: [indicator, _jsx("h1", { "data-ss-preview-page-title": "", children: title })] }), _jsx("p", { "data-ss-preview-page-description": "", children: description })] }), actions ? _jsx("div", { "data-ss-preview-page-actions": "", children: actions }) : null, children] }) })] });
+}
+export function PreviewPageProgress() {
+    return _jsx("span", { "data-ss-preview-page-progress": "", "aria-hidden": "true" });
+}

package/dist/preview-panel-state.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentProps, ReactNode } from 'react';
+type MessageProps = {
+    title: string;
+    description: ReactNode;
+    actions?: ReactNode;
+    children?: ReactNode;
+    role?: 'alert' | 'status';
+};
+/** Also works before the authoring runtime loads, or after its providers fail.
+ * Keep these styles self-contained: the host and runtime own separate bundles. */
+export declare function PreviewPanelMessage({ title, description, actions, children, role }: MessageProps): import("react").JSX.Element;
+/** A blocking state fills the panel; recoverable notices use Message directly. */
+export declare function PreviewPanelState(props: MessageProps): import("react").JSX.Element;
+export declare function PreviewPanelAction(props: ComponentProps<'button'>): import("react").JSX.Element;
+export {};

package/dist/preview-panel-state.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/** Also works before the authoring runtime loads, or after its providers fail.
+ * Keep these styles self-contained: the host and runtime own separate bundles. */
+export function PreviewPanelMessage({ title, description, actions, children, role = 'alert' }) {
+    return _jsxs(_Fragment, { children: [_jsx("style", { children: MESSAGE_STYLES }), _jsxs("div", { "data-ss-panel-message": "", role: role, children: [_jsxs("div", { "data-ss-panel-message-copy": "", children: [_jsx("h2", { children: title }), _jsx("p", { children: description })] }), actions ? _jsx("div", { "data-ss-panel-message-actions": "", children: actions }) : null, children] })] });
+}
+/** A blocking state fills the panel; recoverable notices use Message directly. */
+export function PreviewPanelState(props) {
+    return _jsx("div", { "data-ss-panel-state": "", children: _jsx(PreviewPanelMessage, { ...props }) });
+}
+export function PreviewPanelAction(props) {
+    return _jsx("button", { type: "button", "data-ss-panel-action": "", ...props });
+}
+const MESSAGE_STYLES = `
+  [data-ss-panel-state] { box-sizing: border-box; display: flex; flex-direction: column; width: 100%; height: 100%; min-height: 0; min-width: 0; overflow: auto; padding: 24px; background: var(--ss-surface-page, #fff); }
+  [data-ss-panel-state] > [data-ss-panel-message] { margin: auto; padding: 0; }
+  [data-ss-panel-message] { box-sizing: border-box; flex: none; width: 100%; max-width: 360px; margin-inline: auto; padding: 16px; color: #52525b; font: 400 13px/1.5 "Storystick Inter", "Inter Variable", ui-sans-serif, system-ui, sans-serif; text-align: center; overflow-wrap: anywhere; }
+  [data-ss-panel-message-copy] h2 { margin: 0; color: #18181b; font-size: 15px; font-weight: 500; line-height: 1.4; text-wrap: balance; }
+  [data-ss-panel-message-copy] p { margin: 8px 0 0; text-wrap: pretty; }
+  [data-ss-panel-message-actions] { display: flex; flex-wrap: wrap; align-items: center; justify-content: center; gap: 8px; margin-top: 16px; }
+  [data-ss-panel-action] { display: inline-flex; align-items: center; justify-content: center; min-height: 32px; padding: 6px 14px; border: 1px solid transparent; border-radius: 999px; background: #18181b; color: #fff; font: inherit; line-height: 20px; cursor: pointer; text-decoration: none; }
+  [data-ss-panel-action]:hover { background: #303034; }
+  [data-ss-panel-action]:focus-visible, [data-ss-panel-message] summary:focus-visible { outline: 2px solid #3b82f6; outline-offset: 3px; }
+  [data-ss-panel-action]:disabled { opacity: .5; cursor: default; }
+  [data-ss-panel-message] details { width: 100%; margin-top: 16px; }
+  [data-ss-panel-message] summary { cursor: pointer; border-radius: 4px; }
+  [data-ss-panel-message] pre { max-height: 240px; overflow: auto; margin: 12px 0 0; padding: 12px; border-radius: 12px; background: #f4f4f5; color: #52525b; font: 12px/1.5 ui-monospace, monospace; text-align: left; white-space: pre; }
+`;

package/dist/preview-provenance-publisher-model.d.ts

@@ -0,0 +1,5 @@
+export declare const PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_EVENT: "storystick.preview.provenance-publisher-consumed";
+export declare const PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_REGISTRY: "__ssPreviewProvenanceConsumedPublishersV2";
+export declare function serializePreviewProvenancePublisher(value: unknown): string;
+export declare function previewProvenancePublisherConsumptionKey(frameId: string, renderNonce: string): string;
+export declare const PREVIEW_PROVENANCE_OCCURRENCE_EVENT: "storystick.preview.provenance-occurrence";

package/dist/preview-provenance-publisher-model.js

@@ -0,0 +1,9 @@
+export const PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_EVENT = 'storystick.preview.provenance-publisher-consumed';
+export const PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_REGISTRY = '__ssPreviewProvenanceConsumedPublishersV2';
+export function serializePreviewProvenancePublisher(value) {
+    return JSON.stringify(value).replace(/</g, '\\u003c');
+}
+export function previewProvenancePublisherConsumptionKey(frameId, renderNonce) {
+    return JSON.stringify([frameId, renderNonce]);
+}
+export const PREVIEW_PROVENANCE_OCCURRENCE_EVENT = 'storystick.preview.provenance-occurrence';

package/dist/preview-provenance-publisher.d.ts

@@ -0,0 +1,15 @@
+import { type ReactElement } from 'react';
+import type { PreviewProvenancePublicSidecar } from './preview-provenance.js';
+export interface PreviewProvenanceSidecarProps {
+    readonly frameId: string;
+    readonly sessionId?: string | null;
+    readonly sidecar: PreviewProvenancePublicSidecar | null | undefined;
+}
+/**
+ * Publishes one server-rendered frame early enough for the deferred preview
+ * runtime to consume it, then lets React retire the inert capsule immediately
+ * after hydration. The runtime deliberately leaves React-owned capsules in
+ * place so it never mutates the tree React is about to hydrate.
+ */
+export declare function PreviewProvenanceSidecar({ frameId, sessionId, sidecar, }: PreviewProvenanceSidecarProps): ReactElement | null;
+export declare const PreviewProvenancePublisher: typeof PreviewProvenanceSidecar;

package/dist/preview-provenance-publisher.js

@@ -0,0 +1,68 @@
+'use client';
+import { createElement, useLayoutEffect, useState } from 'react';
+import { PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_EVENT, PREVIEW_PROVENANCE_OCCURRENCE_EVENT, PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_REGISTRY, previewProvenancePublisherConsumptionKey, serializePreviewProvenancePublisher, } from './preview-provenance-publisher-model.js';
+/**
+ * Publishes one server-rendered frame early enough for the deferred preview
+ * runtime to consume it, then lets React retire the inert capsule immediately
+ * after hydration. The runtime deliberately leaves React-owned capsules in
+ * place so it never mutates the tree React is about to hydrate.
+ */
+export function PreviewProvenanceSidecar({ frameId, sessionId, sidecar, }) {
+    const [awaitingConsumption, setAwaitingConsumption] = useState(true);
+    const renderNonce = sidecar?.renderNonce;
+    const publisherKey = typeof renderNonce === 'string'
+        ? previewProvenancePublisherConsumptionKey(frameId, renderNonce)
+        : null;
+    useLayoutEffect(() => {
+        if (publisherKey === null)
+            return;
+        // Consumption belongs to one render epoch. A new RSC occurrence must
+        // republish even when this component instance survived the refresh.
+        setAwaitingConsumption(true);
+        window.dispatchEvent(new CustomEvent(PREVIEW_PROVENANCE_OCCURRENCE_EVENT, {
+            detail: { operation: 'mount', frameId, renderNonce },
+        }));
+        const finishIfConsumed = (event) => {
+            const detail = event instanceof CustomEvent
+                ? event.detail
+                : null;
+            if (detail !== null && detail.publisherKey !== publisherKey)
+                return;
+            const registry = window[PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_REGISTRY];
+            if (registry?.[publisherKey] === true)
+                setAwaitingConsumption(false);
+        };
+        window.addEventListener(PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_EVENT, finishIfConsumed);
+        finishIfConsumed();
+        return () => {
+            window.dispatchEvent(new CustomEvent(PREVIEW_PROVENANCE_OCCURRENCE_EVENT, {
+                detail: { operation: 'unmount', frameId, renderNonce },
+            }));
+            window.removeEventListener(PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_EVENT, finishIfConsumed);
+        };
+    }, [publisherKey, frameId, renderNonce]);
+    if (!awaitingConsumption ||
+        !sidecar ||
+        (!sessionId && !sidecar.dependencySet?.readContext) ||
+        typeof sidecar.renderNonce !== 'string' ||
+        sidecar.renderNonce.length === 0 ||
+        typeof sidecar.emissionRevision !== 'number' ||
+        !Number.isFinite(sidecar.emissionRevision) ||
+        sidecar.emissionRevision <= 0)
+        return null;
+    return createElement('template', {
+        'data-ss-provenance-publisher': frameId,
+        'data-ss-provenance-react-owned': 'true',
+        'data-preview-message-session-id': sessionId,
+        suppressHydrationWarning: true,
+        dangerouslySetInnerHTML: {
+            __html: serializePreviewProvenancePublisher({
+                type: 'storystick.preview.provenance-publisher',
+                version: 2,
+                sessionId,
+                frame: { frameId, sidecar },
+            }),
+        },
+    });
+}
+export const PreviewProvenancePublisher = PreviewProvenanceSidecar;

package/dist/preview-provenance.d.ts

@@ -0,0 +1,6 @@
+export { PreviewProvenancePublisher, PreviewProvenanceSidecar, } from './preview-provenance-publisher.js';
+export type { PreviewProvenanceSidecarProps } from './preview-provenance-publisher.js';
+export { PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_EVENT, PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_REGISTRY, previewProvenancePublisherConsumptionKey, serializePreviewProvenancePublisher, } from './preview-provenance-publisher-model.js';
+export { isPreviewSliceDirectInvocationCandidate, readPreviewSliceScopeAdapter, registerPreviewSliceScopeAdapter, } from './preview-slice-scope.js';
+export type { PreviewSliceScopeAdapter, PreviewSliceScopeDescriptor, PreviewSliceScopeInvocation, } from './preview-slice-scope.js';
+export * from '@storystick/preview/provenance/render-context';

package/dist/preview-provenance.js

@@ -0,0 +1,4 @@
+export { PreviewProvenancePublisher, PreviewProvenanceSidecar, } from './preview-provenance-publisher.js';
+export { PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_EVENT, PREVIEW_PROVENANCE_PUBLISHER_CONSUMED_REGISTRY, previewProvenancePublisherConsumptionKey, serializePreviewProvenancePublisher, } from './preview-provenance-publisher-model.js';
+export { isPreviewSliceDirectInvocationCandidate, readPreviewSliceScopeAdapter, registerPreviewSliceScopeAdapter, } from './preview-slice-scope.js';
+export * from '@storystick/preview/provenance/render-context';

package/dist/preview-scope.d.ts

@@ -0,0 +1,128 @@
+/**
+ * preview-scope — the SliceZone ↔ `Slice.*` prod-strip contract (ADR-129
+ * D3 / D4-amended).
+ *
+ * `Slice.section` emits the `data-ss-slice` binding attribute ONLY in
+ * preview. The runtime preview-mode signal cannot be a React context —
+ * a React Server Component cannot read context, so a context-gated
+ * `Slice.*` would be forced `'use client'` and stop being RSC-safe
+ * (empirically confirmed, ADR-129 vertical-slice de-risk, check C).
+ *
+ * Instead the signal travels on the one object `Slice.section` already
+ * receives: the `slice` prop. `<SliceZone>` is the single component
+ * that knows preview-vs-production (the `publishedAt`/`snapshotId`
+ * discriminator — see `slice-zone.tsx`). In preview it STAMPS each
+ * slice object it passes to a slice component with that slice's
+ * serialized per-slice model (ADR-129 D4/D9). `Slice.section` reads the
+ * stamp and emits it back as the `data-ss-model` attribute — on the
+ * slice's own root element, alongside `data-ss-slice`. Outside preview
+ * the slice is passed through unstamped and neither attribute is
+ * emitted — a true prod-strip, RSC-safe, zero hooks.
+ *
+ * D9 amendment (cross-model /review R5) — the per-slice model is a
+ * `data-ss-model` ATTRIBUTE, never a `<script>` node. A `<script>`
+ * sibling is `display:none` but still an element, so it shifts
+ * `:nth-child` / `first:` / `odd:` / `even:` for the customer's slices
+ * (preview ≠ production). An attribute on the slice's own element
+ * shifts nothing — the same rule that drove D4 from a marker-node to
+ * an attribute. With the island node gone, ADR-129 injects zero nodes.
+ *
+ * ── RSC AMENDMENT (2026-05-27) ──────────────────────────────────────
+ * The stamp was originally a module-local `Symbol` key. Next.js 15's
+ * RSC serializer rejects Symbol-keyed properties on objects passed
+ * from a Server Component to a Client Component with the error
+ *   "Only plain objects can be passed to Client Components from
+ *    Server Components. Objects with symbol properties like
+ *    `storystick.previewScope` are not supported."
+ * Customer slice components are routinely `'use client'` (interactive
+ * forms, hooks, …); even when the slice component is RSC, its
+ * descendants are usually client components, so the stamped slice
+ * always ends up crossing the RSC→Client boundary in real apps. The
+ * Symbol was a non-starter on Next 15.
+ *
+ * The stamp is now a string-keyed property under a fresh, namespaced
+ * Storystick reserved key: `_ssPreview`. The earlier `_model` slot
+ * was rejected by codex R1 — `_model` is the ADR-053 model-linking
+ * sidecar key that `hydrateSlice` reads as a string model id, so
+ * reusing it would (a) overwrite the model link in preview and
+ * (b) false-positive `isPreviewScoped()` on every production-linked
+ * slice. The `_ss*` prefix mirrors the existing `data-ss-*` DOM
+ * attribute convention used by `Slice.*` (`data-ss-slice`,
+ * `data-ss-bind`, `data-ss-model`) — one namespace, no ambiguity.
+ *
+ * Codex R2 then raised a P2: a string key alone is forgeable — a
+ * customer could (in theory) define a slice field literally named
+ * `_ssPreview` of type `string`, and SliceZone would mistake it for
+ * a preview stamp. The mitigation is structural: the stamp value is
+ * not a bare string but a tagged object `{ v: 'ss-preview-1', model:
+ * <JSON> }`. `isPreviewScoped()` checks the tag, not just the key —
+ * a customer field with the same string-typed name is rejected by
+ * shape.
+ *
+ * Codex R3 P2 (accepted as documented tradeoff): a customer COULD
+ * still define a field literally named `_ssPreview` with an object
+ * value that exactly matches the tagged shape `{ v: 'ss-preview-1',
+ * model: <string> }`. Two reasons we accept this:
+ *
+ *   1. The `_<x>` prefix is the existing Storystick reserved
+ *      namespace — `_type`, `_key`, `_variation`, `_model` all live
+ *      there. Adding `_ssPreview` extends the established convention.
+ *      The storyspec format documents leading-underscore field names
+ *      as SDK-reserved; the schema generator doesn't emit them.
+ *   2. The Symbol-keyed alternative was the ONLY structurally
+ *      unforgeable choice, and it is incompatible with Next 15's RSC
+ *      serializer (the bug this fix addresses). There is no third
+ *      design that satisfies BOTH "RSC-serializable" AND
+ *      "structurally unforgeable from any customer field".
+ *
+ * If a customer in v∞ produces a field shaped exactly like the stamp,
+ * the failure mode is overwrite-in-preview only (production renders
+ * never call `stampPreviewScope`). Detection would be loud (the
+ * customer's component receives a model JSON instead of its data),
+ * and the schema reader is the right place to forbid `_<x>` field
+ * names — a follow-up scoped to the schema parser, not this SDK seam.
+ *
+ * `slice-zone.tsx::SLICE_META_KEYS` gains `_ssPreview` so
+ * `extractSliceFields` filters it out of the serialized model
+ * payload (no recursive self-embedding of the stamp into its own
+ * model). Customer iteration (`Object.keys`, `JSON.stringify` of the
+ * slice) sees one extra meta key under the same `_*` convention
+ * customers already filter when walking slice fields; in production
+ * the property is never stamped, so production renders are
+ * byte-identical to a slice with no preview machinery — the
+ * reference-stable fast path is preserved.
+ *
+ * Why this is solid:
+ * - Plain object property ⇒ RSC-safe by construction.
+ * - Fresh namespaced key + tagged value shape ⇒ unforgeable from a
+ *   customer field of any type the schema generator can emit.
+ * - Filtered by `extractSliceFields` via `SLICE_META_KEYS` ⇒ doesn't
+ *   recurse into the serialized model payload.
+ * - Production stays unstamped ⇒ no leak in prod, no reference churn.
+ * - The wire contract with `@storystick/preview` is the DOM
+ *   `data-ss-model` attribute — that has not changed.
+ */
+/**
+ * Return a shallow copy of `slice` carrying the preview-scope stamp —
+ * the serialized per-slice model string `<SliceZone>` built for it.
+ * A copy (never a mutation) so `hydrateSlice`'s no-mutation invariant
+ * holds and the customer's query-cache entry is untouched. The copy
+ * costs one object identity per slice per render — accepted: it is
+ * stamped ONLY in preview, where slices already re-render on every
+ * live-content revision, so `React.memo` stability is not in play.
+ * Production renders never call this — there `hydrateSlice`'s
+ * reference-stable fast path is preserved intact.
+ */
+export declare function stampPreviewScope<T extends object>(slice: T, modelJson: string): T;
+/**
+ * The serialized per-slice model `<SliceZone>` stamped on this slice,
+ * or `undefined` when the slice is not preview-scoped (production, a
+ * bare slice, a test stub, or a customer field that happens to share
+ * the `_ssPreview` name but doesn't match the stamp shape).
+ */
+export declare function getPreviewModel(slice: unknown): string | undefined;
+/**
+ * Was this slice object stamped by `<SliceZone>` as preview-scoped?
+ * Equivalent to "has a per-slice model" — the two are co-stamped.
+ */
+export declare function isPreviewScoped(slice: unknown): boolean;