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

package/dist/server-runtime.js

@@ -0,0 +1,1584 @@
+import { PUBLIC_RENDER_CHALLENGE_HEADER, isPublicRenderChallenge } from '@storystick/types/public-delivery';
+import { fetchProjectLocaleSettings } from '@storystick/client/adapter';
+import { createPublicRenderReceipt, createPublicSiteManifest } from '@storystick/client';
+import { publishedLocaleRoutes as readPublishedLocaleRoutes } from '@storystick/client/adapter';
+import { pathnameForPreviewDraft, previewDocumentSeo, localeContextForPreviewDraft } from '@storystick/preview/server/draft-route';
+import { PREVIEW_CONTEXT_SUPERSEDED_DIGEST } from './preview-render-error.js';
+import { mapPreviewSessionError } from '@storystick/preview/session-subscriber';
+/** Next server reads, optional CMS routing, and static route inventory. */
+import 'server-only';
+import { attachDocumentLocaleRouting, normalizePublicLocaleOrigins, publishedLocaleHrefs } from '@storystick/client/locale-routing';
+import { cache } from 'react';
+import { bindSiteQuerySchema, previewRuntimeForSchema, bindPreviewRuntimeToReads, previewRuntimeForReads, bindPreviewRuntimeToSidecar } from './preview/provenance-runtime-adapter.js';
+import { unstable_buildPreviewRouteDocumentFrameWithRuntime } from './preview/route-document-provenance.js';
+import { prepareOrdinaryPreviewRead } from '@storystick/preview/server/ordinary-read-provenance';
+import { createRouteHandler } from './preview/route-handler.js';
+import { storystickAlternates } from './i18n-seo.js';
+import { stripPreviewProvenance } from './clean.js';
+import { STORYSTICK_PREVIEW_ROBOTS } from './preview-metadata.js';
+import { readNativeSliceLocale } from './preview/slice-locale.js';
+import { draftMode, cookies, headers } from 'next/headers';
+import { previewControlClient } from '@storystick/preview/server/control-client';
+import { isPreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { isPreviewProjectionGenerationSignal } from '@storystick/preview/framework/generation-signal';
+import { normalizePathname, pathnameToSegments, StorystickError, } from '@storystick/client';
+import { createHttpTransportV2, fetchCurrentSchema, resolveInfra, } from '@storystick/client/adapter';
+import { createInternalClient, prepareContentValues, assertExactQueryResult, getInternalClientRuntime, getPreviewReadObservation, previewAssetDependenciesFromValue, } from '@storystick/client/internal';
+import { publicPathnameForLocale, } from '@storystick/types/internal/locale-routing';
+import { readPreviewProvenanceRouteRender, registerPreviewSliceScopeAdapter, } from '@storystick/react/internal/preview-provenance';
+import { resolvePreviewGrantAccess, } from '@storystick/preview/server/extract-token';
+import { exchangePreviewGrantForServer, PreviewGrantExchangeError, classifyPreviewGrantError, } from '@storystick/preview/server/grant';
+import { resolveStorystickApplicationBuildDigest, resolveStorystickApplicationBuildId, resolveStorystickServerCodeVersion } from './code-version.js';
+import { PREVIEW_SESSION_QUERY_PARAM, readPreviewDraftDocumentId, previewDraftHref, readPreviewSessionIdFromSearch, } from '@storystick/preview/identity';
+import { attachPreviewFrameDependencies, } from '@storystick/preview/provenance';
+import { attachPreviewRouteRenderContext, collectPreviewRouteDocumentSliceTypes, createPreviewReadIdentityTransport, resolvePreviewProvenanceConfig, } from './preview/server-preview-internals.js';
+import { createPreviewReadLifecycle } from '@storystick/preview/server/read-lifecycle';
+import { runNativeSlice } from './preview/slice-locale.js';
+import { buildStorystickSitemapShards, STORYSTICK_SITEMAP_MAX_URLS, } from './i18n-seo.js';
+import { appendSearchParamsToRedirect } from './preview-session-recovery.js';
+import { withNextQueryOptions, deploymentScopedFetch } from './query-fetch-options.js';
+// Each createSite owns a distinct immutable schema; no request state is stored.
+const staticSiteSchemas = new WeakSet();
+function deploymentId() {
+    return process.env.VERCEL_DEPLOYMENT_ID ?? process.env.STORYSTICK_DEPLOYMENT_ID;
+}
+function createNextHttpTransport(options) {
+    return createHttpTransportV2({ ...options, fetchImpl: deploymentScopedFetch(deploymentId()) });
+}
+export { buildStorystickSitemap, buildStorystickSitemapShards, STORYSTICK_SITEMAP_MAX_URLS, storystickAlternates, } from './i18n-seo.js';
+export { appendSearchParamsToRedirect, } from './preview-session-recovery.js';
+registerPreviewSliceScopeAdapter(runNativeSlice);
+/** Internal schema for control-plane-only helpers such as route resolution. */
+const CONTROL_QUERY_SCHEMA = Object.freeze({
+    contractVersion: 2,
+    fingerprint: 'query-schema.v2.control-only',
+    stories: Object.freeze({}),
+});
+const readPreviewRawReadCache = cache((_schema) => new Map());
+const requestRenderSlot = cache(() => ({}));
+function previewRequestSelectionKey(selection) {
+    return JSON.stringify({
+        sessionId: selection.sessionId,
+    });
+}
+function bindRequestPreviewSelection(selection) {
+    const slot = requestRenderSlot();
+    const key = previewRequestSelectionKey(selection);
+    if (slot.previewRequest === undefined) {
+        slot.previewRequest = selection;
+        slot.previewRequestKey = key;
+        return selection;
+    }
+    if (slot.previewRequestKey !== key) {
+        throw new StorystickError('Two incompatible Preview selectors were bound in one request.', {
+            code: 'storystick/PREVIEW_CONTEXT_CONFLICT',
+            category: 'validation',
+            recoverable: true,
+            retryable: false,
+        });
+    }
+    return slot.previewRequest;
+}
+function readRequestPreviewSelection() {
+    return requestRenderSlot().previewRequest;
+}
+function localeContextKey(context) {
+    return JSON.stringify({
+        locale: context.locale,
+        defaultLocale: context.defaultLocale,
+        locales: context.locales,
+        localeRouting: context.localeRouting,
+        publicOrigins: context.publicOrigins,
+        synthetic: context.synthetic,
+    });
+}
+function bindRequestLocaleContext(context) {
+    const slot = requestRenderSlot();
+    const key = localeContextKey(context);
+    if (slot.binding === undefined) {
+        slot.key = key;
+        slot.binding = Promise.resolve(context);
+        return slot.binding;
+    }
+    if (slot.key !== key) {
+        throw mixedLocaleRequest('Two incompatible locale routes were bound in one request.');
+    }
+    return slot.binding;
+}
+async function readRequestLocaleContext() {
+    const binding = requestRenderSlot().binding;
+    if (binding === undefined) {
+        throw new Error('StorystickError: LOCALE_REQUEST_CONTEXT_MISSING — call resolvePage({ pathname }) before locale-aware reads.');
+    }
+    return binding;
+}
+function readBoundRequestLocaleContext() {
+    return requestRenderSlot().binding;
+}
+const readProjectLocaleSettings = cache(async (requestContext) => {
+    // A resolved page already carries the project's routing settings. Keep
+    // subsequent layout/client reads on that same request snapshot.
+    const bound = readBoundRequestLocaleContext();
+    if (bound)
+        return bound;
+    const projectId = readProjectId();
+    const apiKey = readApiKey();
+    const infra = await resolveServerInfra(projectId);
+    return fetchProjectLocaleSettings(createNextHttpTransport({
+        projectId, endpoint: infra.endpoint, apiKey, applicationBuildId: resolveStorystickApplicationBuildId(),
+    }), requestContext);
+});
+// ─────────────────────────────────────────────
+// StorystickError re-export (ADR-091 §Consequences > @storystick/next)
+// ─────────────────────────────────────────────
+//
+// The class itself moved to `@storystick/client` in Lane A. We re-export
+// it from this server entry so existing user code that imported it from
+// `@storystick/next` keeps working source-compat. `instanceof` checks
+// across both import paths resolve to the same class identity.
+export { StorystickError } from '@storystick/client';
+const PREVIEW_SESSION_ENDED_ERROR_CODES = new Set([
+    'storystick/PREVIEW_GRANT_EXPIRED',
+    'storystick/PREVIEW_GRANT_MISSING',
+    'storystick/PREVIEW_GRANT_REVOKED',
+    'storystick/PREVIEW_ACCESS_REVOKED',
+    'storystick/PREVIEW_CONTEXT_INVALID',
+    'storystick/PREVIEW_GRANT_FORBIDDEN',
+]);
+/**
+ * Natural cookie expiry can arrive as EXPIRED while the cookie is still in
+ * the request jar, or MISSING after the browser evicts it while Draft Mode
+ * remains enabled. Both are the same user-visible ended-session state.
+ */
+export function isPreviewSessionEndedError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const code = error.code;
+    return typeof code === 'string' && PREVIEW_SESSION_ENDED_ERROR_CODES.has(code);
+}
+export { buildPreviewProvenanceFrame, } from './preview/provenance-frame-builder.js';
+export { STORYSTICK_PREVIEW_ROBOTS } from './preview-metadata.js';
+export { readPreviewProvenanceSessionId, resolvePreviewProvenanceRouteIdentity, } from './preview/preview-request-identity.js';
+export { stripPreviewProvenance } from './clean.js';
+// ─────────────────────────────────────────────
+// Env-var helpers
+// ─────────────────────────────────────────────
+function readRequiredEnv(name, hint) {
+    const value = process.env[name];
+    if (!value || value.length === 0) {
+        throw new Error(`StorystickError: No ${name} found.\n${hint}`);
+    }
+    return value;
+}
+function readApiKey() {
+    return readRequiredEnv('STORYSTICK_API_KEY', 'Add it to your .env.local (ss_sk_live_* for server-side reads):\n\n' +
+        '  STORYSTICK_API_KEY=ss_sk_live_...\n');
+}
+function readProjectId() {
+    return readRequiredEnv('STORYSTICK_PROJECT_ID', 'Add it to your .env.local — it is the 8-char shortId visible in your\n' +
+        'Hub project URL at /p/<label>-<shortId>:\n\n' +
+        '  STORYSTICK_PROJECT_ID=a3k9m2x7\n' +
+        '  STORYSTICK_API_KEY=ss_sk_live_...\n');
+}
+/**
+ * Resolve the gateway endpoint + Convex RPC URL for `projectId`. ADR-131
+ * C9 — delegates to `resolveInfra` which auto-derives the `.convex.site` /
+ * `.convex.cloud` pair from one gateway round-trip. Per-URL env escape
+ * hatches (`STORYSTICK_ENDPOINT`, `STORYSTICK_CONVEX_URL`) are honoured
+ * (undocumented in customer `.env.example`) for self-host overrides.
+ */
+async function resolveServerInfra(projectId) {
+    const directEndpoint = process.env.STORYSTICK_ENDPOINT;
+    const directConvex = process.env.STORYSTICK_CONVEX_URL;
+    return resolveInfra(projectId, {
+        endpoint: directEndpoint && directEndpoint.length > 0 ? directEndpoint : undefined,
+        convexUrl: directConvex && directConvex.length > 0 ? directConvex : undefined,
+    });
+}
+/**
+ * Build a Storystick client bound to the current Next.js request.
+ *
+ * Behavior:
+ *   - Production traffic (`draftMode().isEnabled === false`): returns
+ *     a configured client that mints JWTs from `STORYSTICK_API_KEY`.
+ *     `cookies()` is NEVER called, so Next's static prerender / ISR
+ *     cache is preserved for non-editor traffic.
+ *   - Editor traffic (`draftMode().isEnabled === true`, `__prerender_bypass`
+ *     latched for the browser session): resolves the latest signed admission.
+ *     A closed admission returns public data, even while Draft Mode remains on.
+ *     An active admission resolves a short-lived
+ *     preview JWT from that grant and wires
+ *     `requestContext` so the transport sends `Authorization: Bearer <jwt>`,
+ *     emits `X-Storystick-Preview: 1`, and forces `cache: 'no-store'`.
+ *   - An explicit Preview selector with no addressed grant throws a recoverable
+ *     auth error. Native Draft Mode alone may belong to another local project
+ *     and does not activate Storystick Preview. Editor traffic
+ *     with a present-but-malformed/expired cookie throws the existing
+ *     recoverable auth error during extraction (CSO-PREVIEW-15). In both
+ *     cases, the preview request never reaches the API-key mint path.
+ */
+async function createServerClientForLocale(querySchema, locale, previewRequest, localeRouting, primaryPage = false) {
+    const nativePreview = process.env.NODE_ENV !== 'production' || !!process.env.STORYSTICK_LANE_ID
+        ? Promise.resolve(true) : draftMode().then(mode => mode.isEnabled);
+    const projectId = readProjectId();
+    const apiKey = readApiKey();
+    const infra = await resolveServerInfra(projectId);
+    const requestPreviewSelection = previewRequest === undefined
+        ? readRequestPreviewSelection()
+        : bindRequestPreviewSelection(previewRequest);
+    // Ordinary links and server layouts inherit the admission. The view remains
+    // optional, for route observations and explicit draft destinations only.
+    const hasExplicitPreviewSelector = requestPreviewSelection !== undefined;
+    const endpoint = infra.endpoint;
+    const previewEnabled = hasExplicitPreviewSelector || await nativePreview;
+    if (!previewEnabled)
+        return createNextServerClient({
+            querySchema, primaryPage, localeRouting, projectId, apiKey, endpoint, locale,
+        });
+    // Step 2 — editor traffic (prod: gated by draftMode above; dev: always
+    // reaches here). Read the addressed PreviewGrant cookie. Enabled alongside
+    // `__prerender_bypass` by the activation handler in prod;
+    // in dev the bypass cookie was dropped at the iframe boundary but the
+    // Storystick cookie traversed via the loopback CHIPS carve-out
+    // (commit 4b866ec, validated by spike cookie-iframe-chips-http-localhost.spec.js).
+    const routePathname = requestPreviewSelection?.routePathname ?? '';
+    const requestSessionId = requestPreviewSelection?.sessionId ?? null;
+    const requestOrigin = await deriveRequestOrigin();
+    const fields = await resolveCurrentPreviewGrantAccess({
+        projectId,
+        requestOrigin,
+        endpoint,
+        apiKey,
+        applicationBuildId: resolveStorystickApplicationBuildId(),
+    });
+    if (!fields) {
+        if (hasExplicitPreviewSelector && fields !== null) {
+            throw new StorystickError('Preview mode is active but the addressed PreviewGrant is missing.', {
+                code: 'storystick/PREVIEW_GRANT_MISSING',
+                category: 'auth',
+                recoverable: true,
+                retryable: false,
+            });
+        }
+        // Development traffic reaches this branch without a draftMode gate so
+        // normal local page loads can legitimately have no preview cookie.
+        // Present-but-malformed / expired grants still throw in the resolver.
+        return createNextServerClient({
+            querySchema,
+            primaryPage,
+            localeRouting,
+            projectId,
+            apiKey,
+            endpoint,
+            locale,
+        });
+    }
+    // Layouts and pages share the admitted perspective; a page may also identify its view.
+    const [session, readContext] = await Promise.all([
+        requestSessionId ? readPreviewSessionForRequest(fields, projectId, requestSessionId) : null,
+        readPreviewContextForRequest(fields.token, infra.endpoint),
+    ]);
+    const previewScope = readContext.perspective;
+    const releaseId = previewScope.kind === 'release' ? previewScope.releaseId : null;
+    const variantId = previewScope.kind === 'variant' ? previewScope.variantId : null;
+    const codeVersion = resolveStorystickServerCodeVersion();
+    const observationId = readPreviewObservationId(readContext.contextId, readContext.revision);
+    const observationFetchUrl = `${infra.endpoint.replace(/\/$/, '')}/api/preview/control`;
+    const admittedSessionId = session ? requestSessionId : null;
+    const isPreviewContextSuperseded = async () => {
+        const current = await readPreviewContext(fields.token, infra.endpoint);
+        return current.contextId === readContext.contextId && current.revision > readContext.revision;
+    };
+    const enqueueObservedDocs = admittedSessionId
+        ? getObservedDocsBatcher(observationFetchUrl, fields.token, projectId, admittedSessionId, requestOrigin + routePathname, codeVersion)
+        : undefined;
+    return createNextServerClient({
+        querySchema,
+        primaryPage,
+        localeRouting,
+        projectId,
+        apiKey,
+        endpoint,
+        locale,
+        isPreviewContextSuperseded,
+        requestContext: {
+            previewToken: fields.token,
+            previewReadContext: readContext,
+            previewSessionId: admittedSessionId ?? undefined,
+            previewQueryConsumer: 'server-render',
+            variantId,
+            releaseId,
+            previewCodeVersion: codeVersion,
+            previewObservationId: observationId,
+            onAccessedContent: enqueueObservedDocs,
+            refreshPreviewToken: async (oldToken) => {
+                // Access credentials are disposable. The durable grant is the
+                // refresh authority, so an RSC can recover on demand even though it
+                // cannot persist the refreshed access JWT back into the HttpOnly
+                // cookie during rendering.
+                void oldToken;
+                if (!requestOrigin) {
+                    // Fail closed when we cannot derive the origin from headers.
+                    // Falling back to the cookie's `previewOrigin` would let a
+                    // leaked cookie self-attest (codex Lane C blocker). The
+                    // transport will throw `PREVIEW_TOKEN_EXPIRED` on undefined.
+                    return undefined;
+                }
+                try {
+                    const exchange = await exchangePreviewGrantForServer({
+                        endpoint,
+                        apiKey,
+                        applicationBuildId: resolveStorystickApplicationBuildId(),
+                        grantToken: fields.grantToken,
+                        requestOrigin,
+                        contentShapeCapability: fields.contentShapeCapability,
+                    });
+                    if (exchange.projectId !== fields.projectId ||
+                        exchange.previewOrigin !== fields.previewOrigin ||
+                        (exchange.grantId !== undefined &&
+                            exchange.grantId !== fields.grantId) ||
+                        (exchange.grantExpiresAt !== undefined &&
+                            exchange.grantExpiresAt <= Date.now())) {
+                        throw new StorystickError('Preview grant exchange returned incompatible bindings.', {
+                            code: 'storystick/PREVIEW_GRANT_BINDING_MISMATCH',
+                            category: 'auth',
+                            recoverable: true,
+                            retryable: false,
+                        });
+                    }
+                    return exchange.token;
+                }
+                catch (err) {
+                    // Refresh failed (Central rejected, network error, etc.).
+                    // Preserve the preview-specific taxonomy here instead of
+                    // collapsing every case to PREVIEW_TOKEN_EXPIRED. The
+                    // transport still never falls back to the API-key mint cache
+                    // on preview requests (audit P1-1 invariant).
+                    if (err instanceof PreviewGrantExchangeError) {
+                        throw buildPreviewGrantStorystickError(err);
+                    }
+                    throw err;
+                }
+            },
+        },
+    });
+}
+export async function createServerClient(querySchema) {
+    const binding = readBoundRequestLocaleContext();
+    const context = binding ? await binding : undefined;
+    return createServerClientForLocale(querySchema, context?.synthetic ? undefined : context?.locale, undefined, context);
+}
+async function createNextServerClient(input) {
+    // Route resolution returns and attaches its own locale settings. Reading
+    // them first adds a serialized request with no information the route needs.
+    // Explicit domain routing still supplies settings through input.localeRouting.
+    const localeRouting = input.localeRouting ?? (input.primaryPage !== true && previewRuntimeForSchema(input.querySchema)
+        ? await readProjectLocaleSettings(input.requestContext)
+        : undefined);
+    const requestContext = input.requestContext?.previewToken &&
+        (previewRuntimeForSchema(input.querySchema) || resolvePreviewProvenanceConfig().enabled)
+        ? {
+            ...input.requestContext,
+            unstable_previewProvenanceReadLifecycle: createPreviewReadLifecycle({
+                primaryPage: input.primaryPage,
+                projectId: input.projectId,
+                endpoint: input.endpoint,
+                runtime: previewRuntimeForSchema(input.querySchema),
+                previewObservationId: input.requestContext.previewObservationId,
+                variantId: input.requestContext.variantId,
+                releaseId: input.requestContext.releaseId,
+                previewCodeVersion: input.requestContext.previewCodeVersion,
+                rawReadCache: readPreviewRawReadCache(input.querySchema),
+            }),
+        }
+        : input.requestContext;
+    return createInternalClient({
+        schema: input.querySchema,
+        localeRouting,
+        projectId: input.projectId,
+        apiKey: input.apiKey,
+        endpoint: input.endpoint,
+        defaults: input.locale ? { locale: input.locale } : undefined,
+        requestContext,
+        transport: withNextQueryOptions(input.projectId, localeGuardTransport(previewRuntimeForSchema(input.querySchema) ? undefined : input.locale, createPreviewReadIdentityTransport(createNextHttpTransport({
+            projectId: input.projectId,
+            endpoint: input.endpoint,
+            deliveryEndpoint: process.env.STORYSTICK_DELIVERY_ENDPOINT,
+            apiKey: input.apiKey,
+            applicationBuildId: resolveStorystickApplicationBuildId(),
+        }))), input.isPreviewContextSuperseded, staticSiteSchemas.has(input.querySchema)),
+    });
+}
+function localeGuardTransport(locale, transport) {
+    if (!transport)
+        throw new Error('StorystickError: missing Next transport.');
+    if (!locale)
+        return transport;
+    return {
+        async request(input) {
+            const query = input.udfPath === 'queries:queryV2' &&
+                input.args.query && typeof input.args.query === 'object'
+                ? input.args.query
+                : undefined;
+            const requested = query?.locale?.code;
+            if (requested !== undefined && requested !== locale) {
+                throw mixedLocaleRequest(`Request locale "${requested}" conflicts with bound locale "${locale}".`);
+            }
+            return transport.request(input);
+        },
+    };
+}
+function mixedLocaleRequest(message) {
+    return new StorystickError(message, {
+        code: 'storystick/MIXED_LOCALE_REQUEST',
+        category: 'validation',
+        recoverable: true,
+        retryable: false,
+    });
+}
+function buildPreviewGrantStorystickError(err) {
+    const publicError = classifyPreviewGrantError(err, 'exchange');
+    return new StorystickError(`${publicError.code} — ${publicError.message}`, {
+        code: `storystick/${publicError.code}`,
+        ref: publicError.upstreamRef,
+        category: publicError.category,
+        recoverable: publicError.recoverable,
+        retryable: publicError.retryable,
+        payload: {
+            operation: 'preview-grant-access',
+            upstreamCode: publicError.upstreamCode,
+        },
+    });
+}
+const resolveCurrentPreviewGrantAccessCached = cache(async (projectId, requestOrigin, endpoint, apiKey, applicationBuildId) => {
+    const cookieStore = (await cookies());
+    return resolvePreviewGrantAccess(cookieStore, {
+        projectId,
+        requestOrigin,
+        endpoint,
+        apiKey,
+        applicationBuildId,
+    });
+});
+function resolveCurrentPreviewGrantAccess(options) {
+    return resolveCurrentPreviewGrantAccessCached(options.projectId, options.requestOrigin, options.endpoint, options.apiKey, options.applicationBuildId);
+}
+/**
+ * Derive the current request's origin from the headers store. Mirrors
+ * what `request.nextUrl.origin` provides inside a route handler:
+ * combines the forwarded protocol with the host header.
+ *
+ * `next/headers::headers()` is request-scoped (Dynamic API), the same
+ * way `cookies()` is — calling it under `draftMode().isEnabled === true`
+ * is safe (the route is already dynamically re-rendered for editor
+ * traffic; the dynamic-API tax was already paid by `cookies()`).
+ *
+ * Returns the empty string when no host header is present (e.g., outside
+ * a Next request context, or behind a misconfigured proxy that strips
+ * `Host` + `X-Forwarded-Host`). The refresh callback fails closed in
+ * that case rather than self-attesting from the cookie's `previewOrigin`.
+ */
+async function deriveRequestOrigin() {
+    try {
+        const h = await headers();
+        const host = h.get('x-forwarded-host') ?? h.get('host');
+        const proto = h.get('x-forwarded-proto') ?? 'https';
+        if (host)
+            return `${proto}://${host}`;
+    }
+    catch {
+        // headers() can throw outside a request context — fall through.
+    }
+    return '';
+}
+// ─────────────────────────────────────────────
+// ADR-131 §D3.1b — first-render observation tap helpers
+// ─────────────────────────────────────────────
+/**
+ * Resolve the customer's deploy version. Drives Layer 1 cache
+ * invalidation for route-scoped document observations; on `codeVersion`
+ * drift the central row discards previously-observed document ids rather
+ * than threading stale observations into the current route.
+ *
+ * Precedence:
+ *   1. `STORYSTICK_CODE_VERSION` — explicit operator override.
+ *   2. `NEXT_BUILD_ID` — Next.js writes this on `next build`.
+ *   3. `VERCEL_GIT_COMMIT_SHA` — Vercel-specific fallback.
+ *   4. `'dev-unknown'` — last-resort marker so the orchestrator
+ *      sees a stable key during `next dev` (no cache invalidation
+ *      across edits is fine in dev — observations refresh on
+ *      navigate anyway).
+ */
+const OBSERVATION_IDLE_FLUSH_MS = 250;
+const OBSERVATION_MAX_FLUSH_MS = 1_000;
+/**
+ * Request-scoped observation coalescer. The SDK transport still reports
+ * every successful preview read, but the Next adapter sends one bounded
+ * `recordAccessedDocumentIds` mutation per render/session/route burst.
+ */
+const getObservedDocsBatcher = cache((observationFetchUrl, previewToken, projectId, sessionId, routeUrl, codeVersion) => {
+    const pendingDocumentIds = new Set();
+    const pendingStoryTypes = new Set();
+    let pendingObservationId;
+    let pendingRenderWatermark;
+    let idleTimer;
+    let maxTimer;
+    const clearTimers = () => {
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        if (maxTimer !== undefined)
+            clearTimeout(maxTimer);
+        idleTimer = undefined;
+        maxTimer = undefined;
+    };
+    const flush = () => {
+        clearTimers();
+        const documentIds = Array.from(pendingDocumentIds);
+        const storyTypes = Array.from(pendingStoryTypes);
+        const observationId = pendingObservationId;
+        const renderWatermark = pendingRenderWatermark;
+        pendingDocumentIds.clear();
+        pendingStoryTypes.clear();
+        pendingObservationId = undefined;
+        pendingRenderWatermark = undefined;
+        if ((documentIds.length === 0 && storyTypes.length === 0) ||
+            observationId === undefined ||
+            renderWatermark === undefined)
+            return;
+        // Fire-and-forget. Observation is a fallback signal; render latency
+        // must never be coupled to Convex write pressure.
+        void postObservedDocs({
+            observationFetchUrl,
+            previewToken,
+            projectId,
+            sessionId,
+            routeUrl,
+            codeVersion,
+            documentIds,
+            storyTypes,
+            observationId,
+            renderWatermark,
+        });
+    };
+    return (observation) => {
+        // codeVersion + observationId are the compatibility fence. A callback
+        // crossing render identities is dropped instead of contaminating the
+        // current render projection.
+        if (observation.codeVersion !== codeVersion ||
+            observation.observationId.length === 0)
+            return;
+        if (pendingObservationId !== undefined &&
+            pendingObservationId !== observation.observationId) {
+            flush();
+        }
+        pendingObservationId = observation.observationId;
+        pendingRenderWatermark =
+            pendingRenderWatermark === undefined
+                ? observation.renderWatermark
+                : Math.min(pendingRenderWatermark, observation.renderWatermark);
+        for (const id of observation.documentIds) {
+            if (typeof id === 'string' && id.length > 0)
+                pendingDocumentIds.add(id);
+        }
+        for (const storyType of observation.storyTypes) {
+            if (typeof storyType === 'string' && storyType.length > 0) {
+                pendingStoryTypes.add(storyType);
+            }
+        }
+        if (pendingDocumentIds.size === 0 && pendingStoryTypes.size === 0)
+            return;
+        if (idleTimer !== undefined)
+            clearTimeout(idleTimer);
+        idleTimer = setObservationTimer(flush, OBSERVATION_IDLE_FLUSH_MS);
+        maxTimer ??= setObservationTimer(flush, OBSERVATION_MAX_FLUSH_MS);
+    };
+});
+function setObservationTimer(callback, delayMs) {
+    const timer = setTimeout(callback, delayMs);
+    if (typeof timer === 'object' && timer !== null && 'unref' in timer) {
+        const unref = timer.unref;
+        if (typeof unref === 'function')
+            unref.call(timer);
+    }
+    return timer;
+}
+/**
+ * Best-effort Preview dependency observation through the public gateway.
+ * The gateway verifies the SDK token; the native mutation rechecks the grant.
+ * These are rendering dependencies, never financial usage evidence.
+ *
+ * Failure modes (all silent — the tap is fire-and-forget by contract):
+ *   - Network: `fetch` rejects. Swallowed.
+ *   - 401/403: stale cookie. The user re-enters Studio preview; the
+ *     next preview's tap will succeed.
+ *   - 429: per-session rate limit. Studio uses the most recent
+ *     successful row until the bucket replenishes.
+ *
+ * NEVER throws. The `try/catch` is paranoid: a thrown sync error from
+ * `fetch` (URL malformed, etc.) would otherwise unwind into the
+ * customer's RSC tree (the tap was synchronously invoked from the
+ * transport).
+ */
+async function postObservedDocs(input) {
+    try {
+        // Hash on the customer side so observation state never carries the
+        // raw URL (PII hygiene + stable Convex index key shape). The
+        // orchestrator hashes the same routeUrl with the same SHA-256 to
+        // look up rows.
+        const routeHash = await sha256Hex(input.routeUrl);
+        const payload = JSON.stringify({
+            operation: 'observe',
+            input: {
+                projectId: input.projectId,
+                sessionId: input.sessionId,
+                routeHash,
+                codeVersion: input.codeVersion,
+                documentIds: input.documentIds,
+                storyTypes: input.storyTypes,
+                observationId: input.observationId,
+                renderWatermark: input.renderWatermark,
+            },
+        });
+        await fetch(input.observationFetchUrl, {
+            method: 'POST',
+            redirect: 'error',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${input.previewToken}`,
+            },
+            body: payload,
+            cache: 'no-store',
+        });
+    }
+    catch {
+        // Fire-and-forget. The tap MUST NOT propagate failures back into
+        // the RSC tree; if observation fails, the next preview's tap is
+        // a clean retry.
+    }
+}
+function createPreviewObservationId() {
+    if (typeof globalThis.crypto !== 'undefined' &&
+        typeof globalThis.crypto.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+    return `obs_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+// The arguments are semantic React-cache keys: one RSC request may construct
+// several clients, but reads from different context revisions must never be
+// grouped under apparently compatible frame metadata. A view is not required.
+const readPreviewObservationId = cache((_contextId, _contextRevision) => createPreviewObservationId());
+/**
+ * SHA-256 hex digest of a string. Lives here rather than imported from
+ * a local helper to keep the server adapter independent from Studio
+ * internals.
+ */
+async function sha256Hex(input) {
+    const bytes = new TextEncoder().encode(input);
+    const buf = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buf).set(bytes);
+    const digest = await crypto.subtle.digest('SHA-256', buf);
+    return Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+// ─────────────────────────────────────────────
+// Published-route inventory for static params and sitemaps. Build-time reads
+// deliberately omit request cookies and Preview state.
+async function buildBuildTimeClient(querySchema = CONTROL_QUERY_SCHEMA) {
+    const projectId = readProjectId();
+    const apiKey = readApiKey();
+    const infra = await resolveServerInfra(projectId);
+    return createInternalClient({
+        schema: querySchema,
+        projectId,
+        apiKey,
+        endpoint: infra.endpoint,
+        applicationBuildId: resolveStorystickApplicationBuildId(),
+        // No requestContext — build time has no viewer, no preview, no
+        // request scope. Production-snapshot reads only.
+        transport: createNextHttpTransport({ projectId, endpoint: infra.endpoint, apiKey,
+            applicationBuildId: resolveStorystickApplicationBuildId() }),
+    });
+}
+async function publishedLocaleRoutes(storyTypes) {
+    return readPublishedLocaleRoutes(await buildBuildTimeClient(), storyTypes);
+}
+async function sitemap(options) {
+    const routes = await publishedLocaleRoutes(options.storyTypes);
+    const shardSize = options.shardSize ?? STORYSTICK_SITEMAP_MAX_URLS;
+    const shards = buildStorystickSitemapShards(routes, options, shardSize);
+    if (options.id === undefined && shards.length > 1) {
+        throw new StorystickError(`This project needs ${shards.length} sitemap files. Export generateSitemaps() with site.sitemapIds(), then pass its id to site.sitemap().`, {
+            code: 'storystick/QUERY_INVALID',
+            category: 'validation',
+            recoverable: true,
+            retryable: false,
+        });
+    }
+    const id = options.id ?? 0;
+    if (!Number.isSafeInteger(id) || id < 0 || id >= shards.length) {
+        throw new RangeError(`Unknown sitemap shard id: ${id}`);
+    }
+    return shards[id];
+}
+async function sitemapIds(options) {
+    const routes = await publishedLocaleRoutes(options.storyTypes);
+    const shardSize = options.shardSize ?? STORYSTICK_SITEMAP_MAX_URLS;
+    if (!Number.isSafeInteger(shardSize) || shardSize < 1) {
+        throw new RangeError('sitemap shardSize must be a positive integer');
+    }
+    const indexableCount = routes.filter((route) => (!options.locale || route.locale === options.locale) && route.seo.indexable && route.seo.canonicalUrl === undefined).length;
+    return Array.from({ length: Math.max(1, Math.ceil(indexableCount / shardSize)) }, (_, id) => ({ id }));
+}
+/** Published paths for the optional `[[...pathname]]` route convention. */
+async function routes(storyTypes) {
+    const entries = await publishedLocaleRoutes(storyTypes);
+    return entries.map((entry) => {
+        const pathname = normalizePathname(entry.publicPathname);
+        return {
+            pathname: pathname.length === 0 ? undefined : pathnameToSegments(pathname),
+        };
+    });
+}
+// ─────────────────────────────────────────────
+// resolvePage — ADR-094 §1 Next façade
+// ─────────────────────────────────────────────
+import { resolveStorystickPage } from '@storystick/client/adapter';
+const resolveStorystickPageCached = cache(async (cacheKey, previewSessionId, previewRoutePathname, querySchema) => {
+    const input = JSON.parse(cacheKey);
+    // The site manifest must code authored values before the client hydrates
+    // bindings and mapped zones. Coding the prepared document leaves their
+    // already-autonomous values pointing at the original, unmarked content.
+    const client = await createServerClientForLocale(querySchema ?? CONTROL_QUERY_SCHEMA, undefined, previewRoutePathname === undefined
+        ? undefined
+        : {
+            sessionId: previewSessionId ?? null,
+            routePathname: previewRoutePathname,
+        }, input.publicOrigins ? { ...await readProjectLocaleSettings(), publicOrigins: input.publicOrigins } : undefined, true);
+    return resolveStorystickPage(client, input);
+});
+function serializeResolvePageSearchParams(searchParams) {
+    const serialized = new URLSearchParams();
+    if (searchParams === undefined)
+        return '';
+    for (const [key, value] of Object.entries(searchParams)) {
+        if (typeof value === 'string') {
+            serialized.append(key, value);
+            continue;
+        }
+        if (Array.isArray(value)) {
+            for (const item of value)
+                serialized.append(key, item);
+        }
+    }
+    return serialized.toString();
+}
+function previewRequestFromResolvePage(searchParams, publicPathname) {
+    if (searchParams === undefined)
+        return undefined;
+    const serialized = serializeResolvePageSearchParams(searchParams);
+    const browserPathname = publicPathname.length === 0
+        ? '/'
+        : `/${publicPathname}`;
+    const rawSessionId = searchParams[PREVIEW_SESSION_QUERY_PARAM];
+    const draftDocumentId = readPreviewDraftDocumentId(serialized);
+    if (rawSessionId === undefined) {
+        if (draftDocumentId)
+            throw new StorystickPreviewDraftError('A document destination requires a Preview view.');
+        return undefined;
+    }
+    // Duplicate selectors are ambiguous and fail closed. A normal Next page
+    // receives the single selector left by the activation redirect.
+    const sessionId = typeof rawSessionId === 'string'
+        ? readPreviewSessionIdFromSearch(`${PREVIEW_SESSION_QUERY_PARAM}=${encodeURIComponent(rawSessionId)}`)
+        : null;
+    if (!sessionId)
+        throw new StorystickError('The Preview view selector is ambiguous or invalid.', {
+            code: 'storystick/PREVIEW_CONTEXT_INVALID', category: 'validation', recoverable: true, retryable: false,
+        });
+    return {
+        sessionId,
+        routePathname: serialized.length === 0
+            ? browserPathname
+            : `${browserPathname}?${serialized}`,
+    };
+}
+export async function resolvePage(input) {
+    const publicPathname = normalizePathname(input.pathname);
+    const pageSelection = previewRequestFromResolvePage(input.searchParams, publicPathname);
+    const previewRequest = pageSelection ? bindRequestPreviewSelection(pageSelection) : readRequestPreviewSelection();
+    const previewDraft = await resolvePreviewDraftForResolvedPage(previewRequest);
+    if (previewDraft?.localeSettings) {
+        const localeContext = localeContextForPreviewDraft(input.locale ? publicPathnameForLocale(input.pathname, input.locale, previewDraft.localeSettings) : input.pathname, previewDraft.localeSettings);
+        if (localeContext) {
+            if (input.publicOrigins) {
+                localeContext.publicOrigins = input.publicOrigins;
+                if (input.publicOrigins[localeContext.locale])
+                    localeContext.publicPathname = '/' + localeContext.pathname;
+            }
+            const rawInitialLocale = previewDraft.document._locale;
+            const initialLocale = isRecord(rawInitialLocale)
+                ? rawInitialLocale.code
+                : undefined;
+            const localizedPreviewDraft = previewDraft.target?.kind === 'template' ||
+                initialLocale === localeContext.locale
+                ? previewDraft
+                : await resolvePreviewDraftPayload(localeContext.locale, previewRequest?.sessionId, previewRequest?.routePathname);
+            if (localizedPreviewDraft) {
+                await bindRequestLocaleContext(localeContext);
+                const draft = localizedPreviewDraft.document;
+                const canonicalPathname = pathnameForPreviewDraft(draft);
+                // A persisted address replaces the preview-only destination. The same
+                // route resolver remains responsible for rendering the document there.
+                if (readPreviewDraftDocumentId(serializeResolvePageSearchParams(input.searchParams)) &&
+                    typeof draft.resolvedPathname === 'string') {
+                    const destination = input.publicOrigins?.[localeContext.locale]
+                        ? '/' + canonicalPathname
+                        : publicPathnameForLocale(canonicalPathname, localeContext.locale, previewDraft.localeSettings);
+                    return {
+                        type: 'redirect', permanent: false,
+                        redirectTo: previewDraftHref(appendSearchParamsToRedirect(destination, input.searchParams ?? {}), null),
+                    };
+                }
+                // The draft payload resolves the destination, just like a pathname
+                // lookup. Read document content through the same query lifecycle as
+                // addressed pages so render values carry scope, receipts and page identity.
+                const content = localizedPreviewDraft.target?.kind === 'document' && input.querySchema
+                    ? await readPreviewDraftPageContent(draft, input.querySchema, localeContext, previewRequest)
+                    : draft;
+                const { data, document } = await prepareResolvedPageRoute({
+                    declaration: input.data,
+                    querySchema: input.querySchema,
+                    document: content,
+                    storyType: typeof draft.storyType === 'string' ? draft.storyType : 'page',
+                    localeContext,
+                    previewRequest,
+                    sessionId: previewRequest?.sessionId,
+                });
+                const rawDraftLocale = draft._locale;
+                const draftLocale = isRecord(rawDraftLocale) ? rawDraftLocale : {};
+                return {
+                    type: 'document',
+                    document,
+                    storyType: typeof draft.storyType === 'string' ? draft.storyType : 'page',
+                    canonicalPathname,
+                    publicPathname: localeContext.publicPathname,
+                    localeContext,
+                    primaryLocale: localizedPreviewDraft.routeAlternates?.primaryLocale ??
+                        (typeof draftLocale.primaryLocale === 'string'
+                            ? draftLocale.primaryLocale
+                            : localeContext.defaultLocale),
+                    alternates: localizedPreviewDraft.routeAlternates?.alternates ?? {},
+                    seo: previewDocumentSeo(draft),
+                    ...(data === undefined ? {} : { data }),
+                };
+            }
+        }
+    }
+    if (previewRequest && readPreviewDraftDocumentId(previewRequest.routePathname.split('?')[1] ?? '')) {
+        return { type: 'notFound' };
+    }
+    const route = await resolveStorystickPageCached(stableStringify({
+        pathname: publicPathname,
+        locale: input.locale,
+        publicOrigins: input.publicOrigins,
+        ...(input.storyTypes ? { storyTypes: [...input.storyTypes] } : {}),
+    }), previewRequest?.sessionId, previewRequest?.routePathname, input.querySchema);
+    if (route.type === 'redirect') {
+        return input.searchParams === undefined
+            ? route
+            : {
+                ...route,
+                redirectTo: appendSearchParamsToRedirect(route.redirectTo, input.searchParams),
+            };
+    }
+    if (route.type === 'notFound' && route.localeContext) {
+        await bindRequestLocaleContext(route.localeContext);
+        return route;
+    }
+    if (route.type !== 'document')
+        return route;
+    await bindRequestLocaleContext(route.localeContext);
+    const { data, document } = await prepareResolvedPageRoute({
+        declaration: input.data,
+        querySchema: input.querySchema,
+        document: route.document,
+        storyType: route.storyType,
+        localeContext: route.localeContext,
+        previewRequest,
+    });
+    return {
+        ...route,
+        ...(data === undefined ? {} : { data }),
+        document,
+    };
+}
+async function readPreviewDraftPageContent(destination, querySchema, localeContext, previewRequest) {
+    const client = await createServerClientForLocale(querySchema, localeContext.locale, previewRequest, localeContext, { documentId: destination.documentId, locale: localeContext.locale, publicPathname: localeContext.publicPathname });
+    const query = {
+        version: 2,
+        target: { kind: 'documents', storyType: destination.storyType },
+        selection: { mode: 'all' },
+        cardinality: 'one',
+        address: { kind: 'id', value: destination.documentId },
+        // Destination resolution remains exact-locale. Rendering composes its
+        // inherited fields, just like any other addressed document read.
+        locale: { code: localeContext.locale, fallback: 'configured' },
+        generatedSchemaFingerprint: querySchema.fingerprint,
+    };
+    const result = await getInternalClientRuntime(client).executionHost.executeCompiled(query, stableStringify(query));
+    assertExactQueryResult(result);
+    if (!result.data || result.data.documentId !== destination.documentId || result.data.storyType !== destination.storyType) {
+        throw new StorystickPreviewDraftError('The Preview draft destination changed before its content could be read.');
+    }
+    return result.data;
+}
+async function prepareResolvedPageRoute(input) {
+    // Locale routing must be attached before content values are prepared: the
+    // preparation pass captures this document as each value's immutable origin.
+    // Public and Preview draft routes deliberately share this exact boundary.
+    attachDocumentLocaleRouting(input.document, input.localeContext);
+    const [data, document] = await Promise.all([
+        resolveDeclaredPageData({
+            declaration: input.declaration,
+            querySchema: input.querySchema,
+            document: input.document,
+            storyType: input.storyType,
+            localeContext: input.localeContext,
+            previewRequest: input.previewRequest,
+        }),
+        resolvePageRouteDocumentForRender({
+            document: input.document,
+            sessionId: input.sessionId,
+            pathname: input.localeContext.publicPathname,
+            querySchema: input.querySchema,
+        }),
+    ]);
+    return { data, document };
+}
+async function resolveDeclaredPageData(input) {
+    if (input.declaration === undefined)
+        return undefined;
+    const entries = Object.entries(input.declaration);
+    if (entries.length === 0)
+        return {};
+    if (!input.querySchema) {
+        throw new TypeError('storystick/QUERY_INVALID: resolvePage data requires querySchema.');
+    }
+    const querySchema = input.querySchema;
+    let sliceTypes;
+    const getSliceTypes = () => {
+        sliceTypes ??= collectPreviewRouteDocumentSliceTypes(input.document);
+        return sliceTypes;
+    };
+    const resolved = await Promise.all(entries.map(async ([key, declaration]) => {
+        if (!pageDataDeclarationMatchesRoute({
+            declaration,
+            storyType: input.storyType,
+            sliceTypes: getSliceTypes,
+        })) {
+            return [key, []];
+        }
+        const rows = await readStorystickList({
+            querySchema,
+            storyType: declaration.query,
+            first: declaration.first,
+            localeContext: input.localeContext,
+            previewRequest: input.previewRequest,
+        });
+        return [key, rows];
+    }));
+    return Object.fromEntries(resolved);
+}
+function pageDataDeclarationMatchesRoute(input) {
+    const conditions = input.declaration.for;
+    if (conditions === undefined || conditions.length === 0)
+        return true;
+    for (const condition of conditions) {
+        if (typeof condition === 'string') {
+            if (input.sliceTypes().has(condition))
+                return true;
+            continue;
+        }
+        if (condition.storyType === input.storyType)
+            return true;
+    }
+    return false;
+}
+async function readStorystickList(input) {
+    const context = input.localeContext ??
+        (readBoundRequestLocaleContext() ? await readRequestLocaleContext() : undefined);
+    return readGeneratedListCached(input.querySchema, input.storyType, input.first, context?.synthetic ? undefined : context?.locale, input.previewRequest?.sessionId, input.previewRequest?.routePathname, context?.publicOrigins ? stableStringify(context) : undefined);
+}
+const readGeneratedListCached = cache(async (querySchema, storyType, requestedFirst, locale, previewSessionId, previewRoutePathname, routingKey) => {
+    if (!Object.prototype.hasOwnProperty.call(querySchema.stories, storyType)) {
+        throw new TypeError(`storystick/QUERY_INVALID: Unknown document story ${JSON.stringify(storyType)}.`);
+    }
+    const client = await createServerClientForLocale(querySchema, locale, previewRoutePathname === undefined
+        ? undefined
+        : {
+            sessionId: previewSessionId ?? null,
+            routePathname: previewRoutePathname,
+        }, routingKey ? JSON.parse(routingKey) : undefined);
+    const maximum = requestedFirst === undefined ? 10_000 : Math.min(10_000, requestedFirst);
+    if (!Number.isSafeInteger(maximum) || maximum < 1) {
+        throw new TypeError('storystick/QUERY_INVALID: page data first must be a positive integer.');
+    }
+    const documents = [];
+    const cursors = new Set();
+    let cursor;
+    for (let page = 0; page < 100 && documents.length < maximum; page += 1) {
+        let query = client.query(storyType).selectAll();
+        if (locale)
+            query = query.locale(locale);
+        const result = await query.page({
+            first: Math.min(100, maximum - documents.length),
+            ...(cursor ? { after: cursor } : {}),
+        }).execute();
+        assertExactQueryResult(result);
+        documents.push(...result.data);
+        const next = result.pageInfo.endCursor;
+        if (!result.pageInfo.hasNextPage)
+            return documents;
+        if (!next || cursors.has(next)) {
+            throw new StorystickError('Query pagination returned a repeated cursor.', {
+                code: 'storystick/QUERY_CURSOR_INVALID',
+                category: 'system',
+                retryable: false,
+            });
+        }
+        cursors.add(next);
+        cursor = next;
+    }
+    if (documents.length >= maximum)
+        return documents;
+    throw new StorystickError('Query pagination exceeded the 100-page safety bound.', {
+        code: 'storystick/QUERY_PROTOCOL', category: 'system', retryable: false,
+    });
+});
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+    }
+    const record = value;
+    return `{${Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(',')}}`;
+}
+/**
+ * Resolve the render-time Source Graph closure for a route body.
+ *
+ * `resolvePage()` can attach identity for the route document itself, but app
+ * renderers often load additional QueryResults afterwards (related posts,
+ * customers, authors, tags, etc.). This helper is the server-side seam that
+ * combines the route document and the actual render context before rendering.
+ * It is a no-op outside Preview V2.
+ */
+export async function resolveStorystickRouteRender({ document, context, pathname, }) {
+    const runtime = previewRuntimeForReads(document, context);
+    const config = runtime?.config.resolveSemanticConfig() ?? resolvePreviewProvenanceConfig();
+    if (!config.enabled)
+        return { document, context };
+    const existingRender = readPreviewProvenanceRouteRender(document);
+    if (existingRender === null && pathname === undefined) {
+        return { document, context };
+    }
+    const manifest = runtime ? await runtime.config.resolveSemanticManifest() : {};
+    const publicSidecar = existingRender?.frame.publicSidecar ?? null;
+    const sourceDocument = stripPreviewRouteRenderMetadata(document);
+    const frame = await unstable_buildPreviewRouteDocumentFrameWithRuntime({
+        document: sourceDocument,
+        context,
+        pathname: normalizeRoutePathname(pathname ?? pathnameFromRouteHash(existingRender?.frame.routeHash) ?? '/'),
+        manifest,
+        routeHash: existingRender?.frame.routeHash,
+        sessionId: existingRender?.frame.sessionId,
+        codeVersion: publicSidecar?.codeVersion,
+        renderId: publicSidecar?.renderId,
+        generation: publicSidecar?.generation,
+        fixture: config.fixture,
+    }, runtime);
+    if (frame === null)
+        return { document, context };
+    if (runtime)
+        bindPreviewRuntimeToSidecar(frame.publicSidecar, runtime);
+    const renderContext = attachPreviewRouteRenderContext((frame.codedContext ?? context), frame);
+    return {
+        document: attachPreviewRouteRenderContext(sourceDocument, frame),
+        context: renderContext,
+    };
+}
+async function resolvePageRouteDocumentForRender({ document, sessionId, pathname, querySchema, }) {
+    // A generated manifest enables the capability, not Preview for public traffic.
+    // Gate before planning/noStore/cookie reads so native public pages retain ISR.
+    if (!sessionId && !getPreviewReadObservation(document)?.readContext)
+        return document;
+    const siteRuntime = querySchema ? previewRuntimeForSchema(querySchema) : undefined;
+    bindPreviewRuntimeToReads(document, siteRuntime);
+    // The page also owns the manifest for session-bound template payloads,
+    // which have no document-query observation.
+    const runtime = previewRuntimeForReads(document) ?? siteRuntime;
+    return prepareContentValues(runtime ? await prepareOrdinaryPreviewRead(document, runtime, {
+        sessionId, pathname: normalizeRoutePathname(pathname),
+    }) : document, true, true);
+}
+function stripPreviewRouteRenderMetadata(document) {
+    if (!isRecord(document))
+        return document;
+    const { __ssPreviewProvenance: _previewProvenance, __ssPreviewRouteFrame: _previewRouteFrame, __ssPreviewRouteRender: _previewRouteRender, ...rest } = document;
+    return rest;
+}
+function pathnameFromRouteHash(routeHash) {
+    if (routeHash === undefined)
+        return null;
+    if (!routeHash.startsWith('route:'))
+        return null;
+    const pathname = routeHash.slice('route:'.length);
+    return pathname.length > 0 ? pathname : '/';
+}
+function normalizeRoutePathname(pathname) {
+    const canonical = normalizePathname(pathname);
+    return canonical.length === 0 ? '/' : `/${canonical}`;
+}
+async function resolvePreviewDraftForResolvedPage(previewRequest) {
+    if (previewRequest !== undefined) {
+        if (!previewRequest.sessionId)
+            return null;
+        return resolvePreviewDraftPayload(undefined, previewRequest.sessionId, previewRequest.routePathname);
+    }
+    return null;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// ─────────────────────────────────────────────
+// resolvePreviewDraft + isPreviewDraftActive — ADR-099 D2
+// ─────────────────────────────────────────────
+//
+// Customer's root layout calls `resolvePreviewDraft()` and substitutes
+// `children` with `<Renderer document={draft}/>` when a draft is active.
+// The fast path (no `_ss_session` selector) bails before any
+// Convex call, preserving prod traffic at zero cost.
+//
+// `isPreviewDraftActive()` is the customer guard helper for nested
+// Server Components: `if (await isPreviewDraftActive()) return null`
+// short-circuits `notFound()`/`redirect()` calls in the discarded
+// page subtree. Pre-ship spike (§5.10) determines whether this is a
+// hard requirement (mixed/red OUTCOME) or a cost-optimization (green
+// OUTCOME — saves a Convex call in nested SCs that fetch draft data).
+//
+// React `cache()` scopes both reads to the current request. The session
+// guard and the draft payload fetch are cached independently: callers
+// that only need `isPreviewDraftActive()` avoid fetching document-shaped
+// content, while root layouts call `resolvePreviewDraft()` directly.
+/**
+ * Visible-failure subclass for preview-draft resolution failures
+ * (CSO-PREVIEW-1 invariant — never silent prod fallback when the editor
+ * is targeting a draft). Categorized as `'system'` to flow through the
+ * existing canonical category union; the subclass identity (via
+ * `instanceof`) is the discriminator for customer error.tsx handlers
+ * that want to render a draft-specific message.
+ */
+export class StorystickPreviewDraftError extends StorystickError {
+    constructor(message) {
+        super(message, { category: 'system' });
+    }
+}
+async function readPreviewReadState(token, endpoint, includeProjectionCheckpoint = false) {
+    const result = await previewControlClient(endpoint, token).context(includeProjectionCheckpoint ? { includeProjectionCheckpoint: true } : {});
+    if (!isRecord(result) || result.status !== 'active' || !isPreviewReadContext(result.context)) {
+        throw new StorystickError('This Preview context is no longer available.', {
+            code: 'storystick/PREVIEW_CONTEXT_INVALID', category: 'auth', recoverable: true, retryable: false,
+        });
+    }
+    const checkpoint = result.projectionCheckpoint;
+    return {
+        context: result.context,
+        ...(isPreviewProjectionGenerationSignal(checkpoint) ? { projectionCheckpoint: {
+                generation: checkpoint.generation, status: checkpoint.status,
+                ...(checkpoint.projectedThroughSeq === undefined ? {} : { projectedThroughSeq: checkpoint.projectedThroughSeq }),
+                ...(checkpoint.projectionHash === undefined ? {} : { projectionHash: checkpoint.projectionHash }),
+                ...(checkpoint.lensHash === undefined ? {} : { lensHash: checkpoint.lensHash }),
+            } } : {}),
+    };
+}
+const readPreviewStateForRequest = cache((token, deploymentUrl) => readPreviewReadState(token, deploymentUrl, true));
+async function readPreviewContextForRequest(token, deploymentUrl) {
+    return (await readPreviewStateForRequest(token, deploymentUrl)).context;
+}
+async function readPreviewContext(token, deploymentUrl) {
+    return (await readPreviewReadState(token, deploymentUrl)).context;
+}
+/** @internal The existing server mount attests the same request as its page.
+ * No cookies or infrastructure reads are added to public production renders. */
+export const readPreviewServerRenderReceipt = cache(async (projectOverride) => {
+    if (process.env.NODE_ENV === 'production' && !process.env.STORYSTICK_LANE_ID &&
+        !(await draftMode()).isEnabled)
+        return null;
+    const projectId = projectOverride ?? readProjectId();
+    const apiKey = readApiKey();
+    const infra = await resolveServerInfra(projectId);
+    const fields = await resolveCurrentPreviewGrantAccess({
+        projectId, apiKey, endpoint: infra.endpoint,
+        requestOrigin: await deriveRequestOrigin(),
+        applicationBuildId: resolveStorystickApplicationBuildId(),
+    });
+    if (!fields)
+        return null;
+    const { context: readContext, projectionCheckpoint } = await readPreviewStateForRequest(fields.token, infra.endpoint);
+    return {
+        readContext,
+        renderId: readPreviewObservationId(readContext.contextId, readContext.revision),
+        ...(projectionCheckpoint ? { projectionCheckpoint } : {}),
+    };
+});
+function parsePreviewDraftTarget(value, fallbackDraftDocumentId) {
+    if (value && typeof value === 'object') {
+        const target = value;
+        if ((target.kind === 'document' || target.kind === 'template') &&
+            typeof target.id === 'string') {
+            return { kind: target.kind, id: target.id };
+        }
+    }
+    return fallbackDraftDocumentId
+        ? { kind: 'document', id: fallbackDraftDocumentId }
+        : null;
+}
+async function fetchPreviewSessionRow(fields, projectId, sessionId) {
+    const infra = await resolveServerInfra(projectId);
+    const client = previewControlClient(infra.endpoint, fields.token);
+    let raw;
+    try {
+        raw = await client.session({ sessionId, mode: 'routing-only' });
+    }
+    catch (error) {
+        const { code } = mapPreviewSessionError(error);
+        // Missing routing metadata cannot supply a perspective. The separate
+        // context read still validates this exact view and fails closed if absent.
+        if (code === 'PREVIEW_ADMISSION_SUPERSEDED' || code === 'PREVIEW_VIEW_UNAVAILABLE')
+            return null;
+        // A new Studio view may load while the origin still carries another
+        // admission's cookie. Keep the server read closed, but let the existing
+        // whole-render recovery retry once AFTER the browser authenticates this
+        // exact view. Otherwise Next labels this admission race a customer error
+        // and Studio abandons the healthy replacement as soon as auth becomes ready.
+        if (code === 'PREVIEW_GRANT_FORBIDDEN' && error instanceof Error) {
+            Object.assign(error, { digest: PREVIEW_CONTEXT_SUPERSEDED_DIGEST });
+        }
+        throw error;
+    }
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const row = raw;
+    const draftDocumentId = typeof row.draftDocumentId === 'string'
+        ? row.draftDocumentId
+        : null;
+    const draftTarget = parsePreviewDraftTarget(row.draftTarget, draftDocumentId);
+    return {
+        sessionId: String(row.sessionId ?? ''),
+        previewedDocumentId: String(row.previewedDocumentId ?? ''),
+        pathname: String(row.pathname ?? ''),
+        activeVariantId: typeof row.activeVariantId === 'string' ? row.activeVariantId : null,
+        activeReleaseId: typeof row.activeReleaseId === 'string' ? row.activeReleaseId : null,
+        parentOrigin: String(row.parentOrigin ?? ''),
+        previewOrigin: typeof row.previewOrigin === 'string' ? row.previewOrigin : undefined,
+        contentRevision: typeof row.contentRevision === 'number' ? row.contentRevision : 0,
+        draftDocumentId,
+        draftTarget,
+    };
+}
+/**
+ * Fetch the preview session row. Cached per-request via React.cache so
+ * `resolvePreviewDraft()` and `isPreviewDraftActive()` share the same
+ * round-trip when both are called in the same RSC render.
+ *
+ * Returns `null` when:
+ *  - The `_ss_session` selector is absent (prod traffic fast path).
+ *
+ * Throws / propagates when preview state is present but invalid or when
+ * the underlying query fails — e.g. malformed cookie,
+ * `PREVIEW_PROJECT_MISMATCH`, or `PREVIEW_GRANT_EXPIRED`. The editor must see the
+ * failure, never silently fall back to prod content.
+ */
+const readPreviewSessionForRequest = cache(fetchPreviewSessionRow);
+const _fetchPreviewSession = cache(async (previewSessionId) => {
+    const sessionId = previewSessionId;
+    if (!sessionId)
+        return null;
+    const projectId = readProjectId();
+    const [infra, requestOrigin] = await Promise.all([
+        resolveServerInfra(projectId),
+        deriveRequestOrigin(),
+    ]);
+    const fields = await resolveCurrentPreviewGrantAccess({
+        projectId,
+        requestOrigin,
+        endpoint: infra.endpoint,
+        apiKey: readApiKey(),
+        applicationBuildId: resolveStorystickApplicationBuildId(),
+    });
+    if (!fields)
+        return null;
+    return readPreviewSessionForRequest(fields, projectId, sessionId);
+});
+const _fetchPreviewDraftPayload = cache(async (previewSessionId, locale, draftDocumentId) => {
+    const sessionId = previewSessionId;
+    if (!sessionId)
+        return null;
+    const projectId = readProjectId();
+    const [infra, requestOrigin] = await Promise.all([
+        resolveServerInfra(projectId),
+        deriveRequestOrigin(),
+    ]);
+    const fields = await resolveCurrentPreviewGrantAccess({
+        projectId,
+        requestOrigin,
+        endpoint: infra.endpoint,
+        apiKey: readApiKey(),
+        applicationBuildId: resolveStorystickApplicationBuildId(),
+    });
+    if (!fields)
+        return null;
+    // Resolve the admitted context and routing metadata together. An ordinary
+    // addressed page has no draft payload; do not add a serialized empty read.
+    const [readContext, session] = await Promise.all([
+        readPreviewContextForRequest(fields.token, infra.endpoint),
+        draftDocumentId ? null : readPreviewSessionForRequest(fields, projectId, sessionId),
+    ]);
+    if (!draftDocumentId && !session?.draftTarget)
+        return null;
+    const client = previewControlClient(infra.endpoint, fields.token);
+    try {
+        const payload = await client.draft({
+            sessionId,
+            ...(draftDocumentId ? { draftDocumentId } : {}),
+            ...(locale === undefined ? {} : { locale }),
+            contextId: readContext.contextId,
+            revision: readContext.revision,
+        });
+        return { payload, session };
+    }
+    catch (cause) {
+        const { code } = mapPreviewSessionError(cause);
+        if (code === 'PREVIEW_ADMISSION_SUPERSEDED' || code === 'PREVIEW_VIEW_UNAVAILABLE')
+            return null;
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        throw new StorystickPreviewDraftError(`Preview draft payload could not be resolved. ${detail}`);
+    }
+});
+/**
+ * Resolve an explicitly selected draft in a native page request. Independent
+ * layouts use site.client() and keep their own content; they do not substitute
+ * their children. Template prototypes use the same document-shaped payload.
+ *
+ * @returns The draft `QueryResult` when Cas A is active and the doc is
+ * routable. `null` otherwise (prod traffic, Tier 1 path, doc not in Cas
+ * A scope).
+ *
+ * @throws `StorystickPreviewDraftError` when the row references a draft
+ * target that cannot be resolved (deleted / stale / cross-tenant
+ * session). CSO-PREVIEW-1: the editor must see a visible failure, never
+ * silent prod fallback.
+ *
+ * Wrapped in `React.cache()` — repeated calls within one RSC render
+ * share the same Promise.
+ */
+async function resolvePreviewDraftPayload(locale, previewSessionId, previewRoutePathname) {
+    const requestedDocumentId = previewRoutePathname === undefined
+        ? null
+        : readPreviewDraftDocumentId(new URL(previewRoutePathname, 'https://preview.invalid').search);
+    const result = await _fetchPreviewDraftPayload(previewSessionId, locale, requestedDocumentId);
+    const raw = result?.payload;
+    const session = result?.session;
+    if (!raw || (!session && !requestedDocumentId))
+        return null;
+    if (raw.isRoutable !== true)
+        return null; // Cas A scope only (defense)
+    const settings = raw.__ssPreviewLocaleSettings;
+    const routeAlternates = raw.__ssPreviewRouteAlternates;
+    const { __ssPreviewLocaleSettings: _localeSettings, __ssPreviewRouteAlternates: _routeAlternates, ...doc } = raw;
+    // The draft payload is fetched outside the provenance transport, so it
+    // carries no read identity of its own. Tag it with its session target and
+    // the schema-derived assets carried by `_assets`. Without the latter, an
+    // asset replacement advances only `asset:<id>` while this direct draft path
+    // keeps watching the document/template clock and therefore stays stale
+    // until an unrelated content edit happens.
+    const target = requestedDocumentId
+        ? { kind: 'document', id: requestedDocumentId }
+        : session?.draftTarget ?? null;
+    const targetDependencies = target?.kind === 'template'
+        ? [{ kind: 'template', templateId: target.id }]
+        : target?.kind === 'document'
+            ? [
+                {
+                    kind: 'document',
+                    documentId: target.id,
+                    reason: 'scope-document',
+                },
+            ]
+            : [];
+    attachPreviewFrameDependencies(doc, [
+        ...targetDependencies,
+        ...previewAssetDependenciesFromValue(doc),
+    ]);
+    return {
+        document: doc,
+        target,
+        ...(isRecord(routeAlternates) &&
+            typeof routeAlternates.primaryLocale === 'string' &&
+            isRecord(routeAlternates.alternates)
+            ? {
+                routeAlternates: {
+                    primaryLocale: routeAlternates.primaryLocale,
+                    alternates: Object.fromEntries(Object.entries(routeAlternates.alternates).filter((entry) => typeof entry[1] === 'string')),
+                },
+            }
+            : {}),
+        ...(isRecord(settings)
+            ? {
+                localeSettings: settings,
+            }
+            : {}),
+    };
+}
+const resolvePreviewDraftForLocale = cache(async (locale, previewSessionId) => (await resolvePreviewDraftPayload(locale, previewSessionId))?.document ?? null);
+export function resolvePreviewDraft(options) {
+    return resolvePreviewDraftForLocale(options.locale, options.sessionId);
+}
+/** Advanced draft guard for an explicitly selected view. Prefer site.resolvePage for CMS routes. */
+export const isPreviewDraftActive = cache(async (sessionId) => {
+    const session = await _fetchPreviewSession(sessionId);
+    return session?.draftTarget != null;
+});
+/** Immutable configuration; sessions and request data are resolved per render. */
+export function createSite(options) {
+    const schema = bindSiteQuerySchema(options.definition.querySchema, options.definition.previewProvenanceEditableTextPathManifest);
+    if (options.publicRendering === 'static') {
+        const id = deploymentId();
+        if (!id || !/^[A-Za-z0-9:_-]{1,255}$/.test(id)) {
+            throw new TypeError('Static public rendering requires a unique VERCEL_DEPLOYMENT_ID or STORYSTICK_DEPLOYMENT_ID per compilation (1–255 URL-safe characters).');
+        }
+        staticSiteSchemas.add(schema);
+    }
+    const storyTypes = Object.freeze([...(options.storyTypes ?? Object.entries(schema.stories)
+            .filter(([, story]) => story.addresses.includes('pathname'))
+            .map(([name]) => name))]);
+    const publicOrigins = options.publicOrigins ? normalizePublicLocaleOrigins(options.publicOrigins) : undefined;
+    const domainLocale = options.domainLocale;
+    if (domainLocale && !publicOrigins?.[domainLocale])
+        throw new TypeError('domainLocale must have a configured public origin.');
+    const defaultLocale = options.locale ?? domainLocale;
+    const configuredSiteUrl = options.siteUrl?.toString();
+    for (const name of storyTypes) {
+        if (!schema.stories[name]?.addresses.includes('pathname'))
+            throw new TypeError(`Story "${name}" does not have a pathname address.`);
+    }
+    const resolve = (input) => resolvePage({ ...input, ...(domainLocale ? { locale: input.locale ?? domainLocale } : {}), publicOrigins, querySchema: schema, storyTypes: [...storyTypes] });
+    const client = async (input = {}) => {
+        const sliceLocale = await readNativeSliceLocale();
+        const explicitLocale = input.locale ?? sliceLocale ?? defaultLocale;
+        const defaults = explicitLocale === undefined || publicOrigins ? await readProjectLocaleSettings() : undefined;
+        const locale = explicitLocale ?? (defaults?.synthetic ? undefined : defaults?.defaultLocale);
+        return createServerClientForLocale(schema, locale, undefined, defaults ? { ...defaults, ...(publicOrigins ? { publicOrigins } : {}) } : undefined);
+    };
+    const siteUrl = () => {
+        const value = configuredSiteUrl ?? process.env.STORYSTICK_SITE_URL;
+        if (!value)
+            throw new TypeError('Set siteUrl in createSite, or STORYSTICK_SITE_URL, for canonical URLs and sitemaps.');
+        const url = new URL(value);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+            throw new TypeError('Storystick siteUrl must be an absolute HTTP(S) URL without credentials, search or hash.');
+        }
+        return url;
+    };
+    return Object.freeze({
+        client,
+        async renderReceipt(input) {
+            if ((await draftMode()).isEnabled)
+                return null;
+            const buildId = resolveStorystickApplicationBuildId();
+            if (!buildId)
+                throw new TypeError('Public render receipts require an application build ID.');
+            const token = options.publicRendering === 'request' ? (await headers()).get(PUBLIC_RENDER_CHALLENGE_HEADER) : undefined;
+            return createPublicRenderReceipt({ ...input, projectId: readProjectId(), buildId,
+                ...(isPublicRenderChallenge(token) ? { requestToken: token } : {}),
+                deploymentId: input.deploymentId ?? deploymentId() });
+        },
+        async publicationManifest(input = {}) {
+            const buildId = resolveStorystickApplicationBuildId();
+            const resolvedDeploymentId = input.deploymentId ?? deploymentId();
+            if (!buildId || !resolvedDeploymentId)
+                throw new TypeError('Publication manifests require build and deployment IDs.');
+            const routes = await readPublishedLocaleRoutes(await client(), storyTypes);
+            return createPublicSiteManifest({ projectId: readProjectId(), buildId, deploymentId: resolvedDeploymentId, results: [routes],
+                sitemapPath: input.sitemapPath ?? '/sitemap.xml',
+                routes: routes.filter(route => !domainLocale || route.locale === domainLocale).map(route => ({
+                    pathname: domainLocale ? '/' + route.pathname.replace(/^\/+/, '') : route.publicPathname,
+                    indexable: route.seo.indexable && route.seo.canonicalUrl === undefined,
+                })) });
+        },
+        /** Project default locale, or the explicit locale configured for this site. */
+        async locale() {
+            return defaultLocale ?? (await readProjectLocaleSettings()).defaultLocale;
+        },
+        async resolvePage(input) {
+            if (!('params' in input))
+                return resolve(input);
+            const params = await input.params;
+            // Keep public ISR static: only Preview and redirects need searchParams.
+            const preview = process.env.NODE_ENV !== 'production' ||
+                !!process.env.STORYSTICK_LANE_ID || (await draftMode()).isEnabled;
+            const searchParams = preview ? await input.searchParams : undefined;
+            const route = await resolve({ pathname: params.pathname, searchParams });
+            return route.type === 'redirect' ? { ...route,
+                redirectTo: appendSearchParamsToRedirect(route.redirectTo, searchParams ?? await input.searchParams ?? {}),
+            } : route;
+        },
+        params: async () => domainLocale
+            ? (await publishedLocaleRoutes(storyTypes)).filter(entry => entry.locale === domainLocale).map(entry => ({
+                pathname: normalizePathname(entry.pathname) ? pathnameToSegments(entry.pathname) : undefined,
+            }))
+            : routes(storyTypes),
+        /** Only real published translations; no prefix substitution in language switches. */
+        alternates(route) {
+            return route.type === 'document' ? publishedLocaleHrefs(route.alternates, {
+                ...route.localeContext, ...(publicOrigins ? { publicOrigins } : {}),
+            }) : {};
+        },
+        async metadata(route, metadata = {}) {
+            const contextualClient = await client();
+            const preview = !!getInternalClientRuntime(contextualClient)?.requestContext?.previewToken;
+            if (route.type !== 'document')
+                return preview ? { robots: { ...STORYSTICK_PREVIEW_ROBOTS } } : {};
+            return stripPreviewProvenance({
+                ...metadata,
+                alternates: { ...metadata.alternates, ...storystickAlternates(route, { siteUrl: siteUrl(), publicOrigins }) },
+                robots: preview ? { ...STORYSTICK_PREVIEW_ROBOTS } : !route.seo.indexable ? { index: false } : metadata.robots,
+            });
+        },
+        handlers: Object.freeze(createRouteHandler({
+            ...options.routes,
+            migrationReadback: async () => {
+                const artifactId = resolveStorystickApplicationBuildId();
+                const artifactDigest = resolveStorystickApplicationBuildDigest();
+                if (!artifactId || !artifactDigest)
+                    return null;
+                const current = await fetchCurrentSchema(await createServerClientForLocale(schema, undefined), { cache: 'no-store' });
+                return {
+                    projectId: readProjectId(),
+                    artifactId,
+                    artifactDigest,
+                    schemaVersion: current?.version ?? null,
+                    querySchemaFingerprint: schema.fingerprint,
+                    publication: { version: 2, rendering: options.publicRendering ?? 'unqualified', receipts: options.publicRendering === 'request' },
+                };
+            },
+        })),
+        sitemap: (input = {}) => sitemap({ ...input, siteUrl: siteUrl(), publicOrigins, locale: domainLocale, storyTypes }),
+        sitemapIds: (input = {}) => sitemapIds({ ...input, locale: domainLocale, storyTypes }),
+    });
+}