@superdoc/sdk 2.27.0 → 2.28.0-next.16

package/dist/agent/actions.js

@@ -9,6 +9,8 @@ import { runSuperdocStructureInsertWorkflow } from '../action-primitives/tools/s
 import { runSuperdocTextTransformWorkflow } from '../action-primitives/tools/text-transform.js';
 import { buildDocumentSnapshot, buildMutationSnapshot, matchRunsForBlock, MutationSnapshotError, resolveSnapshotSelector, } from './doc-snapshot.js';
 import { isRecord } from '../guards.js';
+import { LEAD_IN_BODY_SAMPLE_CHARS, LEAD_IN_DELIMITERS, LEAD_IN_MAX_CHARS, LEAD_IN_QUOTES, labelLeadInSpanOf, leadInEndOf, leadInShapeOf, } from './lead-in-label.js';
+import { RUN_BOOL_MARKS, bodyLookToWrite, callerStyledAnEntry, contextualFormattingOf, createdLeadLengthOf, insertedTextEntriesOf, isSectionTitle, leadBodySplitOf, parallelGroupIndexOf, placementAnchorIdOf, referenceProbeOf, shouldTryParallelGroup, withoutTruncationEllipsis, } from './inserted-block-formatting.js';
 export const ACTION_DEFINITIONS = actionDescriptors;
 function projectActionDefinitions(project) {
     return Object.fromEntries(Object.entries(ACTION_DEFINITIONS).map(([name, definition]) => [name, project(definition)]));
@@ -2669,7 +2671,6 @@ async function runRewriteBlock(doc, args) {
         return context.failure('rewrite_block', error);
     }
 }
-const RUN_BOOL_MARKS = ['bold', 'italic', 'underline', 'strike'];
 function inlineFromSnapshotRun(run) {
     const inline = {};
     for (const key of RUN_BOOL_MARKS) {
@@ -5186,112 +5187,8 @@ async function runScopedReplace(doc, args) {
  */
 /** Points → twips: the node read side reports points, mutations take twips. */
 const TWIPS_PER_POINT = 20;
-/**
- * Delimiters that separate a list item's lead-in label from its body text.
- * Spaced dashes are listed separately from bare ones because the label run
- * usually stops BEFORE the space ("JavaScript / TypeScript" + " — SuperDoc…").
- */
-const LEAD_IN_DELIMITERS = [':', ' — ', ' – ', ' - ', '—', '–'];
-/** A lead-in is a LABEL, not a sentence — longer spans are prose, not a pattern. */
-const LEAD_IN_MAX_CHARS = 90;
-/** Sentence characters sampled past the label, to read the body's own look. */
-const LEAD_IN_BODY_SAMPLE_CHARS = 40;
-/**
- * Where an item's lead-in label ends.
- *
- * The SIBLINGS' delimiter wins whenever the item uses it: with a dash-style
- * list, "Rust: Advanced — details" splits at the dash, not at the colon inside
- * the label. Falling back to the earliest known delimiter is only for items
- * that do not use the siblings' one at all.
- */
-function leadInEndOf(text, preferred) {
-    const at = (delimiter) => {
-        const index = text.indexOf(delimiter);
-        return index > 0 && index <= LEAD_IN_MAX_CHARS ? index : null;
-    };
-    if (preferred) {
-        const preferredAt = at(preferred);
-        if (preferredAt != null)
-            return preferredAt;
-    }
-    const found = LEAD_IN_DELIMITERS.map(at).filter((index) => index != null);
-    return found.length > 0 ? Math.min(...found) : null;
-}
-/** Quote characters a defined term is wrapped in ("Deliverables" means …). */
-const LEAD_IN_QUOTES = ['"', '\u201c', '\u2018', "'"];
-/**
- * Delimiters allowed to sit INSIDE the label run. Wider than the set used to
- * split at a delimiter that follows the label, because a sentence period only
- * counts as a label boundary when the reference's own emphasised run ends with
- * it — "1.7. Records. " — which is evidence no bare text scan can provide.
- */
-const LEAD_IN_TAIL_DELIMITERS = ['. ', ': ', ...LEAD_IN_DELIMITERS];
-/**
- * Read the label shape a reference block uses, from its text and its label run.
- *
- * The delimiter has to sit at the label's edge: immediately AFTER it ("Label:
- * sentence"), or at its own tail ("1.7. Records. " — a numbered clause whose
- * marker and label share one run). That adjacency is what distinguishes a label
- * from an ordinary emphasised opening clause.
- */
-function leadInShapeOf(blockText, labelText, quote) {
-    if (quote)
-        return { kind: 'quoted', quote };
-    const after = LEAD_IN_DELIMITERS.find((d) => blockText.startsWith(d, labelText.length));
-    if (after)
-        return { kind: 'before', delimiter: after };
-    const trimmed = labelText.trimEnd();
-    const inside = LEAD_IN_TAIL_DELIMITERS.find((d) => trimmed.endsWith(d.trimEnd()) && trimmed.length > d.trimEnd().length);
-    if (inside) {
-        const occurrence = labelText.split(inside).length - 1;
-        if (occurrence > 0)
-            return { kind: 'inside', delimiter: inside, occurrence };
-    }
-    // A single emphasised word followed by a space and plain prose: the token
-    // itself is the label ("WHEREAS the Party…"). Multi-word runs stay
-    // unrecognised — an emphasised opening clause is prose, not a label.
-    if (/^\S+\s$/.test(labelText) && blockText.length > labelText.length && blockText.startsWith(labelText)) {
-        return { kind: 'word', label: labelText.trimEnd() };
-    }
-    return null;
-}
-/** 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).
-        const next = text.charAt(shape.label.length);
-        return text.startsWith(shape.label) && (next === '' || /\s/.test(next))
-            ? { start: 0, end: shape.label.length }
-            : null;
-    }
-    if (shape.kind === 'quoted') {
-        const opener = text.slice(0, 2).indexOf(shape.quote);
-        if (opener < 0)
-            return null;
-        const close = text.indexOf(shape.quote, opener + 1);
-        if (close < 0 || close - opener - 1 <= 0 || close > LEAD_IN_MAX_CHARS)
-            return null;
-        return { start: opener + 1, end: close };
-    }
-    if (shape.kind === 'inside') {
-        // Mirror the reference's STRUCTURE: "1.7. Records. " ends at its second
-        // ". ", so "1.8. Review. The parties…" must end at its second one too —
-        // stopping at the first would emphasise the number alone.
-        let at = -1;
-        for (let seen = 0; seen < shape.occurrence; seen += 1) {
-            at = text.indexOf(shape.delimiter, at + 1);
-            if (at < 0)
-                return null;
-        }
-        if (at <= 0 || at > LEAD_IN_MAX_CHARS)
-            return null;
-        return { start: 0, end: at + shape.delimiter.length };
-    }
-    const end = leadInEndOf(text, shape.delimiter);
-    return end == null ? null : { start: 0, end };
+    return shape.kind === 'typed' ? typedCaptionSpanOf(text, shape.delimiter) : labelLeadInSpanOf(text, shape);
 }
 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}[.)])`;
@@ -6564,26 +6461,12 @@ async function matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anc
                 applied.indent = refIndent;
             }
         }
-        // Lead-marker pattern: manually lettered/numbered sections style the
-        // marker run differently from the body ("(m) " bold, rest plain) — a
-        // per-run pattern blocks.list rows cannot express. When the reference
-        // block opens with such a styled marker and the created text opens with a
-        // similar marker token, reproduce the reference's marker/body split on the
-        // created block. Skipped when the caller supplied explicit runs/marks.
         if (allowLeadPattern) {
             const lead = await matchLeadMarkerPattern(doc, reference, created, createdText);
             if (lead?.changed)
                 applied.leadMarker = lead;
-            // matchLeadMarkerPattern only knows a shared literal lead ("WHEREAS") and
-            // numbered tokens ("1.", "(m)"), and it needs the reference split across
-            // two runs. Sample the reference's RUNS for everything else: a quoted
-            // defined term (`"Deliverables" means …`), a "1.7. Records. " clause whose
-            // marker and label share a run. A UNIFORM reference is not a split, so
-            // its emphasis never transfers.
             else {
                 const runPattern = await matchBlockRunPattern(doc, reference, created, createdText);
-                // Assigning `undefined` would still create the key, and an `applied` with
-                // keys reads as "this block was matched" — hiding a block that got nothing.
                 if (runPattern)
                     applied.runPattern = runPattern;
             }
@@ -6633,21 +6516,6 @@ function typedShapeReference(postBlocks, preIds, created, createdIndex, createdT
         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})[).:\]]/;
-/**
- * Reproduce a reference block's lead/body run split on a freshly-created
- * block. Fires only when the reference genuinely has the pattern — its first
- * run is a SHORT lead-in styled differently from the body — and the created
- * text opens with a matching lead of its own. Two lead shapes are recognized:
- *  - literal lead words shared by siblings ("WHEREAS", "NOW, THEREFORE"): the
- *    created text starts with the reference's exact lead text;
- *  - marker tokens ("(m)", "1.", "a)"): the token text differs per clause, so
- *    the created lead is its OWN token matched by shape.
- * Applies the reference lead's marks to the created lead span and only the
- * reference body's font and size to the rest: the body never gains emphasis or
- * an explicit mark-off it did not already carry.
- */
 async function matchLeadMarkerPattern(doc, reference, created, createdText) {
     const createdPreview = created.textPreview ?? '';
     if (!reference.nodeId || !created.nodeId || !createdPreview)
@@ -6656,60 +6524,20 @@ async function matchLeadMarkerPattern(doc, reference, created, createdText) {
     const formatFn = maybeMethod(doc, ['format', 'apply']);
     if (!queryFn || !formatFn)
         return null;
-    // A short unique-enough prefix of the reference is all we need: the runs
-    // returned tile the MATCHED range, covering the lead and the body start.
-    // blocks.list truncates textPreview with a trailing ellipsis — strip it, the
-    // remaining prefix IS document text so query.match can find it.
-    const refProbe = (reference.textPreview ?? '')
-        .replace(/…\s*$/, '')
-        .slice(0, 60)
-        .trim();
+    const refProbe = referenceProbeOf(reference.textPreview ?? '');
     if (!refProbe)
         return null;
-    const refRuns = await matchRunsForBlock(queryFn, refProbe, reference.nodeId);
-    if (refRuns.length < 2)
-        return null; // uniform reference — no split to copy
-    const leadRun = refRuns[0];
-    const bodyRun = refRuns[1];
-    // The pattern requires a real FORMATTING transition between lead and body
-    // (bold/italic/underline/strike). Runs split only by font/color/hyperlink
-    // boundaries are ordinary prose — restyling from those would misfire.
-    if (RUN_BOOL_MARKS.every((key) => Boolean(leadRun[key]) === Boolean(bodyRun[key])))
-        return null;
-    const refLead = leadRun.text.trimEnd();
-    // The first run must be a short lead-in (a token or a word or two), not
-    // half the sentence.
-    if (refLead.length === 0 || refLead.length > 40 || leadRun.start !== 0)
+    const split = leadBodySplitOf(await matchRunsForBlock(queryFn, refProbe, reference.nodeId));
+    if (!split)
         return null;
-    // The caller knows the text it inserted; the blocks.list preview is truncated.
-    const fullText = createdText || createdPreview.replace(/…\s*$/, '');
-    // The created block's own lead span (ASCII markers only by design).
-    let createdLeadLen = 0;
-    const boundaryAfter = (len) => len >= fullText.length || !/[A-Za-z0-9]/.test(fullText[len]);
-    if (fullText.startsWith(refLead) && boundaryAfter(refLead.length)) {
-        // Literal shared lead word(s) — "WHEREAS, …" after a "WHEREAS, …" sibling.
-        // Exact-case with a token boundary so "Note" never claims "Notebook".
-        createdLeadLen = refLead.length;
-    }
-    else {
-        const refMarker = LEAD_MARKER_PATTERN.exec(refLead);
-        const createdMarker = LEAD_MARKER_PATTERN.exec(fullText);
-        // Marker tokens: the reference's first run must BE the token, and the
-        // created text must open with a token of the same category (letters
-        // with letters, digits with digits — "(m)" doesn't restyle "1.").
-        if (refMarker &&
-            createdMarker &&
-            refMarker[0] === refLead &&
-            /\d/.test(refMarker[0]) === /\d/.test(createdMarker[0])) {
-            createdLeadLen = createdMarker[0].length;
-        }
-    }
+    const fullText = createdText || withoutTruncationEllipsis(createdPreview);
+    const createdLeadLen = createdLeadLengthOf(split.leadText, fullText);
     if (createdLeadLen === 0)
         return null;
-    const markerInline = emphasisedLookOf(inlineFromSnapshotRun(leadRun));
+    const markerInline = emphasisedLookOf(inlineFromSnapshotRun(split.lead));
     if (!markerInline)
         return null;
-    const bodyInline = baseRunLookOf(bodyRun);
+    const bodyInline = baseRunLookOf(split.body);
     let changed = await applyInlineQuiet(formatFn, {
         blockId: created.nodeId,
         start: 0,
@@ -6727,21 +6555,10 @@ async function matchLeadMarkerPattern(doc, reference, created, createdText) {
     }
     return { marker: fullText.slice(0, createdLeadLen), markerInline, bodyInline, changed };
 }
-/**
- * Copy a reference block's RUN pattern onto a created block: the body's font
- * and size over the whole block, then the label look over the new block's own
- * label span.
- *
- * Complements matchLeadMarkerPattern, which requires either a shared literal
- * lead word or a marker token AND a two-run reference. This one reads the
- * reference's runs (`query.match`, the only read that reports run styling) and
- * handles the shapes that leaves out. A single uniform run has no label, so
- * nothing but its font transfers.
- */
 async function matchBlockRunPattern(doc, reference, created, createdText) {
     const formatFn = maybeMethod(doc, ['format', 'apply']);
-    const referenceText = (reference.textPreview ?? '').replace(/…\s*$/, '').trim();
-    const fullText = createdText || (created.textPreview ?? '').replace(/…\s*$/, '');
+    const referenceText = withoutTruncationEllipsis(reference.textPreview ?? '').trim();
+    const fullText = createdText || withoutTruncationEllipsis(created.textPreview ?? '');
     if (!formatFn || !reference.nodeId || !created.nodeId || !referenceText || !fullText)
         return null;
     const pattern = await listItemRunPattern(doc, referenceText, reference.nodeId);
@@ -6753,11 +6570,7 @@ async function matchBlockRunPattern(doc, reference, created, createdText) {
     const own = Object.keys(sampled).length > 0
         ? await effectiveBaseLookOf(doc, fullText, { nodeId: created.nodeId, nodeType: created.nodeType })
         : null;
-    const body = own === 'mixed'
-        ? {}
-        : own
-            ? Object.fromEntries(Object.entries(sampled).filter(([key, value]) => own[key] !== value))
-            : sampled;
+    const body = bodyLookToWrite(sampled, own);
     if (Object.keys(body).length > 0) {
         if (await applyInlineQuiet(formatFn, { blockId: created.nodeId, start: 0, end, inline: body })) {
             applied.body = body;
@@ -6783,17 +6596,10 @@ async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, avail
             .filter(({ row }) => row.nodeId && !preIds.has(row.nodeId) && !row.isEmpty);
         if (createdRows.length === 0)
             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 anchorId = anchorSelector && typeof anchorSelector.nodeId === 'string' ? anchorSelector.nodeId : null;
+        const anchorId = placementAnchorIdOf(args);
         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 : args?.text != null ? [args.text] : [];
-        const hasExplicitStyling = rawTexts.some((entry) => isRecord(entry) && (Array.isArray(entry.runs) || entry.marks != null));
+        const rawTexts = insertedTextEntriesOf(args);
+        const hasExplicitStyling = callerStyledAnEntry(rawTexts);
         const insertedTexts = rawTexts.map((entry) => {
             if (typeof entry === 'string')
                 return entry;
@@ -6801,26 +6607,12 @@ async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, avail
             return spec ? itemSpecText(spec) : '';
         });
         const allApplied = [];
-        for (let ci = 0; ci < createdRows.length; ci += 1) {
-            const { row: created, index: createdIndex } = createdRows[ci];
-            // The first of several inserted blocks is the section TITLE — it should
-            // read like a heading (flush-left), so it must NOT inherit the body
-            // sibling's left indent even though it matches the same anchor.
-            const isTitle = createdRows.length > 1 && ci === 0;
+        for (const [ci, { row: created, index: createdIndex }] of createdRows.entries()) {
             const createdText = insertedTexts[ci] ?? '';
-            const match = (anchor) => matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anchor, createdRows.length === 1, isTitle, !hasExplicitStyling, 
-            // The texts the caller inserted, in order — the truncated preview
-            // cannot measure a label span or the end of the block.
-            createdText);
+            const match = (anchor) => matchOneBlock(doc, postBlocks, preIds, created, createdIndex, anchor, createdRows.length === 1, isSectionTitle(ci, createdRows.length), !hasExplicitStyling, createdText);
             let result = await match(anchorRow);
-            // A GROUP of paragraphs usually repeats the group before it: a signature
-            // block is name / "By:" / "Name:", and the new name line should look like
-            // 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;
-            if (createdRows.length > 1 && (!applied || Object.keys(applied).length === 0)) {
-                const parallel = postBlocks[createdIndex - createdRows.length];
+            if (shouldTryParallelGroup(createdRows.length, result)) {
+                const parallel = postBlocks[parallelGroupIndexOf(createdIndex, createdRows.length)];
                 if (parallel && preIds.has(parallel.nodeId) && !parallel.isEmpty) {
                     result = (await match(parallel)) ?? result;
                 }
@@ -6828,13 +6620,12 @@ async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, avail
             if (result)
                 allApplied.push(result);
         }
-        if (allApplied.length === 0)
+        const contextualFormatting = contextualFormattingOf(allApplied);
+        if (!contextualFormatting)
             return receipt;
-        return { ...receipt, contextualFormatting: allApplied.length === 1 ? allApplied[0] : allApplied };
+        return { ...receipt, contextualFormatting };
     }
     catch (err) {
-        // Formatting matching is best-effort polish: never fail a successful
-        // insert because of it — but the receipt says it was skipped.
         return {
             ...receipt,
             contextualFormatting: { skipped: reasonOf(err) },

package/dist/agent/inserted-block-formatting.cjs

@@ -0,0 +1,102 @@
+'use strict';
+
+var guards = require('../guards.cjs');
+
+const RUN_BOOL_MARKS = ['bold', 'italic', 'underline', 'strike'];
+const TRUNCATED_PREVIEW_TAIL = /…\s*$/;
+const REFERENCE_PROBE_CHARS = 60;
+const LEAD_RUN_MAX_CHARS = 40;
+const MARKER_TOKEN = /^\(?(?:[a-zA-Z]{1,3}|\d{1,3})[).:\]]/;
+const ASCII_WORD_CHARACTER = /[A-Za-z0-9]/;
+const DIGIT = /\d/;
+function withoutTruncationEllipsis(preview) {
+    return preview.replace(TRUNCATED_PREVIEW_TAIL, '');
+}
+function referenceProbeOf(referencePreview) {
+    return withoutTruncationEllipsis(referencePreview).slice(0, REFERENCE_PROBE_CHARS).trim();
+}
+function differsInEmphasis(a, b) {
+    return RUN_BOOL_MARKS.some((key) => Boolean(a[key]) !== Boolean(b[key]));
+}
+function leadBodySplitOf(referenceRuns) {
+    const [lead, body] = referenceRuns;
+    if (!lead || !body || !differsInEmphasis(lead, body))
+        return null;
+    const leadText = lead.text.trimEnd();
+    const isShortOpeningRun = leadText.length > 0 && leadText.length <= LEAD_RUN_MAX_CHARS && lead.start === 0;
+    return isShortOpeningRun ? { lead, body, leadText } : null;
+}
+function endsAtTokenBoundary(text, length) {
+    return length >= text.length || !ASCII_WORD_CHARACTER.test(text.charAt(length));
+}
+function sharedLiteralLeadLength(referenceLead, createdText) {
+    const opensWithSameLead = createdText.startsWith(referenceLead) && endsAtTokenBoundary(createdText, referenceLead.length);
+    return opensWithSameLead ? referenceLead.length : 0;
+}
+function sameCategoryMarkerLength(referenceLead, createdText) {
+    const referenceMarker = MARKER_TOKEN.exec(referenceLead)?.[0];
+    const createdMarker = MARKER_TOKEN.exec(createdText)?.[0];
+    if (referenceMarker == null || createdMarker == null || referenceMarker !== referenceLead)
+        return 0;
+    return DIGIT.test(referenceMarker) === DIGIT.test(createdMarker) ? createdMarker.length : 0;
+}
+function createdLeadLengthOf(referenceLead, createdText) {
+    return sharedLiteralLeadLength(referenceLead, createdText) || sameCategoryMarkerLength(referenceLead, createdText);
+}
+function bodyLookToWrite(sampled, own) {
+    if (own === 'mixed')
+        return {};
+    if (!own)
+        return sampled;
+    return Object.fromEntries(Object.entries(sampled).filter(([key, value]) => own[key] !== value));
+}
+function placementAnchorIdOf(args) {
+    const placement = args?.placement;
+    const selector = guards.isRecord(placement) ? placement.selector : null;
+    return guards.isRecord(selector) && typeof selector.nodeId === 'string' ? selector.nodeId : null;
+}
+function insertedTextEntriesOf(args) {
+    const texts = args?.texts;
+    if (Array.isArray(texts))
+        return texts;
+    const text = args?.text;
+    return text != null ? [text] : [];
+}
+function callerStyledAnEntry(entries) {
+    return entries.some((entry) => guards.isRecord(entry) && (Array.isArray(entry.runs) || entry.marks != null));
+}
+function isSectionTitle(insertedIndex, insertedCount) {
+    return insertedCount > 1 && insertedIndex === 0;
+}
+function appliedNothing(result) {
+    const applied = result?.applied;
+    return !guards.isRecord(applied) || Object.keys(applied).length === 0;
+}
+function shouldTryParallelGroup(insertedCount, result) {
+    return insertedCount > 1 && appliedNothing(result);
+}
+function parallelGroupIndexOf(createdIndex, insertedCount) {
+    return createdIndex - insertedCount;
+}
+function contextualFormattingOf(results) {
+    const [only, ...rest] = results;
+    if (!only)
+        return null;
+    return rest.length === 0 ? only : results;
+}
+
+exports.LEAD_RUN_MAX_CHARS = LEAD_RUN_MAX_CHARS;
+exports.REFERENCE_PROBE_CHARS = REFERENCE_PROBE_CHARS;
+exports.RUN_BOOL_MARKS = RUN_BOOL_MARKS;
+exports.bodyLookToWrite = bodyLookToWrite;
+exports.callerStyledAnEntry = callerStyledAnEntry;
+exports.contextualFormattingOf = contextualFormattingOf;
+exports.createdLeadLengthOf = createdLeadLengthOf;
+exports.insertedTextEntriesOf = insertedTextEntriesOf;
+exports.isSectionTitle = isSectionTitle;
+exports.leadBodySplitOf = leadBodySplitOf;
+exports.parallelGroupIndexOf = parallelGroupIndexOf;
+exports.placementAnchorIdOf = placementAnchorIdOf;
+exports.referenceProbeOf = referenceProbeOf;
+exports.shouldTryParallelGroup = shouldTryParallelGroup;
+exports.withoutTruncationEllipsis = withoutTruncationEllipsis;

package/dist/agent/inserted-block-formatting.d.ts

@@ -0,0 +1,22 @@
+import type { SnapshotRun } from './doc-snapshot.js';
+export declare const RUN_BOOL_MARKS: readonly ["bold", "italic", "underline", "strike"];
+export declare const REFERENCE_PROBE_CHARS = 60;
+export declare const LEAD_RUN_MAX_CHARS = 40;
+export declare function withoutTruncationEllipsis(preview: string): string;
+export declare function referenceProbeOf(referencePreview: string): string;
+export type LeadBodySplit = {
+    lead: SnapshotRun;
+    body: SnapshotRun;
+    leadText: string;
+};
+export declare function leadBodySplitOf(referenceRuns: readonly SnapshotRun[]): LeadBodySplit | null;
+export declare function createdLeadLengthOf(referenceLead: string, createdText: string): number;
+export type BlockBaseLook = Record<string, unknown> | 'mixed' | null;
+export declare function bodyLookToWrite(sampled: Record<string, unknown>, own: BlockBaseLook): Record<string, unknown>;
+export declare function placementAnchorIdOf(args: Record<string, unknown> | undefined): string | null;
+export declare function insertedTextEntriesOf(args: Record<string, unknown> | undefined): unknown[];
+export declare function callerStyledAnEntry(entries: readonly unknown[]): boolean;
+export declare function isSectionTitle(insertedIndex: number, insertedCount: number): boolean;
+export declare function shouldTryParallelGroup(insertedCount: number, result: Record<string, unknown> | null): boolean;
+export declare function parallelGroupIndexOf(createdIndex: number, insertedCount: number): number;
+export declare function contextualFormattingOf(results: Record<string, unknown>[]): Record<string, unknown> | Record<string, unknown>[] | null;

package/dist/agent/inserted-block-formatting.js

@@ -0,0 +1,83 @@
+import { isRecord } from '../guards.js';
+export const RUN_BOOL_MARKS = ['bold', 'italic', 'underline', 'strike'];
+const TRUNCATED_PREVIEW_TAIL = /…\s*$/;
+export const REFERENCE_PROBE_CHARS = 60;
+export const LEAD_RUN_MAX_CHARS = 40;
+const MARKER_TOKEN = /^\(?(?:[a-zA-Z]{1,3}|\d{1,3})[).:\]]/;
+const ASCII_WORD_CHARACTER = /[A-Za-z0-9]/;
+const DIGIT = /\d/;
+export function withoutTruncationEllipsis(preview) {
+    return preview.replace(TRUNCATED_PREVIEW_TAIL, '');
+}
+export function referenceProbeOf(referencePreview) {
+    return withoutTruncationEllipsis(referencePreview).slice(0, REFERENCE_PROBE_CHARS).trim();
+}
+function differsInEmphasis(a, b) {
+    return RUN_BOOL_MARKS.some((key) => Boolean(a[key]) !== Boolean(b[key]));
+}
+export function leadBodySplitOf(referenceRuns) {
+    const [lead, body] = referenceRuns;
+    if (!lead || !body || !differsInEmphasis(lead, body))
+        return null;
+    const leadText = lead.text.trimEnd();
+    const isShortOpeningRun = leadText.length > 0 && leadText.length <= LEAD_RUN_MAX_CHARS && lead.start === 0;
+    return isShortOpeningRun ? { lead, body, leadText } : null;
+}
+function endsAtTokenBoundary(text, length) {
+    return length >= text.length || !ASCII_WORD_CHARACTER.test(text.charAt(length));
+}
+function sharedLiteralLeadLength(referenceLead, createdText) {
+    const opensWithSameLead = createdText.startsWith(referenceLead) && endsAtTokenBoundary(createdText, referenceLead.length);
+    return opensWithSameLead ? referenceLead.length : 0;
+}
+function sameCategoryMarkerLength(referenceLead, createdText) {
+    const referenceMarker = MARKER_TOKEN.exec(referenceLead)?.[0];
+    const createdMarker = MARKER_TOKEN.exec(createdText)?.[0];
+    if (referenceMarker == null || createdMarker == null || referenceMarker !== referenceLead)
+        return 0;
+    return DIGIT.test(referenceMarker) === DIGIT.test(createdMarker) ? createdMarker.length : 0;
+}
+export function createdLeadLengthOf(referenceLead, createdText) {
+    return sharedLiteralLeadLength(referenceLead, createdText) || sameCategoryMarkerLength(referenceLead, createdText);
+}
+export function bodyLookToWrite(sampled, own) {
+    if (own === 'mixed')
+        return {};
+    if (!own)
+        return sampled;
+    return Object.fromEntries(Object.entries(sampled).filter(([key, value]) => own[key] !== value));
+}
+export function placementAnchorIdOf(args) {
+    const placement = args?.placement;
+    const selector = isRecord(placement) ? placement.selector : null;
+    return isRecord(selector) && typeof selector.nodeId === 'string' ? selector.nodeId : null;
+}
+export function insertedTextEntriesOf(args) {
+    const texts = args?.texts;
+    if (Array.isArray(texts))
+        return texts;
+    const text = args?.text;
+    return text != null ? [text] : [];
+}
+export function callerStyledAnEntry(entries) {
+    return entries.some((entry) => isRecord(entry) && (Array.isArray(entry.runs) || entry.marks != null));
+}
+export function isSectionTitle(insertedIndex, insertedCount) {
+    return insertedCount > 1 && insertedIndex === 0;
+}
+function appliedNothing(result) {
+    const applied = result?.applied;
+    return !isRecord(applied) || Object.keys(applied).length === 0;
+}
+export function shouldTryParallelGroup(insertedCount, result) {
+    return insertedCount > 1 && appliedNothing(result);
+}
+export function parallelGroupIndexOf(createdIndex, insertedCount) {
+    return createdIndex - insertedCount;
+}
+export function contextualFormattingOf(results) {
+    const [only, ...rest] = results;
+    if (!only)
+        return null;
+    return rest.length === 0 ? only : results;
+}

package/dist/agent/lead-in-label.cjs

@@ -0,0 +1,100 @@
+'use strict';
+
+const SPACED_DASH_DELIMITERS = [' — ', ' – ', ' - '];
+const BARE_DASH_DELIMITERS = ['—', '–'];
+const LEAD_IN_DELIMITERS = [':', ...SPACED_DASH_DELIMITERS, ...BARE_DASH_DELIMITERS];
+const DELIMITERS_A_LABEL_RUN_MAY_END_WITH = ['. ', ': ', ...LEAD_IN_DELIMITERS];
+const LEAD_IN_MAX_CHARS = 90;
+const LEAD_IN_BODY_SAMPLE_CHARS = 40;
+const LEAD_IN_QUOTES = ['"', '“', '‘', "'"];
+const QUOTED_TERM_OPENER_WINDOW = 2;
+const SINGLE_WORD_THEN_SPACE = /^\S+\s$/;
+function labelEndAt(text, delimiter) {
+    const index = text.indexOf(delimiter);
+    return index > 0 && index <= LEAD_IN_MAX_CHARS ? index : null;
+}
+function earliestLeadInEnd(text) {
+    const found = LEAD_IN_DELIMITERS.map((delimiter) => labelEndAt(text, delimiter)).filter((index) => index != null);
+    return found.length > 0 ? Math.min(...found) : null;
+}
+function leadInEndOf(text, siblingDelimiter) {
+    const siblingEnd = siblingDelimiter ? labelEndAt(text, siblingDelimiter) : null;
+    return siblingEnd ?? earliestLeadInEnd(text);
+}
+function labelRunTailShapeOf(labelText) {
+    const trimmed = labelText.trimEnd();
+    const delimiter = DELIMITERS_A_LABEL_RUN_MAY_END_WITH.find((d) => trimmed.endsWith(d.trimEnd()) && trimmed.length > d.trimEnd().length);
+    if (!delimiter)
+        return null;
+    const occurrence = labelText.split(delimiter).length - 1;
+    return occurrence > 0 ? { kind: 'inside', delimiter, occurrence } : null;
+}
+function emphasisedOpeningWordOf(blockText, labelText) {
+    const opensWithSingleWord = SINGLE_WORD_THEN_SPACE.test(labelText) && blockText.length > labelText.length && blockText.startsWith(labelText);
+    return opensWithSingleWord ? { kind: 'word', label: labelText.trimEnd() } : null;
+}
+function leadInShapeOf(blockText, labelText, quote) {
+    if (quote)
+        return { kind: 'quoted', quote };
+    const delimiterAfterLabel = LEAD_IN_DELIMITERS.find((d) => blockText.startsWith(d, labelText.length));
+    if (delimiterAfterLabel)
+        return { kind: 'before', delimiter: delimiterAfterLabel };
+    return labelRunTailShapeOf(labelText) ?? emphasisedOpeningWordOf(blockText, labelText);
+}
+function isWordBoundary(character) {
+    return character === '' || /\s/.test(character);
+}
+function openingWordSpanOf(text, shape) {
+    const opensWithSameWord = text.startsWith(shape.label) && isWordBoundary(text.charAt(shape.label.length));
+    return opensWithSameWord ? { start: 0, end: shape.label.length } : null;
+}
+function quotedTermSpanOf(text, shape) {
+    const opener = text.slice(0, QUOTED_TERM_OPENER_WINDOW).indexOf(shape.quote);
+    if (opener < 0)
+        return null;
+    const termStart = opener + 1;
+    const close = text.indexOf(shape.quote, termStart);
+    const closesAfterNonEmptyTerm = close > termStart;
+    if (!closesAfterNonEmptyTerm || close > LEAD_IN_MAX_CHARS)
+        return null;
+    return { start: termStart, end: close };
+}
+function nthIndexOf(text, search, occurrence) {
+    let at = -1;
+    for (let seen = 0; seen < occurrence; seen += 1) {
+        at = text.indexOf(search, at + 1);
+        if (at < 0)
+            return -1;
+    }
+    return at;
+}
+function spanThroughSameDelimiterCountOf(text, shape) {
+    const at = nthIndexOf(text, shape.delimiter, shape.occurrence);
+    if (at <= 0 || at > LEAD_IN_MAX_CHARS)
+        return null;
+    return { start: 0, end: at + shape.delimiter.length };
+}
+function spanBeforeDelimiterOf(text, shape) {
+    const end = leadInEndOf(text, shape.delimiter);
+    return end == null ? null : { start: 0, end };
+}
+function labelLeadInSpanOf(text, shape) {
+    switch (shape.kind) {
+        case 'word':
+            return openingWordSpanOf(text, shape);
+        case 'quoted':
+            return quotedTermSpanOf(text, shape);
+        case 'inside':
+            return spanThroughSameDelimiterCountOf(text, shape);
+        case 'before':
+            return spanBeforeDelimiterOf(text, shape);
+    }
+}
+
+exports.LEAD_IN_BODY_SAMPLE_CHARS = LEAD_IN_BODY_SAMPLE_CHARS;
+exports.LEAD_IN_DELIMITERS = LEAD_IN_DELIMITERS;
+exports.LEAD_IN_MAX_CHARS = LEAD_IN_MAX_CHARS;
+exports.LEAD_IN_QUOTES = LEAD_IN_QUOTES;
+exports.labelLeadInSpanOf = labelLeadInSpanOf;
+exports.leadInEndOf = leadInEndOf;
+exports.leadInShapeOf = leadInShapeOf;