@docx4j/core-ts 0.5.0 → 0.7.0

package/NOTICE

@@ -10,3 +10,7 @@ resolution utilities follow docx4j's design and names. It depends on @docx4j/gen
 (https://github.com/plutext/docx4j-generated-objects-ts) for the Office Open XML object model and on
 @docx4j/jsonix (https://github.com/plutext/jsonix) for XML binding; see their NOTICE files for the
 material they derive from (ECMA-376, Microsoft Open Specifications, Jsonix).
+
+The Markdown writer (src/model/text/commonmark.mts) is a port of the Markdown renderer of
+commonmark-java (https://github.com/commonmark/commonmark-java), Copyright (c) 2015, Atlassian Pty
+Ltd, under the BSD 2-Clause License; its notice and conditions are kept in that file.

package/README.md

@@ -45,9 +45,11 @@ const ooxml = await pkg.saveFlatOpc();              // pkg:package, for insertOo
 A part that is never touched is written back byte for byte; `getContents()` (or a view over
 it) marks a part for re-marshalling. `mc:AlternateContent` is kept with every branch, as docx4j
 keeps it: the content API reads the branch Word would (the first `mc:Choice` whose namespaces are
-understood, else the `mc:Fallback`), an edit lands in every branch, and a save writes them all
-(`{ mcePreprocess: true }` resolves the element when a part is unmarshalled instead, as Word does on
-open). Subpaths
+understood, else the `mc:Fallback`) at every level, and a save writes them all (`{ mcePreprocess: true }`
+resolves the element when a part is unmarshalled instead, as Word does on open). Among a paragraph's runs
+the branch read is edited in place and the others kept (CR-012 section 12). At block, row and cell level a
+view in a branch is read-only (`NotSupportedError`), while resolving tracked changes, `replaceText`, a
+tracked deletion, the column edits and the binding passes reach every branch (CR-013). Subpaths
 `@docx4j/core-ts/opc`, `/parts`, `/packages` and `/model` give the layers separately,
 `/office-js` the `Word` shim (below), `/html` HTML to WordprocessingML (a converter to an
 intermediate form and a builder from it, CR-005 section 8; the HTML parser is yours, a browser's
@@ -55,6 +57,66 @@ intermediate form and a builder from it, CR-005 section 8; the HTML parser is yo
 container; nothing else in the package imports a `node:` builtin, so a browser or add-in bundle
 never sees one).
 
+### Repairs
+
+Some packages Word opens only after its repair prompt, and some it won't open at all. `LoadOptions.repair`
+(WD REQ-207, [CR-031](docs/change-requests/CR-031-the-repair-option.md)) says how a load treats them:
+
+```ts
+const pkg = await WordprocessingMLPackage.load(bytes, { repair: 'word' });
+pkg.repaired;                                       // 'none', 'word' or 'own'; a text result's metadata.repaired says the same
+```
+
+| The package | `refuse`, the default | `word` | `all` |
+|---|---|---|---|
+| Two zip entries of one name (OPC part names, without case) | `DuplicateEntryException` | The first of each read, as Word does: `package.duplicate_entry` | As `word` |
+| More than one `officeDocument` relationship | `MultipleMainPartsException` | The last one's target read, as a fresh Word does: `package.multiple_main_parts` | As `word` |
+| A relationships part in another namespace, or in none | `RelationshipsNamespaceException` | Every relationship read by its local name, as Word does: `package.relationships_namespace` | As `word` |
+| An `External` `officeDocument` relationship beside an internal one | `ExternalMainPartException` | Refused: Word refuses it even through its repair | This package's own repair: the internal part read, every `External` main relationship dropped, its URL never fetched: `package.external_main_part` |
+| An `External` `officeDocument` relationship alone | Refused: no main document part (REQ-321) | Refused | Refused |
+
+Each warning is on `pkg.warnings` and, in the text model, a warning of the same code. A save then writes the
+repaired package: one entry of each name, one main relationship, the right namespace, no `External` main
+relationship. `repair` doesn't open the save's own gate ([CR-025](docs/change-requests/CR-025-dropped-content-reported.md)):
+a changed part is written without what Word's own save drops too, such as an ignorable element Word doesn't understand,
+each listed on `pkg.lastSave.dropped`; one that would lose anything else Word keeps, or won't open, needs
+`pkg.checkLossOnSave = false`, each item then on `pkg.lastSave.lost`. Each `part.skipped` warning says which (`onSave`). The other shapes
+Word repairs, such as an undeclared `mc:Ignorable` prefix or an element the model has no place for, read the same at
+every value (CR-031 section 2.1.1).
+
+### Saving
+
+A save copies every part nothing changed byte for byte, and re-marshals only what was read. Before it writes
+anything, it checks what it would write. It refuses a file Word would refuse or repair, and a save that would lose
+content Word keeps. Each check has a switch on the package, and each records what it let through on `pkg.lastSave`:
+
+| A save that would | Throws | To write it anyway | Recorded on `pkg.lastSave` |
+|---|---|---|---|
+| Write a child its container never admits: a run straight in the body, a table in a paragraph, a string in a run ([CR-016](docs/change-requests/CR-016-misplaced-content-refused.md)) | `MisplacedContentException` (`target.misplaced`, each child with its part, path and the fix) | `pkg.checkContentOnSave = false` | `misplaced` |
+| Lose what the read skipped, where Word's save keeps it or Word won't open the file ([CR-025](docs/change-requests/CR-025-dropped-content-reported.md)) | `SaveLossException` (`save.content_lost`, each part) | `pkg.checkLossOnSave = false` | `lost` |
+| Lose what the read skipped, where Word's own save drops it too | Nothing: written without it | | `dropped` |
+
+```ts
+import { SaveLossException } from '@docx4j/core-ts';
+
+try {
+  await pkg.save();
+} catch (e) {
+  if (!(e instanceof SaveLossException)) throw e;
+  pkg.checkLossOnSave = false;                      // accept the loss: e.losses names each part
+  await pkg.save();
+  pkg.lastSave.lost;                                // what went, each a part.skipped warning
+}
+```
+
+Only a part that was read is checked, so a package loaded and saved untouched is never refused. What a load found
+is on `pkg.warnings` before any save: content the read skipped (`part.skipped`, its `onSave` saying which row it
+falls in), misplaced children, and integer values past what Word stores (`value.out_of_range`, which a save writes
+as held and lists on `lastSave.outOfRange`). `part.checkContent()` and `pkg.checkContent()` run the first check on
+request, changing nothing. Two more switches change what a save writes: `pkg.normaliseOnSave` (run properties in
+Word's normal form, on by default) and `pkg.writeTimesOnSave` (the core properties' times, off by default).
+`pkg.dateTimeZone` is the time zone every revision's and comment's date is written and read in.
+
 ### Guides
 
 | | |
@@ -238,7 +300,33 @@ body.acceptAll();     // or rejectAll(), or accept()/reject() one at a time
 `getTrackedChanges()` is also on `Paragraph` and `Range`. Text and searches read the accepted
 view throughout, so an agent sees the document as it will read once the changes are taken. A moved
 paragraph is listed as its two halves, and accepting or rejecting either resolves the whole move,
-as Word's Review tab does.
+as Word's Review tab does. `accept()` and `reject()` return whether they acted: a change already
+resolved since it was listed, by its own view or another, is left alone and gives `false` (Office
+JS's return nothing).
+
+A body is one story. Every story at once - the main document, each footnote, endnote and comment,
+the headers and footers in the order the sections reference them, and the text boxes in each - is
+the package's, as docx4j lists it (`TrackedChanges.in`), with docx4j's kind and the part of each
+change. The listing and the resolve-all verbs take a filter: docx4j's conditions as an object, which
+travels as JSON, or a function over each single change. A group of touching changes is listed whole
+when any of its pieces matches, and resolved only in the pieces that match:
+
+```ts
+for (const change of await pkg.getAllTrackedChanges()) {
+  change.kind;        // docx4j's: 'RUN_INSERTION', 'PARAGRAPH_MARK_DELETION', 'TABLE_PROPERTIES', ...
+  change.part.partName.name;   // '/word/document.xml', '/word/footnotes.xml', '/word/header1.xml', ...
+}
+await pkg.rejectAllRevisions({ authors: ['Author B'] });
+await pkg.acceptAllRevisions({ types: ['Deleted'], from: '2026-10-01', parts: ['/word/document.xml'] });
+await pkg.acceptAllRevisions((change) => change.author === 'Claude');
+body.acceptAll({ kinds: ['RUN_DELETION'] });   // one story; a deleted paragraph's text goes, its mark stays
+```
+
+The conditions are `authors`, `types` (Office JS's names or docx4j's `ADDED`, `DELETED`,
+`FORMATTED`), `kinds`, `from` (inclusive) and `to` (exclusive), and `parts` (a part or its name).
+A key or a value the filter does not know throws a `TypeError`, before anything is resolved. With a
+filter, what no change owns (a `w:cellMerge`, a `w:numberingChange`) is left alone; without one it is
+swept, as before. Each verb returns how many listed changes had a matching piece.
 
 To record one caller's edits without touching the document's own setting - an agent working in a
 document whose `w:trackRevisions` belongs to its owner - use `withTracking`. Nothing is written

package/dist/html/convert.mjs

@@ -415,7 +415,8 @@ function cellFrom(el, w) {
     var _a, _b;
     const blocks = [];
     walkBlocks(el, blocks, w);
-    if (blocks.length === 0) {
+    // a cell ends with a paragraph, as Word reads it, after a table too (CR-002 section 55)
+    if (blocks.length === 0 || blocks[blocks.length - 1].kind === 'table') {
         blocks.push({ kind: 'paragraph', style: null, inlines: [] });
         w.report.paragraphs++;
     }

package/dist/html/elements.mjs

@@ -142,7 +142,8 @@ function tableXml(t, resolve) {
         w += (_a = widths[col + k]) !== null && _a !== void 0 ? _a : widths[0]; return w; };
     const tcPr = (col, span, merge) => `<w:tcPr><w:tcW w:w="${widthOf(col, span)}" w:type="dxa"/>${span > 1 ? `<w:gridSpan w:val="${span}"/>` : ''}${merge === 'restart' ? '<w:vMerge w:val="restart"/>' : merge === 'continue' ? '<w:vMerge/>' : ''}</w:tcPr>`;
     const cellXml = (c, col) => {
-        const blocks = c.blocks.length > 0 ? blocksToXml(c.blocks, resolve) : '<w:p/>';
+        const last = c.blocks[c.blocks.length - 1];
+        const blocks = last === undefined ? '<w:p/>' : blocksToXml(c.blocks, resolve) + (last.kind === 'table' ? '<w:p/>' : '');
         return `<w:tc>${tcPr(col, c.colspan, c.rowspan > 1 ? 'restart' : undefined)}${blocks}</w:tc>`;
     };
     // A cell spanning rows holds its place in the rows below with a continuation cell, as WordprocessingML writes a vertical merge.

package/dist/model/color/ColorMath.d.mts

@@ -0,0 +1,29 @@
+/** sRGB (0 to 1) to linear RGB (IEC 61966-2-1). */
+export declare function toLinear(c: number): number;
+/** linear RGB to sRGB, clamped to 0 to 1. */
+export declare function toSrgb(l: number): number;
+export declare function clamp01(v: number): number;
+/** a channel, 0 to 1, as 0 to 255, rounded half up */
+export declare function channel(v: number): number;
+/** a channel, 0 to 1, as 0 to 255, rounded half down (Office's luminance transforms) */
+export declare function channelHalfDown(v: number): number;
+/** [h, s, l], each 0 to 1, from sRGB channels 0 to 1; a grey's hue is 0 */
+export declare function rgbToHsl(r: number, g: number, b: number): [number, number, number];
+/**
+ * sRGB channels (0 to 1, clamped) from HSL; the saturation is not clamped, as Office does not clamp it (a
+ * saturation above 1 pushes a channel past its range, which is then clamped).
+ */
+export declare function hslToRgb(h: number, s: number, l: number): [number, number, number];
+/**
+ * sRGB channels (0 to 1, not clamped) from HSL as Foley and van Dam give it: the same colour as {@link hslToRgb}
+ * but not the same rounding error, and the one Office's luminance transforms round as.
+ */
+export declare function hslToRgbFoley(h: number, s: number, l: number): [number, number, number];
+export declare const HLSMAX = 240;
+/** [h, l, s] on 0 to 240, as Windows' ColorRGBToHLS (KB29240) computes them */
+export declare function rgbToHls240(r: number, g: number, b: number): [number, number, number];
+/**
+ * RGB from {@link rgbToHls240}'s values, as Windows' ColorHLSToRGB, except that a grey is rounded rather than
+ * truncated, which is what Excel's fills show (docx4j CR-034 section 11, P4).
+ */
+export declare function hls240ToRgb(h: number, l: number, s: number): [number, number, number];

package/dist/model/color/ColorMath.mjs

@@ -0,0 +1,146 @@
+// The colour arithmetic Office uses, as docx4j CR-034's probes measured it (section 11): sRGB's transfer function,
+// HSL with an unclamped saturation, and Windows' integer HLS for SpreadsheetML tints. docx4j
+// `org.docx4j.model.color.ColorMath`, expression for expression: JS numbers are IEEE doubles as Java's are, so the
+// same expressions in the same order give the same bits, which the luminance transforms' rounding depends on
+// (CR-008 section 3). Java's integer division is `Math.trunc` of the quotient here; nothing is simplified.
+// ------------------------------------------------------------------ sRGB and linear RGB
+/** sRGB (0 to 1) to linear RGB (IEC 61966-2-1). */
+export function toLinear(c) {
+    return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+/** linear RGB to sRGB, clamped to 0 to 1. */
+export function toSrgb(l) {
+    const c = clamp01(l);
+    return c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+export function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** a channel, 0 to 1, as 0 to 255, rounded half up */
+export function channel(v) {
+    return Math.floor(clamp01(v) * 255 + 0.5);
+}
+/** a channel, 0 to 1, as 0 to 255, rounded half down (Office's luminance transforms) */
+export function channelHalfDown(v) {
+    // Math.ceil(-0.5) is -0 in JS, 0 in Java's (int) cast; ResolvedColor's clamp makes either 0
+    return Math.ceil(clamp01(v) * 255 - 0.5);
+}
+// ------------------------------------------------------------------ HSL
+/** [h, s, l], each 0 to 1, from sRGB channels 0 to 1; a grey's hue is 0 */
+export function rgbToHsl(r, g, b) {
+    const max = Math.max(r, Math.max(g, b)), min = Math.min(r, Math.min(g, b));
+    const l = (max + min) / 2;
+    if (max === min)
+        return [0, 0, l];
+    const d = max - min;
+    const s = l <= 0.5 ? d / (max + min) : d / (2 - max - min);
+    let h;
+    if (max === r) {
+        h = ((g - b) / d) % 6;
+        if (h < 0)
+            h += 6;
+    }
+    else if (max === g) {
+        h = (b - r) / d + 2;
+    }
+    else {
+        h = (r - g) / d + 4;
+    }
+    return [h / 6, s, l];
+}
+/**
+ * sRGB channels (0 to 1, clamped) from HSL; the saturation is not clamped, as Office does not clamp it (a
+ * saturation above 1 pushes a channel past its range, which is then clamped).
+ */
+export function hslToRgb(h, s, l) {
+    return [hslChannel(0, h, s, l), hslChannel(8, h, s, l), hslChannel(4, h, s, l)];
+}
+/**
+ * sRGB channels (0 to 1, not clamped) from HSL as Foley and van Dam give it: the same colour as {@link hslToRgb}
+ * but not the same rounding error, and the one Office's luminance transforms round as.
+ */
+export function hslToRgbFoley(h, s, l) {
+    // keep this form and its order of operations, and don't fold it into hslToRgb: a channel that is exactly half a
+    // unit rounds (channelHalfDown) the way this form's floating-point error leans, which is the way Office rounds it
+    // (docx4j CR-034 section 11, follow-up: 29 of 30 halves; hslToRgb's error leans otherwise)
+    const m2 = l <= 0.5 ? l * (1 + s) : l + s - l * s, m1 = 2 * l - m2;
+    return [foley(m1, m2, h + 1 / 3.0), foley(m1, m2, h), foley(m1, m2, h - 1 / 3.0)];
+}
+function foley(m1, m2, h) {
+    h -= Math.floor(h);
+    if (h < 1 / 6.0)
+        return m1 + (m2 - m1) * 6 * h;
+    if (h < 1 / 2.0)
+        return m2;
+    if (h < 2 / 3.0)
+        return m1 + (m2 - m1) * (2 / 3.0 - h) * 6;
+    return m1;
+}
+function hslChannel(n, h, s, l) {
+    let k = (n + h * 12) % 12;
+    if (k < 0)
+        k += 12;
+    const a = s * Math.min(l, 1 - l);
+    return clamp01(l - a * Math.max(-1, Math.min(Math.min(k - 3, 9 - k), 1)));
+}
+// ------------------------------------------------------------------ Windows' integer HLS (Excel)
+export const HLSMAX = 240;
+const RGBMAX = 255;
+/** Java's int division. */
+const div = (a, b) => Math.trunc(a / b);
+/** [h, l, s] on 0 to 240, as Windows' ColorRGBToHLS (KB29240) computes them */
+export function rgbToHls240(r, g, b) {
+    const max = Math.max(r, Math.max(g, b)), min = Math.min(r, Math.min(g, b));
+    const l = div((max + min) * HLSMAX + RGBMAX, 2 * RGBMAX);
+    if (max === min)
+        return [div(HLSMAX * 2, 3), l, 0];
+    const s = l <= div(HLSMAX, 2)
+        ? div((max - min) * HLSMAX + div(max + min, 2), max + min)
+        : div((max - min) * HLSMAX + div(2 * RGBMAX - max - min, 2), 2 * RGBMAX - max - min);
+    const d = max - min;
+    const rd = div((max - r) * div(HLSMAX, 6) + div(d, 2), d);
+    const gd = div((max - g) * div(HLSMAX, 6) + div(d, 2), d);
+    const bd = div((max - b) * div(HLSMAX, 6) + div(d, 2), d);
+    let h;
+    if (r === max)
+        h = bd - gd;
+    else if (g === max)
+        h = div(HLSMAX, 3) + rd - bd;
+    else
+        h = div(2 * HLSMAX, 3) + gd - rd;
+    if (h < 0)
+        h += HLSMAX;
+    if (h > HLSMAX)
+        h -= HLSMAX;
+    return [h, l, s];
+}
+/**
+ * RGB from {@link rgbToHls240}'s values, as Windows' ColorHLSToRGB, except that a grey is rounded rather than
+ * truncated, which is what Excel's fills show (docx4j CR-034 section 11, P4).
+ */
+export function hls240ToRgb(h, l, s) {
+    if (s === 0) {
+        const v = div(l * RGBMAX + div(HLSMAX, 2), HLSMAX);
+        return [v, v, v];
+    }
+    const m2 = l <= div(HLSMAX, 2) ? div(l * (HLSMAX + s) + div(HLSMAX, 2), HLSMAX) : l + s - div(l * s + div(HLSMAX, 2), HLSMAX);
+    const m1 = 2 * l - m2;
+    return [
+        div(hueToRgb(m1, m2, h + div(HLSMAX, 3)) * RGBMAX + div(HLSMAX, 2), HLSMAX),
+        div(hueToRgb(m1, m2, h) * RGBMAX + div(HLSMAX, 2), HLSMAX),
+        div(hueToRgb(m1, m2, h - div(HLSMAX, 3)) * RGBMAX + div(HLSMAX, 2), HLSMAX)
+    ];
+}
+function hueToRgb(n1, n2, hue) {
+    if (hue < 0)
+        hue += HLSMAX;
+    if (hue > HLSMAX)
+        hue -= HLSMAX;
+    if (hue < div(HLSMAX, 6))
+        return n1 + div((n2 - n1) * hue + div(HLSMAX, 12), div(HLSMAX, 6));
+    if (hue < div(HLSMAX, 2))
+        return n2;
+    if (hue < div(HLSMAX * 2, 3))
+        return n1 + div((n2 - n1) * (div(HLSMAX * 2, 3) - hue) + div(HLSMAX, 12), div(HLSMAX, 6));
+    return n1;
+}

package/dist/model/color/ColorTables.d.mts

@@ -0,0 +1,6 @@
+/** `a:prstClr` names to RRGGBB. */
+export declare const PRESET: ReadonlyMap<string, string>;
+/** `a:sysClr` names to Windows' default RRGGBB. */
+export declare const SYSTEM: ReadonlyMap<string, string>;
+/** SpreadsheetML indexed colours 0 to 65. */
+export declare const INDEXED: readonly string[];

package/dist/model/color/ColorTables.mjs

@@ -0,0 +1,83 @@
+// The fixed colour tables: DrawingML's preset colours (`a:prstClr`), Windows' default system colours (`a:sysClr`,
+// which Office draws as the machine's colour, not `lastClr`: docx4j CR-034 section 11), and SpreadsheetML's legacy
+// indexed palette. docx4j `org.docx4j.model.color.ColorTables`, copied entry for entry.
+//
+// The preset and system values are Apache POI's `org.apache.poi.sl.usermodel.PresetColor` (trunk ae62bb5116,
+// Apache-2.0), keyed by the names docx4j's schema gives `ST_PresetColorVal` and `ST_SystemColorVal`. The indexed
+// palette is Excel 365's, read from its PDF of CR-034's probe tc-p4-spreadsheet.xlsx (2026-10-12): entries 0 to 63,
+// then 64 and 65, the system foreground and background.
+/** `a:prstClr` names to RRGGBB. */
+export const PRESET = new Map(Object.entries({
+    aliceBlue: 'F0F8FF', antiqueWhite: 'FAEBD7', aqua: '00FFFF',
+    aquamarine: '7FFFD4', azure: 'F0FFFF', beige: 'F5F5DC',
+    bisque: 'FFE4C4', black: '000000', blanchedAlmond: 'FFEBCD',
+    blue: '0000FF', blueViolet: '8A2BE2', brown: 'A52A2A',
+    burlyWood: 'DEB887', cadetBlue: '5F9EA0', chartreuse: '7FFF00',
+    chocolate: 'D2691E', coral: 'FF7F50', cornflowerBlue: '6495ED',
+    cornsilk: 'FFF8DC', crimson: 'DC143C', cyan: '00FFFF',
+    dkBlue: '00008B', dkCyan: '008B8B', dkGoldenrod: 'B8860B',
+    dkGray: 'A9A9A9', dkGreen: '006400', dkKhaki: 'BDB76B',
+    dkMagenta: '8B008B', dkOliveGreen: '556B2F', dkOrange: 'FF8C00',
+    dkOrchid: '9932CC', dkRed: '8B0000', dkSalmon: 'E9967A',
+    dkSeaGreen: '8FBC8B', dkSlateBlue: '483D8B', dkSlateGray: '2F4F4F',
+    dkTurquoise: '00CED1', dkViolet: '9400D3', deepPink: 'FF1493',
+    deepSkyBlue: '00BFFF', dimGray: '696969', dodgerBlue: '1E90FF',
+    firebrick: 'B22222', floralWhite: 'FFFAF0', forestGreen: '228B22',
+    fuchsia: 'FF00FF', gainsboro: 'DCDCDC', ghostWhite: 'F8F8FF',
+    gold: 'FFD700', goldenrod: 'DAA520', gray: '808080',
+    green: '008000', greenYellow: 'ADFF2F', honeydew: 'F0FFF0',
+    hotPink: 'FF69B4', indianRed: 'CD5C5C', indigo: '4B0082',
+    ivory: 'FFFFF0', khaki: 'F0E68C', lavender: 'E6E6FA',
+    lavenderBlush: 'FFF0F5', lawnGreen: '7CFC00', lemonChiffon: 'FFFACD',
+    ltBlue: 'ADD8E6', ltCoral: 'F08080', ltCyan: 'E0FFFF',
+    ltGoldenrodYellow: 'FAFA78', ltGray: 'D3D3D3', ltGreen: '90EE90',
+    ltPink: 'FFB6C1', ltSalmon: 'FFA07A', ltSeaGreen: '20B2AA',
+    ltSkyBlue: '87CEFA', ltSlateGray: '778899', ltSteelBlue: 'B0C4DE',
+    ltYellow: 'FFFFE0', lime: '00FF00', limeGreen: '32CD32',
+    linen: 'FAF0E6', magenta: 'FF00FF', maroon: '800000',
+    medAquamarine: '66CDAA', medBlue: '0000CD', medOrchid: 'BA55D3',
+    medPurple: '9370DB', medSeaGreen: '3CB371', medSlateBlue: '7B68EE',
+    medSpringGreen: '00FA9A', medTurquoise: '48D1CC', medVioletRed: 'C71585',
+    midnightBlue: '191970', mintCream: 'F5FFFA', mistyRose: 'FFE4E1',
+    moccasin: 'FFE4B5', navajoWhite: 'FFDEAD', navy: '000080',
+    oldLace: 'FDF5E6', olive: '808000', oliveDrab: '6B8E23',
+    orange: 'FFA500', orangeRed: 'FF4500', orchid: 'DA70D6',
+    paleGoldenrod: 'EEE8AA', paleGreen: '98FB98', paleTurquoise: 'AFEEEE',
+    paleVioletRed: 'DB7093', papayaWhip: 'FFEFD5', peachPuff: 'FFDAB9',
+    peru: 'CD853F', pink: 'FFC0CB', plum: 'DDA0DD',
+    powderBlue: 'B0E0E6', purple: '800080', red: 'FF0000',
+    rosyBrown: 'BC8F8F', royalBlue: '4169E1', saddleBrown: '8B4513',
+    salmon: 'FA8072', sandyBrown: 'F4A460', seaGreen: '2E8B57',
+    seaShell: 'FFF5EE', sienna: 'A0522D', silver: 'C0C0C0',
+    skyBlue: '87CEEB', slateBlue: '6A5ACD', slateGray: '708090',
+    snow: 'FFFAFA', springGreen: '00FF7F', steelBlue: '4682B4',
+    tan: 'D2B48C', teal: '008080', thistle: 'D8BFD8',
+    tomato: 'FF6347', turquoise: '40E0D0', violet: 'EE82EE',
+    wheat: 'F5DEB3', white: 'FFFFFF', whiteSmoke: 'F5F5F5',
+    yellow: 'FFFF00', yellowGreen: '9ACD32',
+}));
+/** `a:sysClr` names to Windows' default RRGGBB. */
+export const SYSTEM = new Map(Object.entries({
+    scrollBar: 'C8C8C8', background: '000000', activeCaption: '99B4D1',
+    inactiveCaption: 'BFCDDB', menu: 'F0F0F0', window: 'FFFFFF',
+    windowFrame: '646464', menuText: '000000', windowText: '000000',
+    captionText: '000000', activeBorder: 'B4B4B4', inactiveBorder: 'F4F7FC',
+    appWorkspace: 'ABABAB', highlight: '3399FF', highlightText: 'FFFFFF',
+    btnFace: 'F0F0F0', btnShadow: '696969', grayText: '6D6D6D',
+    btnText: '000000', inactiveCaptionText: '000000', btnHighlight: 'E3E3E3',
+    '3dDkShadow': '000000', '3dLight': 'E3E3E3', infoText: '000000',
+    infoBk: 'FFFFE1', hotLight: '0066CC', gradientActiveCaption: 'B9D1EA',
+    gradientInactiveCaption: 'D7E4F2', menuHighlight: '3399FF', menuBar: 'F0F0F0',
+}));
+/** SpreadsheetML indexed colours 0 to 65. */
+export const INDEXED = Object.freeze([
+    '000000', 'FFFFFF', 'FF0000', '00FF00', '0000FF', 'FFFF00', 'FF00FF', '00FFFF',
+    '000000', 'FFFFFF', 'FF0000', '00FF00', '0000FF', 'FFFF00', 'FF00FF', '00FFFF',
+    '800000', '008000', '000080', '808000', '800080', '008080', 'C0C0C0', '808080',
+    '9999FF', '993366', 'FFFFCC', 'CCFFFF', '660066', 'FF8080', '0066CC', 'CCCCFF',
+    '000080', 'FF00FF', 'FFFF00', '00FFFF', '800080', '800000', '008080', '0000FF',
+    '00CCFF', 'CCFFFF', 'CCFFCC', 'FFFF99', '99CCFF', 'FF99CC', 'CC99FF', 'FFCC99',
+    '3366FF', '33CCCC', '99CC00', 'FFCC00', 'FF9900', 'FF6600', '666699', '969696',
+    '003366', '339966', '003300', '333300', '993300', '993366', '333399', '333333',
+    '000000', 'FFFFFF',
+]);

package/dist/model/color/DrawingMLColors.d.mts

@@ -0,0 +1,52 @@
+import type * as dml from '@docx4j/generated-objects-ts/modules/org_docx4j_dml';
+import { ResolvedColor } from './ResolvedColor.mjs';
+import { StyleFill } from './StyleFill.mjs';
+import type { ThemeColors } from './ThemeColors.mjs';
+/** hexBinary as the objects model has it at run time (byte numbers), or as its declarations say (hex digits). */
+export declare function bytesOf(v: unknown): number[] | undefined;
+/**
+ * DrawingML colours (ISO/IEC 29500-1 section 20.1.2.3) resolved as Office draws them. The six kinds: `srgbClr`,
+ * `scrgbClr` (linear percentages), `hslClr`, `sysClr` (the machine's colour by name, not `lastClr`), `prstClr` and
+ * `schemeClr` (through {@link ThemeColors}). Their transforms apply in document order, in the spaces Word and
+ * PowerPoint use, measured on 403 cases each (docx4j CR-034 section 11, P3):
+ * - `tint`, `shade`, `inv`, `red`/`green`/`blue` and their `Off`/`Mod`: linear RGB; `gamma` and `invGamma`: the
+ *   sRGB transfer function each way;
+ * - `hue`, `sat`, `lum` and their `Off`/`Mod`, `comp`: HSL of the sRGB colour, the saturation not clamped (the
+ *   channels are, afterwards); a colour whose last change is a luminance transform converted back as Foley and van
+ *   Dam do and rounded half down, as Office rounds it (so `tx1` at `lumMod 50000 lumOff 50000` is 7F7F7F);
+ * - `gray`: Rec.709 luma of the sRGB channels;
+ * - `alpha`, `alphaOff`, `alphaMod`: the alpha.
+ *
+ * MS-OI29500 says `lumOff` and `satOff` are not supported by Office; Office 365 applies both as above in every case
+ * measured. Known differences from Office: a saturation set on a grey (Office gives a grey's hue about 40 degrees),
+ * and some hue, saturation and luminance cases one unit off.
+ *
+ * An object is known by its `TYPE_NAME` (which the objects package's unmarshal and factories give it), or, wrapped
+ * as `{ name, value }`, by its element name; a holder of a colour also by its `srgbClr`, `schemeClr`, ... member.
+ * docx4j's `null` is `undefined` here.
+ */
+export declare const DrawingMLColors: {
+    /**
+     * The colour a DrawingML colour element, or an element holding one, resolves to.
+     *
+     * @param colour one of the six kinds (`CTSchemeColor`, `CTSRgbColor`, ...), or a holder of one: `CTColor` (a
+     *   scheme slot), `CTSolidColorFillProperties`, `CTStyleMatrixReference`, `CTFontReference`; `{ name, value }`
+     *   is unwrapped
+     * @param theme the theme and colour map for `schemeClr`; may be undefined where there is none
+     * @returns undefined where there is no colour, or a `schemeClr` cannot be resolved
+     */
+    resolve(colour: unknown, theme: ThemeColors | undefined): ResolvedColor | undefined;
+    /** A fill: `a:noFill`, `a:solidFill` (its colour resolved), or a gradient, pattern, picture or group fill reported by kind. */
+    fill(fillProperties: unknown, theme: ThemeColors | undefined): StyleFill;
+    /** A line's fill: none, solid, gradient or pattern. */
+    lineFill(ln: dml.CTLineProperties | undefined | null, theme: ThemeColors | undefined): StyleFill;
+    /**
+     * A shape style's `a:fillRef`: index 0 is no fill, 1 to 999 the theme's `a:fillStyleLst`, 1001 and up its
+     * `a:bgFillStyleLst`, with `phClr` the reference's own colour.
+     */
+    fillReference(ref: dml.CTStyleMatrixReference | undefined | null, theme: ThemeColors | undefined): StyleFill;
+    /** A shape style's `a:lnRef`: index 0 is no line, else the theme's `a:lnStyleLst` entry's fill. */
+    lineReference(ref: dml.CTStyleMatrixReference | undefined | null, theme: ThemeColors | undefined): StyleFill;
+    /** A shape style's `a:fontRef`: its colour, the text's where the text states none. */
+    fontReference(ref: dml.CTFontReference | undefined | null, theme: ThemeColors | undefined): ResolvedColor | undefined;
+};