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

package/dist/provenance/owner-map.js

@@ -0,0 +1,239 @@
+import { parsePreviewRichTextSliceEmbedAddress } from './richtext-slice-embed-address.js';
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+import { hasCoherentPreviewProvenanceSourceIdentity } from './source-identity.js';
+export function hasCompleteDirectLocatorCoverage(anchorMap) {
+    let locatorCount = 0;
+    for (const map of anchorMap.maps) {
+        const markerIds = new Set((map.editLocators ?? []).map((entry) => entry.markerId));
+        locatorCount += markerIds.size;
+        if (map.sidecarMarkerIds.some((markerId) => !markerIds.has(markerId))) {
+            return false;
+        }
+    }
+    return locatorCount > 0;
+}
+/**
+ * Resolve owners entirely from the public render payload delivered with the
+ * anchor map. The sidecar and observed anchors are the complete click
+ * authority; no second transport or document hydration participates.
+ */
+export function resolveDirectProvenanceOwnerMap(input) {
+    const rejections = [];
+    const owners = [];
+    const ownerByMarkerId = new Map();
+    const ambiguousMarkerIds = new Set();
+    const reject = (rejection) => {
+        rejections.push(rejection);
+    };
+    if (input.anchorMap.pending || !input.anchorMap.valid) {
+        reject({ reason: 'anchor-map-not-paintable' });
+        return finish(owners, ownerByMarkerId, rejections);
+    }
+    for (const map of input.anchorMap.maps) {
+        if (!map.valid) {
+            reject({ reason: 'anchor-map-not-paintable', frameId: map.frameId });
+            continue;
+        }
+        const directByMarkerId = new Map((map.editLocators ?? []).map((entry) => [entry.markerId, entry]));
+        const candidateMarkerIds = new Set(map.anchors.map((anchor) => anchor.markerId));
+        for (const markerId of map.unpaintedMarkerIds) {
+            if (directByMarkerId.get(markerId)?.presence === 'expected') {
+                candidateMarkerIds.add(markerId);
+            }
+        }
+        for (const markerId of map.ambiguousMarkerIds) {
+            candidateMarkerIds.add(markerId);
+        }
+        for (const markerId of candidateMarkerIds) {
+            if (ambiguousMarkerIds.has(markerId))
+                continue;
+            const direct = directByMarkerId.get(markerId);
+            if (!direct) {
+                reject({ reason: 'edit-locator-missing', frameId: map.frameId, markerId });
+                continue;
+            }
+            if (!hasCoherentPreviewProvenanceSourceIdentity(direct.locator)) {
+                reject({
+                    reason: 'edit-locator-variant-mismatch',
+                    frameId: map.frameId,
+                    markerId,
+                });
+                continue;
+            }
+            const owner = resolvedOwnerFromDirectLocator({
+                markerId,
+                frameId: map.frameId,
+                locator: direct.locator,
+                modality: direct.modality,
+                presence: direct.presence,
+            });
+            const existingOwner = ownerByMarkerId.get(markerId);
+            if (existingOwner !== undefined) {
+                if (sameOwner(existingOwner, owner))
+                    continue;
+                reject({ reason: 'duplicate-marker-owner', frameId: map.frameId, markerId });
+                ambiguousMarkerIds.add(markerId);
+                ownerByMarkerId.delete(markerId);
+                removeOwner(owners, markerId);
+                continue;
+            }
+            owners.push(owner);
+            ownerByMarkerId.set(markerId, owner);
+        }
+    }
+    return finish(owners, ownerByMarkerId, rejections);
+}
+export function buildProvenanceSnapshotItems(input) {
+    if (input.anchorMap.pending || !input.anchorMap.valid || !input.ownerMap.valid) {
+        return [];
+    }
+    const items = [];
+    for (const map of input.anchorMap.maps) {
+        if (!map.valid)
+            return [];
+        for (const anchor of map.anchors) {
+            const owner = input.ownerMap.ownerByMarkerId.get(anchor.markerId);
+            if (owner === undefined)
+                continue;
+            if (anchor.paintId === undefined || anchor.paintId.length === 0)
+                continue;
+            if (!isFiniteDocumentRect(anchor.documentRect))
+                continue;
+            items.push({
+                kind: 'field',
+                snapshotItemKey: anchor.paintId,
+                method: 'observed',
+                documentId: owner.documentId,
+                sliceKey: owner.fromAnchors.find((candidate) => candidate.pathPrefix === 'sections')?.key,
+                path: owner.canonicalPath,
+                fromAnchors: owner.fromAnchors,
+                ...(owner.navigationPath !== undefined
+                    ? { navigationPath: owner.navigationPath }
+                    : {}),
+                ...(owner.navigationAnchors !== undefined
+                    ? { navigationAnchors: owner.navigationAnchors }
+                    : {}),
+                field: owner.field,
+                documentRect: anchor.documentRect,
+                tier: { kind: 'observed' },
+            });
+        }
+    }
+    return items;
+}
+function removeOwner(owners, markerId) {
+    const index = owners.findIndex((owner) => owner.markerId === markerId);
+    if (index >= 0)
+        owners.splice(index, 1);
+}
+function sameOwner(a, b) {
+    return a.frameId === b.frameId &&
+        a.sourceSetId === b.sourceSetId &&
+        a.documentId === b.documentId &&
+        normalizePreviewVariantId(a.variantId) === normalizePreviewVariantId(b.variantId) &&
+        a.canonicalPath === b.canonicalPath &&
+        a.navigationPath === b.navigationPath &&
+        a.richTextTextNodeIndex === b.richTextTextNodeIndex &&
+        a.richTextSliceEmbedIndex === b.richTextSliceEmbedIndex &&
+        a.richTextSliceEmbedKey === b.richTextSliceEmbedKey &&
+        a.presence === b.presence;
+}
+function resolvedOwnerFromDirectLocator(input) {
+    const source = {
+        documentId: input.locator.documentId,
+        ...(input.locator.variantId !== undefined
+            ? { variantId: input.locator.variantId }
+            : {}),
+        canonicalPath: input.locator.canonicalPath,
+        pathAnchors: input.locator.pathAnchors,
+        ...(input.locator.navigationPath !== undefined
+            ? { navigationPath: input.locator.navigationPath }
+            : {}),
+        ...(input.locator.navigationAnchors !== undefined
+            ? { navigationAnchors: input.locator.navigationAnchors }
+            : {}),
+        ...(input.locator.textNodeIndex !== undefined
+            ? { textNodeIndex: input.locator.textNodeIndex }
+            : {}),
+        sourceKind: input.locator.sourceKind,
+        ...(input.locator.readScope !== undefined
+            ? { readScope: input.locator.readScope }
+            : {}),
+    };
+    return {
+        markerId: input.markerId,
+        frameId: input.frameId,
+        sourceSetId: input.locator.sourceSetId,
+        documentId: input.locator.documentId,
+        ...(input.locator.variantId !== undefined
+            ? { variantId: input.locator.variantId }
+            : {}),
+        ...(input.locator.readScope !== undefined
+            ? { readScope: input.locator.readScope }
+            : {}),
+        canonicalPath: input.locator.canonicalPath,
+        ...(input.locator.navigationPath !== undefined
+            ? { navigationPath: input.locator.navigationPath }
+            : {}),
+        ...(input.locator.textNodeIndex !== undefined
+            ? { richTextTextNodeIndex: input.locator.textNodeIndex }
+            : {}),
+        ...richTextSliceEmbedAddressForSource(source),
+        pathAnchors: input.locator.pathAnchors,
+        fromAnchors: input.locator.pathAnchors.map((anchor) => ({
+            pathPrefix: anchor.path,
+            key: anchor.key,
+        })),
+        ...(input.locator.navigationAnchors !== undefined
+            ? {
+                navigationAnchors: input.locator.navigationAnchors.map((anchor) => ({
+                    pathPrefix: anchor.path,
+                    key: anchor.key,
+                })),
+            }
+            : {}),
+        sourceKind: input.locator.sourceKind,
+        modality: input.modality,
+        ...(input.presence !== undefined ? { presence: input.presence } : {}),
+        field: extractLeafField(input.locator.canonicalPath),
+    };
+}
+function richTextSliceEmbedAddressForSource(source) {
+    const addressPath = source.navigationPath ?? source.canonicalPath;
+    const address = parsePreviewRichTextSliceEmbedAddress(addressPath);
+    if (address === null)
+        return {};
+    const anchors = source.navigationAnchors ?? source.pathAnchors;
+    const key = anchors.find((anchor) => anchor.path === address.rootPath)?.key;
+    return {
+        richTextSliceEmbedIndex: address.index,
+        ...(key !== undefined ? { richTextSliceEmbedKey: key } : {}),
+    };
+}
+function extractLeafField(path) {
+    const dotIndex = path.lastIndexOf('.');
+    if (dotIndex >= 0)
+        return path.slice(dotIndex + 1);
+    return path.includes('[') ? '' : path;
+}
+function finish(owners, ownerByMarkerId, rejections) {
+    const valid = rejections.length === 0;
+    return {
+        // One unresolved or contradictory marker invalidates the whole render
+        // candidate. Painting a partial map would make click authority depend on
+        // traversal order while a streamed frame is settling.
+        valid,
+        owners: valid ? owners : [],
+        ownerByMarkerId: valid
+            ? ownerByMarkerId
+            : new Map(),
+        rejections,
+    };
+}
+function isFiniteDocumentRect(rect) {
+    return (rect !== undefined &&
+        Number.isFinite(rect.x) &&
+        Number.isFinite(rect.y) &&
+        Number.isFinite(rect.width) &&
+        Number.isFinite(rect.height));
+}

package/dist/provenance/read-carrier.d.ts

@@ -0,0 +1,22 @@
+import type { PublicProvenanceSidecar, PublicSidecarMarker } from './sidecar.js';
+/** Identity of the route resolved by the site, not an edit/access capability. */
+export interface PreviewPrimaryPage {
+    readonly documentId: string;
+    readonly locale: string;
+    readonly publicPathname: string;
+}
+/** Select only unambiguous metadata for the route actually rendered. Closed over
+ * no module state so the same rule runs in the injected reporter and Studio return link. */
+export declare function selectPreviewPrimaryPage(pages: readonly unknown[], browserPathname: string, basePath?: string): PreviewPrimaryPage | null;
+/** Self-contained, public read provenance. No token, content value or private graph. */
+export declare function encodePreviewReadCarrier(frameId: string, sidecar: PublicProvenanceSidecar, marker: PublicSidecarMarker, primaryPage?: PreviewPrimaryPage): string;
+/**
+ * Shape decoding only. Consumers must normalize the sidecar and validate the
+ * read context against the authorized view. Kept closed over no module state so
+ * the same implementation can be embedded in the zero-dependency browser runtime.
+ */
+export declare function decodePreviewReadCarrier(value: unknown): {
+    frameId: string;
+    sidecar: PublicProvenanceSidecar;
+    primaryPage?: PreviewPrimaryPage;
+} | null;

package/dist/provenance/read-carrier.js

@@ -0,0 +1,92 @@
+/** Select only unambiguous metadata for the route actually rendered. Closed over
+ * no module state so the same rule runs in the injected reporter and Studio return link. */
+export function selectPreviewPrimaryPage(pages, browserPathname, basePath = '') {
+    const base = basePath.replace(/\/$/, '');
+    const pathname = base && (browserPathname === base || browserPathname.startsWith(base + '/'))
+        ? browserPathname.slice(base.length) || '/' : browserPathname;
+    const canonical = (path) => new URL(path, 'https://preview.invalid').pathname.replace(/\/$/, '') || '/';
+    let selected = null;
+    for (const value of pages) {
+        const page = value;
+        if (!page || typeof page.documentId !== 'string' || !page.documentId || page.documentId.length > 180 ||
+            typeof page.locale !== 'string' || !page.locale || page.locale.length > 100 || typeof page.publicPathname !== 'string' ||
+            !page.publicPathname.startsWith('/') || page.publicPathname.startsWith('//') || /[\\?#\u0000-\u0020]/.test(page.publicPathname))
+            return null;
+        if (canonical(page.publicPathname) !== canonical(pathname))
+            continue;
+        if (selected && (selected.documentId !== page.documentId || selected.locale !== page.locale))
+            return null;
+        selected = page;
+    }
+    return selected;
+}
+/** Self-contained, public read provenance. No token, content value or private graph. */
+export function encodePreviewReadCarrier(frameId, sidecar, marker, primaryPage) {
+    const dependency = sidecar.dependencySet;
+    const value = [frameId, sidecar.codeVersion, sidecar.variantId ?? null,
+        sidecar.renderId, sidecar.renderNonce, sidecar.emissionRevision,
+        dependency?.readContext ?? null, dependency?.receiptIds ?? [],
+        dependency?.renderWatermark ?? null, dependency?.sessionId ?? null,
+        sidecar.previewScope ?? null,
+        [marker.markerId, marker.editLocator ?? null, marker.modality, marker.anchorKind,
+            marker.renderedTextFingerprint ?? null], primaryPage ?? null];
+    const bytes = new TextEncoder().encode(JSON.stringify(value));
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    const result = 'ssr1.' + btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+    if (result.length > 32_768)
+        throw new Error('Preview read carrier exceeds its size limit.');
+    return result;
+}
+/**
+ * Shape decoding only. Consumers must normalize the sidecar and validate the
+ * read context against the authorized view. Kept closed over no module state so
+ * the same implementation can be embedded in the zero-dependency browser runtime.
+ */
+export function decodePreviewReadCarrier(value) {
+    if (typeof value !== 'string' || !value.startsWith('ssr1.') || value.length > 32_768)
+        return null;
+    try {
+        const binary = atob(value.slice(5).replace(/-/g, '+').replace(/_/g, '/'));
+        const text = decodeURIComponent(Array.from(binary, char => '%' + char.charCodeAt(0).toString(16).padStart(2, '0')).join(''));
+        const row = JSON.parse(text);
+        if (!Array.isArray(row) || row.length !== 13 ||
+            ![row[0], row[1], row[3], row[4]].every(part => typeof part === 'string' && part.length > 0 && part.length <= 512) ||
+            !Number.isSafeInteger(row[5]) || row[5] <= 0 ||
+            !Array.isArray(row[7]) || row[7].length > 64 ||
+            !row[7].every((id) => typeof id === 'string' && id.length <= 512) ||
+            !Array.isArray(row[11]) || row[11].length !== 5)
+            return null;
+        const [frameId, codeVersion, variantId, renderId, renderNonce, emissionRevision, readContext, receiptIds, renderWatermark, sessionId, previewScope, marker, primaryPage] = row;
+        if (primaryPage !== null && (!primaryPage || typeof primaryPage !== 'object' ||
+            typeof primaryPage.documentId !== 'string' || !primaryPage.documentId || primaryPage.documentId.length > 180 ||
+            typeof primaryPage.locale !== 'string' || !primaryPage.locale || primaryPage.locale.length > 100 ||
+            typeof primaryPage.publicPathname !== 'string' || primaryPage.publicPathname.length > 8192 ||
+            !primaryPage.publicPathname.startsWith('/') || primaryPage.publicPathname.startsWith('//') ||
+            /[\\?#\u0000-\u0020]/.test(primaryPage.publicPathname)))
+            return null;
+        const routeHash = 'occurrence:' + frameId;
+        return { frameId, ...(primaryPage ? { primaryPage } : {}), sidecar: {
+                type: 'storystick.preview.public-sidecar', version: 1,
+                routeHash, codeVersion, renderId, renderNonce, emissionRevision, generation: 1,
+                ...(variantId ? { variantId } : {}),
+                ...(previewScope ? { previewScope } : {}),
+                dependencySet: {
+                    type: 'storystick.preview.frame-dependency-set', version: 1,
+                    frameId, routeHash, codeVersion, renderId, generation: 1,
+                    ...(sessionId ? { sessionId } : {}),
+                    ...(readContext === null ? {} : { readContext }),
+                    ...(variantId ? { variantId } : {}),
+                    receiptIds, ...(renderWatermark === null ? {} : { renderWatermark }), dependencies: [],
+                },
+                markers: [{ markerId: marker[0], ...(marker[1] ? { editLocator: marker[1] } : {}),
+                        modality: marker[2], anchorKind: marker[3], anchorMultiplicity: 'multi', presence: 'optional',
+                        ...(marker[4] ? { renderedTextFingerprint: marker[4] } : {}),
+                    }],
+            } };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/provenance/recorder.d.ts

@@ -0,0 +1,38 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { MarkerRecord, PreviewProvenanceCarrierPlan, ProvenanceFrame, SourceSet } from './types.js';
+export interface ProvenanceRecorderOptions {
+    readonly sessionId?: string;
+    readonly readContext?: PreviewReadContext;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string | null;
+    readonly previewScope?: PreviewReadScopeEcho;
+    readonly renderId: string;
+    readonly generation: number;
+    readonly renderNonce?: string;
+    readonly emissionRevision?: number;
+    readonly enabled?: boolean;
+}
+export interface MarkOptions {
+    readonly modality: MarkerRecord['modality'];
+    readonly anchorKind: MarkerRecord['anchorKind'];
+    readonly carrierPlans?: readonly PreviewProvenanceCarrierPlan[];
+    readonly anchorMultiplicity?: MarkerRecord['anchorMultiplicity'];
+    readonly presence?: MarkerRecord['presence'];
+    readonly renderedText?: string;
+}
+export interface RegisteredMark {
+    readonly markerId: string | null;
+    readonly sourceSetId: string;
+    readonly attrs: Readonly<Record<string, string>>;
+    readonly carrierPlans: readonly PreviewProvenanceCarrierPlan[];
+}
+export declare class ProvenanceRecorder {
+    private readonly options;
+    private readonly sourceSets;
+    private readonly markers;
+    constructor(options: ProvenanceRecorderOptions);
+    mark(sourceSet: SourceSet, options: MarkOptions): Promise<RegisteredMark>;
+    flush(): ProvenanceFrame;
+}

package/dist/provenance/recorder.js

@@ -0,0 +1,82 @@
+import { createDirectEditMarkerId } from './markers.js';
+import { fingerprintRenderedText } from './normalize.js';
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+import { attrsForPreviewProvenanceCarrierPlans, createPreviewProvenanceAttributeCarrierPlan, } from './carrier-plan.js';
+export class ProvenanceRecorder {
+    options;
+    sourceSets = new Map();
+    markers = [];
+    constructor(options) {
+        this.options = options;
+    }
+    async mark(sourceSet, options) {
+        const carrierPlans = options.carrierPlans ?? [
+            createPreviewProvenanceAttributeCarrierPlan({
+                modality: options.modality,
+                anchorKind: options.anchorKind,
+            }),
+        ];
+        if (this.options.enabled === false) {
+            return {
+                markerId: null,
+                sourceSetId: sourceSet.id,
+                attrs: {},
+                carrierPlans,
+            };
+        }
+        this.sourceSets.set(sourceSet.id, sourceSet);
+        const markerId = await createDirectEditMarkerId({
+            ...(this.options.sessionId ? { sessionId: this.options.sessionId } : {}),
+            ...(this.options.readContext ? { readContext: this.options.readContext } : {}),
+            routeHash: this.options.routeHash,
+            codeVersion: this.options.codeVersion,
+            variantId: this.options.variantId,
+            renderId: this.options.renderId,
+            sourceSetId: sourceSet.id,
+        });
+        this.markers.push({
+            markerId,
+            sourceSetId: sourceSet.id,
+            modality: options.modality,
+            anchorKind: options.anchorKind,
+            carrierPlans,
+            anchorMultiplicity: options.anchorMultiplicity,
+            presence: options.presence,
+            renderedTextFingerprint: options.renderedText === undefined
+                ? undefined
+                : fingerprintRenderedText(options.renderedText),
+        });
+        return {
+            markerId,
+            sourceSetId: sourceSet.id,
+            attrs: attrsForPreviewProvenanceCarrierPlans(markerId, carrierPlans),
+            carrierPlans,
+        };
+    }
+    flush() {
+        return {
+            type: 'storystick.preview.provenance-frame',
+            version: 1,
+            ...(this.options.sessionId ? { sessionId: this.options.sessionId } : {}),
+            ...(this.options.readContext ? { readContext: this.options.readContext } : {}),
+            routeHash: this.options.routeHash,
+            codeVersion: this.options.codeVersion,
+            ...(normalizePreviewVariantId(this.options.variantId) !== null
+                ? { variantId: normalizePreviewVariantId(this.options.variantId) }
+                : {}),
+            ...(this.options.previewScope !== undefined
+                ? { previewScope: this.options.previewScope }
+                : {}),
+            renderId: this.options.renderId,
+            generation: this.options.generation,
+            ...(this.options.renderNonce !== undefined
+                ? { renderNonce: this.options.renderNonce }
+                : {}),
+            ...(this.options.emissionRevision !== undefined
+                ? { emissionRevision: this.options.emissionRevision }
+                : {}),
+            sourceSets: [...this.sourceSets.values()],
+            markers: [...this.markers],
+        };
+    }
+}

package/dist/provenance/render-context.d.ts

@@ -0,0 +1,106 @@
+import { type PreviewReadContext } from '@storystick/types/preview-query-targeting';
+export type PreviewProvenanceAttrs = Readonly<Record<string, string | boolean>>;
+export type PreviewProvenanceAttrsByKey = Readonly<Record<string, PreviewProvenanceAttrs>>;
+export type PreviewProvenanceFields = Readonly<Record<string, PreviewProvenanceAttrs>>;
+export type PreviewProvenanceArrays = Readonly<Record<string, Readonly<Record<string, PreviewProvenanceFields>>>>;
+export type PreviewProvenancePaths = Readonly<Record<string, PreviewProvenanceAttrs>>;
+export interface PreviewProvenanceFieldSegment {
+    readonly type: 'field';
+    readonly name: string;
+}
+export interface PreviewProvenanceArrayItemSegment {
+    readonly type: 'arrayItem';
+    readonly field: string;
+    readonly key: string;
+}
+export interface PreviewProvenanceRichTextTextNodeSegment {
+    readonly type: 'richTextTextNode';
+    readonly index: number;
+}
+export type PreviewProvenancePathSegment = PreviewProvenanceFieldSegment | PreviewProvenanceArrayItemSegment | PreviewProvenanceRichTextTextNodeSegment;
+export type PreviewProvenancePath = readonly PreviewProvenancePathSegment[];
+export interface PreviewProvenanceSliceKey {
+    readonly _key: string;
+}
+export interface PreviewProvenanceDocumentKey {
+    readonly documentId: string;
+}
+export interface SliceProvenance {
+    readonly fields: PreviewProvenanceFields;
+    readonly arrays: PreviewProvenanceArrays;
+    readonly paths: PreviewProvenancePaths;
+}
+export interface DocumentProvenance {
+    readonly fields: PreviewProvenanceFields;
+    readonly paths: PreviewProvenancePaths;
+}
+export interface PreviewProvenancePathCarrier {
+    readonly paths: PreviewProvenancePaths;
+}
+export interface PreviewProvenanceContext {
+    readonly __ssPreviewProvenance?: {
+        readonly attrsByKey: PreviewProvenanceAttrsByKey;
+    };
+}
+export interface PreviewProvenanceRouteFrameContext {
+    readonly type: 'storystick.preview.route-frame';
+    readonly version: 1;
+    readonly frameId: string;
+    readonly sessionId?: string;
+    readonly routeHash: string;
+    readonly publicSidecar: PreviewProvenancePublicSidecar | null;
+}
+export interface PreviewProvenanceRouteFrameCarrier {
+    readonly __ssPreviewRouteFrame?: PreviewProvenanceRouteFrameContext;
+}
+export interface PreviewProvenanceRouteRenderContext {
+    readonly type: 'storystick.preview.route-render';
+    readonly version: 1;
+    readonly frame: PreviewProvenanceRouteFrameContext;
+    readonly document: Record<string, unknown>;
+}
+export interface PreviewProvenanceRouteRenderCarrier {
+    readonly __ssPreviewRouteRender?: PreviewProvenanceRouteRenderContext;
+}
+export interface PreviewProvenancePublicSidecarMarker {
+    readonly markerId: string;
+    readonly modality?: string;
+    readonly anchorKind?: string;
+    readonly anchorMultiplicity?: string;
+    readonly presence?: string;
+    readonly renderedTextFingerprint?: string;
+}
+export interface PreviewProvenancePublicSidecar {
+    readonly dependencySet?: {
+        readonly readContext?: PreviewReadContext;
+        readonly receiptIds?: readonly string[];
+    };
+    readonly type: 'storystick.preview.public-sidecar';
+    readonly version: number;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly renderId: string;
+    readonly generation: number;
+    readonly renderNonce?: string;
+    readonly routeRenderNonce?: string;
+    readonly emissionRevision?: number;
+    readonly markers: readonly PreviewProvenancePublicSidecarMarker[];
+}
+export declare function serializePreviewProvenanceSidecar(sidecar: PreviewProvenancePublicSidecar): string;
+export declare function withPreviewProvenanceContext(context: unknown, attrsByKey: PreviewProvenanceAttrsByKey | null | undefined): unknown;
+export declare function withPreviewProvenanceRouteFrame<T>(value: T, frame: PreviewProvenanceRouteFrameContext | null | undefined): T;
+export declare function readPreviewProvenanceRouteFrame(value: unknown): PreviewProvenanceRouteFrameContext | null;
+export declare function withPreviewProvenanceRouteRender<T>(value: T, render: PreviewProvenanceRouteRenderContext | null | undefined): T;
+export declare function readPreviewProvenanceRouteRender(value: unknown): PreviewProvenanceRouteRenderContext | null;
+export declare function previewProvenanceAttrs(context: unknown, key: string): PreviewProvenanceAttrs;
+export declare function buildSliceProvenance(context: unknown, slice: PreviewProvenanceSliceKey): SliceProvenance | undefined;
+export declare function buildDocumentProvenance(context: unknown, document: PreviewProvenanceDocumentKey): DocumentProvenance | undefined;
+export declare function fieldSegment(name: string): PreviewProvenanceFieldSegment;
+export declare function arrayItemSegment(field: string, key: string): PreviewProvenanceArrayItemSegment;
+export declare function richTextTextNodeSegment(index: number): PreviewProvenanceRichTextTextNodeSegment;
+export declare function previewPathKey(path: PreviewProvenancePath): string;
+export declare function slicePathKey(slice: PreviewProvenanceSliceKey, path: PreviewProvenancePath): string;
+export declare function sliceFieldKey(slice: PreviewProvenanceSliceKey, field: string): string;
+export declare function sliceArrayFieldKey(slice: PreviewProvenanceSliceKey, arrayName: string, itemKey: string, field: string): string;
+export declare function documentPathKey(document: PreviewProvenanceDocumentKey, path: PreviewProvenancePath): string;
+export declare function documentFieldKey(document: PreviewProvenanceDocumentKey, field: string): string;