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

package/dist/provenance/sidecar-store.d.ts

@@ -0,0 +1,63 @@
+import type { PublicProvenanceSidecar } from './sidecar.js';
+export declare const PREVIEW_PROVENANCE_PUBLISHER_TYPE: "storystick.preview.provenance-publisher";
+export declare const PREVIEW_PROVENANCE_SNAPSHOT_TYPE: "storystick.preview.provenance-sidecar-snapshot";
+export declare const PREVIEW_PROVENANCE_STORE_KEY: "__ssPreviewProvenanceSidecarStoreV2";
+export interface PreviewProvenanceTransportFrame {
+    readonly frameId: string;
+    readonly sidecar: PublicProvenanceSidecar;
+}
+/**
+ * Transient server-rendered carrier. The external preview runtime consumes
+ * this record, removes the carrier, and publishes an atomic snapshot through
+ * Studio. It is deliberately not an executable or persistent inline script.
+ */
+export interface PreviewProvenancePublisher {
+    readonly type: typeof PREVIEW_PROVENANCE_PUBLISHER_TYPE;
+    readonly version: 2;
+    readonly sessionId?: string;
+    readonly frame: PreviewProvenanceTransportFrame;
+}
+export interface PreviewProvenanceSidecarSnapshot {
+    readonly type: typeof PREVIEW_PROVENANCE_SNAPSHOT_TYPE;
+    readonly version: 2;
+    readonly sessionId: string;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId: string | null;
+    readonly renderId: string;
+    readonly renderNonce: string;
+    readonly generation: number;
+    readonly emissionRevision: number;
+    readonly operation: 'replace' | 'tombstone';
+    readonly complete: boolean;
+    readonly expectedFrameIds: readonly string[];
+    readonly frames: readonly PreviewProvenanceTransportFrame[];
+}
+export interface PreviewProvenanceSidecarStore {
+    readonly version: 2;
+    accept(snapshot: PreviewProvenanceSidecarSnapshot): boolean;
+    readSnapshot(): PreviewProvenanceSidecarSnapshot | null;
+    readFrames(): readonly PreviewProvenanceTransportFrame[];
+}
+export declare function installPreviewProvenanceSidecarStore(win: Window): PreviewProvenanceSidecarStore;
+export declare function readPreviewProvenanceSidecarStore(win: Window | null | undefined): PreviewProvenanceSidecarStore | null;
+export declare function isPreviewProvenanceSidecarSnapshot(value: unknown): value is PreviewProvenanceSidecarSnapshot;
+export declare function comparePreviewProvenanceSnapshotOrder(left: Pick<PreviewProvenanceSidecarSnapshot, 'generation' | 'emissionRevision'>, right: Pick<PreviewProvenanceSidecarSnapshot, 'generation' | 'emissionRevision'>): number;
+/**
+ * Studio keeps one watermark while an iframe WindowProxy survives customer
+ * full-document navigations. A fresh document restarts its local generation
+ * at one, so generation ordering alone cannot distinguish it from a stale
+ * replay belonging to the previous document.
+ *
+ * `emissionRevision` is wall-clock based and the newly rendered document's
+ * revision is later in this race. A lower-generation snapshot may therefore
+ * cross that document boundary only when both independent identity signals
+ * agree: a new render nonce and a strictly newer revision. If clock order is
+ * unavailable the comparison fails closed; same-render replays and nonce
+ * collisions remain governed by the ordinary generation-first order.
+ *
+ * The iframe-local sidecar store intentionally keeps using the stricter
+ * generation comparator above: it is recreated per document and has no
+ * cross-document WindowProxy lifecycle to reconcile.
+ */
+export declare function shouldAcceptPreviewProvenanceSnapshotAfterWatermark(next: Pick<PreviewProvenanceSidecarSnapshot, 'generation' | 'emissionRevision' | 'renderNonce'>, watermark: Pick<PreviewProvenanceSidecarSnapshot, 'generation' | 'emissionRevision' | 'renderNonce'>): boolean;

package/dist/provenance/sidecar-store.js

@@ -0,0 +1,151 @@
+export const PREVIEW_PROVENANCE_PUBLISHER_TYPE = 'storystick.preview.provenance-publisher';
+export const PREVIEW_PROVENANCE_SNAPSHOT_TYPE = 'storystick.preview.provenance-sidecar-snapshot';
+export const PREVIEW_PROVENANCE_STORE_KEY = '__ssPreviewProvenanceSidecarStoreV2';
+export function installPreviewProvenanceSidecarStore(win) {
+    const target = win;
+    const existing = target[PREVIEW_PROVENANCE_STORE_KEY];
+    if (existing?.version === 2)
+        return existing;
+    let active = null;
+    let latestAccepted = null;
+    const store = {
+        version: 2,
+        accept(snapshot) {
+            if (!isPreviewProvenanceSidecarSnapshot(snapshot))
+                return false;
+            if (latestAccepted !== null) {
+                const order = comparePreviewProvenanceSnapshotOrder(snapshot, latestAccepted);
+                if (order < 0)
+                    return false;
+                if (order === 0) {
+                    if (snapshot.renderNonce !== latestAccepted.renderNonce)
+                        return false;
+                    if (snapshot.operation === 'tombstone')
+                        return true;
+                }
+            }
+            latestAccepted = snapshot;
+            if (snapshot.operation === 'tombstone') {
+                active = null;
+                return true;
+            }
+            active = snapshot;
+            return true;
+        },
+        readSnapshot: () => active,
+        readFrames: () => active?.frames ?? [],
+    };
+    target[PREVIEW_PROVENANCE_STORE_KEY] = store;
+    return store;
+}
+export function readPreviewProvenanceSidecarStore(win) {
+    if (!win)
+        return null;
+    const store = win[PREVIEW_PROVENANCE_STORE_KEY];
+    return store?.version === 2 ? store : null;
+}
+export function isPreviewProvenanceSidecarSnapshot(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.type !== PREVIEW_PROVENANCE_SNAPSHOT_TYPE ||
+        value.version !== 2 ||
+        typeof value.sessionId !== 'string' ||
+        value.sessionId.length === 0 ||
+        typeof value.routeHash !== 'string' ||
+        typeof value.codeVersion !== 'string' ||
+        !(value.variantId === null || typeof value.variantId === 'string') ||
+        typeof value.renderId !== 'string' ||
+        typeof value.renderNonce !== 'string' ||
+        value.renderNonce.length === 0 ||
+        !isPositiveFinite(value.generation) ||
+        !isPositiveFinite(value.emissionRevision) ||
+        !(value.operation === 'replace' || value.operation === 'tombstone') ||
+        typeof value.complete !== 'boolean' ||
+        !isStringArray(value.expectedFrameIds) ||
+        !Array.isArray(value.frames)) {
+        return false;
+    }
+    if (value.operation === 'tombstone') {
+        return value.complete && value.expectedFrameIds.length === 0 && value.frames.length === 0;
+    }
+    if (!value.complete || value.routeHash.length === 0 || value.codeVersion.length === 0) {
+        return false;
+    }
+    const expected = new Set(value.expectedFrameIds);
+    if (expected.size !== value.expectedFrameIds.length || !expected.has('route'))
+        return false;
+    const received = new Set();
+    for (const frame of value.frames) {
+        if (!isRecord(frame) || typeof frame.frameId !== 'string' || frame.frameId.length === 0) {
+            return false;
+        }
+        if (!isPublicSidecar(frame.sidecar) || received.has(frame.frameId))
+            return false;
+        if (frame.sidecar.codeVersion !== value.codeVersion ||
+            (frame.frameId === 'route' &&
+                (frame.sidecar.routeHash !== value.routeHash ||
+                    frame.sidecar.renderId !== value.renderId ||
+                    frame.sidecar.renderNonce !== value.renderNonce))) {
+            return false;
+        }
+        received.add(frame.frameId);
+    }
+    return received.size === expected.size && [...expected].every((id) => received.has(id));
+}
+export function comparePreviewProvenanceSnapshotOrder(left, right) {
+    if (left.generation !== right.generation) {
+        return left.generation < right.generation ? -1 : 1;
+    }
+    if (left.emissionRevision === right.emissionRevision)
+        return 0;
+    return left.emissionRevision < right.emissionRevision ? -1 : 1;
+}
+/**
+ * Studio keeps one watermark while an iframe WindowProxy survives customer
+ * full-document navigations. A fresh document restarts its local generation
+ * at one, so generation ordering alone cannot distinguish it from a stale
+ * replay belonging to the previous document.
+ *
+ * `emissionRevision` is wall-clock based and the newly rendered document's
+ * revision is later in this race. A lower-generation snapshot may therefore
+ * cross that document boundary only when both independent identity signals
+ * agree: a new render nonce and a strictly newer revision. If clock order is
+ * unavailable the comparison fails closed; same-render replays and nonce
+ * collisions remain governed by the ordinary generation-first order.
+ *
+ * The iframe-local sidecar store intentionally keeps using the stricter
+ * generation comparator above: it is recreated per document and has no
+ * cross-document WindowProxy lifecycle to reconcile.
+ */
+export function shouldAcceptPreviewProvenanceSnapshotAfterWatermark(next, watermark) {
+    const order = comparePreviewProvenanceSnapshotOrder(next, watermark);
+    if (order > 0)
+        return true;
+    if (order === 0)
+        return next.renderNonce === watermark.renderNonce;
+    return (next.renderNonce !== watermark.renderNonce &&
+        next.emissionRevision > watermark.emissionRevision);
+}
+function isPublicSidecar(value) {
+    if (!isRecord(value))
+        return false;
+    return value.type === 'storystick.preview.public-sidecar' &&
+        value.version === 1 &&
+        typeof value.routeHash === 'string' &&
+        typeof value.codeVersion === 'string' &&
+        typeof value.renderId === 'string' &&
+        typeof value.renderNonce === 'string' &&
+        value.renderNonce.length > 0 &&
+        isPositiveFinite(value.generation) &&
+        isPositiveFinite(value.emissionRevision) &&
+        Array.isArray(value.markers);
+}
+function isPositiveFinite(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string' && item.length > 0);
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/provenance/sidecar.d.ts

@@ -0,0 +1,34 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { MarkerRecord, PreviewProvenanceCarrierPlan, ProvenanceFrame } from './types.js';
+import { type DirectEditLocator } from './direct-edit-locator.js';
+import { type PreviewFrameDependencySet } from './frame-dependencies.js';
+export interface PublicSidecarMarker {
+    readonly markerId: string;
+    /** Public edit address; presentation/occurrence identity stays on the frame. */
+    readonly editLocator?: DirectEditLocator;
+    readonly modality: MarkerRecord['modality'];
+    readonly anchorKind: MarkerRecord['anchorKind'];
+    readonly carrierPlans?: readonly PreviewProvenanceCarrierPlan[];
+    readonly anchorMultiplicity?: MarkerRecord['anchorMultiplicity'];
+    readonly presence?: MarkerRecord['presence'];
+    readonly renderedTextFingerprint?: string;
+}
+export interface PublicProvenanceSidecar {
+    readonly type: 'storystick.preview.public-sidecar';
+    readonly version: 1;
+    readonly routeHash: string;
+    readonly codeVersion: string;
+    readonly variantId?: string;
+    readonly previewScope?: PreviewReadScopeEcho;
+    readonly renderId: string;
+    readonly generation: number;
+    readonly renderNonce?: string;
+    /** Parent route render nonce for streamed descendant frames. */
+    readonly routeRenderNonce?: string;
+    readonly emissionRevision?: number;
+    /** Public render-read identity used to project the active refresh watches. */
+    readonly dependencySet?: PreviewFrameDependencySet;
+    readonly markers: readonly PublicSidecarMarker[];
+}
+export declare function createPublicSidecar(frame: ProvenanceFrame, dependencySet?: PreviewFrameDependencySet): PublicProvenanceSidecar;
+export declare function parsePublicSidecar(text: string | null | undefined): PublicProvenanceSidecar;

package/dist/provenance/sidecar.js

@@ -0,0 +1,227 @@
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+import { directEditLocatorForSourceSet, normalizeDirectEditLocator, normalizePreviewReadScopeEcho, } from './direct-edit-locator.js';
+import { isPreviewFrameDependencySet, } from './frame-dependencies.js';
+export function createPublicSidecar(frame, dependencySet) {
+    const sourceSetById = new Map(frame.sourceSets.map((sourceSet) => [sourceSet.id, sourceSet]));
+    return {
+        type: 'storystick.preview.public-sidecar',
+        version: 1,
+        routeHash: frame.routeHash,
+        codeVersion: frame.codeVersion,
+        ...(normalizePreviewVariantId(frame.variantId) !== null
+            ? { variantId: normalizePreviewVariantId(frame.variantId) }
+            : {}),
+        ...(frame.previewScope !== undefined
+            ? { previewScope: frame.previewScope }
+            : {}),
+        renderId: frame.renderId,
+        generation: frame.generation,
+        ...(frame.renderNonce !== undefined ? { renderNonce: frame.renderNonce } : {}),
+        ...(frame.emissionRevision !== undefined
+            ? { emissionRevision: frame.emissionRevision }
+            : {}),
+        ...(dependencySet !== undefined ? { dependencySet } : {}),
+        markers: frame.markers.map((marker) => {
+            const editLocator = directEditLocatorForSourceSet(sourceSetById.get(marker.sourceSetId));
+            return {
+                markerId: marker.markerId,
+                ...(editLocator !== null ? { editLocator } : {}),
+                modality: marker.modality,
+                anchorKind: marker.anchorKind,
+                carrierPlans: marker.carrierPlans,
+                anchorMultiplicity: marker.anchorMultiplicity,
+                // Expected remains non-fatal in anchor validation, while retaining the
+                // information needed for owner diagnostics in the public frame.
+                presence: marker.presence,
+                renderedTextFingerprint: marker.renderedTextFingerprint,
+            };
+        }),
+    };
+}
+export function parsePublicSidecar(text) {
+    if (text === null || text === undefined || text.trim().length === 0)
+        return emptyPublicSidecar();
+    try {
+        const parsed = JSON.parse(text);
+        return {
+            type: 'storystick.preview.public-sidecar',
+            version: 1,
+            routeHash: typeof parsed.routeHash === 'string' ? parsed.routeHash : '',
+            codeVersion: typeof parsed.codeVersion === 'string' ? parsed.codeVersion : '',
+            ...(normalizePreviewVariantId(parsed.variantId) !== null
+                ? { variantId: normalizePreviewVariantId(parsed.variantId) }
+                : {}),
+            ...(normalizePreviewReadScopeEcho(parsed.previewScope) !== null
+                ? { previewScope: normalizePreviewReadScopeEcho(parsed.previewScope) }
+                : {}),
+            renderId: typeof parsed.renderId === 'string' ? parsed.renderId : '',
+            generation: typeof parsed.generation === 'number' ? parsed.generation : 0,
+            ...(typeof parsed.renderNonce === 'string' && parsed.renderNonce.length > 0
+                ? { renderNonce: parsed.renderNonce }
+                : {}),
+            ...(typeof parsed.routeRenderNonce === 'string' &&
+                parsed.routeRenderNonce.length > 0
+                ? { routeRenderNonce: parsed.routeRenderNonce }
+                : {}),
+            ...(typeof parsed.emissionRevision === 'number' &&
+                Number.isFinite(parsed.emissionRevision) &&
+                parsed.emissionRevision > 0
+                ? { emissionRevision: parsed.emissionRevision }
+                : {}),
+            ...(isPreviewFrameDependencySet(parsed.dependencySet)
+                ? { dependencySet: parsed.dependencySet }
+                : {}),
+            markers: Array.isArray(parsed.markers)
+                ? parsed.markers.flatMap((marker) => normalizeMarker(marker))
+                : [],
+        };
+    }
+    catch {
+        return emptyPublicSidecar();
+    }
+}
+function normalizeMarker(marker) {
+    if (typeof marker !== 'object' || marker === null)
+        return [];
+    const candidate = marker;
+    if (typeof candidate.markerId !== 'string' || candidate.markerId.length === 0)
+        return [];
+    if (!isModality(candidate.modality) || !isAnchorKind(candidate.anchorKind))
+        return [];
+    return [{
+            markerId: candidate.markerId,
+            ...(normalizeDirectEditLocator(candidate.editLocator) !== null
+                ? { editLocator: normalizeDirectEditLocator(candidate.editLocator) }
+                : {}),
+            modality: candidate.modality,
+            anchorKind: candidate.anchorKind,
+            carrierPlans: normalizeCarrierPlans(candidate.carrierPlans),
+            anchorMultiplicity: candidate.anchorMultiplicity === 'multi' ? 'multi' : undefined,
+            presence: candidate.presence === 'optional' || candidate.presence === 'expected'
+                ? candidate.presence
+                : undefined,
+            renderedTextFingerprint: typeof candidate.renderedTextFingerprint === 'string'
+                ? candidate.renderedTextFingerprint
+                : undefined,
+        }];
+}
+function emptyPublicSidecar() {
+    return {
+        type: 'storystick.preview.public-sidecar',
+        version: 1,
+        routeHash: '',
+        codeVersion: '',
+        renderId: '',
+        generation: 0,
+        markers: [],
+    };
+}
+function isModality(value) {
+    return value === 'text' ||
+        value === 'attr:href' ||
+        value === 'attr:src' ||
+        value === 'attr:alt' ||
+        value === 'attr:title' ||
+        value === 'attr:aria-label';
+}
+function isAnchorKind(value) {
+    return value === 'element' || value === 'attribute' || value === 'text-range' || value === 'scope';
+}
+function normalizeCarrierPlans(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const plans = value.flatMap((plan) => normalizeCarrierPlan(plan));
+    return plans.length > 0 ? plans : undefined;
+}
+function normalizeCarrierPlan(value) {
+    if (typeof value !== 'object' || value === null)
+        return [];
+    const candidate = value;
+    if (candidate.previewOnly !== true ||
+        candidate.markerPayload !== 'opaque-marker-id') {
+        return [];
+    }
+    if (candidate.kind === 'attribute' &&
+        (candidate.carrier === 'data-ss-p' || candidate.carrier === 'data-ss-e') &&
+        candidate.status === 'emitted' &&
+        isModality(candidate.modality) &&
+        isAnchorKind(candidate.anchorKind)) {
+        return [{
+                kind: 'attribute',
+                carrier: candidate.carrier,
+                modality: candidate.modality,
+                anchorKind: candidate.anchorKind,
+                status: 'emitted',
+                previewOnly: true,
+                markerPayload: 'opaque-marker-id',
+            }];
+    }
+    if (candidate.kind === 'text' &&
+        candidate.carrier === 'coded-text-unicode-tags' &&
+        candidate.status === 'emitted' &&
+        candidate.modality === 'text' &&
+        candidate.anchorKind === 'element' &&
+        isCodedTextSurface(candidate.surface)) {
+        return [{
+                kind: 'text',
+                carrier: 'coded-text-unicode-tags',
+                modality: 'text',
+                anchorKind: 'element',
+                status: 'emitted',
+                previewOnly: true,
+                markerPayload: 'opaque-marker-id',
+                surface: candidate.surface,
+            }];
+    }
+    if (candidate.kind === 'text-range' &&
+        candidate.carrier === 'coded-text-unicode-tags' &&
+        candidate.status === 'emitted' &&
+        candidate.modality === 'text' &&
+        candidate.anchorKind === 'text-range' &&
+        candidate.surface === 'non-promoted-text-range') {
+        return [{
+                kind: 'text-range',
+                carrier: 'coded-text-unicode-tags',
+                modality: 'text',
+                anchorKind: 'text-range',
+                status: 'emitted',
+                previewOnly: true,
+                markerPayload: 'opaque-marker-id',
+                surface: 'non-promoted-text-range',
+            }];
+    }
+    if ((candidate.kind === 'future-attribute' ||
+        candidate.kind === 'future-media' ||
+        candidate.kind === 'future-scope') &&
+        candidate.status === 'planned' &&
+        isFutureCarrier(candidate.carrier) &&
+        isFutureModality(candidate.modality) &&
+        isAnchorKind(candidate.anchorKind) &&
+        typeof candidate.reason === 'string' &&
+        candidate.reason.length > 0) {
+        return [{
+                kind: candidate.kind,
+                carrier: candidate.carrier,
+                modality: candidate.modality,
+                anchorKind: candidate.anchorKind,
+                status: 'planned',
+                previewOnly: true,
+                markerPayload: 'opaque-marker-id',
+                reason: candidate.reason,
+            }];
+    }
+    return [];
+}
+function isCodedTextSurface(value) {
+    return value === 'direct-editorial-text' ||
+        value === 'rich-text-text-node' ||
+        value === 'fallback-text-carrier';
+}
+function isFutureCarrier(value) {
+    return value === 'attribute-output-carrier' ||
+        value === 'media-carrier' ||
+        value === 'scope-carrier';
+}
+function isFutureModality(value) {
+    return isModality(value) || value === 'media' || value === 'scope';
+}

package/dist/provenance/slice-model.d.ts

@@ -0,0 +1,28 @@
+export interface SliceAnchor {
+    pathPrefix: string;
+    key: string;
+}
+export interface SliceModel {
+    v: 129;
+    renderId: string;
+    doc: string;
+    i: number;
+    type: string;
+    fields: Record<string, unknown>;
+    zoneField: string;
+    zoneFieldSource: 'explicit' | 'default';
+    parentAnchors: ReadonlyArray<SliceAnchor>;
+    source?: {
+        path: string;
+        anchors: ReadonlyArray<SliceAnchor>;
+    };
+}
+export declare function getPreviewDocumentId(context: unknown): string | null;
+export declare function isPublishedSnapshotContext(context: unknown): boolean;
+export declare function extractSliceFields(slice: object): Record<string, unknown>;
+export declare function makeSliceRenderId(input: {
+    readonly scopeDocId: string;
+    readonly slices: readonly unknown[];
+    readonly scopeKey?: string;
+}): string;
+export declare function serializeSliceModel(model: SliceModel): string | null;

package/dist/provenance/slice-model.js

@@ -0,0 +1,86 @@
+const PREVIEW_OBJECT_MARKER_KEY = '_ssMarker';
+const SLICE_META_KEYS = new Set([
+    '_type',
+    '_key',
+    '_variation',
+    '_model',
+    '_ssPreview',
+    '__ssContent',
+]);
+export function getPreviewDocumentId(context) {
+    if (!context || typeof context !== 'object')
+        return null;
+    const c = context;
+    return typeof c.documentId === 'string' && c.documentId.length > 0
+        ? c.documentId
+        : null;
+}
+export function isPublishedSnapshotContext(context) {
+    if (!context || typeof context !== 'object')
+        return false;
+    const c = context;
+    return c.publishedAt != null || c.snapshotId != null;
+}
+export function extractSliceFields(slice) {
+    const storedSlice = slice;
+    const fields = {};
+    for (const key of Object.keys(slice)) {
+        if (!SLICE_META_KEYS.has(key))
+            fields[key] = storedSlice[key];
+    }
+    return fields;
+}
+export function makeSliceRenderId(input) {
+    let hash = 0x811c9dc5;
+    hash = hashString(hash, input.scopeDocId);
+    if (input.scopeKey !== undefined && input.scopeKey.length > 0) {
+        hash = hashString(hash, `@${input.scopeKey}`);
+    }
+    hash = hashString(hash, `#${input.slices.length}`);
+    for (let index = 0; index < input.slices.length; index += 1) {
+        const slice = input.slices[index];
+        hash = hashString(hash, `|${index}:`);
+        hash = hashString(hash, readSliceIdentity(slice, '_type'));
+        hash = hashString(hash, ':');
+        hash = hashString(hash, readSliceIdentity(slice, '_key'));
+    }
+    return `r${hash.toString(36)}`;
+}
+function readSliceIdentity(slice, key) {
+    if (slice === null || typeof slice !== 'object')
+        return '';
+    const value = slice[key];
+    return typeof value === 'string' ? value : '';
+}
+export function serializeSliceModel(model) {
+    let json;
+    try {
+        const ancestors = [];
+        json = JSON.stringify(model, function (key, val) {
+            if (key === PREVIEW_OBJECT_MARKER_KEY || key === '__ssContent' || key === '_ssPreview')
+                return undefined;
+            if (typeof val === 'bigint')
+                return String(val);
+            if (val !== null && typeof val === 'object') {
+                while (ancestors.length && ancestors.at(-1) !== this)
+                    ancestors.pop();
+                if (ancestors.includes(val))
+                    return undefined;
+                ancestors.push(val);
+            }
+            return val;
+        });
+    }
+    catch {
+        return null;
+    }
+    return json || null;
+}
+function hashString(seed, value) {
+    let hash = seed >>> 0;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}

package/dist/provenance/source-identity.d.ts

@@ -0,0 +1,3 @@
+import type { ProvenanceId } from './types.js';
+/** Compare only the source's own read echo, never the presentation frame. */
+export declare function hasCoherentPreviewProvenanceSourceIdentity(source: Pick<ProvenanceId, 'variantId' | 'readScope'>): boolean;

package/dist/provenance/source-identity.js

@@ -0,0 +1,7 @@
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+/** Compare only the source's own read echo, never the presentation frame. */
+export function hasCoherentPreviewProvenanceSourceIdentity(source) {
+    return source.readScope === undefined ||
+        normalizePreviewVariantId(source.variantId) ===
+            normalizePreviewVariantId(source.readScope.appliedVariantId);
+}