reamkit 1.15.0 → 1.15.2

package/dist/esm/word/drawing-parser.js

@@ -53,6 +53,15 @@ function parseAnchorPos(anchor, tag, allowed) {
 		...tag === "wp:positionH" && ANCHOR_ALIGNS.has(alignRaw) ? { align: alignRaw } : {}
 	};
 }
+/**
+* ECMA-376 Part 3 (Markup Compatibility) — resolve an `<mc:AlternateContent>` to
+* the children of the first `<mc:Choice>` whose `Requires` lists only namespaces
+* we understand, else the `<mc:Fallback>` children, else nothing. (`Requires`
+* holds space-separated namespace prefixes as declared in the document.)
+*
+* @param altContent The `mc:AlternateContent` node.
+* @returns The chosen branch's children.
+*/
 function resolveMc(altContent) {
 	for (const choice of poChildren(altContent)) {
 		if (!poIs(choice, "mc:Choice")) continue;
@@ -62,12 +71,32 @@ function resolveMc(altContent) {
 	const fallback = poChildren(altContent).find((c) => poIs(c, "mc:Fallback"));
 	return fallback ? poChildren(fallback) : [];
 }
+/**
+* Flatten a children list, expanding any `<mc:AlternateContent>` to its chosen
+* branch (via {@link resolveMc}) so downstream scanning sees plain elements (a
+* `<w:drawing>`, or the VML we ignore). Used both at run level and inside
+* `a:graphicData`.
+*
+* @param children The raw child list.
+* @returns The flattened children.
+*/
 function expandMcChildren(children) {
 	const out = [];
 	for (const c of children) if (poIs(c, "mc:AlternateContent")) out.push(...resolveMc(c));
 	else out.push(c);
 	return out;
 }
+/**
+* Parse a `<w:drawing>` (ECMA-376 Part 1 §20) into a {@link DrawingContent}. The
+* `a:graphicData` `@uri` selects the branch: a `wps:wsp` shape, a chart, a
+* SmartArt diagram, or — falling through — an embedded picture from
+* `a:blip @r:embed`.
+*
+* @param drawing      The `w:drawing` node.
+* @param resolveColor Resolver for theme/scheme colours used by shape fills/lines.
+* @param parseBody    Optional body parser for a shape's text box (omitted ⇒ no text).
+* @returns The parsed content, or `null` when no anchor / recognizable graphic is found.
+*/
 function parseDrawing(drawing, resolveColor, parseBody) {
 	const anchor = poChildren(drawing).find((c) => poIs(c, "wp:inline")) ?? poChildren(drawing).find((c) => poIs(c, "wp:anchor"));
 	if (!anchor) return null;
@@ -128,6 +157,18 @@ function parseDrawing(drawing, resolveColor, parseBody) {
 	};
 	return null;
 }
+/**
+* Parse a legacy `<w:pict>`/`<w:object>` VML picture (ISO/IEC 29500-1 §14, VML
+* transitional) into an `image` {@link DrawingContent}. Modern files use
+* `<w:drawing>` ({@link parseDrawing}); VML still shows up in headers, OLE-object
+* previews (`@o:ole`) and documents last saved by older Word. A VML shape carries
+* an `<v:imagedata r:id>` pointing at the media part and a CSS-like `@style`
+* (`"width:75.6pt;height:49.2pt"`) giving its box; just enough is read to recover
+* the relationship id, the size and the `@alt` text.
+*
+* @param node The `w:pict` / `w:object` node.
+* @returns The picture, or `null` when there is no embedded `v:imagedata` or no usable size.
+*/
 function parseVmlPicture(node) {
 	const imagedata = poFindDescendant(node, "v:imagedata");
 	if (!imagedata) return null;
@@ -242,6 +283,11 @@ function parseXfrm(xfrm) {
 		...flipV ? { flipV: true } : {}
 	};
 }
+/**
+* Parse an `a:prstGeom` (§20.1.9.18) into a preset {@link ShapeGeometry}: the
+* `@prst` preset name plus the `a:avLst` adjust values (each `a:gd`'s `val …`
+* formula). Defaults to the `rect` preset when `@prst` is absent.
+*/
 function parsePrstGeom(prst) {
 	const preset = poAttr(prst, "prst") ?? "rect";
 	const adjust = /* @__PURE__ */ new Map();
@@ -260,6 +306,13 @@ function parsePrstGeom(prst) {
 		adjust
 	};
 }
+/**
+* Parse an `a:custGeom` (ECMA-376 §20.1.9.11) → its first `<a:path>`
+* (§20.1.9.15) into a custom {@link ShapeGeometry}. Coordinates stay in
+* path-space (the geometry layer scales + y-flips them). Multiple subpaths with
+* differing `w`/`h` are a follow-up; falls back to a `rect` preset when the path
+* is empty or has no usable size.
+*/
 function parseCustGeom(cust) {
 	const pathLst = poChildren(cust).find((c) => poIs(c, "a:pathLst"));
 	const path = pathLst ? poChildren(pathLst).find((c) => poIs(c, "a:path")) : void 0;
@@ -355,6 +408,13 @@ function pts(node) {
 	return out;
 }
 var firstPt = (node) => pts(node)[0];
+/**
+* Parse a shape's fill from its `a:spPr`: the first of `a:noFill`, `a:solidFill`
+* or `a:gradFill` wins. An unresolvable colour degrades to `{ kind: 'none' }`.
+*
+* @param spPr         The `wps:spPr` node.
+* @param resolveColor Resolver for theme/scheme colours.
+*/
 function parseFill(spPr, resolveColor) {
 	for (const child of poChildren(spPr)) {
 		if (poIs(child, "a:noFill")) return { kind: "none" };
@@ -375,6 +435,14 @@ function parseFill(spPr, resolveColor) {
 	}
 	return { kind: "none" };
 }
+/**
+* Parse a shape's outline (`a:ln`) from its `a:spPr` into a {@link ShapeLine}:
+* width, cap, solid colour, dash pattern, and an explicit `a:noFill` (an unstroked
+* outline). Returns `undefined` when the shape has no `a:ln`.
+*
+* @param spPr         The `wps:spPr` node.
+* @param resolveColor Resolver for theme/scheme colours.
+*/
 function parseLine(spPr, resolveColor) {
 	const ln = poChildren(spPr).find((c) => poIs(c, "a:ln"));
 	if (!ln) return void 0;

package/dist/esm/word/font-table.d.ts

@@ -9,7 +9,31 @@ interface FontTableEntry {
     readonly name: string;
     readonly embeds: Partial<Record<EmbedVariant, EmbedRef>>;
 }
+/**
+ * §17.8.1 — restore an obfuscated embedded font by XOR-ing its first 32 bytes
+ * with the `fontKey` GUID bytes in reverse order, recovering a normal sfnt.
+ *
+ * @param data    The obfuscated `.odttf` bytes.
+ * @param fontKey The 16-byte `w:fontKey` GUID (with or without braces/dashes).
+ * @returns The de-obfuscated bytes, or `data` unchanged when `fontKey` is not a GUID.
+ */
 export declare function deobfuscateEmbeddedFont(data: Uint8Array, fontKey: string): Uint8Array;
+/**
+ * Parse `word/fontTable.xml` for its embedded-font references (§17.8). Returns
+ * one `FontTableEntry` per `w:font` that carries at least one `w:embed*` child,
+ * each naming the relationship id + `w:fontKey` for a Regular/Bold/Italic/
+ * BoldItalic face. A regex pass, not a full XML parse — only the embed refs matter.
+ */
 export declare function parseFontTable(data: Uint8Array): Array<FontTableEntry>;
+/**
+ * De-obfuscate and load every embedded font in the package, building one
+ * {@link FontRegistry} per font keyed by its normalized (trimmed, lower-cased)
+ * name so a run's `w:ascii` can match it. Each candidate face is validated
+ * against the sfnt signature; a font lacking a usable Regular face, or whose
+ * faces fail to parse, is skipped (the family then falls back to substitution).
+ *
+ * @param pkg The opened OPC package for the `.docx`.
+ * @returns A map from normalized font name to its registry (empty when nothing embeds).
+ */
 export declare function loadEmbeddedFonts(pkg: OpcPackage): Map<string, FontRegistry>;
 export {};

package/dist/esm/word/font-table.js

@@ -8,6 +8,14 @@ var VARIANT_BY_TAG = {
 	Italic: "italic",
 	BoldItalic: "boldItalic"
 };
+/**
+* §17.8.1 — restore an obfuscated embedded font by XOR-ing its first 32 bytes
+* with the `fontKey` GUID bytes in reverse order, recovering a normal sfnt.
+*
+* @param data    The obfuscated `.odttf` bytes.
+* @param fontKey The 16-byte `w:fontKey` GUID (with or without braces/dashes).
+* @returns The de-obfuscated bytes, or `data` unchanged when `fontKey` is not a GUID.
+*/
 function deobfuscateEmbeddedFont(data, fontKey) {
 	const hex = fontKey.replace(/[{}-]/g, "");
 	if (hex.length !== 32) return data;
@@ -19,6 +27,12 @@ function deobfuscateEmbeddedFont(data, fontKey) {
 	for (let i = 0; i < n; i++) out[i] = out[i] ^ key[i % 16];
 	return out;
 }
+/**
+* Parse `word/fontTable.xml` for its embedded-font references (§17.8). Returns
+* one `FontTableEntry` per `w:font` that carries at least one `w:embed*` child,
+* each naming the relationship id + `w:fontKey` for a Regular/Bold/Italic/
+* BoldItalic face. A regex pass, not a full XML parse — only the embed refs matter.
+*/
 function parseFontTable(data) {
 	const xml = new TextDecoder("utf-8").decode(data);
 	const out = [];
@@ -44,6 +58,16 @@ function parseFontTable(data) {
 	}
 	return out;
 }
+/**
+* De-obfuscate and load every embedded font in the package, building one
+* {@link FontRegistry} per font keyed by its normalized (trimmed, lower-cased)
+* name so a run's `w:ascii` can match it. Each candidate face is validated
+* against the sfnt signature; a font lacking a usable Regular face, or whose
+* faces fail to parse, is skipped (the family then falls back to substitution).
+*
+* @param pkg The opened OPC package for the `.docx`.
+* @returns A map from normalized font name to its registry (empty when nothing embeds).
+*/
 function loadEmbeddedFonts(pkg) {
 	const out = /* @__PURE__ */ new Map();
 	const ftData = pkg.getPart(FONT_TABLE_PART);

package/dist/esm/word/numbering-parser.d.ts

@@ -1,3 +1,14 @@
 import { Numbering } from '../core/document-model/index.js';
+/** The empty {@link Numbering} returned when a document has no `numbering.xml`. */
 export declare const EMPTY_NUMBERING: Numbering;
+/**
+ * Parse `word/numbering.xml` (ECMA-376 Part 1 §17.9) into a {@link Numbering}:
+ * the abstract numbering definitions (each level's format, start, text template
+ * and indent/run properties) plus the num instances that bind a `numId` to an
+ * `abstractNumId`. `basedOn` inheritance and per-level overrides are not resolved
+ * here; an unparseable format defaults to `decimal`.
+ *
+ * @param data The raw `numbering.xml` bytes.
+ * @returns The parsed numbering, or {@link EMPTY_NUMBERING} when the root is absent.
+ */
 export declare function parseNumbering(data: Uint8Array): Numbering;

package/dist/esm/word/numbering-parser.js

@@ -21,10 +21,21 @@ var FORMATS = new Set([
 	"bullet",
 	"none"
 ]);
+/** The empty {@link Numbering} returned when a document has no `numbering.xml`. */
 var EMPTY_NUMBERING = {
 	abstractNums: /* @__PURE__ */ new Map(),
 	numInstances: /* @__PURE__ */ new Map()
 };
+/**
+* Parse `word/numbering.xml` (ECMA-376 Part 1 §17.9) into a {@link Numbering}:
+* the abstract numbering definitions (each level's format, start, text template
+* and indent/run properties) plus the num instances that bind a `numId` to an
+* `abstractNumId`. `basedOn` inheritance and per-level overrides are not resolved
+* here; an unparseable format defaults to `decimal`.
+*
+* @param data The raw `numbering.xml` bytes.
+* @returns The parsed numbering, or {@link EMPTY_NUMBERING} when the root is absent.
+*/
 function parseNumbering(data) {
 	const xml = decoder.decode(data);
 	const root = asElement(parser.parse(xml)["w:numbering"]);

package/dist/esm/word/omml-parser.d.ts

@@ -1,4 +1,19 @@
 import { MathNode } from '../core/document-model/index.js';
 import { PoNode } from '../core/po-helpers.js';
+/**
+ * Parse an `<m:oMath>` subtree (ECMA-376 Part 1 §22) into a recursive
+ * {@link MathNode}. Coverage grows by milestone; unrecognized constructs degrade
+ * by recursing into their content so any literal symbols still surface.
+ *
+ * @param oMath The `m:oMath` PoNode.
+ * @returns A `row` node wrapping the parsed content.
+ */
 export declare function parseOMath(oMath: PoNode): MathNode;
+/**
+ * Collect a named child element's content as a `row` node (`m:num`, `m:den`,
+ * `m:e`, …). Returns an empty row when the child is absent.
+ *
+ * @param parent The enclosing math element.
+ * @param tag    The child element's qualified tag.
+ */
 export declare function childRow(parent: PoNode, tag: string): MathNode;

package/dist/esm/word/omml-parser.js

@@ -1,5 +1,13 @@
 import { poChildren, poChildrenWith, poIs, poTag, poText, poToggle, poVal } from "../core/po-helpers.js";
 //#region src/word/omml-parser.ts
+/**
+* Parse an `<m:oMath>` subtree (ECMA-376 Part 1 §22) into a recursive
+* {@link MathNode}. Coverage grows by milestone; unrecognized constructs degrade
+* by recursing into their content so any literal symbols still surface.
+*
+* @param oMath The `m:oMath` PoNode.
+* @returns A `row` node wrapping the parsed content.
+*/
 function parseOMath(oMath) {
 	return {
 		type: "row",
@@ -65,6 +73,13 @@ function parseMathNode(node) {
 		}
 	}
 }
+/**
+* Collect a named child element's content as a `row` node (`m:num`, `m:den`,
+* `m:e`, …). Returns an empty row when the child is absent.
+*
+* @param parent The enclosing math element.
+* @param tag    The child element's qualified tag.
+*/
 function childRow(parent, tag) {
 	const el = poChildren(parent).find((c) => poIs(c, tag));
 	return {

package/dist/esm/word/omml-serializer.d.ts

@@ -1,2 +1,11 @@
 import { MathNode } from '../core/document-model/index.js';
+/**
+ * Serialize a {@link MathNode} tree to the inner content of an `<m:oMath>`
+ * element (ECMA-376 Part 1 §22). The inverse of `parseOMath`; the `m:` namespace
+ * is declared by the caller, and the output round-trips back through the parser
+ * (WT3).
+ *
+ * @param node The math tree (typically a `row` node).
+ * @returns The serialized OMML markup.
+ */
 export declare function omathXml(node: MathNode): string;

package/dist/esm/word/omml-serializer.js

@@ -1,4 +1,13 @@
 //#region src/word/omml-serializer.ts
+/**
+* Serialize a {@link MathNode} tree to the inner content of an `<m:oMath>`
+* element (ECMA-376 Part 1 §22). The inverse of `parseOMath`; the `m:` namespace
+* is declared by the caller, and the output round-trips back through the parser
+* (WT3).
+*
+* @param node The math tree (typically a `row` node).
+* @returns The serialized OMML markup.
+*/
 function omathXml(node) {
 	return ser(node);
 }

package/dist/esm/word/paragraph-properties.d.ts

@@ -1,2 +1,12 @@
 import { ParagraphProperties } from '../core/document-model/index.js';
+/**
+ * Parse a `w:pPr` element (ECMA-376 Part 1 §17.3.1) into {@link ParagraphProperties}.
+ * Reads the style reference, alignment, spacing, indentation, page-break-before,
+ * bidi, outline level, numbering reference (`w:numPr`) and paragraph-mark run
+ * properties (`w:rPr`); unrecognized or out-of-range values are skipped.
+ *
+ * @param pPr The `w:pPr` element in flat (fast-xml-parser) shape, or anything
+ *   non-element (yielding an empty result).
+ * @returns The extracted properties; an empty object when `pPr` is absent.
+ */
 export declare function parseParagraphProperties(pPr: unknown): ParagraphProperties;

package/dist/esm/word/paragraph-properties.js

@@ -14,6 +14,16 @@ var LINE_RULES = new Set([
 	"exact",
 	"atLeast"
 ]);
+/**
+* Parse a `w:pPr` element (ECMA-376 Part 1 §17.3.1) into {@link ParagraphProperties}.
+* Reads the style reference, alignment, spacing, indentation, page-break-before,
+* bidi, outline level, numbering reference (`w:numPr`) and paragraph-mark run
+* properties (`w:rPr`); unrecognized or out-of-range values are skipped.
+*
+* @param pPr The `w:pPr` element in flat (fast-xml-parser) shape, or anything
+*   non-element (yielding an empty result).
+* @returns The extracted properties; an empty object when `pPr` is absent.
+*/
 function parseParagraphProperties(pPr) {
 	const el = asElement(pPr);
 	if (!el) return {};

package/dist/esm/word/po-to-flat.d.ts

@@ -1,2 +1,13 @@
 import { PoNode } from '../core/po-helpers.js';
+/**
+ * Convert one `preserveOrder` element ({@link PoNode}) into the flat object shape
+ * `fast-xml-parser` produces *without* `preserveOrder`, so the flat-tree property
+ * parsers (`run-properties.ts`, `paragraph-properties.ts`) can consume it unchanged.
+ *
+ * Attributes are flattened to `@_`-prefixed keys, text nodes concatenate into
+ * `#text`, and repeated child tags collapse to an array under the tag name.
+ *
+ * @param node The PO element to flatten; `undefined` yields an empty object.
+ * @returns The flat `{ "@_w:val": …, "w:b": {…}, "w:r": [{…}], "#text": "…" }` shape.
+ */
 export declare function poElementToFlat(node: PoNode | undefined): Record<string, unknown>;

package/dist/esm/word/po-to-flat.js

@@ -2,6 +2,17 @@ import { poChildren, poTag } from "../core/po-helpers.js";
 //#region src/word/po-to-flat.ts
 var ATTRS_KEY = ":@";
 var TEXT_KEY = "#text";
+/**
+* Convert one `preserveOrder` element ({@link PoNode}) into the flat object shape
+* `fast-xml-parser` produces *without* `preserveOrder`, so the flat-tree property
+* parsers (`run-properties.ts`, `paragraph-properties.ts`) can consume it unchanged.
+*
+* Attributes are flattened to `@_`-prefixed keys, text nodes concatenate into
+* `#text`, and repeated child tags collapse to an array under the tag name.
+*
+* @param node The PO element to flatten; `undefined` yields an empty object.
+* @returns The flat `{ "@_w:val": …, "w:b": {…}, "w:r": [{…}], "#text": "…" }` shape.
+*/
 function poElementToFlat(node) {
 	const out = {};
 	if (!node) return out;

package/dist/esm/word/run-properties.d.ts

@@ -1,2 +1,12 @@
 import { RunProperties } from '../core/document-model/index.js';
+/**
+ * Parse a run-properties element (`w:rPr`, ECMA-376 Part 1 §17.3.2) into the
+ * typed {@link RunProperties}. Reads the character formatting the renderer needs:
+ * style reference, bold/italic/strike toggles, underline style, size, colour,
+ * font family map, vertical alignment, RTL, and language; sizes convert from
+ * half-points to points and colours normalize to uppercase hex.
+ *
+ * @param rPr The flat-tree `w:rPr` element (or `undefined`/non-element).
+ * @returns The parsed properties; an empty object when `rPr` is absent.
+ */
 export declare function parseRunProperties(rPr: unknown): RunProperties;

package/dist/esm/word/run-properties.js

@@ -17,6 +17,16 @@ var VERTICAL_ALIGNS = new Set([
 	"superscript",
 	"subscript"
 ]);
+/**
+* Parse a run-properties element (`w:rPr`, ECMA-376 Part 1 §17.3.2) into the
+* typed {@link RunProperties}. Reads the character formatting the renderer needs:
+* style reference, bold/italic/strike toggles, underline style, size, colour,
+* font family map, vertical alignment, RTL, and language; sizes convert from
+* half-points to points and colours normalize to uppercase hex.
+*
+* @param rPr The flat-tree `w:rPr` element (or `undefined`/non-element).
+* @returns The parsed properties; an empty object when `rPr` is absent.
+*/
 function parseRunProperties(rPr) {
 	const el = asElement(rPr);
 	if (!el) return {};

package/dist/esm/word/settings-parser.d.ts

@@ -1,5 +1,18 @@
+/** The handful of `word/settings.xml` flags the renderer consumes. */
 export interface DocumentSettings {
+    /**
+     * ECMA-376 §17.15.1.36 — `w:evenAndOddHeaders`. When `true`, even-numbered
+     * pages use the `'even'` header/footer references instead of `'default'`.
+     */
     readonly evenAndOddHeaders: boolean;
 }
+/** The all-defaults {@link DocumentSettings}, returned when no `w:settings` root is found. */
 export declare const EMPTY_SETTINGS: DocumentSettings;
+/**
+ * Parse `word/settings.xml` (ECMA-376 §17.15), extracting only the flags the
+ * renderer needs; everything else (compat, autoSpaceDE, …) is ignored.
+ *
+ * @param data The raw `word/settings.xml` bytes.
+ * @returns The extracted {@link DocumentSettings}, or {@link EMPTY_SETTINGS} when the root is absent.
+ */
 export declare function parseSettings(data: Uint8Array): DocumentSettings;

package/dist/esm/word/settings-parser.js

@@ -10,7 +10,15 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	trimValues: false
 });
+/** The all-defaults {@link DocumentSettings}, returned when no `w:settings` root is found. */
 var EMPTY_SETTINGS = { evenAndOddHeaders: false };
+/**
+* Parse `word/settings.xml` (ECMA-376 §17.15), extracting only the flags the
+* renderer needs; everything else (compat, autoSpaceDE, …) is ignored.
+*
+* @param data The raw `word/settings.xml` bytes.
+* @returns The extracted {@link DocumentSettings}, or {@link EMPTY_SETTINGS} when the root is absent.
+*/
 function parseSettings(data) {
 	const xml = decoder.decode(data);
 	const settings = poFindByPath(parser.parse(xml), ["w:settings"]);

package/dist/esm/word/styles-parser.d.ts

@@ -1,2 +1,12 @@
 import { StyleSheet } from '../core/document-model/index.js';
+/**
+ * Parse `word/styles.xml` (ECMA-376 Part 1 §17.7) into a {@link StyleSheet}: the
+ * document defaults (`w:docDefaults` run/paragraph properties) plus the named
+ * styles, keyed by `styleId`. Table styles additionally carry their base layer,
+ * conditional (`w:tblStylePr`) layers and banding sizes. `basedOn` inheritance is
+ * recorded but not resolved — that happens in the style-cascade module.
+ *
+ * @param stylesXml The raw `styles.xml` bytes.
+ * @returns The parsed stylesheet, or `EMPTY_STYLE_SHEET` when the root is absent.
+ */
 export declare function parseStyles(stylesXml: Uint8Array): StyleSheet;

package/dist/esm/word/styles-parser.js

@@ -21,6 +21,16 @@ var STYLE_TYPES = new Set([
 	"table",
 	"numbering"
 ]);
+/**
+* Parse `word/styles.xml` (ECMA-376 Part 1 §17.7) into a {@link StyleSheet}: the
+* document defaults (`w:docDefaults` run/paragraph properties) plus the named
+* styles, keyed by `styleId`. Table styles additionally carry their base layer,
+* conditional (`w:tblStylePr`) layers and banding sizes. `basedOn` inheritance is
+* recorded but not resolved — that happens in the style-cascade module.
+*
+* @param stylesXml The raw `styles.xml` bytes.
+* @returns The parsed stylesheet, or `EMPTY_STYLE_SHEET` when the root is absent.
+*/
 function parseStyles(stylesXml) {
 	const xml = decoder.decode(stylesXml);
 	const root = asElement(parser.parse(xml)["w:styles"]);

package/dist/esm/word/table-parser.d.ts

@@ -1,4 +1,15 @@
 import { Table } from '../core/document-model/index.js';
 import { PoNode } from '../core/po-helpers.js';
 import { ParseContext } from './document-parser.js';
+/**
+ * Parse a `w:tbl` (ECMA-376 Part 1 §17.4) in preserveOrder shape into the typed
+ * {@link Table} model: its properties (style ref, look, width, layout, borders,
+ * default cell margins), column grid and rows. Vertical merges are resolved in a
+ * second pass so cells carry the resolved {@link CellMerge} role, not the raw
+ * `w:vMerge` markers.
+ *
+ * @param tbl The `w:tbl` PoNode.
+ * @param ctx The document-wide parse context (resolvers for colour, images, etc.).
+ * @returns The parsed table.
+ */
 export declare function parseTable(tbl: PoNode, ctx?: ParseContext): Table;

package/dist/esm/word/table-parser.js

@@ -21,6 +21,17 @@ var HEIGHT_RULES = new Set([
 	"atLeast",
 	"exact"
 ]);
+/**
+* Parse a `w:tbl` (ECMA-376 Part 1 §17.4) in preserveOrder shape into the typed
+* {@link Table} model: its properties (style ref, look, width, layout, borders,
+* default cell margins), column grid and rows. Vertical merges are resolved in a
+* second pass so cells carry the resolved {@link CellMerge} role, not the raw
+* `w:vMerge` markers.
+*
+* @param tbl The `w:tbl` PoNode.
+* @param ctx The document-wide parse context (resolvers for colour, images, etc.).
+* @returns The parsed table.
+*/
 function parseTable(tbl, ctx = DEFAULT_PARSE_CONTEXT) {
 	const properties = parseTableProperties(poFirstChild(tbl, "w:tblPr"));
 	const grid = parseTableGrid(poFirstChild(tbl, "w:tblGrid"));

package/dist/esm/word/text-extractor.d.ts

@@ -1 +1,10 @@
+/**
+ * Extract the body paragraphs of a WordprocessingML document as a flat array of
+ * plain text — one string per paragraph, runs concatenated. A backwards-compatible
+ * convenience over {@link parseDocument} for tests/tools that want only text;
+ * table contents and all formatting are dropped.
+ *
+ * @param documentXml The raw `word/document.xml` bytes.
+ * @returns One joined run-text string per body paragraph, in document order.
+ */
 export declare function extractParagraphs(documentXml: Uint8Array): Array<string>;

package/dist/esm/word/xml-helpers.d.ts

@@ -1,9 +1,53 @@
+/** The value of a parsed XML attribute (always a string in this flat tree). */
 export type XmlAttrValue = string;
+/** A parsed XML element: attributes (`@_`-prefixed) and child tags keyed by name. */
 export type XmlElement = Record<string, unknown>;
+/**
+ * Narrow an arbitrary parsed value to an {@link XmlElement}.
+ *
+ * @returns The value as an element record, or `undefined` when it is null, a
+ *          primitive, or an array (i.e. not a single element node).
+ */
 export declare function asElement(v: unknown): XmlElement | undefined;
+/**
+ * Coerce a value to an array, treating a lone element as a one-item array.
+ * `fast-xml-parser` collapses a single repeated child to a bare object; this
+ * normalizes it so callers can always iterate.
+ *
+ * @returns The value as an array (empty for null/undefined).
+ */
 export declare function asArray(v: unknown): ReadonlyArray<unknown>;
+/**
+ * Read a string attribute off an element, trying the `w:`-prefixed name first
+ * then the unprefixed fallback (e.g. `@_w:val` then `@_val`).
+ *
+ * @param node The element to read from.
+ * @param name The local attribute name (without the `@_`/`w:` prefix).
+ * @returns The attribute value, or `undefined` when the node is not an element
+ *          or the attribute is absent / non-string.
+ */
 export declare function getAttr(node: unknown, name: string): string | undefined;
+/** Shorthand for {@link getAttr}`(node, 'val')` — the ubiquitous `@w:val` attribute. */
 export declare function getVal(node: unknown): string | undefined;
+/**
+ * Read an attribute and parse it as a finite number.
+ *
+ * @param node The element to read from.
+ * @param name The local attribute name.
+ * @returns The parsed number, or `undefined` when absent or not finite.
+ */
 export declare function parseIntAttr(node: unknown, name: string): number | undefined;
+/**
+ * Parse a toggle (boolean) property per ECMA-376 Part 1 §17.17.4:
+ * - Absent → `undefined` (inherit)
+ * - Present without `val`, or `val ∈ {true, 1, on}` → `true`
+ * - Present with `val ∈ {false, 0, off}` → `false`
+ *
+ * @returns The toggle state, or `undefined` when the property is absent.
+ */
 export declare function parseToggle(node: unknown): boolean | undefined;
+/**
+ * Read the `#text` content of a node. A bare string/number is returned directly;
+ * an element returns its `#text` child (coerced to string), else the empty string.
+ */
 export declare function getText(node: unknown): string;

package/dist/esm/word/xml-helpers.js

@@ -1,22 +1,52 @@
 //#region src/word/xml-helpers.ts
+/**
+* Narrow an arbitrary parsed value to an {@link XmlElement}.
+*
+* @returns The value as an element record, or `undefined` when it is null, a
+*          primitive, or an array (i.e. not a single element node).
+*/
 function asElement(v) {
 	if (v === null || v === void 0) return void 0;
 	if (typeof v !== "object" || Array.isArray(v)) return void 0;
 	return v;
 }
+/**
+* Coerce a value to an array, treating a lone element as a one-item array.
+* `fast-xml-parser` collapses a single repeated child to a bare object; this
+* normalizes it so callers can always iterate.
+*
+* @returns The value as an array (empty for null/undefined).
+*/
 function asArray(v) {
 	if (v === null || v === void 0) return [];
 	return Array.isArray(v) ? v : [v];
 }
+/**
+* Read a string attribute off an element, trying the `w:`-prefixed name first
+* then the unprefixed fallback (e.g. `@_w:val` then `@_val`).
+*
+* @param node The element to read from.
+* @param name The local attribute name (without the `@_`/`w:` prefix).
+* @returns The attribute value, or `undefined` when the node is not an element
+*          or the attribute is absent / non-string.
+*/
 function getAttr(node, name) {
 	const el = asElement(node);
 	if (!el) return void 0;
 	const v = el[`@_w:${name}`] ?? el[`@_${name}`];
 	return typeof v === "string" ? v : void 0;
 }
+/** Shorthand for {@link getAttr}`(node, 'val')` — the ubiquitous `@w:val` attribute. */
 function getVal(node) {
 	return getAttr(node, "val");
 }
+/**
+* Read an attribute and parse it as a finite number.
+*
+* @param node The element to read from.
+* @param name The local attribute name.
+* @returns The parsed number, or `undefined` when absent or not finite.
+*/
 function parseIntAttr(node, name) {
 	const v = getAttr(node, name);
 	if (v === void 0) return void 0;
@@ -24,6 +54,14 @@ function parseIntAttr(node, name) {
 	if (!Number.isFinite(n)) return void 0;
 	return n;
 }
+/**
+* Parse a toggle (boolean) property per ECMA-376 Part 1 §17.17.4:
+* - Absent → `undefined` (inherit)
+* - Present without `val`, or `val ∈ {true, 1, on}` → `true`
+* - Present with `val ∈ {false, 0, off}` → `false`
+*
+* @returns The toggle state, or `undefined` when the property is absent.
+*/
 function parseToggle(node) {
 	if (node === void 0) return void 0;
 	if (node === null || node === "" || typeof node === "boolean" || typeof node === "number") return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reamkit",
-  "version": "1.15.0",
+  "version": "1.15.2",
   "description": "Ream — convert DOCX, XLSX, PPTX and PDF to PDF, SVG, HTML, DOCX and XLSX, built from scratch on the ECMA-376 and ISO 32000 specifications. Parse once, convert anywhere.",
   "license": "MIT",
   "author": "Alex Krassavin <info@reamkit.dev>",