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

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

@@ -0,0 +1,676 @@
+import { collectPreviewReadObservations } from '@storystick/client/internal';
+import { PREVIEW_PROVENANCE_CODED_TEXT_START, appliedPreviewVariantIdFromQueryResult, previewReadScopeEchoFromQueryResult, requestedPreviewVariantIdFromQueryResult, classifyPreviewProvenanceCodedTextTarget, collectPreviewProvenanceSourceMappedQueryResults, collectPreviewFrameDependencies, createPreviewProvenanceAttributeCarrierPlan, createPreviewProvenanceCodedTextCarrierPlan, createPreviewFrameDependencySet, createPublicSidecar, materializePreviewProvenanceSourceMap, previewProvenanceSourceSetForLeaf, recordPreviewProvenanceEditableLeaves, validateProvenanceFrame, } from '@storystick/preview/provenance';
+import { normalizePreviewVariantId } from '@storystick/preview/identity';
+import { defaultPreviewProvenanceRenderId } from './render-id.js';
+import { resolvePreviewFrameReadMetadataFromObservations, } from './preview-read-metadata.js';
+import { withPreviewProvenanceContext, } from '../provenance/render-context.js';
+import { buildPreviewProvenanceFrameWithRuntime, } from './provenance-frame-builder.js';
+import { createPreviewProvenanceTemporalIdentity, } from './provenance-runtime.js';
+const RENDER_FRAME_SOURCE_SET_CAP = 512;
+const RENDER_FRAME_MARKER_CAP = 2_048;
+const RENDER_FRAME_JSON_BYTES_CAP = 256 * 1024;
+const ESTIMATED_MARKER_ID = `p_${'x'.repeat(22)}`;
+export function unstable_previewRenderFrameRootAttrs(frame) {
+    return frame?.sessionId
+        ? { 'data-preview-message-session-id': frame.sessionId }
+        : {};
+}
+export async function unstable_buildPreviewRenderFrameWithRuntime(options, runtime) {
+    const enabled = options.enabled ?? runtime.config.isEnabled();
+    if (!enabled)
+        return null;
+    runtime.recorder.markNoStore({ enabled });
+    const codeVersion = options.codeVersion ?? runtime.config.resolveCodeVersion();
+    const readObservations = collectPreviewReadObservations(options.codedDocument, options.codedContext);
+    const readMetadata = typeof options.observationId === 'string' &&
+        typeof options.renderWatermark === 'number'
+        ? {
+            readContext: options.readContext,
+            receiptIds: options.receiptIds ?? [],
+            observationId: options.observationId,
+            renderWatermark: options.renderWatermark,
+        }
+        : resolvePreviewFrameReadMetadataFromObservations(codeVersion, readObservations);
+    if (readMetadata === null && readObservations.some((read) => read.readContext))
+        return null;
+    const input = {
+        runtime,
+        enabled,
+        frameId: options.frameId,
+        routeHash: options.routeHash,
+        variantId: options.variantId,
+        previewScope: options.previewScope,
+        fallbackPathname: options.fallbackPathname ?? options.pathname,
+        sessionId: options.sessionId,
+        codeVersion,
+        renderId: options.renderId,
+        generation: options.generation,
+        renderNonce: options.renderNonce,
+        emissionRevision: options.emissionRevision,
+        readMetadata,
+        authoritativeDocumentIds: options.authoritativeDocumentIds,
+        dependencies: [
+            ...(options.dependencies ?? []),
+            ...collectPreviewFrameDependencies(options.codedDocument, options.codedContext),
+        ],
+        leaves: options.leaves,
+        sourceMapDiagnostics: options.sourceMapDiagnostics ?? defaultSourceMapDiagnostics(options.leaves),
+        codedDocument: options.codedDocument,
+        codedContext: options.codedContext,
+        codedTextRoot: options.codedTextRoot ?? options.codedDocument,
+        codedTextRootPrefix: options.codedTextRootPrefix,
+        codedTextRootsByDocumentId: options.codedTextRootsByDocumentId,
+        fixture: options.fixture,
+        projectId: options.projectId,
+        endpoint: options.endpoint,
+        convexUrl: options.convexUrl,
+    };
+    const capped = capPreviewProvenanceLeaves(input);
+    if (input.fixture?.enabled) {
+        return buildFixtureRenderFrame(input, capped);
+    }
+    const result = await buildPreviewProvenanceFrameWithRuntime({
+        enabled: input.enabled,
+        frameId: input.frameId,
+        sessionId: input.sessionId,
+        routeHash: input.routeHash,
+        variantId: input.variantId,
+        previewScope: input.previewScope,
+        fallbackPathname: input.fallbackPathname,
+        codeVersion: input.codeVersion,
+        renderId: input.renderId,
+        generation: input.generation,
+        renderNonce: input.renderNonce,
+        emissionRevision: input.emissionRevision,
+        readContext: input.readMetadata?.readContext,
+        receiptIds: input.readMetadata?.receiptIds,
+        observationId: input.readMetadata?.observationId,
+        renderWatermark: input.readMetadata?.renderWatermark,
+        authoritativeDocumentIds: input.authoritativeDocumentIds,
+        dependencies: input.dependencies,
+        leaves: capped.leaves,
+        codedTextRoot: input.codedTextRoot,
+        codedTextRootPrefix: input.codedTextRootPrefix,
+        codedTextRootsByDocumentId: input.codedTextRootsByDocumentId,
+        projectId: input.projectId,
+        endpoint: input.endpoint,
+        convexUrl: input.convexUrl,
+    }, runtime);
+    if (result === null)
+        return null;
+    logPreviewProvenanceCodedTextWriteDebug({
+        frameId: input.frameId,
+        pathname: input.fallbackPathname,
+        cap: capped,
+        codedTextWrites: result.codedTextWrites,
+        codedDocument: input.codedDocument,
+        codedContext: input.codedContext,
+    });
+    return {
+        frameId: input.frameId,
+        sessionId: result.sessionId,
+        routeHash: result.routeHash,
+        variantId: result.variantId,
+        attrsByKey: result.attrsByKey,
+        codedDocument: attachPreviewProvenanceContext(input.codedDocument, result.attrsByKey),
+        codedContext: attachPreviewProvenanceContext(input.codedContext, result.attrsByKey),
+        renderFrame: result.renderFrame,
+        dependencySet: result.dependencySet,
+        publicSidecar: result.publicSidecar,
+        validationOk: result.validationOk,
+        diagnostics: previewRenderFrameDiagnostics({
+            input,
+            cap: capped,
+            frame: result.renderFrame,
+            publicSidecar: result.publicSidecar,
+            codedTextWrites: result.codedTextWrites,
+        }),
+    };
+}
+export async function unstable_buildPreviewDocumentRenderFrameFromReadsWithRuntime(options, runtime) {
+    const enabled = options.enabled ?? runtime.config.isEnabled();
+    if (!enabled)
+        return null;
+    const codedContext = options.context === undefined ? undefined : cloneJson(options.context);
+    const reads = options.documents ?? collectPreviewProvenanceSourceMappedQueryResults(options.context);
+    const documents = reads.map(normalizePreviewDocumentRenderFrameRead).filter((entry) => entry.document !== null && entry.document !== undefined);
+    const plans = documents.map((entry) => planPreviewDocumentRenderFrameRead({
+        frameId: options.frameId,
+        manifest: options.manifest,
+        read: entry,
+    }));
+    const sourceMapDiagnostics = summarizeDocumentMarkPlans(plans);
+    const codedTextRootsByDocumentId = codedTextRootsForRenderFrameReads({
+        reads: documents,
+        codedContext,
+    });
+    const dependencies = [
+        ...(options.dependencies ?? []),
+        ...dependenciesForRenderFrameReads(documents),
+        ...collectPreviewFrameDependencies(options.context, ...documents.map((read) => read.document)),
+    ];
+    const echoedAppliedVariantId = appliedVariantIdFromRenderFrameReads(documents);
+    const echoedRequestedVariantId = requestedVariantIdFromRenderFrameReads(documents);
+    const previewScope = previewScopeFromRenderFrameReads(documents);
+    const variantId = echoedAppliedVariantId !== undefined
+        ? echoedAppliedVariantId
+        : echoedRequestedVariantId !== undefined
+            ? echoedRequestedVariantId
+            : options.variantId === undefined
+                ? variantIdFromRenderFrameReads(documents)
+                : normalizePreviewVariantId(options.variantId);
+    const codeVersion = options.codeVersion ?? runtime.config.resolveCodeVersion();
+    const readObservations = collectPreviewReadObservations(options.context, ...documents.map((read) => read.document));
+    const readMetadata = resolvePreviewFrameReadMetadataFromObservations(codeVersion, readObservations);
+    if (readMetadata === null && readObservations.some((read) => read.readContext))
+        return null;
+    return unstable_buildPreviewRenderFrameWithRuntime({
+        enabled,
+        frameId: options.frameId,
+        routeHash: options.routeHash,
+        variantId: options.variantId === undefined ? variantId ?? undefined : variantId,
+        previewScope,
+        sessionId: options.sessionId,
+        codeVersion,
+        renderId: options.renderId,
+        generation: options.generation,
+        renderNonce: options.renderNonce,
+        emissionRevision: options.emissionRevision,
+        readContext: readMetadata?.readContext,
+        receiptIds: readMetadata?.receiptIds,
+        observationId: readMetadata?.observationId,
+        renderWatermark: readMetadata?.renderWatermark,
+        authoritativeDocumentIds: options.authoritativeDocumentIds ?? documents
+            .map((entry) => entry.document.documentId)
+            .filter((value) => value.length > 0),
+        dependencies,
+        leaves: plans.flatMap((plan) => plan.marks),
+        sourceMapDiagnostics,
+        codedContext,
+        codedTextRootPrefix: options.codedTextRootPrefix ?? [],
+        codedTextRootsByDocumentId,
+        fixture: options.fixture,
+        projectId: options.projectId,
+        endpoint: options.endpoint,
+        convexUrl: options.convexUrl,
+    }, runtime);
+}
+function normalizePreviewDocumentRenderFrameRead(read) {
+    if (isRecord(read) && 'document' in read) {
+        return read;
+    }
+    return { document: read };
+}
+function dependenciesForRenderFrameReads(reads) {
+    return reads.flatMap((read) => {
+        const storyType = read.storyType ?? storyTypeOf(read.document);
+        return [
+            {
+                kind: 'document',
+                documentId: read.document.documentId,
+                ...(storyType === 'unknown' ? {} : { storyType }),
+                reason: 'scope-document',
+            },
+            ...(read.dependencies ?? []),
+        ];
+    });
+}
+function variantIdFromRenderFrameReads(reads) {
+    for (const read of reads) {
+        const variantId = normalizePreviewVariantId(read.document._locale?.variantId) ??
+            normalizePreviewVariantId(read.document._variant?.variantId);
+        if (variantId !== null)
+            return variantId;
+    }
+    return null;
+}
+function appliedVariantIdFromRenderFrameReads(reads) {
+    let sawScopeEcho = false;
+    for (const read of reads) {
+        const appliedVariantId = appliedPreviewVariantIdFromQueryResult(read.document);
+        if (appliedVariantId === undefined)
+            continue;
+        sawScopeEcho = true;
+        if (appliedVariantId !== null)
+            return appliedVariantId;
+    }
+    return sawScopeEcho ? null : undefined;
+}
+function requestedVariantIdFromRenderFrameReads(reads) {
+    for (const read of reads) {
+        const requestedVariantId = requestedPreviewVariantIdFromQueryResult(read.document);
+        if (requestedVariantId !== undefined)
+            return requestedVariantId;
+    }
+    return undefined;
+}
+function previewScopeFromRenderFrameReads(reads) {
+    let fallback;
+    for (const read of reads) {
+        const scope = previewReadScopeEchoFromQueryResult(read.document);
+        if (scope === undefined)
+            continue;
+        fallback ??= scope;
+        if (scope.appliesToDocument !== false)
+            return scope;
+    }
+    return fallback;
+}
+function defaultSourceMapDiagnostics(leaves) {
+    return {
+        entries: leaves.length,
+        manifestIneligible: 0,
+        nonIdentityDerivation: 0,
+        carrierSkipped: 0,
+    };
+}
+function planPreviewDocumentRenderFrameRead(input) {
+    const storyType = input.read.storyType ?? storyTypeOf(input.read.document);
+    const fields = input.read.fields ?? input.read.document.fields;
+    if (fields === null || fields === undefined) {
+        return emptyDocumentMarkPlan();
+    }
+    const queryResult = input.read.fields === undefined && input.read.storyType === undefined
+        ? input.read.document
+        : {
+            documentId: input.read.document.documentId,
+            storyType,
+            fields,
+        };
+    const materialized = materializePreviewProvenanceSourceMap({
+        queryResult,
+        manifest: input.manifest,
+        // Keys remain document-scoped here. Source-set document scoping belongs to
+        // the materializer so every caller receives it exactly once.
+        keyPrefix: input.read.keyPrefix ??
+            `${input.frameId}:${storyType}:${input.read.document.documentId}`,
+        sourceSetPrefix: input.read.sourceSetPrefix ??
+            `${safeSourceSetPart(input.frameId)}_${safeSourceSetPart(storyType)}`,
+        presence: 'optional',
+    });
+    const marks = materialized.leaves.flatMap((leaf) => {
+        if (input.read.renderedLeavesPolicy === undefined)
+            return [leaf];
+        const expected = input.read.renderedLeavesPolicy({
+            document: input.read.document,
+            storyType,
+            fields,
+            canonicalPath: leaf.canonicalPath,
+            leaf,
+        });
+        return expected ? [{ ...leaf, presence: 'expected' }] : [];
+    });
+    return documentMarkPlan(marks, materialized, {
+        carrierSkipped: materialized.leaves.length - marks.length,
+    });
+}
+function codedTextRootsForRenderFrameReads(input) {
+    const roots = new Map();
+    const contextDocuments = new Map(collectPreviewProvenanceSourceMappedQueryResults(input.codedContext)
+        .map((document) => [document.documentId, document]));
+    for (const read of input.reads) {
+        if (read.codedTextRootPath) {
+            const root = valueAtPath(input.codedContext, read.codedTextRootPath);
+            if (root !== undefined)
+                roots.set(read.document.documentId, root);
+            continue;
+        }
+        const contextDocument = contextDocuments.get(read.document.documentId);
+        if (contextDocument && isRecord(contextDocument.fields)) {
+            roots.set(read.document.documentId, contextDocument.fields);
+        }
+    }
+    return roots;
+}
+function emptyDocumentMarkPlan() {
+    return {
+        marks: [],
+        sourceMapEntries: 0,
+        skipped: {
+            manifestIneligible: 0,
+            nonIdentityDerivation: 0,
+        },
+        carrierSkipped: 0,
+    };
+}
+function documentMarkPlan(marks, materialized, options = {}) {
+    return {
+        marks,
+        sourceMapEntries: materialized.sourceMapEntries,
+        skipped: materialized.skipped,
+        carrierSkipped: options.carrierSkipped ?? 0,
+    };
+}
+function summarizeDocumentMarkPlans(plans) {
+    return {
+        entries: sum(plans, (plan) => plan.sourceMapEntries),
+        manifestIneligible: sum(plans, (plan) => plan.skipped.manifestIneligible),
+        nonIdentityDerivation: sum(plans, (plan) => plan.skipped.nonIdentityDerivation),
+        carrierSkipped: sum(plans, (plan) => plan.carrierSkipped),
+    };
+}
+function capPreviewProvenanceLeaves(input) {
+    const leaves = [];
+    let capped = false;
+    for (const leaf of input.leaves) {
+        if (leaves.length >= RENDER_FRAME_SOURCE_SET_CAP ||
+            leaves.length >= RENDER_FRAME_MARKER_CAP) {
+            capped = true;
+            continue;
+        }
+        const candidate = [...leaves, leaf];
+        if (estimatePreviewProvenanceFrameBytes(input, candidate) >
+            RENDER_FRAME_JSON_BYTES_CAP) {
+            capped = true;
+            continue;
+        }
+        leaves.push(leaf);
+    }
+    return {
+        leaves,
+        dropped: input.leaves.length - leaves.length,
+        capped,
+    };
+}
+function previewRenderFrameDiagnostics(input) {
+    const carrierSkipped = input.input.sourceMapDiagnostics.carrierSkipped +
+        input.cap.dropped +
+        countSkippedCarrierPlans(input.publicSidecar) +
+        input.codedTextWrites.failures.length;
+    return {
+        sourceMapEntries: input.input.sourceMapDiagnostics.entries,
+        carriersWritten: countWrittenCarrierPlans(input.publicSidecar),
+        carrierSkipped,
+        frameBytes: jsonByteLength(input.frame),
+        frameCapped: input.cap.capped,
+        skipped: {
+            manifestIneligible: input.input.sourceMapDiagnostics.manifestIneligible,
+            nonIdentityDerivation: input.input.sourceMapDiagnostics.nonIdentityDerivation,
+            cap: input.cap.dropped,
+            codedTextWriteFailures: input.codedTextWrites.failures.length,
+        },
+    };
+}
+function estimatePreviewProvenanceFrameBytes(input, leaves) {
+    const routeHash = input.routeHash ?? 'x'.repeat(64);
+    const codeVersion = input.codeVersion ?? input.runtime.config.resolveCodeVersion();
+    const renderId = input.renderId ??
+        defaultPreviewProvenanceRenderId({
+            frameId: input.frameId,
+            routeHash,
+        });
+    const frame = {
+        type: 'storystick.preview.provenance-frame',
+        version: 1,
+        sessionId: input.sessionId ?? input.fixture?.sessionId ?? 'preview-session',
+        routeHash,
+        ...(normalizePreviewVariantId(input.variantId) !== null
+            ? { variantId: normalizePreviewVariantId(input.variantId) }
+            : {}),
+        codeVersion,
+        renderId,
+        generation: input.generation ?? 1,
+        sourceSets: leaves.map(estimatedSourceSetForLeaf),
+        markers: leaves.map((leaf) => ({
+            markerId: ESTIMATED_MARKER_ID,
+            sourceSetId: leaf.sourceSetId,
+            modality: 'text',
+            anchorKind: 'element',
+            carrierPlans: estimatedCarrierPlansForLeaf(leaf),
+            anchorMultiplicity: leaf.anchorMultiplicity,
+            presence: leaf.presence,
+            renderedTextFingerprint: 'txt:000000:000000',
+        })),
+    };
+    return jsonByteLength(frame);
+}
+function estimatedSourceSetForLeaf(leaf) {
+    return previewProvenanceSourceSetForLeaf(leaf);
+}
+function estimatedCarrierPlansForLeaf(leaf) {
+    const carrierPlans = [
+        createPreviewProvenanceAttributeCarrierPlan({
+            modality: 'text',
+            anchorKind: 'element',
+        }),
+    ];
+    if (leaf.codedRichTextTextNodeIndex !== undefined) {
+        carrierPlans.push(createPreviewProvenanceCodedTextCarrierPlan({
+            surface: 'rich-text-text-node',
+        }));
+    }
+    else if (leaf.codedText === true || leaf.codedTextPath !== undefined) {
+        const policy = classifyPreviewProvenanceCodedTextTarget({
+            canonicalPath: leaf.navigationPath ?? leaf.canonicalPath,
+            sourceKind: leaf.sourceKind === 'richtext' ? 'richtext' : 'stored',
+        });
+        if (policy.allowed) {
+            carrierPlans.push(createPreviewProvenanceCodedTextCarrierPlan({
+                surface: policy.surface,
+            }));
+        }
+    }
+    return carrierPlans;
+}
+function countWrittenCarrierPlans(sidecar) {
+    return sum(sidecar?.markers ?? [], (marker) => (marker.carrierPlans ?? []).filter((plan) => plan.status === 'emitted')
+        .length);
+}
+function countSkippedCarrierPlans(sidecar) {
+    return sum(sidecar?.markers ?? [], (marker) => (marker.carrierPlans ?? []).filter((plan) => plan.status !== 'emitted')
+        .length);
+}
+async function buildFixtureRenderFrame(input, capped) {
+    const identity = await resolveFixturePreviewIdentity(input);
+    const codeVersion = input.codeVersion ?? input.runtime.config.resolveCodeVersion();
+    const renderId = input.renderId ??
+        defaultPreviewProvenanceRenderId({
+            frameId: input.frameId,
+            routeHash: identity.routeHash,
+        });
+    const generation = input.generation ?? 1;
+    const generatedTemporalIdentity = createPreviewProvenanceTemporalIdentity(input.runtime, {
+        sessionId: identity.sessionId,
+        frameId: input.frameId,
+        routeHash: identity.routeHash,
+        codeVersion,
+        renderId,
+        generation,
+    });
+    const recorded = await recordPreviewProvenanceEditableLeaves({
+        sessionId: identity.sessionId,
+        routeHash: identity.routeHash,
+        variantId: identity.variantId,
+        previewScope: input.previewScope,
+        codeVersion,
+        renderId,
+        generation,
+        renderNonce: input.renderNonce ?? generatedTemporalIdentity.renderNonce,
+        emissionRevision: input.emissionRevision ?? generatedTemporalIdentity.emissionRevision,
+        enabled: input.enabled,
+        leaves: capped.leaves,
+        codedTextRoot: input.codedTextRoot,
+        codedTextRootPrefix: input.codedTextRootPrefix,
+        codedTextRootsByDocumentId: input.codedTextRootsByDocumentId,
+    });
+    const dependencySet = createPreviewFrameDependencySet({
+        sessionId: identity.sessionId,
+        routeHash: identity.routeHash,
+        variantId: identity.variantId,
+        codeVersion,
+        frameId: input.frameId,
+        renderId,
+        generation,
+        observationId: input.readMetadata?.observationId,
+        renderWatermark: input.readMetadata?.renderWatermark,
+        dependencies: input.dependencies ?? input.authoritativeDocumentIds.map((documentId) => ({
+            kind: 'document',
+            documentId,
+            reason: 'rendered-document',
+        })),
+    });
+    const validation = validateProvenanceFrame(recorded.renderFrame, {
+        documentIds: new Set(input.authoritativeDocumentIds),
+        routeHash: identity.routeHash,
+        variantId: identity.variantId,
+        codeVersion,
+    });
+    const publicSidecar = recorded.publicSidecar === null
+        ? null
+        : createPublicSidecar(recorded.renderFrame, dependencySet);
+    return {
+        frameId: input.frameId,
+        sessionId: identity.sessionId,
+        routeHash: identity.routeHash,
+        variantId: identity.variantId,
+        attrsByKey: recorded.attrsByKey,
+        codedDocument: attachPreviewProvenanceContext(input.codedDocument, recorded.attrsByKey),
+        codedContext: attachPreviewProvenanceContext(input.codedContext, recorded.attrsByKey),
+        renderFrame: recorded.renderFrame,
+        dependencySet,
+        publicSidecar,
+        validationOk: validation.ok,
+        diagnostics: previewRenderFrameDiagnostics({
+            input,
+            cap: capped,
+            frame: recorded.renderFrame,
+            publicSidecar,
+            codedTextWrites: recorded.codedTextWrites,
+        }),
+    };
+}
+async function resolveFixturePreviewIdentity(input) {
+    const fixture = input.fixture;
+    const explicitVariantId = input.variantId === undefined
+        ? undefined
+        : normalizePreviewVariantId(input.variantId);
+    const fallbackSessionId = fixture?.sessionId ?? input.sessionId ?? '';
+    const liveSessionId = await input.runtime.recorder.readSessionId();
+    const sessionId = liveSessionId ?? fallbackSessionId;
+    const liveRouteIdentity = liveSessionId !== null && input.variantId === undefined
+        ? await input.runtime.recorder.resolveRouteIdentity({
+            sessionId,
+            fallbackPathname: input.fallbackPathname,
+            projectId: input.projectId,
+            endpoint: input.endpoint,
+            convexUrl: input.convexUrl,
+        }).catch(() => null)
+        : null;
+    const fallbackVariantId = explicitVariantId !== undefined
+        ? explicitVariantId
+        : liveRouteIdentity?.variantId ?? normalizePreviewVariantId(fixture?.variantId);
+    if (input.routeHash !== undefined) {
+        return {
+            sessionId,
+            routeHash: input.routeHash,
+            variantId: fallbackVariantId,
+        };
+    }
+    if (liveSessionId !== null) {
+        const routeIdentity = liveRouteIdentity ??
+            await input.runtime.recorder.resolveRouteIdentity({
+                sessionId,
+                fallbackPathname: input.fallbackPathname,
+                projectId: input.projectId,
+                endpoint: input.endpoint,
+                convexUrl: input.convexUrl,
+            }).catch(() => null);
+        if (routeIdentity !== null) {
+            return {
+                sessionId,
+                routeHash: routeIdentity.routeHash,
+                variantId: fallbackVariantId ?? routeIdentity.variantId,
+            };
+        }
+    }
+    return {
+        sessionId,
+        routeHash: fixture?.routeHash ??
+            `route:${input.fallbackPathname || '/'}`,
+        variantId: fallbackVariantId,
+    };
+}
+function logPreviewProvenanceCodedTextWriteDebug(input) {
+    if (process.env.STORYSTICK_PREVIEW_PROVENANCE_DEBUG !== '1')
+        return;
+    const contextMarkerCounts = {};
+    if (isRecord(input.codedContext)) {
+        for (const [key, value] of Object.entries(input.codedContext)) {
+            const count = countCodedTextMarkers(value);
+            if (count > 0)
+                contextMarkerCounts[key] = count;
+        }
+    }
+    console.warn('[preview-provenance] coded-text writes', {
+        frameId: input.frameId,
+        pathname: input.pathname ?? null,
+        attempted: input.codedTextWrites.attempted,
+        written: input.codedTextWrites.written,
+        failures: input.codedTextWrites.failures.length,
+        capDropped: input.cap.dropped,
+        capApplied: input.cap.capped,
+        markersInCodedDocument: countCodedTextMarkers(input.codedDocument),
+        markersInCodedContext: countCodedTextMarkers(input.codedContext),
+        markersInCodedContextByKey: contextMarkerCounts,
+    });
+    for (const failure of input.codedTextWrites.failures.slice(0, 48)) {
+        console.warn('[preview-provenance] coded-text write failure', failure);
+    }
+}
+function countCodedTextMarkers(value) {
+    if (value === undefined)
+        return 0;
+    try {
+        const json = JSON.stringify(value);
+        if (typeof json !== 'string')
+            return 0;
+        return json.split(PREVIEW_PROVENANCE_CODED_TEXT_START).length - 1;
+    }
+    catch {
+        return 0;
+    }
+}
+function attachPreviewProvenanceContext(value, attrsByKey) {
+    if (value === undefined)
+        return undefined;
+    return withPreviewProvenanceContext(value, attrsByKey);
+}
+function jsonByteLength(value) {
+    return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+function sum(values, valueOf) {
+    let total = 0;
+    for (const value of values)
+        total += valueOf(value);
+    return total;
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function valueAtPath(root, path) {
+    let cursor = root;
+    for (const part of path) {
+        if (typeof part === 'number') {
+            if (!Array.isArray(cursor))
+                return undefined;
+            cursor = cursor[part];
+            continue;
+        }
+        if (!isRecord(cursor))
+            return undefined;
+        cursor = cursor[part];
+    }
+    return cursor;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function storyTypeOf(document) {
+    return typeof document.storyType === 'string' && document.storyType.length > 0
+        ? document.storyType
+        : 'unknown';
+}
+function safeSourceSetPart(value) {
+    return value.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '') ||
+        'field';
+}

package/dist/server/render-id.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deterministic preview render-id derivation.
+ *
+ * Marker identity (HMAC) incorporates the renderId, so the stability of
+ * every provenance marker across refreshes rests on this derivation
+ * having ZERO temporal or random components. Pinned by
+ * tests/preview-provenance-render-id.test.ts — do not add Date/random
+ * inputs here.
+ */
+export declare function defaultPreviewProvenanceRenderId(input: {
+    readonly frameId: string;
+    readonly routeHash: string;
+}): string;
+/** Independent mounts of the same document must not replace each other's frame. */
+export declare function createPreviewOccurrenceId(): string;