open-agreements 0.7.7 → 0.8.0

package/node_modules/@usejunior/docx-core/dist/primitives/document_view.js

@@ -1,22 +1,28 @@
 import { OOXML, W } from './namespaces.js';
+import { getAttributeSafe, getFirstChild } from './xml-helpers.js';
 import { getParagraphText, getParagraphRuns } from './text.js';
-import { extractListLabel, stripListLabel, LabelType } from './list_labels.js';
+import { getParagraphBookmarkId } from './bookmarks.js';
+import { buildTableMetaMap, deriveTableContext } from './table_context.js';
+import { extractListLabel, stripListLabel } from './list_labels.js';
 import { parseNumberingXml, computeListLabelForParagraph } from './numbering.js';
 import { parseStylesXml, extractParagraphFormatting, extractEffectiveRunFormatting } from './styles.js';
 import { HIGHLIGHT_TAG } from './semantic_tags.js';
 import { computeModalBaseline, computeParagraphFontBaseline, emitFormattingTags, mergeAdjacentTags } from './formatting_tags.js';
 import { isReservedFootnote } from './footnotes.js';
-const SHORT_HEADER_MAX_LENGTH = 50;
-const MAX_HEADER_TEXT_LENGTH = 60;
-const STYLE_EXAMPLE_TEXT_PREVIEW_LENGTH = 50;
+import { deriveHeading, detectRunInHeader, detectTitleCapsCentered, extractHeaderInfo, suppressSignatureClusters, } from './document_view-headings.js';
+import { discoverStyles, fingerprintKey } from './document_view-styles.js';
+import { findTaggedTextInsertionIndex } from './document_view-comments.js';
+export { discoverStyles } from './document_view-styles.js';
+export { INLINE_COMMENT_MARKER_RUNTIME, TOON_INLINE_TAG_RE, collectInlineCommentMarkers, tokenizeToonInline } from './document_view-comments.js';
+export { collectTableMarkerInfo, formatTableMarker, formatToonCommentEndnoteLines, formatToonCommentLines, formatToonCommentsEndnotesBlock, formatToonDataLine, renderToon, renderToonWithCommentEndnotes, } from './document_view-toon.js';
 function getWAttr(el, localName) {
-    return el.getAttributeNS(OOXML.W_NS, localName) ?? el.getAttribute(`w:${localName}`) ?? el.getAttribute(localName);
+    return getAttributeSafe(el, OOXML.W_NS, localName, 'w');
 }
 function runHighlightVal(run) {
-    const rPr = run.getElementsByTagNameNS(OOXML.W_NS, W.rPr).item(0);
+    const rPr = getFirstChild(run, OOXML.W_NS, W.rPr);
     if (!rPr)
         return null;
-    const h = rPr.getElementsByTagNameNS(OOXML.W_NS, W.highlight).item(0);
+    const h = getFirstChild(rPr, OOXML.W_NS, W.highlight);
     if (!h)
         return null;
     const v = getWAttr(h, 'val');
@@ -46,304 +52,55 @@ function emitHighlightTagsFromParagraph(p) {
         out.push(`</${HIGHLIGHT_TAG}>`);
     return out.join('');
 }
-function fingerprintKey(fp) {
-    // Stable JSON-ish key used for Map lookups.
-    return `${fp.list_level}|${fp.left_indent_pt.toFixed(1)}|${fp.first_line_indent_pt.toFixed(1)}|${fp.style_name}|${fp.alignment}`;
-}
-/**
- * v0.3: Compact style fingerprint token.
- * Concatenates style name, list level, alignment, and indentation for token-efficient LLM context.
- * Example: "Normal:L-1:LEFT:I0:H0"
- */
-function computeFingerprintToken(fp, styleId) {
-    const name = styleId || fp.style_name || 'body';
-    const level = `L${fp.list_level}`;
-    const align = fp.alignment;
-    const indent = `I${Math.round(fp.left_indent_pt)}`;
-    const hanging = `H${Math.round(fp.first_line_indent_pt)}`;
-    return `${name}:${level}:${align}:${indent}:${hanging}`;
-}
-// Pattern-based header detection fallback (ported from Python ingestor._extract_header_info).
-const HEADER_PATTERN = /^([A-Z][^.!?:]*(?:\s+[A-Z][^.!?:]*)*)([.:]?)(?:\s|$)/;
-function extractHeaderInfo(cleanText) {
-    if (!cleanText || cleanText.length < 2)
-        return { header_text: null, header_style: null };
-    if (!/^[A-Z]/.test(cleanText))
-        return { header_text: null, header_style: null };
-    const stripped = cleanText.trim();
-    if (stripped.length <= SHORT_HEADER_MAX_LENGTH) {
-        if (stripped.endsWith('.'))
-            return { header_text: stripped.slice(0, -1), header_style: 'title_with_period' };
-        if (stripped.endsWith(':'))
-            return { header_text: stripped.slice(0, -1), header_style: 'title_with_colon' };
-        const words = stripped.split(/\s+/);
-        if (words.length <= 5)
-            return { header_text: stripped, header_style: 'title_bare' };
-        return { header_text: null, header_style: null };
-    }
-    const m = HEADER_PATTERN.exec(stripped);
-    if (!m)
-        return { header_text: null, header_style: null };
-    const headerText = (m[1] ?? '').trim();
-    const terminator = m[2] ?? '';
-    const remaining = stripped.slice(m[0].length);
-    if (!remaining || headerText.length > MAX_HEADER_TEXT_LENGTH)
-        return { header_text: null, header_style: null };
-    if (terminator === '.')
-        return { header_text: headerText, header_style: 'title_with_period' };
-    if (terminator === ':')
-        return { header_text: headerText, header_style: 'title_with_colon' };
-    return { header_text: headerText, header_style: 'title_bare' };
-}
-function detectRunInHeader(params) {
-    const { paragraph, paragraphPPr, paragraphStyleId, styles } = params;
-    const punct = new Set(['.', ':', '-']);
-    // Use visible runs only (field code text stripped in getParagraphRuns()).
-    const runs = getParagraphRuns(paragraph);
-    if (runs.length === 0)
-        return null;
-    // Group by run element, preserving order.
-    const orderedUniqueRuns = [];
-    const seen = new Set();
-    for (const tr of runs) {
-        if (!seen.has(tr.r)) {
-            seen.add(tr.r);
-            orderedUniqueRuns.push(tr.r);
-        }
-    }
-    let headerText = '';
-    let formatting = null;
-    let headerCharCount = 0;
-    for (const r of orderedUniqueRuns) {
-        const fmt = extractEffectiveRunFormatting({ run: r, paragraphPPr, paragraphStyleId, styles });
-        const isHeaderStyle = fmt.bold || fmt.underline;
-        if (!isHeaderStyle)
-            break;
-        // Accumulate run text.
-        const ts = Array.from(r.getElementsByTagNameNS(OOXML.W_NS, W.t));
-        for (const t of ts) {
-            const tc = t.textContent ?? '';
-            headerText += tc;
-            headerCharCount += tc.length;
-        }
-        if (!formatting)
-            formatting = { bold: fmt.bold, italic: fmt.italic, underline: fmt.underline };
-    }
-    const trimmed = headerText.trim();
-    if (!trimmed)
-        return null;
-    if (!punct.has(trimmed[trimmed.length - 1]))
-        return null;
-    if (!formatting)
-        return null;
-    return { raw_text: trimmed, formatting, headerCharCount };
-}
-function inferSemanticName(params) {
-    const { fp, nodes } = params;
-    // Find first label_type if present.
-    let labelType = null;
-    for (const n of nodes) {
-        if (n.list_metadata.label_type) {
-            labelType = n.list_metadata.label_type;
-            break;
-        }
-    }
-    const listLevel = fp.list_level;
-    if (listLevel >= 0) {
-        if (listLevel === 0) {
-            if (labelType === LabelType.ARTICLE)
-                return { base_id: 'article', display_name: 'Article Heading' };
-            if (labelType === LabelType.SECTION)
-                return { base_id: 'section', display_name: 'Section Heading' };
-            if (labelType === LabelType.ROMAN)
-                return { base_id: 'roman_section', display_name: 'Roman Numeral Section' };
-            return { base_id: 'top_level', display_name: 'Top-Level List Item' };
-        }
-        if (listLevel === 1) {
-            if (labelType === LabelType.LETTER)
-                return { base_id: 'subsection', display_name: 'Subsection (a)/(A)' };
-            if (labelType === LabelType.NUMBER)
-                return { base_id: 'subsection_number', display_name: 'Numbered Subsection' };
-            if (labelType === LabelType.ROMAN)
-                return { base_id: 'subsection_roman', display_name: 'Roman Subsection' };
-            return { base_id: 'level_1', display_name: `Level ${listLevel} List Item` };
-        }
-        if (labelType === LabelType.ROMAN)
-            return { base_id: `level_${listLevel}_roman`, display_name: `Level ${listLevel} Roman` };
-        if (labelType === LabelType.LETTER)
-            return { base_id: `level_${listLevel}_letter`, display_name: `Level ${listLevel} Letter` };
-        return { base_id: `level_${listLevel}`, display_name: `Level ${listLevel} List Item` };
-    }
-    // Non-list.
-    const styleName = fp.style_name.toLowerCase().replace(/\s+/g, '_');
-    if (fp.left_indent_pt > 0)
-        return { base_id: 'indent_block', display_name: 'Indented Block' };
-    if (styleName.includes('heading') || styleName.includes('title'))
-        return { base_id: 'heading', display_name: 'Heading' };
-    if (styleName.includes('quote') || styleName.includes('block'))
-        return { base_id: 'block_quote', display_name: 'Block Quote' };
-    return { base_id: 'body', display_name: 'Body Text' };
-}
-export function discoverStyles(nodes) {
-    const groups = new Map();
-    for (const n of nodes) {
-        const key = fingerprintKey(n.style_fingerprint);
-        const g = groups.get(key);
-        if (g)
-            g.nodes.push(n);
-        else
-            groups.set(key, { fp: n.style_fingerprint, nodes: [n] });
-    }
-    const used = {};
-    const styles = new Map();
-    const fpToStyle = new Map();
-    for (const [fpKey, g] of groups.entries()) {
-        const { base_id, display_name } = inferSemanticName({ fp: g.fp, nodes: g.nodes });
-        let styleId = base_id;
-        if (used[base_id] !== undefined) {
-            used[base_id] += 1;
-            styleId = `${base_id}_${used[base_id]}`;
-        }
-        else {
-            used[base_id] = 0;
-        }
-        const median = g.nodes[Math.floor(g.nodes.length / 2)];
-        const info = {
-            style_id: styleId,
-            display_name,
-            fingerprint: g.fp,
-            example_node_id: median.id,
-            example_text: median.clean_text.slice(0, STYLE_EXAMPLE_TEXT_PREVIEW_LENGTH),
-            count: g.nodes.length,
-            dominant_alignment: g.fp.alignment,
-        };
-        styles.set(styleId, info);
-        fpToStyle.set(fpKey, styleId);
-    }
-    return { styles, fingerprint_to_style: fpToStyle };
-}
-function headerStripFromText(params) {
-    // Mirrors Python TOONRenderer header stripping.
-    const { header } = params;
-    let { text } = params;
-    if (!header)
-        return text;
-    const headerNorm = header.trim().toLowerCase();
-    const textLower = text.toLowerCase();
-    for (const punct of [':', '.', '-', ';', '']) {
-        const testPrefix = `${headerNorm}${punct}`;
-        if (textLower.startsWith(testPrefix)) {
-            text = text.slice(testPrefix.length).trimStart();
-            return text;
-        }
-    }
-    if (text.startsWith(header)) {
-        text = text.slice(header.length).replace(/^[.:\-;]+/, '').trimStart();
-    }
-    return text;
-}
-/**
- * Format a single toon data line for one DocumentViewNode.
- * Handles table-context-aware style (th/td) and header stripping.
- */
-export function formatToonDataLine(n, options) {
-    let text = n.tagged_text;
-    if (n.header)
-        text = headerStripFromText({ header: n.header, text });
-    let header = n.header;
-    if (header && !text) {
-        text = header;
-        header = '';
-    }
-    const tc = n.table_context;
-    let style;
-    if (tc) {
-        style = tc.is_header_row
-            ? `th(${tc.row_index},${tc.col_index})`
-            : `td(${tc.row_index},${tc.col_index})`;
-    }
-    else {
-        style = options?.compact
-            ? computeFingerprintToken(n.style_fingerprint, n.style)
-            : n.style;
-    }
-    return `${n.id} | ${n.list_label} | ${header} | ${style} | ${text}`;
-}
 /**
- * Collect table marker info (dimensions) from nodes for #TABLE markers.
- * Column headers are NOT included in the marker — they appear once in the th() rows.
+ * Collect the bookmarked paragraphs of a document, each with its derived table
+ * context, in document order. This is the shared paragraph-collection core used
+ * by BOTH `DocxDocument.buildDocumentView()` and the free `buildDocumentView()`
+ * so the two produce identical node sets.
+ *
+ * Only paragraphs carrying a `_bk_*` bookmark id are included (the document view
+ * addresses nodes by that id). This function does NOT insert bookmarks — a
+ * consumer operating on un-bookmarked source DOCX MUST call
+ * `DocxDocument.insertParagraphBookmarks()` first, or the result is empty.
  */
-export function collectTableMarkerInfo(nodes) {
-    const info = new Map();
-    for (const n of nodes) {
-        const tc = n.table_context;
-        if (!tc)
-            continue;
-        if (!info.has(tc.table_index)) {
-            info.set(tc.table_index, {
-                id: tc.table_id,
-                totalRows: tc.total_rows,
-                totalCols: tc.total_cols,
-            });
-        }
-    }
-    return info;
+export function collectViewParagraphs(documentXml) {
+    const body = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.body).item(0);
+    if (!body)
+        return [];
+    const tableMetaMap = buildTableMetaMap(body);
+    return Array.from(body.getElementsByTagNameNS(OOXML.W_NS, W.p))
+        .map((p) => {
+        const id = getParagraphBookmarkId(p);
+        if (!id)
+            return null;
+        const tableContext = deriveTableContext(p, tableMetaMap);
+        return tableContext ? { id, p, tableContext } : { id, p };
+    })
+        .filter((x) => x !== null);
 }
 /**
- * Format a #TABLE marker line from collected table info.
- * Headers are omitted — they appear exactly once in the th(0,N) data rows.
+ * Free function form of the document-view builder. Delegates to the same shared
+ * core (`collectViewParagraphs` + `buildNodesForDocumentView`) as
+ * `DocxDocument.buildDocumentView()`, so it returns populated nodes — one per
+ * bookmarked paragraph — rather than the empty stub it used to be.
+ *
+ * Like the method, it includes only paragraphs carrying a `_bk_*` bookmark id
+ * and does NOT insert bookmarks itself.
  */
-export function formatTableMarker(info) {
-    return `#TABLE ${info.id} | ${info.totalRows} rows × ${info.totalCols} cols`;
-}
-export function renderToon(nodes, options = {}) {
-    const lines = ['#SCHEMA id | list_label | header | style | text'];
-    // Pre-scan: collect table marker info for #TABLE lines
-    const tableInfo = collectTableMarkerInfo(nodes);
-    let currentTableIndex = null;
-    for (const n of nodes) {
-        const tc = n.table_context;
-        const nodeTableIndex = tc ? tc.table_index : null;
-        // Close previous table if we left it or moved to a different table
-        if (currentTableIndex !== null && nodeTableIndex !== currentTableIndex) {
-            lines.push('#END_TABLE');
-            currentTableIndex = null;
-        }
-        // Open new table if entering one
-        if (nodeTableIndex !== null && currentTableIndex === null) {
-            const info = tableInfo.get(nodeTableIndex);
-            if (info)
-                lines.push(formatTableMarker(info));
-            currentTableIndex = nodeTableIndex;
-        }
-        lines.push(formatToonDataLine(n, options));
-    }
-    // Close any open table at end
-    if (currentTableIndex !== null) {
-        lines.push('#END_TABLE');
-    }
-    return lines.join('\n');
-}
 export function buildDocumentView(params) {
-    const { documentXml, stylesXml, numberingXml, opts } = params;
-    const includeSemantic = opts?.include_semantic_tags ?? true;
-    void includeSemantic;
-    const stylesModel = parseStylesXml(stylesXml);
-    void stylesModel;
-    const numberingModel = parseNumberingXml(numberingXml);
-    void numberingModel;
-    const counters = new Map();
-    void counters;
-    const body = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.body).item(0);
-    if (!body)
-        return { nodes: [], styles: { styles: new Map(), fingerprint_to_style: new Map() } };
-    const paragraphs = Array.from(body.getElementsByTagNameNS(OOXML.W_NS, W.p));
-    const nodes = [];
-    for (const p of paragraphs) {
-        const prev = p.previousSibling;
-        void prev;
-    }
-    return { nodes, styles: { styles: new Map(), fingerprint_to_style: new Map() } };
+    const { documentXml, stylesXml, numberingXml, footnotesXml, relsMap, opts } = params;
+    const paragraphs = collectViewParagraphs(documentXml);
+    return buildNodesForDocumentView({
+        paragraphs,
+        stylesXml,
+        numberingXml,
+        include_semantic_tags: opts?.include_semantic_tags ?? true,
+        show_formatting: opts?.show_formatting ?? false,
+        formatting_mode: opts?.formatting_mode ?? 'compact',
+        relsMap,
+        documentXml,
+        footnotesXml: footnotesXml ?? null,
+    });
 }
 // ── Helpers for building AnnotatedRun arrays ─────────────────────────
 /**
@@ -357,9 +114,7 @@ function resolveRunHyperlinkUrl(runEl, relsMap) {
     if (!parent || parent.localName !== W.hyperlink)
         return null;
     // r:id attribute can be namespaced or prefixed.
-    const rId = parent.getAttributeNS(OOXML.R_NS, 'id') ??
-        parent.getAttribute('r:id') ??
-        null;
+    const rId = getAttributeSafe(parent, OOXML.R_NS, 'id', 'r', { bareFallback: false });
     if (!rId)
         return null;
     return relsMap.get(rId) ?? null;
@@ -439,9 +194,11 @@ function buildFootnoteDisplayMap(documentXml, footnotesXml) {
     return map;
 }
 /**
- * Compute footnote marker insertion points for a paragraph.
- * Returns an array of { offset, marker } sorted by offset descending
- * for safe right-to-left insertion into the text string.
+ * Compute the footnote references a paragraph visibly anchors, in document
+ * order. This is the single derivation of "which footnotes does this paragraph
+ * reference, and with what display number" — the view injects [^N] markers
+ * from it AND exposes it as DocumentViewNode.footnote_refs so consumers
+ * (read_file's clean_text suffix) never re-walk the DOM. @see #393
  *
  * Self-contained: only inspects the paragraph DOM for w:footnoteReference
  * elements. Does NOT modify getParagraphRuns or getParagraphText.
@@ -500,28 +257,85 @@ function getFootnoteMarkersForParagraph(p, displayMap) {
             if (displayNum != null) {
                 markers.push({
                     offset: visibleOffset + runVisibleLen,
-                    marker: `[^${displayNum}]`,
+                    id: footnoteId,
+                    display: displayNum,
                 });
             }
         }
         visibleOffset += runVisibleLen;
     }
-    // Sort descending by offset for safe right-to-left insertion
-    markers.sort((a, b) => b.offset - a.offset);
     return markers;
 }
 /**
- * Inject footnote markers into a text string at the given offsets.
- * Markers must be sorted descending by offset.
+ * Paragraph content that makes a text-empty paragraph meaningful on its own:
+ * an endnote or comment anchored to the paragraph (the comment range markers
+ * are what `getComments` resolves `anchored_paragraph_id`/`end_paragraph_id`
+ * from, so dropping their paragraph leaves a dangling anchor ID no node_ids
+ * probe can resolve), or embedded visual content (DrawingML drawing, VML
+ * picture, embedded object). Dropping such a paragraph from the document view
+ * severs the anchored note/comment from every read surface and silently
+ * hides images.
+ *
+ * Footnote references are handled separately via the display map so their
+ * [^N] markers render; the shapes here only need the node to exist.
+ * @see #383
+ */
+const ANCHORING_CONTENT = [
+    W.endnoteReference,
+    W.commentReference,
+    W.commentRangeStart,
+    W.commentRangeEnd,
+    W.drawing,
+    W.pict,
+    W.object,
+];
+/**
+ * True when `el` sits inside a `w:del` or `w:moveFrom` revision wrapper below
+ * the paragraph. Deleted/moved-from content is invisible to the view's text
+ * extraction (`getParagraphText` reads `w:t`, never `w:delText`), so an
+ * anchor that only survives inside a tracked deletion — e.g. the
+ * `w:commentReference` a tracked comment-delete leaves under `w:del` — must
+ * not resurrect its paragraph as a blank visible node.
+ */
+function isInsideRemovedRevisionWrapper(el, paragraph) {
+    let cur = el.parentNode;
+    while (cur && cur !== paragraph) {
+        if (cur.namespaceURI === OOXML.W_NS && (cur.localName === W.del || cur.localName === W.moveFrom)) {
+            return true;
+        }
+        cur = cur.parentNode;
+    }
+    return false;
+}
+function paragraphHasAnchoringContent(p) {
+    return ANCHORING_CONTENT.some((localName) => {
+        const els = p.getElementsByTagNameNS(OOXML.W_NS, localName);
+        for (let i = 0; i < els.length; i++) {
+            if (!isInsideRemovedRevisionWrapper(els.item(i), p))
+                return true;
+        }
+        return false;
+    });
+}
+/**
+ * Inject [^N] footnote markers into a text string at the given offsets.
+ * Markers arrive in document order; insertion happens right-to-left (offset
+ * descending) so earlier offsets stay valid as text grows.
+ *
+ * Offsets are *visible*-character offsets (they count document text, not the inline
+ * formatting tags emitted by `emitFormattingTags`). When `text` carries formatting tags
+ * we therefore map each visible offset to a tag-aware insertion index, exactly as the
+ * comment-marker path does (`findTaggedTextInsertionIndex`). A naive `slice(offset)` would
+ * land the `[^n]` marker inside a tag or mid-word once formatting is present.
  */
 function injectFootnoteMarkers(text, markers) {
     if (markers.length === 0)
         return text;
+    const descending = [...markers].sort((a, b) => b.offset - a.offset);
     let result = text;
-    for (const { offset, marker } of markers) {
-        // Clamp offset to text length
-        const pos = Math.min(offset, result.length);
-        result = result.slice(0, pos) + marker + result.slice(pos);
+    for (const { offset, display } of descending) {
+        const insertionIndex = findTaggedTextInsertionIndex(result, offset);
+        result = result.slice(0, insertionIndex) + `[^${display}]` + result.slice(insertionIndex);
     }
     return result;
 }
@@ -544,7 +358,7 @@ export function buildNodesForDocumentView(params) {
     const allBodyRuns = [];
     if (showFormatting) {
         for (const { p } of paragraphs) {
-            const paraPPr = p.getElementsByTagNameNS(OOXML.W_NS, W.pPr).item(0);
+            const paraPPr = getFirstChild(p, OOXML.W_NS, W.pPr);
             const paraFmt = extractParagraphFormatting(paraPPr ?? null, stylesModel);
             const runs = buildAnnotatedRuns({
                 p,
@@ -593,20 +407,39 @@ export function buildNodesForDocumentView(params) {
     const nodes = [];
     for (let idx = 0; idx < paragraphs.length; idx++) {
         const { id, p, tableContext } = paragraphs[idx];
-        const paraPPr = p.getElementsByTagNameNS(OOXML.W_NS, W.pPr).item(0);
+        const paraPPr = getFirstChild(p, OOXML.W_NS, W.pPr);
         const paraFmt = extractParagraphFormatting(paraPPr ?? null, stylesModel);
+        // Raw visible text (field codes stripped, but NOT CR/LF-stripped or trimmed).
+        // This is the coordinate system `replaceParagraphTextRange`/`replaceTextAtRange`
+        // operate in; it is carried on the node so the clean_text → raw offset map can
+        // be rebuilt deterministically. @see buildCleanToRawOffsetMap
+        const rawText = getParagraphText(p);
         // Visible clean text (field codes stripped).
-        const fullText = getParagraphText(p).replace(/\r/g, '').replace(/\n/g, '').trim();
-        // Preserve empty table cell paragraphs for structural completeness.
-        if (!fullText && !tableContext)
+        const fullText = rawText.replace(/\r/g, '').replace(/\n/g, '').trim();
+        // Computed once per paragraph: gates the empty-paragraph skip below, drives
+        // the [^N] marker injection, and is exposed as node.footnote_refs.
+        const fnMarkers = getFootnoteMarkersForParagraph(p, footnoteDisplayMap);
+        // Preserve empty table cell paragraphs for structural completeness, and
+        // text-empty paragraphs that carry anchoring content — a visible footnote
+        // reference (its [^N] marker renders via the injection pass below), an
+        // endnote reference, a comment reference or comment range marker, or an
+        // embedded drawing/picture/object. Dropping those loses the anchored
+        // note/comment/image from every rendering of the document view. Anchors
+        // that survive only inside a tracked deletion don't count, and paragraphs
+        // that are empty for spacing only are still skipped.
+        // @see #185, #383
+        if (!fullText &&
+            !tableContext &&
+            fnMarkers.length === 0 &&
+            !paragraphHasAnchoringContent(p))
             continue;
         // Numbering (auto-numbered) info from numPr.
         let numId = null;
         let ilvl = null;
-        const numPr = paraPPr ? paraPPr.getElementsByTagNameNS(OOXML.W_NS, W.numPr).item(0) : null;
+        const numPr = paraPPr ? getFirstChild(paraPPr, OOXML.W_NS, W.numPr) : null;
         if (numPr) {
-            const numIdEl = numPr.getElementsByTagNameNS(OOXML.W_NS, W.numId).item(0);
-            const ilvlEl = numPr.getElementsByTagNameNS(OOXML.W_NS, W.ilvl).item(0);
+            const numIdEl = getFirstChild(numPr, OOXML.W_NS, W.numId);
+            const ilvlEl = getFirstChild(numPr, OOXML.W_NS, W.ilvl);
             const numIdVal = numIdEl ? getWAttr(numIdEl, 'val') : null;
             const ilvlVal = ilvlEl ? getWAttr(ilvlEl, 'val') : null;
             if (numIdVal)
@@ -649,7 +482,13 @@ export function buildNodesForDocumentView(params) {
         let headerFormatting = null;
         let headerCharCount = 0;
         try {
-            const hdr = detectRunInHeader({ paragraph: p, paragraphPPr: paraPPr ?? null, paragraphStyleId: paraFmt.styleId, styles: stylesModel });
+            // Skip in-table run-in header detection — table cells are key/value
+            // layout and a bold prefix is a label, not a section heading.
+            // Mirrors the !tableContext gates on detectTitleCapsCentered and
+            // extractHeaderInfo below.
+            const hdr = tableContext
+                ? null
+                : detectRunInHeader({ paragraph: p, paragraphPPr: paraPPr ?? null, paragraphStyleId: paraFmt.styleId, styles: stylesModel });
             if (hdr) {
                 headerText = hdr.raw_text.replace(/[.:\-]+$/g, '');
                 headerStyle = 'run_in_header';
@@ -660,11 +499,39 @@ export function buildNodesForDocumentView(params) {
         catch {
             // ignore
         }
-        if (!headerText) {
+        // Centered ALL-CAPS bold standalone titles (e.g. an NVCA SPA's
+        // `SERIES […] PREFERRED STOCK PURCHASE AGREEMENT`). Runs before
+        // extractHeaderInfo so the documented precedence (title_caps_centered
+        // outranks short standalone title_bare/title_with_period/title_with_colon)
+        // matches the implementation. Only fires when run_in_header did not match
+        // AND the paragraph has no list label AND is not in a table cell. The
+        // try/catch is defensive against malformed XML in user documents.
+        if (!headerText && !labelString && !tableContext) {
+            try {
+                const titleHdr = detectTitleCapsCentered({
+                    paragraph: p,
+                    paragraphPPr: paraPPr ?? null,
+                    paragraphStyleId: paraFmt.styleId,
+                    alignment: paraFmt.alignment,
+                    cleanTextNoLabel,
+                    styles: stylesModel,
+                });
+                if (titleHdr) {
+                    headerText = titleHdr.raw_text;
+                    headerStyle = 'title_caps_centered';
+                    headerFormatting = titleHdr.formatting;
+                }
+            }
+            catch {
+                // ignore: malformed run/style data falls through to extractHeaderInfo.
+            }
+        }
+        if (!headerText && !tableContext) {
             const fallback = extractHeaderInfo(cleanTextNoLabel);
             headerText = fallback.header_text;
             headerStyle = fallback.header_style;
         }
+        const heading = deriveHeading(paraFmt.styleId, cleanTextNoLabel, headerText, headerStyle, tableContext != null);
         // ── Tag emission ──
         let tagged = cleanTextNoLabel;
         if (showFormatting) {
@@ -721,7 +588,7 @@ export function buildNodesForDocumentView(params) {
             }
             // Emit formatting tags from run-level metadata.
             const paraFontBaseline = computeParagraphFontBaseline(bodyRuns, { formattingMode });
-            tagged = emitFormattingTags({ runs: bodyRuns, baseline: docBaseline, fontBaseline: paraFontBaseline });
+            tagged = emitFormattingTags({ runs: bodyRuns, baseline: docBaseline, fontBaseline: paraFontBaseline, formattingMode });
             tagged = mergeAdjacentTags(tagged);
         }
         else if (includeSemantic) {
@@ -774,10 +641,13 @@ export function buildNodesForDocumentView(params) {
             bodyFmt = null;
         }
         // Inject footnote [^N] markers into view text (view-only, not shared text primitives)
-        const fnMarkers = getFootnoteMarkersForParagraph(p, footnoteDisplayMap);
         if (fnMarkers.length > 0) {
             tagged = injectFootnoteMarkers(tagged, fnMarkers);
         }
+        // Visible characters stripped from the raw paragraph head when extracting a manual
+        // label (label text + trailing whitespace). Auto-numbered paragraphs leave fullText
+        // intact, so this is 0 for them.
+        const visibleOffsetCorrection = isAutoNumbered ? 0 : Math.max(0, fullText.length - cleanTextNoLabel.length);
         const node = {
             id,
             list_label: labelString,
@@ -785,7 +655,9 @@ export function buildNodesForDocumentView(params) {
             style: '', // filled after style discovery
             text: tagged, // filled after header stripping at render time
             clean_text: cleanTextNoLabel,
+            raw_text: rawText,
             tagged_text: tagged,
+            visible_offset_correction: visibleOffsetCorrection > 0 ? visibleOffsetCorrection : undefined,
             list_metadata: {
                 list_level: listLevel,
                 label_type: labelType,
@@ -804,10 +676,16 @@ export function buildNodesForDocumentView(params) {
             header_formatting: headerFormatting,
             body_run_formatting: bodyFmt,
         };
+        if (heading)
+            node.heading = heading;
+        if (fnMarkers.length > 0) {
+            node.footnote_refs = fnMarkers.map(({ id: fnId, display }) => ({ id: fnId, display }));
+        }
         if (tableContext)
             node.table_context = tableContext;
         nodes.push(node);
     }
+    suppressSignatureClusters(nodes);
     const styles = discoverStyles(nodes);
     for (const n of nodes) {
         const sid = styles.fingerprint_to_style.get(fingerprintKey(n.style_fingerprint));
@@ -816,4 +694,87 @@ export function buildNodesForDocumentView(params) {
     }
     return { nodes, styles };
 }
+// ── clean_text → raw offset map (the #1 offset hazard, centralized) ──
+//
+// Selector patterns are authored against the stable, normalized `clean_text`,
+// but mutation (`replaceParagraphTextRange` / `DocxDocument.replaceTextAtRange`)
+// operates on RAW offsets — `getParagraphText(p)` coordinates. `clean_text` is
+// derived from `raw_text` by removing CR/LF, trimming leading/trailing
+// whitespace, and (for manually-labelled list paragraphs) stripping the label
+// prefix. Each removed character shifts every following offset, so a scalar
+// correction (`visible_offset_correction`) is insufficient when CR/LF appear in
+// the interior. This builds a per-character map so a matched clean-text span can
+// be translated to exact raw offsets.
+//
+// `clean_text` does NOT collapse internal whitespace (that lives only in
+// `computeContentFingerprint`), so the map deliberately does not handle that.
+/**
+ * Build a `clean_text → raw_text` offset map for a node. The returned array has
+ * length `clean_text.length + 1`: index `o` (a clean-text offset, `0..length`)
+ * holds the corresponding raw-text offset. A clean span `[cs, ce)` therefore
+ * maps to the raw span `[map[cs], map[ce])`, ready for `replaceTextAtRange`.
+ *
+ * When `node.raw_text` is absent (legacy hand-built fixtures), the map is the
+ * identity — callers operating on real builder output always have `raw_text`.
+ */
+export function buildCleanToRawOffsetMap(node) {
+    const clean = node.clean_text;
+    const raw = node.raw_text;
+    // Identity fallback when raw text is unavailable.
+    if (raw === undefined) {
+        const map = new Array(clean.length + 1);
+        for (let i = 0; i <= clean.length; i++)
+            map[i] = i;
+        return map;
+    }
+    // Phase A: drop CR/LF, recording the raw index of every surviving character.
+    const survivingRawIdx = [];
+    let stripped = '';
+    for (let i = 0; i < raw.length; i++) {
+        const c = raw[i];
+        if (c === '\r' || c === '\n')
+            continue;
+        stripped += c;
+        survivingRawIdx.push(i);
+    }
+    // Phase B: trim leading/trailing whitespace (String.prototype.trim semantics,
+    // matching the `.trim()` in the clean_text derivation).
+    const leadingTrim = stripped.length - stripped.replace(/^\s+/, '').length;
+    const trimmed = stripped.trim();
+    const fullRawIdx = survivingRawIdx.slice(leadingTrim, leadingTrim + trimmed.length);
+    // Phase C: manual-list-label prefix. `clean_text` is a front-stripped suffix
+    // of the trimmed full text, so locate where it begins.
+    let prefixLen = 0;
+    if (clean.length <= trimmed.length && trimmed.endsWith(clean)) {
+        prefixLen = trimmed.length - clean.length;
+    }
+    else {
+        const idx = trimmed.indexOf(clean);
+        prefixLen = idx >= 0 ? idx : 0;
+    }
+    const cleanRawIdx = fullRawIdx.slice(prefixLen, prefixLen + clean.length);
+    const map = new Array(clean.length + 1);
+    for (let o = 0; o < clean.length; o++) {
+        map[o] = cleanRawIdx[o] ?? o;
+    }
+    // End offset (one past the last clean char).
+    if (clean.length === 0) {
+        map[0] = fullRawIdx[0] ?? survivingRawIdx[0] ?? 0;
+    }
+    else {
+        const lastRaw = cleanRawIdx[clean.length - 1];
+        map[clean.length] = (lastRaw ?? clean.length - 1) + 1;
+    }
+    return map;
+}
+/**
+ * Translate a single `clean_text` offset to its `raw_text` offset for a node.
+ * Convenience wrapper over {@link buildCleanToRawOffsetMap}; for translating
+ * many offsets on one node, build the map once and index it directly.
+ */
+export function cleanToRawOffset(node, cleanOffset) {
+    const map = buildCleanToRawOffsetMap(node);
+    const clamped = Math.max(0, Math.min(cleanOffset, map.length - 1));
+    return map[clamped];
+}
 //# sourceMappingURL=document_view.js.map