@superdoc/sdk 2.23.0-next.8 → 2.23.0

package/dist/agent/actions.cjs

@@ -9,6 +9,7 @@ var listTransform = require('../action-primitives/tools/list-transform.cjs');
 var structureInsert = require('../action-primitives/tools/structure-insert.cjs');
 var textTransform = require('../action-primitives/tools/text-transform.cjs');
 var docSnapshot = require('./doc-snapshot.cjs');
+var guards = require('../guards.cjs');
 
 const ACTION_DEFINITIONS = actionDescriptors;
 function projectActionDefinitions(project) {
@@ -72,9 +73,6 @@ function getActionDispositions() {
 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);
@@ -100,7 +98,7 @@ function isNoOp(err) {
     return err?.code === 'NO_OP';
 }
 function asRecord(value) {
-    return isRecord(value) ? value : null;
+    return guards.isRecord(value) ? value : null;
 }
 function asString(value, fallback) {
     return typeof value === 'string' ? value : fallback;
@@ -657,7 +655,7 @@ async function previewMutations(doc, steps, changeMode, expectedRevision) {
         });
     }
     const result = await fn({ atomic: true, changeMode: changeMode ?? 'direct', expectedRevision, steps });
-    return isRecord(result) ? result : {};
+    return guards.isRecord(result) ? result : {};
 }
 async function executeCreateTable(doc, args, placement) {
     const fn = maybeMethod(doc, ['create', 'table']);
@@ -880,6 +878,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.ExecutionContext(doc, { evidence: args.evidence, selectors: placementSelectors(args.placement) });
     try {
@@ -892,7 +891,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 = [];
@@ -932,6 +931,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);
@@ -1052,7 +1061,7 @@ async function runReplaceTextUnchecked(doc, args) {
                     const preview = await previewMutations(doc, candidates.map((candidate) => candidate.step), args.changeMode, pre.revision);
                     if (preview.valid === true)
                         break;
-                    const failures = Array.isArray(preview.failures) ? preview.failures.filter(isRecord) : [];
+                    const failures = Array.isArray(preview.failures) ? preview.failures.filter(guards.isRecord) : [];
                     const absent = failures.find((failure) => failure.code === 'MATCH_NOT_FOUND' && typeof failure.stepId === 'string');
                     if (!absent) {
                         throw new Error(typeof failures[0]?.message === 'string' ? failures[0].message : 'replacement plan could not be prepared');
@@ -1281,6 +1290,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']);
 /**
@@ -1450,6 +1625,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$1.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)`,
@@ -1459,6 +1639,7 @@ async function runDeleteBlocks(doc, args) {
             executedOperations,
             verification,
             deletedBlocks: deleted,
+            ...(listPunctuation.length > 0 ? { listPunctuation } : {}),
             ...(errors$1.length ? { errors: errors$1 } : {}),
             ...(errors$1.length
                 ? { nextStep: 'Re-inspect the document and retry the selectors that did not resolve to one block.' }
@@ -2713,7 +2894,7 @@ async function listAllTrackedChanges(listFn) {
         const page = asRecord(await listFn({ offset, limit: PAGE, in: 'all' }));
         const items = Array.isArray(page?.items) ? page.items : [];
         for (const item of items) {
-            if (isRecord(item))
+            if (guards.isRecord(item))
                 out.push(item);
         }
         const total = asNumber(page?.total, out.length) ?? out.length;
@@ -4290,12 +4471,12 @@ function findTextTarget(snapshot, nodeId) {
     return null;
 }
 function compactOpResult(result) {
-    if (!isRecord(result))
+    if (!guards.isRecord(result))
         return result;
     const compact = {};
     if (typeof result.success === 'boolean')
         compact.success = result.success;
-    if (isRecord(result.revision))
+    if (guards.isRecord(result.revision))
         compact.revision = result.revision;
     if (Array.isArray(result.steps))
         compact.stepCount = result.steps.length;
@@ -4311,7 +4492,7 @@ function trackedChangeRefIds(result) {
     }));
 }
 function parseScopedReplaceArgs(args, edits, changeMode, expectedRevision) {
-    if (!isRecord(args.selector))
+    if (!guards.isRecord(args.selector))
         return null;
     return {
         edits,
@@ -4341,9 +4522,9 @@ async function fieldResultRanges(doc, nodeId, blockText) {
     const limit = 500;
     for (let offset = 0; offset < 100_000; offset += limit) {
         const page = await fn({ limit, offset });
-        const items = isRecord(page) && Array.isArray(page.items) ? page.items.filter(isRecord) : [];
+        const items = guards.isRecord(page) && Array.isArray(page.items) ? page.items.filter(guards.isRecord) : [];
         for (const item of items) {
-            const address = isRecord(item.address) ? item.address : null;
+            const address = guards.isRecord(item.address) ? item.address : null;
             const inBody = typeof address?.storyId !== 'string' || address.storyId.startsWith('main:');
             if (address?.blockId !== nodeId || !inBody)
                 continue;
@@ -4352,7 +4533,7 @@ async function fieldResultRanges(doc, nodeId, blockText) {
             }
             results.push(item.resolvedText);
         }
-        const total = isRecord(page) && typeof page.total === 'number' ? page.total : null;
+        const total = guards.isRecord(page) && typeof page.total === 'number' ? page.total : null;
         if (items.length < limit || (total != null && offset + limit >= total))
             break;
     }
@@ -4403,8 +4584,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);
@@ -4441,6 +4623,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);
@@ -4493,11 +4692,11 @@ async function runScopedReplaceUnchecked(doc, args) {
             // that each one still covers the text matched in the snapshot, so a
             // projection mismatch never rewrites other text.
             const preview = await previewMutations(doc, steps, args.changeMode, pre.revision);
-            const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(isRecord) : [];
+            const previewSteps = Array.isArray(preview.steps) ? preview.steps.filter(guards.isRecord) : [];
             const aligned = preview.valid === true &&
                 steps.every((step, index) => {
                     const resolutions = previewSteps.find((candidate) => candidate.stepId === step.id)?.resolutions;
-                    const resolved = Array.isArray(resolutions) && isRecord(resolutions[0]) ? resolutions[0].text : undefined;
+                    const resolved = Array.isArray(resolutions) && guards.isRecord(resolutions[0]) ? resolutions[0].text : undefined;
                     const span = targetedSpans[index];
                     return resolved === block.text.slice(span.start, span.end);
                 });
@@ -4530,7 +4729,7 @@ async function runScopedReplaceUnchecked(doc, args) {
     // atomic history step. Only do so while the document is still at the
     // revision this plan produced, so the undo cannot reach any other change.
     let rolledBack = false;
-    const appliedRevision = isRecord(result) && isRecord(result.revision) ? result.revision.after : undefined;
+    const appliedRevision = guards.isRecord(result) && guards.isRecord(result.revision) ? result.revision.after : undefined;
     if (wroteExactTargets &&
         postBlock != null &&
         postBlock.text !== expected &&
@@ -4645,13 +4844,13 @@ function markRunPropsFromMarks(marks) {
  * paragraphIndentOf. Returns null when the paragraph mark carries nothing.
  */
 function paragraphMarkRunPropsOf(payload) {
-    const node = isRecord(payload) ? payload.node : null;
-    if (!isRecord(node))
+    const node = guards.isRecord(payload) ? payload.node : null;
+    if (!guards.isRecord(node))
         return null;
-    const candidates = [isRecord(node.paragraph) ? node.paragraph.props : null, node.props];
+    const candidates = [guards.isRecord(node.paragraph) ? node.paragraph.props : null, node.props];
     for (const props of candidates) {
-        const mark = isRecord(props) ? props.markRunProps : null;
-        if (isRecord(mark) && Object.keys(mark).length > 0)
+        const mark = guards.isRecord(props) ? props.markRunProps : null;
+        if (guards.isRecord(mark) && Object.keys(mark).length > 0)
             return mark;
     }
     return null;
@@ -4727,6 +4926,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).
@@ -4761,6 +4962,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|$)`);
+function typedMarkerPrefixOf(text) {
+    const match = TYPED_MARKER_PREFIX.exec(text);
+    return match ? { prefix: match[0], marker: match[1] } : null;
+}
+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);
+}
+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 —
@@ -4837,7 +5113,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 : [];
@@ -4851,6 +5130,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
@@ -4886,6 +5168,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.
@@ -4896,13 +5231,13 @@ async function listItemRunPattern(doc, text, blockId) {
  * indent copied" rather than a thrown read.
  */
 function paragraphIndentOf(payload) {
-    const node = isRecord(payload) ? payload.node : null;
-    if (!isRecord(node))
+    const node = guards.isRecord(payload) ? payload.node : null;
+    if (!guards.isRecord(node))
         return null;
-    const candidates = [isRecord(node.paragraph) ? node.paragraph.props : null, node.props];
+    const candidates = [guards.isRecord(node.paragraph) ? node.paragraph.props : null, node.props];
     for (const props of candidates) {
-        const indent = isRecord(props) ? props.indent : null;
-        if (!isRecord(indent))
+        const indent = guards.isRecord(props) ? props.indent : null;
+        if (!guards.isRecord(indent))
             continue;
         const twips = {};
         for (const key of ['left', 'right', 'firstLine', 'hanging']) {
@@ -4979,7 +5314,7 @@ function marksToInline(marks) {
 }
 /** Parse a raw agent mark bag, keeping only recognized keys with valid types. */
 function normalizeMarks(raw) {
-    if (!isRecord(raw))
+    if (!guards.isRecord(raw))
         return undefined;
     const m = {};
     if (typeof raw.bold === 'boolean')
@@ -5009,7 +5344,7 @@ function normalizeMarks(raw) {
 function normalizeItemSpec(raw) {
     if (typeof raw === 'string')
         return { text: raw, level: 0 };
-    if (!isRecord(raw))
+    if (!guards.isRecord(raw))
         return null;
     const spec = {};
     const lvl = asNumber(raw.level);
@@ -5023,7 +5358,7 @@ function normalizeItemSpec(raw) {
             if (typeof r === 'string') {
                 runs.push({ text: r });
             }
-            else if (isRecord(r) && typeof r.text === 'string') {
+            else if (guards.isRecord(r) && typeof r.text === 'string') {
                 const rm = normalizeMarks(r.marks);
                 runs.push(rm ? { text: r.text, marks: rm } : { text: r.text });
             }
@@ -5642,9 +5977,9 @@ async function appendListAtPlacement(doc, args) {
     const items = Array.isArray(args.items)
         ? args.items.filter((t) => typeof t === 'string' && t.length > 0)
         : [];
-    const placement = isRecord(args.placement) ? args.placement : null;
+    const placement = guards.isRecord(args.placement) ? args.placement : null;
     const at = placement && typeof placement.at === 'string' ? placement.at : null;
-    const selector = placement && isRecord(placement.selector) ? placement.selector : null;
+    const selector = placement && guards.isRecord(placement.selector) ? placement.selector : null;
     if (items.length === 0 || !placement || (at !== 'after' && at !== 'before') || !selector)
         return null;
     const pre = await docSnapshot.buildMutationSnapshot(doc, { includeDomains: ['blocks'] });
@@ -5764,6 +6099,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
@@ -5789,7 +6125,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;
@@ -5892,6 +6230,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})[).:\]]/;
 /**
@@ -6022,7 +6396,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] };
         }
@@ -6042,15 +6417,15 @@ async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, avail
             return receipt;
         // The placement anchor, when the action targeted one, is the user's own
         // statement of "blend in with THIS" — prefer it over type-matched siblings.
-        const placement = isRecord(args?.placement) ? args.placement : null;
-        const anchorSelector = placement && isRecord(placement.selector) ? placement.selector : null;
+        const placement = guards.isRecord(args?.placement) ? args.placement : null;
+        const anchorSelector = placement && guards.isRecord(placement.selector) ? placement.selector : null;
         const anchorId = anchorSelector && typeof anchorSelector.nodeId === 'string' ? anchorSelector.nodeId : null;
         const anchorRow = anchorId ? (postBlocks.find((b) => b.nodeId === anchorId) ?? null) : null;
         // 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 hasExplicitStyling = rawTexts.some((entry) => isRecord(entry) && (Array.isArray(entry.runs) || entry.marks != null));
+        const rawTexts = Array.isArray(args?.texts) ? args.texts : args?.text != null ? [args.text] : [];
+        const hasExplicitStyling = rawTexts.some((entry) => guards.isRecord(entry) && (Array.isArray(entry.runs) || entry.marks != null));
         const insertedTexts = rawTexts.map((entry) => {
             if (typeof entry === 'string')
                 return entry;
@@ -6075,7 +6450,7 @@ async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, avail
             // the previous NAME line, not like the "Name:" line directly above it.
             // Only tried when matching against the neighbour found nothing, so this
             // cannot change a case that already had an answer.
-            const applied = isRecord(result?.applied) ? result.applied : null;
+            const applied = guards.isRecord(result?.applied) ? result.applied : null;
             if (createdRows.length > 1 && (!applied || Object.keys(applied).length === 0)) {
                 const parallel = postBlocks[createdIndex - createdRows.length];
                 if (parallel && preIds.has(parallel.nodeId) && !parallel.isEmpty) {
@@ -6250,7 +6625,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' },
                 },
             ],
@@ -6291,7 +6674,7 @@ async function runAttachNumbering(doc, args) {
     };
 }
 async function dispatchSuperdocPerformAction(doc, args) {
-    if (!isRecord(args)) {
+    if (!guards.isRecord(args)) {
         throw new errors.SuperDocCliError('superdoc_perform_action arguments must be an object', {
             code: 'INVALID_ARGUMENT',
         });
@@ -6365,7 +6748,7 @@ async function dispatchSuperdocPerformAction(doc, args) {
             if (expectedRevision !== undefined && (typeof expectedRevision !== 'string' || expectedRevision.length === 0)) {
                 throw new errors.SuperDocCliError('replace_text: expectedRevision must be a non-empty string from this live document handle', { code: 'INVALID_ARGUMENT' });
             }
-            if (edits.some((edit) => edit.occurrence != null) && !isRecord(args.selector)) {
+            if (edits.some((edit) => edit.occurrence != null) && !guards.isRecord(args.selector)) {
                 throw new errors.SuperDocCliError('replace_text: explicit occurrence requires a selector resolving to one block', {
                     code: 'INVALID_ARGUMENT',
                 });
@@ -6995,13 +7378,13 @@ function parseExactTrackedChangeIdList(value) {
 }
 async function superdocPerformAction(doc, args) {
     try {
-        const changeMode = isRecord(args) ? parseChangeMode(args.changeMode) : undefined;
+        const changeMode = guards.isRecord(args) ? parseChangeMode(args.changeMode) : undefined;
         return await dispatchSuperdocPerformAction(changeMode ? actionChangeMode.bindActionChangeMode(doc, changeMode) : doc, args);
     }
     catch (error) {
         if (!(error instanceof docSnapshot.MutationSnapshotError))
             throw error;
-        const action = isRecord(args) && isActionName(args.action) ? args.action : 'superdoc_perform_action';
+        const action = guards.isRecord(args) && isActionName(args.action) ? args.action : 'superdoc_perform_action';
         return {
             status: 'failed',
             intent: action,
@@ -7062,7 +7445,7 @@ function parseEdits(value) {
         return undefined;
     const result = [];
     for (const entry of value) {
-        if (!isRecord(entry))
+        if (!guards.isRecord(entry))
             return undefined;
         const find = asString(entry.find);
         const replace = asString(entry.replace) ?? '';
@@ -7082,7 +7465,7 @@ function parseEdits(value) {
 function parseCellCandidate(cell) {
     if (typeof cell === 'string')
         return cell;
-    if (isRecord(cell)) {
+    if (guards.isRecord(cell)) {
         const spec = normalizeItemSpec(cell);
         if (spec)
             return { text: spec.text, runs: spec.runs, marks: spec.marks };
@@ -7110,7 +7493,7 @@ function parsePlaceholderFields(value) {
         return undefined;
     const result = [];
     for (const entry of value) {
-        if (!isRecord(entry) || typeof entry.value !== 'string')
+        if (!guards.isRecord(entry) || typeof entry.value !== 'string')
             return undefined;
         const label = asString(entry.label);
         result.push(label ? { label, value: entry.value } : { value: entry.value });
@@ -7118,7 +7501,7 @@ function parsePlaceholderFields(value) {
     return result;
 }
 function parsePlacement(value) {
-    if (!isRecord(value))
+    if (!guards.isRecord(value))
         return undefined;
     const at = asString(value.at);
     if (at === 'document_end' || at === 'document_start') {
@@ -7133,7 +7516,7 @@ function parsePlacement(value) {
     return undefined;
 }
 function parseSelector(value) {
-    if (!isRecord(value))
+    if (!guards.isRecord(value))
         return undefined;
     const kind = asString(value.kind);
     if (kind === 'nodeId') {
@@ -7260,4 +7643,7 @@ exports.ACTION_NAMES_LIST = ACTION_NAMES_LIST;
 exports.getActionDispositions = getActionDispositions;
 exports.getUnavailableTrackedActions = getUnavailableTrackedActions;
 exports.isActionName = isActionName;
+exports.markerShapeOf = markerShapeOf;
 exports.superdocPerformAction = superdocPerformAction;
+exports.typedCaptionSpanOf = typedCaptionSpanOf;
+exports.typedMarkerPrefixOf = typedMarkerPrefixOf;