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

package/dist/preview/route-initial.js

@@ -0,0 +1,156 @@
+/** One-shot PreviewGrant activation route. */
+import { NextResponse } from 'next/server';
+import { draftMode, cookies } from 'next/headers';
+import { PREVIEW_ACTIVATION_QUERY_PARAM, PreviewActivationError, PreviewGrantExchangeError, PreviewRedirectError, activatePreviewGrantForServer, assertSafePreviewRedirect, classifyPreviewGrantError, isSafePreviewSessionId, parsePreviewActivation, previewCookieAttributes, } from '@storystick/preview/server/grant';
+import { getPreviewTransport, resolvePreviewRequestOrigin } from './internal.js';
+import { primePreviewGrantAccess } from '@storystick/preview/server/extract-token';
+import { resolveStorystickApplicationBuildId } from '../code-version.js';
+import { buildPreviewGrantCookieFromActivation, setPreviewGrantCookieOnResponse, } from '@storystick/preview/server/route-session-cookie';
+import { previewInitialRouteErrorResponse, } from './route-errors.js';
+import { PREVIEW_SESSION_QUERY_PARAM, PREVIEW_VARIANT_QUERY_PARAM, PREVIEW_RELEASE_QUERY_PARAM, PreviewScopeConflictError, createPreviewScope, writePreviewScopeToSearchParams, } from '@storystick/preview/identity';
+const DEFAULTS = {
+    redirectParam: 'redirect',
+    basePath: '',
+};
+export function createStorystickPreviewHandler(options = {}) {
+    const redirectParam = options.redirectParam ?? DEFAULTS.redirectParam;
+    const basePath = options.basePath ?? DEFAULTS.basePath;
+    return async function GET(request) {
+        const url = request.nextUrl;
+        const sessionId = url.searchParams.get(PREVIEW_SESSION_QUERY_PARAM);
+        if (!isSafePreviewSessionId(sessionId)) {
+            return withNoReferrer(previewInitialRouteErrorResponse(request, {
+                status: 400, code: 'PREVIEW_SESSION_MISSING', message: 'preview session selector is required',
+                category: 'validation', recoverable: true, retryable: false,
+            }));
+        }
+        let activation;
+        try {
+            activation = parsePreviewActivation(url.searchParams.get(PREVIEW_ACTIVATION_QUERY_PARAM));
+        }
+        catch (error) {
+            if (error instanceof PreviewActivationError) {
+                return withNoReferrer(previewInitialRouteErrorResponse(request, {
+                    status: 400, code: 'PREVIEW_ACTIVATION_INVALID', message: 'preview activation is missing or malformed',
+                    category: 'validation', recoverable: true, retryable: false,
+                }));
+            }
+            throw error;
+        }
+        let safeRedirect;
+        try {
+            safeRedirect = assertSafePreviewRedirect(url.searchParams.get(redirectParam) || basePath || '/', basePath);
+        }
+        catch (error) {
+            if (error instanceof PreviewRedirectError) {
+                console.warn('[storystick/preview] unsafe redirect rejected');
+                return withNoReferrer(previewInitialRouteErrorResponse(request, {
+                    status: 400, code: 'PREVIEW_REDIRECT_UNSAFE', message: 'unsafe redirect',
+                    category: 'validation', recoverable: true, retryable: false,
+                }));
+            }
+            throw error;
+        }
+        let previewScope;
+        try {
+            previewScope = createPreviewScope({
+                variantId: url.searchParams.get(PREVIEW_VARIANT_QUERY_PARAM),
+                releaseId: url.searchParams.get(PREVIEW_RELEASE_QUERY_PARAM),
+            });
+        }
+        catch (error) {
+            if (error instanceof PreviewScopeConflictError) {
+                return withNoReferrer(previewInitialRouteErrorResponse(request, {
+                    status: 400, code: 'PREVIEW_SCOPE_CONFLICT', message: 'preview cannot select a variant and a release together',
+                    category: 'validation', recoverable: true, retryable: false,
+                }));
+            }
+            throw error;
+        }
+        const requestOrigin = resolvePreviewRequestOrigin(request);
+        const transport = await getPreviewTransport();
+        const cookieStore = await cookies();
+        const scope = { ...transport, requestOrigin };
+        let exchange;
+        try {
+            exchange = await activatePreviewGrantForServer({
+                endpoint: transport.endpoint,
+                apiKey: transport.apiKey,
+                applicationBuildId: resolveStorystickApplicationBuildId(),
+                grantId: activation.grantId,
+                activationSecret: activation.activationSecret,
+                sessionId,
+                requestOrigin,
+            });
+        }
+        catch (error) {
+            if (error instanceof PreviewGrantExchangeError) {
+                const publicError = classifyPreviewGrantError(error, 'activate');
+                console.warn('[storystick/preview] grant activation failed', {
+                    code: publicError.code,
+                    status: publicError.status,
+                    upstreamCode: error.code,
+                    upstreamRef: error.ref,
+                });
+                return withNoReferrer(previewInitialRouteErrorResponse(request, publicError));
+            }
+            throw error;
+        }
+        if (exchange.sessionId !== sessionId ||
+            exchange.grantId !== activation.grantId ||
+            exchange.previewOrigin !== requestOrigin ||
+            exchange.projectId !== (await getPreviewTransport()).projectId ||
+            exchange.grantExpiresAt <= Date.now()) {
+            return withNoReferrer(previewInitialRouteErrorResponse(request, {
+                status: 502, code: 'PREVIEW_GRANT_BINDING_MISMATCH', message: 'preview unavailable',
+                category: 'auth', recoverable: true, retryable: false,
+            }));
+        }
+        const cookie = buildPreviewGrantCookieFromActivation(exchange, Date.now(), resolveStorystickApplicationBuildId());
+        const draft = await draftMode();
+        draft.enable();
+        const finalUrl = scrubPreviewBootstrap(safeRedirect, requestOrigin);
+        finalUrl.searchParams.set(PREVIEW_SESSION_QUERY_PARAM, sessionId);
+        writePreviewScopeToSearchParams(finalUrl.searchParams, previewScope);
+        const response = NextResponse.redirect(finalUrl, { status: 302 });
+        const requestUrl = new URL(url.pathname + url.search, requestOrigin).toString();
+        if (previewCookieAttributes({ expiresIn: 0, requestUrl }).partitioned) {
+            // Draft Mode owns the build-bound value and cache semantics. Its cookie
+            // must travel in the same partition as the signed Storystick admission.
+            // Next exposes the freshly enabled cookie through this mutable store;
+            // response cookies take precedence when Next merges its Set-Cookie values.
+            const draftCookie = cookieStore.get('__prerender_bypass');
+            if (!draftCookie?.value) {
+                throw new Error('[storystick/preview] Draft Mode did not emit its cookie');
+            }
+            response.cookies.set({
+                ...draftCookie,
+                httpOnly: true,
+                secure: true,
+                sameSite: 'none',
+                partitioned: true,
+            });
+        }
+        primePreviewGrantAccess({ ...cookie, contentShapeCapability: exchange.contentShapeCapability,
+            admissionSequence: exchange.admissionSequence }, { ...scope, applicationBuildId: cookie.applicationBuildId });
+        await setPreviewGrantCookieOnResponse({
+            response, scope, reader: cookieStore, sequence: exchange.admissionSequence,
+            cookie,
+            requestUrl,
+            basePath,
+        });
+        response.headers.set('Cache-Control', 'no-store');
+        response.headers.set('Referrer-Policy', 'no-referrer');
+        return response;
+    };
+}
+function scrubPreviewBootstrap(path, requestOrigin) {
+    const result = new URL(path, requestOrigin);
+    result.searchParams.delete(PREVIEW_ACTIVATION_QUERY_PARAM);
+    result.searchParams.delete(PREVIEW_SESSION_QUERY_PARAM);
+    return result;
+}
+function withNoReferrer(response) {
+    response.headers.set('Referrer-Policy', 'no-referrer');
+    return response;
+}

package/dist/preview/route-provenance-runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `createStorystickPreviewProvenanceRuntimeHandler` — preview-only
+ * Overlay Frame source runtime route.
+ *
+ * Lower-level standalone factory. The recommended customer mount is
+ * `createRouteHandler()` at `app/api/storystick/[...action]/route.ts`.
+ * This factory still backs the `/api/storystick/provenance-runtime` action
+ * inside the one-file dispatcher:
+ *
+ *   // app/api/storystick/[...action]/route.ts
+ *   import { createRouteHandler } from '@storystick/next/preview'
+ *   const storystick = createRouteHandler()
+ *   export const GET = storystick.GET
+ *   export const POST = storystick.POST
+ *
+ * The handler lives under the existing server-only `@storystick/next/preview`
+ * subpath, not the root client-safe entry. It gates first, then dynamically
+ * imports the runtime script so customer static/client bundles do not carry
+ * provenance selectors or message strings.
+ */
+import type { NextRequest } from 'next/server';
+export interface PreviewProvenanceRuntimeHandlerOptions {
+    /**
+     * Optional server policy. Enabled by default for trusted Preview sessions.
+     */
+    enabled?: boolean | (() => boolean | Promise<boolean>);
+    /**
+     * Require a valid Storystick preview cookie before serving the runtime.
+     * Defaults to true. Fixture-only tests can set this to false when they do
+     * not run through the real Preview cookie exchange.
+     */
+    requirePreviewCookie?: boolean;
+}
+export declare function createStorystickPreviewProvenanceRuntimeHandler(options?: PreviewProvenanceRuntimeHandlerOptions): (request: NextRequest) => Promise<Response>;

package/dist/preview/route-provenance-runtime.js

@@ -0,0 +1,90 @@
+/**
+ * `createStorystickPreviewProvenanceRuntimeHandler` — preview-only
+ * Overlay Frame source runtime route.
+ *
+ * Lower-level standalone factory. The recommended customer mount is
+ * `createRouteHandler()` at `app/api/storystick/[...action]/route.ts`.
+ * This factory still backs the `/api/storystick/provenance-runtime` action
+ * inside the one-file dispatcher:
+ *
+ *   // app/api/storystick/[...action]/route.ts
+ *   import { createRouteHandler } from '@storystick/next/preview'
+ *   const storystick = createRouteHandler()
+ *   export const GET = storystick.GET
+ *   export const POST = storystick.POST
+ *
+ * The handler lives under the existing server-only `@storystick/next/preview`
+ * subpath, not the root client-safe entry. It gates first, then dynamically
+ * imports the runtime script so customer static/client bundles do not carry
+ * provenance selectors or message strings.
+ */
+import { cookies } from 'next/headers';
+import { getPreviewTransport } from "./internal.js";
+import { readPreviewGrantCookie } from '@storystick/preview/server/extract-token';
+import { resolvePreviewRequestOrigin } from './internal.js';
+import { unstable_resolveStorystickPreviewProvenanceConfig } from './provenance-config.js';
+export function createStorystickPreviewProvenanceRuntimeHandler(options = {}) {
+    return async function GET(request) {
+        if (!(await isEnabled(options.enabled)))
+            return notFound();
+        if (shouldRequirePreviewCookie(options.requirePreviewCookie)) {
+            const active = await hasValidPreviewGrant(request);
+            if (!active)
+                return notFound();
+        }
+        const { previewProvenanceRuntimeScript } = await import('@storystick/preview/provenance');
+        return new Response(previewProvenanceRuntimeScript, {
+            headers: runtimeHeaders(),
+        });
+    };
+}
+function shouldRequirePreviewCookie(option) {
+    if (typeof option === 'boolean')
+        return option;
+    return !unstable_resolveStorystickPreviewProvenanceConfig().fixtureEnabled;
+}
+async function isEnabled(gate) {
+    if (typeof gate === 'function')
+        return Boolean(await gate());
+    if (typeof gate === 'boolean')
+        return gate;
+    return true;
+}
+async function hasValidPreviewGrant(request) {
+    try {
+        const cookieStore = await cookies();
+        const grant = await readPreviewGrantCookie(cookieStore, { ...await getPreviewTransport(), requestOrigin: resolvePreviewRequestOrigin(request) });
+        if (!grant)
+            return false;
+        if (grant.previewOrigin !== resolvePreviewRequestOrigin(request))
+            return false;
+        // The origin-bound, HttpOnly preview cookie is the authority for this
+        // runtime. Requiring Next's separate Draft Mode cookie here makes the
+        // reporter depend on an implementation detail of the redirect response:
+        // in local production lanes that cookie is not retained, even while the
+        // verified preview cookie and the authenticated iframe session are live.
+        // Serving this script cannot grant preview access on its own; every
+        // privileged path still validates the same preview cookie/server token.
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function runtimeHeaders() {
+    return {
+        'Cache-Control': 'no-store',
+        'Content-Type': 'application/javascript; charset=utf-8',
+        'X-Content-Type-Options': 'nosniff',
+        'X-Robots-Tag': 'noindex, nofollow, noarchive',
+    };
+}
+function notFound() {
+    return new Response('Not found', {
+        status: 404,
+        headers: {
+            'Cache-Control': 'no-store',
+            'X-Robots-Tag': 'noindex, nofollow, noarchive',
+        },
+    });
+}

package/dist/preview/route-token.d.ts

@@ -0,0 +1,6 @@
+/** Read the installed admission; credential renewal never overwrites it. */
+import type { NextRequest } from 'next/server';
+export interface PreviewTokenHandlerOptions {
+    basePath?: string;
+}
+export declare function createStorystickPreviewTokenHandler(options?: PreviewTokenHandlerOptions): (request: NextRequest) => Promise<Response>;

package/dist/preview/route-token.js

@@ -0,0 +1,46 @@
+import { NextResponse } from 'next/server';
+import { cookies, draftMode } from 'next/headers';
+import { PREVIEW_SESSION_QUERY_PARAM } from '@storystick/preview/identity';
+import { isSafePreviewSessionId } from '@storystick/preview/server/grant';
+import { resolveStorystickApplicationBuildId } from '../code-version.js';
+import { createPreviewControlClient, getPreviewTransport, resolvePreviewRequestOrigin } from './internal.js';
+import { resolvePreviewGrantAccess } from '@storystick/preview/server/extract-token';
+import { prunePreviewAdmissionCookies } from '@storystick/preview/server/route-session-cookie';
+import { previewControlErrorResponse, previewErrorResponse } from './route-errors.js';
+export function createStorystickPreviewTokenHandler(options = {}) {
+    return async function POST(request) {
+        const sessionId = request.nextUrl.searchParams.get(PREVIEW_SESSION_QUERY_PARAM);
+        if (!isSafePreviewSessionId(sessionId))
+            return previewErrorResponse(400, 'PREVIEW_SESSION_MISSING', 'Preview session selector is required.');
+        const requestOrigin = resolvePreviewRequestOrigin(request);
+        if (request.headers.get('origin') !== requestOrigin)
+            return previewErrorResponse(403, 'PREVIEW_ORIGIN_MISMATCH', 'A same-origin Preview request is required.');
+        try {
+            const transport = await getPreviewTransport();
+            const reader = await cookies();
+            const scope = { ...transport, requestOrigin };
+            const now = Date.now();
+            const fields = await resolvePreviewGrantAccess(reader, { ...scope, applicationBuildId: resolveStorystickApplicationBuildId(), now });
+            if (fields === null)
+                return previewErrorResponse(401, 'PREVIEW_CONTEXT_ENDED', 'Preview has been closed.');
+            if (!fields)
+                return previewErrorResponse(401, 'PREVIEW_GRANT_MISSING', 'Open Preview from Studio again.');
+            if (process.env.NODE_ENV === 'production' && !process.env.STORYSTICK_LANE_ID && !(await draftMode()).isEnabled) {
+                return previewErrorResponse(409, 'CONTENT_SHAPE_RELOAD_REQUIRED', 'Reopen Preview from Studio after the site deployment changed.');
+            }
+            const client = await createPreviewControlClient(fields.token);
+            await client.context({ sessionId });
+            const remainingMs = Math.max(0, fields.tokenExpiresAt - now);
+            const response = NextResponse.json({ token: fields.token, expiresAt: fields.tokenExpiresAt,
+                refreshAfter: now + Math.max(1000, Math.floor(remainingMs * 0.8)), sessionId, projectId: fields.projectId }, { headers: { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' } });
+            // Safe even if this response arrives after a newer activation: all deletions
+            // have lower sequence AND were observed in this particular request.
+            prunePreviewAdmissionCookies({ response, reader, scope, requestUrl: requestOrigin + request.nextUrl.pathname,
+                basePath: options.basePath ?? '' }, fields.admissionSequence);
+            return response;
+        }
+        catch (error) {
+            return previewControlErrorResponse(error);
+        }
+    };
+}

package/dist/preview/server-preview-internals.d.ts

@@ -0,0 +1,3 @@
+export { unstable_createPreviewReadIdentityTransport as createPreviewReadIdentityTransport, } from '@storystick/preview/server/read-identity';
+export { unstable_resolveStorystickPreviewProvenanceConfig as resolvePreviewProvenanceConfig, unstable_resolveStorystickPreviewProvenanceManifest as resolvePreviewProvenanceManifest, } from './provenance-config.js';
+export { unstable_attachPreviewRouteMetadataContext as attachPreviewRouteMetadataContext, unstable_attachPreviewRouteRenderContext as attachPreviewRouteRenderContext, unstable_buildPreviewRouteDocumentFrame as buildPreviewRouteDocumentFrame, unstable_collectPreviewRouteDocumentSliceTypes as collectPreviewRouteDocumentSliceTypes, } from './route-document-provenance.js';

package/dist/preview/server-preview-internals.js

@@ -0,0 +1,3 @@
+export { unstable_createPreviewReadIdentityTransport as createPreviewReadIdentityTransport, } from '@storystick/preview/server/read-identity';
+export { unstable_resolveStorystickPreviewProvenanceConfig as resolvePreviewProvenanceConfig, unstable_resolveStorystickPreviewProvenanceManifest as resolvePreviewProvenanceManifest, } from './provenance-config.js';
+export { unstable_attachPreviewRouteMetadataContext as attachPreviewRouteMetadataContext, unstable_attachPreviewRouteRenderContext as attachPreviewRouteRenderContext, unstable_buildPreviewRouteDocumentFrame as buildPreviewRouteDocumentFrame, unstable_collectPreviewRouteDocumentSliceTypes as collectPreviewRouteDocumentSliceTypes, } from './route-document-provenance.js';

package/dist/preview/slice-locale.d.ts

@@ -0,0 +1,5 @@
+import 'server-only';
+import type { ReactNode } from 'react';
+import type { PreviewSliceScopeInvocation } from '@storystick/react/internal/preview-provenance';
+export declare function readNativeSliceLocale(): Promise<string | undefined>;
+export declare function runNativeSlice(input: PreviewSliceScopeInvocation): Promise<ReactNode>;

package/dist/preview/slice-locale.js

@@ -0,0 +1,15 @@
+import 'server-only';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readContentOrigin } from '@storystick/client/internal';
+import { readDocumentLocaleRouting } from '@storystick/client/locale-routing';
+// Framework adapter only: an async slice inherits its explicit document locale.
+// No query collection or render boundary is attached to the component.
+const localeScope = new AsyncLocalStorage();
+export async function readNativeSliceLocale() {
+    return localeScope.getStore();
+}
+export async function runNativeSlice(input) {
+    const origin = readContentOrigin(input.props.slice);
+    const locale = readDocumentLocaleRouting(origin?._localeRouting)?.locale;
+    return localeScope.run(locale, () => input.component(input.props));
+}

package/dist/preview-error-surface.d.ts

@@ -0,0 +1,7 @@
+export interface PreviewErrorSurfaceProps {
+    code?: string | null;
+    studioUrl?: string | null;
+}
+/** A terminal Preview state owns its viewport, without changing customer DOM.
+ * Isolate product styling from the customer's page and its error boundary. */
+export declare function PreviewErrorSurface({ code, studioUrl }: PreviewErrorSurfaceProps): import("react").JSX.Element;

package/dist/preview-error-surface.js

@@ -0,0 +1,20 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { lookupSdkCopy } from '@storystick/preview/sdk-error-copy';
+import { PreviewPageState } from '@storystick/react/internal/preview-page-state';
+/** A terminal Preview state owns its viewport, without changing customer DOM.
+ * Isolate product styling from the customer's page and its error boundary. */
+export function PreviewErrorSurface({ code, studioUrl }) {
+    const copy = lookupSdkCopy(code);
+    const host = useRef(null);
+    const [root, setRoot] = useState(null);
+    useEffect(() => {
+        if (host.current)
+            setRoot(host.current.shadowRoot ?? host.current.attachShadow({ mode: 'open' }));
+    }, []);
+    return _jsx("div", { ref: host, "data-storystick-preview-error": "", "data-storystick-preview-controls": "", style: {
+            all: 'initial', position: 'fixed', inset: 0, zIndex: 2147483646, background: '#fff',
+        }, children: root ? createPortal(_jsx(PreviewPageState, { title: copy.title, description: copy.body, role: "alert", actions: studioUrl ? _jsx("a", { "data-ss-preview-page-action": "", href: studioUrl, children: "Return to Studio" }) : null, children: code || copy.commonCauses.length ? _jsxs("details", { children: [_jsx("summary", { children: "Technical details" }), code ? _jsx("pre", { children: code }) : null, copy.commonCauses.length ? _jsx("ul", { style: { textAlign: 'left', paddingLeft: 18 }, children: copy.commonCauses.map(cause => _jsx("li", { children: cause }, cause)) }) : null] }) : null }), root) : null });
+}

package/dist/preview-exit.d.ts

@@ -0,0 +1,7 @@
+import { type PreviewReadContext } from '@storystick/types/preview-query-targeting';
+type DisablePreviewResult = 'disabled' | 'conflict';
+/** Shared same-origin exit contract for user controls and observed context end. */
+export declare function disablePreview(url: string, context: PreviewReadContext | null, contextUrl?: string): Promise<DisablePreviewResult>;
+export declare function hasPendingPreviewExit(url: string, context: PreviewReadContext | null): boolean;
+export declare function publicPreviewLocation(href: string): string;
+export {};

package/dist/preview-exit.js

@@ -0,0 +1,71 @@
+import { readStandalonePreviewSessionId } from '@storystick/preview/identity/browser-context';
+import { isPreviewReadContext } from '@storystick/types/preview-query-targeting';
+const activeDisableRequests = new Map();
+function previewExitKey(url, context, contextUrl) {
+    return JSON.stringify([url, context?.contextId ?? null, context?.revision ?? null, context ? null : contextUrl ?? null]);
+}
+/** Shared same-origin exit contract for user controls and observed context end. */
+export function disablePreview(url, context, contextUrl) {
+    const key = previewExitKey(url, context, contextUrl);
+    const activeRequest = activeDisableRequests.get(key);
+    if (activeRequest)
+        return activeRequest;
+    const request = requestPreviewDisable(url, context, contextUrl);
+    activeDisableRequests.set(key, request);
+    void request.finally(() => {
+        if (activeDisableRequests.get(key) === request)
+            activeDisableRequests.delete(key);
+    }).catch(() => undefined);
+    return request;
+}
+export function hasPendingPreviewExit(url, context) {
+    return activeDisableRequests.has(previewExitKey(url, context));
+}
+async function requestPreviewDisable(url, context, contextUrl) {
+    if (!context && contextUrl) {
+        const sessionId = readStandalonePreviewSessionId();
+        const addressedUrl = new URL(contextUrl, window.location.origin);
+        if (sessionId)
+            addressedUrl.searchParams.set('_ss_session', sessionId);
+        const observed = await fetch(addressedUrl.pathname + addressedUrl.search, { credentials: 'same-origin', cache: 'no-store', signal: AbortSignal.timeout(10000) });
+        if (observed.ok) {
+            const result = await observed.json();
+            if (!result || typeof result !== 'object' || !('context' in result) || !isPreviewReadContext(result.context))
+                throw new Error('Preview context unavailable');
+            context = result.context;
+        }
+        else if (observed.status !== 401 && observed.status !== 403) {
+            const failure = await observed.json().catch(() => null);
+            // An expired view or changed build can be left locally. Never replace it
+            // with another window's context merely to issue an Exit command.
+            if (!failure || typeof failure !== 'object' || !('error' in failure) ||
+                !failure.error || typeof failure.error !== 'object' || !('code' in failure.error) ||
+                !['CONTENT_SHAPE_RELOAD_REQUIRED', 'PREVIEW_VIEW_UNAVAILABLE', 'PREVIEW_CONTEXT_INVALID'].includes(String(failure.error.code)))
+                throw new Error('Preview context unavailable');
+        }
+    }
+    const response = await fetch(url, {
+        method: 'POST', credentials: 'same-origin', cache: 'no-store', signal: AbortSignal.timeout(10000),
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+        body: JSON.stringify(context ? {
+            commandId: `leave_${context.contextId}_${context.revision}`,
+            expectedContextId: context.contextId, expectedRevision: context.revision, perspective: null,
+        } : {}),
+    });
+    if (response.status === 409)
+        return 'conflict';
+    if (!response.ok)
+        throw new Error('Preview exit unavailable');
+    const result = await response.json();
+    if (!result || typeof result !== 'object' || !('status' in result) || result.status !== 'disabled') {
+        throw new Error('Preview exit unavailable');
+    }
+    return 'disabled';
+}
+export function publicPreviewLocation(href) {
+    const url = new URL(href);
+    for (const name of [...url.searchParams.keys()])
+        if (name.startsWith('_ss_'))
+            url.searchParams.delete(name);
+    return url.pathname + url.search + url.hash;
+}

package/dist/preview-metadata.d.ts

@@ -0,0 +1,15 @@
+import type { Metadata } from 'next';
+type EnvLike = Record<string, string | undefined>;
+export interface StorystickPreviewRobotsOptions {
+    readonly enabled?: boolean;
+    readonly env?: EnvLike;
+}
+export declare const STORYSTICK_PREVIEW_ROBOTS: {
+    readonly index: false;
+    readonly follow: false;
+    readonly noarchive: true;
+};
+/** Internal legacy configuration used by the render adapter; not an application flag. */
+export declare function isStorystickPreviewProvenanceEnabled(env?: EnvLike): boolean;
+export declare function storystickPreviewRobots(options?: StorystickPreviewRobotsOptions): Metadata['robots'] | undefined;
+export {};

package/dist/preview-metadata.js

@@ -0,0 +1,13 @@
+export const STORYSTICK_PREVIEW_ROBOTS = {
+    index: false, follow: false, noarchive: true,
+};
+/** Internal legacy configuration used by the render adapter; not an application flag. */
+export function isStorystickPreviewProvenanceEnabled(env = defaultEnv()) {
+    return env.STORYSTICK_PREVIEW_PROVENANCE === '1';
+}
+export function storystickPreviewRobots(options = {}) {
+    return (options.enabled ?? isStorystickPreviewProvenanceEnabled(options.env)) ? { ...STORYSTICK_PREVIEW_ROBOTS } : undefined;
+}
+function defaultEnv() {
+    return typeof process === 'undefined' ? {} : process.env;
+}

package/dist/preview-mode-latch.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Preview identity latch (ADR-113 D2 + follow-up).
+ *
+ * Both customer SDK hooks (`useStorystickPreviewNavigation` and
+ * `useStorystickPreviewLocation`) plus the forward-path session
+ * preservation in `preview-nav.ts` need a stable answer to two
+ * questions:
+ *
+ *   1. *"Is this page running inside a Storystick preview iframe?"*
+ *      (boolean — gates whether to register handlers)
+ *   2. *"What is the active `_ss_session` identifier?"*
+ *      (string — appended to Studio-dispatched destinations so
+ *      subsequent App Router navigates stay inside the preview
+ *      session)
+ *
+ * The original heuristic — re-derive from `window.location.search` on
+ * every render — breaks the moment the customer's own intra-iframe
+ * nav drops `_ss_session` from the URL: the gate flips to false (PR5
+ * fix), and the destination injection loses the marker (this fix).
+ *
+ *   t0 boot:    /?_ss_session=X    → active=true,  sessionId=X
+ *   t1 nav:     /pricing           → active=true,  sessionId=X (cached)
+ *   t2 onward:  /pricing           → active=true,  sessionId=X (cached)
+ *
+ * The latch lives on `globalThis` (not module scope) so it survives
+ * HMR: Next/Fast Refresh re-evaluates modules but never replaces the
+ * `globalThis` object, so a module-scope `let` would be lost on HMR
+ * while a `globalThis.__storystick_preview_mode_latched__` write is
+ * preserved by construction.
+ *
+ * **Backward-compatible shape**: `sessionId` is OPTIONAL on the
+ * stored object. An older `@storystick/next` version that wrote just
+ * `{ active }` (pre-follow-up) is read by the new code as
+ * `existing.sessionId === undefined` — the new code then runs
+ * opportunistic backfill: if the URL currently has `_ss_session`, it
+ * upgrades the in-place latch object so subsequent reads pick up the
+ * id. Symmetric direction (new writer / old reader) is trivially
+ * safe — the old reader only ever inspected `.active`.
+ *
+ * **Why not bump the namespace key**: two `@storystick/next` versions
+ * in the same process MUST share the active-preview decision (the
+ * gate). Bumping the key would partition the gate too, reintroducing
+ * the pre-PR5 bug for the older copy. Codex R4 follow-up consult
+ * 2026-05-14: keep namespace, extend shape.
+ *
+ * **Tri-state via object presence**: a raw boolean cannot distinguish
+ * "latched and false" from "not latched yet". The `PreviewLatch`
+ * object is the sentinel: `existing !== undefined` means latched
+ * (active or not); the boolean inside carries the decision.
+ *
+ * **Namespace stability**: `__storystick_preview_mode_latched__` is
+ * the single, underscore-prefixed key. The literal-string grep test
+ * in `preview-mode-latch.test.ts` pins it; do not rename even if
+ * "mode" is now an under-description (the latch carries identity too).
+ */
+interface PreviewLatch {
+    active: boolean;
+    /**
+     * Captured `_ss_session` value from the URL at boot. `null` when
+     * the page is not in preview mode (top-level) or when the latch
+     * was written by an old SDK version that did not yet track the
+     * session id. New SDK code opportunistically backfills this field
+     * via `isPreviewModeLatched()` when the URL still carries the
+     * param — see "Backward-compatible shape" above.
+     */
+    sessionId?: string | null;
+    /**
+     * Captured `_ss_variant` URL override for this iframe. This is not
+     * preview identity; it is a per-iframe read-scope override.
+     */
+    variantId?: string | null;
+    /** Captured `_ss_release` per-iframe read-scope override. */
+    releaseId?: string | null;
+}
+declare global {
+    var __storystick_preview_mode_latched__: PreviewLatch | undefined;
+}
+import { type PreviewScope } from '@storystick/preview/identity';
+/**
+ * Return whether the current page is running inside a Storystick
+ * preview iframe. Latches on first valid call: subsequent calls return
+ * the cached value even after the URL drops `_ss_session` (customer
+ * intra-iframe nav).
+ *
+ * Also performs opportunistic sessionId backfill: if the existing
+ * latch is missing `sessionId` (either old SDK shape or first mount
+ * happened mid-customer-nav) AND the URL currently carries
+ * `_ss_session`, the value is written into the latch in place so
+ * `getLatchedPreviewSessionId()` returns it on subsequent calls.
+ *
+ * SSR / no-`window` calls return false without latching — they cannot
+ * know yet, and we must not freeze the wrong answer for the eventual
+ * client hydration.
+ */
+export declare function isPreviewModeLatched(): boolean;
+/**
+ * Return the latched `_ss_session` identifier. `null` when the latch
+ * has not run, the page is not in preview mode, or the latch was
+ * captured before the param was available (an old SDK version, or a
+ * first read that happened mid-customer-nav).
+ *
+ * Callers in the SDK forward path (`preservePreviewSession`) use this
+ * as the primary source over `window.location.search`: the latch is
+ * Studio-authoritative (set at boot from the URL Studio constructed),
+ * while the live URL is customer-mutable surface that intra-iframe
+ * nav routinely strips.
+ *
+ * The caller is responsible for invoking `isPreviewModeLatched()`
+ * first (or otherwise gating on preview mode) before consuming this
+ * value — outside preview the latch is never written and this
+ * returns `null` unconditionally.
+ */
+export declare function getLatchedPreviewSessionId(): string | null;
+export declare function readPreviewSessionIdForNavigation(): string | null;
+export declare function readPreviewVariantIdForNavigation(): string | null;
+export declare function readPreviewReleaseIdForNavigation(): string | null;
+/**
+ * Replace the latched request scope after a trusted Studio navigation.
+ * Living scope deliberately clears both selectors so a later customer-side
+ * navigation cannot resurrect an older variant or release from the boot URL.
+ */
+export declare function setLatchedPreviewScope(scope: PreviewScope): void;
+/**
+ * Test-only reset. Vitest's module isolation re-imports modules between
+ * tests but `globalThis` is shared across the suite, so a latch set in
+ * test A would leak into test B. Tests call this in `beforeEach` to
+ * start each case with a fresh latch.
+ *
+ * Production code MUST NOT call this — clearing the latch reintroduces
+ * the very bug it exists to prevent.
+ */
+export declare function _resetPreviewModeLatchForTests(): void;
+export {};