reamkit 1.15.1 → 1.15.3

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

@@ -28,7 +28,17 @@ var RUN_CONTAINER_TAGS = new Set([
 	"w:ins",
 	"w:moveTo"
 ]);
+/** The default {@link ParseContext} — just the default colour resolver. */
 var DEFAULT_PARSE_CONTEXT = { resolveColor: defaultColorResolver };
+/**
+* Parse `word/document.xml` (ECMA-376 Part 1 §17) into a flat list of
+* {@link BodyElement}, preserving the original interleaving of paragraphs and
+* tables.
+*
+* @param documentXml The raw `document.xml` bytes.
+* @param ctx         The document-wide parse context.
+* @returns The body elements; empty when the `w:body` is absent.
+*/
 function parseDocument(documentXml, ctx = DEFAULT_PARSE_CONTEXT) {
 	const xml = decoder.decode(documentXml);
 	const body = poFindByPath(parser.parse(xml), ["w:document", "w:body"]);
@@ -40,10 +50,21 @@ var HF_TYPES = new Set([
 	"first",
 	"even"
 ]);
+/** The empty {@link SectionProperties} fallback (no headers/footers). */
 var EMPTY_SECTION = {
 	headers: [],
 	footers: []
 };
+/**
+* Collect every section in the document (ECMA-376 §17.6): one `sectPr` per
+* intermediate paragraph plus the body-final one. Each {@link Section} carries
+* the exclusive `endIndex` into the body-element list, so section `i` applies to
+* `body[sections[i-1].endIndex .. endIndex)`. A document with no `sectPr` at all
+* returns a single empty section spanning the whole body.
+*
+* @param documentXml The raw `document.xml` bytes.
+* @returns The sections in document order; empty when the `w:body` is absent.
+*/
 function parseSections(documentXml) {
 	const xml = decoder.decode(documentXml);
 	const body = poFindByPath(parser.parse(xml), ["w:document", "w:body"]);
@@ -151,11 +172,29 @@ function pushHeaderFooter(node, list) {
 		relationshipId: rId
 	});
 }
+/**
+* Parse `word/header*.xml` or `word/footer*.xml`. The root is `w:hdr` or
+* `w:ftr`, whose children are the same body-element shape as the main document.
+*
+* @param xml The raw header/footer part bytes.
+* @param ctx The document-wide parse context.
+* @returns The body elements; empty when neither root is found.
+*/
 function parseHeaderFooter(xml, ctx = DEFAULT_PARSE_CONTEXT) {
 	const root = parser.parse(decoder.decode(xml)).find((n) => poIs(n, "w:hdr") || poIs(n, "w:ftr"));
 	if (!root) return [];
 	return parseBodyElements(poChildren(root), ctx);
 }
+/**
+* Parse a sequence of body-level children (`w:p`, `w:tbl`, `w:sdt`,
+* `w:bookmarkStart`) into {@link BodyElement}s, preserving order. A lone-drawing
+* paragraph collapses to a standalone image/shape/chart block; a block-level SDT
+* unwraps to its content; a body-level bookmark anchors onto the next paragraph.
+*
+* @param children The body-level child nodes.
+* @param ctx      The document-wide parse context.
+* @returns The parsed body elements.
+*/
 function parseBodyElements(children, ctx = DEFAULT_PARSE_CONTEXT) {
 	const out = [];
 	let pendingBookmarks;
@@ -538,6 +577,17 @@ function parseRun(r, ctx) {
 function elementTag(node) {
 	for (const key of Object.keys(node)) if (key !== ":@" && key !== "#text") return key;
 }
+/**
+* Parse `footnotes.xml` / `endnotes.xml` (§17.11) into note content by id. The
+* separator / continuationSeparator / continuationNotice stubs (negative ids or
+* an explicit `w:type`) are skipped — the layout draws its own separator.
+*
+* @param notesXml The raw notes-part bytes.
+* @param rootTag  The part's root element (`w:footnotes` or `w:endnotes`).
+* @param noteTag  The per-note element (`w:footnote` or `w:endnote`).
+* @param ctx      The document-wide parse context.
+* @returns A map from note id to its body content.
+*/
 function parseNotes(notesXml, rootTag, noteTag, ctx = DEFAULT_PARSE_CONTEXT) {
 	const xml = decoder.decode(notesXml);
 	const root = poFindByPath(parser.parse(xml), [rootTag]);
@@ -588,6 +638,15 @@ function parseCommentsRaw(commentsXml, ctx) {
 		paraIds
 	};
 }
+/**
+* Parse `word/commentsExtended.xml` (Microsoft w15 `commentsEx`) — a flat list
+* of `commentEx`, each keyed by a comment's `paraId`: `paraIdParent` links a
+* reply to its parent, `done` flags a resolved thread. Prefix-agnostic (w15 by
+* convention).
+*
+* @param xml The raw `commentsExtended.xml` bytes.
+* @returns A map from `paraId` to its {@link CommentExtension}.
+*/
 function parseCommentsExtended(xml) {
 	const tree = parser.parse(decoder.decode(xml));
 	const out = /* @__PURE__ */ new Map();
@@ -627,11 +686,29 @@ function linkCommentThreads(comments, paraIdByComment, ext) {
 	}
 	return out;
 }
+/**
+* Read comments with their thread metadata: `comments.xml` for content /
+* attribution plus the optional `commentsExtended.xml` for reply links and
+* resolved flags (CM4). A reply gains `parentId`, a resolved thread gains `done`.
+*
+* @param commentsXml         The raw `comments.xml` bytes.
+* @param commentsExtendedXml The raw `commentsExtended.xml` bytes, or `undefined`.
+* @param ctx                 The document-wide parse context.
+* @returns A map from comment id to the parsed, thread-linked comment.
+*/
 function parseCommentThreads(commentsXml, commentsExtendedXml, ctx = DEFAULT_PARSE_CONTEXT) {
 	const { comments, paraIds } = parseCommentsRaw(commentsXml, ctx);
 	if (!commentsExtendedXml) return comments;
 	return linkCommentThreads(comments, paraIds, parseCommentsExtended(commentsExtendedXml));
 }
+/**
+* Parse `word/people.xml` (Microsoft w15) — maps an author display name to a
+* presence identity (`w15:presenceInfo/@w15:userId`, usually an email), used to
+* enrich a comment's `authorId`. Prefix-agnostic.
+*
+* @param xml The raw `people.xml` bytes.
+* @returns A map from author name to userId.
+*/
 function parsePeople(xml) {
 	const tree = parser.parse(decoder.decode(xml));
 	const out = /* @__PURE__ */ new Map();
@@ -651,6 +728,15 @@ function parsePeople(xml) {
 	}
 	return out;
 }
+/**
+* Attach each comment's `authorId` by matching its author name against the
+* {@link parsePeople} map. Comments without a matching author pass through
+* unchanged.
+*
+* @param comments The comments by id.
+* @param people   The author → userId map from `people.xml`.
+* @returns The comments with `authorId` filled in where resolvable.
+*/
 function applyAuthorIds(comments, people) {
 	if (people.size === 0) return comments;
 	const out = /* @__PURE__ */ new Map();

package/dist/esm/word/docx-reader.d.ts

@@ -1,4 +1,20 @@
 import { DocumentReader, ReadResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
+/**
+ * Read a `.docx` package into the {@link FlowDoc} interlayer (ir-design §7): the
+ * document-derived half of what the converter used to do inline. Parses the main
+ * document, styles, numbering, notes, comments, headers/footers, charts, embedded
+ * fonts and core properties, runs the body through the stage-6 FlowDoc transforms
+ * (list markers then the style cascade), and returns the tree plus any
+ * graceful-degradation losses. Caller-supplied conversion options (fonts, PDF/A,
+ * signature) stay with the converter/facade.
+ *
+ * @param docx The raw `.docx` (OPC ZIP) bytes.
+ * @returns The parsed {@link FlowDoc} and the losses recorded while reading.
+ */
 export declare function readDocx(docx: Uint8Array): ReadResult<FlowDoc>;
+/**
+ * The {@link DocumentReader} registration for `.docx`: its id, the FlowDoc
+ * feature set it supports, the sniffer, and the {@link readDocx} entry point.
+ */
 export declare const docxReader: DocumentReader<FlowDoc>;

package/dist/esm/word/docx-reader.js

@@ -5,7 +5,7 @@ import { EMPTY_STYLE_SHEET, resolveBodyStyles, resolveHeadersFootersStyles } fro
 import { resolveTableStyles } from "../core/style-cascade/table.js";
 import "../core/style-cascade/index.js";
 import { poFindDescendant } from "../core/po-helpers.js";
-import { bytesInclude } from "../core/bytes.js";
+import { bytesIncludePartName } from "../core/bytes.js";
 import { DEFAULT_THEME_PALETTE, makeColorResolver } from "../core/drawingml/colors.js";
 import { parseChart, withChartColorStyle } from "../core/drawingml/chart-parser.js";
 import { parseTheme } from "../core/drawingml/theme-parser.js";
@@ -33,6 +33,18 @@ var CORE_PROPS_PART = "docProps/core.xml";
 var MAIN_DOCUMENT_PART = "word/document.xml";
 var REL_HYPERLINK = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
 var THEME_PART = "word/theme/theme1.xml";
+/**
+* Read a `.docx` package into the {@link FlowDoc} interlayer (ir-design §7): the
+* document-derived half of what the converter used to do inline. Parses the main
+* document, styles, numbering, notes, comments, headers/footers, charts, embedded
+* fonts and core properties, runs the body through the stage-6 FlowDoc transforms
+* (list markers then the style cascade), and returns the tree plus any
+* graceful-degradation losses. Caller-supplied conversion options (fonts, PDF/A,
+* signature) stay with the converter/facade.
+*
+* @param docx The raw `.docx` (OPC ZIP) bytes.
+* @returns The parsed {@link FlowDoc} and the losses recorded while reading.
+*/
 function readDocx(docx) {
 	const pkg = OpcPackage.open(docx);
 	const main = pkg.getMainDocument();
@@ -110,6 +122,10 @@ function readDocx(docx) {
 		losses
 	};
 }
+/**
+* The {@link DocumentReader} registration for `.docx`: its id, the FlowDoc
+* feature set it supports, the sniffer, and the {@link readDocx} entry point.
+*/
 var docxReader = {
 	id: "docx",
 	produces: "flow",
@@ -128,7 +144,7 @@ var docxReader = {
 		FEATURES.trackedChanges,
 		FEATURES.fontsEmbedding
 	]),
-	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && bytesInclude(bytes, "word/document.xml"),
+	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && bytesIncludePartName(bytes, "word/document.xml"),
 	read: (bytes) => readDocx(bytes)
 };
 function infoFromCore(core) {

package/dist/esm/word/docx-to-pdf.d.ts

@@ -1,12 +1,34 @@
 import { FontBytesByVariant, FontRegistry } from '../core/font/index.js';
 import { FamilyKey, FetchLike } from '../core/fonts/index.js';
 import { SignatureOptions, StyledRenderOptions } from '../pdf/index.js';
+/**
+ * Options for the `.docx` → PDF converters. Extends the low-level
+ * {@link StyledRenderOptions} (minus the font `registry` and `styles`, which the
+ * converter builds itself) with font supply, substitute-font hints and two
+ * source-touching conveniences.
+ */
 export interface ConvertDocxOptions extends Omit<StyledRenderOptions, 'registry' | 'styles'> {
+    /** A single regular-variant font as raw bytes. */
     readonly fontBytes?: Uint8Array;
+    /** Explicit font bytes per variant (regular/bold/italic/bold-italic). */
     readonly fonts?: FontBytesByVariant;
+    /**
+     * Force a substitute font family for the auto-download path (e.g. `'serif'`).
+     * Ignored when `fonts`/`fontBytes` are supplied.
+     */
     readonly fontFamily?: string;
+    /** Injectable `fetch` for the auto-download path (defaults to the global `fetch`). */
     readonly fontFetch?: FetchLike;
+    /**
+     * For PDF/A-3 only: embed the input `.docx` as an associated source file
+     * (`/AFRelationship /Source`) so the archive carries its own source. Ignored
+     * for other profiles (PDF/A-1/2 forbid arbitrary embedded files).
+     */
     readonly embedSource?: boolean;
+    /**
+     * Digitally sign the output (ISO 32000 §12.8). Requires the async
+     * {@link convertDocxToPdf} (signing uses WebCrypto); ignored by the sync converter.
+     */
     readonly signature?: SignatureOptions;
 }
 /**
@@ -15,6 +37,16 @@ export interface ConvertDocxOptions extends Omit<StyledRenderOptions, 'registry'
  * Internal since 1.0 — see the async variant above.
  */
 export declare function convertDocxToPdfSync(docx: Uint8Array, options: ConvertDocxOptions): Uint8Array;
+/**
+ * The distinct curated font families the document references (scanning the
+ * `w:ascii` of `styles.xml` + `document.xml`), always including the sans default
+ * `'arimo'` as a fallback for unstyled runs / math / charts. The async path
+ * fetches one substitute set per family so each run renders in the right one.
+ *
+ * @param docx The `.docx` bytes.
+ * @returns The resolved {@link FamilyKey} set; just the default when the package
+ *   cannot be opened.
+ */
 export declare function detectDocxFamilyKeys(docx: Uint8Array): Set<FamilyKey>;
 /**
  * One-shot .docx → PDF (auto-downloads a substitute font set when the caller
@@ -24,6 +56,17 @@ export declare function detectDocxFamilyKeys(docx: Uint8Array): Set<FamilyKey>;
  * the createConverter facade and the test suite drive this directly.
  */
 export declare function convertDocxToPdf(docx: Uint8Array, options?: ConvertDocxOptions): Promise<Uint8Array>;
+/**
+ * Substitute-font auto-download for a `.docx` without caller-supplied fonts:
+ * detect the families used and fetch an open set per family (a single-family
+ * document takes the simple one-family path). Shared by the converter and the
+ * {@link Ream} facade — both work from the same source bytes.
+ *
+ * @param docx    The `.docx` bytes.
+ * @param options Optional `fontFamily` override and injectable `fontFetch`.
+ * @returns The base font bytes plus, for a multi-family document, a per-family
+ *   registry map so each run resolves to its own substitute.
+ */
 export declare function resolveDocxAutoFonts(docx: Uint8Array, options?: {
     readonly fontFamily?: string;
     readonly fontFetch?: FetchLike;
@@ -31,4 +74,13 @@ export declare function resolveDocxAutoFonts(docx: Uint8Array, options?: {
     fonts: FontBytesByVariant;
     registriesByFamily?: Map<FamilyKey, FontRegistry>;
 }>;
+/**
+ * Best-effort detection of the document's primary font family, used to choose a
+ * substitute for auto-download. Prefers the document defaults' `w:ascii` font,
+ * then falls back to the most frequent run font. A cheap regex over the XML — no
+ * need to fully parse for this hint.
+ *
+ * @param docx The `.docx` bytes.
+ * @returns The detected family name, or `undefined` when none is found.
+ */
 export declare function detectDocxFontFamily(docx: Uint8Array): string | undefined;

package/dist/esm/word/docx-to-pdf.js

@@ -48,6 +48,16 @@ function prepareDocxStyledRender(docx, options) {
 		}
 	};
 }
+/**
+* The distinct curated font families the document references (scanning the
+* `w:ascii` of `styles.xml` + `document.xml`), always including the sans default
+* `'arimo'` as a fallback for unstyled runs / math / charts. The async path
+* fetches one substitute set per family so each run renders in the right one.
+*
+* @param docx The `.docx` bytes.
+* @returns The resolved {@link FamilyKey} set; just the default when the package
+*   cannot be opened.
+*/
 function detectDocxFamilyKeys(docx) {
 	const keys = new Set(["arimo"]);
 	let pkg;
@@ -93,6 +103,17 @@ async function buildUnsignedDocxPdf(docx, options) {
 	}
 	return convertDocxToPdfSync(docx, withFonts);
 }
+/**
+* Substitute-font auto-download for a `.docx` without caller-supplied fonts:
+* detect the families used and fetch an open set per family (a single-family
+* document takes the simple one-family path). Shared by the converter and the
+* {@link Ream} facade — both work from the same source bytes.
+*
+* @param docx    The `.docx` bytes.
+* @param options Optional `fontFamily` override and injectable `fontFetch`.
+* @returns The base font bytes plus, for a multi-family document, a per-family
+*   registry map so each run resolves to its own substitute.
+*/
 async function resolveDocxAutoFonts(docx, options = {}) {
 	const fetchOpt = options.fontFetch ? { fetch: options.fontFetch } : {};
 	const keys = options.fontFamily ? new Set([resolveFamilyKey(options.fontFamily)]) : detectDocxFamilyKeys(docx);

package/dist/esm/word/docx-writer.d.ts

@@ -1,4 +1,21 @@
 import { DocumentWriter, WriteResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
+/**
+ * Serialize a {@link FlowDoc} to a WordprocessingML package (E-DOCX) — the
+ * inverse of the docx reader. A flow medium with zero layout and zero I/O: the
+ * body's resolved properties are written as direct (denormalized) formatting, so
+ * the round-trip is semantic, not byte-for-byte. Emits the main document plus
+ * numbering, footnotes/endnotes, comments (+ commentsExtended), per-section
+ * headers/footers, charts and media parts; anything not yet serialized is
+ * reported as a {@link Loss}.
+ *
+ * @param flow The interlayer to write back.
+ * @returns The encoded `.docx` bytes and the loss report.
+ */
 export declare function writeDocx(flow: FlowDoc): WriteResult;
+/**
+ * The {@link DocumentWriter} registration for `.docx`: its id, the medium it
+ * consumes (`flow`), the feature set it supports, and the {@link writeDocx}
+ * entry point.
+ */
 export declare const docxWriter: DocumentWriter<FlowDoc>;

package/dist/esm/word/docx-writer.js

@@ -88,6 +88,18 @@ function newScope() {
 		relIdByResource: /* @__PURE__ */ new Map()
 	};
 }
+/**
+* Serialize a {@link FlowDoc} to a WordprocessingML package (E-DOCX) — the
+* inverse of the docx reader. A flow medium with zero layout and zero I/O: the
+* body's resolved properties are written as direct (denormalized) formatting, so
+* the round-trip is semantic, not byte-for-byte. Emits the main document plus
+* numbering, footnotes/endnotes, comments (+ commentsExtended), per-section
+* headers/footers, charts and media parts; anything not yet serialized is
+* reported as a {@link Loss}.
+*
+* @param flow The interlayer to write back.
+* @returns The encoded `.docx` bytes and the loss report.
+*/
 function writeDocx(flow) {
 	const losses = [];
 	const body = [];
@@ -334,6 +346,11 @@ function emitHeadersFooters(flow, section, state, docScope, extraParts, extraPar
 	}
 	return refs;
 }
+/**
+* The {@link DocumentWriter} registration for `.docx`: its id, the medium it
+* consumes (`flow`), the feature set it supports, and the {@link writeDocx}
+* entry point.
+*/
 var docxWriter = {
 	id: "docx",
 	consumes: "flow",

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

@@ -2,6 +2,11 @@ import { BodyElement, FloatAnchor, ShapeFill, ShapeGeometry, ShapeLine, ShapeTex
 import { ColorResolver } from '../core/drawingml/colors.js';
 import { PoNode } from '../core/po-helpers.js';
 import { Pt } from '../core/ir/index.js';
+/**
+ * A parsed DrawingML shape without the owning paragraph's properties (attached by
+ * the caller, mirroring how the image branch returns size + id and the caller
+ * adds the `pPr`).
+ */
 export interface ShapeData {
     readonly width: Pt;
     readonly height: Pt;
@@ -9,14 +14,25 @@ export interface ShapeData {
     readonly fill: ShapeFill;
     readonly line?: ShapeLine;
     readonly transform?: ShapeTransform;
+    /** The shape's text body (a `wps:txbx`), when it carries one. */
     readonly text?: ShapeTextBody;
 }
+/**
+ * Parses the body elements of a `w:txbxContent`. Injected by the caller to avoid
+ * a module cycle with `document-parser` (which imports this module).
+ */
 export type ParseBody = (children: ReadonlyArray<PoNode>) => Array<BodyElement>;
+/**
+ * The result of parsing a `<w:drawing>` (or legacy VML picture): an embedded
+ * picture, a DrawingML shape, a chart reference, or a SmartArt diagram. Each
+ * variant carries optional alternate text and a float anchor.
+ */
 export type DrawingContent = {
     readonly kind: 'image';
     readonly imageId: string;
     readonly width: Pt;
     readonly height: Pt;
+    /** `wp:docPr` `@descr`/`@title` — alternate text for the tagged-PDF Figure. */
     readonly altText?: string;
     readonly float?: FloatAnchor;
 } | {
@@ -26,6 +42,7 @@ export type DrawingContent = {
     readonly float?: FloatAnchor;
 } | {
     readonly kind: 'chart';
+    /** The `c:chart` `@r:id` relationship id to the chart part. */
     readonly chartRelId: string;
     readonly width: Pt;
     readonly height: Pt;
@@ -33,17 +50,88 @@ export type DrawingContent = {
     readonly float?: FloatAnchor;
 } | {
     readonly kind: 'diagram';
+    /** SmartArt data-part relationship id (`dgm:relIds` `@r:dm`); the reader resolves the drawing override. */
     readonly dmRelId: string;
+    /** Frame width in EMU. */
     readonly widthEmu: number;
+    /** Frame height in EMU. */
     readonly heightEmu: number;
     readonly altText?: string;
     readonly float?: FloatAnchor;
 };
+/**
+ * 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.
+ */
 export declare function resolveMc(altContent: PoNode): ReadonlyArray<PoNode>;
+/**
+ * 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.
+ */
 export declare function expandMcChildren(children: ReadonlyArray<PoNode>): Array<PoNode>;
+/**
+ * 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.
+ */
 export declare function parseDrawing(drawing: PoNode, resolveColor: ColorResolver, parseBody?: ParseBody): DrawingContent | 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.
+ */
 export declare function parseVmlPicture(node: PoNode): DrawingContent | null;
+/**
+ * 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.
+ */
 export declare function parsePrstGeom(prst: PoNode): ShapeGeometry;
+/**
+ * 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.
+ */
 export declare function parseCustGeom(cust: PoNode): ShapeGeometry;
+/**
+ * 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.
+ */
 export declare function parseFill(spPr: PoNode, resolveColor: ColorResolver): ShapeFill;
+/**
+ * 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.
+ */
 export declare function parseLine(spPr: PoNode, resolveColor: ColorResolver): ShapeLine | undefined;

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 {};