reamkit 1.15.0 → 1.15.2

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

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

@@ -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",

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;