@superdoc/sdk 2.27.0-next.9 → 2.28.0

package/dist/agent/actions.cjs

@@ -11,6 +11,8 @@ 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');
+var leadInLabel = require('./lead-in-label.cjs');
+var insertedBlockFormatting = require('./inserted-block-formatting.cjs');
 
 const ACTION_DEFINITIONS = actionDescriptors;
 function projectActionDefinitions(project) {
@@ -2672,10 +2674,9 @@ 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) {
+    for (const key of insertedBlockFormatting.RUN_BOOL_MARKS) {
         if (run[key])
             inline[key] = true;
     }
@@ -5189,112 +5190,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) : leadInLabel.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}[.)])`;
@@ -5454,11 +5351,11 @@ async function listItemRunPattern(doc, text, blockId) {
         return null;
     // 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);
-    let windowEnd = delimiterAt != null ? delimiterAt + LEAD_IN_BODY_SAMPLE_CHARS : LEAD_IN_BODY_SAMPLE_CHARS;
+    const delimiterAt = leadInLabel.leadInEndOf(text);
+    let windowEnd = delimiterAt != null ? delimiterAt + leadInLabel.LEAD_IN_BODY_SAMPLE_CHARS : leadInLabel.LEAD_IN_BODY_SAMPLE_CHARS;
     const typedCaption = typedCaptionSpanOf(text);
     if (typedCaption)
-        windowEnd = Math.max(windowEnd, typedCaption.end + LEAD_IN_BODY_SAMPLE_CHARS);
+        windowEnd = Math.max(windowEnd, typedCaption.end + leadInLabel.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 : [];
@@ -5518,7 +5415,7 @@ function runPatternFromRuns(runs, blockText, runTextOf) {
     // `"` + **Deliverables** + `" means …` — so the label is the SECOND run
     // and the quotes stay unemphasised.
     const opener = runTextOf(runs[0]).trim();
-    const quote = LEAD_IN_QUOTES.find((q) => opener === q);
+    const quote = leadInLabel.LEAD_IN_QUOTES.find((q) => opener === q);
     const labelIndex = quote && runs.length > 2 ? 1 : 0;
     const label = runs[labelIndex];
     const labelText = runTextOf(label);
@@ -5530,8 +5427,8 @@ function runPatternFromRuns(runs, blockText, runTextOf) {
     // would stamp its emphasis across the whole new block.
     const bodyStyle = matchRunStyle(runs[labelIndex + 1]);
     const differs = !sameMatchRunStyle(leadStyle, bodyStyle);
-    const shape = leadInShapeOf(blockText, labelText, labelIndex > 0 ? quote : undefined);
-    const isLabel = differs && shape != null && labelText.length > 0 && labelText.length <= LEAD_IN_MAX_CHARS;
+    const shape = leadInLabel.leadInShapeOf(blockText, labelText, labelIndex > 0 ? quote : undefined);
+    const isLabel = differs && shape != null && labelText.length > 0 && labelText.length <= leadInLabel.LEAD_IN_MAX_CHARS;
     return runPatternOf(bodyStyle, isLabel && shape ? { style: leadStyle, shape } : undefined);
 }
 function typedPrefixLabelOf(runs, runTextOf) {
@@ -5571,9 +5468,9 @@ function typedPrefixLabelOf(runs, runTextOf) {
     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)
+    if (labelText.length === 0 || labelText.length > leadInLabel.LEAD_IN_MAX_CHARS)
         return null;
-    const delimiter = ['.', ...LEAD_IN_DELIMITERS.map((d) => d.trim())].find((d) => labelText.endsWith(d) && labelText.length > d.length);
+    const delimiter = ['.', ...leadInLabel.LEAD_IN_DELIMITERS.map((d) => d.trim())].find((d) => labelText.endsWith(d) && labelText.length > d.length);
     if (!delimiter)
         return null;
     return runPatternOf(matchRunStyle(runs[bodyIndex]), {
@@ -5611,7 +5508,7 @@ function paragraphIndentOf(payload) {
     return null;
 }
 function emphasisedLookOf(look) {
-    return RUN_BOOL_MARKS.some((key) => look[key] === true) ? look : null;
+    return insertedBlockFormatting.RUN_BOOL_MARKS.some((key) => look[key] === true) ? look : null;
 }
 async function effectiveBaseLookOf(doc, text, block) {
     const queryFn = maybeMethod(doc, ['query', 'match']);
@@ -5661,7 +5558,7 @@ function inlineLookFromRow(row) {
  */
 function runInlineAgainstBaseline(marks, baseline) {
     const inline = marksToInline(marks);
-    for (const key of RUN_BOOL_MARKS) {
+    for (const key of insertedBlockFormatting.RUN_BOOL_MARKS) {
         if (baseline[key] === true && inline[key] === undefined)
             inline[key] = false;
     }
@@ -6567,26 +6464,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;
             }
@@ -6636,21 +6519,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)
@@ -6659,60 +6527,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 = insertedBlockFormatting.referenceProbeOf(reference.textPreview ?? '');
     if (!refProbe)
         return null;
-    const refRuns = await docSnapshot.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 = insertedBlockFormatting.leadBodySplitOf(await docSnapshot.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 || insertedBlockFormatting.withoutTruncationEllipsis(createdPreview);
+    const createdLeadLen = insertedBlockFormatting.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,
@@ -6730,21 +6558,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 = insertedBlockFormatting.withoutTruncationEllipsis(reference.textPreview ?? '').trim();
+    const fullText = createdText || insertedBlockFormatting.withoutTruncationEllipsis(created.textPreview ?? '');
     if (!formatFn || !reference.nodeId || !created.nodeId || !referenceText || !fullText)
         return null;
     const pattern = await listItemRunPattern(doc, referenceText, reference.nodeId);
@@ -6756,11 +6573,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 = insertedBlockFormatting.bodyLookToWrite(sampled, own);
     if (Object.keys(body).length > 0) {
         if (await applyInlineQuiet(formatFn, { blockId: created.nodeId, start: 0, end, inline: body })) {
             applied.body = body;
@@ -6786,17 +6599,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 = 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 anchorId = insertedBlockFormatting.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) => guards.isRecord(entry) && (Array.isArray(entry.runs) || entry.marks != null));
+        const rawTexts = insertedBlockFormatting.insertedTextEntriesOf(args);
+        const hasExplicitStyling = insertedBlockFormatting.callerStyledAnEntry(rawTexts);
         const insertedTexts = rawTexts.map((entry) => {
             if (typeof entry === 'string')
                 return entry;
@@ -6804,26 +6610,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, insertedBlockFormatting.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 = guards.isRecord(result?.applied) ? result.applied : null;
-            if (createdRows.length > 1 && (!applied || Object.keys(applied).length === 0)) {
-                const parallel = postBlocks[createdIndex - createdRows.length];
+            if (insertedBlockFormatting.shouldTryParallelGroup(createdRows.length, result)) {
+                const parallel = postBlocks[insertedBlockFormatting.parallelGroupIndexOf(createdIndex, createdRows.length)];
                 if (parallel && preIds.has(parallel.nodeId) && !parallel.isEmpty) {
                     result = (await match(parallel)) ?? result;
                 }
@@ -6831,13 +6623,12 @@ async function matchInsertedBlockFormatting(doc, preBlocks, receipt, args, avail
             if (result)
                 allApplied.push(result);
         }
-        if (allApplied.length === 0)
+        const contextualFormatting = insertedBlockFormatting.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) },