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

package/dist/provenance/anchor-map.js

@@ -0,0 +1,177 @@
+import { fingerprintRenderedText } from './normalize.js';
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+export function previewPaintRenderIdentityEquals(left, right) {
+    return previewPaintRenderIdentityMismatch(left, right) === null;
+}
+export function previewPaintRenderIdentityMismatch(left, right) {
+    if (left.sessionId !== right.sessionId)
+        return 'session-id';
+    if (left.generation !== right.generation)
+        return 'generation';
+    if (left.sourceOfTruth !== right.sourceOfTruth)
+        return 'source-of-truth';
+    if ((left.commandId ?? null) !== (right.commandId ?? null))
+        return 'command-id';
+    if (left.pathname !== right.pathname)
+        return 'pathname';
+    if (left.routeHash !== right.routeHash)
+        return 'route-hash';
+    if (left.codeVersion !== right.codeVersion)
+        return 'code-version';
+    if (left.renderId !== right.renderId)
+        return 'render-id';
+    if (normalizePreviewVariantId(left.variantId) !==
+        normalizePreviewVariantId(right.variantId)) {
+        return 'variant-id';
+    }
+    if (!previewReadContextsEqual(left.readContext, right.readContext)) {
+        return 'read-context';
+    }
+    if ((left.routeLocale ?? null) !== (right.routeLocale ?? null)) {
+        return 'route-locale';
+    }
+    return null;
+}
+function previewReadContextsEqual(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    if (left.contextId !== right.contextId || left.revision !== right.revision) {
+        return false;
+    }
+    if (left.perspective.kind !== right.perspective.kind)
+        return false;
+    switch (left.perspective.kind) {
+        case 'published':
+        case 'living':
+            return true;
+        case 'variant':
+            return (right.perspective.kind === 'variant' &&
+                left.perspective.variantId === right.perspective.variantId);
+        case 'release':
+            return (right.perspective.kind === 'release' &&
+                left.perspective.releaseId === right.perspective.releaseId);
+    }
+}
+export function buildAnchorMap(input) {
+    const pending = input.pending ?? false;
+    const sidecarVariantId = normalizePreviewVariantId(input.sidecar.variantId);
+    const expectedVariantId = input.variantId === undefined
+        ? sidecarVariantId
+        : normalizePreviewVariantId(input.variantId);
+    const sidecarMarkers = new Map(input.sidecar.markers.map((marker) => [marker.markerId, marker]));
+    const sidecarMarkerIds = new Set(sidecarMarkers.keys());
+    const rawAnchors = input.anchors.filter((anchor) => anchor.markerId.length > 0);
+    const counts = new Map();
+    for (const anchor of rawAnchors)
+        counts.set(anchor.markerId, (counts.get(anchor.markerId) || 0) + 1);
+    const observedMarkerIds = new Set(rawAnchors.map((anchor) => anchor.markerId));
+    const invalidMarkerIds = rawAnchors
+        .filter((anchor) => !sidecarMarkerIds.has(anchor.markerId))
+        .map((anchor) => anchor.markerId);
+    const unpaintedMarkerIds = [...sidecarMarkerIds].filter((markerId) => !observedMarkerIds.has(markerId));
+    const missingMarkerIds = [...sidecarMarkerIds].filter((markerId) => !observedMarkerIds.has(markerId) && isRequiredMarker(markerId, sidecarMarkers));
+    const ambiguousMarkerIds = [...counts.entries()]
+        .filter(([markerId, count]) => count > 1 && !allowsMultipleAnchors(markerId, sidecarMarkers))
+        .map(([markerId]) => markerId);
+    const contentMismatchMarkerIds = rawAnchors
+        .filter((anchor) => {
+        const sidecarMarker = sidecarMarkers.get(anchor.markerId);
+        const anchorFingerprint = fingerprintRenderedText(anchor.text);
+        return sidecarMarker?.renderedTextFingerprint !== undefined &&
+            sidecarMarker.renderedTextFingerprint !== anchorFingerprint;
+    })
+        .map((anchor) => anchor.markerId);
+    const contentMismatchMarkerIdSet = new Set(contentMismatchMarkerIds);
+    const fatalContentMismatchMarkerIds = [
+        ...contentMismatchMarkerIdSet,
+    ].filter((markerId) => isRequiredMarker(markerId, sidecarMarkers));
+    const anchors = rawAnchors.filter((anchor) => anchor.connected &&
+        sidecarMarkerIds.has(anchor.markerId) &&
+        ((counts.get(anchor.markerId) || 0) === 1 || allowsMultipleAnchors(anchor.markerId, sidecarMarkers)) &&
+        !contentMismatchMarkerIdSet.has(anchor.markerId));
+    const codedTextMarkerIds = new Set(anchors
+        .filter((anchor) => anchor.carrier === 'coded-text')
+        .map((anchor) => anchor.markerId));
+    const domMarkerIds = new Set(anchors.filter(isPaintableAnchor).map((anchor) => anchor.markerId));
+    const dependencySet = input.sidecar.dependencySet;
+    const dependencySetMatches = dependencySet === undefined ||
+        (dependencySet.sessionId === input.sessionId &&
+            dependencySet.routeHash === input.sidecar.routeHash &&
+            dependencySet.codeVersion === input.sidecar.codeVersion &&
+            dependencySet.renderId === input.sidecar.renderId &&
+            dependencySet.generation === input.sidecar.generation &&
+            normalizePreviewVariantId(dependencySet.variantId) === sidecarVariantId);
+    return {
+        sessionId: input.sessionId,
+        generation: input.generation,
+        sourceOfTruth: input.sourceOfTruth,
+        ...(input.commandId !== undefined && { commandId: input.commandId }),
+        pathname: input.pathname,
+        routeHash: input.routeHash,
+        codeVersion: input.sidecar.codeVersion,
+        variantId: sidecarVariantId,
+        ...(input.sidecar.previewScope !== undefined
+            ? { previewScope: input.sidecar.previewScope }
+            : {}),
+        renderId: input.sidecar.renderId,
+        ...(input.sidecar.renderNonce !== undefined
+            ? { renderNonce: input.sidecar.renderNonce }
+            : {}),
+        ...(input.sidecar.emissionRevision !== undefined
+            ? { emissionRevision: input.sidecar.emissionRevision }
+            : {}),
+        ...(dependencySet !== undefined && dependencySetMatches
+            ? { dependencySet }
+            : {}),
+        phase: input.phase,
+        pending,
+        anchors,
+        editLocators: input.sidecar.markers.flatMap((marker) => marker.editLocator === undefined
+            ? []
+            : [{
+                    markerId: marker.markerId,
+                    locator: marker.editLocator,
+                    modality: marker.modality,
+                    ...(marker.presence !== undefined
+                        ? { presence: marker.presence }
+                        : {}),
+                }]),
+        sidecarMarkerIds: [...sidecarMarkerIds],
+        invalidMarkerIds: [...new Set(invalidMarkerIds)],
+        unpaintedMarkerIds,
+        missingMarkerIds,
+        ambiguousMarkerIds,
+        contentMismatchMarkerIds: [...contentMismatchMarkerIdSet],
+        fatalContentMismatchMarkerIds,
+        paintDiagnostics: {
+            codedTextOnlyNotPaintable: [...sidecarMarkerIds].filter((markerId) => codedTextMarkerIds.has(markerId) && !domMarkerIds.has(markerId)),
+            domTargetPainted: [...sidecarMarkerIds].filter((markerId) => domMarkerIds.has(markerId)),
+        },
+        valid: !pending &&
+            input.sessionId.length > 0 &&
+            Number.isFinite(input.generation) &&
+            input.generation > 0 &&
+            input.routeHash.length > 0 &&
+            input.codeVersion.length > 0 &&
+            input.sidecar.routeHash.length > 0 &&
+            input.sidecar.codeVersion.length > 0 &&
+            input.sidecar.renderId.length > 0 &&
+            input.sidecar.routeHash === input.routeHash &&
+            input.sidecar.codeVersion === input.codeVersion &&
+            sidecarVariantId === expectedVariantId &&
+            dependencySetMatches &&
+            invalidMarkerIds.length === 0 &&
+            missingMarkerIds.length === 0 &&
+            fatalContentMismatchMarkerIds.length === 0,
+    };
+}
+function isPaintableAnchor(anchor) {
+    return typeof anchor.paintId === 'string' && anchor.paintId.length > 0;
+}
+function allowsMultipleAnchors(markerId, sidecarMarkers) {
+    return sidecarMarkers.get(markerId)?.anchorMultiplicity === 'multi';
+}
+function isRequiredMarker(markerId, sidecarMarkers) {
+    const presence = sidecarMarkers.get(markerId)?.presence;
+    return presence !== 'optional' && presence !== 'expected';
+}

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

@@ -0,0 +1,51 @@
+import type { PreviewProvenanceCarrierPlan, ProvenanceAnchorKind, ProvenanceMarkerModality } from './types.js';
+export declare const PREVIEW_PROVENANCE_ATTRIBUTE_CARRIER = "data-ss-p";
+export declare const PREVIEW_PROVENANCE_ELEMENT_ATTRIBUTE_CARRIER = "data-ss-e";
+declare const ATTRIBUTE_NAME_BY_CARRIER: {
+    readonly "data-ss-p": "data-ss-p";
+    readonly "data-ss-e": "data-ss-e";
+};
+export declare function createPreviewProvenanceAttributeCarrierPlan(input: {
+    readonly modality: ProvenanceMarkerModality;
+    readonly anchorKind: ProvenanceAnchorKind;
+    readonly carrier?: keyof typeof ATTRIBUTE_NAME_BY_CARRIER;
+}): PreviewProvenanceCarrierPlan;
+export declare function createPreviewProvenanceCodedTextCarrierPlan(input: {
+    readonly surface: 'direct-editorial-text' | 'rich-text-text-node' | 'fallback-text-carrier';
+}): PreviewProvenanceCarrierPlan;
+export declare function createPreviewProvenanceTextRangeCarrierPlan(): PreviewProvenanceCarrierPlan;
+/**
+ * Conserved deliberately: these planned carriers are the annotation-model
+ * seams for href, src/media, and composite scope output. They are future
+ * product surface, not retired-mechanism residue.
+ */
+export declare const previewProvenanceFutureCarrierPlans: readonly [{
+    readonly kind: "future-attribute";
+    readonly carrier: "attribute-output-carrier";
+    readonly modality: "attr:href";
+    readonly anchorKind: "attribute";
+    readonly status: "planned";
+    readonly previewOnly: true;
+    readonly markerPayload: "opaque-marker-id";
+    readonly reason: "URL and technical attributes need explicit attribute capture, not coded text.";
+}, {
+    readonly kind: "future-media";
+    readonly carrier: "media-carrier";
+    readonly modality: "media";
+    readonly anchorKind: "attribute";
+    readonly status: "planned";
+    readonly previewOnly: true;
+    readonly markerPayload: "opaque-marker-id";
+    readonly reason: "Media fields need an explicit media carrier for src-like outputs.";
+}, {
+    readonly kind: "future-scope";
+    readonly carrier: "scope-carrier";
+    readonly modality: "scope";
+    readonly anchorKind: "scope";
+    readonly status: "planned";
+    readonly previewOnly: true;
+    readonly markerPayload: "opaque-marker-id";
+    readonly reason: "Composite or structural outputs need group/scope ownership.";
+}];
+export declare function attrsForPreviewProvenanceCarrierPlans(markerId: string | null, carrierPlans: readonly PreviewProvenanceCarrierPlan[]): Readonly<Record<string, string>>;
+export {};

package/dist/provenance/carrier-plan.js

@@ -0,0 +1,90 @@
+export const PREVIEW_PROVENANCE_ATTRIBUTE_CARRIER = 'data-ss-p';
+export const PREVIEW_PROVENANCE_ELEMENT_ATTRIBUTE_CARRIER = 'data-ss-e';
+const ATTRIBUTE_NAME_BY_CARRIER = {
+    [PREVIEW_PROVENANCE_ATTRIBUTE_CARRIER]: 'data-ss-p',
+    [PREVIEW_PROVENANCE_ELEMENT_ATTRIBUTE_CARRIER]: 'data-ss-e',
+};
+export function createPreviewProvenanceAttributeCarrierPlan(input) {
+    return {
+        kind: 'attribute',
+        carrier: input.carrier ?? PREVIEW_PROVENANCE_ATTRIBUTE_CARRIER,
+        modality: input.modality,
+        anchorKind: input.anchorKind,
+        status: 'emitted',
+        previewOnly: true,
+        markerPayload: 'opaque-marker-id',
+    };
+}
+export function createPreviewProvenanceCodedTextCarrierPlan(input) {
+    return {
+        kind: 'text',
+        carrier: 'coded-text-unicode-tags',
+        modality: 'text',
+        anchorKind: 'element',
+        status: 'emitted',
+        previewOnly: true,
+        markerPayload: 'opaque-marker-id',
+        surface: input.surface,
+    };
+}
+export function createPreviewProvenanceTextRangeCarrierPlan() {
+    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',
+    };
+}
+/**
+ * Conserved deliberately: these planned carriers are the annotation-model
+ * seams for href, src/media, and composite scope output. They are future
+ * product surface, not retired-mechanism residue.
+ */
+export const previewProvenanceFutureCarrierPlans = [
+    {
+        kind: 'future-attribute',
+        carrier: 'attribute-output-carrier',
+        modality: 'attr:href',
+        anchorKind: 'attribute',
+        status: 'planned',
+        previewOnly: true,
+        markerPayload: 'opaque-marker-id',
+        reason: 'URL and technical attributes need explicit attribute capture, not coded text.',
+    },
+    {
+        kind: 'future-media',
+        carrier: 'media-carrier',
+        modality: 'media',
+        anchorKind: 'attribute',
+        status: 'planned',
+        previewOnly: true,
+        markerPayload: 'opaque-marker-id',
+        reason: 'Media fields need an explicit media carrier for src-like outputs.',
+    },
+    {
+        kind: 'future-scope',
+        carrier: 'scope-carrier',
+        modality: 'scope',
+        anchorKind: 'scope',
+        status: 'planned',
+        previewOnly: true,
+        markerPayload: 'opaque-marker-id',
+        reason: 'Composite or structural outputs need group/scope ownership.',
+    },
+];
+export function attrsForPreviewProvenanceCarrierPlans(markerId, carrierPlans) {
+    if (markerId === null || markerId.length === 0)
+        return {};
+    const attrs = {};
+    for (const plan of carrierPlans) {
+        if (plan.kind !== 'attribute')
+            continue;
+        const attributeName = ATTRIBUTE_NAME_BY_CARRIER[plan.carrier];
+        attrs[attributeName] = markerId;
+    }
+    return attrs;
+}

package/dist/provenance/coded-text.d.ts

@@ -0,0 +1,20 @@
+export { PREVIEW_PROVENANCE_CODED_TEXT_START, PREVIEW_PROVENANCE_CODED_TEXT_SEPARATOR, PREVIEW_PROVENANCE_CODED_TEXT_END, encodePreviewProvenanceText, decodePreviewProvenanceText, stripPreviewProvenanceTextMarkers, type PreviewProvenanceCodedTextSegment, type PreviewProvenanceCodedTextDecodeResult, } from '@storystick/types/internal/preview-provenance';
+export type PreviewProvenanceCodedTextPathPart = string | number;
+export type PreviewProvenanceCodedTextSurface = 'direct-editorial-text' | 'rich-text-text-node' | 'fallback-text-carrier';
+export type PreviewProvenanceCodedTextPolicyResult = {
+    readonly allowed: true;
+    readonly surface: PreviewProvenanceCodedTextSurface;
+} | {
+    readonly allowed: false;
+    readonly reason: 'technical-field' | 'url-like-field' | 'date-like-field' | 'private-or-system-field' | 'invalid-path';
+};
+export declare function codedTextPathForCanonicalPath(canonicalPath: string, rootPrefix?: readonly PreviewProvenanceCodedTextPathPart[]): readonly PreviewProvenanceCodedTextPathPart[] | null;
+export declare function classifyPreviewProvenanceCodedTextTarget(input: {
+    readonly canonicalPath: string;
+    readonly sourceKind?: 'stored' | 'richtext';
+    readonly fallback?: boolean;
+}): PreviewProvenanceCodedTextPolicyResult;
+export declare function writePreviewProvenanceCodedTextAtPath(root: unknown, path: readonly PreviewProvenanceCodedTextPathPart[], markerId: string | null | undefined, expectedText: string): boolean;
+export declare function writePreviewProvenanceObjectMarkerAtPath(root: unknown, path: readonly PreviewProvenanceCodedTextPathPart[], markerId: string | null | undefined): boolean;
+export declare function previewProvenanceRichTextTextNodes(content: unknown): readonly string[];
+export declare function writePreviewProvenanceCodedRichTextTextNodeAtPath(root: unknown, path: readonly PreviewProvenanceCodedTextPathPart[], textNodeIndex: number, markerId: string | null | undefined, expectedText: string): boolean;

package/dist/provenance/coded-text.js

@@ -0,0 +1,302 @@
+import { encodePreviewProvenanceText, } from '@storystick/types/internal/preview-provenance';
+export { PREVIEW_PROVENANCE_CODED_TEXT_START, PREVIEW_PROVENANCE_CODED_TEXT_SEPARATOR, PREVIEW_PROVENANCE_CODED_TEXT_END, encodePreviewProvenanceText, decodePreviewProvenanceText, stripPreviewProvenanceTextMarkers, } from '@storystick/types/internal/preview-provenance';
+const PREVIEW_OBJECT_MARKER_KEY = '_ssMarker';
+const PREVIEW_OBJECT_MARKER_TAG = 'ss-marker-1';
+function withPreviewObjectMarker(value, markerId) {
+    if (typeof markerId !== 'string' ||
+        markerId.length === 0 ||
+        Array.isArray(value)) {
+        return value;
+    }
+    return {
+        ...value,
+        [PREVIEW_OBJECT_MARKER_KEY]: {
+            v: PREVIEW_OBJECT_MARKER_TAG,
+            m: markerId,
+        },
+    };
+}
+const URL_LIKE_CODED_TEXT_FIELD_NAMES = new Set([
+    'href',
+    'pathname',
+    'slug',
+    'src',
+    'url',
+]);
+const TECHNICAL_CODED_TEXT_FIELD_NAMES = new Set([
+    'anchor',
+    'asset',
+    'blurHash',
+    'code',
+    'crop',
+    'document',
+    'dominantColor',
+    'extension',
+    'filename',
+    'icon',
+    'id',
+    'language',
+    'linkType',
+    'lqip',
+    'mimeType',
+    'rel',
+    'target',
+    'thumbhash',
+    'variant',
+]);
+const DATE_LIKE_CODED_TEXT_FIELD_NAMES = new Set([
+    'createdAt',
+    'date',
+    'datetime',
+    'publishedAt',
+    'updatedAt',
+]);
+export function codedTextPathForCanonicalPath(canonicalPath, rootPrefix = ['fields']) {
+    const segments = parseCanonicalPath(canonicalPath);
+    if (segments.length === 0)
+        return null;
+    return [...rootPrefix, ...segments];
+}
+export function classifyPreviewProvenanceCodedTextTarget(input) {
+    const parts = parseCanonicalPath(input.canonicalPath);
+    if (parts.length === 0)
+        return { allowed: false, reason: 'invalid-path' };
+    for (const part of parts) {
+        if (typeof part !== 'string')
+            continue;
+        if (part.startsWith('_')) {
+            return { allowed: false, reason: 'private-or-system-field' };
+        }
+        if (URL_LIKE_CODED_TEXT_FIELD_NAMES.has(part)) {
+            return { allowed: false, reason: 'url-like-field' };
+        }
+        if (DATE_LIKE_CODED_TEXT_FIELD_NAMES.has(part)) {
+            return { allowed: false, reason: 'date-like-field' };
+        }
+        if (TECHNICAL_CODED_TEXT_FIELD_NAMES.has(part)) {
+            return { allowed: false, reason: 'technical-field' };
+        }
+    }
+    if (input.sourceKind === 'richtext') {
+        return { allowed: true, surface: 'rich-text-text-node' };
+    }
+    if (input.fallback === true) {
+        return { allowed: true, surface: 'fallback-text-carrier' };
+    }
+    return { allowed: true, surface: 'direct-editorial-text' };
+}
+export function writePreviewProvenanceCodedTextAtPath(root, path, markerId, expectedText) {
+    if (typeof markerId !== 'string' || markerId.length === 0)
+        return false;
+    if (root === null || root === undefined)
+        return false;
+    const direct = mutableValueAtPath(root, path);
+    if (direct !== null && direct.value === expectedText) {
+        direct.set(encodePreviewProvenanceText(markerId, expectedText));
+        return true;
+    }
+    return writePreviewProvenanceCodedRichTextEmbedDataAtPath(root, path, (value) => value === expectedText
+        ? encodePreviewProvenanceText(markerId, expectedText)
+        : null);
+}
+export function writePreviewProvenanceObjectMarkerAtPath(root, path, markerId) {
+    if (typeof markerId !== 'string' || markerId.length === 0)
+        return false;
+    if (root === null || root === undefined)
+        return false;
+    const direct = mutableValueAtPath(root, path);
+    if (direct !== null) {
+        const directObject = asRecord(direct.value);
+        if (directObject !== null) {
+            direct.set(withPreviewObjectMarker(directObject, markerId));
+            return true;
+        }
+    }
+    return writePreviewProvenanceCodedRichTextEmbedDataAtPath(root, path, (value) => {
+        const object = asRecord(value);
+        return object === null ? null : withPreviewObjectMarker(object, markerId);
+    });
+}
+export function previewProvenanceRichTextTextNodes(content) {
+    const doc = parseRichTextDocument(content);
+    if (doc === null)
+        return [];
+    const nodes = [];
+    collectRichTextTextNodes(doc, nodes);
+    return nodes;
+}
+export function writePreviewProvenanceCodedRichTextTextNodeAtPath(root, path, textNodeIndex, markerId, expectedText) {
+    if (typeof markerId !== 'string' || markerId.length === 0)
+        return false;
+    if (!Number.isSafeInteger(textNodeIndex) || textNodeIndex < 0)
+        return false;
+    if (root === null || root === undefined)
+        return false;
+    const direct = mutableValueAtPath(root, path);
+    const encoded = direct === null
+        ? null
+        : writePreviewProvenanceCodedRichTextTextNode(direct.value, textNodeIndex, markerId, expectedText);
+    if (encoded !== null) {
+        direct?.set(encoded);
+        return true;
+    }
+    return writePreviewProvenanceCodedRichTextEmbedDataAtPath(root, path, (value) => writePreviewProvenanceCodedRichTextTextNode(value, textNodeIndex, markerId, expectedText));
+}
+function parseCanonicalPath(path) {
+    const segments = [];
+    for (const part of path.split('.')) {
+        if (part.length === 0)
+            return [];
+        const match = /^([A-Za-z_$][\w$]*)(\[\d+\])*$/.exec(part);
+        if (!match)
+            return [];
+        segments.push(match[1]);
+        const indexes = part.match(/\[(\d+)\]/g) ?? [];
+        for (const rawIndex of indexes) {
+            const value = Number(rawIndex.slice(1, -1));
+            if (!Number.isSafeInteger(value) || value < 0)
+                return [];
+            segments.push(value);
+        }
+    }
+    return segments;
+}
+function readPathPart(value, part) {
+    if ((typeof part !== 'string' && typeof part !== 'number') ||
+        value === null ||
+        typeof value !== 'object') {
+        return undefined;
+    }
+    return value[part];
+}
+function mutableValueAtPath(root, path) {
+    if (path.length === 0)
+        return null;
+    let cursor = root;
+    for (let index = 0; index < path.length - 1; index++) {
+        cursor = readPathPart(cursor, path[index]);
+        if (cursor === null || cursor === undefined)
+            return null;
+    }
+    const leaf = path[path.length - 1];
+    if ((typeof leaf !== 'string' && typeof leaf !== 'number') ||
+        cursor === null ||
+        typeof cursor !== 'object') {
+        return null;
+    }
+    const holder = cursor;
+    return {
+        value: holder[leaf],
+        set: (value) => {
+            holder[leaf] = value;
+        },
+    };
+}
+function writePreviewProvenanceCodedRichTextEmbedDataAtPath(root, path, writeValue) {
+    for (let prefixLength = path.length - 1; prefixLength >= 1; prefixLength--) {
+        const richTextSlot = mutableValueAtPath(root, path.slice(0, prefixLength));
+        if (richTextSlot === null)
+            continue;
+        const encoded = writePreviewProvenanceCodedRichTextEmbedData(richTextSlot.value, path.slice(prefixLength), writeValue);
+        if (encoded === null)
+            continue;
+        richTextSlot.set(encoded);
+        return true;
+    }
+    return false;
+}
+function writePreviewProvenanceCodedRichTextEmbedData(content, path, writeValue) {
+    if (path.length < 2 ||
+        typeof path[0] !== 'number' ||
+        (typeof path[1] !== 'string' && typeof path[1] !== 'number')) {
+        return null;
+    }
+    const doc = parseRichTextDocument(content);
+    if (doc === null)
+        return null;
+    const embeds = [];
+    collectRichTextSliceEmbedRecords(doc, embeds);
+    const embed = embeds[path[0]];
+    if (!embed)
+        return null;
+    const attrs = asRecord(embed.attrs);
+    const data = asRecord(attrs?.data);
+    if (data === null)
+        return null;
+    const slot = mutableValueAtPath(data, [path[1]]);
+    if (slot === null)
+        return null;
+    const written = path.length === 2
+        ? writeValue(slot.value)
+        : writePreviewProvenanceCodedRichTextEmbedData(slot.value, path.slice(2), writeValue);
+    if (written === null)
+        return null;
+    slot.set(written);
+    return JSON.stringify(doc);
+}
+function writePreviewProvenanceCodedRichTextTextNode(content, textNodeIndex, markerId, expectedText) {
+    const doc = parseRichTextDocument(content);
+    if (doc === null)
+        return null;
+    const nodes = [];
+    collectRichTextTextNodeRecords(doc, nodes);
+    const target = nodes[textNodeIndex];
+    if (!target || target.text !== expectedText)
+        return null;
+    target.text = encodePreviewProvenanceText(markerId, expectedText);
+    return JSON.stringify(doc);
+}
+function parseRichTextDocument(content) {
+    let doc = content;
+    if (typeof content === 'string') {
+        try {
+            doc = JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (doc === null || typeof doc !== 'object')
+        return null;
+    return doc;
+}
+function collectRichTextTextNodes(value, out) {
+    if (value === null || typeof value !== 'object')
+        return;
+    const node = value;
+    if (node.type === 'text' && typeof node.text === 'string') {
+        out.push(node.text);
+    }
+    if (!Array.isArray(node.content))
+        return;
+    for (const child of node.content)
+        collectRichTextTextNodes(child, out);
+}
+function collectRichTextTextNodeRecords(value, out) {
+    if (value === null || typeof value !== 'object')
+        return;
+    const node = value;
+    if (node.type === 'text' && typeof node.text === 'string') {
+        out.push(node);
+    }
+    if (!Array.isArray(node.content))
+        return;
+    for (const child of node.content)
+        collectRichTextTextNodeRecords(child, out);
+}
+function collectRichTextSliceEmbedRecords(value, out) {
+    if (value === null || typeof value !== 'object')
+        return;
+    const node = value;
+    if (node.type === 'sliceEmbed')
+        out.push(node);
+    if (!Array.isArray(node.content))
+        return;
+    for (const child of node.content)
+        collectRichTextSliceEmbedRecords(child, out);
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}

package/dist/provenance/direct-edit-locator.d.ts

@@ -0,0 +1,29 @@
+import { type PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { PathAnchor, ProvenanceId, SourceSet } from './types.js';
+/**
+ * Public, render-bound address of the single editorial source behind a marker.
+ *
+ * The locator deliberately contains no presentation identity. The frame and
+ * the concrete anchor own that occurrence, while this value owns only the
+ * Studio edit target. Keeping those identities separate is what allows one
+ * model field to appear several times, and allows cross-document clicks to
+ * retain the iframe that produced them.
+ */
+export interface DirectEditLocator {
+    readonly version: 1;
+    readonly sourceSetId: string;
+    readonly documentId: string;
+    readonly variantId?: string;
+    readonly canonicalPath: string;
+    readonly pathAnchors: readonly PathAnchor[];
+    readonly navigationPath?: string;
+    readonly navigationAnchors?: readonly PathAnchor[];
+    readonly textNodeIndex?: number;
+    readonly sourceKind: ProvenanceId['sourceKind'];
+    /** Scope attested by the concrete owner read, when available. */
+    readonly readScope?: PreviewReadScopeEcho;
+}
+export declare function directEditLocatorForSourceSet(sourceSet: SourceSet | null | undefined): DirectEditLocator | null;
+export declare function directEditLocatorForSource(sourceSetId: string, source: ProvenanceId): DirectEditLocator | null;
+export declare function normalizeDirectEditLocator(value: unknown): DirectEditLocator | null;
+export declare function normalizePreviewReadScopeEcho(value: unknown): PreviewReadScopeEcho | null;