reamkit 1.15.1 → 1.15.3

package/dist/esm/pptx/sp-helpers.d.ts

@@ -1,17 +1,45 @@
 import { RunProperties } from '../core/document-model/index.js';
 import { ColorResolver } from '../core/drawingml/colors.js';
 import { PoNode } from '../core/po-helpers.js';
+/**
+ * §19.3.1.36 `p:ph` — a shape's placeholder reference. `type`/`idx` tie a slide
+ * shape to the matching prototype in its layout and master.
+ */
 export interface PlaceholderRef {
+    /** The placeholder type, e.g. `'title'`, `'ctrTitle'`, `'subTitle'`, `'body'`, `'obj'`. */
     readonly type?: string;
     readonly idx?: string;
 }
+/** An `a:xfrm` box in EMU (`off` + `ext`). */
 export interface ShapeBoxEmu {
     readonly x: number;
     readonly y: number;
     readonly cx: number;
     readonly cy: number;
 }
+/**
+ * `p:nvSpPr/p:nvPr/p:ph` → the placeholder reference, or `undefined` for an
+ * ordinary (non-placeholder) shape. A bare `<p:ph/>` returns an empty ref (still
+ * a placeholder: `type` defaults to `'obj'`).
+ */
 export declare function parsePh(sp: PoNode): PlaceholderRef | undefined;
+/**
+ * An xfrm node (`a:off` + `a:ext` children) → the EMU box. Works for both
+ * `a:xfrm` (in `p:spPr`) and `p:xfrm` (on a `p:graphicFrame`), whose children are
+ * identical. Returns `undefined` for a missing or degenerate (non-positive)
+ * extent.
+ */
 export declare function boxFromXfrm(xfrm: PoNode | undefined): ShapeBoxEmu | undefined;
+/**
+ * `p:spPr/a:xfrm` → the EMU box, or `undefined` when the shape carries no
+ * explicit transform (a placeholder that inherits it from the layout/master).
+ */
 export declare function parseXfrmBox(spPr: PoNode | undefined): ShapeBoxEmu | undefined;
+/**
+ * `a:rPr` / `a:defRPr` → {@link RunProperties}. Both the direct run formatting on
+ * a slide (`a:rPr`) and the per-level defaults in a master's `p:txStyles`
+ * (`a:defRPr`) share this element, so the cascade reuses the same reader: size
+ * (`sz`, hundredths of a point), bold/italic/underline, solid colour and the
+ * latin typeface. Scheme colours and the theme font cascade come in PX5.
+ */
 export declare function rPrToRunProps(rPr: PoNode | undefined, colors: ColorResolver): RunProperties;

package/dist/esm/pptx/sp-helpers.js

@@ -3,6 +3,11 @@ import { poAttr, poChildren, poIntAttr, poIs } from "../core/po-helpers.js";
 import { resolveColorNode } from "../core/drawingml/colors.js";
 //#region src/pptx/sp-helpers.ts
 var isTrue = (v) => v === "1" || v === "true" || v === "on";
+/**
+* `p:nvSpPr/p:nvPr/p:ph` → the placeholder reference, or `undefined` for an
+* ordinary (non-placeholder) shape. A bare `<p:ph/>` returns an empty ref (still
+* a placeholder: `type` defaults to `'obj'`).
+*/
 function parsePh(sp) {
 	const nvSpPr = poChildren(sp).find((c) => poIs(c, "p:nvSpPr"));
 	const nvPr = nvSpPr ? poChildren(nvSpPr).find((c) => poIs(c, "p:nvPr")) : void 0;
@@ -15,6 +20,12 @@ function parsePh(sp) {
 		...idx !== void 0 ? { idx } : {}
 	};
 }
+/**
+* An xfrm node (`a:off` + `a:ext` children) → the EMU box. Works for both
+* `a:xfrm` (in `p:spPr`) and `p:xfrm` (on a `p:graphicFrame`), whose children are
+* identical. Returns `undefined` for a missing or degenerate (non-positive)
+* extent.
+*/
 function boxFromXfrm(xfrm) {
 	if (!xfrm) return void 0;
 	const off = poChildren(xfrm).find((c) => poIs(c, "a:off"));
@@ -29,9 +40,20 @@ function boxFromXfrm(xfrm) {
 		cy
 	};
 }
+/**
+* `p:spPr/a:xfrm` → the EMU box, or `undefined` when the shape carries no
+* explicit transform (a placeholder that inherits it from the layout/master).
+*/
 function parseXfrmBox(spPr) {
 	return boxFromXfrm(spPr ? poChildren(spPr).find((c) => poIs(c, "a:xfrm")) : void 0);
 }
+/**
+* `a:rPr` / `a:defRPr` → {@link RunProperties}. Both the direct run formatting on
+* a slide (`a:rPr`) and the per-level defaults in a master's `p:txStyles`
+* (`a:defRPr`) share this element, so the cascade reuses the same reader: size
+* (`sz`, hundredths of a point), bold/italic/underline, solid colour and the
+* latin typeface. Scheme colours and the theme font cascade come in PX5.
+*/
 function rPrToRunProps(rPr, colors) {
 	if (!rPr) return {};
 	const sz = poIntAttr(rPr, "sz");

package/dist/esm/svg/svg-writer.d.ts

@@ -1,8 +1,25 @@
 import { DocumentWriter, WriteResult } from '../core/ir/adapters.js';
 import { LaidOutDocument } from '../layout/page-doc.js';
+/** Options for {@link writeSvg}. */
 export interface SvgWriteOptions {
     /** Gap between stacked pages, in px/pt (default 12). */
     readonly pageGap?: number;
 }
+/**
+ * Render a {@link LaidOutDocument} to a single SVG preview (ir-design §7 /
+ * stage 6). Written purely against the PageDoc schema; knows nothing about OOXML
+ * or the PDF writer. PageItem coordinates are already top-left/y-down — SVG's own
+ * frame — so they are emitted verbatim. Pages stack vertically in one `<svg>`,
+ * separated by {@link SvgWriteOptions.pageGap}, each on a white outlined rect so
+ * they read as pages.
+ *
+ * @param laid The laid-out, paginated document from the layout engine.
+ * @param opts Optional page-gap override.
+ * @returns The encoded SVG bytes plus the recorded {@link Loss} list.
+ */
 export declare function writeSvg(laid: LaidOutDocument, opts?: SvgWriteOptions): WriteResult;
+/**
+ * The page-medium {@link DocumentWriter} adapter (id `'svg'`), wrapping
+ * {@link writeSvg}, with the set of {@link FEATURES} it renders.
+ */
 export declare const svgWriter: DocumentWriter<LaidOutDocument>;

package/dist/esm/svg/svg-writer.js

@@ -5,6 +5,18 @@ import { paintPlan } from "../layout/page-doc.js";
 import { toBase64 } from "../core/bytes.js";
 //#region src/svg/svg-writer.ts
 var PAGE_GAP = 12;
+/**
+* Render a {@link LaidOutDocument} to a single SVG preview (ir-design §7 /
+* stage 6). Written purely against the PageDoc schema; knows nothing about OOXML
+* or the PDF writer. PageItem coordinates are already top-left/y-down — SVG's own
+* frame — so they are emitted verbatim. Pages stack vertically in one `<svg>`,
+* separated by {@link SvgWriteOptions.pageGap}, each on a white outlined rect so
+* they read as pages.
+*
+* @param laid The laid-out, paginated document from the layout engine.
+* @param opts Optional page-gap override.
+* @returns The encoded SVG bytes plus the recorded {@link Loss} list.
+*/
 function writeSvg(laid, opts = {}) {
 	const gap = opts.pageGap ?? PAGE_GAP;
 	const losses = [];
@@ -27,6 +39,10 @@ function writeSvg(laid, opts = {}) {
 		losses
 	};
 }
+/**
+* The page-medium {@link DocumentWriter} adapter (id `'svg'`), wrapping
+* {@link writeSvg}, with the set of {@link FEATURES} it renders.
+*/
 var svgWriter = {
 	id: "svg",
 	consumes: "page",

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

@@ -1,4 +1,20 @@
 import { DocumentReader, ReadResult } from '../../core/ir/adapters.js';
 import { FlowDoc } from '../../core/ir/flow.js';
+/**
+ * Read a legacy Word 97–2003 `.doc` (DOC-1..11) into the same {@link FlowDoc} the
+ * OOXML docx reader produces: paragraphs of formatted runs, tables (column widths,
+ * cell borders, vertical merges, shading), inline images, list items, the first
+ * section's page size and the section's headers/footers. The text + formatting is
+ * read; drawing shapes / text boxes and comments are not, so a `degraded` (or
+ * `dropped`, for an encrypted file) {@link Loss} is reported.
+ *
+ * @param bytes The `.doc` (OLE2/CFB) bytes.
+ * @returns The projected {@link FlowDoc} and the read loss(es).
+ */
 export declare function readDoc(bytes: Uint8Array): ReadResult<FlowDoc>;
+/**
+ * The {@link DocumentReader} for legacy `.doc`: sniffs a Word 97–2003 binary (a
+ * CFB with a `WordDocument` stream) and reads it via {@link readDoc} into a
+ * {@link FlowDoc}.
+ */
 export declare const docReader: DocumentReader<FlowDoc>;

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

@@ -114,6 +114,17 @@ var DOC_ENCRYPTED_LOSS = {
 	feature: FEATURES.text,
 	detail: "legacy .doc is encrypted/obfuscated — its text cannot be read"
 };
+/**
+* Read a legacy Word 97–2003 `.doc` (DOC-1..11) into the same {@link FlowDoc} the
+* OOXML docx reader produces: paragraphs of formatted runs, tables (column widths,
+* cell borders, vertical merges, shading), inline images, list items, the first
+* section's page size and the section's headers/footers. The text + formatting is
+* read; drawing shapes / text boxes and comments are not, so a `degraded` (or
+* `dropped`, for an encrypted file) {@link Loss} is reported.
+*
+* @param bytes The `.doc` (OLE2/CFB) bytes.
+* @returns The projected {@link FlowDoc} and the read loss(es).
+*/
 function readDoc(bytes) {
 	const content = extractDocContent(bytes);
 	const resources = new ResourceStore();
@@ -416,6 +427,11 @@ function alignmentFromJc(jc) {
 		default: return;
 	}
 }
+/**
+* The {@link DocumentReader} for legacy `.doc`: sniffs a Word 97–2003 binary (a
+* CFB with a `WordDocument` stream) and reads it via {@link readDoc} into a
+* {@link FlowDoc}.
+*/
 var docReader = {
 	id: "doc",
 	produces: "flow",

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

@@ -1,21 +1,37 @@
+/** Run (character) formatting decoded from a CHPX grpprl. */
 export interface DocCharProps {
     readonly bold?: boolean;
     readonly italic?: boolean;
+    /** Word `kul` underline code (0 = none). */
     readonly underlineKul?: number;
+    /** Font size in half-points. */
     readonly sizeHalfPts?: number;
+    /** The character is special — `sprmCFSpec` (e.g. a picture placeholder). */
     readonly fSpec?: boolean;
+    /** `sprmCPicLocation` — offset into the `Data` stream of the picture's PICF. */
     readonly picOffset?: number;
 }
+/** An embedded picture: the extracted image bytes and its display size (twips). */
 export interface DocPicture {
     readonly bytes: Uint8Array;
     readonly widthTwips: number;
     readonly heightTwips: number;
 }
+/**
+ * One cell border (DOC-11) from a Brc80: its width in points, colour and whether
+ * it is a double line. Absent when the cell edge has no border.
+ */
 export interface DocBorder {
     readonly widthPt: number;
     readonly colorHex: string;
+    /** The border is a double line (`brcType` 0x03). */
     readonly double?: boolean;
 }
+/**
+ * A table cell's TC80 descriptor (DOC-11): its four edge borders and its
+ * vertical-merge marker (`restart` = the top of a vertical span, `continue` = a
+ * cell merged into the one above). Carried per cell on the row's TTP.
+ */
 export interface DocTc {
     readonly borders?: {
         readonly top?: DocBorder;
@@ -25,31 +41,62 @@ export interface DocTc {
     };
     readonly vMerge?: 'restart' | 'continue';
 }
+/** Paragraph formatting decoded from a PAPX grpprl. */
 export interface DocParaProps {
+    /** Word justification (0 left, 1 center, 2 right, 3 both, 4 distribute). */
     readonly jc?: number;
     readonly indentLeftTwips?: number;
     readonly indentRightTwips?: number;
+    /** First-line indent, signed (negative = hanging). */
     readonly indentFirstTwips?: number;
     readonly spaceBeforeTwips?: number;
     readonly spaceAfterTwips?: number;
+    /** The paragraph is in a table — `sprmPFInTable`. */
     readonly inTable?: boolean;
+    /** This is the row's terminating paragraph (TTP) — `sprmPFTtp`. */
     readonly rowEnd?: boolean;
+    /**
+     * `sprmTDefTable` rgdxaCenter — the (cols+1) cell-boundary x-positions (twips);
+     * present on the TTP. Cell `i` width = `edge[i+1] − edge[i]`.
+     */
     readonly cellEdgesTwips?: ReadonlyArray<number>;
+    /**
+     * `sprmTDefTable` TC80 per-cell descriptors (borders + vertical merge), one per
+     * cell, present on the TTP alongside `cellEdgesTwips` (DOC-11).
+     */
     readonly cellDescriptors?: ReadonlyArray<DocTc>;
+    /**
+     * `sprmTDefTableShd` — each cell's background fill hex (cvBack), or `undefined`
+     * for an auto (no-fill) cell. Indexed parallel to `cellDescriptors`.
+     */
     readonly cellShadings?: ReadonlyArray<string | undefined>;
+    /** `sprmPIlfo` — list-format override index (>0 ⇒ the paragraph is a list item). */
     readonly listIlfo?: number;
+    /** `sprmPIlvl` — list level (0–8). */
     readonly listIlvl?: number;
 }
+/** One maximal same-formatting run of text, or an embedded picture. */
 export interface DocRun {
     readonly text: string;
     readonly props: DocCharProps;
+    /** Set instead of `text` when the run is an embedded picture. */
     readonly picture?: DocPicture;
 }
+/** One paragraph: its runs plus the decoded paragraph properties. */
 export interface DocParagraph {
     readonly runs: ReadonlyArray<DocRun>;
     readonly props: DocParaProps;
+    /**
+     * The paragraph was ended by a cell mark (0x07) rather than a CR — i.e. it
+     * closes a table cell. With `props.rowEnd` it also closes the row.
+     */
     readonly cellMark?: boolean;
 }
+/**
+ * The section's header/footer stories (best-effort: the binary story ordering
+ * cannot be validated against a real file, so only well-formed, non-empty stories
+ * are surfaced). `default` is the odd-page (primary) header/footer.
+ */
 export interface DocHeaderFooters {
     readonly defaultHeader?: ReadonlyArray<DocParagraph>;
     readonly defaultFooter?: ReadonlyArray<DocParagraph>;
@@ -58,11 +105,21 @@ export interface DocHeaderFooters {
     readonly evenHeader?: ReadonlyArray<DocParagraph>;
     readonly evenFooter?: ReadonlyArray<DocParagraph>;
 }
+/**
+ * One list level (LVL) — the format of its number (DOC-10). `nfc` is the MSONFC
+ * code (0 arabic, 1/2 upper/lower roman, 3/4 upper/lower letter, 23 bullet, 0xFF
+ * none); `xst` is the number-text template as UTF-16 code units, where a code unit
+ * ≤ 8 is a placeholder for the number of that (zero-based) level.
+ */
 export interface DocLvl {
     readonly nfc: number;
     readonly iStartAt: number;
     readonly xst: ReadonlyArray<number>;
 }
+/**
+ * The document's list tables (DOC-10): an LFO → lsid map (a paragraph's 1-based
+ * `sprmPIlfo` indexes it) and, per lsid, the list's levels.
+ */
 export interface DocListTables {
     readonly lfoLsids: ReadonlyArray<number>;
     readonly lists: ReadonlyMap<number, {
@@ -70,14 +127,34 @@ export interface DocListTables {
         readonly levels: ReadonlyArray<DocLvl>;
     }>;
 }
+/** Everything extracted from a `.doc`'s `WordDocument` stream. */
 export interface DocContent {
     readonly paragraphs: ReadonlyArray<DocParagraph>;
     readonly headerFooters?: DocHeaderFooters;
+    /** The list tables resolving a paragraph's (ilfo, ilvl) to its number format. */
     readonly listTables?: DocListTables;
+    /**
+     * The first section's page size in points (xaPage/yaPage from its SEP), when
+     * present and sane; absent ⇒ the reader's default (US Letter) applies.
+     */
     readonly pageSize?: {
         readonly widthPt: number;
         readonly heightPt: number;
     };
+    /** The file is encrypted/obfuscated — text cannot be read without the key. */
     readonly encrypted: boolean;
 }
+/**
+ * Extract a `.doc`'s `WordDocument` stream into its main-document paragraphs plus
+ * the section's header/footer stories, list tables and first-section page size.
+ * Joins the piece table (CLX → CPs/FCs), CHPX run formatting and PAPX paragraph
+ * formatting, splitting at the CR / cell marks. Every offset is bounds-checked, so
+ * a structurally odd file yields no text rather than throwing.
+ *
+ * @param bytes The `.doc` (OLE2/CFB) bytes.
+ * @returns The extracted {@link DocContent}; `encrypted` is set (with no
+ *   paragraphs) for an encrypted file, and an empty result is returned when the
+ *   stream is missing, not a Word file, or has no piece table (Word 6/95 is out of
+ *   scope).
+ */
 export declare function extractDocContent(bytes: Uint8Array): DocContent;

package/dist/esm/word/doc/doc-text.js

@@ -86,6 +86,19 @@ function readSectionPageSize(wd, table) {
 		heightPt: ya / 20
 	};
 }
+/**
+* Extract a `.doc`'s `WordDocument` stream into its main-document paragraphs plus
+* the section's header/footer stories, list tables and first-section page size.
+* Joins the piece table (CLX → CPs/FCs), CHPX run formatting and PAPX paragraph
+* formatting, splitting at the CR / cell marks. Every offset is bounds-checked, so
+* a structurally odd file yields no text rather than throwing.
+*
+* @param bytes The `.doc` (OLE2/CFB) bytes.
+* @returns The extracted {@link DocContent}; `encrypted` is set (with no
+*   paragraphs) for an encrypted file, and an empty result is returned when the
+*   stream is missing, not a Word file, or has no piece table (Word 6/95 is out of
+*   scope).
+*/
 function extractDocContent(bytes) {
 	const cfb = openCfb(bytes);
 	const wd = cfb.readStream("WordDocument");

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

@@ -2,24 +2,122 @@ import { BodyElement, Comment, Section, SectionProperties } from '../core/docume
 import { ColorResolver } from '../core/drawingml/colors.js';
 import { Loss, ResourceId } from '../core/ir/index.js';
 import { PoNode } from '../core/po-helpers.js';
+/**
+ * Resolves a drawing relationship id to a content-addressed `ResourceId` —
+ * supplied by the converter (which owns the OPC package and the `ResourceStore`).
+ */
 export type ImageResolver = (relId: string) => ResourceId | undefined;
+/** Resolves a `w:hyperlink` `r:id` to its external target URL. */
 export type HyperlinkResolver = (relId: string) => string | undefined;
+/**
+ * Document-wide resolvers every nested parser needs — one context object instead
+ * of threading a parameter pair through ten signatures (oop-design §8).
+ */
 export interface ParseContext {
+    /** Resolver for theme/scheme/auto colours. */
     readonly resolveColor: ColorResolver;
+    /** Resolver for a drawing relationship id to a stored image. */
     readonly resolveImage?: ImageResolver;
+    /**
+     * §17.16.22 `w:hyperlink` `r:id` → external target URL from the owning part's
+     * rels (`TargetMode="External"` only). Absent ⇒ links unwrap to plain text.
+     */
     readonly resolveHyperlink?: HyperlinkResolver;
+    /**
+     * SmartArt: a data relationship id (`dgm:relIds` `@r:dm`) → the diagram's
+     * pre-rendered drawing override (its `dsp:spTree`), or `undefined` when the file
+     * ships none (E-SMARTART SA2).
+     */
     readonly resolveDiagram?: (relId: string) => PoNode | undefined;
+    /**
+     * Sink for graceful-degradation notices (E-SMARTART SA3): a SmartArt with no
+     * drawing override records a dropped-feature {@link Loss} rather than vanishing.
+     */
     readonly onLoss?: (loss: Loss) => void;
+    /**
+     * §17.13.4 comment ranges currently open as the body is read — a mutable set
+     * the run collector stamps onto each run (`commentRangeRefs`). A comment range
+     * can span paragraphs, so the state is document-level, not per-paragraph. The
+     * reference is readonly; its contents mutate during the walk (CM2c).
+     */
     readonly openCommentRanges?: Set<string>;
 }
+/** The default {@link ParseContext} — just the default colour resolver. */
 export declare const DEFAULT_PARSE_CONTEXT: ParseContext;
+/**
+ * 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.
+ */
 export declare function parseDocument(documentXml: Uint8Array, ctx?: ParseContext): Array<BodyElement>;
+/** The empty {@link SectionProperties} fallback (no headers/footers). */
 export declare const EMPTY_SECTION: SectionProperties;
+/**
+ * Parse the document's final section properties (ECMA-376 Part 1 §17.6.17 — the
+ * body-level `sectPr` is the last child of `w:body` and describes the final
+ * section). Returned as a single {@link SectionProperties} for backward
+ * compatibility; multi-section documents use {@link parseSections} instead.
+ *
+ * @param documentXml The raw `document.xml` bytes.
+ * @returns The final section's properties, or {@link EMPTY_SECTION} when there is none.
+ */
 export declare function parseSection(documentXml: Uint8Array): SectionProperties;
+/**
+ * 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.
+ */
 export declare function parseSections(documentXml: Uint8Array): Array<Section>;
+/**
+ * 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.
+ */
 export declare function parseHeaderFooter(xml: Uint8Array, ctx?: ParseContext): Array<BodyElement>;
+/**
+ * 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.
+ */
 export declare function parseBodyElements(children: ReadonlyArray<PoNode>, ctx?: ParseContext): Array<BodyElement>;
+/**
+ * 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.
+ */
 export declare function parseNotes(notesXml: Uint8Array, rootTag: 'w:footnotes' | 'w:endnotes', noteTag: 'w:footnote' | 'w:endnote', ctx?: ParseContext): Map<string, Array<BodyElement>>;
+/**
+ * Parse `word/comments.xml` (§17.13.4) into {@link Comment}s by id, each with its
+ * block content and author/initials/date attribution. Thread metadata is added
+ * separately by {@link parseCommentThreads}.
+ *
+ * @param commentsXml The raw `comments.xml` bytes.
+ * @param ctx         The document-wide parse context.
+ * @returns A map from comment id to the parsed comment.
+ */
 export declare function parseComments(commentsXml: Uint8Array, ctx?: ParseContext): Map<string, Comment>;
 /** A commentsExtended entry, keyed by the comment's last-paragraph w14:paraId. */
 export interface CommentExtension {
@@ -28,7 +126,43 @@ export interface CommentExtension {
     /** w15:done — the thread is resolved. */
     readonly done: boolean;
 }
+/**
+ * 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}.
+ */
 export declare function parseCommentsExtended(xml: Uint8Array): Map<string, CommentExtension>;
+/**
+ * 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.
+ */
 export declare function parseCommentThreads(commentsXml: Uint8Array, commentsExtendedXml: Uint8Array | undefined, ctx?: ParseContext): Map<string, Comment>;
+/**
+ * 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.
+ */
 export declare function parsePeople(xml: Uint8Array): Map<string, string>;
+/**
+ * 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.
+ */
 export declare function applyAuthorIds(comments: Map<string, Comment>, people: Map<string, string>): Map<string, Comment>;