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

package/dist/server/grant.d.ts

@@ -0,0 +1,128 @@
+import { type PreviewAuthoringAdmission } from '../authoring/runtime-contract.js';
+export declare const PREVIEW_CAPABILITY_COOKIE = "__storystick_preview";
+export declare const PREVIEW_ACTIVATION_QUERY_PARAM = "_ss_activation";
+export type PreviewGrantCookie = {
+    v: 2;
+    grantId: string;
+    grantToken: string;
+    grantExpiresAt: number;
+    projectId: string;
+    previewOrigin: string;
+    accessToken: string;
+    accessExpiresAt: number;
+    /** First server-observed epoch, retained for the grant lifetime. */
+    contentShapeCapability?: string;
+    /** Build that minted this grant's access token; a redeploy must reopen Preview. */
+    applicationBuildId?: string;
+};
+export type PreviewGrantActivationResponse = {
+    admissionSequence: number;
+    grantToken: string;
+    grantId: string;
+    grantExpiresAt: number;
+    token: string;
+    tokenExpiresIn: number;
+    sessionId: string;
+    projectId: string;
+    previewOrigin: string;
+    contentShapeCapability: string;
+};
+export type PreviewGrantExchangeResponse = {
+    admissionSequence?: number;
+    token: string;
+    tokenExpiresIn: number;
+    projectId: string;
+    previewOrigin: string;
+    grantId?: string;
+    grantExpiresAt?: number;
+    contentShapeCapability: string;
+};
+export type PreviewCookieAttributes = {
+    httpOnly: true;
+    secure: boolean;
+    sameSite: 'none' | 'lax';
+    partitioned?: true;
+    path: string;
+    maxAge: number;
+};
+type ErrorCategory = 'system' | 'auth' | 'validation' | 'conflict' | 'cancel';
+export declare class PreviewGrantExchangeError extends Error {
+    readonly code: string;
+    readonly ref: string | undefined;
+    readonly category: ErrorCategory;
+    readonly retryable: boolean;
+    readonly status: number | undefined;
+    constructor(message: string, opts: {
+        code: string;
+        ref?: string;
+        category: ErrorCategory;
+        retryable: boolean;
+        status?: number;
+    });
+}
+export declare class PreviewRedirectError extends Error {
+    constructor(message: string);
+}
+export declare class PreviewActivationError extends Error {
+    constructor(message: string);
+}
+export type PreviewGrantOperation = 'activate' | 'exchange' | 'authoring';
+export type PreviewAdapterError = {
+    status: number;
+    code: string;
+    message: string;
+    category: ErrorCategory;
+    recoverable: boolean;
+    retryable: boolean;
+    upstreamCode: string;
+    upstreamRef?: string;
+};
+export declare function classifyPreviewGrantError(err: PreviewGrantExchangeError, operation: PreviewGrantOperation): PreviewAdapterError;
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export declare function activatePreviewGrantForServer(opts: {
+    endpoint: string;
+    apiKey: string;
+    applicationBuildId?: string;
+    grantId: string;
+    activationSecret: string;
+    sessionId: string;
+    requestOrigin: string;
+    fetchImpl?: FetchLike;
+}): Promise<PreviewGrantActivationResponse>;
+export declare function exchangePreviewGrantForServer(opts: {
+    endpoint: string;
+    apiKey: string;
+    applicationBuildId?: string;
+    grantToken: string;
+    requestOrigin: string;
+    contentShapeCapability: string;
+    fetchImpl?: FetchLike;
+}): Promise<PreviewGrantExchangeResponse>;
+export declare function exchangePreviewAuthoringAdmissionForServer(opts: {
+    endpoint: string;
+    apiKey: string;
+    applicationBuildId?: string;
+    grantToken: string;
+    requestOrigin: string;
+    contentShapeCapability: string;
+    admissionId?: string;
+    fileDelegationId?: string;
+    fetchImpl?: FetchLike;
+}): Promise<PreviewAuthoringAdmission>;
+export declare function parsePreviewActivation(value: string | null): {
+    grantId: string;
+    activationSecret: string;
+};
+export declare function isSafePreviewSessionId(value: unknown): value is string;
+export declare function previewCapabilityCookieName(scope: {
+    projectId: string;
+    requestOrigin: string;
+}): string;
+export declare function previewCookieAttributes({ expiresIn, requestUrl, basePath, }: {
+    expiresIn: number;
+    requestUrl: string;
+    basePath?: string;
+}): PreviewCookieAttributes;
+export declare function assertSafePreviewRedirect(path: string, basePath?: string): string;
+export declare function previewNoStoreFetchOptions(): RequestInit;
+export {};

package/dist/server/grant.js

@@ -0,0 +1,395 @@
+import { scopedPreviewCookieName } from '@storystick/preview/identity/preview-cookie';
+/** Framework-neutral primitives for the durable PreviewGrant lifecycle. */
+import { contentShapeCapabilityHeaders } from '@storystick/types';
+import { isPreviewAuthoringAdmission } from '../authoring/runtime-contract.js';
+export const PREVIEW_CAPABILITY_COOKIE = '__storystick_preview';
+export const PREVIEW_ACTIVATION_QUERY_PARAM = '_ss_activation';
+const PREVIEW_SESSION_ID_RE = /^[A-Za-z0-9_-]{1,180}$/;
+export class PreviewGrantExchangeError extends Error {
+    code;
+    ref;
+    category;
+    retryable;
+    status;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'PreviewGrantExchangeError';
+        this.code = opts.code;
+        this.ref = opts.ref;
+        this.category = opts.category;
+        this.retryable = opts.retryable;
+        this.status = opts.status;
+    }
+}
+export class PreviewRedirectError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PreviewRedirectError';
+    }
+}
+export class PreviewActivationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PreviewActivationError';
+    }
+}
+const VALID_CATEGORIES = new Set([
+    'system',
+    'auth',
+    'validation',
+    'conflict',
+    'cancel',
+]);
+function asCategory(value) {
+    return typeof value === 'string' && VALID_CATEGORIES.has(value)
+        ? value
+        : 'system';
+}
+function bareErrorCode(code) {
+    return code.startsWith('storystick/') ? code.slice('storystick/'.length) : code;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+const HARD_GRANT_FAILURES = new Set([
+    'PREVIEW_ACTIVATION_INVALID',
+    'GRANT_INVALID',
+    'PREVIEW_GRANT_INVALID',
+    'GRANT_EXPIRED',
+    'PREVIEW_GRANT_EXPIRED',
+    'GRANT_REVOKED',
+    'PREVIEW_GRANT_REVOKED',
+    'PREVIEW_ACCESS_REVOKED',
+    'PREVIEW_GRANT_FORBIDDEN',
+    'MEMBERSHIP_REVOKED',
+    'ORIGIN_MISMATCH',
+    'PROJECT_MISMATCH',
+]);
+export function classifyPreviewGrantError(err, operation) {
+    const upstreamCode = bareErrorCode(err.code);
+    if (upstreamCode === 'PREVIEW_CONTEXT_INVALID') {
+        return {
+            status: 409,
+            code: upstreamCode,
+            message: 'This preview context or perspective is no longer available. Choose an available perspective in Studio and reopen the preview.',
+            category: 'conflict', recoverable: true, retryable: false,
+            upstreamCode: err.code,
+            ...(err.ref !== undefined && { upstreamRef: err.ref }),
+        };
+    }
+    if (upstreamCode === 'PREVIEW_PROJECT_MISMATCH') {
+        return { status: 403, code: upstreamCode,
+            message: 'This site is configured for a different Storystick project. Check the Preview URL in Studio and the site’s project connection.',
+            category: 'auth', recoverable: true, retryable: false, upstreamCode: err.code };
+    }
+    if (upstreamCode === 'CONTENT_SHAPE_RELOAD_REQUIRED') {
+        return {
+            status: 409,
+            code: upstreamCode,
+            message: 'Open Preview again from Studio to load the current content shape.',
+            category: 'conflict',
+            recoverable: true,
+            retryable: false,
+            upstreamCode: err.code,
+            ...(err.ref !== undefined && { upstreamRef: err.ref }),
+        };
+    }
+    const prefix = operation === 'activate'
+        ? 'PREVIEW_GRANT_ACTIVATION'
+        : operation === 'authoring'
+            ? 'PREVIEW_AUTHORING_ADMISSION'
+            : 'PREVIEW_GRANT_ACCESS';
+    if (upstreamCode === 'RATE_LIMITED' || err.status === 429) {
+        return {
+            status: 429,
+            code: `${prefix}_RATE_LIMITED`,
+            message: 'preview grant temporarily rate limited',
+            category: 'system',
+            recoverable: true,
+            retryable: true,
+            upstreamCode: err.code,
+            ...(err.ref !== undefined && { upstreamRef: err.ref }),
+        };
+    }
+    if (err.code === 'PREVIEW_GRANT_NETWORK') {
+        return {
+            status: 503,
+            code: `${prefix}_UNAVAILABLE`,
+            message: 'preview grant service unavailable',
+            category: 'system',
+            recoverable: true,
+            retryable: true,
+            upstreamCode: err.code,
+            ...(err.ref !== undefined && { upstreamRef: err.ref }),
+        };
+    }
+    if (HARD_GRANT_FAILURES.has(upstreamCode)) {
+        return {
+            status: err.status !== undefined && err.status >= 400 && err.status < 500
+                ? err.status
+                : 401,
+            code: `PREVIEW_${upstreamCode.replace(/^PREVIEW_/, '')}`,
+            message: 'preview grant is no longer valid',
+            category: 'auth',
+            recoverable: true,
+            retryable: false,
+            upstreamCode: err.code,
+            ...(err.ref !== undefined && { upstreamRef: err.ref }),
+        };
+    }
+    if (err.category === 'auth' || err.status === 401 || err.status === 403) {
+        return {
+            status: err.status === 403 ? 403 : 401,
+            code: `${prefix}_AUTH_FAILED`,
+            message: 'preview grant authentication failed',
+            category: 'auth',
+            recoverable: true,
+            retryable: false,
+            upstreamCode: err.code,
+            ...(err.ref !== undefined && { upstreamRef: err.ref }),
+        };
+    }
+    return {
+        status: err.status && err.status >= 400 ? err.status : 502,
+        code: `${prefix}_FAILED`,
+        message: 'preview grant exchange failed',
+        category: err.category,
+        recoverable: true,
+        retryable: err.retryable,
+        upstreamCode: err.code,
+        ...(err.ref !== undefined && { upstreamRef: err.ref }),
+    };
+}
+async function postGrantOperation(path, opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    let response;
+    try {
+        response = await fetchImpl(`${opts.endpoint}${path}`, {
+            method: 'POST',
+            // A shared in-flight exchange cannot retain future callers indefinitely.
+            ...(path.endsWith('/exchange-for-server') || path.endsWith('/authoring-for-server')
+                ? { signal: AbortSignal.timeout(10_000) }
+                : {}),
+            headers: {
+                Authorization: `Bearer ${opts.apiKey}`,
+                'Content-Type': 'application/json',
+                'X-Storystick-Client': 'sdk',
+                ...contentShapeCapabilityHeaders('api', opts.contentShapeCapability, opts.applicationBuildId),
+            },
+            body: JSON.stringify(opts.body),
+            cache: 'no-store',
+        });
+    }
+    catch (error) {
+        throw new PreviewGrantExchangeError(`Preview grant network error: ${error instanceof Error ? error.message : String(error)}`, {
+            code: 'PREVIEW_GRANT_NETWORK',
+            category: 'system',
+            retryable: true,
+        });
+    }
+    if (!response.ok) {
+        let code = `HTTP_${response.status}`;
+        let message = response.statusText;
+        let ref;
+        let category = 'system';
+        let retryable = response.status === 429 || response.status >= 500;
+        try {
+            const body = (await response.json());
+            const wrapped = body.error ?? body;
+            code = wrapped.code ?? code;
+            message = wrapped.message ?? message;
+            ref = wrapped.ref;
+            category = asCategory(wrapped.category);
+            retryable = wrapped.retryable ?? retryable;
+        }
+        catch {
+            // Keep the coarse HTTP fallback when Central did not return JSON.
+        }
+        throw new PreviewGrantExchangeError(`${code} — ${message}`, {
+            code,
+            ref,
+            category,
+            retryable,
+            status: response.status,
+        });
+    }
+    return response.json();
+}
+export async function activatePreviewGrantForServer(opts) {
+    const data = (await postGrantOperation('/api/preview-grants/activate-for-server', {
+        endpoint: opts.endpoint,
+        apiKey: opts.apiKey,
+        applicationBuildId: opts.applicationBuildId,
+        body: {
+            grantId: opts.grantId,
+            activationSecret: opts.activationSecret,
+            sessionId: opts.sessionId,
+            requestOrigin: opts.requestOrigin,
+        },
+        fetchImpl: opts.fetchImpl,
+    }));
+    if (!Number.isSafeInteger(data.admissionSequence) || (data.admissionSequence ?? 0) <= 0 ||
+        !isNonEmptyString(data.grantToken) ||
+        !isSafePreviewSessionId(data.grantId) ||
+        typeof data.grantExpiresAt !== 'number' ||
+        !Number.isFinite(data.grantExpiresAt) ||
+        !isNonEmptyString(data.token) ||
+        typeof data.tokenExpiresIn !== 'number' ||
+        !Number.isFinite(data.tokenExpiresIn) ||
+        data.tokenExpiresIn <= 0 ||
+        !isSafePreviewSessionId(data.sessionId) ||
+        !isNonEmptyString(data.projectId) ||
+        !isNonEmptyString(data.previewOrigin) ||
+        !isNonEmptyString(data.contentShapeCapability)) {
+        throw new PreviewGrantExchangeError('Preview grant activation response is malformed', {
+            code: 'PREVIEW_GRANT_INVALID_RESPONSE',
+            category: 'system',
+            retryable: false,
+        });
+    }
+    return data;
+}
+export async function exchangePreviewGrantForServer(opts) {
+    const data = (await postGrantOperation('/api/preview-grants/exchange-for-server', {
+        endpoint: opts.endpoint,
+        apiKey: opts.apiKey,
+        applicationBuildId: opts.applicationBuildId,
+        body: {
+            grantToken: opts.grantToken,
+            requestOrigin: opts.requestOrigin,
+        },
+        contentShapeCapability: opts.contentShapeCapability,
+        fetchImpl: opts.fetchImpl,
+    }));
+    if (!isNonEmptyString(data.token) ||
+        typeof data.tokenExpiresIn !== 'number' ||
+        !Number.isFinite(data.tokenExpiresIn) ||
+        data.tokenExpiresIn <= 0 ||
+        !isNonEmptyString(data.projectId) ||
+        !isNonEmptyString(data.previewOrigin) ||
+        !isNonEmptyString(data.contentShapeCapability) ||
+        (data.grantId !== undefined && !isSafePreviewSessionId(data.grantId)) ||
+        (data.grantExpiresAt !== undefined &&
+            (typeof data.grantExpiresAt !== 'number' ||
+                !Number.isFinite(data.grantExpiresAt)))) {
+        throw new PreviewGrantExchangeError('Preview grant access response is malformed', {
+            code: 'PREVIEW_GRANT_INVALID_RESPONSE',
+            category: 'system',
+            retryable: false,
+        });
+    }
+    return data;
+}
+export async function exchangePreviewAuthoringAdmissionForServer(opts) {
+    const data = (await postGrantOperation('/api/preview-grants/authoring-for-server', {
+        endpoint: opts.endpoint,
+        apiKey: opts.apiKey,
+        applicationBuildId: opts.applicationBuildId,
+        body: {
+            grantToken: opts.grantToken,
+            requestOrigin: opts.requestOrigin,
+            ...(opts.admissionId && opts.fileDelegationId
+                ? {
+                    admissionId: opts.admissionId,
+                    fileDelegationId: opts.fileDelegationId,
+                }
+                : {}),
+        },
+        contentShapeCapability: opts.contentShapeCapability,
+        fetchImpl: opts.fetchImpl,
+    }));
+    if (!isPreviewAuthoringAdmission(data)) {
+        throw new PreviewGrantExchangeError('Preview authoring admission response is malformed', {
+            code: 'PREVIEW_GRANT_INVALID_RESPONSE',
+            category: 'system',
+            retryable: false,
+        });
+    }
+    return data;
+}
+export function parsePreviewActivation(value) {
+    if (!value)
+        throw new PreviewActivationError('preview activation is required');
+    const separator = value.indexOf('.');
+    if (separator <= 0 || separator === value.length - 1) {
+        throw new PreviewActivationError('preview activation is malformed');
+    }
+    const grantId = value.slice(0, separator);
+    const activationSecret = value.slice(separator + 1);
+    if (!isSafePreviewSessionId(grantId) ||
+        !/^[A-Za-z0-9_-]{16,512}$/.test(activationSecret)) {
+        throw new PreviewActivationError('preview activation is malformed');
+    }
+    return { grantId, activationSecret };
+}
+export function isSafePreviewSessionId(value) {
+    return typeof value === 'string' && PREVIEW_SESSION_ID_RE.test(value);
+}
+export function previewCapabilityCookieName(scope) {
+    // Ports do not partition browser cookies. Scope the name, retaining the native Path.
+    return scopedPreviewCookieName(PREVIEW_CAPABILITY_COOKIE, scope);
+}
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+export function previewCookieAttributes({ expiresIn, requestUrl, basePath = '', }) {
+    const url = new URL(requestUrl);
+    const maxAge = Math.max(0, Math.floor(expiresIn));
+    const isHttpNonLoopback = url.protocol === 'http:' && !LOOPBACK_HOSTNAMES.has(url.hostname);
+    if (isHttpNonLoopback) {
+        return {
+            httpOnly: true,
+            secure: false,
+            sameSite: 'lax',
+            path: basePath || '/',
+            maxAge,
+        };
+    }
+    return {
+        httpOnly: true,
+        secure: true,
+        sameSite: 'none',
+        partitioned: true,
+        path: basePath || '/',
+        maxAge,
+    };
+}
+const CONTROL_CHAR_RE = /[\x00-\x1f]/;
+export function assertSafePreviewRedirect(path, basePath = '') {
+    const input = path || '/';
+    if (CONTROL_CHAR_RE.test(input)) {
+        throw new PreviewRedirectError('Unsafe redirect path: control characters');
+    }
+    let decoded;
+    try {
+        decoded = decodeURIComponent(input);
+    }
+    catch {
+        throw new PreviewRedirectError('Unsafe redirect path: malformed encoding');
+    }
+    if (decoded.startsWith('//') ||
+        /^[a-zA-Z][a-zA-Z0-9+\-.]*:/.test(decoded)) {
+        throw new PreviewRedirectError('Unsafe redirect path: external target');
+    }
+    let parsed;
+    try {
+        parsed = new URL(input, `http://placeholder.invalid${basePath || '/'}`);
+    }
+    catch {
+        throw new PreviewRedirectError('Unsafe redirect path: unparseable');
+    }
+    if (parsed.hostname !== 'placeholder.invalid') {
+        throw new PreviewRedirectError('Unsafe redirect path: external host');
+    }
+    const normalized = parsed.pathname;
+    if (basePath &&
+        normalized !== basePath &&
+        !normalized.startsWith(`${basePath}/`)) {
+        throw new PreviewRedirectError('Unsafe redirect path: outside basePath');
+    }
+    return normalized + parsed.search + parsed.hash;
+}
+export function previewNoStoreFetchOptions() {
+    return {
+        cache: 'no-store',
+        headers: { 'Cache-Control': 'no-store' },
+    };
+}

package/dist/server/ordinary-read-provenance.d.ts

@@ -0,0 +1,11 @@
+import type { PreviewPrimaryPage } from '@storystick/preview/provenance';
+import { type PreviewProvenanceRuntime } from './provenance-runtime.js';
+/** Encode after the raw request cache. Reads stay native and need no render publisher. */
+export declare function prepareOrdinaryPreviewRead<T>(raw: T, runtime: PreviewProvenanceRuntime, options?: {
+    sessionId?: string | null;
+    pathname?: string;
+    primaryPage?: {
+        document: object;
+        identity: PreviewPrimaryPage;
+    };
+}): Promise<T>;

package/dist/server/ordinary-read-provenance.js

@@ -0,0 +1,124 @@
+import { isContentRenderPlan, mergeContentFields, selectedContentFields } from '@storystick/types';
+import { attachPreviewReadObservation, getPreviewReadObservation, attachPreviewQueryReceipt, getPreviewQueryReceiptId } from '@storystick/client/internal';
+import { attachPreviewFrameDependencies, collectPreviewFrameDependencies, attachPreviewProvenanceSourceMap, getPreviewProvenanceSourceMap, decodePreviewProvenanceText, encodePreviewProvenanceText, encodePreviewReadCarrier, } from '@storystick/preview/provenance';
+import { withPreviewProvenanceContext } from '../provenance/render-context.js';
+import { unstable_attachPreviewRouteRenderContext, unstable_buildPreviewRouteDocumentFrameWithRuntime } from './route-document-provenance.js';
+import { bindPreviewRuntimeToReads } from './provenance-runtime.js';
+/** Encode after the raw request cache. Reads stay native and need no render publisher. */
+export async function prepareOrdinaryPreviewRead(raw, runtime, options = {}) {
+    if (!runtime.config.isEnabled())
+        return raw;
+    const manifest = await runtime.config.resolveSemanticManifest();
+    async function visit(value) {
+        if (!value || typeof value !== 'object')
+            return value;
+        if ('__ssPreviewRouteRender' in value)
+            return value;
+        let coded;
+        if ('documentId' in value && 'storyType' in value && 'fields' in value) {
+            const document = value;
+            const observation = getPreviewReadObservation(value);
+            const bytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify([
+                document.documentId, observation?.receiptId ?? null,
+                observation?.readContext ?? null, document._locale ?? null,
+            ])));
+            const frameId = 'read_' + Array.from(new Uint8Array(bytes), byte => byte.toString(16).padStart(2, '0')).join('').slice(0, 24);
+            const plan = document._render;
+            const dependencies = isContentRenderPlan(plan) ? plan.dependencies : undefined;
+            // Hidden render dependencies participate in coding but remain outside the
+            // caller's selected root fields. This preserves binding source identity.
+            const planningDocument = dependencies ? { ...document, fields: mergeContentFields(dependencies, document.fields) } : document;
+            if (observation)
+                attachPreviewReadObservation(planningDocument, observation);
+            if (planningDocument !== document) {
+                attachPreviewQueryReceipt(planningDocument, getPreviewQueryReceiptId(document) ?? undefined);
+                attachPreviewFrameDependencies(planningDocument, collectPreviewFrameDependencies(document));
+                const sourceMap = getPreviewProvenanceSourceMap(document);
+                if (sourceMap)
+                    attachPreviewProvenanceSourceMap(planningDocument, sourceMap);
+            }
+            const frame = await unstable_buildPreviewRouteDocumentFrameWithRuntime({
+                document: planningDocument, manifest, frameId, routeHash: 'occurrence:' + frameId,
+                renderId: frameId, pathname: options.pathname ?? '/', sessionId: options.sessionId,
+            }, runtime);
+            if (!frame?.validationOk || !frame.publicSidecar || !frame.codedDocument)
+                return value;
+            const carriers = new Map(frame.publicSidecar.markers.map(marker => [marker.markerId, encodePreviewReadCarrier(frameId, frame.publicSidecar, marker, options.primaryPage?.document === value ? options.primaryPage.identity : undefined)]));
+            const codedDocument = frame.codedDocument;
+            if (dependencies && isContentRenderPlan(plan)) {
+                const codedFields = codedDocument.fields;
+                codedDocument._render = { ...plan, dependencies: Object.fromEntries(Object.keys(dependencies)
+                        .map(key => [key, codedFields[key]])) };
+                codedDocument.fields = selectedContentFields(codedFields, document.fields);
+            }
+            const documentWithCarriers = rewriteCarriers(frame.codedDocument, carriers);
+            const attrsByKey = Object.fromEntries(Object.entries(frame.attrsByKey).map(([key, attrs]) => [key, Object.fromEntries(Object.entries(attrs).map(([name, id]) => [name, typeof id === 'string' ? carriers.get(id) ?? id : id]))]));
+            const contextual = withPreviewProvenanceContext(documentWithCarriers, attrsByKey);
+            // Renderers retain their attribute/slice context. The values themselves
+            // publish provenance; no adjacent React publisher or projection boundary.
+            coded = unstable_attachPreviewRouteRenderContext(contextual, {
+                ...frame, codedDocument: contextual, attrsByKey, publicSidecar: null,
+            });
+            const sourceMap = getPreviewProvenanceSourceMap(document);
+            if (sourceMap)
+                attachPreviewProvenanceSourceMap(coded, sourceMap);
+        }
+        else if (Array.isArray(value)) {
+            coded = await Promise.all(value.map(visit));
+        }
+        else {
+            coded = Object.fromEntries(await Promise.all(Object.entries(value)
+                .map(async ([key, child]) => [key, await visit(child)])));
+        }
+        const observation = getPreviewReadObservation(value);
+        if (observation)
+            attachPreviewReadObservation(coded, observation);
+        attachPreviewQueryReceipt(coded, getPreviewQueryReceiptId(value) ?? undefined);
+        attachPreviewFrameDependencies(coded, collectPreviewFrameDependencies(value));
+        return coded;
+    }
+    const coded = await visit(raw);
+    bindPreviewRuntimeToReads(coded, runtime);
+    return coded;
+}
+function rewriteCarriers(value, carriers) {
+    if (typeof value === 'string') {
+        // Object markers and attribute IDs also remain plain serializable strings.
+        if (carriers.has(value))
+            return carriers.get(value);
+        const decoded = decodePreviewProvenanceText(value);
+        let rewritten = value;
+        if (decoded.segments.length) {
+            let cursor = 0;
+            let coded = '';
+            for (const segment of decoded.segments) {
+                coded += value.slice(cursor, segment.markerStart) + encodePreviewProvenanceText(carriers.get(segment.markerId) ?? segment.markerId, segment.text);
+                cursor = segment.markerEnd;
+            }
+            rewritten = coded + value.slice(cursor);
+        }
+        return rewriteSerializedRichTextCarriers(rewritten, carriers);
+    }
+    if (Array.isArray(value))
+        return value.map(child => rewriteCarriers(child, carriers));
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value)
+            .map(([key, child]) => [key, rewriteCarriers(child, carriers)]));
+    return value;
+}
+function rewriteSerializedRichTextCarriers(value, carriers) {
+    if (value[0] !== '{' || !value.includes('"type"') || !value.includes('"content"'))
+        return value;
+    try {
+        const parsed = JSON.parse(value);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return value;
+        const document = parsed;
+        if (document.type !== 'doc' || !Array.isArray(document.content))
+            return value;
+        return JSON.stringify(rewriteCarriers(parsed, carriers));
+    }
+    catch {
+        return value;
+    }
+}

package/dist/server/preview-read-metadata.d.ts

@@ -0,0 +1,10 @@
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { type PreviewReadObservation } from '@storystick/client/internal';
+export interface PreviewFrameReadMetadata {
+    readonly readContext?: PreviewReadContext;
+    readonly receiptIds: readonly string[];
+    readonly observationId: string;
+    readonly renderWatermark: number;
+}
+export declare function resolvePreviewFrameReadMetadata(codeVersion: string, ...roots: readonly unknown[]): PreviewFrameReadMetadata | null;
+export declare function resolvePreviewFrameReadMetadataFromObservations(codeVersion: string, observations: readonly PreviewReadObservation[]): PreviewFrameReadMetadata | null;