open-agreements
Version:
Open-source legal template filling CLI and library
885 lines • 38.4 kB
JavaScript
import { DocxZip } from './zip.js';
import { parseXml, serializeXml } from './xml.js';
import { maybeCaptureEmittedDocumentXml } from './schema-corpus-capture.js';
import { OOXML, W } from './namespaces.js';
import { createWmlElement, isW, getDirectChildrenByName } from './dom-helpers.js';
import { findParagraphByBookmarkId, insertParagraphBookmarks, cleanupInternalBookmarks, getParagraphBookmarkId, insertSingleParagraphBookmark, } from './bookmarks.js';
import { getParagraphRuns, getParagraphText, replaceParagraphTextRange } from './text.js';
import { allocateRevisionId, createRevisionContainer, } from './track-changes-emitter.js';
import { buildNodesForDocumentView, collectViewParagraphs } from './document_view.js';
import { serializeToMarkdown } from './serialize_markdown.js';
import { serializeToHtml } from './serialize_html.js';
import { serializeToPlainText } from './serialize_plaintext.js';
import { parseStylesXml } from './styles.js';
import { parseNumberingXml } from './numbering.js';
import { findUniqueSubstringMatch } from './matching.js';
import { parseDocumentRels } from './relationships.js';
import { setParagraphSpacing, setTableCellPadding, setTableRowHeight, } from './layout.js';
import { extractTables, } from './tables.js';
import { mergeRuns } from './merge_runs.js';
import { restoreUntouchedBlocks } from './minimal_save.js';
import { simplifyRedlines } from './simplify_redlines.js';
import { preventDoubleElevation } from './prevent_double_elevation.js';
import { validateDocument } from './validate_document.js';
import { validateAiRevisions as validateAiRevisionsImpl, } from './validate_ai_revisions.js';
import { enumerateRevisionStoryPartPaths, REVISION_STORY_PART_PATHS, } from './revision-parts.js';
import { acceptChanges as acceptChangesImpl } from './accept_changes.js';
import { rejectChanges as rejectChangesImpl } from './reject_changes.js';
import { bootstrapCommentParts, addComment as addCommentImpl, addCommentReply as addCommentReplyImpl, getComments as getCommentsImpl, getComment as getCommentImpl, deleteComment as deleteCommentImpl, } from './comments.js';
import { bootstrapFootnoteParts, getFootnotes as getFootnotesImpl, getFootnote as getFootnoteImpl, addFootnote as addFootnoteImpl, updateFootnoteText as updateFootnoteTextImpl, deleteFootnote as deleteFootnoteImpl, } from './footnotes.js';
function emptyAcceptChangesResult() {
return { insertionsAccepted: 0, deletionsAccepted: 0, movesResolved: 0, propertyChangesResolved: 0 };
}
function hasAcceptedChanges(result) {
return (result.insertionsAccepted > 0 ||
result.deletionsAccepted > 0 ||
result.movesResolved > 0 ||
result.propertyChangesResolved > 0);
}
function addAcceptChangesResult(total, result) {
total.insertionsAccepted += result.insertionsAccepted;
total.deletionsAccepted += result.deletionsAccepted;
total.movesResolved += result.movesResolved;
total.propertyChangesResolved += result.propertyChangesResolved;
}
function emptyRejectChangesResult() {
return { insertionsRemoved: 0, deletionsRestored: 0, movesReverted: 0, propertyChangesReverted: 0 };
}
function hasRejectedChanges(result) {
return (result.insertionsRemoved > 0 ||
result.deletionsRestored > 0 ||
result.movesReverted > 0 ||
result.propertyChangesReverted > 0);
}
function addRejectChangesResult(total, result) {
total.insertionsRemoved += result.insertionsRemoved;
total.deletionsRestored += result.deletionsRestored;
total.movesReverted += result.movesReverted;
total.propertyChangesReverted += result.propertyChangesReverted;
}
function parseWId(el) {
const idStr = el.getAttributeNS(OOXML.W_NS, 'id') ?? el.getAttribute('w:id');
if (!idStr)
return null;
const n = parseInt(idStr, 10);
return Number.isNaN(n) ? null : n;
}
function collectLiveFootnoteRefIds(doc) {
const ids = new Set();
const refs = doc.getElementsByTagNameNS(OOXML.W_NS, W.footnoteReference);
for (let i = 0; i < refs.length; i++) {
const id = parseWId(refs.item(i));
if (id !== null)
ids.add(id);
}
return ids;
}
// Side-effect of accept/reject on document.xml: a body w:footnoteReference that
// lived inside a removed w:del (accept) or w:ins (reject) is gone afterwards.
// The corresponding <w:footnote w:id=N> in footnotes.xml is then unreachable —
// remove it so the side part matches the post-sweep body. Reserved separator /
// continuationSeparator entries are preserved unconditionally.
function pruneOrphanedFootnotes(footnotesDoc, liveRefIds) {
const entries = Array.from(footnotesDoc.getElementsByTagNameNS(OOXML.W_NS, W.footnote));
let pruned = 0;
for (const fn of entries) {
const typ = fn.getAttributeNS(OOXML.W_NS, 'type') ?? fn.getAttribute('w:type');
if (typ === W.separator || typ === W.continuationSeparator)
continue;
const id = parseWId(fn);
if (id === null)
continue;
if (liveRefIds.has(id))
continue;
fn.parentNode?.removeChild(fn);
pruned++;
}
return pruned;
}
function prevElementSibling(node) {
let cur = node?.previousSibling ?? null;
while (cur) {
if (cur.nodeType === 1)
return cur;
cur = cur.previousSibling;
}
return null;
}
function nextElementSibling(node) {
let cur = node?.nextSibling ?? null;
while (cur) {
if (cur.nodeType === 1)
return cur;
cur = cur.nextSibling;
}
return null;
}
export class DocxDocument {
zip;
documentXml;
stylesXml;
numberingXml;
footnotesXml;
relsMap;
dirty;
documentViewCache;
/**
* Raw document.xml text as loaded, before normalize()/edits mutate the DOM.
* Reference for minimal re-serialization in toBuffer(); null for instances
* not created via load().
*/
originalDocumentXmlText;
constructor(zip, documentXml, stylesXml, numberingXml, footnotesXml, relsMap, originalDocumentXmlText = null) {
this.zip = zip;
this.documentXml = documentXml;
this.stylesXml = stylesXml;
this.numberingXml = numberingXml;
this.footnotesXml = footnotesXml;
this.relsMap = relsMap;
this.dirty = false;
this.documentViewCache = null;
this.originalDocumentXmlText = originalDocumentXmlText;
}
static async load(buffer) {
const zip = await DocxZip.load(buffer);
const xml = await zip.readText('word/document.xml');
const doc = parseXml(xml);
// Optional parts used for fidelity: list labels + style fingerprints.
const stylesText = await zip.readTextOrNull('word/styles.xml');
const numberingText = await zip.readTextOrNull('word/numbering.xml');
const stylesXml = stylesText ? parseXml(stylesText) : null;
const numberingXml = numberingText ? parseXml(numberingText) : null;
// Load footnotes for [^N] marker rendering in document view.
const footnotesText = await zip.readTextOrNull('word/footnotes.xml');
const footnotesXml = footnotesText ? parseXml(footnotesText) : null;
// Load document relationships for hyperlink resolution.
const relsText = await zip.readTextOrNull('word/_rels/document.xml.rels');
const relsMap = relsText ? parseDocumentRels(parseXml(relsText)) : new Map();
return new DocxDocument(zip, doc, stylesXml, numberingXml, footnotesXml, relsMap, xml);
}
getParagraphs() {
const body = this.documentXml.getElementsByTagNameNS(OOXML.W_NS, W.body).item(0);
if (!body)
return [];
return Array.from(body.getElementsByTagNameNS(OOXML.W_NS, W.p));
}
getParagraphElementById(bookmarkId) {
return findParagraphByBookmarkId(this.documentXml, bookmarkId);
}
getParagraphTextById(bookmarkId) {
const p = this.getParagraphElementById(bookmarkId);
if (!p)
return null;
return getParagraphText(p);
}
insertParagraphBookmarks(attachmentId) {
const res = insertParagraphBookmarks(this.documentXml, attachmentId);
if (res.indexedParagraphs > 0)
this.dirty = true;
return { paragraphCount: res.indexedParagraphs };
}
/**
* Normalize the document by merging format-identical adjacent runs and
* consolidating adjacent same-author tracked-change wrappers.
* Should be called BEFORE bookmark allocation.
*/
normalize() {
const mr = mergeRuns(this.documentXml);
const sr = simplifyRedlines(this.documentXml);
// Prevent double elevation in footnote/endnote reference styles
let de = { doubleElevationsFixed: 0 };
if (this.stylesXml) {
de = preventDoubleElevation(this.stylesXml);
if (de.doubleElevationsFixed > 0) {
this.zip.writeText('word/styles.xml', serializeXml(this.stylesXml));
}
}
if (mr.runsMerged > 0 || sr.wrappersConsolidated > 0 || de.doubleElevationsFixed > 0) {
this.dirty = true;
this.documentViewCache = null;
}
return {
runsMerged: mr.runsMerged,
proofErrRemoved: mr.proofErrRemoved,
wrappersConsolidated: sr.wrappersConsolidated,
doubleElevationsFixed: de.doubleElevationsFixed,
};
}
/**
* Validate structural integrity of the document.
* Non-destructive, read-only check.
*/
validate() {
return validateDocument(this.documentXml);
}
async validateAiRevisions(aiAuthor, touched) {
const stories = [{ part: 'word/document.xml', doc: this.documentXml }];
for (const partPath of enumerateRevisionStoryPartPaths(this.zip)) {
const xml = await this.zip.readTextOrNull(partPath);
if (!xml)
continue;
stories.push({ part: partPath, doc: parseXml(xml) });
}
return validateAiRevisionsImpl({
aiAuthor,
stories,
packageZip: this.zip,
touched,
});
}
/**
* Accept all tracked changes in document.xml plus supported revisionable
* side-story parts, producing clean XML with no revision markup.
*/
async acceptChanges() {
const total = emptyAcceptChangesResult();
const bodyResult = acceptChangesImpl(this.documentXml);
addAcceptChangesResult(total, bodyResult);
// After accepting, footnotes whose body reference lived inside a removed
// w:del are orphaned. Only worth checking when the body sweep removed
// deletions (the only operation that can drop a footnoteReference).
const liveFootnoteRefIds = bodyResult.deletionsAccepted > 0
? collectLiveFootnoteRefIds(this.documentXml)
: null;
for (const partPath of REVISION_STORY_PART_PATHS) {
const xml = await this.zip.readTextOrNull(partPath);
if (!xml)
continue;
const partDoc = parseXml(xml);
const partResult = acceptChangesImpl(partDoc);
addAcceptChangesResult(total, partResult);
let footnotesPruned = 0;
if (partPath === 'word/footnotes.xml' && liveFootnoteRefIds) {
footnotesPruned = pruneOrphanedFootnotes(partDoc, liveFootnoteRefIds);
}
if (hasAcceptedChanges(partResult) || footnotesPruned > 0) {
this.zip.writeText(partPath, serializeXml(partDoc));
if (partPath === 'word/footnotes.xml') {
this.footnotesXml = partDoc;
}
}
}
if (hasAcceptedChanges(total)) {
this.dirty = true;
this.documentViewCache = null;
}
return total;
}
/**
* Reject all tracked changes in document.xml plus supported revisionable
* side-story parts, restoring their pre-edit state where possible.
*/
async rejectChanges() {
const total = emptyRejectChangesResult();
const bodyResult = rejectChangesImpl(this.documentXml);
addRejectChangesResult(total, bodyResult);
// After rejecting, footnotes whose body reference lived inside a removed
// w:ins are orphaned. Only worth checking when the body sweep removed
// insertions (the only operation that can drop a footnoteReference).
const liveFootnoteRefIds = bodyResult.insertionsRemoved > 0
? collectLiveFootnoteRefIds(this.documentXml)
: null;
for (const partPath of REVISION_STORY_PART_PATHS) {
const xml = await this.zip.readTextOrNull(partPath);
if (!xml)
continue;
const partDoc = parseXml(xml);
const partResult = rejectChangesImpl(partDoc);
addRejectChangesResult(total, partResult);
let footnotesPruned = 0;
if (partPath === 'word/footnotes.xml' && liveFootnoteRefIds) {
footnotesPruned = pruneOrphanedFootnotes(partDoc, liveFootnoteRefIds);
}
if (hasRejectedChanges(partResult) || footnotesPruned > 0) {
this.zip.writeText(partPath, serializeXml(partDoc));
if (partPath === 'word/footnotes.xml') {
this.footnotesXml = partDoc;
}
}
}
if (hasRejectedChanges(total)) {
this.dirty = true;
this.documentViewCache = null;
}
return total;
}
removeJuniorBookmarks() {
const removed = cleanupInternalBookmarks(this.documentXml);
if (removed > 0)
this.dirty = true;
return removed;
}
readParagraphs(opts) {
const all = this.getParagraphs()
.map((p) => {
const id = getParagraphBookmarkId(p);
if (!id)
return null;
const text = getParagraphText(p).trim();
if (!text)
return null;
return { id, text };
})
.filter((x) => x !== null);
const total = all.length;
const { nodeIds, offset, limit } = opts ?? {};
if (nodeIds && nodeIds.length > 0) {
const set = new Set(nodeIds);
return { paragraphs: all.filter((p) => set.has(p.id)), totalParagraphs: total };
}
let startIdx = 0;
if (typeof offset === 'number') {
// Offset is 1-based in Python server; negative counts from end.
if (offset > 0)
startIdx = Math.max(0, offset - 1);
if (offset < 0)
startIdx = Math.max(0, total + offset);
}
const endIdx = typeof limit === 'number' ? Math.min(total, startIdx + limit) : total;
return { paragraphs: all.slice(startIdx, endIdx), totalParagraphs: total };
}
/**
* Parsed `word/numbering.xml` model (abstract numberings + instances), or null when the
* document has no numbering part. The document view's `numbering` field only carries
* `num_id`/`ilvl`; semantic converters (DOCX → ODT) need `numFmt`/`lvlText`/`start` to
* synthesize target-format list styles, so the full model is exposed here.
*/
getNumberingModel() {
return this.numberingXml ? parseNumberingXml(this.numberingXml) : null;
}
/**
* Parsed named-style model of the loaded document (empty when the package has no
* `word/styles.xml`). Semantic converters (DOCX → ODT) resolve heading/body style chains
* through it to seed their own style templates from the source's definitions.
*/
getStylesModel() {
return parseStylesXml(this.stylesXml);
}
buildDocumentView(opts) {
const includeSemanticTags = opts?.includeSemanticTags ?? true;
const showFormatting = opts?.showFormatting ?? false;
const formattingMode = opts?.formattingMode ?? 'compact';
const cached = this.documentViewCache;
if (!this.dirty && cached && cached.includeSemanticTags === includeSemanticTags && cached.showFormatting === showFormatting && cached.formattingMode === formattingMode) {
return { nodes: cached.nodes, styles: cached.styles };
}
// Shared paragraph-collection core (also used by the free buildDocumentView):
// attaches each bookmarked paragraph's table context.
const paragraphs = collectViewParagraphs(this.documentXml);
const { nodes, styles } = buildNodesForDocumentView({
paragraphs,
stylesXml: this.stylesXml,
numberingXml: this.numberingXml,
include_semantic_tags: includeSemanticTags,
show_formatting: showFormatting,
formatting_mode: formattingMode,
relsMap: this.relsMap,
documentXml: this.documentXml,
footnotesXml: this.footnotesXml,
});
this.documentViewCache = { includeSemanticTags, showFormatting, formattingMode, nodes, styles };
this.dirty = false;
return { nodes, styles };
}
replaceText(params) {
const { targetParagraphId, findText, replaceText } = params;
const p = findParagraphByBookmarkId(this.documentXml, targetParagraphId);
if (!p)
throw new Error(`Paragraph not found: ${targetParagraphId}`);
const full = getParagraphText(p);
const match = findUniqueSubstringMatch(full, findText);
if (match.status === 'not_found') {
throw new Error(`Text not found in paragraph ${targetParagraphId}`);
}
if (match.status === 'multiple') {
throw new Error(`Multiple matches (${match.matchCount}) found in paragraph ${targetParagraphId} using ${match.mode} matching`);
}
replaceParagraphTextRange(p, match.start, match.end, replaceText);
this.dirty = true;
this.documentViewCache = null;
}
/**
* Replace text at a known character range without re-searching.
* Used by the range-trimming approach where the caller has already located the match.
*/
replaceTextAtRange(params) {
const { targetParagraphId, start, end, replaceText } = params;
const p = findParagraphByBookmarkId(this.documentXml, targetParagraphId);
if (!p)
throw new Error(`Paragraph not found: ${targetParagraphId}`);
replaceParagraphTextRange(p, start, end, replaceText);
this.dirty = true;
this.documentViewCache = null;
}
insertParagraph(params, ctx) {
const { positionalAnchorNodeId, relativePosition, newText, newParagraphId: _newParagraphId, styleSourceId } = params;
const anchor = findParagraphByBookmarkId(this.documentXml, positionalAnchorNodeId);
if (!anchor)
throw new Error(`Anchor paragraph not found: ${positionalAnchorNodeId}`);
const anchorP = anchor;
// Resolve style source paragraph (if provided).
let styleSourceP = null;
let styleSourceFallback = false;
if (styleSourceId) {
styleSourceP = findParagraphByBookmarkId(this.documentXml, styleSourceId);
if (!styleSourceP) {
styleSourceFallback = true;
// Fall back to anchor
}
}
const formattingSource = styleSourceP ?? anchorP;
const doc = this.documentXml;
const parent = anchorP.parentNode;
if (!parent)
throw new Error('Anchor paragraph has no parent');
function isWTag(el, localName) {
return !!el && el.namespaceURI === OOXML.W_NS && el.localName === localName;
}
function setXmlSpacePreserveIfNeeded(t, text) {
if (!text)
return;
if (text.startsWith(' ') || text.endsWith(' ')) {
t.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve');
}
}
function cloneRunFormattingOnly(sourceRun) {
const r = doc.createElementNS(OOXML.W_NS, 'w:r');
for (const child of Array.from(sourceRun.childNodes)) {
if (child.nodeType !== 1)
continue;
const el = child;
if (isWTag(el, W.rPr)) {
r.appendChild(el.cloneNode(true));
break;
}
}
return r;
}
function appendTextToRun(run, text) {
let buf = '';
const flush = () => {
if (!buf)
return;
const t = doc.createElementNS(OOXML.W_NS, 'w:t');
setXmlSpacePreserveIfNeeded(t, buf);
t.appendChild(doc.createTextNode(buf));
run.appendChild(t);
buf = '';
};
for (let i = 0; i < text.length; i++) {
const ch = text[i];
if (ch === '\t') {
flush();
run.appendChild(doc.createElementNS(OOXML.W_NS, 'w:tab'));
continue;
}
if (ch === '\n') {
flush();
run.appendChild(doc.createElementNS(OOXML.W_NS, 'w:br'));
continue;
}
buf += ch;
}
flush();
}
function cloneParagraphShell(anchorPara) {
// Clone anchor paragraph to preserve formatting; then wipe its runs and keep pPr only.
const newP = anchorPara.cloneNode(true);
const children = Array.from(newP.childNodes);
for (const child of children) {
if (child.nodeType === 1 && isWTag(child, W.pPr))
continue;
newP.removeChild(child);
}
// sectPr is the section terminator — must stay on the anchor, not propagate to the new paragraph.
const clonedPPr = getDirectChildrenByName(newP, W.pPr)[0];
if (clonedPPr) {
for (const sectPr of getDirectChildrenByName(clonedPPr, 'sectPr')) {
clonedPPr.removeChild(sectPr);
}
}
return newP;
}
function ensureParagraphProperties(paragraph) {
const existing = getDirectChildrenByName(paragraph, W.pPr)[0];
if (existing)
return existing;
const pPr = createWmlElement(doc, W.pPr);
paragraph.insertBefore(pPr, paragraph.firstChild);
return pPr;
}
function ensureParagraphRunProperties(pPr) {
const existing = getDirectChildrenByName(pPr, W.rPr)[0];
if (existing)
return existing;
const rPr = createWmlElement(doc, W.rPr);
const sectPr = getDirectChildrenByName(pPr, 'sectPr')[0];
const pPrChange = getDirectChildrenByName(pPr, 'pPrChange')[0];
const insertBefore = sectPr ?? pPrChange ?? null;
if (insertBefore) {
pPr.insertBefore(rPr, insertBefore);
}
else {
pPr.appendChild(rPr);
}
return rPr;
}
function addParagraphInsertionMarker(paragraph, revisionCtx) {
const pPr = ensureParagraphProperties(paragraph);
const rPr = ensureParagraphRunProperties(pPr);
const marker = createWmlElement(doc, 'ins', {
'w:id': String(allocateRevisionId(revisionCtx.idState)),
'w:author': revisionCtx.author,
'w:date': revisionCtx.date,
});
rPr.insertBefore(marker, rPr.firstChild);
}
function clearRunPropertyRevisionMarkup(run) {
const rPr = getDirectChildrenByName(run, W.rPr)[0];
if (!rPr)
return;
for (const child of Array.from(rPr.childNodes)) {
if (child.nodeType !== 1)
continue;
const element = child;
if (isW(element, 'rPrChange')) {
rPr.removeChild(element);
}
}
}
function clearParagraphPropertyRevisionMarkup(paragraph) {
const pPr = getDirectChildrenByName(paragraph, W.pPr)[0];
if (!pPr)
return;
for (const pPrChange of getDirectChildrenByName(pPr, 'pPrChange')) {
pPr.removeChild(pPrChange);
}
const rPr = getDirectChildrenByName(pPr, W.rPr)[0];
if (!rPr)
return;
for (const child of Array.from(rPr.childNodes)) {
if (child.nodeType !== 1)
continue;
const element = child;
// CT_ParaRPr revision children: w:ins, w:del, w:moveFrom, w:moveTo, w:rPrChange.
if (isW(element, 'ins') ||
isW(element, 'del') ||
isW(element, 'moveFrom') ||
isW(element, 'moveTo') ||
isW(element, 'rPrChange')) {
rPr.removeChild(element);
}
}
}
function getInsertionRefNode() {
if (relativePosition === 'BEFORE') {
const prev = prevElementSibling(anchorP);
return isW(prev, W.bookmarkStart) ? prev : anchorP;
}
const next = nextElementSibling(anchorP);
if (next && isW(next, W.bookmarkEnd))
return next.nextSibling;
return anchorP.nextSibling;
}
// Choose a run in the formatting source to use as formatting template: pick the run with the most visible text.
const sourceVisibleRuns = getParagraphRuns(formattingSource);
let templateRun = null;
let bestLen = -1;
for (const tr of sourceVisibleRuns) {
if (tr.text.length > bestLen) {
bestLen = tr.text.length;
templateRun = tr.r;
}
}
if (!templateRun) {
const allRuns = Array.from(formattingSource.getElementsByTagNameNS(OOXML.W_NS, W.r));
templateRun = allRuns[0] ?? doc.createElementNS(OOXML.W_NS, 'w:r');
}
const paragraphsToInsert = newText.replace(/\r\n/g, '\n').split(/\n{2,}/);
const insertedIds = [];
let cursor = getInsertionRefNode();
for (const paraText of paragraphsToInsert) {
const newP = cloneParagraphShell(formattingSource);
const newRun = cloneRunFormattingOnly(templateRun);
appendTextToRun(newRun, paraText);
if (ctx) {
clearRunPropertyRevisionMarkup(newRun);
clearParagraphPropertyRevisionMarkup(newP);
addParagraphInsertionMarker(newP, ctx);
const insertion = createRevisionContainer(doc, 'ins', ctx);
insertion.appendChild(newRun);
newP.appendChild(insertion);
}
else {
newP.appendChild(newRun);
}
parent.insertBefore(newP, cursor);
const id = insertSingleParagraphBookmark(doc, newP);
insertedIds.push(id);
if (relativePosition === 'AFTER') {
const endEl = nextElementSibling(newP);
cursor = endEl && isW(endEl, W.bookmarkEnd) ? endEl.nextSibling : newP.nextSibling;
}
}
this.dirty = true;
this.documentViewCache = null;
const result = {
newParagraphId: insertedIds[0],
newParagraphIds: insertedIds,
};
if (styleSourceFallback)
result.styleSourceFallback = true;
return result;
}
setParagraphSpacing(mutation, ctx) {
const result = setParagraphSpacing(this.documentXml, mutation, ctx);
if (result.affectedParagraphs > 0) {
this.dirty = true;
this.documentViewCache = null;
}
return result;
}
setTableRowHeight(mutation, ctx) {
const result = setTableRowHeight(this.documentXml, mutation, ctx);
if (result.affectedRows > 0) {
this.dirty = true;
this.documentViewCache = null;
}
return result;
}
setTableCellPadding(mutation, ctx) {
const result = setTableCellPadding(this.documentXml, mutation, ctx);
if (result.affectedCells > 0) {
this.dirty = true;
this.documentViewCache = null;
}
return result;
}
/**
* Extract tables from the document body.
* Read-only operation — does not mutate document state.
*/
extractTables(options) {
return extractTables(this.documentXml, options);
}
/**
* Merge format-identical adjacent runs only (no redline simplification).
* Useful as a pre-processing step before text search when runs may be fragmented.
* Pass `{ preserveRsidIdentity: true }` from edit pipelines that must not
* disturb rsid attributes on runs the caller did not touch (#286).
*/
mergeRunsOnly(opts = {}) {
const result = mergeRuns(this.documentXml, opts);
if (result.runsMerged > 0) {
this.dirty = true;
this.documentViewCache = null;
}
return result;
}
/**
* Add a root comment anchored to a text range within a paragraph.
*
* Bootstraps comment parts if missing (idempotent).
* Returns the allocated comment ID.
*/
async addComment(params, ctx) {
const p = findParagraphByBookmarkId(this.documentXml, params.paragraphId);
if (!p)
throw new Error(`Paragraph not found: ${params.paragraphId}`);
await bootstrapCommentParts(this.zip);
const result = await addCommentImpl(this.documentXml, this.zip, {
paragraphEl: p,
start: params.start,
end: params.end,
author: params.author,
text: params.text,
initials: params.initials,
}, ctx);
this.dirty = true;
this.documentViewCache = null;
return result;
}
/**
* Add a threaded reply to an existing comment.
*
* Bootstraps comment parts if missing (idempotent).
* Returns the allocated comment ID and parent ID.
*/
async addCommentReply(params, ctx) {
await bootstrapCommentParts(this.zip);
const result = await addCommentReplyImpl(this.documentXml, this.zip, {
parentCommentId: params.parentCommentId,
author: params.author,
text: params.text,
initials: params.initials,
}, ctx);
this.dirty = true;
this.documentViewCache = null;
return result;
}
async getComments() {
return getCommentsImpl(this.zip, this.documentXml);
}
async getComment(commentId) {
return getCommentImpl(this.zip, this.documentXml, commentId);
}
async deleteComment(params, ctx) {
await deleteCommentImpl(this.documentXml, this.zip, params, ctx);
this.dirty = true;
this.documentViewCache = null;
}
// ── Footnote methods ──────────────────────────────────────────────────
async refreshFootnotesXml() {
const text = await this.zip.readTextOrNull('word/footnotes.xml');
this.footnotesXml = text ? parseXml(text) : null;
}
async getFootnotes() {
return getFootnotesImpl(this.zip, this.documentXml);
}
/**
* Serialize the document to GitHub-Flavored Markdown. Convenience wrapper that wires the
* structured document view (with inline formatting) and footnotes into
* {@link serializeToMarkdown}. Markdown is intentionally lossy — see that serializer.
*
* Async because footnote extraction reads the footnotes part from the zip.
*/
async toMarkdown(opts) {
const { nodes } = this.buildDocumentView({ showFormatting: true });
const footnotes = await this.getFootnotes();
return serializeToMarkdown(nodes, footnotes, opts);
}
/**
* Serialize the document to semantic HTML. Convenience wrapper that wires the structured
* document view (with inline formatting) and footnotes into {@link serializeToHtml}. The
* default output is a complete `<!DOCTYPE html>` document; pass `{ fragment: true }` for the
* body-level elements only. This is the semantic tier — exact layout is not reproduced.
*
* Async because footnote extraction reads the footnotes part from the zip.
*/
async toHtml(opts) {
const { nodes } = this.buildDocumentView({ showFormatting: true });
const footnotes = await this.getFootnotes();
return serializeToHtml(nodes, footnotes, opts);
}
/**
* Serialize the document to plain text (no markup). Convenience wrapper that wires the
* structured document view and footnotes into {@link serializeToPlainText}. All formatting
* is stripped; block structure survives as blank-line-separated paragraphs, `- ` bullets,
* and tab-separated table rows. Intentionally lossy — see that serializer.
*
* Uses the same `showFormatting: true` view as {@link toMarkdown} so the block structure
* and injected `[^n]` footnote markers match; the inline tags it produces are then stripped.
*
* Async because footnote extraction reads the footnotes part from the zip.
*/
async toPlainText(opts) {
const { nodes } = this.buildDocumentView({ showFormatting: true });
const footnotes = await this.getFootnotes();
return serializeToPlainText(nodes, footnotes, opts);
}
async getFootnote(noteId) {
return getFootnoteImpl(this.zip, this.documentXml, noteId);
}
/**
* Add a footnote anchored to a paragraph, optionally after specific text.
*
* Bootstraps footnote parts if missing (idempotent).
* Returns the allocated footnote ID.
*/
async addFootnote(params, ctx) {
const p = findParagraphByBookmarkId(this.documentXml, params.paragraphId);
if (!p)
throw new Error(`Paragraph not found: ${params.paragraphId}`);
await bootstrapFootnoteParts(this.zip);
const result = await addFootnoteImpl(this.documentXml, this.zip, {
paragraphEl: p,
afterText: params.afterText,
text: params.text,
}, ctx);
await this.refreshFootnotesXml();
this.dirty = true;
this.documentViewCache = null;
return result;
}
/**
* Update the text content of an existing footnote.
*/
async updateFootnoteText(params, ctx) {
await updateFootnoteTextImpl(this.zip, params, ctx);
await this.refreshFootnotesXml();
this.dirty = true;
this.documentViewCache = null;
}
/**
* Delete a footnote and its references from the document.
*/
async deleteFootnote(params, ctx) {
await deleteFootnoteImpl(this.documentXml, this.zip, params, ctx);
await this.refreshFootnotesXml();
this.dirty = true;
this.documentViewCache = null;
}
/**
* Return a deep clone of the internal document.xml DOM.
* Callers can mutate the clone (e.g. acceptChanges / rejectChanges)
* without affecting session state.
*/
getDocumentXmlClone() {
return this.documentXml.cloneNode(true);
}
/**
* Return a deep clone of the comments.xml DOM, or null if the document
* has no comments part.
*/
async getCommentsXmlClone() {
const commentsText = await this.zip.readTextOrNull('word/comments.xml');
if (!commentsText)
return null;
return parseXml(commentsText);
}
/**
* Serialize the document to a .docx buffer.
*
* With `minimalReserialization` (requires `cleanBookmarks`), top-level body
* blocks that no edit touched are restored element-for-element from the
* original document.xml instead of carrying the open-time normalization
* (proofErr stripping, run merging) to disk — so output diffs reflect the
* actual edit blast radius. Edited/inserted blocks are emitted as-is.
* Falls back to full re-serialization (blocksRestored: 0) when no original
* text was captured or reconciliation fails.
*
* @see https://github.com/UseJunior/safe-docx/issues/408
*/
async toBuffer(opts) {
// Always write the latest document.xml when saving.
// Important: when cleanBookmarks=true (download), we must NOT mutate session state.
const xmlWithBookmarks = serializeXml(this.documentXml);
maybeCaptureEmittedDocumentXml(xmlWithBookmarks);
this.zip.writeText('word/document.xml', xmlWithBookmarks);
if (opts?.cleanBookmarks) {
const cloned = parseXml(xmlWithBookmarks);
const bookmarksRemoved = cleanupInternalBookmarks(cloned);
let blocksRestored = 0;
if (opts.minimalReserialization && this.originalDocumentXmlText !== null) {
try {
blocksRestored = restoreUntouchedBlocks(cloned, this.originalDocumentXmlText);
}
catch {
// Reconciliation is best-effort; the fully re-serialized DOM is
// always a correct (if non-minimal) save.
blocksRestored = 0;
}
}
const cleanedXml = serializeXml(cloned);
// Temporarily swap document.xml in the zip for output, then restore.
maybeCaptureEmittedDocumentXml(cleanedXml);
this.zip.writeText('word/document.xml', cleanedXml);
const buffer = await this.zip.toBuffer();
this.zip.writeText('word/document.xml', xmlWithBookmarks);
return { buffer, bookmarksRemoved, blocksRestored };
}
const buffer = await this.zip.toBuffer();
return { buffer, bookmarksRemoved: 0, blocksRestored: 0 };
}
}
//# sourceMappingURL=document.js.map