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

package/dist/preview/provenance-frame-builder.d.ts

@@ -0,0 +1,6 @@
+import 'server-only';
+import { type PreviewProvenanceRuntime } from './provenance-runtime-adapter.js';
+import { type BuildPreviewProvenanceFrameOptions, type BuildPreviewProvenanceFrameResult } from '@storystick/preview/server/provenance-frame-builder';
+export * from '@storystick/preview/server/provenance-frame-builder';
+export declare function buildPreviewProvenanceFrame(options: BuildPreviewProvenanceFrameOptions): Promise<BuildPreviewProvenanceFrameResult | null>;
+export declare function buildPreviewProvenanceFrameWithRuntime(options: BuildPreviewProvenanceFrameOptions, injectedRuntime?: PreviewProvenanceRuntime): Promise<BuildPreviewProvenanceFrameResult | null>;

package/dist/preview/provenance-frame-builder.js

@@ -0,0 +1,10 @@
+import 'server-only';
+import { resolvePreviewProvenanceRuntime } from './provenance-runtime-adapter.js';
+import { buildPreviewProvenanceFrameWithRuntime as sharedBuildProvenance } from '@storystick/preview/server/provenance-frame-builder';
+export * from '@storystick/preview/server/provenance-frame-builder';
+export async function buildPreviewProvenanceFrame(options) {
+    return buildPreviewProvenanceFrameWithRuntime(options);
+}
+export async function buildPreviewProvenanceFrameWithRuntime(options, injectedRuntime) {
+    return sharedBuildProvenance(options, resolvePreviewProvenanceRuntime(injectedRuntime));
+}

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

@@ -0,0 +1,5 @@
+import 'server-only';
+export interface MarkStorystickPreviewProvenanceNoStoreOptions {
+    readonly enabled?: boolean;
+}
+export declare function markStorystickPreviewProvenanceNoStore(options?: MarkStorystickPreviewProvenanceNoStoreOptions): void;

package/dist/preview/provenance-response.js

@@ -0,0 +1,9 @@
+import 'server-only';
+import { unstable_noStore } from 'next/cache';
+import { isStorystickPreviewProvenanceEnabled } from '../preview-metadata.js';
+export function markStorystickPreviewProvenanceNoStore(options = {}) {
+    const enabled = options.enabled ?? isStorystickPreviewProvenanceEnabled();
+    if (!enabled)
+        return;
+    unstable_noStore();
+}

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

@@ -0,0 +1,9 @@
+import 'server-only';
+import type { QuerySchemaDefinition } from '@storystick/client';
+import type { PreviewProvenanceEditableTextPathManifest } from '@storystick/preview/provenance';
+export type * from '@storystick/preview/server/provenance-runtime';
+export { createPreviewProvenanceTemporalIdentity, bindPreviewRuntimeToReads, previewRuntimeForReads, bindPreviewRuntimeToSidecar, previewRuntimeForSidecar, previewRuntimeForSchema } from '@storystick/preview/server/provenance-runtime';
+import { type PreviewProvenanceRuntime } from '@storystick/preview/server/provenance-runtime';
+export declare const defaultPreviewProvenanceRuntime: PreviewProvenanceRuntime;
+export declare function resolvePreviewProvenanceRuntime(runtime: PreviewProvenanceRuntime | undefined): PreviewProvenanceRuntime;
+export declare function bindSiteQuerySchema<TSchema extends QuerySchemaDefinition>(schema: TSchema, manifest: PreviewProvenanceEditableTextPathManifest): TSchema;

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

@@ -0,0 +1,42 @@
+import 'server-only';
+import { resolveStorystickServerCodeVersion, } from '../code-version.js';
+import { readPreviewProvenanceSessionId, resolvePreviewProvenanceRouteIdentity, } from './preview-request-identity.js';
+import { unstable_resolveStorystickPreviewProvenanceConfig, } from './provenance-config.js';
+import { markStorystickPreviewProvenanceNoStore } from './provenance-response.js';
+export { createPreviewProvenanceTemporalIdentity, bindPreviewRuntimeToReads, previewRuntimeForReads, bindPreviewRuntimeToSidecar, previewRuntimeForSidecar, previewRuntimeForSchema } from '@storystick/preview/server/provenance-runtime';
+import { bindPreviewRuntimeToSchema, createDefaultPreviewProvenanceTemporalIdentity } from '@storystick/preview/server/provenance-runtime';
+export const defaultPreviewProvenanceRuntime = {
+    config: {
+        isEnabled: () => process.env.STORYSTICK_PREVIEW_PROVENANCE === '1',
+        isProduction: () => process.env.NODE_ENV === 'production',
+        resolveCodeVersion: (options = {}) => resolveStorystickServerCodeVersion(options),
+        resolveSemanticConfig: () => unstable_resolveStorystickPreviewProvenanceConfig(),
+        resolveSemanticManifest: async () => ({}),
+    },
+    recorder: {
+        markNoStore: markStorystickPreviewProvenanceNoStore,
+        readSessionId: readPreviewProvenanceSessionId,
+        resolveRouteIdentity: resolvePreviewProvenanceRouteIdentity,
+    },
+    transport: {
+        createTemporalIdentity: createDefaultPreviewProvenanceTemporalIdentity,
+    },
+};
+export function resolvePreviewProvenanceRuntime(runtime) {
+    return runtime ?? defaultPreviewProvenanceRuntime;
+}
+export function bindSiteQuerySchema(schema, manifest) {
+    const boundSchema = Object.freeze({ ...schema });
+    const runtime = {
+        ...defaultPreviewProvenanceRuntime,
+        config: {
+            ...defaultPreviewProvenanceRuntime.config,
+            isEnabled: () => true,
+            resolveSemanticConfig: () => ({ enabled: true, fixtureEnabled: false, sessionId: '',
+                codeVersion: resolveStorystickServerCodeVersion(), fixture: null }),
+            resolveSemanticManifest: async () => manifest,
+        },
+    };
+    bindPreviewRuntimeToSchema(boundSchema, runtime);
+    return boundSchema;
+}

package/dist/preview/render-frame-provenance.d.ts

@@ -0,0 +1,23 @@
+import 'server-only';
+import { type ReactElement, type ReactNode } from 'react';
+import { type PreviewProvenanceRuntime } from './provenance-runtime-adapter.js';
+import { type PreviewRenderFrame, type BuildPreviewRenderFrameOptions, type BuildPreviewDocumentRenderFrameFromReadsOptions, type PreviewDocumentRenderFrame } from '@storystick/preview/server/render-frame-provenance';
+export * from '@storystick/preview/server/render-frame-provenance';
+export interface unstable_StorystickRenderFrameProps {
+    readonly frame: Pick<PreviewRenderFrame, 'frameId' | 'sessionId' | 'publicSidecar'> | null | undefined;
+    readonly attrs?: Readonly<Record<string, string>>;
+    readonly children: ReactNode;
+}
+export interface RenderPreviewScopeFromReadsOptions<TContext = unknown> extends Omit<BuildPreviewDocumentRenderFrameFromReadsOptions<TContext>, 'frameId' | 'routeHash'> {
+    readonly frameId?: string;
+    readonly routeHash?: string;
+    readonly attrs?: Readonly<Record<string, string>>;
+    readonly render: (context: TContext) => ReactNode | Promise<ReactNode>;
+}
+export declare function unstable_StorystickRenderFrame({ frame, attrs, children, }: unstable_StorystickRenderFrameProps): ReactElement;
+export declare function unstable_renderPreviewScopeFromReads<TContext = unknown>(options: RenderPreviewScopeFromReadsOptions<TContext>): Promise<ReactElement>;
+export declare function unstable_renderPreviewScopeFromReadsWithRuntime<TContext = unknown>(options: RenderPreviewScopeFromReadsOptions<TContext>, injectedRuntime?: PreviewProvenanceRuntime): Promise<ReactElement>;
+export declare function unstable_buildPreviewRenderFrame<TDocument = unknown, TContext = unknown>(options: BuildPreviewRenderFrameOptions<TDocument, TContext>): Promise<PreviewRenderFrame<TDocument, TContext> | null>;
+export declare function unstable_buildPreviewRenderFrameWithRuntime<TDocument = unknown, TContext = unknown>(options: BuildPreviewRenderFrameOptions<TDocument, TContext>, injectedRuntime?: PreviewProvenanceRuntime): Promise<PreviewRenderFrame<TDocument, TContext> | null>;
+export declare function unstable_buildPreviewDocumentRenderFrameFromReads<TContext = unknown>(options: BuildPreviewDocumentRenderFrameFromReadsOptions<TContext>): Promise<PreviewDocumentRenderFrame<TContext> | null>;
+export declare function unstable_buildPreviewDocumentRenderFrameFromReadsWithRuntime<TContext = unknown>(options: BuildPreviewDocumentRenderFrameFromReadsOptions<TContext>, injectedRuntime?: PreviewProvenanceRuntime): Promise<PreviewDocumentRenderFrame<TContext> | null>;

package/dist/preview/render-frame-provenance.js

@@ -0,0 +1,47 @@
+import 'server-only';
+import { createElement, Fragment } from 'react';
+import { PreviewProvenanceSidecar } from '@storystick/react/internal/preview-provenance';
+import { createPreviewOccurrenceId } from '@storystick/preview/server/render-id';
+import { resolvePreviewProvenanceRuntime } from './provenance-runtime-adapter.js';
+import { unstable_buildPreviewRenderFrameWithRuntime as sharedBuildFrame, unstable_buildPreviewDocumentRenderFrameFromReadsWithRuntime as sharedBuildReads } from '@storystick/preview/server/render-frame-provenance';
+export * from '@storystick/preview/server/render-frame-provenance';
+export function unstable_StorystickRenderFrame({ frame, attrs, children, }) {
+    const content = attrs === undefined
+        ? children
+        : createElement('div', attrs, children);
+    return createElement(Fragment, null, frame
+        ? createElement(PreviewProvenanceSidecar, {
+            frameId: frame.frameId,
+            sessionId: frame.sessionId,
+            sidecar: frame.publicSidecar,
+        })
+        : null, content);
+}
+export async function unstable_renderPreviewScopeFromReads(options) {
+    return unstable_renderPreviewScopeFromReadsWithRuntime(options);
+}
+export async function unstable_renderPreviewScopeFromReadsWithRuntime(options, injectedRuntime) {
+    const runtime = resolvePreviewProvenanceRuntime(injectedRuntime);
+    const { attrs, render, ...frameOptions } = options;
+    const frameId = frameOptions.frameId ?? createPreviewOccurrenceId();
+    const frame = await unstable_buildPreviewDocumentRenderFrameFromReadsWithRuntime({
+        ...frameOptions,
+        frameId,
+        routeHash: frameOptions.routeHash ?? `occurrence:${frameId}`,
+    }, runtime);
+    const context = (frame?.codedContext ?? frameOptions.context);
+    const children = await render(context);
+    return unstable_StorystickRenderFrame({ frame, attrs, children });
+}
+export async function unstable_buildPreviewRenderFrame(options) {
+    return unstable_buildPreviewRenderFrameWithRuntime(options);
+}
+export async function unstable_buildPreviewRenderFrameWithRuntime(options, injectedRuntime) {
+    return sharedBuildFrame(options, resolvePreviewProvenanceRuntime(injectedRuntime));
+}
+export async function unstable_buildPreviewDocumentRenderFrameFromReads(options) {
+    return unstable_buildPreviewDocumentRenderFrameFromReadsWithRuntime(options);
+}
+export async function unstable_buildPreviewDocumentRenderFrameFromReadsWithRuntime(options, injectedRuntime) {
+    return sharedBuildReads(options, resolvePreviewProvenanceRuntime(injectedRuntime));
+}

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

@@ -0,0 +1,3 @@
+/** Same-origin elevation from an active PreviewGrant to a bounded write admission. */
+import type { NextRequest } from 'next/server';
+export declare function createStorystickPreviewAuthoringHandler(): (request: NextRequest) => Promise<Response>;

package/dist/preview/route-authoring.js

@@ -0,0 +1,80 @@
+/** Same-origin elevation from an active PreviewGrant to a bounded write admission. */
+import { NextResponse } from 'next/server';
+import { cookies } from 'next/headers';
+import { PreviewGrantExchangeError, classifyPreviewGrantError, exchangePreviewAuthoringAdmissionForServer, } from '@storystick/preview/server/grant';
+import { resolveStorystickApplicationBuildId } from '../code-version.js';
+import { getPreviewTransport, resolvePreviewRequestOrigin } from './internal.js';
+import { readPreviewGrantCookie } from '@storystick/preview/server/extract-token';
+import { previewControlErrorResponse, previewErrorResponse, } from './route-errors.js';
+export function createStorystickPreviewAuthoringHandler() {
+    return async function POST(request) {
+        const requestOrigin = resolvePreviewRequestOrigin(request);
+        if (request.headers.get('origin') !== requestOrigin) {
+            return previewErrorResponse(403, 'PREVIEW_ORIGIN_MISMATCH', 'A same-origin Preview request is required.', { category: 'auth', recoverable: true });
+        }
+        let renewal;
+        try {
+            renewal = parseRenewal(await request.json());
+        }
+        catch {
+            return previewErrorResponse(400, 'PREVIEW_AUTHORING_REQUEST_INVALID', 'The authoring request is invalid.', { category: 'validation' });
+        }
+        try {
+            const transport = await getPreviewTransport();
+            const scope = { ...transport, requestOrigin };
+            const admission = await readPreviewGrantCookie(await cookies(), scope);
+            if (admission === null) {
+                return previewErrorResponse(401, 'PREVIEW_CONTEXT_ENDED', 'Preview has been closed.', { category: 'auth', recoverable: true });
+            }
+            if (!admission) {
+                return previewErrorResponse(401, 'PREVIEW_GRANT_MISSING', 'Open Preview from Studio again.', { category: 'auth', recoverable: true });
+            }
+            const applicationBuildId = resolveStorystickApplicationBuildId();
+            if (admission.applicationBuildId !== applicationBuildId) {
+                return previewErrorResponse(409, 'CONTENT_SHAPE_RELOAD_REQUIRED', 'Reopen Preview from Studio after the site deployment changed.', { category: 'conflict', recoverable: true });
+            }
+            const result = await exchangePreviewAuthoringAdmissionForServer({
+                endpoint: transport.endpoint,
+                apiKey: transport.apiKey,
+                applicationBuildId,
+                grantToken: admission.grantToken,
+                requestOrigin,
+                contentShapeCapability: admission.contentShapeCapability,
+                ...renewal,
+            });
+            if (result.projectShortId !== transport.projectId) {
+                return previewErrorResponse(403, 'PREVIEW_PROJECT_MISMATCH', 'This site is configured for a different Storystick project.', { category: 'auth', recoverable: true });
+            }
+            return NextResponse.json(result, {
+                headers: {
+                    'Cache-Control': 'private, no-store',
+                    'X-Content-Type-Options': 'nosniff',
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof PreviewGrantExchangeError) {
+                return previewErrorResponse(classifyPreviewGrantError(error, 'authoring'));
+            }
+            return previewControlErrorResponse(error);
+        }
+    };
+}
+function parseRenewal(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error();
+    const body = value;
+    const admissionId = optionalId(body.admissionId);
+    const fileDelegationId = optionalId(body.fileDelegationId);
+    if (Boolean(admissionId) !== Boolean(fileDelegationId))
+        throw new Error();
+    return admissionId ? { admissionId, fileDelegationId } : {};
+}
+function optionalId(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0 || value.length > 256) {
+        throw new Error();
+    }
+    return value;
+}

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

@@ -0,0 +1,3 @@
+/** Shared Preview commands stay inside the existing customer-site dispatcher. */
+import type { NextRequest } from 'next/server';
+export declare function handlePreviewContext(request: NextRequest): Promise<Response>;

package/dist/preview/route-context.js

@@ -0,0 +1,38 @@
+import { NextResponse } from 'next/server';
+import { cookies } from 'next/headers';
+import { createPreviewControlClient, getPreviewTransport, resolvePreviewRequestOrigin } from './internal.js';
+import { resolvePreviewGrantAccess } from '@storystick/preview/server/extract-token';
+import { resolveStorystickApplicationBuildId } from '../code-version.js';
+import { readPreviewContextCommand } from '@storystick/preview/server/read-context-command';
+import { previewControlErrorResponse, previewErrorResponse } from './route-errors.js';
+export async function handlePreviewContext(request) {
+    const requestOrigin = resolvePreviewRequestOrigin(request);
+    if (request.method === 'POST' && request.headers.get('origin') !== requestOrigin) {
+        return previewErrorResponse(403, 'PREVIEW_ORIGIN_MISMATCH', 'A same-origin Preview command is required.');
+    }
+    try {
+        const transport = await getPreviewTransport();
+        const fields = await resolvePreviewGrantAccess(await cookies(), { ...transport, requestOrigin, applicationBuildId: resolveStorystickApplicationBuildId() });
+        if (!fields)
+            return previewErrorResponse(401, 'PREVIEW_GRANT_MISSING', 'Preview is not active.');
+        const client = await createPreviewControlClient(fields.token);
+        if (request.method === 'GET') {
+            const result = await client.context();
+            return NextResponse.json(result, { headers: { 'Cache-Control': 'private, no-store' } });
+        }
+        const command = await readPreviewContextCommand(request);
+        if (!command)
+            return previewErrorResponse(400, 'PREVIEW_CONTEXT_INVALID', 'Invalid Preview command.');
+        const result = await client.changeContext({
+            commandId: command.commandId,
+            expectedContextId: command.expectedContextId,
+            expectedRevision: command.expectedRevision,
+            perspective: command.perspective,
+        });
+        return NextResponse.json(result, { status: result.status === 'conflict' ? 409 : 200,
+            headers: { 'Cache-Control': 'private, no-store' } });
+    }
+    catch (error) {
+        return previewControlErrorResponse(error);
+    }
+}

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

@@ -0,0 +1,7 @@
+/** Leave this navigation experience; other views retain their admission. */
+import type { NextRequest } from 'next/server';
+export type PreviewDisableHandlerOptions = {
+    redirectAfter?: string;
+    basePath?: string;
+};
+export declare function createStorystickPreviewDisableHandler(options?: PreviewDisableHandlerOptions): (request: NextRequest) => Promise<Response>;

package/dist/preview/route-disable.js

@@ -0,0 +1,63 @@
+/** Leave this navigation experience; other views retain their admission. */
+import { NextResponse } from 'next/server';
+import { cookies } from 'next/headers';
+import { StorystickError } from '@storystick/client';
+import { PreviewRedirectError, assertSafePreviewRedirect, } from '@storystick/preview/server/grant';
+import { createPreviewControlClient, getPreviewTransport, resolvePreviewRequestOrigin } from './internal.js';
+import { resolvePreviewGrantAccess } from '@storystick/preview/server/extract-token';
+import { resolveStorystickApplicationBuildId } from '../code-version.js';
+import { readPreviewContextCommand } from '@storystick/preview/server/read-context-command';
+import { previewControlErrorResponse, previewErrorResponse } from './route-errors.js';
+export function createStorystickPreviewDisableHandler(options = {}) {
+    const basePath = options.basePath ?? '';
+    const rawRedirect = options.redirectAfter ?? (basePath || '/');
+    let safeRedirect;
+    try {
+        safeRedirect = assertSafePreviewRedirect(rawRedirect, basePath);
+    }
+    catch (error) {
+        if (error instanceof PreviewRedirectError) {
+            throw new Error('[storystick/preview] invalid preview disable redirectAfter');
+        }
+        throw error;
+    }
+    return async function POST(request) {
+        const requestOrigin = resolvePreviewRequestOrigin(request);
+        if (request.headers.get('origin') !== requestOrigin) {
+            return previewErrorResponse(403, 'PREVIEW_ORIGIN_MISMATCH', 'A same-origin Preview command is required.');
+        }
+        const transport = await getPreviewTransport();
+        const reader = await cookies();
+        try {
+            const fields = await resolvePreviewGrantAccess(reader, { ...transport, requestOrigin, applicationBuildId: resolveStorystickApplicationBuildId() });
+            if (fields) {
+                const client = await createPreviewControlClient(fields.token);
+                const command = await readPreviewContextCommand(request);
+                // No observable context (expired/refused bootstrap): clear this tab only.
+                if (command) {
+                    if (command.perspective !== null)
+                        return previewErrorResponse(400, 'PREVIEW_CONTEXT_INVALID', 'Invalid Preview exit.');
+                    const result = await client.changeContext({
+                        ...command, perspective: null,
+                    });
+                    if (result.status === 'conflict')
+                        return previewErrorResponse(409, 'PREVIEW_CONTEXT_CONFLICT', 'The Preview context changed. Retry leaving Preview.', { category: 'conflict', recoverable: true });
+                }
+            }
+        }
+        catch (error) {
+            const failure = previewControlErrorResponse(error);
+            // Explicit exit must also work after expiration or revocation. Invalid
+            // credentials cannot mutate server state, but can be removed locally.
+            const changedBuild = error instanceof StorystickError &&
+                error.code === 'storystick/CONTENT_SHAPE_RELOAD_REQUIRED';
+            if (failure.status !== 401 && failure.status !== 403 && !changedBuild)
+                return failure;
+        }
+        const response = request.headers.get('accept')?.includes('application/json')
+            ? NextResponse.json({ status: 'disabled' })
+            : NextResponse.redirect(new URL(safeRedirect, requestOrigin), { status: 302 });
+        response.headers.set('Cache-Control', 'no-store');
+        return response;
+    };
+}

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

@@ -0,0 +1,23 @@
+import 'server-only';
+import { type ReactElement, type ReactNode } from 'react';
+import type { PreviewProvenanceQueryResultLike } from '@storystick/preview/provenance';
+import { type PreviewProvenanceRuntime } from './provenance-runtime-adapter.js';
+import { type PreviewRouteDocumentFrame, type BuildPreviewRouteDocumentFrameOptions } from '@storystick/preview/server/route-document-provenance';
+export * from '@storystick/preview/server/route-document-provenance';
+export interface unstable_StorystickRoutePreviewFrameProps {
+    readonly frame: Pick<PreviewRouteDocumentFrame, 'frameId' | 'sessionId' | 'routeHash' | 'variantId' | 'publicSidecar'> | null | undefined;
+    readonly attrs?: Readonly<Record<string, string>>;
+    readonly children: ReactNode;
+}
+export interface RenderPreviewRouteDocumentOptions<TDocument extends PreviewProvenanceQueryResultLike, TContext = unknown> extends Omit<BuildPreviewRouteDocumentFrameOptions<TDocument, TContext>, 'routeHash'> {
+    readonly attrs?: Readonly<Record<string, string>>;
+    readonly render: (input: {
+        readonly document: TDocument;
+        readonly context: TContext | undefined;
+    }) => ReactNode | Promise<ReactNode>;
+}
+export declare function unstable_StorystickRoutePreviewFrame({ frame, attrs, children, }: unstable_StorystickRoutePreviewFrameProps): ReactElement;
+export declare function unstable_renderPreviewRouteDocument<TDocument extends PreviewProvenanceQueryResultLike, TContext = unknown>(options: RenderPreviewRouteDocumentOptions<TDocument, TContext>): Promise<ReactElement>;
+export declare function unstable_renderPreviewRouteDocumentWithRuntime<TDocument extends PreviewProvenanceQueryResultLike, TContext = unknown>(options: RenderPreviewRouteDocumentOptions<TDocument, TContext>, injectedRuntime?: PreviewProvenanceRuntime): Promise<ReactElement>;
+export declare function unstable_buildPreviewRouteDocumentFrame<TDocument extends PreviewProvenanceQueryResultLike, TContext = unknown>(options: BuildPreviewRouteDocumentFrameOptions<TDocument, TContext>): Promise<PreviewRouteDocumentFrame<TDocument, TContext> | null>;
+export declare function unstable_buildPreviewRouteDocumentFrameWithRuntime<TDocument extends PreviewProvenanceQueryResultLike, TContext = unknown>(options: BuildPreviewRouteDocumentFrameOptions<TDocument, TContext>, injectedRuntime?: PreviewProvenanceRuntime): Promise<PreviewRouteDocumentFrame<TDocument, TContext> | null>;

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

@@ -0,0 +1,46 @@
+import 'server-only';
+import { createElement, Fragment } from 'react';
+import { PreviewProvenanceSidecar } from '@storystick/react/internal/preview-provenance';
+import { resolvePreviewProvenanceRuntime, bindPreviewRuntimeToSidecar } from './provenance-runtime-adapter.js';
+import { unstable_buildPreviewRouteDocumentFrameWithRuntime as sharedBuildRoute, unstable_attachPreviewRouteRenderContext, stripPreviewRouteMetadata } from '@storystick/preview/server/route-document-provenance';
+export * from '@storystick/preview/server/route-document-provenance';
+export function unstable_StorystickRoutePreviewFrame({ frame, attrs, children, }) {
+    const content = attrs !== undefined
+        ? createElement('div', attrs, children)
+        : children;
+    return createElement(Fragment, null, frame
+        ? createElement(PreviewProvenanceSidecar, {
+            frameId: frame.frameId,
+            sessionId: frame.sessionId,
+            sidecar: frame.publicSidecar,
+        })
+        : null, content);
+}
+export async function unstable_renderPreviewRouteDocument(options) {
+    return unstable_renderPreviewRouteDocumentWithRuntime(options);
+}
+export async function unstable_renderPreviewRouteDocumentWithRuntime(options, injectedRuntime) {
+    const runtime = resolvePreviewProvenanceRuntime(injectedRuntime);
+    const { attrs, render, ...frameOptions } = options;
+    const document = stripPreviewRouteMetadata(frameOptions.document);
+    const frame = await unstable_buildPreviewRouteDocumentFrameWithRuntime({
+        ...frameOptions,
+        document,
+    }, runtime);
+    if (frame)
+        bindPreviewRuntimeToSidecar(frame.publicSidecar, runtime);
+    const renderDocument = frame?.codedDocument
+        ? unstable_attachPreviewRouteRenderContext(frame.codedDocument, frame)
+        : document;
+    const context = frame
+        ? unstable_attachPreviewRouteRenderContext((frame.codedContext ?? frameOptions.context), frame)
+        : frameOptions.context;
+    const children = await render({ document: renderDocument, context });
+    return unstable_StorystickRoutePreviewFrame({ frame, attrs, children });
+}
+export async function unstable_buildPreviewRouteDocumentFrame(options) {
+    return unstable_buildPreviewRouteDocumentFrameWithRuntime(options);
+}
+export async function unstable_buildPreviewRouteDocumentFrameWithRuntime(options, injectedRuntime) {
+    return sharedBuildRoute(options, resolvePreviewProvenanceRuntime(injectedRuntime));
+}

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

@@ -0,0 +1 @@
+export * from '@storystick/preview/server/control-errors';

package/dist/preview/route-errors.js

@@ -0,0 +1 @@
+export * from '@storystick/preview/server/control-errors';

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

@@ -0,0 +1,36 @@
+import type { NextRequest } from 'next/server';
+import { type StorystickRevalidateHandlerOptions } from '../revalidate.js';
+import { type PreviewDisableHandlerOptions } from './route-disable.js';
+import { type PreviewHandlerOptions } from './route-initial.js';
+import { type PreviewProvenanceRuntimeHandlerOptions } from './route-provenance-runtime.js';
+import { type PreviewTokenHandlerOptions } from './route-token.js';
+export interface RouteHandlerOptions {
+    /**
+     * Runtime URL prefix matching `next.config.js` `basePath`. Applied to the
+     * preview, token, and disable handlers unless overridden per handler.
+     */
+    basePath?: string;
+    preview?: PreviewHandlerOptions;
+    token?: PreviewTokenHandlerOptions;
+    disable?: PreviewDisableHandlerOptions;
+    provenanceRuntime?: PreviewProvenanceRuntimeHandlerOptions;
+    revalidate?: StorystickRevalidateHandlerOptions;
+    /** Optional application readback. Its source must be this deployed build. */
+    migrationReadback?: () => Promise<{
+        projectId: string;
+        artifactId: string;
+        artifactDigest: string;
+        schemaVersion: string | null;
+        querySchemaFingerprint: string;
+        publication?: {
+            version: 2;
+            rendering: 'request' | 'static' | 'unqualified';
+            receipts: boolean;
+        };
+    } | null>;
+}
+export interface RouteHandlers {
+    GET(request: NextRequest): Promise<Response>;
+    POST(request: NextRequest): Promise<Response>;
+}
+export declare function createRouteHandler(options?: RouteHandlerOptions): RouteHandlers;

package/dist/preview/route-handler.js

@@ -0,0 +1,139 @@
+import { NextResponse } from 'next/server';
+import { STORYSTICK_HEALTH_ROUTE_PATH, STORYSTICK_MIGRATION_READBACK_ROUTE_PATH, STORYSTICK_PREVIEW_DISABLE_ROUTE_PATH, STORYSTICK_PREVIEW_AUTHORING_ROUTE_PATH, STORYSTICK_PREVIEW_PROVENANCE_RUNTIME_ROUTE_PATH, STORYSTICK_PREVIEW_ROUTE_PATH, STORYSTICK_PREVIEW_TOKEN_ROUTE_PATH, STORYSTICK_PREVIEW_CONTEXT_ROUTE_PATH, STORYSTICK_REVALIDATE_ROUTE_PATH, } from '@storystick/preview/routes';
+import { createStorystickRevalidateHandler, } from '../revalidate.js';
+import { createStorystickPreviewDisableHandler, } from './route-disable.js';
+import { createStorystickPreviewHandler, } from './route-initial.js';
+import { createStorystickPreviewProvenanceRuntimeHandler, } from './route-provenance-runtime.js';
+import { createStorystickPreviewTokenHandler, } from './route-token.js';
+import { handlePreviewContext } from './route-context.js';
+import { createStorystickPreviewAuthoringHandler } from './route-authoring.js';
+export function createRouteHandler(options = {}) {
+    const preview = createStorystickPreviewHandler(withBasePath(options.preview, options.basePath));
+    const token = createStorystickPreviewTokenHandler(withBasePath(options.token, options.basePath));
+    const disable = createStorystickPreviewDisableHandler(withBasePath(options.disable, options.basePath));
+    const authoring = createStorystickPreviewAuthoringHandler();
+    const provenanceRuntime = createStorystickPreviewProvenanceRuntimeHandler(options.provenanceRuntime);
+    const revalidate = createStorystickRevalidateHandler(options.revalidate);
+    return {
+        async GET(request) {
+            switch (resolveAction(request, options.basePath)) {
+                case 'context': return handlePreviewContext(request);
+                case 'preview':
+                    return preview(request);
+                case 'health':
+                    return healthResponse();
+                case 'migration-readback':
+                    return migrationReadbackResponse(options.migrationReadback);
+                case 'provenance-runtime':
+                    return provenanceRuntime(request);
+                case 'token':
+                case 'disable':
+                case 'authoring':
+                case 'revalidate':
+                    return methodNotAllowed('POST');
+                default:
+                    return notFound();
+            }
+        },
+        async POST(request) {
+            switch (resolveAction(request, options.basePath)) {
+                case 'context': return handlePreviewContext(request);
+                case 'token':
+                    return token(request);
+                case 'disable':
+                    return disable(request);
+                case 'authoring':
+                    return authoring(request);
+                case 'revalidate':
+                    return revalidate(request);
+                case 'preview':
+                case 'health':
+                case 'migration-readback':
+                case 'provenance-runtime':
+                    return methodNotAllowed('GET');
+                default:
+                    return notFound();
+            }
+        },
+    };
+}
+function withBasePath(options, basePath) {
+    if (!basePath || options?.basePath)
+        return (options ?? {});
+    return { ...(options ?? {}), basePath };
+}
+function resolveAction(request, basePath) {
+    const pathname = stripBasePath(request.nextUrl.pathname, basePath);
+    switch (pathname) {
+        case STORYSTICK_PREVIEW_ROUTE_PATH:
+            return 'preview';
+        case STORYSTICK_PREVIEW_TOKEN_ROUTE_PATH:
+            return 'token';
+        case STORYSTICK_PREVIEW_CONTEXT_ROUTE_PATH:
+            return 'context';
+        case STORYSTICK_PREVIEW_DISABLE_ROUTE_PATH:
+            return 'disable';
+        case STORYSTICK_PREVIEW_AUTHORING_ROUTE_PATH:
+            return 'authoring';
+        case STORYSTICK_HEALTH_ROUTE_PATH:
+            return 'health';
+        case STORYSTICK_MIGRATION_READBACK_ROUTE_PATH:
+            return 'migration-readback';
+        case STORYSTICK_REVALIDATE_ROUTE_PATH:
+            return 'revalidate';
+        case STORYSTICK_PREVIEW_PROVENANCE_RUNTIME_ROUTE_PATH:
+            return 'provenance-runtime';
+        default:
+            return null;
+    }
+}
+function stripBasePath(pathname, basePath) {
+    if (!basePath)
+        return pathname;
+    const normalized = normalizeBasePath(basePath);
+    if (pathname === normalized)
+        return '/';
+    if (pathname.startsWith(`${normalized}/`)) {
+        return pathname.slice(normalized.length);
+    }
+    return pathname;
+}
+function normalizeBasePath(value) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === '/')
+        return '';
+    const withLeadingSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    return withLeadingSlash.endsWith('/')
+        ? withLeadingSlash.slice(0, -1)
+        : withLeadingSlash;
+}
+function healthResponse() {
+    return NextResponse.json({ ok: true }, { headers: { 'Cache-Control': 'no-store' } });
+}
+async function migrationReadbackResponse(readback) {
+    const headers = { 'Cache-Control': 'no-store' };
+    if (!readback)
+        return notFound();
+    try {
+        const migration = await readback();
+        return NextResponse.json(migration ? { ok: true, migration } : { ok: false, error: 'migration_readback_not_configured' }, {
+            status: migration ? 200 : 503,
+            headers,
+        });
+    }
+    catch {
+        return NextResponse.json({ ok: false, error: 'migration_readback_unavailable' }, { status: 503, headers });
+    }
+}
+function methodNotAllowed(allow) {
+    return NextResponse.json({ ok: false, error: 'method_not_allowed' }, {
+        status: 405,
+        headers: {
+            Allow: allow,
+            'Cache-Control': 'no-store',
+        },
+    });
+}
+function notFound() {
+    return NextResponse.json({ ok: false, error: 'not_found' }, { status: 404, headers: { 'Cache-Control': 'no-store' } });
+}

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

@@ -0,0 +1,9 @@
+/** One-shot PreviewGrant activation route. */
+import type { NextRequest } from 'next/server';
+export type PreviewHandlerOptions = {
+    /** Query param carrying the final same-origin path. Default `redirect`. */
+    redirectParam?: string;
+    /** Runtime URL prefix matching `next.config.js` `basePath`. */
+    basePath?: string;
+};
+export declare function createStorystickPreviewHandler(options?: PreviewHandlerOptions): (request: NextRequest) => Promise<Response>;