@superdoc/sdk 2.23.0-next.8 → 2.23.0

package/dist/agent/actions.d.ts

@@ -491,6 +491,19 @@ export type AddHyperlinkArgs = {
     url: string;
     tooltip?: string;
 };
+export declare function typedMarkerPrefixOf(text: string): {
+    prefix: string;
+    marker: string;
+} | null;
+export type MarkerShape = {
+    wrapper: 'paren' | 'period' | 'close';
+    kind: 'digit' | 'lower-roman' | 'lower-alpha' | 'upper-roman' | 'upper-alpha';
+};
+export declare function markerShapeOf(text: string): MarkerShape | null;
+export declare function typedCaptionSpanOf(text: string, delimiter?: string): {
+    start: number;
+    end: number;
+} | null;
 export declare function superdocPerformAction(doc: BoundDocApi, args: unknown): Promise<AgentReceipt>;
 export declare const ACTION_NAMES_LIST: readonly ActionName[];
 export {};

package/dist/agent/actions.js

@@ -7,6 +7,7 @@ import { runSuperdocListTransformWorkflow } from '../action-primitives/tools/lis
 import { runSuperdocStructureInsertWorkflow } from '../action-primitives/tools/structure-insert.js';
 import { runSuperdocTextTransformWorkflow } from '../action-primitives/tools/text-transform.js';
 import { buildDocumentSnapshot, buildMutationSnapshot, matchRunsForBlock, MutationSnapshotError, resolveSnapshotSelector, } from './doc-snapshot.js';
+import { isRecord } from '../guards.js';
 export const ACTION_DEFINITIONS = actionDescriptors;
 function projectActionDefinitions(project) {
     return Object.fromEntries(Object.entries(ACTION_DEFINITIONS).map(([name, definition]) => [name, project(definition)]));
@@ -69,9 +70,6 @@ export function getActionDispositions() {
 export function isActionName(value) {
     return typeof value === 'string' && ACTION_NAMES.includes(value);
 }
-function isRecord(value) {
-    return value != null && typeof value === 'object' && !Array.isArray(value);
-}
 /** The message to put in a receipt when something best-effort did not happen. */
 function reasonOf(err) {
     return err instanceof Error ? err.message : String(err);
@@ -877,6 +875,7 @@ async function styleTableCells(doc, cells, changeMode) {
     await applyItemStyling(doc, nodeIds, specs, changeMode);
     return styled.length;
 }
+const TYPED_SIBLING_WINDOW = 20;
 async function runInsertParagraphs(doc, args, formatArgs) {
     const context = new ExecutionContext(doc, { evidence: args.evidence, selectors: placementSelectors(args.placement) });
     try {
@@ -889,7 +888,7 @@ async function runInsertParagraphs(doc, args, formatArgs) {
                 kind: 'placement',
                 at: placement.kind === 'documentStart' ? 'document_start' : 'document_end',
             });
-        const preRows = pre.complete ? await listBlockRows(doc) : anchor ? [anchor] : [];
+        let preRows = pre.complete ? await listBlockRows(doc) : anchor ? [anchor] : [];
         let currentPlacement = placement;
         const nodeIds = [];
         const specs = [];
@@ -929,6 +928,16 @@ async function runInsertParagraphs(doc, args, formatArgs) {
             if (!pre.complete) {
                 const created = await post.page({ nodeIds, limit: Math.max(nodeIds.length, 1) });
                 localRows = [...(anchor ? [anchor] : []), ...created].sort((a, b) => a.ordinal - b.ordinal);
+                const placed = anchor && texts.some((text) => typedMarkerPrefixOf(text)) ? await post.block(anchor.nodeId) : null;
+                if (placed) {
+                    const span = TYPED_SIBLING_WINDOW + nodeIds.length;
+                    const window = await post.page({ offset: Math.max(0, placed.ordinal - 1 - span), limit: 2 * span + 1 });
+                    const createdIds = new Set(nodeIds);
+                    if (nodeIds.every((id) => window.some((row) => row.nodeId === id))) {
+                        preRows = window.filter((row) => !createdIds.has(row.nodeId));
+                        localRows = window;
+                    }
+                }
             }
             const count = context.executedOperations.length;
             formatted = await matchInsertedBlockFormatting(context.document, preRows, context.receipt('insert_paragraphs', []), formatArgs, localRows);
@@ -1278,6 +1287,172 @@ async function runDeleteText(doc, args) {
         return failedReceipt('delete_text', err, pre);
     }
 }
+const CONJUNCTION_TAIL = /[;,]\s*(and|or)\s*$/i;
+const ITEM_ENDING = /(?:[;,]\s*(?:and|or)|[.;,:])\s*$/i;
+const ITEM_CLOSERS = /["'”’)\]]+$/;
+function enumerationSlotOf(block) {
+    const numbering = blockNumbering(block);
+    const path = numbering?.path;
+    if (Array.isArray(path) && path.length > 0) {
+        return { key: `scheme:${path.slice(0, -1).join('.')}:${path.length}`, depth: path.length, typed: null };
+    }
+    const markerShape = numbering?.marker ? markerShapeOf(numbering.marker) : null;
+    if (markerShape)
+        return { key: `scheme-marker:${markerShape.wrapper}:${markerShape.kind}`, depth: null, typed: null };
+    const text = block.text || block.textPreview || '';
+    const typedMarker = typedMarkerPrefixOf(text)?.marker;
+    const typedShape = typedMarker ? markerShapeOf(text) : null;
+    if (!typedMarker || !typedShape)
+        return null;
+    const parent = typedShape.kind === 'digit' ? typedDigitParentOf(typedMarker) : '';
+    return { key: `typed:${typedShape.wrapper}:${typedShape.kind}:${parent}`, depth: null, typed: typedShape };
+}
+function typedDigitParentOf(marker) {
+    const segments = marker.replace(/^\(/, '').replace(/[.)]$/, '').split('.');
+    return `${segments.length}:${segments.slice(0, -1).join('.')}`;
+}
+const ROMAN_DIGITS = { i: 1, v: 5, x: 10 };
+function markerValueOf(token, shape) {
+    const core = token.replace(/^\(/, '').replace(/[.)]$/, '').toLowerCase();
+    if (shape.kind === 'digit')
+        return Number(core.split('.').pop());
+    if (shape.kind === 'lower-roman' || shape.kind === 'upper-roman') {
+        let total = 0;
+        for (let i = 0; i < core.length; i += 1) {
+            const value = ROMAN_DIGITS[core[i]] ?? 0;
+            total += value < (ROMAN_DIGITS[core[i + 1] ?? ''] ?? 0) ? -value : value;
+        }
+        return total;
+    }
+    const letter = core.charCodeAt(0) - 96;
+    return core.length === 1 ? letter : 26 * (core.length - 1) + letter;
+}
+function enumerationRunOf(blocks, index, slot, textOf) {
+    const typed = slot.typed;
+    const valueOf = (block) => {
+        if (!typed) {
+            const path = blockNumbering(block)?.path;
+            return Array.isArray(path) && path.length > 0 ? Number(path[path.length - 1]) : null;
+        }
+        const token = typed ? typedMarkerPrefixOf(textOf(block))?.marker : null;
+        return token && typed ? markerValueOf(token, typed) : null;
+    };
+    const walk = (step) => {
+        const found = [];
+        let edge = valueOf(blocks[index]);
+        let crossed = false;
+        for (let i = index + step; i >= 0 && i < blocks.length; i += step) {
+            const block = blocks[i];
+            if (textOf(block).length === 0)
+                continue;
+            const other = enumerationSlotOf(block);
+            const continuesAsLetter = typed != null &&
+                other?.typed != null &&
+                markerShapeFits(typed, other.typed) &&
+                edge != null &&
+                valueOf(block) === edge + step;
+            if (other?.key === slot.key || continuesAsLetter) {
+                const value = valueOf(block);
+                if (value != null && edge != null) {
+                    const advance = (value - edge) * step;
+                    if (advance <= 0 || ((crossed || !typed) && advance !== 1))
+                        break;
+                }
+                found.push(block);
+                edge = value;
+                crossed = false;
+                continue;
+            }
+            if (typed && other?.typed) {
+                if (step === -1 && edge != null) {
+                    const prefix = typedMarkerPrefixOf(textOf(block)).prefix;
+                    const inline = new RegExp(String.raw `(?:^|\s)(${TYPED_MARKER_TOKEN}) `).exec(textOf(block).slice(prefix.length));
+                    const inlineShape = inline ? markerShapeOf(inline[1]) : null;
+                    if (inline && sameMarkerShape(inlineShape, typed) && markerValueOf(inline[1], typed) === edge - 1) {
+                        found.push(block);
+                        break;
+                    }
+                }
+                crossed = true;
+                continue;
+            }
+            if (slot.depth != null && other?.depth != null && other.depth > slot.depth)
+                continue;
+            break;
+        }
+        return found;
+    };
+    return [...walk(-1).reverse(), blocks[index], ...walk(1)];
+}
+function listPunctuationAfterDelete(blocks, deletedIds) {
+    const textOf = (block) => (block.text || (block.textPreview ?? '').replace(/…\s*$/, '')).trimEnd();
+    const endingOf = (block) => {
+        const text = textOf(block);
+        const closers = ITEM_CLOSERS.exec(text)?.[0] ?? '';
+        const body = text.slice(0, text.length - closers.length).trimEnd();
+        const ending = ITEM_ENDING.exec(body);
+        return {
+            core: ending?.[0].trim() ?? '',
+            real: ending ? `${ending[0].trim()}${closers}` : closers,
+            closers,
+            conjunction: CONJUNCTION_TAIL.exec(body)?.[0].trim() ?? null,
+        };
+    };
+    const quote = (block) => {
+        const text = textOf(block);
+        return JSON.stringify(text.length > 40 ? `...${text.slice(-40)}` : text);
+    };
+    const change = (block, to) => {
+        const ending = endingOf(block);
+        return `change the ending of ${quote(block)} (nodeId ${block.nodeId}) from "${ending.real}" to "${to}${ending.closers}"`;
+    };
+    const entries = [];
+    const covered = new Set();
+    blocks.forEach((block, index) => {
+        if (!deletedIds.has(block.nodeId) || covered.has(block.nodeId))
+            return;
+        const slot = enumerationSlotOf(block);
+        if (!slot)
+            return;
+        const run = enumerationRunOf(blocks, index, slot, textOf);
+        for (const item of run)
+            covered.add(item.nodeId);
+        const survivors = run.filter((item) => !deletedIds.has(item.nodeId));
+        if (survivors.length === 0)
+            return;
+        const last = survivors[survivors.length - 1];
+        const penultimate = survivors.length >= 2 ? survivors[survivors.length - 2] : undefined;
+        const originalPenultimate = run[run.length - 2];
+        if (run.some((item) => item !== originalPenultimate && endingOf(item).conjunction))
+            return;
+        const runEnd = run[run.length - 1];
+        if (!deletedIds.has(runEnd.nodeId))
+            return;
+        const tail = originalPenultimate ? endingOf(originalPenultimate).conjunction : null;
+        const separator = tail ? tail.charAt(0) : ';';
+        const closing = endingOf(runEnd).core || '.';
+        const lastEnding = endingOf(last);
+        if (lastEnding.core === ':')
+            return;
+        const needsClose = lastEnding.core !== closing && (lastEnding.conjunction != null || lastEnding.core === separator);
+        const needsTail = penultimate != null && tail != null && endingOf(penultimate).core !== ':' && !endingOf(penultimate).conjunction;
+        if (!needsClose && !(needsTail && lastEnding.core !== closing))
+            return;
+        const edits = [
+            `end ${quote(last)} (nodeId ${last.nodeId}) with "${closing}${lastEnding.closers}" instead of "${lastEnding.real}"`,
+        ];
+        if (needsTail)
+            edits.push(change(penultimate, tail));
+        entries.push({
+            deleted: runEnd.nodeId,
+            lastItem: last.nodeId,
+            lastItemEnds: lastEnding.real,
+            ...(penultimate ? { penultimate: penultimate.nodeId, penultimateEnds: endingOf(penultimate).real } : {}),
+            suggestion: `The run now ends at ${quote(last)}: ${edits.join(', and ')}, using replace_text.`,
+        });
+    });
+    return entries;
+}
 /** Block node types `doc.blocks.delete` removes as a whole paragraph-shaped block. */
 const DELETABLE_BLOCK_NODE_TYPES = new Set(['paragraph', 'heading', 'listItem']);
 /**
@@ -1447,6 +1622,11 @@ async function runDeleteBlocks(doc, args) {
         // an error, so the `errors.length` term still catches a short request.
         const allApplied = deleted.length === targets.length && errors.length === 0;
         const verified = verification.every((v) => v.passed);
+        let listPunctuation = [];
+        try {
+            listPunctuation = listPunctuationAfterDelete(pre.blocks, new Set(deleted.map((entry) => entry.nodeId)));
+        }
+        catch { }
         return {
             status: !verified || deleted.length === 0 ? 'failed' : allApplied ? 'ok' : 'partial',
             intent: `delete_blocks: ${deleted.length} block(s)`,
@@ -1456,6 +1636,7 @@ async function runDeleteBlocks(doc, args) {
             executedOperations,
             verification,
             deletedBlocks: deleted,
+            ...(listPunctuation.length > 0 ? { listPunctuation } : {}),
             ...(errors.length ? { errors } : {}),
             ...(errors.length
                 ? { nextStep: 'Re-inspect the document and retry the selectors that did not resolve to one block.' }
@@ -4400,8 +4581,9 @@ async function runScopedReplaceUnchecked(doc, args) {
             occurrences: spans.length,
             ...(edit.occurrence != null ? { occurrence: edit.occurrence } : {}),
         });
-        for (const span of spans)
-            allSpans.push({ ...span, replace: edit.replace, find: edit.find });
+        for (const span of spans) {
+            allSpans.push({ ...span, replace: edit.replace, find: edit.find, editIndex: perEdit.length - 1 });
+        }
     }
     const appliedEdits = perEdit.filter((e) => e.occurrences > 0);
     const skippedEdits = perEdit.filter((e) => e.occurrences === 0);
@@ -4438,6 +4620,23 @@ async function runScopedReplaceUnchecked(doc, args) {
         planned.push(span);
         lastEnd = span.end;
     }
+    planned.forEach((span, at) => {
+        if (span.replace.trim().length > 0)
+            return;
+        const text = block.text;
+        if (text.charAt(span.start - 1) !== ' ' || text.charAt(span.end) !== ' ')
+            return;
+        if (text.charAt(span.start - 2) === ' ' || text.charAt(span.end + 1) === ' ')
+            return;
+        if (/[.!?]["'\u201d\u2019)\]]*$/.test(text.slice(0, span.start - 1)))
+            return;
+        if ((planned[at + 1]?.start ?? Infinity) <= span.end || (planned[at - 1]?.end ?? -1) >= span.start - 1)
+            return;
+        if (span.replace.length > 0)
+            span.start -= 1;
+        span.end += 1;
+        perEdit[span.editIndex].collapsedSpace = true;
+    });
     // The block text once every planned span is replaced: the whole-block
     // rewrite writes it, and exact-target writes must produce it.
     const expected = planned.reduceRight((text, span) => text.slice(0, span.start) + span.replace + text.slice(span.end), block.text);
@@ -4724,6 +4923,8 @@ function leadInShapeOf(blockText, labelText, quote) {
 }
 /** The span of `text` that carries the label look, or null when it has none. */
 function leadInSpanOf(text, shape) {
+    if (shape.kind === 'typed')
+        return typedCaptionSpanOf(text, shape.delimiter);
     if (shape.kind === 'word') {
         // Only the SAME token inherits the look — "WHEREAS the Parties…" does,
         // "The Parties further agree…" does not (no guessing a label there).
@@ -4758,6 +4959,81 @@ function leadInSpanOf(text, shape) {
     const end = leadInEndOf(text, shape.delimiter);
     return end == null ? null : { start: 0, end };
 }
+const TYPED_MARKER_CORE = String.raw `(?:\d{1,3}(?:\.\d{1,3})*|[ivx]{1,6}|[IVX]{1,6}|[a-z]{1,2}|[A-Z])`;
+const TYPED_MARKER_TOKEN = String.raw `(?:\(${TYPED_MARKER_CORE}\)|${TYPED_MARKER_CORE}[.)])`;
+const TYPED_MARKER_PREFIX = new RegExp(String.raw `^[ \t]*(${TYPED_MARKER_TOKEN})\t[\t ]*`);
+const LEADING_MARKER_TOKEN = new RegExp(String.raw `^\s*(${TYPED_MARKER_TOKEN})(?=\s|$)`);
+export function typedMarkerPrefixOf(text) {
+    const match = TYPED_MARKER_PREFIX.exec(text);
+    return match ? { prefix: match[0], marker: match[1] } : null;
+}
+export function markerShapeOf(text) {
+    const match = LEADING_MARKER_TOKEN.exec(text);
+    if (!match)
+        return null;
+    const token = match[1];
+    const wrapper = token.startsWith('(') ? 'paren' : token.endsWith('.') ? 'period' : 'close';
+    const core = token.replace(/^\(/, '').replace(/[.)]$/, '');
+    let kind;
+    if (/^\d/.test(core))
+        kind = 'digit';
+    else if (/^[ivx]+$/.test(core))
+        kind = 'lower-roman';
+    else if (/^[IVX]+$/.test(core))
+        kind = 'upper-roman';
+    else if (/^[a-z]+$/.test(core))
+        kind = 'lower-alpha';
+    else if (/^[A-Z]+$/.test(core))
+        kind = 'upper-alpha';
+    else
+        return null;
+    return { wrapper, kind };
+}
+function sameMarkerShape(a, b) {
+    return a != null && b != null && a.wrapper === b.wrapper && a.kind === b.kind;
+}
+function markerShapeFits(reference, created) {
+    if (!reference || reference.wrapper !== created.wrapper)
+        return false;
+    if (reference.kind === created.kind)
+        return true;
+    return ((created.kind === 'lower-roman' && reference.kind === 'lower-alpha') ||
+        (created.kind === 'upper-roman' && reference.kind === 'upper-alpha'));
+}
+function continuesAlphabet(referenceText, createdText, referenceBefore) {
+    const letterOf = (text) => /^[a-zA-Z]$/.exec(LEADING_MARKER_TOKEN.exec(text)?.[1]?.replace(/[().]/g, '') ?? '')?.[0];
+    const reference = letterOf(referenceText);
+    const created = letterOf(createdText);
+    return (reference != null &&
+        created != null &&
+        created.charCodeAt(0) - reference.charCodeAt(0) === (referenceBefore ? 1 : -1));
+}
+const TYPED_CAPTION_MAX_CHARS = 60;
+function isTitleLike(caption) {
+    const words = caption.match(/\p{L}+/gu) ?? [];
+    const capitalised = words.filter((word) => /^\p{Lu}/u.test(word)).length;
+    return (words.length > 0 &&
+        words.every((word) => word.length < 4 || /^\p{Lu}/u.test(word)) &&
+        capitalised * 2 >= words.length);
+}
+export function typedCaptionSpanOf(text, delimiter = '.') {
+    const typed = typedMarkerPrefixOf(text);
+    const mark = delimiter.trim();
+    if (!typed || !mark)
+        return null;
+    const start = typed.prefix.length;
+    for (let at = text.indexOf(mark, start); at >= 0; at = text.indexOf(mark, at + 1)) {
+        const end = at + mark.length;
+        if (end - start > TYPED_CAPTION_MAX_CHARS)
+            return null;
+        if (at === start || !/\s/.test(text.charAt(end)))
+            continue;
+        if (!isTitleLike(text.slice(start, at)))
+            return null;
+        return text.slice(end).trim().length > 0 ? { start, end } : null;
+    }
+    return null;
+}
 /**
  * Cut `text` at `end` without splitting a surrogate pair: half an emoji is not
  * document text, and `query.match` finds nothing when handed a lone surrogate —
@@ -4834,7 +5110,10 @@ async function listItemRunPattern(doc, text, blockId) {
     // Window: through the label's delimiter plus enough of the sentence to sample
     // it, or a plain head when the item carries no label at all.
     const delimiterAt = leadInEndOf(text);
-    const windowEnd = delimiterAt != null ? delimiterAt + LEAD_IN_BODY_SAMPLE_CHARS : LEAD_IN_BODY_SAMPLE_CHARS;
+    let windowEnd = delimiterAt != null ? delimiterAt + LEAD_IN_BODY_SAMPLE_CHARS : LEAD_IN_BODY_SAMPLE_CHARS;
+    const typedCaption = typedCaptionSpanOf(text);
+    if (typedCaption)
+        windowEnd = Math.max(windowEnd, typedCaption.end + LEAD_IN_BODY_SAMPLE_CHARS);
     const pattern = sliceWholeChars(text, windowEnd);
     const result = asRecord(await queryFn({ select: { type: 'text', pattern } }));
     const items = Array.isArray(result?.items) ? result.items : [];
@@ -4848,6 +5127,9 @@ async function listItemRunPattern(doc, text, blockId) {
             const runs = (Array.isArray(rec?.runs) ? rec.runs : []).filter((r) => runTextOf(r).length > 0);
             if (runs.length === 0)
                 continue;
+            const typedLead = typedPrefixLabelOf(runs, runTextOf);
+            if (typedLead)
+                return typedLead;
             const blockText = asString(rec?.text, '') ?? '';
             // A quoted defined term keeps its opening quote in a run of its own —
             // `"` + **Deliverables** + `" means …` — so the label is the SECOND run
@@ -4883,6 +5165,59 @@ async function listItemRunPattern(doc, text, blockId) {
     }
     return null;
 }
+function typedPrefixLabelOf(runs, runTextOf) {
+    const typed = typedMarkerPrefixOf(runs.map(runTextOf).join(''));
+    if (!typed)
+        return null;
+    const markerEnd = typed.prefix.indexOf(typed.marker) + typed.marker.length;
+    let covered = 0;
+    let labelIndex = 0;
+    while (labelIndex < runs.length && covered + runTextOf(runs[labelIndex]).length <= typed.prefix.length) {
+        covered += runTextOf(runs[labelIndex]).length;
+        labelIndex += 1;
+    }
+    if (covered < markerEnd || labelIndex + 1 >= runs.length)
+        return null;
+    const underlined = (run) => asRecord(asRecord(asRecord(run)?.styles)?.effective)?.underline === true;
+    const emphasisOf = (run) => {
+        const style = matchRunStyle(run);
+        return `${style.bold}/${style.italic}/${underlined(run)}`;
+    };
+    const label = runs[labelIndex];
+    if (emphasisOf(label) === 'false/false/false')
+        return null;
+    const isBlank = (run) => runTextOf(run).trim().length === 0;
+    const continuesLabel = (index) => {
+        if (emphasisOf(runs[index]) === emphasisOf(label))
+            return true;
+        let next = index;
+        while (next < runs.length && isBlank(runs[next]))
+            next += 1;
+        return next > index && next < runs.length && emphasisOf(runs[next]) === emphasisOf(label);
+    };
+    let bodyIndex = labelIndex + 1;
+    while (bodyIndex < runs.length && continuesLabel(bodyIndex))
+        bodyIndex += 1;
+    while (bodyIndex < runs.length - 1 && isBlank(runs[bodyIndex]))
+        bodyIndex += 1;
+    if (bodyIndex >= runs.length)
+        return null;
+    const labelText = runs.slice(labelIndex, bodyIndex).map(runTextOf).join('').trim();
+    if (labelText.length === 0 || labelText.length > LEAD_IN_MAX_CHARS)
+        return null;
+    const delimiter = ['.', ...LEAD_IN_DELIMITERS.map((d) => d.trim())].find((d) => labelText.endsWith(d) && labelText.length > d.length);
+    if (!delimiter)
+        return null;
+    const body = runs[bodyIndex];
+    const leadStyle = matchRunStyle(label);
+    const bodyStyle = matchRunStyle(body);
+    const leadUnderline = underlined(label);
+    const bodyUnderline = underlined(body);
+    const look = inlineFromMatchStyle(leadStyle, bodyStyle);
+    if (leadUnderline || bodyUnderline)
+        look.underline = leadUnderline;
+    return { body: inlineFromMatchStyle(bodyStyle), lead: { look, shape: { kind: 'typed', delimiter } } };
+}
 /**
  * Pull a paragraph's direct indentation out of a `getNodeById` payload and
  * convert it to the twips that `format.paragraph.setIndentation` expects.
@@ -5761,6 +6096,7 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
         }
         if (!reference)
             return null;
+        reference = typedShapeReference(postBlocks, preIds, created, createdIndex, createdText, reference, compatibleHeading);
         const applied = {};
         // Numbering: when the reference participates in a numbering scheme and
         // the new block does not, attach it to the same sequence — this is what
@@ -5786,7 +6122,9 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
             }
         }
         if (reference.styleId && reference.styleId !== created.styleId) {
-            const setStyleFn = maybeMethod(doc, ['styles', 'paragraph', 'setStyle']);
+            const keepRunMarks = !allowLeadPattern;
+            const setStyleFn = (keepRunMarks ? maybeMethod(doc, ['styles', 'paragraph', 'setStyleRef']) : null) ??
+                maybeMethod(doc, ['styles', 'paragraph', 'setStyle']);
             if (setStyleFn) {
                 const target = { kind: 'block', nodeType: created.nodeType, nodeId: created.nodeId };
                 let canCopyStyle = true;
@@ -5889,6 +6227,42 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
         return { matchedSibling: null, skipped: reasonOf(err) };
     }
 }
+function typedShapeReference(postBlocks, preIds, created, createdIndex, createdText, reference, compatible) {
+    const typed = createdText ? typedMarkerPrefixOf(createdText) : null;
+    if (!typed || createdText.slice(typed.prefix.length).trim().length === 0)
+        return reference;
+    const shape = markerShapeOf(createdText);
+    const referenceShape = markerShapeOf(reference.textPreview ?? '');
+    if (!shape || sameMarkerShape(referenceShape, shape))
+        return reference;
+    const usable = (row) => !!row && preIds.has(row.nodeId) && row.nodeType === created.nodeType && !row.isEmpty && compatible(row);
+    const before = postBlocks.slice(0, createdIndex).reverse().find(usable);
+    const after = postBlocks.slice(createdIndex + 1).find(usable);
+    const continued = [reference, before, after].find((row) => !!row &&
+        markerShapeFits(markerShapeOf(row.textPreview ?? ''), shape) &&
+        continuesAlphabet(row.textPreview ?? '', createdText, postBlocks.findIndex((b) => b.nodeId === row.nodeId) < createdIndex));
+    if (continued)
+        return continued;
+    const candidate = (row) => {
+        if (!usable(row))
+            return null;
+        const preview = row.textPreview ?? '';
+        return typedMarkerPrefixOf(preview) ? markerShapeOf(preview) : null;
+    };
+    const nearest = (accepts) => {
+        for (let distance = 1; distance < postBlocks.length; distance += 1) {
+            for (const index of [createdIndex - distance, createdIndex + distance]) {
+                const row = postBlocks[index];
+                if (index >= 0 && accepts(candidate(row)))
+                    return row;
+            }
+        }
+        return null;
+    };
+    return (nearest((rowShape) => sameMarkerShape(rowShape, shape)) ??
+        nearest((rowShape) => markerShapeFits(rowShape, shape)) ??
+        reference);
+}
 /** A lead-in marker token like "(m)", "1.", "a)", "(iv)" at the start of clause text. */
 const LEAD_MARKER_PATTERN = /^\(?(?:[a-zA-Z]{1,3}|\d{1,3})[).:\]]/;
 /**
@@ -6019,7 +6393,8 @@ async function matchBlockRunPattern(doc, reference, created, createdText) {
         const span = leadInSpanOf(fullText, pattern.lead.shape);
         // A uniform reference has no body look and no delimiter of its own: its look
         // belongs to the whole created block, not to a label span inside it.
-        const range = span ?? (Object.keys(pattern.body).length === 0 ? { start: 0, end } : null);
+        const range = span ??
+            (Object.keys(pattern.body).length === 0 && pattern.lead.shape.kind !== 'typed' ? { start: 0, end } : null);
         if (range && (await applyInlineQuiet(formatFn, { blockId: created.nodeId, ...range, inline: pattern.lead.look }))) {
             applied.lead = { ...pattern.lead.look, range: [range.start, range.end] };
         }
@@ -6046,7 +6421,7 @@ async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, avail
         // When the caller styled any entry explicitly (runs/marks), it took
         // ownership of intra-paragraph formatting — the automatic lead-marker
         // pattern pass must not fight it.
-        const rawTexts = Array.isArray(args?.texts) ? args.texts : [];
+        const rawTexts = Array.isArray(args?.texts) ? args.texts : args?.text != null ? [args.text] : [];
         const hasExplicitStyling = rawTexts.some((entry) => isRecord(entry) && (Array.isArray(entry.runs) || entry.marks != null));
         const insertedTexts = rawTexts.map((entry) => {
             if (typeof entry === 'string')
@@ -6247,7 +6622,15 @@ async function runAttachNumbering(doc, args) {
             errors: [
                 {
                     code: 'TARGET_NOT_FOUND',
-                    message: `no block renders marker ${JSON.stringify(likeMarker)}. Available: ${available.join(' ')}`,
+                    message: available.length > 0
+                        ? `no block renders marker ${JSON.stringify(likeMarker)}. Available: ${available.join(' ')}`
+                        : rows.some((r) => typedMarkerPrefixOf(r.textPreview ?? '') != null)
+                            ? `no block renders marker ${JSON.stringify(likeMarker)}: this document has no numbering scheme; its clause numbers are typed text. ` +
+                                `Copy the sibling's typed prefix (tab, next number, tab) into the paragraph text with insert_paragraphs or replace_text, ` +
+                                `then renumber the following typed markers with replace_text.`
+                            : `no block renders marker ${JSON.stringify(likeMarker)}: no block in this document carries numbering. ` +
+                                `To add a paragraph that matches its neighbours use insert_paragraphs next to them; ` +
+                                `to start a numbered list use append_list or convert_list.`,
                     recovery: { kind: 'reinspect' },
                 },
             ],

package/dist/agent/runtime.cjs

@@ -7,6 +7,7 @@ var errors = require('../runtime/errors.cjs');
 var ir = require('./ir.cjs');
 var docSnapshot = require('./doc-snapshot.cjs');
 var operationCatalog = require('./operation-catalog.cjs');
+var guards = require('../guards.cjs');
 
 const RESERVED_ARG_KEYS = new Set(['sessionId', 'doc']);
 function ensureKnownOperation(operationId) {
@@ -30,11 +31,8 @@ function ensureClean(args) {
     }
     return args;
 }
-function isRecord(value) {
-    return value != null && typeof value === 'object' && !Array.isArray(value);
-}
 function isRefToken(value) {
-    return (isRecord(value) &&
+    return (guards.isRecord(value) &&
         typeof value.ref === 'string' &&
         (value.path == null || typeof value.path === 'string') &&
         Object.keys(value).every((key) => key === 'ref' || key === 'path'));
@@ -51,7 +49,7 @@ function readBindingPath(value, path) {
             cursor = cursor[index];
             continue;
         }
-        if (!isRecord(cursor) || !(segment in cursor))
+        if (!guards.isRecord(cursor) || !(segment in cursor))
             return undefined;
         cursor = cursor[segment];
     }
@@ -80,7 +78,7 @@ function resolveBindingTokens(value, bindings) {
     if (Array.isArray(value)) {
         return value.map((entry) => resolveBindingTokens(entry, bindings));
     }
-    if (!isRecord(value))
+    if (!guards.isRecord(value))
         return value;
     return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolveBindingTokens(entry, bindings)]));
 }
@@ -90,7 +88,7 @@ function extractBoundNodeIds(value) {
     if (Array.isArray(value)) {
         return [...new Set(value.flatMap((entry) => extractBoundNodeIds(entry)))];
     }
-    if (!isRecord(value))
+    if (!guards.isRecord(value))
         return [];
     const direct = typeof value.nodeId === 'string' && value.nodeId.length > 0
         ? [value.nodeId]
@@ -364,7 +362,7 @@ function revisionOnlyParagraphStep(plan) {
         return undefined;
     const at = apply.args.at;
     if (at !== undefined) {
-        if (!isRecord(at))
+        if (!guards.isRecord(at))
             return undefined;
         if (at.kind === 'documentStart' || at.kind === 'documentEnd') {
             if (Object.keys(at).some((key) => key !== 'kind'))
@@ -372,7 +370,7 @@ function revisionOnlyParagraphStep(plan) {
         }
         else if (at.kind === 'before' || at.kind === 'after') {
             if (Object.keys(at).some((key) => key !== 'kind' && key !== 'target') ||
-                !isRecord(at.target) ||
+                !guards.isRecord(at.target) ||
                 at.target.kind !== 'block' ||
                 typeof at.target.nodeId !== 'string' ||
                 typeof at.target.nodeType !== 'string' ||

package/dist/agent/runtime.js

@@ -5,6 +5,7 @@ import { SuperDocCliError } from '../runtime/errors.js';
 import { validatePlan } from './ir.js';
 import { buildDocumentSnapshot, buildMutationSnapshot, resolveSnapshotSelector, AmbiguousSelectorError, } from './doc-snapshot.js';
 import { getOperationCatalogEntry } from './operation-catalog.js';
+import { isRecord } from '../guards.js';
 const RESERVED_ARG_KEYS = new Set(['sessionId', 'doc']);
 function ensureKnownOperation(operationId) {
     const entry = getOperationCatalogEntry(operationId);
@@ -27,9 +28,6 @@ function ensureClean(args) {
     }
     return args;
 }
-function isRecord(value) {
-    return value != null && typeof value === 'object' && !Array.isArray(value);
-}
 function isRefToken(value) {
     return (isRecord(value) &&
         typeof value.ref === 'string' &&