@elytracms/studio 0.0.104 → 0.0.105

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

@@ -56,6 +56,34 @@ export interface FromWriterFormResult {
 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;
+/**
+ * **THE position key** (EC-774, Codex r11 F56) — what names ONE position inside one field
+ * value (one `(field, locale)` bucket), so that two positions never share a name: the JSON of
+ * its typed {@link KeySegment}s, built parent → child over core's ONE traversal
+ * (`childPositions`).
+ *
+ * - A component PROP: its enclosing SEQUENCE's key + `['node', id]` + the prop name. Anchored
+ *   by the node — an inline embed a translation moves keeps its key — and scoped to the
+ *   sequence that holds it: one node id in two rich-text values of an object, or in two
+ *   repeater items, is two keys.
+ * - Any other child: its parent's key + its location below the parent (a sub-field by name,
+ *   a repeater item by index, an asset-list entry by asset id and occurrence).
+ *
+ * Injective: a node step cannot alias a name or an index, and no character inside a name can
+ * split it. (The translator used to join locations with `/` and `|` and find a prop by
+ * `lastIndexOf('props')`; a sub-field named `a/b` or a holder named `props` then shared a
+ * name with another position, and both got the second one's translation.)
+ *
+ * Every fold that matches positions across two walks or two values reads it: the translator's
+ * plan and rebuild ({@link textPositionsOf}, {@link rebuildTextPositions}), the locked carry
+ * ({@link withLockedFrom}, {@link lockedChanges}) and a write's own child matching.
+ *
+ * A position under a component node whose id its sequence holds MORE THAN ONCE has no key
+ * (`undefined`): core's writing fold addresses a prop by its node id within one sequence
+ * (`rebuildFromChildren`), so it can never be written apart from its twin's. The translator
+ * refuses it (`unreadable`); the locked carry leaves it as it is.
+ */
+export type PositionKey = string;
 /**
  * One writer-locked position under a value — the TOPMOST locked one on its branch (it stands
  * for everything below it, which is locked too) — with its value (possibly absent: the
@@ -144,6 +172,18 @@ export type FromWriterFormAtNodeResult = {
 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;
+/**
+ * A text position with its {@link PositionKey} below the walk's root (EC-774) — `undefined`
+ * when it has none: it sits under a component node whose id its sequence holds twice, and so
+ * can never be written apart from its twin's.
+ */
+export interface TextPosition extends ValuePosition {
+    readonly key: PositionKey | undefined;
+}
+/** A {@link TextPosition} that has a key — the only kind the writing fold hands back. */
+export interface KeyedTextPosition extends TextPosition {
+    readonly key: PositionKey;
+}
 /**
  * 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 —
@@ -151,17 +191,20 @@ export declare function isTextPosition(position: ValuePosition): boolean;
  * below it: component text props in a composition and in rich-text embeds, object
  * sub-fields, repeater items, asset placement sub-fields. A writer-locked position
  * (EC-716: `ai.exclude` or `form.readOnly`) and everything below it is not text a writer
- * may touch — not a unit, and so never a skip either. Depth-first, document order.
+ * may touch — not a unit, and so never a skip either. Depth-first, document order. Each
+ * carries its {@link PositionKey} (EC-774) — the one name the plan and the rebuild share.
  */
-export declare function textPositionsOf(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>): ValuePosition[];
+export declare function textPositionsOf(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>): TextPosition[];
 /**
  * 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).
+ * component keeps its node id, so its props are found again, under the same key). Every
+ * other value — an image, a select, a component's structure — comes back as it was
+ * (identity-preserving), and so does a text position with no key (EC-774: `replace` never
+ * sees one — it cannot be written apart from its twin).
  */
-export declare function rebuildTextPositions(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>, replace: (textPosition: ValuePosition) => unknown): unknown;
+export declare function rebuildTextPositions(position: ValuePosition, ctx: Pick<WriterFormContext, 'lookupManifest'>, replace: (textPosition: KeyedTextPosition) => 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

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

@@ -150,19 +150,64 @@ function canonicalJson(value) {
         .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 keyString(path) {
+    return JSON.stringify(path);
+}
+/** The node a child is a prop of — a readable prop or one stored as no static member. */
+function propNodeOf(child) {
+    if (isOpaquePosition(child))
+        return child.opaque === 'not-a-static-prop' ? child.component?.nodeId : undefined;
+    return child.kind === 'prop' ? child.component?.nodeId : undefined;
+}
+/** A child's steps below its parent — the relative part of its {@link PositionKey}. */
+function childSegments(parent, child) {
+    const node = propNodeOf(child);
+    if (isOpaquePosition(child)) {
+        return node !== undefined
+            ? [['opaque'], ['node', node], child.declaration.name]
+            : [['opaque'], ...child.at.slice(parent.at.length)];
+    }
+    if (node !== undefined)
+        return [['node', node], child.field.name];
+    const below = child.at.slice(parent.at.length);
+    if (parent.field.type === 'asset' && parent.field.multiple !== false && Array.isArray(parent.value)) {
+        const index = below[0];
+        const entries = parent.value;
+        const id = readAssetId(entries[index]);
+        const occurrence = entries.slice(0, index).filter((entry) => readAssetId(entry) === id).length;
+        return [['asset', id ?? null, occurrence], ...below.slice(1)];
+    }
+    return below;
+}
+/** The node ids a `blocks` / `richText` value holds more than once (none for any other value). */
+function twinNodeIds(position) {
+    const twins = new Set();
+    if (position.field.type !== 'blocks' && position.field.type !== 'richText')
+        return twins;
+    const seen = new Set();
+    for (const { node } of sequenceComponentNodes(position.value))
+        (seen.has(node.id) ? twins : seen).add(node.id);
+    return twins;
+}
+/**
+ * The key of each child of `parent`, whose own key is `parentKey`: `undefined` below a keyless
+ * parent, and for a prop of a node its sequence holds twice (see {@link PositionKey}).
+ */
+function childKeysUnder(parent, parentKey) {
+    if (parentKey === undefined)
+        return () => undefined;
+    const twins = twinNodeIds(parent);
+    return (child) => {
+        const node = propNodeOf(child);
+        return node !== undefined && twins.has(node) ? undefined : [...parentKey, ...childSegments(parent, child)];
+    };
+}
+/**
+ * The key matching a child position of the written value to the current value's, one level
+ * down — the child's {@link PositionKey} steps below its parent.
+ */
 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))}`;
-}
-/** {@link childKey} for a value the traversal cannot read, in its own key space (EC-748). */
-function opaqueChildKey(parent, child) {
-    return child.opaque === 'not-a-static-prop' && child.component
-        ? `opaque:node:${child.component.nodeId}:${child.declaration.name}`
-        : `opaque:at:${JSON.stringify(child.at.slice(parent.at.length))}`;
+    return keyString(childSegments(parent, child));
 }
 /** The model-facing name of an unreadable value: its declaration's name, located when nested. */
 function opaqueSubject(position, root) {
@@ -198,12 +243,9 @@ 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)) {
-            if (isOpaquePosition(child))
-                currentChildren.set(opaqueChildKey(pos, child), child.value);
-            else
-                currentChildren.set(childKey(pos, child), child.value);
-        }
+        const held = { ...pos, value: current };
+        for (const child of childPositions(held, positionCtx))
+            currentChildren.set(childKey(held, child), child.value);
     }
     return rebuildFromChildren(pos, positionCtx, (child) => convert(child, currentChildren.get(childKey(pos, child)), ctx, problems, root, false), 
     // EC-748: a value the model wrote in a shape its declaration does not read — nothing
@@ -211,7 +253,7 @@ function convertChildren(pos, current, ctx, problems, root) {
     // object would reach a locked sub-field through the canonicaliser's unwrap). The stored
     // value echoed back, unchanged, is no write; anything else is a problem, and not written.
     (unreadable) => {
-        const stored = currentChildren.get(opaqueChildKey(pos, unreadable));
+        const stored = currentChildren.get(childKey(pos, unreadable));
         if (stored !== undefined && canonicalJson(stored) === canonicalJson(unreadable.value))
             return unreadable.value;
         problems.push({ at: unreadable.at, code: 'invalid-field-value', message: unreadableWriteMessage(unreadable, root) });
@@ -307,54 +349,40 @@ export function declaredWriterLock(declaration) {
         return 'read-only';
     return undefined;
 }
-/** {@link lockedChildKey} for a value the traversal cannot read — its own key space (EC-748). */
-function lockedOpaqueKey(parent, parentKey, child) {
-    if (child.opaque === 'not-a-static-prop' && child.component) {
-        return `opaque:node:${child.component.nodeId}:${child.declaration.name}`;
-    }
-    return `${parentKey}/opaque:${JSON.stringify(child.at.slice(parent.at.length))}`;
-}
 /**
- * The key matching a child position across two values of one position: a component prop by
- * its NODE (ids are unique in a document and survive a prose edit that shifts indices), an
- * entry of an asset LIST by its asset id and occurrence (the carry's own matching,
- * `carryAssetPlacements` — a reordered gallery keeps each placement), anything else by its
- * location below the parent (a repeater item by index, a sub-field by name).
+ * The locked judge's name for a position: its {@link PositionKey} — a component prop by its
+ * NODE within its sequence (ids survive a prose edit that shifts indices), an asset-list
+ * entry by its asset id and occurrence, anything else by its location below the parent.
+ * EC-774: a position with no key (under a node its sequence holds twice) is named by its
+ * LOCATION, in its own key space: {@link withLockedFrom} never takes it from the other value
+ * (core's write fold would write it into its twin too), and it counts as kept only where the
+ * other value holds the same locked value at the same location — fail closed.
  */
-function lockedChildKey(parent, parentKey, child) {
-    if (child.kind === 'prop' && child.component)
-        return `node:${child.component.nodeId}:${child.field.name}`;
-    const below = child.at.slice(parent.at.length);
-    if (parent.field.type === 'asset' && parent.field.multiple !== false && Array.isArray(parent.value)) {
-        const index = below[0];
-        const entries = parent.value;
-        const id = readAssetId(entries[index]);
-        const occurrence = entries.slice(0, index).filter((entry) => readAssetId(entry) === id).length;
-        return `${parentKey}/asset:${JSON.stringify(id)}#${occurrence}/${JSON.stringify(below.slice(1))}`;
-    }
-    return `${parentKey}/${JSON.stringify(below)}`;
+function lockedKey(key, at) {
+    return key !== undefined ? keyString(key) : JSON.stringify([['twin'], ...at]);
 }
-/** Every topmost writer-locked position at or below `position`, by {@link lockedChildKey}. */
+/** Every topmost writer-locked position at or below `position`, by {@link lockedKey}. */
 function lockedPositionsUnder(position, positionCtx) {
     const out = new Map();
     const visit = (pos, key) => {
         const lock = writerLockOf(pos.field);
         if (lock !== undefined) {
-            out.set(key, { value: pos.value, lock, at: pos.at });
+            out.set(lockedKey(key, pos.at), { value: pos.value, lock, at: pos.at });
             return;
         }
+        const keyOf = childKeysUnder(pos, key);
         for (const child of childPositions(pos, positionCtx)) {
             if (!isOpaquePosition(child)) {
-                visit(child, lockedChildKey(pos, key, child));
+                visit(child, keyOf(child));
                 continue;
             }
             // EC-748: what cannot be read is judged by its declaration — never "nothing locked here".
             const lock = declaredWriterLock(child.declaration);
             if (lock !== undefined)
-                out.set(lockedOpaqueKey(pos, key, child), { value: child.value, lock, at: child.at, opaque: child.opaque });
+                out.set(lockedKey(keyOf(child), child.at), { value: child.value, lock, at: child.at, opaque: child.opaque });
         }
     };
-    visit(position, '');
+    visit(position, []);
     return out;
 }
 /** Whether `entry` sits in `other` unchanged at `key` (a defined value, the same JSON). */
@@ -411,13 +439,20 @@ export function withLockedFrom(position, current, ctx) {
     const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
     const held = lockedPositionsUnder({ ...position, value: current }, positionCtx);
     const rebuild = (pos, key) => {
-        if (writerLockOf(pos.field) !== undefined)
-            return held.has(key) ? held.get(key).value : pos.value;
+        if (writerLockOf(pos.field) !== undefined) {
+            // EC-774: a position with no key (under a node its sequence holds twice) keeps its own
+            // value — taken from `current`, core's write fold would write it into its twin too.
+            if (key === undefined)
+                return pos.value;
+            const name = keyString(key);
+            return held.has(name) ? held.get(name).value : pos.value;
+        }
         // EC-748: a value `position` holds unreadably is kept as it is — nothing below it can be
         // matched by key — and {@link lockedChanges} counts it lost unless `current` holds it too.
-        return rebuildFromChildren(pos, positionCtx, (child) => rebuild(child, lockedChildKey(pos, key, child)), (unreadable) => unreadable.value);
+        const keyOf = childKeysUnder(pos, key);
+        return rebuildFromChildren(pos, positionCtx, (child) => rebuild(child, keyOf(child)), (unreadable) => unreadable.value);
     };
-    return rebuild(position, '');
+    return rebuild(position, []);
 }
 /**
  * The locked values a write from `position.value` (the CURRENT value) to `next` would lose or
@@ -625,6 +660,10 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
     const root = fieldValuePosition(field, displayed, locale !== undefined ? { locale } : {});
     const isTarget = (position) => position.kind === 'prop' && position.component?.nodeId === nodeId && position.field.name === prop;
     let target;
+    // Codex r12 F58: every position the address names. One node id may sit in two sequences of one
+    // field (ids are checked per `blocks` value), and the rebuild below replaces EVERY match — so an
+    // address naming two positions is refused, never written (the node-id scope is EC-776's).
+    let targets = 0;
     // EC-716: the lock the target sits under — its own, or the nearest locked ancestor's
     // (a component embedded in a read-only rich-text prop, a prop of a locked object…).
     let targetLock;
@@ -637,6 +676,8 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
         if (position.kind === 'prop' && position.component?.nodeId === nodeId) {
             componentId = position.component.componentId;
             declared.push(position.field.name);
+            if (position.field.name === prop)
+                targets++;
             if (target === undefined && position.field.name === prop) {
                 target = position;
                 targetLock = lock;
@@ -659,6 +700,12 @@ export function fromWriterFormAtNode(field, displayed, nodeId, prop, raw, ctx, l
         }
     };
     visit(root, undefined);
+    if (targets > 1) {
+        return {
+            ok: false,
+            message: `Component "${nodeId}" (${componentId}) occurs in ${targets} positions of "${field.name}" (one id in separate sequences), so this address does not name one of them; the assistant cannot change prop "${prop}" here. Change it in the editor.`,
+        };
+    }
     if (!target && unreadableTarget) {
         return {
             ok: false,
@@ -710,46 +757,53 @@ function isLocked(position) {
  * below it: component text props in a composition and in rich-text embeds, object
  * sub-fields, repeater items, asset placement sub-fields. A writer-locked position
  * (EC-716: `ai.exclude` or `form.readOnly`) and everything below it is not text a writer
- * may touch — not a unit, and so never a skip either. Depth-first, document order.
+ * may touch — not a unit, and so never a skip either. Depth-first, document order. Each
+ * carries its {@link PositionKey} (EC-774) — the one name the plan and the rebuild share.
  */
 export function textPositionsOf(position, ctx) {
     const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
     const out = [];
-    const visit = (current) => {
+    const visit = (current, key) => {
         if (isLocked(current))
             return;
         if (isTextPosition(current))
-            out.push(current);
+            out.push({ ...current, key: key && keyString(key) });
         if (current.field.type === 'text')
             return;
         // EC-748: a value the traversal cannot read yields no unit — its text cannot be found
         // (and translate skips a bucket where one may hold locked content: `lockedChanges`).
+        const keyOf = childKeysUnder(current, key);
         for (const child of childPositions(current, positionCtx))
             if (!isOpaquePosition(child))
-                visit(child);
+                visit(child, keyOf(child));
     };
-    visit(position);
+    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).
+ * component keeps its node id, so its props are found again, under the same key). Every
+ * other value — an image, a select, a component's structure — comes back as it was
+ * (identity-preserving), and so does a text position with no key (EC-774: `replace` never
+ * sees one — it cannot be written apart from its twin).
  */
 export function rebuildTextPositions(position, ctx, replace) {
     const positionCtx = ctx.lookupManifest ? { lookupManifest: ctx.lookupManifest } : {};
-    const rebuild = (current) => {
+    const rebuild = (current, key) => {
         if (isLocked(current))
             return current.value;
+        const keyed = key && { ...current, key: keyString(key) };
         if (current.field.type === 'text')
-            return replace(current);
-        const value = isTextPosition(current) ? replace(current) : current.value;
+            return keyed ? replace(keyed) : current.value;
+        const value = keyed && isTextPosition(current) ? replace(keyed) : current.value;
+        const replaced = { ...current, value };
+        const keyOf = childKeysUnder(replaced, key);
         // EC-748: an unreadable value comes back as it was (it held no unit).
-        return rebuildFromChildren({ ...current, value }, positionCtx, rebuild, (unreadable) => unreadable.value);
+        return rebuildFromChildren(replaced, positionCtx, (child) => rebuild(child, keyOf(child)), (unreadable) => unreadable.value);
     };
-    return rebuild(position);
+    return rebuild(position, []);
 }
 // --- Stored form → the read (writer) form --------------------------------------------
 /**