@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/properties/index.d.mts

@@ -0,0 +1,4 @@
+export { type Property, type RunProps, type Merge, RUN, PARAGRAPH, TABLE, CELL, TOGGLES, TOGGLE_NAMES, IND, RUN_EXCLUDED, PARAGRAPH_EXCLUDED, TABLE_EXCLUDED, CELL_EXCLUDED, namedProperty, isEmptyOf, hasDirectFormattingOf, applyCatalogue, applyProperty, unsetCatalogue, copyLeaf, } from './catalogue.mjs';
+export * from './styleUtil.mjs';
+export { PropertyResolver, headingLevelByName, WORD_DEFAULT_CELL_MARGIN_TWIPS, type ResolverSource, } from './PropertyResolver.mjs';
+export { setLogger, type Logger } from './log.mjs';

package/dist/model/properties/index.mjs

@@ -0,0 +1,9 @@
+// CR-001 Phase B step 2: property resolution (docx4j `org.docx4j.model.PropertyResolver` and
+// the catalogue-driven half of `org.docx4j.model.styles`).
+//
+// The tables' leaf merge and emptiness rules stay inside `catalogue.mts`: what a consumer
+// needs is the tables, the generic operations over them, and the resolver.
+export { RUN, PARAGRAPH, TABLE, CELL, TOGGLES, TOGGLE_NAMES, IND, RUN_EXCLUDED, PARAGRAPH_EXCLUDED, TABLE_EXCLUDED, CELL_EXCLUDED, namedProperty, isEmptyOf, hasDirectFormattingOf, applyCatalogue, applyProperty, unsetCatalogue, copyLeaf, } from './catalogue.mjs';
+export * from './styleUtil.mjs';
+export { PropertyResolver, headingLevelByName, WORD_DEFAULT_CELL_MARGIN_TWIPS, } from './PropertyResolver.mjs';
+export { setLogger } from './log.mjs';

package/dist/model/properties/log.d.mts

@@ -0,0 +1,7 @@
+export interface Logger {
+    warn(message: string): void;
+}
+/** The logger property resolution writes to. */
+export declare const log: Logger;
+/** Replaces the sink; pass nothing to go back to `console.warn`. */
+export declare function setLogger(logger?: Logger): void;

package/dist/model/properties/log.mjs

@@ -0,0 +1,25 @@
+// The one place property resolution writes a diagnostic. docx4j logs through SLF4J; this
+// package has no logging framework, so a missing style or a style cycle goes to `console.warn`
+// behind a settable sink (an add-in that must stay silent, or a test that wants to assert what
+// was logged, replaces it).
+//
+// Resolution logs a missing style *once per id* (a `w:pStyle` naming a deleted style is common
+// in real documents, and docx4j used to log one ERROR per paragraph); the resolver keeps that
+// set, not this module.
+const consoleLogger = {
+    warn(message) {
+        // eslint-disable-next-line no-console
+        console.warn(message);
+    },
+};
+let sink = consoleLogger;
+/** The logger property resolution writes to. */
+export const log = {
+    warn(message) {
+        sink.warn(message);
+    },
+};
+/** Replaces the sink; pass nothing to go back to `console.warn`. */
+export function setLogger(logger) {
+    sink = logger !== null && logger !== void 0 ? logger : consoleLogger;
+}

package/dist/model/properties/styleUtil.d.mts

@@ -0,0 +1,112 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import { type RunProps } from './catalogue.mjs';
+/** What the paragraph merge needs from the numbering part: a level's `w:ind`. */
+export interface NumberingIndents {
+    /** The indent the level a `w:numPr` names contributes, or undefined. */
+    getInd(numPr: wml.PPrBase.NumPr): wml.PPrBase.Ind | undefined;
+}
+export declare function isEmptyRPr(rPr: RunProps | undefined): boolean;
+export declare function isEmptyPPrBase(pPrBase: wml.PPrBase | undefined): boolean;
+/** docx4j `isEmpty(PPr)`: the base members, the paragraph mark and the section. */
+export declare function isEmptyPPr(pPr: wml.PPr | undefined): boolean;
+export declare function isEmptyTblPr(tblPr: wml.CTTblPrBase | undefined): boolean;
+export declare function isEmptyTcPr(tcPr: wml.TcPr | undefined): boolean;
+export declare function isEmptyTrPr(trPr: wml.TrPr | undefined): boolean;
+export declare function isEmptyTblStylePr(pr: wml.CTTblStylePr | undefined): boolean;
+export declare function isEmptyTblStylePrList(list: readonly wml.CTTblStylePr[] | undefined): boolean;
+export declare function isEmptyStyle(style: wml.Style | undefined): boolean;
+/**
+ * Whether a run's `w:rPr` states any formatting of its own: any member of the run table other
+ * than the style reference is present (an element with no attributes counts: it was stated).
+ */
+export declare function hasDirectFormattingRPr(rPr: RunProps | undefined): boolean;
+/**
+ * Whether a paragraph's `w:pPr` states any formatting of its own. The paragraph mark's
+ * `w:rPr` and a `w:sectPr` are not formatting of the paragraph.
+ */
+export declare function hasDirectFormattingPPr(pPr: wml.PPrBase | undefined): boolean;
+export declare function unsetRPr(source: RunProps, destination: RunProps): void;
+export declare function unsetPPrBase(source: wml.PPrBase, destination: wml.PPrBase): void;
+/**
+ * Apply run properties over run properties (a `w:rPr` or a `w:pPr/w:rPr` over either), in
+ * place. Returns the destination, created when it was undefined and the source had something
+ * to say.
+ */
+export declare function applyRPr<D extends RunProps>(source: RunProps | undefined, destination: D | undefined, create?: () => D): D | undefined;
+/**
+ * Apply one **level** of the style hierarchy over the levels beneath it, combining the
+ * **toggle properties** as ECMA-376-1 §17.7.3 requires instead of overriding them.
+ *
+ * Only a level boundary goes through here - the table style's contribution against the
+ * paragraph style's, and the paragraph style's against the character style's. Within one
+ * level a style's `w:basedOn` chain is *not* XORed (§17.7.3 takes the first value found
+ * walking that chain, which is what merging the chain root-first with {@link applyRPr}
+ * gives), and direct formatting is not a level either: an explicit value there is used as it
+ * stands, so it goes through {@link applyRPr} too.
+ */
+export declare function applyStyleLevel(source: RunProps | undefined, destination: RunProps | undefined, documentDefaults: RunProps | undefined): void;
+/**
+ * Combine the twelve toggle properties of two levels of the style hierarchy and write the
+ * result into a third `w:rPr`. Nothing else of either is touched.
+ */
+export declare function applyToggles(upper: RunProps | undefined, lower: RunProps | undefined, documentDefaults: RunProps | undefined, destination: RunProps | undefined): void;
+/**
+ * One toggle property at one level boundary (ECMA-376-1 §17.7.3), as Word's `toggle-levels`
+ * golden settled it (docx4j CR-015, 2026-09-18):
+ *
+ * - an upper level that says nothing is no boundary at all, so the lower value stands and the
+ *   document defaults' true is not forced back on (confirmed by the golden);
+ * - `w:docDefaults` is a base value, never a term of the XOR: where the defaults say true and
+ *   the upper level states the property, the effective value is true;
+ * - an explicit false at a style level is a term of the XOR like any other value, so
+ *   false XOR lower = lower and only a stated *true* inverts what is beneath it. Word draws a
+ *   run in a character style stating `<w:b w:val="0"/>` over a bold paragraph style **bold**.
+ *   Where no level beneath states the property, the one level's own false stands rather than
+ *   the property going absent.
+ *
+ * Direct formatting never comes through here: an explicit value there wins outright.
+ */
+export declare function toggle(upper: wml.BooleanDefaultTrue | undefined, lower: wml.BooleanDefaultTrue | undefined, documentDefault: wml.BooleanDefaultTrue | undefined): wml.BooleanDefaultTrue | undefined;
+/** Whether this `w:numPr` says "not numbered" - `w:numId w:val="0"` (ECMA-376 17.9.18). */
+export declare function numberingOff(numPr: wml.PPrBase.NumPr | undefined): boolean;
+/**
+ * Apply paragraph properties over paragraph properties, in place: every member but `w:ind`,
+ * then the indent the numbering level this layer brings in contributes, then `w:ind` itself
+ * (an indent stated by the layer overrides the level's).
+ */
+export declare function applyPPrBase(source: wml.PPrBase | undefined, destination: wml.PPrBase, numbering?: NumberingIndents): void;
+/**
+ * Apply a `w:pPr` over a `w:pPr`: the base members and the paragraph mark's `w:rPr`. A
+ * `w:sectPr` is not a paragraph property and is not merged (CR-015 phase 4).
+ */
+export declare function applyPPr(source: wml.PPr | undefined, destination: wml.PPr | undefined, numbering?: NumberingIndents): wml.PPr | undefined;
+export declare function applyTblPr(source: wml.CTTblPrBase | undefined, destination: wml.CTTblPrBase | undefined): wml.CTTblPrBase | undefined;
+export declare function applyTcPr(source: wml.TcPr | undefined, destination: wml.TcPr | undefined): wml.TcPr | undefined;
+/**
+ * A row's properties, which the generated model keeps as one element list: an element of a
+ * name the destination already has replaces it, and one it lacks is added.
+ */
+export declare function applyTrPr(source: wml.TrPr | undefined, destination: wml.TrPr | undefined): wml.TrPr | undefined;
+/**
+ * Merge a table style's conditional formatting (`w:tblStylePr`) into another's, *per
+ * condition*: an entry for a condition the destination already has is applied on top of it,
+ * and one it lacks is added. So a style `w:basedOn` another inherits the conditions it does
+ * not restate, and restating a condition overrides only the properties it names.
+ */
+export declare function applyTblStylePrList(source: readonly wml.CTTblStylePr[] | undefined, destination: wml.CTTblStylePr[] | undefined): void;
+export declare function applyTblStylePr(source: wml.CTTblStylePr | undefined, destination: wml.CTTblStylePr | undefined): wml.CTTblStylePr | undefined;
+/**
+ * Apply one style's own properties over another's (docx4j `apply(Style, Style)`). It does not
+ * climb the `w:basedOn` chain; `PropertyResolver.ancestry` does that.
+ */
+export declare function applyStyle(source: wml.Style | undefined, destination: wml.Style): wml.Style;
+/**
+ * Whether the chain has come back to a style it has already seen (or has gone deeper than
+ * {@link CYCLE_LIMIT}). The caller degrades gracefully by using as much of the hierarchy as it
+ * has; set {@link throwOnCyclicStyles} to throw instead (docx4j's
+ * `docx4j.openpackaging.exceptions.CyclicStylesException.throw` property).
+ */
+export declare function isCyclic(styleId: string, seen: readonly string[]): boolean;
+/** docx4j's `docx4j.openpackaging.exceptions.CyclicStylesException.throw`: off by default. */
+export declare function throwOnCyclicStyles(value: boolean): void;
+export declare function throwsOnCyclicStyles(): boolean;

package/dist/model/properties/styleUtil.mjs

@@ -0,0 +1,359 @@
+import { RUN, PARAGRAPH, TABLE, CELL, TOGGLE_NAMES, TOGGLES, IND, applyCatalogue, unsetCatalogue, isEmptyOf, hasDirectFormattingOf, isTrue, copyLeaf, } from './catalogue.mjs';
+import { CyclicStylesException } from '../../opc/exceptions.mjs';
+import { log } from './log.mjs';
+// ---------------------------------------------------------------- isEmpty
+export function isEmptyRPr(rPr) {
+    return isEmptyOf(RUN, rPr);
+}
+export function isEmptyPPrBase(pPrBase) {
+    return isEmptyOf(PARAGRAPH, pPrBase);
+}
+/** docx4j `isEmpty(PPr)`: the base members, the paragraph mark and the section. */
+export function isEmptyPPr(pPr) {
+    // isEmpty(SectPr) is "false for anything non-null" in docx4j ("implementation is quite basic")
+    return pPr === undefined
+        || (isEmptyPPrBase(pPr) && isEmptyRPr(pPr.rPr) && pPr.sectPr === undefined);
+}
+export function isEmptyTblPr(tblPr) {
+    return isEmptyOf(TABLE, tblPr);
+}
+export function isEmptyTcPr(tcPr) {
+    return isEmptyOf(CELL, tcPr);
+}
+export function isEmptyTrPr(trPr) {
+    return trPr === undefined || trPr.cnfStyleOrDivIdOrGridBefore === undefined
+        || trPr.cnfStyleOrDivIdOrGridBefore.length === 0;
+}
+export function isEmptyTblStylePr(pr) {
+    return pr === undefined
+        || (isEmptyPPr(pr.pPr) && isEmptyRPr(pr.rPr) && isEmptyTblPr(pr.tblPr)
+            && isEmptyTrPr(pr.trPr) && isEmptyTcPr(pr.tcPr) && pr.type === undefined);
+}
+export function isEmptyTblStylePrList(list) {
+    if (list === undefined || list.length === 0)
+        return true;
+    return !list.some((pr) => !isEmptyTblStylePr(pr));
+}
+const CHARACTER_STYLE = 'character';
+const PARAGRAPH_STYLE = 'paragraph';
+const NUMBERING_STYLE = 'numbering';
+const TABLE_STYLE = 'table';
+export function isEmptyStyle(style) {
+    if (style === undefined)
+        return true;
+    if (style.type === CHARACTER_STYLE)
+        return isEmptyRPr(style.rPr);
+    if (style.type === PARAGRAPH_STYLE || style.type === NUMBERING_STYLE) {
+        return isEmptyPPr(style.pPr) && isEmptyRPr(style.rPr);
+    }
+    return isEmptyPPr(style.pPr) && isEmptyRPr(style.rPr) && isEmptyTblPr(style.tblPr)
+        && isEmptyTcPr(style.tcPr) && isEmptyTblStylePrList(style.tblStylePr);
+}
+// ---------------------------------------------------------------- direct formatting
+/**
+ * Whether a run's `w:rPr` states any formatting of its own: any member of the run table other
+ * than the style reference is present (an element with no attributes counts: it was stated).
+ */
+export function hasDirectFormattingRPr(rPr) {
+    return hasDirectFormattingOf(RUN, rPr);
+}
+/**
+ * Whether a paragraph's `w:pPr` states any formatting of its own. The paragraph mark's
+ * `w:rPr` and a `w:sectPr` are not formatting of the paragraph.
+ */
+export function hasDirectFormattingPPr(pPr) {
+    return hasDirectFormattingOf(PARAGRAPH, pPr);
+}
+// ---------------------------------------------------------------- unset
+export function unsetRPr(source, destination) {
+    unsetCatalogue(RUN, source, destination);
+}
+export function unsetPPrBase(source, destination) {
+    unsetCatalogue(PARAGRAPH, source, destination);
+}
+// ---------------------------------------------------------------- apply: runs
+/** A run properties source with nothing to say - except that a `w:rFonts` carrying only a `w:hint` still says something. */
+function skipRun(source) {
+    if (source === undefined)
+        return true;
+    const hint = source.rFonts !== undefined && source.rFonts.hint !== undefined;
+    return isEmptyOf(RUN, source) && !hint;
+}
+/**
+ * Apply run properties over run properties (a `w:rPr` or a `w:pPr/w:rPr` over either), in
+ * place. Returns the destination, created when it was undefined and the source had something
+ * to say.
+ */
+export function applyRPr(source, destination, create) {
+    if (skipRun(source))
+        return destination;
+    const out = destination !== null && destination !== void 0 ? destination : (create ? create() : { TYPE_NAME: 'org_docx4j_wml.RPr' });
+    applyCatalogue(RUN, source, out);
+    return out;
+}
+/**
+ * Apply one **level** of the style hierarchy over the levels beneath it, combining the
+ * **toggle properties** as ECMA-376-1 §17.7.3 requires instead of overriding them.
+ *
+ * Only a level boundary goes through here - the table style's contribution against the
+ * paragraph style's, and the paragraph style's against the character style's. Within one
+ * level a style's `w:basedOn` chain is *not* XORed (§17.7.3 takes the first value found
+ * walking that chain, which is what merging the chain root-first with {@link applyRPr}
+ * gives), and direct formatting is not a level either: an explicit value there is used as it
+ * stands, so it goes through {@link applyRPr} too.
+ */
+export function applyStyleLevel(source, destination, documentDefaults) {
+    if (source === undefined || destination === undefined)
+        return;
+    applyCatalogue(RUN, source, destination, TOGGLE_NAMES);
+    applyToggles(source, destination, documentDefaults, destination);
+}
+/**
+ * Combine the twelve toggle properties of two levels of the style hierarchy and write the
+ * result into a third `w:rPr`. Nothing else of either is touched.
+ */
+export function applyToggles(upper, lower, documentDefaults, destination) {
+    if (destination === undefined)
+        return;
+    for (const p of TOGGLES) {
+        const value = toggle(upper === undefined ? undefined : p.get(upper), lower === undefined ? undefined : p.get(lower), documentDefaults === undefined ? undefined : p.get(documentDefaults));
+        p.set(destination, value);
+    }
+}
+/**
+ * One toggle property at one level boundary (ECMA-376-1 §17.7.3), as Word's `toggle-levels`
+ * golden settled it (docx4j CR-015, 2026-09-18):
+ *
+ * - an upper level that says nothing is no boundary at all, so the lower value stands and the
+ *   document defaults' true is not forced back on (confirmed by the golden);
+ * - `w:docDefaults` is a base value, never a term of the XOR: where the defaults say true and
+ *   the upper level states the property, the effective value is true;
+ * - an explicit false at a style level is a term of the XOR like any other value, so
+ *   false XOR lower = lower and only a stated *true* inverts what is beneath it. Word draws a
+ *   run in a character style stating `<w:b w:val="0"/>` over a bold paragraph style **bold**.
+ *   Where no level beneath states the property, the one level's own false stands rather than
+ *   the property going absent.
+ *
+ * Direct formatting never comes through here: an explicit value there wins outright.
+ */
+export function toggle(upper, lower, documentDefault) {
+    if (upper === undefined)
+        return lower;
+    if (documentDefault !== undefined && isTrue(documentDefault)) {
+        return copyLeaf(documentDefault);
+    }
+    // false XOR lower = lower; with no level beneath it, the level's own false stands
+    if (!isTrue(upper))
+        return lower !== undefined ? lower : upper;
+    const out = { TYPE_NAME: 'org_docx4j_wml.BooleanDefaultTrue' };
+    out.val = !isTrue(lower);
+    return out;
+}
+// ---------------------------------------------------------------- apply: paragraphs
+/** Whether this `w:numPr` says "not numbered" - `w:numId w:val="0"` (ECMA-376 17.9.18). */
+export function numberingOff(numPr) {
+    return numPr !== undefined && numPr.numId !== undefined && numPr.numId.val === 0;
+}
+/** Take out of an indent the components a numbering level contributed. */
+function dropNumberingInd(ind, fromLevel) {
+    if (fromLevel.left !== undefined && fromLevel.left === ind.left)
+        delete ind.left;
+    if (fromLevel.right !== undefined && fromLevel.right === ind.right)
+        delete ind.right;
+    if (fromLevel.hanging !== undefined && fromLevel.hanging === ind.hanging)
+        delete ind.hanging;
+    if (fromLevel.firstLine !== undefined && fromLevel.firstLine === ind.firstLine)
+        delete ind.firstLine;
+    if (fromLevel.start !== undefined && fromLevel.start === ind.start)
+        delete ind.start;
+    if (fromLevel.end !== undefined && fromLevel.end === ind.end)
+        delete ind.end;
+}
+const IND_ONLY = new Set([IND]);
+/**
+ * Apply paragraph properties over paragraph properties, in place: every member but `w:ind`,
+ * then the indent the numbering level this layer brings in contributes, then `w:ind` itself
+ * (an indent stated by the layer overrides the level's).
+ */
+export function applyPPrBase(source, destination, numbering) {
+    if (source === undefined || isEmptyPPrBase(source))
+        return;
+    /* A snapshot: the numPr merge writes into the destination object, so holding a reference
+     * here would hand the numbering-off rule below the w:numId 0 it is looking past. */
+    let inheritedNumPr;
+    if (destination.numPr !== undefined) {
+        inheritedNumPr = { numId: destination.numPr.numId, ilvl: destination.numPr.ilvl };
+    }
+    applyCatalogue(PARAGRAPH, source, destination, IND_ONLY);
+    /* ECMA-376 17.9.18: w:numId w:val="0" takes the paragraph out of the list, so neither the
+     * level's label nor its w:ind applies - only the paragraph's own.  Only the components the
+     * inherited level contributed are dropped, so a w:ind the style states itself survives. */
+    if (numbering !== undefined && numberingOff(source.numPr)
+        && inheritedNumPr !== undefined && inheritedNumPr.numId !== undefined
+        && !numberingOff(inheritedNumPr) && destination.ind !== undefined) {
+        const fromLevel = numbering.getInd(inheritedNumPr);
+        if (fromLevel !== undefined) {
+            const own = copyLeaf(destination.ind);
+            dropNumberingInd(own, fromLevel);
+            destination.ind = own;
+        }
+    }
+    /* The indent of the level of the MERGED w:numPr, since a layer may state only w:ilvl (the
+     * list from the style) or only w:numId (the level from the style): CR-015 probe
+     * styles-numpr-ilvl-only. */
+    if (numbering !== undefined && source.numPr !== undefined
+        && destination.numPr !== undefined && !numberingOff(destination.numPr)) {
+        const numInd = numbering.getInd(destination.numPr);
+        if (numInd !== undefined) {
+            destination.ind = indProperty().merge(numInd, destination.ind);
+        }
+    }
+    // an indent in the layer overrides any the numbering brought in
+    destination.ind = indProperty().merge(source.ind, destination.ind);
+}
+let indEntry;
+function indProperty() {
+    indEntry !== null && indEntry !== void 0 ? indEntry : (indEntry = PARAGRAPH.find((p) => p.name === IND));
+    return indEntry;
+}
+/**
+ * Apply a `w:pPr` over a `w:pPr`: the base members and the paragraph mark's `w:rPr`. A
+ * `w:sectPr` is not a paragraph property and is not merged (CR-015 phase 4).
+ */
+export function applyPPr(source, destination, numbering) {
+    if (source === undefined || isEmptyPPr(source))
+        return destination;
+    const out = destination !== null && destination !== void 0 ? destination : { TYPE_NAME: 'org_docx4j_wml.PPr' };
+    applyPPrBase(source, out, numbering);
+    out.rPr = applyRPr(source.rPr, out.rPr, () => ({ TYPE_NAME: 'org_docx4j_wml.ParaRPr' }));
+    return out;
+}
+// ---------------------------------------------------------------- apply: tables
+export function applyTblPr(source, destination) {
+    if (source === undefined || isEmptyTblPr(source))
+        return destination;
+    const out = destination !== null && destination !== void 0 ? destination : { TYPE_NAME: 'org_docx4j_wml.CTTblPrBase' };
+    applyCatalogue(TABLE, source, out);
+    return out;
+}
+export function applyTcPr(source, destination) {
+    if (source === undefined || isEmptyTcPr(source))
+        return destination;
+    const out = destination !== null && destination !== void 0 ? destination : { TYPE_NAME: 'org_docx4j_wml.TcPr' };
+    applyCatalogue(CELL, source, out);
+    return out;
+}
+/**
+ * A row's properties, which the generated model keeps as one element list: an element of a
+ * name the destination already has replaces it, and one it lacks is added.
+ */
+export function applyTrPr(source, destination) {
+    var _a;
+    if (isEmptyTrPr(source))
+        return destination;
+    const out = destination !== null && destination !== void 0 ? destination : { TYPE_NAME: 'org_docx4j_wml.TrPr' };
+    const into = ((_a = out.cnfStyleOrDivIdOrGridBefore) !== null && _a !== void 0 ? _a : (out.cnfStyleOrDivIdOrGridBefore = []));
+    for (const element of source.cnfStyleOrDivIdOrGridBefore) {
+        const index = into.findIndex((existing) => existing.name.localPart === element.name.localPart
+            && existing.name.namespaceURI === element.name.namespaceURI);
+        if (index >= 0)
+            into.splice(index, 1);
+        into.push(copyLeaf(element));
+    }
+    return out;
+}
+/**
+ * Merge a table style's conditional formatting (`w:tblStylePr`) into another's, *per
+ * condition*: an entry for a condition the destination already has is applied on top of it,
+ * and one it lacks is added. So a style `w:basedOn` another inherits the conditions it does
+ * not restate, and restating a condition overrides only the properties it names.
+ */
+export function applyTblStylePrList(source, destination) {
+    if (isEmptyTblStylePrList(source) || destination === undefined)
+        return;
+    for (const sourcePr of source) {
+        if (sourcePr === undefined)
+            continue;
+        let existing;
+        if (sourcePr.type !== undefined) {
+            existing = destination.find((d) => d !== undefined && d.type === sourcePr.type);
+        }
+        if (existing === undefined) {
+            const copy = applyTblStylePr(sourcePr, undefined);
+            if (copy !== undefined)
+                destination.push(copy);
+        }
+        else {
+            applyTblStylePr(sourcePr, existing);
+        }
+    }
+}
+export function applyTblStylePr(source, destination) {
+    if (isEmptyTblStylePr(source))
+        return destination;
+    const s = source;
+    const out = destination !== null && destination !== void 0 ? destination : { TYPE_NAME: 'org_docx4j_wml.CTTblStylePr' };
+    out.pPr = applyPPr(s.pPr, out.pPr);
+    out.rPr = applyRPr(s.rPr, out.rPr);
+    out.tblPr = applyTblPr(s.tblPr, out.tblPr);
+    out.tcPr = applyTcPr(s.tcPr, out.tcPr);
+    out.trPr = applyTrPr(s.trPr, out.trPr);
+    out.type = s.type;
+    return out;
+}
+/**
+ * Apply one style's own properties over another's (docx4j `apply(Style, Style)`). It does not
+ * climb the `w:basedOn` chain; `PropertyResolver.ancestry` does that.
+ */
+export function applyStyle(source, destination) {
+    var _a;
+    if (isEmptyStyle(source))
+        return destination;
+    const s = source;
+    if (destination.type === undefined)
+        destination.type = s.type;
+    if (s.type === CHARACTER_STYLE) {
+        destination.rPr = applyRPr(s.rPr, destination.rPr);
+        return destination;
+    }
+    if (s.type === PARAGRAPH_STYLE || s.type === NUMBERING_STYLE) {
+        destination.pPr = applyPPr(s.pPr, destination.pPr);
+        destination.rPr = applyRPr(s.rPr, destination.rPr);
+        return destination;
+    }
+    destination.tblPr = applyTblPr(s.tblPr, destination.tblPr);
+    destination.trPr = applyTrPr(s.trPr, destination.trPr);
+    destination.tcPr = applyTcPr(s.tcPr, destination.tcPr);
+    (_a = destination.tblStylePr) !== null && _a !== void 0 ? _a : (destination.tblStylePr = []);
+    applyTblStylePrList(s.tblStylePr, destination.tblStylePr);
+    if (destination.tblStylePr.length === 0)
+        delete destination.tblStylePr;
+    destination.pPr = applyPPr(s.pPr, destination.pPr);
+    destination.rPr = applyRPr(s.rPr, destination.rPr);
+    return destination;
+}
+// ---------------------------------------------------------------- cycles
+/** docx4j's hard limit on deep `w:basedOn` hierarchies. */
+const CYCLE_LIMIT = 32;
+/**
+ * Whether the chain has come back to a style it has already seen (or has gone deeper than
+ * {@link CYCLE_LIMIT}). The caller degrades gracefully by using as much of the hierarchy as it
+ * has; set {@link throwOnCyclicStyles} to throw instead (docx4j's
+ * `docx4j.openpackaging.exceptions.CyclicStylesException.throw` property).
+ */
+export function isCyclic(styleId, seen) {
+    if (!seen.includes(styleId) && seen.length <= CYCLE_LIMIT)
+        return false;
+    log.warn(`Cycle detected in style basedOn hierarchy for: ${styleId} - stopping`);
+    if (throwOnCyclic)
+        throw new CyclicStylesException(`Cycle detected in style basedOn hierarchy for: ${styleId}`);
+    return true;
+}
+let throwOnCyclic = false;
+/** docx4j's `docx4j.openpackaging.exceptions.CyclicStylesException.throw`: off by default. */
+export function throwOnCyclicStyles(value) {
+    throwOnCyclic = value;
+}
+export function throwsOnCyclicStyles() {
+    return throwOnCyclic;
+}

package/dist/node/index.d.mts

@@ -0,0 +1 @@
+export { DirectoryPartStore, DirectoryPartSink } from '../opc/DirectoryPartStore.mjs';

package/dist/node/index.mjs

@@ -0,0 +1,12 @@
+// `@docx4j/core-ts/node`: the parts of the engine that need Node's own APIs.
+//
+// Everything else in this package runs unchanged in a browser or a Word add-in, which is why the
+// `node:` imports are fenced off here: nothing under `.`, `./opc`, `./parts`, `./packages`,
+// `./model` or `./office-js` reaches a Node builtin, so a bundle for the web never has to shim
+// `node:fs`. Import this subpath only from code you know runs in Node.
+//
+//   import { DirectoryPartStore, DirectoryPartSink } from '@docx4j/core-ts/node';
+//
+//   const pkg = await WordprocessingMLPackage.load(await DirectoryPartStore.open('unzipped'));
+//   await pkg.saveTo(new DirectoryPartSink('unzipped-out'));
+export { DirectoryPartStore, DirectoryPartSink } from '../opc/DirectoryPartStore.mjs';

package/dist/office-js/document.d.mts

@@ -0,0 +1,111 @@
+import type { WordprocessingMLPackage } from '../packages/WordprocessingMLPackage.mjs';
+import type { Body } from '../model/content/Body.mjs';
+import type { Range } from '../model/content/Range.mjs';
+import type { TrackedChange } from '../model/content/TrackedChange.mjs';
+import type { ChangeTrackingModeValue } from './enums.mjs';
+/** What `Word.run` was given: the selection to hand to `getSelection()`, and the preparation to do. */
+export interface RunOptions {
+    /** The range `context.document.getSelection()` returns; there is no host selection in Node. */
+    selection?: Range;
+    /**
+     * Unmarshal the core and extended properties and the settings parts before the callback, so
+     * that `document.properties` and `document.changeTrackingMode` read synchronously as Office JS
+     * does (default true). False leaves those parts untouched, and reads of them then report
+     * nothing; a write throws.
+     */
+    unmarshalSideParts?: boolean;
+}
+/**
+ * A subset of Office JS `Word.DocumentProperties` over `docProps/core.xml` (docx4j
+ * DocPropsCorePart) and `docProps/app.xml` (DocPropsExtendedPart). Reads report '' or undefined
+ * when a property is absent; a write creates the part when the package has none.
+ */
+export declare class DocumentProperties {
+    private readonly pkg;
+    constructor(pkg: WordprocessingMLPackage);
+    private coreProps;
+    private extendedProps;
+    /** dc:title. */
+    get title(): string;
+    set title(value: string);
+    /** dc:subject. */
+    get subject(): string;
+    set subject(value: string);
+    /** dc:creator (Office JS calls it the author). */
+    get author(): string;
+    set author(value: string);
+    /** dc:description (Office JS calls it comments). */
+    get comments(): string;
+    set comments(value: string);
+    /** cp:keywords. */
+    get keywords(): string;
+    set keywords(value: string);
+    /** cp:category. */
+    get category(): string;
+    set category(value: string);
+    /** cp:lastModifiedBy. */
+    get lastAuthor(): string;
+    set lastAuthor(value: string);
+    /** cp:revision. */
+    get revisionNumber(): string;
+    set revisionNumber(value: string);
+    /** dcterms:created. */
+    get creationDate(): Date | undefined;
+    set creationDate(value: Date | undefined);
+    /** dcterms:modified. */
+    get lastSaveTime(): Date | undefined;
+    set lastSaveTime(value: Date | undefined);
+    /** cp:lastPrinted. */
+    get lastPrintDate(): Date | undefined;
+    set lastPrintDate(value: Date | undefined);
+    /** Manager (extended properties). */
+    get manager(): string;
+    set manager(value: string);
+    /** Company (extended properties). */
+    get company(): string;
+    set company(value: string);
+    /** Application (extended properties). */
+    get applicationName(): string;
+    set applicationName(value: string);
+    /** Template (extended properties). */
+    get template(): string;
+    set template(value: string);
+    /** DocSecurity (extended properties); read only, as Office JS. */
+    get security(): number;
+}
+/**
+ * A subset of Office JS `Word.Document` over a package. `body` is the main document part's body;
+ * everything else is the document-level surface add-in code reaches for first.
+ */
+export declare class Document {
+    /** The package this document is (extension: Office JS has no package). */
+    readonly package_: WordprocessingMLPackage;
+    private readonly options;
+    readonly properties: DocumentProperties;
+    constructor(
+    /** The package this document is (extension: Office JS has no package). */
+    package_: WordprocessingMLPackage, options?: RunOptions);
+    /** The main document part's body; `Word.run` unmarshalled the part before the callback. */
+    get body(): Body;
+    /** The caller's selection (`Word.run(pkg, fn, { selection })`); there is none in Node. */
+    getSelection(): Range;
+    /**
+     * Office JS `document.changeTrackingMode`: the package's, which is `w:trackRevisions` in the
+     * settings part and, while it is on, makes every edit through the content API write revision
+     * markup (CR-002 phase F). The shim adds nothing of its own; `Word.run` has unmarshalled the
+     * settings part, so both directions are synchronous here.
+     */
+    get changeTrackingMode(): ChangeTrackingModeValue;
+    set changeTrackingMode(mode: ChangeTrackingModeValue);
+    /** Office JS `document.getTrackedChanges()`: the body's, in document order (CR-002 phase F). */
+    getTrackedChanges(): TrackedChange[];
+    /**
+     * The comments of the document. CR-002 phase G puts `getComments()` on `Body`; until it lands
+     * this reports none, so add-in code that lists comments runs either way.
+     */
+    getComments(): unknown[] | Promise<unknown[]>;
+    /** The whole document as a flat OPC `pkg:package` string, as Office JS's `body.getOoxml()`. */
+    getOoxml(): Promise<string>;
+    /** The document as a docx (extension; Office JS's `save()` saves in the host). */
+    save(): Promise<Uint8Array>;
+}