@docx4j/core-ts 0.5.0 → 0.6.0

package/dist/model/listnumbering/Emulator.d.mts

@@ -64,7 +64,8 @@ export interface NumberingResult {
     ilvl: string | undefined;
     /** The level definition, merged. Not docx4j's: a port convenience for CR-002 phase H. */
     level: LevelDefinition | undefined;
-    /** The counter's value at this level, before formatting. Not docx4j's. */
+    /** The count this paragraph's level shows (the 3 of "1.3."), its counter once this paragraph is
+     *  counted. docx4j `getValue()` (17.3.4), which this preceded. */
     count: number | undefined;
     /** No label was produced. docx4j returns an *empty* `ResultTriple` where a `w:num` or its
      *  level has no definition; this flags that case rather than leaving every member undefined
@@ -117,8 +118,32 @@ export declare class Emulator {
      * to.  The style itself, or any style it is based on, counts as the level's own.  Direct
      * formatting is never suppressed: a paragraph whose *own* `w:numPr` names such a level is
      * numbered.
+     *
+     * A level which names no style belongs to one all the same: the first paragraph style in
+     * styles.xml whose own `w:numPr` names it ({@link levelStyleId}, docx4j 17.3.4, measured in
+     * Word 365 on the three documents of docx4j's `LevelOwnerTest`).  Of two styles carrying such
+     * a level Word numbers the first in styles.xml - whatever their names, whichever the document
+     * uses first, whether or not it uses that style at all - and gives the other style's paragraphs
+     * no label and no count.  They keep the level's indent, which the effective indent already
+     * gives them.  A paragraph naming no style is the default paragraph style's in this check.
      */
     styleLinkedElsewhere(numId: string, ilvl: string, pStyleVal: string | undefined): boolean;
+    /**
+     * The paragraph style a numbering level belongs to: the one its `w:lvl/w:pStyle` names (the
+     * `w:num`'s override level's first, as {@link NumberingDefinitions.getLinkedStyleId} reads it),
+     * else the first paragraph style in styles.xml whose own `w:numPr` names a `w:num` on the same
+     * `w:abstractNum` at that level (its `w:ilvl`, 0 where it states none).  Undefined where neither:
+     * no style carries the level, so a paragraph reaches it only through its own `w:numPr`.
+     *
+     * The level is the `w:abstractNum`'s, not a `w:num`'s: a style reaching it through a second
+     * `w:num` is on the same level, even where that `w:num` overrides it with a `w:lvl` of its own.
+     * A style's level is its `w:numPr`'s `w:ilvl`, not the level whose `w:pStyle` names it, as Word
+     * reads it (ECMA-376 17.9.24 has the naming level). docx4j `Emulator.levelStyleId` (17.3.4).
+     *
+     * @param numId a `w:numId` (not 0)
+     * @param ilvl  a `w:ilvl`; undefined or empty for 0
+     */
+    levelStyleId(numId: string, ilvl: string | undefined): string | undefined;
     /**
      * The one resolution of numId and ilvl for a paragraph. docx4j `Emulator.resolve`
      * (CR-014 phase 3, which collapsed `getNumber`'s and `getInd`'s two copies onto it).
@@ -135,13 +160,18 @@ export declare class Emulator {
     resolve(pStyleVal: string | undefined, numId: string | undefined, ilvl: string | undefined, directNumPr: boolean): NumRef;
     /**
      * The numbering reference a paragraph resolves to, without taking a number and without
-     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.
+     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.  A paragraph with
+     * no `w:pPr` resolves as an empty one, against the default paragraph style, as
+     * {@link getNumber} resolves it (docx4j `c283dffdb`, 17.3.4).
      */
     numRefFor(pPr: wml.PPr | undefined): NumRef;
     /**
      * The next number for a paragraph, from its `w:pPr` (its own `w:numPr`, else its style's),
      * counted in `state` or in this emulator's default state.
      *
+     * A paragraph with no `w:pPr` resolves as one with an empty `w:pPr` does, against the default
+     * paragraph style, which may be numbered (docx4j 17.3.4; before, it was not numbered).
+     *
      * @returns undefined where the paragraph is not numbered
      */
     getNumber(pPr: wml.PPr | undefined, state?: NumberingState): NumberingResult | undefined;
@@ -176,11 +206,13 @@ export declare class Emulator {
     static peek(pkg: NumberedPackageLike, pPr: wml.PPr | undefined, state?: NumberingState): NumberingResult | undefined;
     /**
      * docx4j `Emulator.numRefFor(wmlPackage, pPr)`: where this paragraph's numbering resolves to,
-     * before any counting.  Never undefined; a package with no numbering part, a null `w:pPr` or
-     * a package whose `PropertyResolver` has not been built each answer {@link NumRef.notNumbered}
-     * with the reason.
+     * before any counting.  Never undefined; a package with no numbering part or a package whose
+     * `PropertyResolver` has not been built each answer {@link NumRef.notNumbered} with the reason.
+     * A null `w:pPr` resolves as an empty one (docx4j `c283dffdb`, 17.3.4).
      */
     static numRefFor(pkg: NumberedPackageLike | undefined, pPr: wml.PPr | undefined): NumRef;
+    /** docx4j `Emulator.levelStyleId(numberingPart, numId, levelId)`: the paragraph style a level belongs to. */
+    static levelStyleId(part: NumberingPartLike, numId: string, ilvl: string | undefined): string | undefined;
     /** docx4j `Emulator.getInd(wmlPackage, pStyleVal, numId, levelId)`. */
     static getInd(pkg: NumberedPackageLike, pStyleVal: string | undefined, numId: string | undefined, ilvl: string | undefined): wml.PPrBase.Ind | undefined;
     toString(): string;

package/dist/model/listnumbering/Emulator.mjs

@@ -70,12 +70,23 @@ export class Emulator {
      * to.  The style itself, or any style it is based on, counts as the level's own.  Direct
      * formatting is never suppressed: a paragraph whose *own* `w:numPr` names such a level is
      * numbered.
+     *
+     * A level which names no style belongs to one all the same: the first paragraph style in
+     * styles.xml whose own `w:numPr` names it ({@link levelStyleId}, docx4j 17.3.4, measured in
+     * Word 365 on the three documents of docx4j's `LevelOwnerTest`).  Of two styles carrying such
+     * a level Word numbers the first in styles.xml - whatever their names, whichever the document
+     * uses first, whether or not it uses that style at all - and gives the other style's paragraphs
+     * no label and no count.  They keep the level's indent, which the effective indent already
+     * gives them.  A paragraph naming no style is the default paragraph style's in this check.
      */
     styleLinkedElsewhere(numId, ilvl, pStyleVal) {
         var _a, _b;
-        const linked = this.definitions.getLinkedStyleId(numId, ilvl);
+        const linked = this.levelStyleId(numId, ilvl);
         if (linked === undefined || linked === '')
             return false;
+        // a paragraph naming no style is in the default paragraph style, which can own a level
+        if (pStyleVal === undefined && this.resolver !== undefined)
+            pStyleVal = this.resolver.getDefaultParagraphStyleId();
         if (pStyleVal === undefined)
             return true;
         const seen = new Set();
@@ -89,6 +100,42 @@ export class Emulator {
         }
         return true;
     }
+    /**
+     * The paragraph style a numbering level belongs to: the one its `w:lvl/w:pStyle` names (the
+     * `w:num`'s override level's first, as {@link NumberingDefinitions.getLinkedStyleId} reads it),
+     * else the first paragraph style in styles.xml whose own `w:numPr` names a `w:num` on the same
+     * `w:abstractNum` at that level (its `w:ilvl`, 0 where it states none).  Undefined where neither:
+     * no style carries the level, so a paragraph reaches it only through its own `w:numPr`.
+     *
+     * The level is the `w:abstractNum`'s, not a `w:num`'s: a style reaching it through a second
+     * `w:num` is on the same level, even where that `w:num` overrides it with a `w:lvl` of its own.
+     * A style's level is its `w:numPr`'s `w:ilvl`, not the level whose `w:pStyle` names it, as Word
+     * reads it (ECMA-376 17.9.24 has the naming level). docx4j `Emulator.levelStyleId` (17.3.4).
+     *
+     * @param numId a `w:numId` (not 0)
+     * @param ilvl  a `w:ilvl`; undefined or empty for 0
+     */
+    levelStyleId(numId, ilvl) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const linked = this.definitions.getLinkedStyleId(numId, ilvl);
+        if (linked !== undefined && linked !== '')
+            return linked;
+        const abstract = (_a = this.definitions.list(numId)) === null || _a === void 0 ? void 0 : _a.abstractDefinition;
+        if (abstract === undefined)
+            return undefined;
+        const level = ilvl === undefined || ilvl === '' ? '0' : ilvl;
+        for (const style of (_c = (_b = this.resolver) === null || _b === void 0 ? void 0 : _b.getStylesInOrder()) !== null && _c !== void 0 ? _c : []) {
+            const own = (_d = style.pPr) === null || _d === void 0 ? void 0 : _d.numPr;
+            if (style.type !== 'paragraph' || style.styleId === undefined || ((_e = own === null || own === void 0 ? void 0 : own.numId) === null || _e === void 0 ? void 0 : _e.val) === undefined)
+                continue;
+            if (((_f = this.definitions.list(String(own.numId.val))) === null || _f === void 0 ? void 0 : _f.abstractDefinition) !== abstract)
+                continue;
+            const ownLevel = ((_g = own.ilvl) === null || _g === void 0 ? void 0 : _g.val) === undefined ? '0' : String(own.ilvl.val);
+            if (ownLevel === level)
+                return style.styleId;
+        }
+        return undefined;
+    }
     /**
      * The one resolution of numId and ilvl for a paragraph. docx4j `Emulator.resolve`
      * (CR-014 phase 3, which collapsed `getNumber`'s and `getInd`'s two copies onto it).
@@ -171,11 +218,13 @@ export class Emulator {
     }
     /**
      * The numbering reference a paragraph resolves to, without taking a number and without
-     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.
+     * touching any state. docx4j `Emulator.numRefFor` (17.1.1); never undefined.  A paragraph with
+     * no `w:pPr` resolves as an empty one, against the default paragraph style, as
+     * {@link getNumber} resolves it (docx4j `c283dffdb`, 17.3.4).
      */
     numRefFor(pPr) {
         if (pPr === undefined)
-            return NumRef.not('no pPr');
+            return this.resolve(undefined, undefined, undefined, false);
         const [pStyleVal, numId, ilvl] = readNumPr(pPr);
         return this.resolve(pStyleVal, numId, ilvl, numId !== undefined && numId !== '');
     }
@@ -184,11 +233,14 @@ export class Emulator {
      * The next number for a paragraph, from its `w:pPr` (its own `w:numPr`, else its style's),
      * counted in `state` or in this emulator's default state.
      *
+     * A paragraph with no `w:pPr` resolves as one with an empty `w:pPr` does, against the default
+     * paragraph style, which may be numbered (docx4j 17.3.4; before, it was not numbered).
+     *
      * @returns undefined where the paragraph is not numbered
      */
     getNumber(pPr, state) {
         if (pPr === undefined)
-            return undefined;
+            return this.getNumberOf(undefined, undefined, undefined, false, state);
         const [pStyleVal, numId, ilvl] = readNumPr(pPr);
         return this.getNumberOf(pStyleVal, numId, ilvl, numId !== undefined && numId !== '', state);
     }
@@ -280,13 +332,11 @@ export class Emulator {
     }
     /**
      * docx4j `Emulator.numRefFor(wmlPackage, pPr)`: where this paragraph's numbering resolves to,
-     * before any counting.  Never undefined; a package with no numbering part, a null `w:pPr` or
-     * a package whose `PropertyResolver` has not been built each answer {@link NumRef.notNumbered}
-     * with the reason.
+     * before any counting.  Never undefined; a package with no numbering part or a package whose
+     * `PropertyResolver` has not been built each answer {@link NumRef.notNumbered} with the reason.
+     * A null `w:pPr` resolves as an empty one (docx4j `c283dffdb`, 17.3.4).
      */
     static numRefFor(pkg, pPr) {
-        if (pPr === undefined)
-            return NumRef.not('no pPr');
         const part = numberingPartOf(pkg);
         if (part === undefined)
             return NumRef.not('no numbering part');
@@ -296,6 +346,10 @@ export class Emulator {
         }
         return part.getEmulator().numRefFor(pPr);
     }
+    /** docx4j `Emulator.levelStyleId(numberingPart, numId, levelId)`: the paragraph style a level belongs to. */
+    static levelStyleId(part, numId, ilvl) {
+        return part.getEmulator().levelStyleId(numId, ilvl);
+    }
     /** docx4j `Emulator.getInd(wmlPackage, pStyleVal, numId, levelId)`. */
     static getInd(pkg, pStyleVal, numId, ilvl) {
         var _a;

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

@@ -1,6 +1,10 @@
 import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as dml from '@docx4j/generated-objects-ts/modules/org_docx4j_dml';
 import { NumberingDefinitions } from '../listnumbering/definitions.mjs';
 import { CellContext, TableContext } from './table.mjs';
+import { ThemeColors } from '../color/ThemeColors.mjs';
+import type { ResolvedColor } from '../color/ResolvedColor.mjs';
+import { type DefaultTheme, type FontSettings } from '../fonts/defaultTheme.mjs';
 /** The parts the resolver reads. Structural, so this module imports no part class. */
 export interface ResolverSource {
     /** The styles part's `w:styles`, or undefined when the package has none. */
@@ -9,9 +13,14 @@ export interface ResolverSource {
     numbering?: wml.Numbering;
     /**
      * The settings part's `w:settings`, or undefined: read for the compatibility mode and
-     * `overrideTableStyleFontSizeAndJustification` (CR-007). A document with none is in mode 12.
+     * `overrideTableStyleFontSizeAndJustification` (CR-007), and `w:clrSchemeMapping` (CR-008).
+     * A document with none is in mode 12.
      */
     settings?: wml.CTSettings;
+    /** The theme part's `a:theme`, or undefined where the package has none (CR-008). */
+    theme?: dml.Theme;
+    /** The bundled theme a package with no theme part is read as having; `defaultThemeSetting()`'s where undefined. */
+    defaultTheme?: DefaultTheme;
 }
 /** As much of an `XmlPart<T>` as the resolver uses. */
 interface ReadablePart<T> {
@@ -25,7 +34,9 @@ interface PackageLike {
         styleDefinitionsPart?: ReadablePart<wml.Styles>;
         numberingDefinitionsPart?: ReadablePart<wml.Numbering>;
         documentSettingsPart?: ReadablePart<wml.CTSettings>;
+        themePart?: ReadablePart<dml.Theme>;
     };
+    fonts?: FontSettings;
 }
 /** 108 twips (0.08in): the left and right cell margin of Word's built-in Normal Table. */
 export declare const WORD_DEFAULT_CELL_MARGIN_TWIPS = 108;
@@ -48,6 +59,8 @@ export declare class PropertyResolver {
     /** A style's `w:basedOn` chain merged root-first, WITHOUT the document defaults, per style id. */
     private readonly chainPPrCache;
     private readonly chainRPrCache;
+    /** A character style's chain as it applies to a run, where it differs from its chain: see {@link characterLevel}. */
+    private readonly characterLevelCache;
     /** The document defaults with the chain applied over them: what the style overloads return. */
     private readonly effectivePPrByStyle;
     private readonly effectiveRPrByStyle;
@@ -68,6 +81,8 @@ export declare class PropertyResolver {
      * where they state one. Read once per `refresh()`.
      */
     private docDefaultsStateSize;
+    /** Whether a paragraph style and a character style hide a run, by paragraph style then character style (`isVanishedByStyles`). */
+    private readonly vanishCache;
     /** Missing styles are logged once each per resolver. */
     private readonly missingLogged;
     private numberingDefinitions;
@@ -104,6 +119,28 @@ export declare class PropertyResolver {
      * contents replaced. The content API calls it where it creates a style.
      */
     refresh(): void;
+    private themeColors;
+    /**
+     * The document's theme colours: its theme part (or the bundled theme `pkg.fonts.defaultTheme` names where it has
+     * none) and the settings' `w:clrSchemeMapping`. Read once per `refresh()`. A resolver made `fromSource` with no
+     * theme parses the bundled one, which needs the objects package's context built (`ThemeColors.loadDefaultTheme()`).
+     */
+    getThemeColors(): ThemeColors;
+    /**
+     * The colour Word draws for a run's `w:color`: its theme reference where it has one (the value beside it is a
+     * cache), else its value.
+     *
+     * @returns undefined for automatic: the caller's default (black text, as a rule)
+     */
+    resolveColor(color: wml.Color | undefined): ResolvedColor | undefined;
+    /** A border's colour, as {@link resolveColor}; undefined for automatic. docx4j `resolveColor(CTBorder)`. */
+    resolveBorderColor(border: wml.CTBorder | undefined): ResolvedColor | undefined;
+    /** An underline's colour, as {@link resolveColor}; undefined for automatic (the text's). docx4j `resolveColor(U)`. */
+    resolveUnderlineColor(u: wml.U | undefined): ResolvedColor | undefined;
+    /** A shading's fill (`w:fill`, `w:themeFill`); undefined for automatic. */
+    resolveFill(shd: wml.CTShd | undefined): ResolvedColor | undefined;
+    /** A shading's pattern colour (`w:color`, `w:themeColor`); undefined for automatic. */
+    resolvePatternColor(shd: wml.CTShd | undefined): ResolvedColor | undefined;
     getDocumentDefaultPPr(): wml.PPr;
     getDocumentDefaultRPr(): wml.RPr;
     /** The style id of the `w:default="1"` paragraph style, or undefined when the part declares none. */
@@ -112,6 +149,13 @@ export declare class PropertyResolver {
     getResolvedDefaultParagraphStyle(): wml.PPr;
     /** The style with this id, or undefined (docx4j `getStyle`). */
     getStyle(styleId: string | undefined): wml.Style | undefined;
+    /**
+     * The styles part's `w:style` elements in document order, from the tree this resolver reads (its
+     * private copy, or the part's own once that is unmarshalled); empty where there is no styles part.
+     * docx4j reads `StyleDefinitionsPart.getJaxbElement().getStyle()` where order matters
+     * (`Emulator.levelStyleId`: the first paragraph style in styles.xml carrying a level owns it).
+     */
+    getStylesInOrder(): readonly wml.Style[];
     /**
      * The list definitions of the numbering part this resolver read (CR-001 Phase B step 3), or
      * undefined where the package has none. The resolver builds them because the paragraph merge
@@ -138,6 +182,13 @@ export declare class PropertyResolver {
      * object: copy before changing.
      */
     getChainRPr(styleId: string | undefined): wml.RPr;
+    /**
+     * A character style's chain as a level over a run or a paragraph mark: {@link getChainRPr} without its highlight,
+     * since Word draws no highlight from a character style (docx4j CR-060 section 13, round 6: alone, with bold, or
+     * through `w:basedOn`; its save writes `w:highlight="none"` on such a run). A paragraph style's highlight and a
+     * run's own are drawn. docx4j `characterLevel` (1d1b824a9). Cached; live: copy before changing.
+     */
+    private characterLevel;
     /**
      * A style's own `w:pPr` as a layer of its chain. The built-in heading styles have a fixed
      * outline level, which Word takes from the style's built-in NAME ("heading 1" ...
@@ -199,6 +250,14 @@ export declare class PropertyResolver {
      * context resolves exactly as `getEffectiveRPr(rPr, pPr)`. A new object each call.
      */
     getEffectiveRPr(rPr: wml.RPr | undefined, pPr: wml.PPr | undefined, cellContext: CellContext | undefined): wml.RPr;
+    /**
+     * Whether a run with no `w:vanish` of its own is hidden by its styles: the effective `w:vanish` of its
+     * paragraph style (undefined: the default paragraph style) and its character style, the table style left
+     * out, as the text model's hidden rule has it (REQ-507). What `Paragraph.text` leaves out, as Office JS
+     * does (CR-012 phase 4, check 48b case 20). Cached per pair; a pair naming a style the part lacks is
+     * not cached, so that adding the style is seen.
+     */
+    isVanishedByStyles(paragraphStyleId: string | undefined, runStyleId: string | undefined): boolean;
     private effectiveRPrOfStyle;
     /**
      * The character style's chain, then the direct formatting.

package/dist/model/properties/PropertyResolver.mjs

@@ -4,6 +4,9 @@ import { log } from './log.mjs';
 import { NumberingDefinitions } from '../listnumbering/definitions.mjs';
 import { applyPPr, applyPPrBase, applyRPr, applyStyle, applyStyleLevel, applyTblPr, applyToggles, hasDirectFormattingPPr, hasDirectFormattingRPr, isCyclic, isEmptyStyle, } from './styleUtil.mjs';
 import { TableContext, enclosingCellOf } from './table.mjs';
+import { ThemeColors } from '../color/ThemeColors.mjs';
+import { WordColors } from '../color/WordColors.mjs';
+import { themeOfSettings } from '../fonts/defaultTheme.mjs';
 /** The cache key for "no style" (a styles part with no default paragraph style). */
 const NO_STYLE = '';
 /** An empty table style: what a table with no style to apply contributes. Shared, never changed. */
@@ -110,6 +113,8 @@ export class PropertyResolver {
         /** A style's `w:basedOn` chain merged root-first, WITHOUT the document defaults, per style id. */
         this.chainPPrCache = new Map();
         this.chainRPrCache = new Map();
+        /** A character style's chain as it applies to a run, where it differs from its chain: see {@link characterLevel}. */
+        this.characterLevelCache = new Map();
         /** The document defaults with the chain applied over them: what the style overloads return. */
         this.effectivePPrByStyle = new Map();
         this.effectiveRPrByStyle = new Map();
@@ -130,6 +135,8 @@ export class PropertyResolver {
          * where they state one. Read once per `refresh()`.
          */
         this.docDefaultsStateSize = false;
+        /** Whether a paragraph style and a character style hide a run, by paragraph style then character style (`isVanishedByStyles`). */
+        this.vanishCache = new Map();
         /** Missing styles are logged once each per resolver. */
         this.missingLogged = new Set();
         this.source = provider();
@@ -169,10 +176,24 @@ export class PropertyResolver {
         catch (e) {
             log.warn(`The settings part could not be read; taking compatibility mode ${DEFAULT_COMPATIBILITY_MODE}: ${String(e)}`);
         }
+        // the theme, for its colours (CR-008), privately too; where there is none, or it can't be read, the bundled theme
+        // the package names, parsed now so that getThemeColors() needn't wait
+        const themePart = main.themePart;
+        let privateTheme;
+        try {
+            privateTheme = themePart === undefined ? undefined : await themePart.readContents();
+        }
+        catch (e) {
+            log.warn(`The theme part could not be read; its colours are the default theme's: ${String(e)}`);
+        }
+        const defaultTheme = themeOfSettings(pkg.fonts);
+        await ThemeColors.loadDefaultTheme(defaultTheme);
         return new PropertyResolver(() => ({
             styles: (stylesPart === null || stylesPart === void 0 ? void 0 : stylesPart.isUnmarshalled) === true ? stylesPart.contents : privateStyles,
             numbering: (numberingPart === null || numberingPart === void 0 ? void 0 : numberingPart.isUnmarshalled) === true ? numberingPart.contents : privateNumbering,
             settings: (settingsPart === null || settingsPart === void 0 ? void 0 : settingsPart.isUnmarshalled) === true ? settingsPart.contents : privateSettings,
+            theme: (themePart === null || themePart === void 0 ? void 0 : themePart.isUnmarshalled) === true ? themePart.contents : privateTheme,
+            defaultTheme,
         }), () => stylesPart !== undefined && !stylesPart.isUnmarshalled);
     }
     /** Builds a resolver over object trees directly (a test, or parts already in hand). */
@@ -266,13 +287,52 @@ export class PropertyResolver {
     refresh() {
         this.chainPPrCache.clear();
         this.chainRPrCache.clear();
+        this.characterLevelCache.clear();
         this.effectivePPrByStyle.clear();
         this.effectiveRPrByStyle.clear();
+        this.vanishCache.clear();
         this.clearTableCaches();
         this.missingLogged.clear();
+        this.themeColors = undefined;
         this.source = this.provider();
         this.init();
     }
+    /**
+     * The document's theme colours: its theme part (or the bundled theme `pkg.fonts.defaultTheme` names where it has
+     * none) and the settings' `w:clrSchemeMapping`. Read once per `refresh()`. A resolver made `fromSource` with no
+     * theme parses the bundled one, which needs the objects package's context built (`ThemeColors.loadDefaultTheme()`).
+     */
+    getThemeColors() {
+        var _a, _b;
+        (_a = this.themeColors) !== null && _a !== void 0 ? _a : (this.themeColors = ThemeColors.ofTheme(this.source.theme, this.source.defaultTheme)
+            .withWordMapping((_b = this.source.settings) === null || _b === void 0 ? void 0 : _b.clrSchemeMapping));
+        return this.themeColors;
+    }
+    /**
+     * The colour Word draws for a run's `w:color`: its theme reference where it has one (the value beside it is a
+     * cache), else its value.
+     *
+     * @returns undefined for automatic: the caller's default (black text, as a rule)
+     */
+    resolveColor(color) {
+        return WordColors.of(color, this.getThemeColors());
+    }
+    /** A border's colour, as {@link resolveColor}; undefined for automatic. docx4j `resolveColor(CTBorder)`. */
+    resolveBorderColor(border) {
+        return WordColors.ofBorder(border, this.getThemeColors());
+    }
+    /** An underline's colour, as {@link resolveColor}; undefined for automatic (the text's). docx4j `resolveColor(U)`. */
+    resolveUnderlineColor(u) {
+        return WordColors.ofUnderline(u, this.getThemeColors());
+    }
+    /** A shading's fill (`w:fill`, `w:themeFill`); undefined for automatic. */
+    resolveFill(shd) {
+        return WordColors.fill(shd, this.getThemeColors());
+    }
+    /** A shading's pattern colour (`w:color`, `w:themeColor`); undefined for automatic. */
+    resolvePatternColor(shd) {
+        return WordColors.pattern(shd, this.getThemeColors());
+    }
     // ------------------------------------------------------------------ defaults
     getDocumentDefaultPPr() {
         return this.documentDefaultPPr;
@@ -292,6 +352,16 @@ export class PropertyResolver {
     getStyle(styleId) {
         return this.getLiveStyle(styleId);
     }
+    /**
+     * The styles part's `w:style` elements in document order, from the tree this resolver reads (its
+     * private copy, or the part's own once that is unmarshalled); empty where there is no styles part.
+     * docx4j reads `StyleDefinitionsPart.getJaxbElement().getStyle()` where order matters
+     * (`Emulator.levelStyleId`: the first paragraph style in styles.xml carrying a level owns it).
+     */
+    getStylesInOrder() {
+        var _a, _b;
+        return (_b = (_a = this.source.styles) === null || _a === void 0 ? void 0 : _a.style) !== null && _b !== void 0 ? _b : [];
+    }
     /**
      * The list definitions of the numbering part this resolver read (CR-001 Phase B step 3), or
      * undefined where the package has none. The resolver builds them because the paragraph merge
@@ -366,6 +436,24 @@ export class PropertyResolver {
         this.chainRPrCache.set(styleId, chain);
         return chain;
     }
+    /**
+     * A character style's chain as a level over a run or a paragraph mark: {@link getChainRPr} without its highlight,
+     * since Word draws no highlight from a character style (docx4j CR-060 section 13, round 6: alone, with bold, or
+     * through `w:basedOn`; its save writes `w:highlight="none"` on such a run). A paragraph style's highlight and a
+     * run's own are drawn. docx4j `characterLevel` (1d1b824a9). Cached; live: copy before changing.
+     */
+    characterLevel(styleId) {
+        const chain = this.getChainRPr(styleId);
+        if (chain.highlight === undefined)
+            return chain;
+        let level = this.characterLevelCache.get(styleId);
+        if (level === undefined) {
+            level = deepCopy(chain);
+            delete level.highlight;
+            this.characterLevelCache.set(styleId, level);
+        }
+        return level;
+    }
     /**
      * A style's own `w:pPr` as a layer of its chain. The built-in heading styles have a fixed
      * outline level, which Word takes from the style's built-in NAME ("heading 1" ...
@@ -452,6 +540,30 @@ export class PropertyResolver {
         this.applyCharacterStyleAndDirect(arg, effective);
         return effective;
     }
+    /**
+     * Whether a run with no `w:vanish` of its own is hidden by its styles: the effective `w:vanish` of its
+     * paragraph style (undefined: the default paragraph style) and its character style, the table style left
+     * out, as the text model's hidden rule has it (REQ-507). What `Paragraph.text` leaves out, as Office JS
+     * does (CR-012 phase 4, check 48b case 20). Cached per pair; a pair naming a style the part lacks is
+     * not cached, so that adding the style is seen.
+     */
+    isVanishedByStyles(paragraphStyleId, runStyleId) {
+        let byRunStyle = this.vanishCache.get(paragraphStyleId);
+        const cached = byRunStyle === null || byRunStyle === void 0 ? void 0 : byRunStyle.get(runStyleId);
+        if (cached !== undefined)
+            return cached;
+        const rPr = runStyleId === undefined ? undefined : { TYPE_NAME: 'org_docx4j_wml.RPr', rStyle: { TYPE_NAME: 'org_docx4j_wml.RStyle', val: runStyleId } };
+        const pPr = paragraphStyleId === undefined ? undefined : { TYPE_NAME: 'org_docx4j_wml.PPr', pStyle: { TYPE_NAME: 'org_docx4j_wml.PPrBase.PStyle', val: paragraphStyleId } };
+        const vanish = this.getEffectiveRPr(rPr, pPr).vanish;
+        const hidden = vanish !== undefined && vanish !== null && vanish.val !== false;
+        if ((paragraphStyleId === undefined || this.getLiveStyle(paragraphStyleId) !== undefined)
+            && (runStyleId === undefined || this.getLiveStyle(runStyleId) !== undefined)) {
+            if (!byRunStyle)
+                this.vanishCache.set(paragraphStyleId, byRunStyle = new Map());
+            byRunStyle.set(runStyleId, hidden);
+        }
+        return hidden;
+    }
     effectiveRPrOfStyle(styleId) {
         const cached = this.effectiveRPrByStyle.get(styleId);
         if (cached !== undefined)
@@ -481,7 +593,7 @@ export class PropertyResolver {
                 this.logMissing(runStyleId);
             }
             else {
-                applyStyleLevel(this.getChainRPr(runStyleId), effective, this.documentDefaultRPr);
+                applyStyleLevel(this.characterLevel(runStyleId), effective, this.documentDefaultRPr);
             }
         }
         if (hasDirectFormattingRPr(rPr))
@@ -521,7 +633,7 @@ export class PropertyResolver {
                 this.logMissing(runStyleId);
             }
             else {
-                applyStyleLevel(this.getChainRPr(runStyleId), effective, this.documentDefaultRPr);
+                applyStyleLevel(this.characterLevel(runStyleId), effective, this.documentDefaultRPr);
             }
         }
         applyRPr(mark, effective);
@@ -830,6 +942,7 @@ export class PropertyResolver {
         // resolution of this style (and of anything based on it) has to be recomputed
         this.chainPPrCache.clear();
         this.chainRPrCache.clear();
+        this.characterLevelCache.clear();
         this.effectivePPrByStyle.clear();
         this.effectiveRPrByStyle.clear();
         this.clearTableCaches();

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

@@ -41,11 +41,22 @@ export declare function isEmptyRStyle(value: wml.RStyle | undefined): boolean;
 export declare function isEmptyRFonts(value: wml.RFonts | undefined): boolean;
 /**
  * A `w:color` stating only a theme colour is not empty: it is inherited, where until docx4j CR-034
- * (2e381ef26) it was dropped.
+ * (2e381ef26) it was dropped. A value Word reads as absent (`F00`, `bogus`, `Auto`) is empty, so a style's
+ * colour beneath still shows, and only exactly `auto` overrides it (docx4j CR-060, {@link WordColors.stated};
+ * CR-015 section 2, rules 4 and 5).
  */
 export declare function isEmptyColor(value: wml.Color | undefined): boolean;
-/** The underline's colour attributes count, the theme ones too (docx4j CR-034, 2e381ef26). */
+/**
+ * The underline's colour attributes count, the theme ones too (docx4j CR-034, 2e381ef26); a colour Word reads as
+ * absent doesn't (docx4j CR-060, {@link WordColors.stated}).
+ */
 export declare function isEmptyU(value: wml.U | undefined): boolean;
+/** Whether a `w:highlight` value is one of `ST_HighlightColor`'s, compared case-exactly, as Word does (docx4j `WordRepairs.isHighlightColor`). */
+export declare function isHighlightColor(val: string | undefined): boolean;
+/**
+ * A value outside `ST_HighlightColor` (`YELLOW`, `bogus`), or none, is empty: Word's repair drops it, so a style's
+ * highlight beneath still shows (docx4j CR-060, its `StyleUtil.isEmpty(Highlight)`).
+ */
 export declare function isEmptyHighlight(value: wml.Highlight | undefined): boolean;
 /** @since CR-015 phase 1: a style stating only `w:lang` used to count as empty and was never applied. */
 export declare function isEmptyLang(value: wml.CTLanguage | undefined): boolean;
@@ -65,7 +76,10 @@ export declare function isEmptyTabs(value: wml.Tabs | undefined): boolean;
  * its own (CR-015 probe styles-numpr-ilvl-only).
  */
 export declare function isEmptyNumPr(value: wml.PPrBase.NumPr | undefined): boolean;
-/** `w:anchorLock` defaults to true, so only an explicit `w:anchorLock="0"` makes a frame non-empty by itself. */
+/**
+ * Empty only with `w:anchorLock` absent too, as docx4j 82c64bf14 reads it (its CR-059: until then
+ * `isAnchorLock()`, which the schema's old `default="true"` made true for an absent attribute).
+ */
 export declare function isEmptyFramePr(value: wml.CTFramePr | undefined): boolean;
 /** docx4j `apply(BooleanDefaultTrue, BooleanDefaultTrue)`: a copy of the source where it states one. */
 export declare function mergeBool(source: wml.BooleanDefaultTrue | undefined, destination: wml.BooleanDefaultTrue | undefined): wml.BooleanDefaultTrue | undefined;
@@ -131,8 +145,8 @@ export declare const mergeSpacing: Merge<wml.PPrBase.Spacing>;
 export declare const mergeTabs: Merge<wml.Tabs>;
 /**
  * `w:framePr`'s attributes each inherit on their own: a paragraph whose direct `w:framePr`
- * gives only `w:x`/`w:y` keeps the anchors its style states. `w:anchorLock` defaults to true,
- * and docx4j's merge writes that default out explicitly.
+ * gives only `w:x`/`w:y` keeps the anchors its style states, `w:anchorLock` among them (docx4j
+ * 82c64bf14 merges it as stated; until then its merge wrote `isAnchorLock()`'s default out).
  */
 export declare const mergeFramePr: Merge<wml.CTFramePr>;
 /**