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

package/dist/provenance/editable-leaf.js

@@ -0,0 +1,483 @@
+import { codedTextPathForCanonicalPath, classifyPreviewProvenanceCodedTextTarget, writePreviewProvenanceCodedRichTextTextNodeAtPath, writePreviewProvenanceCodedTextAtPath, writePreviewProvenanceObjectMarkerAtPath, } from './coded-text.js';
+import { formatPreviewProvenanceCanonicalPath, walkPreviewProvenanceFieldLeaves, } from './field-leaf-walker.js';
+import { createPreviewProvenanceAttributeCarrierPlan, createPreviewProvenanceCodedTextCarrierPlan, PREVIEW_PROVENANCE_ELEMENT_ATTRIBUTE_CARRIER, } from './carrier-plan.js';
+import { ProvenanceRecorder } from './recorder.js';
+import { createPublicSidecar } from './sidecar.js';
+import { normalizePreviewVariantId } from '../identity/preview-identity.js';
+export { formatPreviewProvenanceCanonicalPath } from './field-leaf-walker.js';
+export function createPreviewProvenanceEditableLeaf(input) {
+    const rootPath = input.rootPath ?? [];
+    return {
+        key: input.key,
+        documentId: input.documentId,
+        ...(normalizePreviewVariantId(input.variantId) !== null
+            ? { variantId: normalizePreviewVariantId(input.variantId) }
+            : {}),
+        ...(input.readScope !== undefined ? { readScope: input.readScope } : {}),
+        canonicalPath: formatPreviewProvenanceCanonicalPath([
+            ...rootPath,
+            ...input.leafPath,
+        ]),
+        pathAnchors: [
+            ...(input.pathAnchors ?? []),
+            ...prefixPreviewProvenancePathAnchors(rootPath, input.relativePathAnchors ?? []),
+        ],
+        ...(input.navigationPath !== undefined
+            ? { navigationPath: input.navigationPath }
+            : {}),
+        ...(input.navigationAnchors !== undefined
+            ? { navigationAnchors: input.navigationAnchors }
+            : {}),
+        sourceKind: input.sourceKind ?? 'stored',
+        sourceSetId: input.sourceSetId,
+        outputKind: input.outputKind ?? 'text',
+        modality: input.modality ?? 'text',
+        anchorKind: input.anchorKind ?? 'element',
+        renderedText: input.renderedText,
+        ...(input.sourceSet ? { sourceSet: input.sourceSet } : {}),
+        codedText: input.codedText,
+        codedTextRoot: input.codedTextRoot,
+        codedTextPath: input.codedTextPath,
+        codedRichTextTextNodeIndex: input.codedRichTextTextNodeIndex,
+        anchorMultiplicity: input.anchorMultiplicity,
+        presence: input.presence,
+    };
+}
+export function planPreviewProvenanceEditableTextLeaves(input) {
+    const candidates = [];
+    walkPreviewProvenanceFieldLeaves({
+        root: input.root,
+        onLeaf: (walked) => {
+            const context = {
+                path: walked.path,
+                fieldName: leafFieldName(walked.path),
+                value: walked.value,
+                sourceKind: walked.sourceKind,
+                outputKind: walked.outputKind,
+                ...(walked.textNodeIndex === undefined
+                    ? {}
+                    : { textNodeIndex: walked.textNodeIndex }),
+            };
+            const matchedPattern = input.match?.(context);
+            if (input.match !== undefined && matchedPattern === null)
+                return;
+            if (walked.outputKind === 'element' && matchedPattern === undefined)
+                return;
+            if (input.include?.(context) === false)
+                return;
+            const slug = pathSlug(walked.path, walked.pathAnchors);
+            const richTextSuffix = walked.textNodeIndex === undefined
+                ? ''
+                : `:richtext:${walked.textNodeIndex}`;
+            const richTextSourceSuffix = walked.textNodeIndex === undefined
+                ? ''
+                : `_richtext_${walked.textNodeIndex}`;
+            candidates.push({
+                path: walked.path,
+                leaf: createPreviewProvenanceEditableLeaf({
+                    key: `${input.keyPrefix}:${slug}${richTextSuffix}`,
+                    documentId: input.documentId,
+                    variantId: input.variantId,
+                    readScope: input.readScope,
+                    rootPath: input.rootPath,
+                    leafPath: walked.path,
+                    pathAnchors: input.pathAnchors,
+                    relativePathAnchors: walked.pathAnchors,
+                    sourceKind: walked.sourceKind,
+                    sourceSetId: `${input.sourceSetPrefix}_${slug}${richTextSourceSuffix}`,
+                    outputKind: walked.outputKind,
+                    modality: matchedPattern?.modality ?? 'text',
+                    anchorKind: matchedPattern?.anchorKind ?? 'element',
+                    renderedText: walked.renderedText,
+                    codedText: walked.outputKind === 'text' && walked.sourceKind === 'stored'
+                        ? true
+                        : undefined,
+                    codedRichTextTextNodeIndex: walked.textNodeIndex,
+                    // Element carriers follow the caller's declared presence, like text.
+                    presence: input.presence,
+                }),
+            });
+        },
+    });
+    return candidates;
+}
+export function createPreviewProvenanceEditableTextManifestInclude(manifest, storyType) {
+    const patterns = storyType ? manifest[storyType] ?? [] : [];
+    return (context) => matchingPreviewProvenanceEditablePathPattern(context, patterns) !== null;
+}
+export function createPreviewProvenanceEditableManifestMatcher(manifest, storyType) {
+    const patterns = storyType ? manifest[storyType] ?? [] : [];
+    return (context) => matchingPreviewProvenanceEditablePathPattern(context, patterns);
+}
+const PREVIEW_PROVENANCE_RESOLVABILITY_PREDICATES = {
+    'attr:src': hasResolvableImageAssetId,
+    'attr:href': hasResolvableHrefTarget,
+};
+export function previewProvenanceEditableTextPathPatternMatches(context, pattern) {
+    if ((pattern.outputKind ?? 'text') !== context.outputKind)
+        return false;
+    if (pattern.sourceKind !== undefined && pattern.sourceKind !== context.sourceKind) {
+        return false;
+    }
+    if (pattern.path.length !== context.path.length)
+        return false;
+    for (let index = 0; index < pattern.path.length; index++) {
+        const expected = pattern.path[index];
+        if (expected === '*')
+            continue;
+        if (expected !== context.path[index])
+            return false;
+    }
+    if (pattern.outputKind === 'element' &&
+        pattern.modality !== undefined) {
+        const isResolvable = PREVIEW_PROVENANCE_RESOLVABILITY_PREDICATES[pattern.modality];
+        if (isResolvable === undefined || !isResolvable(context.value))
+            return false;
+    }
+    return true;
+}
+function hasResolvableImageAssetId(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const assetId = value.assetId;
+    return typeof assetId === 'string' && assetId.length > 0;
+}
+function hasResolvableHrefTarget(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const link = value;
+    // File fields are bare `{ assetId }` values; Link assets carry the same
+    // identity behind an explicit `linkType: asset` discriminator.
+    if ((link.linkType === undefined || link.linkType === 'asset') &&
+        typeof link.assetId === 'string' &&
+        link.assetId.trim().length > 0) {
+        return true;
+    }
+    const target = link.linkType === 'url'
+        ? link.url
+        : link.linkType === 'document' ? link.document : undefined;
+    const normalized = typeof target === 'string' ? target.trim() : '';
+    return normalized !== '' && (link.linkType !== 'url' || normalized !== '#');
+}
+export function matchingPreviewProvenanceEditablePathPattern(context, patterns) {
+    return patterns.find((pattern) => previewProvenanceEditableTextPathPatternMatches(context, pattern)) ?? null;
+}
+export async function recordPreviewProvenanceEditableLeaves(input) {
+    const recorder = new ProvenanceRecorder({
+        sessionId: input.sessionId,
+        readContext: input.readContext,
+        routeHash: input.routeHash,
+        codeVersion: input.codeVersion,
+        variantId: input.variantId,
+        previewScope: input.previewScope,
+        renderId: input.renderId,
+        generation: input.generation,
+        renderNonce: input.renderNonce,
+        emissionRevision: input.emissionRevision,
+        enabled: input.enabled,
+    });
+    const attrsByKey = {};
+    const carrierPlansByKey = {};
+    const codedTextWrites = createCodedTextWriteTracker();
+    for (const leaf of input.leaves) {
+        const sourceSet = previewProvenanceSourceSetForLeaf(leaf);
+        const carrierPlans = previewProvenanceCarrierPlansForLeaf(leaf);
+        const registered = await recorder.mark(sourceSet, {
+            modality: leaf.modality,
+            anchorKind: leaf.anchorKind,
+            carrierPlans,
+            anchorMultiplicity: leaf.anchorMultiplicity,
+            presence: leaf.presence,
+            renderedText: leaf.renderedText,
+        });
+        attrsByKey[leaf.key] = registered.attrs;
+        carrierPlansByKey[leaf.key] = registered.carrierPlans;
+        if (typeof registered.markerId !== 'string' || registered.markerId.length === 0) {
+            continue;
+        }
+        const codedTextRoot = leaf.codedTextRoot ?? resolveCodedTextRoot(input, leaf.documentId);
+        if (leaf.outputKind === 'element') {
+            const objectPath = leaf.codedTextPath ?? codedTextPathForCanonicalPath(leaf.canonicalPath, input.codedTextRootPrefix);
+            if (objectPath === null) {
+                codedTextWrites.fail({
+                    leaf,
+                    operation: 'object',
+                    reason: 'path-unresolvable',
+                });
+            }
+            else {
+                codedTextWrites.record({
+                    leaf,
+                    root: codedTextRoot,
+                    operation: 'object',
+                    written: writePreviewProvenanceObjectMarkerAtPath(codedTextRoot, objectPath, registered.markerId),
+                });
+            }
+            continue;
+        }
+        if (typeof leaf.renderedText !== 'string') {
+            codedTextWrites.fail({
+                leaf,
+                operation: 'text',
+                reason: 'path-or-text-mismatch',
+            });
+            continue;
+        }
+        const renderedText = leaf.renderedText;
+        const codedTextPath = leaf.codedText === true
+            ? leaf.codedTextPath ?? codedTextPathForCanonicalPath(leaf.canonicalPath, input.codedTextRootPrefix)
+            : leaf.codedTextPath;
+        const shouldWritePlainCodedText = leaf.codedRichTextTextNodeIndex === undefined || leaf.codedText === true;
+        if (codedTextPath && shouldWritePlainCodedText) {
+            const policy = classifyPreviewProvenanceCodedTextTarget({
+                canonicalPath: leaf.navigationPath ?? leaf.canonicalPath,
+                sourceKind: leaf.sourceKind === 'richtext' ? 'richtext' : 'stored',
+            });
+            if (!policy.allowed) {
+                codedTextWrites.fail({
+                    leaf,
+                    operation: 'text',
+                    reason: 'coded-text-disallowed',
+                });
+            }
+            else {
+                codedTextWrites.record({
+                    leaf,
+                    root: codedTextRoot,
+                    operation: 'text',
+                    written: writePreviewProvenanceCodedTextAtPath(codedTextRoot, codedTextPath, registered.markerId, renderedText),
+                });
+            }
+        }
+        else if (leaf.codedText === true) {
+            codedTextWrites.fail({
+                leaf,
+                operation: 'text',
+                reason: 'path-unresolvable',
+            });
+        }
+        if (leaf.codedRichTextTextNodeIndex !== undefined) {
+            const richTextPath = leaf.codedTextPath ?? codedTextPathForCanonicalPath(leaf.canonicalPath, input.codedTextRootPrefix);
+            if (richTextPath === null) {
+                codedTextWrites.fail({
+                    leaf,
+                    operation: 'richtext',
+                    reason: 'path-unresolvable',
+                });
+                continue;
+            }
+            const policy = classifyPreviewProvenanceCodedTextTarget({
+                canonicalPath: leaf.navigationPath ?? leaf.canonicalPath,
+                sourceKind: 'richtext',
+            });
+            if (!policy.allowed) {
+                codedTextWrites.fail({
+                    leaf,
+                    operation: 'richtext',
+                    reason: 'coded-text-disallowed',
+                });
+                continue;
+            }
+            codedTextWrites.record({
+                leaf,
+                root: codedTextRoot,
+                operation: 'richtext',
+                written: writePreviewProvenanceCodedRichTextTextNodeAtPath(codedTextRoot, richTextPath, leaf.codedRichTextTextNodeIndex, registered.markerId, renderedText),
+            });
+        }
+    }
+    const renderFrame = recorder.flush();
+    return {
+        attrsByKey,
+        carrierPlansByKey,
+        renderFrame,
+        publicSidecar: input.enabled === false ? null : createPublicSidecar(renderFrame),
+        codedTextWrites: codedTextWrites.summary(),
+    };
+}
+function previewProvenanceCarrierPlansForLeaf(leaf) {
+    if (leaf.outputKind === 'element') {
+        return [
+            createPreviewProvenanceAttributeCarrierPlan({
+                carrier: PREVIEW_PROVENANCE_ELEMENT_ATTRIBUTE_CARRIER,
+                modality: leaf.modality,
+                anchorKind: leaf.anchorKind,
+            }),
+        ];
+    }
+    const carrierPlans = [
+        createPreviewProvenanceAttributeCarrierPlan({
+            modality: leaf.modality,
+            anchorKind: leaf.anchorKind,
+        }),
+    ];
+    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;
+}
+export function previewProvenanceSourceSetForLeaf(leaf) {
+    const source = provenanceIdForLeaf(leaf);
+    if (leaf.sourceSet === undefined) {
+        return {
+            id: leaf.sourceSetId,
+            kind: 'single',
+            sources: [source],
+            primary: source,
+            editable: 'single-field',
+        };
+    }
+    const sources = leaf.sourceSet.sources.map((source) => sourceWithLeafNavigation(source, leaf));
+    const primary = leaf.sourceSet.primary === undefined
+        ? undefined
+        : sourceWithLeafNavigation(leaf.sourceSet.primary, leaf);
+    return {
+        id: leaf.sourceSetId,
+        kind: leaf.sourceSet.kind,
+        sources,
+        ...(primary ? { primary } : {}),
+        ...(leaf.sourceSet.derivation
+            ? { derivation: leaf.sourceSet.derivation }
+            : {}),
+        editable: leaf.sourceSet.editable,
+    };
+}
+function sourceWithLeafNavigation(source, leaf) {
+    if (leaf.navigationPath === undefined && leaf.navigationAnchors === undefined) {
+        return source;
+    }
+    if (!sourceMatchesLeafIdentity(source, leaf))
+        return source;
+    return {
+        ...source,
+        ...(leaf.navigationPath !== undefined
+            ? { navigationPath: leaf.navigationPath }
+            : {}),
+        ...(leaf.navigationAnchors !== undefined
+            ? { navigationAnchors: leaf.navigationAnchors }
+            : {}),
+    };
+}
+function sourceMatchesLeafIdentity(source, leaf) {
+    return source.documentId === leaf.documentId &&
+        normalizePreviewVariantId(source.variantId) === normalizePreviewVariantId(leaf.variantId) &&
+        source.canonicalPath === leaf.canonicalPath &&
+        source.sourceKind === leaf.sourceKind &&
+        source.textNodeIndex === leaf.codedRichTextTextNodeIndex;
+}
+function provenanceIdForLeaf(leaf) {
+    return {
+        documentId: leaf.documentId,
+        ...(normalizePreviewVariantId(leaf.variantId) !== null
+            ? { variantId: normalizePreviewVariantId(leaf.variantId) }
+            : {}),
+        ...(leaf.readScope !== undefined ? { readScope: leaf.readScope } : {}),
+        canonicalPath: leaf.canonicalPath,
+        pathAnchors: leaf.pathAnchors,
+        ...(leaf.navigationPath !== undefined
+            ? { navigationPath: leaf.navigationPath }
+            : {}),
+        ...(leaf.navigationAnchors !== undefined
+            ? { navigationAnchors: leaf.navigationAnchors }
+            : {}),
+        ...(leaf.codedRichTextTextNodeIndex !== undefined
+            ? { textNodeIndex: leaf.codedRichTextTextNodeIndex }
+            : {}),
+        sourceKind: leaf.sourceKind,
+    };
+}
+export function prefixPreviewProvenancePathAnchors(prefixPath, anchors) {
+    if (anchors.length === 0)
+        return [];
+    const prefix = formatPreviewProvenanceCanonicalPath(prefixPath);
+    if (prefix.length === 0)
+        return anchors;
+    return anchors.map((anchor) => ({
+        path: anchor.path.length === 0 ? prefix : `${prefix}.${anchor.path}`,
+        key: anchor.key,
+    }));
+}
+function resolveCodedTextRoot(input, documentId) {
+    const roots = input.codedTextRootsByDocumentId;
+    if (roots === undefined)
+        return input.codedTextRoot;
+    if (isCodedTextRootMap(roots))
+        return roots.get(documentId);
+    return Object.prototype.hasOwnProperty.call(roots, documentId)
+        ? roots[documentId]
+        : undefined;
+}
+function isCodedTextRootMap(roots) {
+    const candidate = roots;
+    return typeof candidate.get === 'function' && typeof candidate.has === 'function';
+}
+function createCodedTextWriteTracker() {
+    let attempted = 0;
+    let written = 0;
+    const failures = [];
+    return {
+        record(input) {
+            attempted += 1;
+            if (input.written) {
+                written += 1;
+                return;
+            }
+            failures.push(codedTextWriteFailure({
+                leaf: input.leaf,
+                operation: input.operation,
+                reason: input.root === null || input.root === undefined
+                    ? 'root-missing'
+                    : input.operation === 'object'
+                        ? 'path-or-object-mismatch'
+                        : 'path-or-text-mismatch',
+            }));
+        },
+        fail(input) {
+            failures.push(codedTextWriteFailure(input));
+        },
+        summary() {
+            return { attempted, written, failures };
+        },
+    };
+}
+function codedTextWriteFailure(input) {
+    return {
+        key: input.leaf.key,
+        documentId: input.leaf.documentId,
+        sourceSetId: input.leaf.sourceSetId,
+        canonicalPath: input.leaf.canonicalPath,
+        operation: input.operation,
+        reason: input.reason,
+    };
+}
+function leafFieldName(path) {
+    const leaf = path[path.length - 1];
+    return typeof leaf === 'string' ? leaf : null;
+}
+function pathSlug(path, relativePathAnchors) {
+    const keyByArrayPath = new Map(relativePathAnchors.map((anchor) => [anchor.path, anchor.key]));
+    return path.map((part, index) => {
+        if (typeof part === 'number') {
+            const arrayPath = formatPreviewProvenanceCanonicalPath(path.slice(0, index));
+            return safeSlugPart(keyByArrayPath.get(arrayPath) ?? String(part));
+        }
+        return safeSlugPart(part);
+    }).join('_');
+}
+function safeSlugPart(value) {
+    return value.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'field';
+}

package/dist/provenance/editor-target.d.ts

@@ -0,0 +1,29 @@
+import type { ImperativeEditorNavigationTarget } from '@storystick/types/editor-destination';
+import type { PreviewReadScopeEcho } from '@storystick/client/internal';
+import type { ProvenanceId } from './types.js';
+export type PreviewOverlayRoutableTarget = {
+    kind: 'slice' | 'field';
+    documentId: string;
+    variantId?: string | null;
+    readScope?: PreviewReadScopeEcho;
+    path: string;
+    sliceKey?: string;
+    fromAnchors: ReadonlyArray<{
+        pathPrefix: string;
+        key: string;
+    }>;
+    navigationPath?: string;
+    navigationAnchors?: ReadonlyArray<{
+        pathPrefix: string;
+        key: string;
+    }>;
+    field?: string;
+    sourceKind?: ProvenanceId['sourceKind'];
+    richTextTextNodeIndex?: number;
+    richTextSliceEmbedIndex?: number;
+    richTextSliceEmbedKey?: string;
+};
+export declare function overlayEditorTarget(target: PreviewOverlayRoutableTarget): ImperativeEditorNavigationTarget;
+/** Non-localized owners (navigation/settings) carry no readScope. Keep the
+ * presentation locale; an inherited applied locale is never an editing target. */
+export declare function overlayEditorLocale(target: Pick<PreviewOverlayRoutableTarget, 'readScope'>, presentationLocale?: string | null): string | undefined;

package/dist/provenance/editor-target.js

@@ -0,0 +1,46 @@
+import { richTextSliceEmbedAddressFromPath, richTextSliceEmbedKeyFromAnchors, } from './richtext-slice-embed-address.js';
+function richTextSliceEmbedNavigationOptions(target) {
+    const path = target.navigationPath ?? target.path;
+    const anchors = target.navigationAnchors ?? target.fromAnchors;
+    if (target.richTextSliceEmbedIndex !== undefined) {
+        const address = richTextSliceEmbedAddressFromPath(path, target.richTextSliceEmbedIndex);
+        const key = target.richTextSliceEmbedKey ??
+            (address !== null
+                ? richTextSliceEmbedKeyFromAnchors(anchors, address.rootPath)
+                : undefined);
+        return {
+            richTextSliceEmbedIndex: target.richTextSliceEmbedIndex,
+            ...(key !== undefined ? { richTextSliceEmbedKey: key } : {}),
+        };
+    }
+    const address = richTextSliceEmbedAddressFromPath(path);
+    if (address === null)
+        return {};
+    const key = richTextSliceEmbedKeyFromAnchors(anchors, address.rootPath);
+    return {
+        richTextSliceEmbedIndex: address.index,
+        ...(key !== undefined ? { richTextSliceEmbedKey: key } : {}),
+    };
+}
+export function overlayEditorTarget(target) {
+    const path = target.navigationPath ?? target.path;
+    if (target.kind === 'slice' && target.sliceKey) {
+        return { kind: 'slice', sliceKey: target.sliceKey, ownerPath: path };
+    }
+    const sliceEmbedOptions = richTextSliceEmbedNavigationOptions(target);
+    return {
+        kind: 'field',
+        path,
+        anchors: target.navigationAnchors ?? target.fromAnchors,
+        ...(target.richTextTextNodeIndex !== undefined
+            ? { richTextTextNodeIndex: target.richTextTextNodeIndex }
+            : {}),
+        ...sliceEmbedOptions,
+        focus: true,
+    };
+}
+/** Non-localized owners (navigation/settings) carry no readScope. Keep the
+ * presentation locale; an inherited applied locale is never an editing target. */
+export function overlayEditorLocale(target, presentationLocale) {
+    return target.readScope?.requestedLocale ?? presentationLocale ?? undefined;
+}

package/dist/provenance/field-leaf-walker.d.ts

@@ -0,0 +1,21 @@
+import type { PathAnchor } from './types.js';
+export type PreviewProvenanceFieldPathPart = string | number;
+export interface PreviewProvenanceWalkedFieldLeaf {
+    readonly path: readonly PreviewProvenanceFieldPathPart[];
+    readonly pathAnchors: readonly PathAnchor[];
+    readonly sourceKind: 'stored' | 'richtext';
+    readonly outputKind: 'text' | 'element';
+    readonly value?: unknown;
+    readonly renderedText?: string;
+    readonly textNodeIndex?: number;
+}
+export interface WalkPreviewProvenanceFieldLeavesInput {
+    readonly root: unknown;
+    readonly onLeaf: (leaf: PreviewProvenanceWalkedFieldLeaf) => void;
+}
+/**
+ * The single recursive field traversal shared by source-map materialization
+ * and editable-leaf planning. Consumers own policy and output shaping.
+ */
+export declare function walkPreviewProvenanceFieldLeaves(input: WalkPreviewProvenanceFieldLeavesInput): void;
+export declare function formatPreviewProvenanceCanonicalPath(path: readonly PreviewProvenanceFieldPathPart[]): string;

package/dist/provenance/field-leaf-walker.js

@@ -0,0 +1,98 @@
+import { previewProvenanceRichTextTextNodes } from './coded-text.js';
+/**
+ * The single recursive field traversal shared by source-map materialization
+ * and editable-leaf planning. Consumers own policy and output shaping.
+ */
+export function walkPreviewProvenanceFieldLeaves(input) {
+    visitFieldValue({
+        value: input.root,
+        path: [],
+        pathAnchors: [],
+        onLeaf: input.onLeaf,
+    });
+}
+export function formatPreviewProvenanceCanonicalPath(path) {
+    return path.map((part, index) => typeof part === 'number'
+        ? `[${part}]`
+        : index === 0
+            ? part
+            : `.${part}`).join('');
+}
+function visitFieldValue(input) {
+    const richTextNodes = previewProvenanceRichTextTextNodes(input.value);
+    if (richTextNodes.length > 0) {
+        for (let textNodeIndex = 0; textNodeIndex < richTextNodes.length; textNodeIndex++) {
+            const renderedText = richTextNodes[textNodeIndex];
+            if (!renderedText)
+                continue;
+            input.onLeaf({
+                path: input.path,
+                pathAnchors: input.pathAnchors,
+                sourceKind: 'richtext',
+                outputKind: 'text',
+                value: renderedText,
+                renderedText,
+                textNodeIndex,
+            });
+        }
+        return;
+    }
+    if (typeof input.value === 'string') {
+        if (input.value.length === 0)
+            return;
+        input.onLeaf({
+            path: input.path,
+            pathAnchors: input.pathAnchors,
+            sourceKind: 'stored',
+            outputKind: 'text',
+            value: input.value,
+            renderedText: input.value,
+        });
+        return;
+    }
+    if (Array.isArray(input.value)) {
+        for (let index = 0; index < input.value.length; index++) {
+            const item = input.value[index];
+            visitFieldValue({
+                value: item,
+                path: [...input.path, index],
+                pathAnchors: keyedArrayItemAnchors(input.path, item, input.pathAnchors),
+                onLeaf: input.onLeaf,
+            });
+        }
+        return;
+    }
+    if (input.value === null || typeof input.value !== 'object')
+        return;
+    if (input.path.length > 0) {
+        input.onLeaf({
+            path: input.path,
+            pathAnchors: input.pathAnchors,
+            sourceKind: 'stored',
+            outputKind: 'element',
+            value: input.value,
+        });
+    }
+    for (const [key, child] of Object.entries(input.value)) {
+        if (key.startsWith('_'))
+            continue;
+        visitFieldValue({
+            value: child,
+            path: [...input.path, key],
+            pathAnchors: input.pathAnchors,
+            onLeaf: input.onLeaf,
+        });
+    }
+}
+function keyedArrayItemAnchors(arrayPath, item, inherited) {
+    const key = item !== null && typeof item === 'object'
+        ? item._key
+        : undefined;
+    if (typeof key !== 'string' || key.length === 0 || arrayPath.length === 0) {
+        return inherited;
+    }
+    return [
+        ...inherited,
+        { path: formatPreviewProvenanceCanonicalPath(arrayPath), key },
+    ];
+}