@elytracms/studio 0.0.92 → 0.0.93

package/dist/lib/ai/writer-form.d.ts

@@ -0,0 +1,116 @@
+import type { CmsDocument, CollectionDef, FieldDef, PropFieldLookup, ValuePath, ValuePosition } from '@elytracms/core/cms-core';
+import type { WriterLeash } from './types.js';
+/** The ids a document already references — reusable anywhere in it without a search. */
+export interface HeldReferences {
+    /** Referenced document ids, by collection. */
+    readonly documents: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly assets: ReadonlySet<string>;
+}
+export declare const NO_HELD_REFERENCES: HeldReferences;
+/**
+ * Every document and asset id a document references, read off THE reference walk
+ * (EC-589) — at any depth. An id the document already holds is real (the leash exists
+ * so a model cannot INVENT one), so it stays usable at any position without a search.
+ */
+export declare function heldReferencesOf(document: CmsDocument | undefined): HeldReferences;
+export interface WriterFormContext {
+    /**
+     * Component id → prop field-defs — the validator's own lookup
+     * (`validateOptions.lookupManifest`, the canonical bag's), so the converter reaches
+     * exactly the props the validator judges. Without it a composition has no prop
+     * positions (and {@link fromWriterFormAtNode} refuses, loudly).
+     */
+    readonly lookupManifest?: PropFieldLookup;
+    /** What the model searched (absent → no searched ids). */
+    readonly leash?: WriterLeash;
+    /** What the document already references ({@link heldReferencesOf}). */
+    readonly held?: HeldReferences;
+}
+/** One problem the conversion found, located at its position below the field value. */
+export interface WriterFormProblem {
+    /** Index-bearing location below the field value (`ValuePosition.at`). */
+    readonly at: readonly (string | number)[];
+    readonly code: 'invalid-field-value' | 'unknown-asset' | 'unknown-relation-target';
+    readonly message: string;
+    /** An id outside the leash: it was REMOVED from the converted value. */
+    readonly leash?: true;
+}
+export interface FromWriterFormResult {
+    /** The stored form (`undefined` — clear the position). */
+    readonly value: unknown;
+    readonly problems: readonly WriterFormProblem[];
+}
+/**
+ * Convert a value a model authored at `position` (its `value` is the WRITER form) into
+ * the stored form, at that position and every position below it. `current` is the value
+ * the write replaces — the DISPLAYED value of the bucket being written (ratified 2c) —
+ * which the placement carry and the composition leash read. `null` / `undefined` clears.
+ */
+export declare function fromWriterForm(position: ValuePosition, current: unknown, ctx: WriterFormContext): FromWriterFormResult;
+/** {@link fromWriterForm} for a top-level field's value. */
+export declare function fromWriterFieldValue(field: FieldDef, raw: unknown, current: unknown, ctx: WriterFormContext, locale?: string): FromWriterFormResult;
+export type FromWriterFormAtNodeResult = {
+    readonly ok: true;
+    /** The field's next value (the displayed value with the one prop converted). */
+    readonly value: unknown;
+    /**
+     * The position the change wrote, in the value-position grammar: the prop by its
+     * node path where the grammar reaches it, else the coarsest addressable ancestor
+     * — the field (bucket) itself (EC-595: a writer may always emit a coarser path).
+     */
+    readonly path: ValuePath;
+    /** The converted prop value when {@link path} is the prop itself (`undefined` — unset). */
+    readonly propValue: unknown;
+    readonly exact: boolean;
+    readonly problems: readonly WriterFormProblem[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Change ONE component prop, addressed by its node id and prop name, inside a field's
+ * value — at ANY depth the traversal reaches: a top-level block, a child in a section's
+ * slot, a component embedded in rich text, a component inside an object's rich text or
+ * inside another component's prop. The prop's writer form goes through
+ * {@link fromWriterForm} with the prop's current value (carry + leash at that position),
+ * and the field value is rebuilt by the traversal's writing fold. Nothing else in the
+ * value changes — no other prop, no node, no prose.
+ */
+export declare function fromWriterFormAtNode(field: FieldDef, displayed: unknown, nodeId: string, prop: string, raw: unknown, ctx: WriterFormContext, locale?: string): FromWriterFormAtNodeResult;
+/** Whether a field-def holds TEXT a translation turns into units: plain text, or a sequence. */
+export declare function isTextPosition(position: ValuePosition): boolean;
+/**
+ * Every TEXT position at or below `position` (EC-593, ratified 4e — "translate uses the
+ * same traversal"): a `text` value, and a `richText` / `blocks` sequence (its prose —
+ * the sequence's own text — is the caller's to split) together with every text position
+ * below it: component text props in a composition and in rich-text embeds, object
+ * sub-fields, repeater items, asset placement sub-fields. An `ai.exclude` position (and
+ * everything below it) is not text a writer may touch. Depth-first, document order.
+ */
+export declare function textPositionsOf(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>): ValuePosition[];
+/**
+ * The writing fold over {@link textPositionsOf}: the value at `position` with each text
+ * position's value replaced by `replace(textPosition)` — for a sequence, its own value
+ * first (its prose), then the text positions below it, read off the REPLACED value (a
+ * component keeps its node id, so its props are found again). Every other value — an
+ * image, a select, a component's structure — comes back as it was (identity-preserving).
+ */
+export declare function rebuildTextPositions(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>, replace: (textPosition: ValuePosition) => unknown): unknown;
+/**
+ * The form a model READS a stored value in — the mirror of {@link fromWriterForm}, so
+ * what `getDocument` shows is what `updateFields` takes back: rich text as a markdown
+ * string wherever the engine's loss-guarded inverse can express it faithfully (no
+ * embedded components, subset-only marks — else the stored `{ version: 2, content }`
+ * stays, so nothing echoed back can silently lose structure), at EVERY position: a
+ * top-level field, an object sub-field, a repeater item, a component's rich-text prop.
+ * Everything else reads as stored (envelopes are writer forms too).
+ */
+export declare function toWriterForm(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>): unknown;
+/**
+ * The components a document holds whose props a writer may change — every component
+ * the traversal reaches a DECLARED prop of, in every field of every bucket, at any depth
+ * — in first-seen order. What the `getDocument` output's prop catalog lists.
+ */
+export declare function componentIdsOf(collection: CollectionDef, document: CmsDocument, lookupManifest: PropFieldLookup): string[];
+/** {@link toWriterForm} over every field of every bucket of a document. */
+export declare function toWriterDocument(collection: CollectionDef, document: CmsDocument, ctx: Pick<WriterFormContext, 'lookupManifest'>): CmsDocument;

package/dist/lib/ai/writer-form.js

@@ -0,0 +1,429 @@
+/**
+ * **THE AI writer-form converter pair** (EC-593, owner-ratified 2026-10-24 — EC-565
+ * Round 4, 4c / 4e / 2c; closes EC-571, EC-562 and EC-570 #3).
+ *
+ * What a model WRITES is not what is stored: rich text is a markdown string, an asset a
+ * bare library id (or its envelope when the position declares placement sub-fields), a
+ * relation `{ collection, id }`. Every AI writer — create (`applyContentWithShape`), edit
+ * (`buildUpdateProposal`), translate (`translateDocument`) — and the one AI reader
+ * (`getDocument`'s output) cross that line here, and only here:
+ *
+ * - {@link fromWriterForm} — writer form → stored form at a position and EVERY position
+ *   below it;
+ * - {@link toWriterForm} — stored form → the form the model reads (rich text as markdown
+ *   wherever it is faithfully expressible), at every position.
+ *
+ * Both are folds over core's ONE value-position traversal (`childPositions` /
+ * `rebuildFromChildren`, EC-582): an object's sub-fields, each repeater item, an asset
+ * placement's sub-fields, and every DECLARED prop of every component node inside a
+ * `blocks` / `richText` value (top level, typography, slots — and below a prop). So a
+ * nested position is converted by the same rule as a top-level one; there is no second
+ * walk to forget a depth (the bug class EC-571 measured: create converted at every depth,
+ * edit at the top level only, the read form and translate at the top level only).
+ *
+ * At every position the converter applies:
+ * - **the id leash** (EC-381) — a relation or asset id must come from what the model
+ *   searched ({@link WriterLeash}, asked per position: a relation by its target, an asset
+ *   by its declaration's `accept`) or be one the document already references. Anything
+ *   else is REMOVED from the value and reported as a `leash` problem (create drops it,
+ *   edit refuses — the callers' ratified policies);
+ * - **the placement carry** (EC-558, ratified 2c) — an asset swap keeps the placement's
+ *   per-use sub-fields through core's one rule (`carryAssetPlacements`), read from the
+ *   `current` value the caller passes: the DISPLAYED value of the bucket being written
+ *   (a new locale bucket carries from its fallback, as the pickers do);
+ * - **the composition leash** (ratified 4c) — the AI writes content at every depth and
+ *   never composition STRUCTURE: a `blocks` value is never written whole
+ *   (`FIELD_TYPES.blocks.writer === 'composition'`), and a rich-text value must keep the
+ *   component nodes it holds (same ids, same components, same places). A component's
+ *   PROP is content — {@link fromWriterFormAtNode} changes one, by its node, at any depth
+ *   the traversal reaches.
+ *
+ * Pure and deterministic; no provider, no I/O.
+ */
+import { carryAssetPlacements, childPositions, fieldPath, fieldTypeOf, fieldValuePosition, isSequenceValue, rebuildFromChildren, referenceNode, sequenceComponentNodes, walkReferences, walkValuePositions, } from '@elytracms/core/cms-core';
+import { parseRichTextValue, richTextValueToMarkdownProse } from '@elytracms/core/rich-text';
+import { richTextValueFromModelInput } from './rich-text-input.js';
+export const NO_HELD_REFERENCES = { documents: new Map(), assets: new Set() };
+/**
+ * Every document and asset id a document references, read off THE reference walk
+ * (EC-589) — at any depth. An id the document already holds is real (the leash exists
+ * so a model cannot INVENT one), so it stays usable at any position without a search.
+ */
+export function heldReferencesOf(document) {
+    if (!document)
+        return NO_HELD_REFERENCES;
+    const documents = new Map();
+    const assets = new Set();
+    walkReferences(document, (hit) => {
+        if (hit.target.type === 'asset')
+            assets.add(hit.target.id);
+        else if (hit.target.type === 'document') {
+            const ids = documents.get(hit.target.ref.collection) ?? new Set();
+            ids.add(hit.target.ref.id);
+            documents.set(hit.target.ref.collection, ids);
+        }
+    });
+    return { documents, assets };
+}
+// --- Writer form → stored form -------------------------------------------------------
+/**
+ * Convert a value a model authored at `position` (its `value` is the WRITER form) into
+ * the stored form, at that position and every position below it. `current` is the value
+ * the write replaces — the DISPLAYED value of the bucket being written (ratified 2c) —
+ * which the placement carry and the composition leash read. `null` / `undefined` clears.
+ */
+export function fromWriterForm(position, current, ctx) {
+    const problems = [];
+    const value = convert(position, current, ctx, problems, position.field.name);
+    return { value, problems };
+}
+/** {@link fromWriterForm} for a top-level field's value. */
+export function fromWriterFieldValue(field, raw, current, ctx, locale) {
+    return fromWriterForm(fieldValuePosition(field, raw, locale !== undefined ? { locale } : {}), current, ctx);
+}
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `title`, `card.image`, `menu[2].label`, `body.content[0].props.headline` — for messages. */
+function label(root, at) {
+    return at.reduce((out, key) => (typeof key === 'number' ? `${out}[${key}]` : `${out}.${key}`), root);
+}
+/** The model-facing name of a position: the field's own name, located when nested. */
+function subject(pos, root) {
+    return pos.at.length === 0 ? `"${pos.field.name}"` : `"${pos.field.name}" (at ${label(root, pos.at)})`;
+}
+/**
+ * The structural fingerprint of a composition: which component nodes there are, nested
+ * where (their component-ancestor chain), in order relative to each other. Prose between
+ * them is content (a new paragraph before an embed shifts its index, not its place among
+ * the components); adding, removing, re-nesting or reordering a component is structure.
+ */
+function compositionOf(value) {
+    return sequenceComponentNodes(value)
+        .map(({ node, chain }) => `${[...chain, node.id].join('/')}=${node.componentId}`)
+        .join('|');
+}
+/** Key-order-insensitive JSON — "is this the same value" for a composition the writer may not change. */
+function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'undefined';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    return `{${Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`)
+        .join(',')}}`;
+}
+/** The stable key matching a child position of the written value to the current value's. */
+function childKey(parent, child) {
+    // A prop by its node (ids are stable across a prose edit that shifts indices);
+    // everything else by its location relative to the parent.
+    return child.kind === 'prop' && child.component
+        ? `node:${child.component.nodeId}:${child.field.name}`
+        : `at:${JSON.stringify(child.at.slice(parent.at.length))}`;
+}
+/** Convert every child position of `pos` (its value already in a readable shape). */
+function convertChildren(pos, current, ctx, problems, root) {
+    const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
+    const currentChildren = new Map();
+    if (current !== undefined) {
+        for (const child of childPositions({ ...pos, value: current }, positionCtx)) {
+            currentChildren.set(childKey(pos, child), child.value);
+        }
+    }
+    return rebuildFromChildren(pos, positionCtx, (child) => convert(child, currentChildren.get(childKey(pos, child)), ctx, problems, root));
+}
+function convert(pos, current, ctx, problems, root) {
+    const { field } = pos;
+    const raw = pos.value === null ? undefined : pos.value;
+    const report = (code, message, leash) => {
+        problems.push({ at: pos.at, code, message, ...(leash ? { leash } : {}) });
+        return undefined;
+    };
+    switch (fieldTypeOf(field).writer) {
+        case 'composition': {
+            // 4c: a composition is never written whole — the value stays exactly what it is
+            // (re-sending it unchanged is no change); its props change one at a time.
+            if (canonicalJson(raw) === canonicalJson(current))
+                return current;
+            return report('invalid-field-value', `Field ${subject(pos, root)} is a page-builder composition: adding, reordering or removing its components is done on the canvas, not by the assistant. Change one component's prop with blockId + prop (the component's id from getDocument).`);
+        }
+        case 'markdown': {
+            let next = undefined;
+            if (raw !== undefined) {
+                const parsed = richTextValueFromModelInput(raw);
+                if (!parsed.ok)
+                    return report('invalid-field-value', `Field ${subject(pos, root)}: ${parsed.problems.join(' ')}`);
+                // An echoed stored value may carry components: their props are positions too.
+                next = convertChildren({ ...pos, value: parsed.value }, current, ctx, problems, root);
+            }
+            // 4c: prose is content, the components embedded in it are structure.
+            if (compositionOf(next) !== compositionOf(current)) {
+                return report('invalid-field-value', `Field ${subject(pos, root)} holds embedded components; the assistant cannot add, remove or move them (that is done in the editor). Send the value back as the stored { version: 2, content } object with every component node kept in place, or change a component's prop with blockId + prop.`);
+            }
+            return next;
+        }
+        case 'placement': {
+            if (raw === undefined)
+                return undefined;
+            const asset = field;
+            const items = Array.isArray(raw) ? raw : [raw];
+            const entries = [];
+            for (const item of items) {
+                if (typeof item === 'string' && item.length > 0)
+                    entries.push({ id: item, rest: {} });
+                else if (isPlainRecord(item) &&
+                    typeof item.id === 'string' &&
+                    item.id.length > 0 &&
+                    (item.type === undefined || item.type === 'asset')) {
+                    const { type: _type, id, ...rest } = item;
+                    entries.push({ id: id, rest });
+                }
+                else {
+                    return report('invalid-field-value', `Asset field ${subject(pos, root)} takes asset id string(s) from listAssets results.`);
+                }
+            }
+            if (asset.multiple !== true && entries.length > 1) {
+                return report('invalid-field-value', `Field ${subject(pos, root)} holds a single asset — pass one id.`);
+            }
+            // EC-381: the asset id leash — searched (fitting this position's `accept`) or
+            // already on the document; the assistant never invents or uploads an asset.
+            const allowed = new Set([
+                ...(ctx.leash?.assetCandidates(asset) ?? []).map((candidate) => candidate.id),
+                ...(ctx.held?.assets ?? []),
+            ]);
+            const unknown = entries.filter((entry) => !allowed.has(entry.id));
+            if (unknown.length > 0) {
+                report('unknown-asset', `Asset field ${subject(pos, root)} may only use ids from listAssets results — search the media library first (got: ${unknown.map((e) => e.id).join(', ')}).`, true);
+            }
+            const kept = entries.filter((entry) => allowed.has(entry.id));
+            if (kept.length === 0)
+                return undefined;
+            // EC-558 / 2c: the ONE carry rule — a held placement keeps its per-use sub-fields,
+            // a swap carries them to the new image, a new id is an envelope.
+            const carried = carryAssetPlacements(current, asset.multiple === true ? { multiple: true, ids: kept.map((e) => e.id) } : { multiple: false, id: kept[0].id });
+            // The writer's own sub-field values win over the carried ones.
+            const withWriter = (entry, index) => {
+                const rest = kept[index]?.rest ?? {};
+                if (Object.keys(rest).length === 0)
+                    return entry;
+                const base = isPlainRecord(entry) ? entry : { type: 'asset', id: kept[index].id };
+                return { ...base, ...rest };
+            };
+            const merged = Array.isArray(carried) ? carried.map(withWriter) : withWriter(carried, 0);
+            return convertChildren({ ...pos, value: merged }, carried, ctx, problems, root);
+        }
+        case 'reference': {
+            if (raw === undefined)
+                return undefined;
+            const relation = field;
+            const items = Array.isArray(raw) ? raw : [raw];
+            const ids = [];
+            for (const item of items) {
+                const id = typeof item === 'string' ? item : isPlainRecord(item) && typeof item.id === 'string' ? item.id : undefined;
+                const collection = isPlainRecord(item) ? item.collection : undefined;
+                if (!id || (collection !== undefined && collection !== relation.target)) {
+                    return report('invalid-field-value', `Relation ${subject(pos, root)} takes document id string(s) from searchDocuments results.`);
+                }
+                ids.push(id);
+            }
+            if (relation.multiple !== true && ids.length > 1) {
+                return report('invalid-field-value', `Field ${subject(pos, root)} holds a single reference — pass one id.`);
+            }
+            // EC-378/EC-381: the relation id leash — searched in the target collection, or
+            // already referenced by the document.
+            const allowed = new Set([
+                ...(ctx.leash?.relationCandidates(relation.target) ?? []).map((candidate) => candidate.id),
+                ...(ctx.held?.documents.get(relation.target) ?? []),
+            ]);
+            const unknown = ids.filter((id) => !allowed.has(id));
+            if (unknown.length > 0) {
+                report('unknown-relation-target', `Relation ${subject(pos, root)} may only use ids from searchDocuments results — search "${relation.target}" first (got: ${unknown.join(', ')}).`, true);
+            }
+            const refs = ids.filter((id) => allowed.has(id)).map((id) => referenceNode({ collection: relation.target, id }));
+            if (refs.length === 0)
+                return undefined;
+            return relation.multiple === true ? refs : refs[0];
+        }
+        case 'object':
+            // A value of the wrong shape has no children; the validator names it.
+            return raw === undefined ? undefined : convertChildren({ ...pos, value: raw }, current, ctx, problems, root);
+        case 'value':
+            return raw;
+    }
+}
+/**
+ * Change ONE component prop, addressed by its node id and prop name, inside a field's
+ * value — at ANY depth the traversal reaches: a top-level block, a child in a section's
+ * slot, a component embedded in rich text, a component inside an object's rich text or
+ * inside another component's prop. The prop's writer form goes through
+ * {@link fromWriterForm} with the prop's current value (carry + leash at that position),
+ * and the field value is rebuilt by the traversal's writing fold. Nothing else in the
+ * value changes — no other prop, no node, no prose.
+ */
+export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, locale) {
+    if (!ctx.lookupManifest) {
+        return {
+            ok: false,
+            message: `Component props cannot be changed here: the project's components are not available to judge "${prop}".`,
+        };
+    }
+    const positionCtx = { lookupManifest: ctx.lookupManifest };
+    const root = fieldValuePosition(field, displayed, locale !== undefined ? { locale } : {});
+    const isTarget = (position) => position.kind === 'prop' && position.component?.nodeId === nodeId && position.field.name === prop;
+    let target;
+    const declared = [];
+    let componentId;
+    walkValuePositions(root, positionCtx, (position) => {
+        if (position.kind !== 'prop' || position.component?.nodeId !== nodeId)
+            return;
+        componentId = position.component.componentId;
+        declared.push(position.field.name);
+        if (target === undefined && position.field.name === prop)
+            target = position;
+    });
+    if (!target) {
+        if (componentId === undefined) {
+            return {
+                ok: false,
+                message: `Component "${nodeId}" was not found in "${field.name}" (or its component declares no props) — read the document first; component ids come from getDocument.`,
+            };
+        }
+        return {
+            ok: false,
+            message: `Component "${nodeId}" (${componentId}) has no prop "${prop}" — its props are: ${declared.join(', ')}.`,
+        };
+    }
+    const found = target;
+    const { value: converted, problems } = fromWriterForm({ ...found, value: raw }, found.value, ctx);
+    const rebuild = (position) => rebuildFromChildren(position, positionCtx, (child) => (isTarget(child) ? converted : rebuild(child)));
+    const value = rebuild(root);
+    return found.exact
+        ? { ok: true, value, path: found.path, propValue: converted, exact: true, problems }
+        : { ok: true, value, path: fieldPath(field.name, locale), propValue: undefined, exact: false, problems };
+}
+// --- The text positions (translate) --------------------------------------------------
+/** Whether a field-def holds TEXT a translation turns into units: plain text, or a sequence. */
+export function isTextPosition(position) {
+    const { type } = position.field;
+    return type === 'text' || type === 'richText' || type === 'blocks';
+}
+function isExcludedBelow(position) {
+    return position.at.length > 0 && position.field.ai?.exclude === true;
+}
+/**
+ * Every TEXT position at or below `position` (EC-593, ratified 4e — "translate uses the
+ * same traversal"): a `text` value, and a `richText` / `blocks` sequence (its prose —
+ * the sequence's own text — is the caller's to split) together with every text position
+ * below it: component text props in a composition and in rich-text embeds, object
+ * sub-fields, repeater items, asset placement sub-fields. An `ai.exclude` position (and
+ * everything below it) is not text a writer may touch. Depth-first, document order.
+ */
+export function textPositionsOf(position, ctx) {
+    const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
+    const out = [];
+    const visit = (current) => {
+        if (isExcludedBelow(current))
+            return;
+        if (isTextPosition(current))
+            out.push(current);
+        if (current.field.type === 'text')
+            return;
+        for (const child of childPositions(current, positionCtx))
+            visit(child);
+    };
+    visit(position);
+    return out;
+}
+/**
+ * The writing fold over {@link textPositionsOf}: the value at `position` with each text
+ * position's value replaced by `replace(textPosition)` — for a sequence, its own value
+ * first (its prose), then the text positions below it, read off the REPLACED value (a
+ * component keeps its node id, so its props are found again). Every other value — an
+ * image, a select, a component's structure — comes back as it was (identity-preserving).
+ */
+export function rebuildTextPositions(position, ctx, replace) {
+    const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
+    const rebuild = (current) => {
+        if (isExcludedBelow(current))
+            return current.value;
+        if (current.field.type === 'text')
+            return replace(current);
+        const value = isTextPosition(current) ? replace(current) : current.value;
+        return rebuildFromChildren({ ...current, value }, positionCtx, rebuild);
+    };
+    return rebuild(position);
+}
+// --- Stored form → the read (writer) form --------------------------------------------
+/**
+ * The form a model READS a stored value in — the mirror of {@link fromWriterForm}, so
+ * what `getDocument` shows is what `updateFields` takes back: rich text as a markdown
+ * string wherever the engine's loss-guarded inverse can express it faithfully (no
+ * embedded components, subset-only marks — else the stored `{ version: 2, content }`
+ * stays, so nothing echoed back can silently lose structure), at EVERY position: a
+ * top-level field, an object sub-field, a repeater item, a component's rich-text prop.
+ * Everything else reads as stored (envelopes are writer forms too).
+ */
+export function toWriterForm(position, ctx) {
+    const { value } = position;
+    if (value === undefined || value === null)
+        return value;
+    const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
+    if (fieldTypeOf(position.field).writer === 'markdown' && isSequenceValue(value)) {
+        const parsed = parseRichTextValue(value);
+        const markdown = parsed.ok ? richTextValueToMarkdownProse(parsed.value) : undefined;
+        if (markdown !== undefined)
+            return markdown;
+    }
+    return rebuildFromChildren(position, positionCtx, (child) => toWriterForm(child, ctx));
+}
+/**
+ * The components a document holds whose props a writer may change — every component
+ * the traversal reaches a DECLARED prop of, in every field of every bucket, at any depth
+ * — in first-seen order. What the `getDocument` output's prop catalog lists.
+ */
+export function componentIdsOf(collection, document, lookupManifest) {
+    const ids = new Set();
+    const byName = new Map(collection.fields.map((field) => [field.name, field]));
+    const visitBucket = (bucket) => {
+        for (const [name, value] of Object.entries(bucket)) {
+            const field = byName.get(name);
+            if (!field)
+                continue;
+            walkValuePositions(fieldValuePosition(field, value), { lookupManifest }, (position) => {
+                if (position.kind === 'prop' && position.component)
+                    ids.add(position.component.componentId);
+            });
+        }
+    };
+    visitBucket(document.values);
+    for (const bucket of Object.values(document.localized ?? {}))
+        visitBucket(bucket);
+    return [...ids];
+}
+/** {@link toWriterForm} over every field of every bucket of a document. */
+export function toWriterDocument(collection, document, ctx) {
+    const byName = new Map(collection.fields.map((field) => [field.name, field]));
+    const mapBucket = (bucket, locale) => {
+        let next = bucket;
+        for (const [name, value] of Object.entries(bucket)) {
+            const field = byName.get(name);
+            if (!field)
+                continue;
+            const read = toWriterForm(fieldValuePosition(field, value, locale !== undefined ? { locale } : {}), ctx);
+            if (read === value)
+                continue;
+            if (next === bucket)
+                next = { ...bucket };
+            next[name] = read;
+        }
+        return next;
+    };
+    const values = mapBucket(document.values);
+    const localized = document.localized
+        ? Object.fromEntries(Object.entries(document.localized).map(([locale, bucket]) => [locale, mapBucket(bucket, locale)]))
+        : undefined;
+    return { ...document, values, ...(localized ? { localized } : {}) };
+}
+//# sourceMappingURL=writer-form.js.map

package/dist/lib/ai/writer-form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-form.js","sourceRoot":"","sources":["../../../src/lib/ai/writer-form.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * **THE AI writer-form converter pair** (EC-593, owner-ratified 2026-10-24 — EC-565\n * Round 4, 4c / 4e / 2c; closes EC-571, EC-562 and EC-570 #3).\n *\n * What a model WRITES is not what is stored: rich text is a markdown string, an asset a\n * bare library id (or its envelope when the position declares placement sub-fields), a\n * relation `{ collection, id }`. Every AI writer — create (`applyContentWithShape`), edit\n * (`buildUpdateProposal`), translate (`translateDocument`) — and the one AI reader\n * (`getDocument`'s output) cross that line here, and only here:\n *\n * - {@link fromWriterForm} — writer form → stored form at a position and EVERY position\n *   below it;\n * - {@link toWriterForm} — stored form → the form the model reads (rich text as markdown\n *   wherever it is faithfully expressible), at every position.\n *\n * Both are folds over core's ONE value-position traversal (`childPositions` /\n * `rebuildFromChildren`, EC-582): an object's sub-fields, each repeater item, an asset\n * placement's sub-fields, and every DECLARED prop of every component node inside a\n * `blocks` / `richText` value (top level, typography, slots — and below a prop). So a\n * nested position is converted by the same rule as a top-level one; there is no second\n * walk to forget a depth (the bug class EC-571 measured: create converted at every depth,\n * edit at the top level only, the read form and translate at the top level only).\n *\n * At every position the converter applies:\n * - **the id leash** (EC-381) — a relation or asset id must come from what the model\n *   searched ({@link WriterLeash}, asked per position: a relation by its target, an asset\n *   by its declaration's `accept`) or be one the document already references. Anything\n *   else is REMOVED from the value and reported as a `leash` problem (create drops it,\n *   edit refuses — the callers' ratified policies);\n * - **the placement carry** (EC-558, ratified 2c) — an asset swap keeps the placement's\n *   per-use sub-fields through core's one rule (`carryAssetPlacements`), read from the\n *   `current` value the caller passes: the DISPLAYED value of the bucket being written\n *   (a new locale bucket carries from its fallback, as the pickers do);\n * - **the composition leash** (ratified 4c) — the AI writes content at every depth and\n *   never composition STRUCTURE: a `blocks` value is never written whole\n *   (`FIELD_TYPES.blocks.writer === 'composition'`), and a rich-text value must keep the\n *   component nodes it holds (same ids, same components, same places). A component's\n *   PROP is content — {@link fromWriterFormAtNode} changes one, by its node, at any depth\n *   the traversal reaches.\n *\n * Pure and deterministic; no provider, no I/O.\n */\nimport {\n  carryAssetPlacements,\n  childPositions,\n  fieldPath,\n  fieldTypeOf,\n  fieldValuePosition,\n  isSequenceValue,\n  rebuildFromChildren,\n  referenceNode,\n  sequenceComponentNodes,\n  walkReferences,\n  walkValuePositions,\n} from '@elytracms/core/cms-core'\nimport type {\n  AssetFieldDef,\n  CmsDocument,\n  CollectionDef,\n  FieldDef,\n  FieldValues,\n  PropFieldLookup,\n  RelationFieldDef,\n  ValuePath,\n  ValuePosition,\n} from '@elytracms/core/cms-core'\nimport { parseRichTextValue, richTextValueToMarkdownProse } from '@elytracms/core/rich-text'\nimport { richTextValueFromModelInput } from './rich-text-input'\nimport type { WriterLeash } from './types'\n\n// --- The context ---------------------------------------------------------------------\n\n/** The ids a document already references — reusable anywhere in it without a search. */\nexport interface HeldReferences {\n  /** Referenced document ids, by collection. */\n  readonly documents: ReadonlyMap<string, ReadonlySet<string>>\n  readonly assets: ReadonlySet<string>\n}\n\nexport const NO_HELD_REFERENCES: HeldReferences = { documents: new Map(), assets: new Set() }\n\n/**\n * Every document and asset id a document references, read off THE reference walk\n * (EC-589) — at any depth. An id the document already holds is real (the leash exists\n * so a model cannot INVENT one), so it stays usable at any position without a search.\n */\nexport function heldReferencesOf(document: CmsDocument | undefined): HeldReferences {\n  if (!document) return NO_HELD_REFERENCES\n  const documents = new Map<string, Set<string>>()\n  const assets = new Set<string>()\n  walkReferences(document, (hit) => {\n    if (hit.target.type === 'asset') assets.add(hit.target.id)\n    else if (hit.target.type === 'document') {\n      const ids = documents.get(hit.target.ref.collection) ?? new Set<string>()\n      ids.add(hit.target.ref.id)\n      documents.set(hit.target.ref.collection, ids)\n    }\n  })\n  return { documents, assets }\n}\n\nexport interface WriterFormContext {\n  /**\n   * Component id → prop field-defs — the validator's own lookup\n   * (`validateOptions.lookupManifest`, the canonical bag's), so the converter reaches\n   * exactly the props the validator judges. Without it a composition has no prop\n   * positions (and {@link fromWriterFormAtNode} refuses, loudly).\n   */\n  readonly lookupManifest?: PropFieldLookup\n  /** What the model searched (absent → no searched ids). */\n  readonly leash?: WriterLeash\n  /** What the document already references ({@link heldReferencesOf}). */\n  readonly held?: HeldReferences\n}\n\n/** One problem the conversion found, located at its position below the field value. */\nexport interface WriterFormProblem {\n  /** Index-bearing location below the field value (`ValuePosition.at`). */\n  readonly at: readonly (string | number)[]\n  readonly code: 'invalid-field-value' | 'unknown-asset' | 'unknown-relation-target'\n  readonly message: string\n  /** An id outside the leash: it was REMOVED from the converted value. */\n  readonly leash?: true\n}\n\nexport interface FromWriterFormResult {\n  /** The stored form (`undefined` — clear the position). */\n  readonly value: unknown\n  readonly problems: readonly WriterFormProblem[]\n}\n\n// --- Writer form → stored form -------------------------------------------------------\n\n/**\n * Convert a value a model authored at `position` (its `value` is the WRITER form) into\n * the stored form, at that position and every position below it. `current` is the value\n * the write replaces — the DISPLAYED value of the bucket being written (ratified 2c) —\n * which the placement carry and the composition leash read. `null` / `undefined` clears.\n */\nexport function fromWriterForm(\n  position: ValuePosition,\n  current: unknown,\n  ctx: WriterFormContext,\n): FromWriterFormResult {\n  const problems: WriterFormProblem[] = []\n  const value = convert(position, current, ctx, problems, position.field.name)\n  return { value, problems }\n}\n\n/** {@link fromWriterForm} for a top-level field's value. */\nexport function fromWriterFieldValue(\n  field: FieldDef,\n  raw: unknown,\n  current: unknown,\n  ctx: WriterFormContext,\n  locale?: string,\n): FromWriterFormResult {\n  return fromWriterForm(fieldValuePosition(field, raw, locale !== undefined ? { locale } : {}), current, ctx)\n}\n\nfunction isPlainRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value)\n}\n\n/** `title`, `card.image`, `menu[2].label`, `body.content[0].props.headline` — for messages. */\nfunction label(root: string, at: readonly (string | number)[]): string {\n  return at.reduce<string>((out, key) => (typeof key === 'number' ? `${out}[${key}]` : `${out}.${key}`), root)\n}\n\n/** The model-facing name of a position: the field's own name, located when nested. */\nfunction subject(pos: ValuePosition, root: string): string {\n  return pos.at.length === 0 ? `\"${pos.field.name}\"` : `\"${pos.field.name}\" (at ${label(root, pos.at)})`\n}\n\n/**\n * The structural fingerprint of a composition: which component nodes there are, nested\n * where (their component-ancestor chain), in order relative to each other. Prose between\n * them is content (a new paragraph before an embed shifts its index, not its place among\n * the components); adding, removing, re-nesting or reordering a component is structure.\n */\nfunction compositionOf(value: unknown): string {\n  return sequenceComponentNodes(value)\n    .map(({ node, chain }) => `${[...chain, node.id].join('/')}=${node.componentId}`)\n    .join('|')\n}\n\n/** Key-order-insensitive JSON — \"is this the same value\" for a composition the writer may not change. */\nfunction canonicalJson(value: unknown): string {\n  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined'\n  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`\n  return `{${Object.entries(value as Record<string, unknown>)\n    .filter(([, v]) => v !== undefined)\n    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))\n    .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`)\n    .join(',')}}`\n}\n\n/** The stable key matching a child position of the written value to the current value's. */\nfunction childKey(parent: ValuePosition, child: ValuePosition): string {\n  // A prop by its node (ids are stable across a prose edit that shifts indices);\n  // everything else by its location relative to the parent.\n  return child.kind === 'prop' && child.component\n    ? `node:${child.component.nodeId}:${child.field.name}`\n    : `at:${JSON.stringify(child.at.slice(parent.at.length))}`\n}\n\n/** Convert every child position of `pos` (its value already in a readable shape). */\nfunction convertChildren(\n  pos: ValuePosition,\n  current: unknown,\n  ctx: WriterFormContext,\n  problems: WriterFormProblem[],\n  root: string,\n): unknown {\n  const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {}\n  const currentChildren = new Map<string, unknown>()\n  if (current !== undefined) {\n    for (const child of childPositions({ ...pos, value: current }, positionCtx)) {\n      currentChildren.set(childKey(pos, child), child.value)\n    }\n  }\n  return rebuildFromChildren(pos, positionCtx, (child) =>\n    convert(child, currentChildren.get(childKey(pos, child)), ctx, problems, root),\n  )\n}\n\nfunction convert(\n  pos: ValuePosition,\n  current: unknown,\n  ctx: WriterFormContext,\n  problems: WriterFormProblem[],\n  root: string,\n): unknown {\n  const { field } = pos\n  const raw = pos.value === null ? undefined : pos.value\n  const report = (code: WriterFormProblem['code'], message: string, leash?: true): undefined => {\n    problems.push({ at: pos.at, code, message, ...(leash ? { leash } : {}) })\n    return undefined\n  }\n\n  switch (fieldTypeOf(field).writer) {\n    case 'composition': {\n      // 4c: a composition is never written whole — the value stays exactly what it is\n      // (re-sending it unchanged is no change); its props change one at a time.\n      if (canonicalJson(raw) === canonicalJson(current)) return current\n      return report(\n        'invalid-field-value',\n        `Field ${subject(pos, root)} is a page-builder composition: adding, reordering or removing its components is done on the canvas, not by the assistant. Change one component's prop with blockId + prop (the component's id from getDocument).`,\n      )\n    }\n\n    case 'markdown': {\n      let next: unknown = undefined\n      if (raw !== undefined) {\n        const parsed = richTextValueFromModelInput(raw)\n        if (!parsed.ok) return report('invalid-field-value', `Field ${subject(pos, root)}: ${parsed.problems.join(' ')}`)\n        // An echoed stored value may carry components: their props are positions too.\n        next = convertChildren({ ...pos, value: parsed.value }, current, ctx, problems, root)\n      }\n      // 4c: prose is content, the components embedded in it are structure.\n      if (compositionOf(next) !== compositionOf(current)) {\n        return report(\n          'invalid-field-value',\n          `Field ${subject(pos, root)} holds embedded components; the assistant cannot add, remove or move them (that is done in the editor). Send the value back as the stored { version: 2, content } object with every component node kept in place, or change a component's prop with blockId + prop.`,\n        )\n      }\n      return next\n    }\n\n    case 'placement': {\n      if (raw === undefined) return undefined\n      const asset = field as AssetFieldDef\n      const items = Array.isArray(raw) ? raw : [raw]\n      const entries: { id: string; rest: Record<string, unknown> }[] = []\n      for (const item of items) {\n        if (typeof item === 'string' && item.length > 0) entries.push({ id: item, rest: {} })\n        else if (\n          isPlainRecord(item) &&\n          typeof item.id === 'string' &&\n          item.id.length > 0 &&\n          (item.type === undefined || item.type === 'asset')\n        ) {\n          const { type: _type, id, ...rest } = item\n          entries.push({ id: id as string, rest })\n        } else {\n          return report(\n            'invalid-field-value',\n            `Asset field ${subject(pos, root)} takes asset id string(s) from listAssets results.`,\n          )\n        }\n      }\n      if (asset.multiple !== true && entries.length > 1) {\n        return report('invalid-field-value', `Field ${subject(pos, root)} holds a single asset — pass one id.`)\n      }\n      // EC-381: the asset id leash — searched (fitting this position's `accept`) or\n      // already on the document; the assistant never invents or uploads an asset.\n      const allowed = new Set([\n        ...(ctx.leash?.assetCandidates(asset) ?? []).map((candidate) => candidate.id),\n        ...(ctx.held?.assets ?? []),\n      ])\n      const unknown = entries.filter((entry) => !allowed.has(entry.id))\n      if (unknown.length > 0) {\n        report(\n          'unknown-asset',\n          `Asset field ${subject(pos, root)} may only use ids from listAssets results — search the media library first (got: ${unknown.map((e) => e.id).join(', ')}).`,\n          true,\n        )\n      }\n      const kept = entries.filter((entry) => allowed.has(entry.id))\n      if (kept.length === 0) return undefined\n      // EC-558 / 2c: the ONE carry rule — a held placement keeps its per-use sub-fields,\n      // a swap carries them to the new image, a new id is an envelope.\n      const carried = carryAssetPlacements(\n        current,\n        asset.multiple === true ? { multiple: true, ids: kept.map((e) => e.id) } : { multiple: false, id: kept[0]!.id },\n      )\n      // The writer's own sub-field values win over the carried ones.\n      const withWriter = (entry: unknown, index: number): unknown => {\n        const rest = kept[index]?.rest ?? {}\n        if (Object.keys(rest).length === 0) return entry\n        const base = isPlainRecord(entry) ? entry : { type: 'asset', id: kept[index]!.id }\n        return { ...base, ...rest }\n      }\n      const merged = Array.isArray(carried) ? carried.map(withWriter) : withWriter(carried, 0)\n      return convertChildren({ ...pos, value: merged }, carried, ctx, problems, root)\n    }\n\n    case 'reference': {\n      if (raw === undefined) return undefined\n      const relation = field as RelationFieldDef\n      const items = Array.isArray(raw) ? raw : [raw]\n      const ids: string[] = []\n      for (const item of items) {\n        const id = typeof item === 'string' ? item : isPlainRecord(item) && typeof item.id === 'string' ? item.id : undefined\n        const collection = isPlainRecord(item) ? item.collection : undefined\n        if (!id || (collection !== undefined && collection !== relation.target)) {\n          return report(\n            'invalid-field-value',\n            `Relation ${subject(pos, root)} takes document id string(s) from searchDocuments results.`,\n          )\n        }\n        ids.push(id)\n      }\n      if (relation.multiple !== true && ids.length > 1) {\n        return report('invalid-field-value', `Field ${subject(pos, root)} holds a single reference — pass one id.`)\n      }\n      // EC-378/EC-381: the relation id leash — searched in the target collection, or\n      // already referenced by the document.\n      const allowed = new Set([\n        ...(ctx.leash?.relationCandidates(relation.target) ?? []).map((candidate) => candidate.id),\n        ...(ctx.held?.documents.get(relation.target) ?? []),\n      ])\n      const unknown = ids.filter((id) => !allowed.has(id))\n      if (unknown.length > 0) {\n        report(\n          'unknown-relation-target',\n          `Relation ${subject(pos, root)} may only use ids from searchDocuments results — search \"${relation.target}\" first (got: ${unknown.join(', ')}).`,\n          true,\n        )\n      }\n      const refs = ids.filter((id) => allowed.has(id)).map((id) => referenceNode({ collection: relation.target, id }))\n      if (refs.length === 0) return undefined\n      return relation.multiple === true ? refs : refs[0]\n    }\n\n    case 'object':\n      // A value of the wrong shape has no children; the validator names it.\n      return raw === undefined ? undefined : convertChildren({ ...pos, value: raw }, current, ctx, problems, root)\n\n    case 'value':\n      return raw\n  }\n}\n\n// --- A component prop, by its node ---------------------------------------------------\n\nexport type FromWriterFormAtNodeResult =\n  | {\n      readonly ok: true\n      /** The field's next value (the displayed value with the one prop converted). */\n      readonly value: unknown\n      /**\n       * The position the change wrote, in the value-position grammar: the prop by its\n       * node path where the grammar reaches it, else the coarsest addressable ancestor\n       * — the field (bucket) itself (EC-595: a writer may always emit a coarser path).\n       */\n      readonly path: ValuePath\n      /** The converted prop value when {@link path} is the prop itself (`undefined` — unset). */\n      readonly propValue: unknown\n      readonly exact: boolean\n      readonly problems: readonly WriterFormProblem[]\n    }\n  | { readonly ok: false; readonly message: string }\n\n/**\n * Change ONE component prop, addressed by its node id and prop name, inside a field's\n * value — at ANY depth the traversal reaches: a top-level block, a child in a section's\n * slot, a component embedded in rich text, a component inside an object's rich text or\n * inside another component's prop. The prop's writer form goes through\n * {@link fromWriterForm} with the prop's current value (carry + leash at that position),\n * and the field value is rebuilt by the traversal's writing fold. Nothing else in the\n * value changes — no other prop, no node, no prose.\n */\nexport function fromWriterFormAtNode(\n  field: FieldDef,\n  displayed: unknown,\n  nodeId: string,\n  prop: string,\n  raw: unknown,\n  ctx: WriterFormContext,\n  locale?: string,\n): FromWriterFormAtNodeResult {\n  if (!ctx.lookupManifest) {\n    return {\n      ok: false,\n      message: `Component props cannot be changed here: the project's components are not available to judge \"${prop}\".`,\n    }\n  }\n  const positionCtx = { lookupManifest: ctx.lookupManifest }\n  const root = fieldValuePosition(field, displayed, locale !== undefined ? { locale } : {})\n  const isTarget = (position: ValuePosition) =>\n    position.kind === 'prop' && position.component?.nodeId === nodeId && position.field.name === prop\n  let target: ValuePosition | undefined\n  const declared: string[] = []\n  let componentId: string | undefined\n  walkValuePositions(root, positionCtx, (position) => {\n    if (position.kind !== 'prop' || position.component?.nodeId !== nodeId) return\n    componentId = position.component.componentId\n    declared.push(position.field.name)\n    if (target === undefined && position.field.name === prop) target = position\n  })\n  if (!target) {\n    if (componentId === undefined) {\n      return {\n        ok: false,\n        message: `Component \"${nodeId}\" was not found in \"${field.name}\" (or its component declares no props) — read the document first; component ids come from getDocument.`,\n      }\n    }\n    return {\n      ok: false,\n      message: `Component \"${nodeId}\" (${componentId}) has no prop \"${prop}\" — its props are: ${declared.join(', ')}.`,\n    }\n  }\n  const found = target\n  const { value: converted, problems } = fromWriterForm({ ...found, value: raw }, found.value, ctx)\n  const rebuild = (position: ValuePosition): unknown =>\n    rebuildFromChildren(position, positionCtx, (child) => (isTarget(child) ? converted : rebuild(child)))\n  const value = rebuild(root)\n  return found.exact\n    ? { ok: true, value, path: found.path, propValue: converted, exact: true, problems }\n    : { ok: true, value, path: fieldPath(field.name, locale), propValue: undefined, exact: false, problems }\n}\n\n// --- The text positions (translate) --------------------------------------------------\n\n/** Whether a field-def holds TEXT a translation turns into units: plain text, or a sequence. */\nexport function isTextPosition(position: ValuePosition): boolean {\n  const { type } = position.field\n  return type === 'text' || type === 'richText' || type === 'blocks'\n}\n\nfunction isExcludedBelow(position: ValuePosition): boolean {\n  return position.at.length > 0 && position.field.ai?.exclude === true\n}\n\n/**\n * Every TEXT position at or below `position` (EC-593, ratified 4e — \"translate uses the\n * same traversal\"): a `text` value, and a `richText` / `blocks` sequence (its prose —\n * the sequence's own text — is the caller's to split) together with every text position\n * below it: component text props in a composition and in rich-text embeds, object\n * sub-fields, repeater items, asset placement sub-fields. An `ai.exclude` position (and\n * everything below it) is not text a writer may touch. Depth-first, document order.\n */\nexport function textPositionsOf(\n  position: ValuePosition,\n  ctx: Pick<WriterFormContext, 'lookupManifest'>,\n): ValuePosition[] {\n  const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {}\n  const out: ValuePosition[] = []\n  const visit = (current: ValuePosition): void => {\n    if (isExcludedBelow(current)) return\n    if (isTextPosition(current)) out.push(current)\n    if (current.field.type === 'text') return\n    for (const child of childPositions(current, positionCtx)) visit(child)\n  }\n  visit(position)\n  return out\n}\n\n/**\n * The writing fold over {@link textPositionsOf}: the value at `position` with each text\n * position's value replaced by `replace(textPosition)` — for a sequence, its own value\n * first (its prose), then the text positions below it, read off the REPLACED value (a\n * component keeps its node id, so its props are found again). Every other value — an\n * image, a select, a component's structure — comes back as it was (identity-preserving).\n */\nexport function rebuildTextPositions(\n  position: ValuePosition,\n  ctx: Pick<WriterFormContext, 'lookupManifest'>,\n  replace: (textPosition: ValuePosition) => unknown,\n): unknown {\n  const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {}\n  const rebuild = (current: ValuePosition): unknown => {\n    if (isExcludedBelow(current)) return current.value\n    if (current.field.type === 'text') return replace(current)\n    const value = isTextPosition(current) ? replace(current) : current.value\n    return rebuildFromChildren({ ...current, value }, positionCtx, rebuild)\n  }\n  return rebuild(position)\n}\n\n// --- Stored form → the read (writer) form --------------------------------------------\n\n/**\n * The form a model READS a stored value in — the mirror of {@link fromWriterForm}, so\n * what `getDocument` shows is what `updateFields` takes back: rich text as a markdown\n * string wherever the engine's loss-guarded inverse can express it faithfully (no\n * embedded components, subset-only marks — else the stored `{ version: 2, content }`\n * stays, so nothing echoed back can silently lose structure), at EVERY position: a\n * top-level field, an object sub-field, a repeater item, a component's rich-text prop.\n * Everything else reads as stored (envelopes are writer forms too).\n */\nexport function toWriterForm(\n  position: ValuePosition,\n  ctx: Pick<WriterFormContext, 'lookupManifest'>,\n): unknown {\n  const { value } = position\n  if (value === undefined || value === null) return value\n  const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {}\n  if (fieldTypeOf(position.field).writer === 'markdown' && isSequenceValue(value)) {\n    const parsed = parseRichTextValue(value)\n    const markdown = parsed.ok ? richTextValueToMarkdownProse(parsed.value) : undefined\n    if (markdown !== undefined) return markdown\n  }\n  return rebuildFromChildren(position, positionCtx, (child) => toWriterForm(child, ctx))\n}\n\n/**\n * The components a document holds whose props a writer may change — every component\n * the traversal reaches a DECLARED prop of, in every field of every bucket, at any depth\n * — in first-seen order. What the `getDocument` output's prop catalog lists.\n */\nexport function componentIdsOf(\n  collection: CollectionDef,\n  document: CmsDocument,\n  lookupManifest: PropFieldLookup,\n): string[] {\n  const ids = new Set<string>()\n  const byName = new Map(collection.fields.map((field) => [field.name, field]))\n  const visitBucket = (bucket: FieldValues) => {\n    for (const [name, value] of Object.entries(bucket)) {\n      const field = byName.get(name)\n      if (!field) continue\n      walkValuePositions(fieldValuePosition(field, value), { lookupManifest }, (position) => {\n        if (position.kind === 'prop' && position.component) ids.add(position.component.componentId)\n      })\n    }\n  }\n  visitBucket(document.values)\n  for (const bucket of Object.values(document.localized ?? {})) visitBucket(bucket)\n  return [...ids]\n}\n\n/** {@link toWriterForm} over every field of every bucket of a document. */\nexport function toWriterDocument(\n  collection: CollectionDef,\n  document: CmsDocument,\n  ctx: Pick<WriterFormContext, 'lookupManifest'>,\n): CmsDocument {\n  const byName = new Map(collection.fields.map((field) => [field.name, field]))\n  const mapBucket = (bucket: FieldValues, locale?: string): FieldValues => {\n    let next = bucket\n    for (const [name, value] of Object.entries(bucket)) {\n      const field = byName.get(name)\n      if (!field) continue\n      const read = toWriterForm(fieldValuePosition(field, value, locale !== undefined ? { locale } : {}), ctx)\n      if (read === value) continue\n      if (next === bucket) next = { ...bucket }\n      next[name] = read\n    }\n    return next\n  }\n  const values = mapBucket(document.values)\n  const localized = document.localized\n    ? Object.fromEntries(Object.entries(document.localized).map(([locale, bucket]) => [locale, mapBucket(bucket, locale)]))\n    : undefined\n  return { ...document, values, ...(localized ? { localized } : {}) }\n}\n"]}