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

package/dist/server/preview-read-metadata.js

@@ -0,0 +1,27 @@
+import { collectPreviewReadObservations, conservativePreviewRenderWatermark, } from '@storystick/client/internal';
+export function resolvePreviewFrameReadMetadata(codeVersion, ...roots) {
+    return resolvePreviewFrameReadMetadataFromObservations(codeVersion, collectPreviewReadObservations(...roots));
+}
+export function resolvePreviewFrameReadMetadataFromObservations(codeVersion, observations) {
+    const compatible = observations.filter((observation) => observation.codeVersion === codeVersion);
+    const contexts = compatible.flatMap((observation) => observation.readContext ? [observation.readContext] : []);
+    const readContext = contexts[0];
+    // An independent read cannot lend its receipt to another document. Every
+    // observation in a shared-context frame must carry its own query proof.
+    if (readContext && compatible.some((read) => !read.receiptId))
+        return null;
+    if (readContext && (contexts.length !== compatible.length || contexts.some((context) => context.contextId !== readContext.contextId || context.revision !== readContext.revision)))
+        return null;
+    const observationIds = new Set(compatible.map((observation) => observation.observationId));
+    if (observationIds.size !== 1)
+        return null;
+    const renderWatermark = conservativePreviewRenderWatermark(compatible);
+    if (renderWatermark === undefined)
+        return null;
+    return {
+        ...(readContext ? { readContext } : {}),
+        receiptIds: [...new Set(compatible.flatMap((observation) => observation.receiptId ? [observation.receiptId] : []))],
+        observationId: [...observationIds][0],
+        renderWatermark,
+    };
+}

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

@@ -0,0 +1,53 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { type PreviewFrameDependency, type PreviewFrameDependencySet, type PreviewProvenanceCodedTextRootsByDocumentId, type PreviewProvenanceCodedTextWriteSummary, type PreviewProvenanceEditableLeaf, type ProvenanceFrame, type PublicProvenanceSidecar } from '@storystick/preview/provenance';
+import { type PreviewProvenanceRuntime } from './provenance-runtime.js';
+export type PreviewProvenanceAttrs = Readonly<Record<string, string>>;
+export type PreviewProvenanceAttrsByKey = Readonly<Record<string, PreviewProvenanceAttrs>>;
+export interface BuildPreviewProvenanceFrameOptions {
+    /**
+     * Temporary runtime preview gate. Omit to use
+     * `STORYSTICK_PREVIEW_PROVENANCE === '1'`; pass explicitly in tests or
+     * trusted preview runtime wiring.
+     */
+    readonly enabled?: boolean;
+    readonly frameId: string;
+    readonly readContext?: PreviewReadContext;
+    readonly receiptIds?: readonly string[];
+    readonly sessionId?: string | null;
+    readonly routeHash?: string;
+    readonly variantId?: string | null;
+    readonly previewScope?: PreviewReadScopeEcho;
+    readonly fallbackPathname?: string;
+    readonly codeVersion?: string;
+    readonly renderId?: string;
+    readonly generation?: number;
+    readonly observationId?: string;
+    readonly renderWatermark?: number;
+    readonly renderNonce?: string;
+    readonly emissionRevision?: number;
+    readonly authoritativeDocumentIds: readonly string[];
+    readonly dependencies?: readonly PreviewFrameDependency[];
+    readonly leaves: readonly PreviewProvenanceEditableLeaf[];
+    readonly codedTextRoot?: unknown;
+    readonly codedTextRootPrefix?: readonly (string | number)[];
+    readonly codedTextRootsByDocumentId?: PreviewProvenanceCodedTextRootsByDocumentId;
+    readonly projectId?: string;
+    readonly endpoint?: string;
+    readonly convexUrl?: string;
+}
+export interface BuildPreviewProvenanceFrameResult {
+    readonly frameId: string;
+    readonly sessionId?: string;
+    readonly routeHash: string;
+    readonly variantId: string | null;
+    readonly codeVersion: string;
+    readonly renderId: string;
+    readonly attrsByKey: PreviewProvenanceAttrsByKey;
+    readonly renderFrame: ProvenanceFrame;
+    readonly dependencySet: PreviewFrameDependencySet;
+    readonly publicSidecar: PublicProvenanceSidecar | null;
+    readonly codedTextWrites: PreviewProvenanceCodedTextWriteSummary;
+    readonly validationOk: boolean;
+}
+export declare function buildPreviewProvenanceFrameWithRuntime(options: BuildPreviewProvenanceFrameOptions, runtime: PreviewProvenanceRuntime): Promise<BuildPreviewProvenanceFrameResult | null>;

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

@@ -0,0 +1,102 @@
+import { createPreviewFrameDependencySet, createPublicSidecar, recordPreviewProvenanceEditableLeaves, validateProvenanceFrame, } from '@storystick/preview/provenance';
+import { normalizePreviewVariantId } from '@storystick/preview/identity';
+import { defaultPreviewProvenanceRenderId } from './render-id.js';
+import { createPreviewProvenanceTemporalIdentity, } from './provenance-runtime.js';
+export async function buildPreviewProvenanceFrameWithRuntime(options, runtime) {
+    const enabled = options.enabled ?? runtime.config.isEnabled();
+    if (!enabled)
+        return null;
+    // A native layout has a read context before there is a view to bind it to.
+    const readContext = options.readContext;
+    const sessionId = options.sessionId ?? (readContext ? undefined : await runtime.recorder.readSessionId()) ?? undefined;
+    if (!readContext && !sessionId)
+        return null;
+    if (readContext && !options.receiptIds?.length)
+        return null;
+    const codeVersion = runtime.config.resolveCodeVersion({ codeVersion: options.codeVersion });
+    const routeIdentity = !readContext && sessionId &&
+        (options.routeHash === undefined || options.variantId === undefined)
+        ? await runtime.recorder.resolveRouteIdentity({
+            sessionId, fallbackPathname: options.fallbackPathname,
+            projectId: options.projectId, endpoint: options.endpoint, convexUrl: options.convexUrl,
+        })
+        : null;
+    const routeHash = options.routeHash ?? routeIdentity?.routeHash ?? `occurrence:${options.frameId}`;
+    const variantId = readContext
+        ? readContext.perspective.kind === 'variant' ? readContext.perspective.variantId : null
+        : options.variantId === undefined ? routeIdentity?.variantId ?? null : normalizePreviewVariantId(options.variantId);
+    const renderId = options.renderId ??
+        defaultPreviewProvenanceRenderId({
+            frameId: options.frameId,
+            routeHash,
+        });
+    const generation = options.generation ?? 1;
+    const generatedTemporalIdentity = createPreviewProvenanceTemporalIdentity(runtime, {
+        sessionId,
+        frameId: options.frameId,
+        routeHash,
+        codeVersion,
+        renderId,
+        generation,
+    });
+    const renderNonce = options.renderNonce ?? generatedTemporalIdentity.renderNonce;
+    const emissionRevision = options.emissionRevision ?? generatedTemporalIdentity.emissionRevision;
+    const recorded = await recordPreviewProvenanceEditableLeaves({
+        sessionId,
+        readContext,
+        routeHash,
+        variantId,
+        previewScope: options.previewScope,
+        codeVersion,
+        renderId,
+        generation,
+        renderNonce,
+        emissionRevision,
+        enabled,
+        leaves: options.leaves,
+        codedTextRoot: options.codedTextRoot,
+        codedTextRootPrefix: options.codedTextRootPrefix,
+        codedTextRootsByDocumentId: options.codedTextRootsByDocumentId,
+    });
+    const dependencySet = createPreviewFrameDependencySet({
+        sessionId,
+        readContext,
+        receiptIds: options.receiptIds,
+        routeHash,
+        variantId,
+        codeVersion,
+        frameId: options.frameId,
+        renderId,
+        generation,
+        observationId: options.observationId,
+        renderWatermark: options.renderWatermark,
+        dependencies: options.dependencies ?? options.authoritativeDocumentIds.map((documentId) => ({
+            kind: 'document',
+            documentId,
+            reason: 'rendered-document',
+        })),
+    });
+    const validation = validateProvenanceFrame(recorded.renderFrame, {
+        documentIds: new Set(options.authoritativeDocumentIds.filter((documentId) => documentId.trim().length > 0)),
+        routeHash,
+        variantId,
+        codeVersion,
+    });
+    const publicSidecar = recorded.publicSidecar === null
+        ? null
+        : createPublicSidecar(recorded.renderFrame, dependencySet);
+    return {
+        frameId: options.frameId,
+        sessionId,
+        routeHash,
+        variantId,
+        codeVersion,
+        renderId,
+        attrsByKey: recorded.attrsByKey,
+        renderFrame: recorded.renderFrame,
+        dependencySet,
+        publicSidecar,
+        codedTextWrites: recorded.codedTextWrites,
+        validationOk: validation.ok,
+    };
+}

package/dist/server/provenance-runtime.d.ts

@@ -0,0 +1,70 @@
+import type { QuerySchemaDefinition } from '@storystick/client';
+import type { PreviewProvenanceEditableTextPathManifest } from '../provenance/index.js';
+import type { PreviewRenderFrameFixtureOptions } from './render-frame-provenance.js';
+export interface ReadPreviewProvenanceSessionOptions {
+    readonly sessionId?: string | null;
+}
+export interface ResolvePreviewProvenanceRouteIdentityOptions {
+    readonly sessionId: string;
+    readonly fallbackPathname?: string;
+    readonly projectId?: string;
+    readonly endpoint?: string;
+    readonly convexUrl?: string;
+}
+export interface PreviewProvenanceRouteIdentity {
+    readonly routeUrl: string;
+    readonly routeHash: string;
+    readonly variantId: string | null;
+}
+export interface StorystickPreviewProvenanceConfig {
+    readonly enabled: boolean;
+    readonly fixtureEnabled: boolean;
+    readonly sessionId: string;
+    readonly codeVersion: string;
+    readonly fixture: PreviewRenderFrameFixtureOptions | null;
+}
+export interface ResolvePreviewRuntimeCodeVersionOptions {
+    readonly codeVersion?: string;
+}
+export interface PreviewProvenanceTemporalIdentityInput {
+    readonly sessionId?: string;
+    readonly frameId: string;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly renderId: string;
+    readonly generation: number;
+}
+export interface PreviewProvenanceTemporalIdentity {
+    readonly renderNonce: string;
+    readonly emissionRevision: number;
+}
+export interface PreviewProvenanceRuntimeConfig {
+    readonly isEnabled: () => boolean;
+    readonly isProduction: () => boolean;
+    readonly resolveCodeVersion: (options?: ResolvePreviewRuntimeCodeVersionOptions) => string;
+    readonly resolveSemanticConfig: () => StorystickPreviewProvenanceConfig;
+    readonly resolveSemanticManifest: () => Promise<PreviewProvenanceEditableTextPathManifest>;
+}
+export interface PreviewProvenanceRuntimeRecorder {
+    readonly markNoStore: (input: {
+        readonly enabled: boolean;
+    }) => void;
+    readonly readSessionId: (options?: ReadPreviewProvenanceSessionOptions) => Promise<string | null>;
+    readonly resolveRouteIdentity: (options: ResolvePreviewProvenanceRouteIdentityOptions) => Promise<PreviewProvenanceRouteIdentity>;
+}
+export interface PreviewProvenanceRuntime {
+    readonly config: PreviewProvenanceRuntimeConfig;
+    readonly recorder: PreviewProvenanceRuntimeRecorder;
+    /** Optional for V1-compatible injected runtimes; the default is V2-aware. */
+    readonly transport?: {
+        readonly createTemporalIdentity: (input: PreviewProvenanceTemporalIdentityInput) => PreviewProvenanceTemporalIdentity;
+    };
+}
+export declare function createDefaultPreviewProvenanceTemporalIdentity(): PreviewProvenanceTemporalIdentity;
+export declare function createPreviewProvenanceTemporalIdentity(runtime: PreviewProvenanceRuntime, input: PreviewProvenanceTemporalIdentityInput): PreviewProvenanceTemporalIdentity;
+export declare function previewRuntimeForSchema(schema: QuerySchemaDefinition): PreviewProvenanceRuntime | undefined;
+export declare function bindPreviewRuntimeToReads(value: unknown, runtime: PreviewProvenanceRuntime | undefined): void;
+export declare function previewRuntimeForReads(...values: readonly unknown[]): PreviewProvenanceRuntime | undefined;
+export declare function bindPreviewRuntimeToSidecar(sidecar: object | null, runtime: PreviewProvenanceRuntime): void;
+export declare function previewRuntimeForSidecar(sidecar: object | null | undefined): PreviewProvenanceRuntime | undefined;
+export declare function bindPreviewRuntimeToSchema(schema: QuerySchemaDefinition, runtime: PreviewProvenanceRuntime): void;

package/dist/server/provenance-runtime.js

@@ -0,0 +1,46 @@
+import { collectPreviewReadObservations } from '@storystick/client/internal';
+let lastEmissionRevision = 0;
+export function createDefaultPreviewProvenanceTemporalIdentity() {
+    const wallClockRevision = Date.now() * 1_000;
+    lastEmissionRevision = Math.max(wallClockRevision, lastEmissionRevision + 1);
+    return {
+        renderNonce: typeof globalThis.crypto?.randomUUID === 'function'
+            ? globalThis.crypto.randomUUID()
+            : `${wallClockRevision.toString(36)}-${Math.random().toString(36).slice(2)}`,
+        emissionRevision: lastEmissionRevision,
+    };
+}
+export function createPreviewProvenanceTemporalIdentity(runtime, input) {
+    return runtime.transport?.createTemporalIdentity(input) ?? createDefaultPreviewProvenanceTemporalIdentity();
+}
+// Immutable site bindings and read ownership. No request/session is stored here,
+// and nothing is serialized onto customer data across an RSC boundary.
+const runtimeBySchema = new WeakMap();
+const runtimeByRead = new WeakMap();
+const runtimeBySidecar = new WeakMap();
+export function previewRuntimeForSchema(schema) {
+    return runtimeBySchema.get(schema);
+}
+export function bindPreviewRuntimeToReads(value, runtime) {
+    if (runtime)
+        for (const read of collectPreviewReadObservations(value))
+            runtimeByRead.set(read, runtime);
+}
+export function previewRuntimeForReads(...values) {
+    let runtime;
+    for (const read of collectPreviewReadObservations(...values)) {
+        const owner = runtimeByRead.get(read);
+        if (runtime && owner && runtime !== owner)
+            throw new Error('A document boundary cannot mix different Storystick site definitions.');
+        runtime ??= owner;
+    }
+    return runtime;
+}
+export function bindPreviewRuntimeToSidecar(sidecar, runtime) {
+    if (sidecar)
+        runtimeBySidecar.set(sidecar, runtime);
+}
+export function previewRuntimeForSidecar(sidecar) {
+    return sidecar ? runtimeBySidecar.get(sidecar) : undefined;
+}
+export function bindPreviewRuntimeToSchema(schema, runtime) { runtimeBySchema.set(schema, runtime); }

package/dist/server/read-context-command.d.ts

@@ -0,0 +1,11 @@
+import { type PreviewPerspective } from '@storystick/types/preview-query-targeting';
+export interface PreviewContextCommand {
+    commandId: string;
+    expectedContextId: string;
+    expectedRevision: number;
+    perspective: PreviewPerspective | null;
+}
+/** Bounded JSON command reader, shared by context changes and explicit exit. */
+export declare function readPreviewContextCommand(request: Request): Promise<PreviewContextCommand | null>;
+/** Small shared command transport; never buffer an unbounded request. */
+export declare function readBoundedPreviewJson(request: Request, limit?: number): Promise<unknown>;

package/dist/server/read-context-command.js

@@ -0,0 +1,53 @@
+import { isPreviewPerspective } from '@storystick/types/preview-query-targeting';
+/** Bounded JSON command reader, shared by context changes and explicit exit. */
+export async function readPreviewContextCommand(request) {
+    const raw = await readBoundedPreviewJson(request);
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return null;
+    }
+    const command = raw;
+    if (Object.keys(command).some((key) => !['commandId', 'expectedContextId', 'expectedRevision', 'perspective'].includes(key)) ||
+        typeof command.expectedContextId !== 'string' || !command.expectedContextId.trim() || command.expectedContextId.length > 256 ||
+        typeof command.commandId !== 'string' || !command.commandId.trim() || command.commandId.length > 128 ||
+        !Number.isSafeInteger(command.expectedRevision) || command.expectedRevision < 1 ||
+        !(command.perspective === null || isPreviewPerspective(command.perspective))) {
+        return null;
+    }
+    return command;
+}
+/** Small shared command transport; never buffer an unbounded request. */
+export async function readBoundedPreviewJson(request, limit = 4096) {
+    try {
+        const reader = request.body?.getReader();
+        if (!reader)
+            throw new Error('missing body');
+        const chunks = [];
+        let bytes = 0;
+        try {
+            while (true) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                bytes += part.value.byteLength;
+                if (bytes > limit) {
+                    await reader.cancel();
+                    throw new Error('body too large');
+                }
+                chunks.push(part.value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const body = new Uint8Array(bytes);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return JSON.parse(new TextDecoder().decode(body));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/read-identity.d.ts

@@ -0,0 +1,3 @@
+import type { Transport } from '@storystick/client/internal';
+export declare function unstable_createPreviewReadIdentityTransport(transport: Transport): Transport;
+export declare function unstable_attachPreviewReadIdentity<T>(value: T): T;

package/dist/server/read-identity.js

@@ -0,0 +1,63 @@
+import { isContentRenderPlan, mergeContentFields } from '@storystick/types';
+import { attachPreviewProvenanceSourceMap, createPreviewProvenanceQueryResultSourceMap, getPreviewProvenanceSourceMap, } from '@storystick/preview/provenance';
+export function unstable_createPreviewReadIdentityTransport(transport) {
+    return {
+        async request(input) {
+            const response = await transport.request(input);
+            if (shouldAttachPreviewReadIdentity(input.requestContext)) {
+                return {
+                    ...response,
+                    data: unstable_attachPreviewReadIdentity(response.data),
+                };
+            }
+            return response;
+        },
+    };
+}
+export function unstable_attachPreviewReadIdentity(value) {
+    const seen = new WeakSet();
+    const visit = (candidate) => {
+        if (!isObject(candidate))
+            return;
+        if (seen.has(candidate))
+            return;
+        seen.add(candidate);
+        if (isQueryResultLike(candidate)) {
+            attachReadSourceMap(candidate);
+            visit(candidate.resolved);
+            return;
+        }
+        if (Array.isArray(candidate)) {
+            for (const item of candidate)
+                visit(item);
+            return;
+        }
+        for (const child of Object.values(candidate))
+            visit(child);
+    };
+    visit(value);
+    return value;
+}
+function shouldAttachPreviewReadIdentity(requestContext) {
+    return (process.env.STORYSTICK_PREVIEW_PROVENANCE === '1' ||
+        (typeof requestContext?.previewToken === 'string' &&
+            requestContext.previewToken.length > 0));
+}
+function attachReadSourceMap(document) {
+    if (getPreviewProvenanceSourceMap(document) !== null)
+        return;
+    const plan = document._render;
+    const fields = isContentRenderPlan(plan) && plan.dependencies
+        ? mergeContentFields(plan.dependencies, document.fields)
+        : document.fields;
+    attachPreviewProvenanceSourceMap(document, createPreviewProvenanceQueryResultSourceMap({ ...document, fields }));
+}
+function isQueryResultLike(value) {
+    return (isObject(value) &&
+        typeof value.documentId === 'string' &&
+        typeof value.storyType === 'string' &&
+        isObject(value.fields));
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/server/read-lifecycle.d.ts

@@ -0,0 +1,17 @@
+import { type PreviewProvenanceReadLifecycle } from '@storystick/client/internal';
+import type { PreviewPrimaryPage } from '@storystick/preview/provenance';
+import type { PreviewProvenanceRuntime } from './provenance-runtime.js';
+export interface PreviewReadLifecycleOptions {
+    /** Routes infer their page; a request-owned draft supplies its explicit destination. */
+    readonly primaryPage?: boolean | PreviewPrimaryPage;
+    readonly projectId: string;
+    readonly endpoint: string;
+    readonly runtime?: PreviewProvenanceRuntime;
+    readonly previewObservationId?: string | null;
+    readonly variantId?: string | null;
+    readonly releaseId?: string | null;
+    readonly previewCodeVersion?: string | null;
+    readonly rawReadCache: Map<string, Promise<unknown>>;
+}
+/** Request-local raw cache. Each consumer gets its own portable Preview values. */
+export declare function createPreviewReadLifecycle(options: PreviewReadLifecycleOptions): PreviewProvenanceReadLifecycle;

package/dist/server/read-lifecycle.js

@@ -0,0 +1,52 @@
+import { prepareOrdinaryPreviewRead } from './ordinary-read-provenance.js';
+/** Request-local raw cache. Each consumer gets its own portable Preview values. */
+export function createPreviewReadLifecycle(options) {
+    return async (input) => {
+        const key = JSON.stringify([options.projectId, options.endpoint, options.previewObservationId,
+            options.variantId, options.releaseId, options.previewCodeVersion, input.cacheKey]);
+        // An abort signal owns its request; it must never cancel a sibling's read.
+        let raw = input.signal ? undefined : options.rawReadCache.get(key);
+        if (!raw) {
+            raw = readProjected(input);
+            if (!input.signal)
+                options.rawReadCache.set(key, raw);
+        }
+        const value = await raw;
+        const route = value;
+        const query = value;
+        const primaryPage = typeof options.primaryPage === 'object' && input.kind === 'query-single' &&
+            query?.data?.documentId === options.primaryPage.documentId
+            ? { document: query.data, identity: options.primaryPage }
+            : options.primaryPage === true && input.kind === 'resolved-route' && route?.type === 'document' &&
+                typeof route.document?.documentId === 'string' && typeof route.localeContext?.locale === 'string' && typeof route.publicPathname === 'string'
+                ? { document: route.document, identity: { documentId: route.document.documentId, locale: route.localeContext.locale, publicPathname: route.publicPathname } }
+                : undefined;
+        return options.runtime ? prepareOrdinaryPreviewRead(value, options.runtime, { primaryPage }) : value;
+    };
+}
+async function readProjected(input) {
+    // Projection may advance between the ready notification and this server read.
+    // Only the two explicit freshness outcomes are retried, within 750ms total.
+    // Exhaustion preserves the blocked result/error; never turn it into absence.
+    let value = await input.executeRaw();
+    for (const delay of [50, 100, 200, 400]) {
+        if (!projectionCatchingUp(value))
+            break;
+        input.signal?.throwIfAborted();
+        await new Promise((resolve, reject) => {
+            const abort = () => { clearTimeout(timer); reject(input.signal.reason); };
+            const timer = setTimeout(() => { input.signal?.removeEventListener('abort', abort); resolve(); }, delay);
+            input.signal?.addEventListener('abort', abort, { once: true });
+        });
+        input.signal?.throwIfAborted();
+        value = await input.executeRaw();
+    }
+    return value;
+}
+function projectionCatchingUp(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const result = value;
+    return result.exactness === 'blocked' && result.reason?.retryable === true &&
+        (result.reason.code === 'projection-stale' || result.reason.code === 'projection-indexing');
+}

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

@@ -0,0 +1,133 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import { type PreviewFrameDependency, type PreviewFrameDependencySet, type PreviewProvenanceCodedTextRootsByDocumentId, type PreviewProvenanceEditableLeaf, type PreviewProvenanceEditableTextPathManifest, type PreviewProvenancePathPart, type PreviewProvenanceQueryResultLike, type ProvenanceFrame, type PublicProvenanceSidecar } from '@storystick/preview/provenance';
+import { type PreviewProvenanceAttrsByKey } from '../provenance/render-context.js';
+import { type PreviewProvenanceRuntime } from './provenance-runtime.js';
+export interface PreviewRenderFrameFixtureOptions {
+    readonly enabled: boolean;
+    readonly sessionId: string;
+    readonly routeHash?: string;
+    readonly variantId?: string | null;
+}
+export interface BuildPreviewRenderFrameOptions<TDocument = unknown, TContext = unknown> {
+    /**
+     * Temporary runtime preview gate. Omit to use
+     * `STORYSTICK_PREVIEW_PROVENANCE === '1'`; pass explicitly in tests or
+     * trusted preview runtime wiring.
+     */
+    readonly enabled?: boolean;
+    readonly frameId: string;
+    readonly pathname?: string;
+    readonly fallbackPathname?: string;
+    readonly routeHash?: string;
+    readonly variantId?: string | null;
+    readonly previewScope?: PreviewReadScopeEcho;
+    readonly sessionId?: string | null;
+    readonly codeVersion?: string;
+    readonly renderId?: string;
+    readonly generation?: number;
+    readonly renderNonce?: string;
+    readonly emissionRevision?: number;
+    /** @internal Authenticated read proof, copied before JSON cloning. */
+    readonly readContext?: PreviewReadContext;
+    readonly receiptIds?: readonly string[];
+    /** @internal Transport-derived render clock metadata. */
+    readonly observationId?: string;
+    /** @internal Transport-derived render clock metadata. */
+    readonly renderWatermark?: number;
+    readonly authoritativeDocumentIds: readonly string[];
+    readonly dependencies?: readonly PreviewFrameDependency[];
+    readonly leaves: readonly PreviewProvenanceEditableLeaf[];
+    readonly sourceMapDiagnostics?: PreviewRenderFrameSourceMapDiagnostics;
+    readonly codedDocument?: TDocument;
+    readonly codedContext?: TContext;
+    readonly codedTextRoot?: unknown;
+    readonly codedTextRootPrefix?: readonly (string | number)[];
+    readonly codedTextRootsByDocumentId?: PreviewProvenanceCodedTextRootsByDocumentId;
+    readonly fixture?: PreviewRenderFrameFixtureOptions | null;
+    readonly projectId?: string;
+    readonly endpoint?: string;
+    readonly convexUrl?: string;
+}
+export interface PreviewRenderFrame<TDocument = unknown, TContext = unknown> {
+    readonly frameId: string;
+    readonly sessionId?: string;
+    readonly routeHash: string;
+    readonly variantId: string | null;
+    readonly attrsByKey: PreviewProvenanceAttrsByKey;
+    readonly codedDocument?: TDocument;
+    readonly codedContext?: TContext;
+    readonly renderFrame: ProvenanceFrame;
+    readonly dependencySet: PreviewFrameDependencySet;
+    readonly publicSidecar: PublicProvenanceSidecar | null;
+    readonly validationOk: boolean;
+    readonly diagnostics: PreviewRenderFrameDiagnostics;
+}
+export interface PreviewDocumentRenderFrame<TContext = unknown> extends PreviewRenderFrame<undefined, TContext> {
+}
+export interface PreviewRenderFrameSourceMapDiagnostics {
+    readonly entries: number;
+    readonly manifestIneligible: number;
+    readonly nonIdentityDerivation: number;
+    readonly carrierSkipped: number;
+}
+export interface PreviewRenderFrameDiagnostics {
+    readonly sourceMapEntries: number;
+    readonly carriersWritten: number;
+    readonly carrierSkipped: number;
+    readonly frameBytes: number;
+    readonly frameCapped: boolean;
+    readonly skipped: {
+        readonly manifestIneligible: number;
+        readonly nonIdentityDerivation: number;
+        readonly cap: number;
+        readonly codedTextWriteFailures: number;
+    };
+}
+export interface PreviewDocumentRenderFrameLeafPolicyInput<TFields = unknown> {
+    readonly document: PreviewProvenanceQueryResultLike;
+    readonly storyType: string;
+    readonly fields: TFields;
+    readonly canonicalPath: string;
+    readonly leaf: PreviewProvenanceEditableLeaf;
+}
+export type PreviewDocumentRenderFrameLeafPolicy<TFields = unknown> = (input: PreviewDocumentRenderFrameLeafPolicyInput<TFields>) => boolean;
+export interface PreviewDocumentRenderFrameRead<TFields = unknown> {
+    readonly document: PreviewProvenanceQueryResultLike | null | undefined;
+    readonly fields?: TFields | null | undefined;
+    readonly storyType?: string;
+    readonly keyPrefix?: string;
+    readonly sourceSetPrefix?: string;
+    readonly codedTextRootPath?: readonly PreviewProvenancePathPart[];
+    readonly dependencies?: readonly PreviewFrameDependency[];
+    readonly renderedLeavesPolicy?: PreviewDocumentRenderFrameLeafPolicy<TFields>;
+}
+export interface BuildPreviewDocumentRenderFrameFromReadsOptions<TContext = unknown> {
+    /**
+     * Temporary runtime preview gate. Omit to use
+     * `STORYSTICK_PREVIEW_PROVENANCE === '1'`.
+     */
+    readonly enabled?: boolean;
+    readonly frameId: string;
+    readonly routeHash: string;
+    readonly variantId?: string | null;
+    readonly sessionId?: string | null;
+    readonly codeVersion?: string;
+    readonly renderId?: string;
+    readonly generation?: number;
+    readonly renderNonce?: string;
+    readonly emissionRevision?: number;
+    readonly documents?: readonly PreviewDocumentRenderFrameRead[];
+    readonly context?: TContext;
+    readonly manifest: PreviewProvenanceEditableTextPathManifest;
+    readonly codedTextRootPrefix?: readonly PreviewProvenancePathPart[];
+    readonly authoritativeDocumentIds?: readonly string[];
+    readonly dependencies?: readonly PreviewFrameDependency[];
+    readonly fixture?: PreviewRenderFrameFixtureOptions | null;
+    readonly projectId?: string;
+    readonly endpoint?: string;
+    readonly convexUrl?: string;
+}
+export declare function unstable_previewRenderFrameRootAttrs(frame: Pick<PreviewRenderFrame, 'sessionId'> | null | undefined): Readonly<Record<string, string>>;
+export declare function unstable_buildPreviewRenderFrameWithRuntime<TDocument = unknown, TContext = unknown>(options: BuildPreviewRenderFrameOptions<TDocument, TContext>, runtime: PreviewProvenanceRuntime): Promise<PreviewRenderFrame<TDocument, TContext> | null>;
+export declare function unstable_buildPreviewDocumentRenderFrameFromReadsWithRuntime<TContext = unknown>(options: BuildPreviewDocumentRenderFrameFromReadsOptions<TContext>, runtime: PreviewProvenanceRuntime): Promise<PreviewDocumentRenderFrame<TContext> | null>;