reamkit 1.15.1 → 1.15.2

package/dist/esm/core/numbering/state.d.ts

@@ -1,6 +1,21 @@
 import { AbstractNumbering, Numbering, NumberingLevel, NumberingReference } from '../document-model/index.js';
+/**
+ * Mutable list-counter state for one numbering scope (e.g. a body or a single
+ * header/footer band). Tracks a counter per list per level and advances them as
+ * paragraphs are visited in order.
+ */
 export declare class NumberingState {
     private readonly counters;
+    /**
+     * Advance the counter for `ref` (resetting deeper levels) and format its
+     * marker text. The first hit at a level seeds it from the level's `start`;
+     * subsequent hits increment.
+     *
+     * @param numbering The parsed numbering definitions.
+     * @param ref       The paragraph's `numId` + `ilvl` reference.
+     * @returns The formatted marker (e.g. `"2."`, `"•"`), or `null` when the
+     *          reference does not resolve to a known list level.
+     */
     resolveMarker(numbering: Numbering, ref: NumberingReference): string | null;
 }
 export declare function formatLevelMarker(abstractNum: AbstractNumbering, currentLevel: NumberingLevel, counters: ReadonlyArray<number>): string;

package/dist/esm/core/numbering/state.js

@@ -1,6 +1,21 @@
 //#region src/core/numbering/state.ts
+/**
+* Mutable list-counter state for one numbering scope (e.g. a body or a single
+* header/footer band). Tracks a counter per list per level and advances them as
+* paragraphs are visited in order.
+*/
 var NumberingState = class {
 	counters = /* @__PURE__ */ new Map();
+	/**
+	* Advance the counter for `ref` (resetting deeper levels) and format its
+	* marker text. The first hit at a level seeds it from the level's `start`;
+	* subsequent hits increment.
+	*
+	* @param numbering The parsed numbering definitions.
+	* @param ref       The paragraph's `numId` + `ilvl` reference.
+	* @returns The formatted marker (e.g. `"2."`, `"•"`), or `null` when the
+	*          reference does not resolve to a known list level.
+	*/
 	resolveMarker(numbering, ref) {
 		const instance = numbering.numInstances.get(ref.numId);
 		if (!instance) return null;

package/dist/esm/core/ole/cfb.d.ts

@@ -1,12 +1,16 @@
+/** The object type of a CFB directory entry (MS-CFB §2.6.1). */
 export type CfbEntryType = 'root' | 'storage' | 'stream' | 'unknown';
+/** One CFB directory entry: its name, type, starting sector and byte size. */
 export interface CfbEntry {
     readonly name: string;
     readonly type: CfbEntryType;
     readonly startSector: number;
     readonly size: number;
 }
+/** Error thrown for a malformed or unsupported compound file. */
 export declare class CfbError extends Error {
 }
+/** A parsed compound file: its directory entries plus stream-access helpers. */
 export interface Cfb {
     /** Every directory entry, in directory order (index 0 is the root storage). */
     readonly entries: ReadonlyArray<CfbEntry>;
@@ -15,5 +19,20 @@ export interface Cfb {
     /** Whether a stream entry with that name exists (case-insensitive). */
     hasStream: (name: string) => boolean;
 }
+/**
+ * Cheap magic-byte probe — the first eight bytes are the CFB signature. Shared
+ * by the legacy readers' sniff and by `OpcPackage` to tell an OLE file from a
+ * ZIP.
+ */
 export declare function isCfb(bytes: Uint8Array): boolean;
+/**
+ * Parse a compound file's bytes into a {@link Cfb}: read the header, FAT (via the
+ * DIFAT), directory and mini-FAT, and expose its streams by name. The
+ * main-document storage's own streams win a name clash over an embedded object's
+ * (MS-CFB §2.6). Every sector index is bounds-checked and every chain walk is
+ * capped, so a crafted container aborts rather than looping or exhausting memory.
+ *
+ * @throws CfbError on a bad signature, an unsupported sector layout, or a
+ *         corrupt/cyclic FAT, mini-FAT or DIFAT chain.
+ */
 export declare function openCfb(bytes: Uint8Array): Cfb;

package/dist/esm/core/ole/cfb.js

@@ -14,12 +14,28 @@ var FREESECT = 4294967295;
 var HEADER_SIZE = 512;
 var DIR_ENTRY_SIZE = 128;
 var MAX_TOTAL_BYTES = 512 * 1024 * 1024;
+/** Error thrown for a malformed or unsupported compound file. */
 var CfbError = class extends Error {};
+/**
+* Cheap magic-byte probe — the first eight bytes are the CFB signature. Shared
+* by the legacy readers' sniff and by `OpcPackage` to tell an OLE file from a
+* ZIP.
+*/
 function isCfb(bytes) {
 	if (bytes.length < HEADER_SIZE) return false;
 	for (let i = 0; i < SIGNATURE.length; i++) if (bytes[i] !== SIGNATURE[i]) return false;
 	return true;
 }
+/**
+* Parse a compound file's bytes into a {@link Cfb}: read the header, FAT (via the
+* DIFAT), directory and mini-FAT, and expose its streams by name. The
+* main-document storage's own streams win a name clash over an embedded object's
+* (MS-CFB §2.6). Every sector index is bounds-checked and every chain walk is
+* capped, so a crafted container aborts rather than looping or exhausting memory.
+*
+* @throws CfbError on a bad signature, an unsupported sector layout, or a
+*         corrupt/cyclic FAT, mini-FAT or DIFAT chain.
+*/
 function openCfb(bytes) {
 	if (!isCfb(bytes)) throw new CfbError("not a compound file (bad signature)");
 	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);

package/dist/esm/core/opc/core-properties.d.ts

@@ -1,11 +1,23 @@
+/**
+ * Package-level metadata from `docProps/core.xml` (ECMA-376 Part 2 §11.1), in
+ * the Dublin Core / OPC core vocabulary. Shared by docx and xlsx packages.
+ */
 export interface CoreProperties {
     readonly title?: string;
     readonly subject?: string;
+    /** `dc:creator` → PDF "Author". */
     readonly creator?: string;
     readonly keywords?: string;
     readonly description?: string;
     readonly lastModifiedBy?: string;
+    /** `dcterms:created` timestamp. */
     readonly created?: Date;
+    /** `dcterms:modified` timestamp. */
     readonly modified?: Date;
 }
+/**
+ * Parse `docProps/core.xml` into {@link CoreProperties}. Tolerates the
+ * `cp:`/`dc:`/`dcterms:` prefixed and the bare element forms; returns `{}` when
+ * the root element is absent.
+ */
 export declare function parseCoreProperties(data: Uint8Array): CoreProperties;

package/dist/esm/core/opc/core-properties.js

@@ -9,6 +9,11 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	trimValues: false
 });
+/**
+* Parse `docProps/core.xml` into {@link CoreProperties}. Tolerates the
+* `cp:`/`dc:`/`dcterms:` prefixed and the bare element forms; returns `{}` when
+* the root element is absent.
+*/
 function parseCoreProperties(data) {
 	const tree = parser.parse(decoder.decode(data));
 	const root = tree["cp:coreProperties"] ?? tree["coreProperties"];

package/dist/esm/core/opc/opc-writer.d.ts

@@ -1,19 +1,27 @@
 import { Relationship } from './relationships.js';
+/** One part to write into the package: its path, bytes, and content type. */
 export interface OpcPart {
-    /** Package path, e.g. 'word/document.xml'. No leading slash. */
+    /** Package path, e.g. `'word/document.xml'`. No leading slash. */
     readonly path: string;
     readonly data: Uint8Array;
-    /** Content type for the [Content_Types].xml Override (XML parts). */
+    /** Content type for the `[Content_Types].xml` Override (XML parts). */
     readonly contentType: string;
 }
+/**
+ * A part's relationships (id/type/target[/External]). The reader returns the
+ * same {@link Relationship} shape, so a writer round-trips through
+ * `parseRelationships`.
+ */
 export interface OpcPartRelationships {
-    /** The owning part, e.g. 'word/document.xml' (or '' for the package root). */
+    /** The owning part, e.g. `'word/document.xml'` (or `''` for the package root). */
     readonly sourcePart: string;
     readonly relationships: ReadonlyArray<Relationship>;
 }
+/** The full input to {@link buildOpcPackage}: parts plus their relationships. */
 export interface OpcWriteOptions {
+    /** The content parts (excluding `[Content_Types].xml` and `.rels`, which are generated). */
     readonly parts: ReadonlyArray<OpcPart>;
-    /** Package-level relationships (_rels/.rels). */
+    /** Package-level relationships (`_rels/.rels`). */
     readonly rootRelationships: ReadonlyArray<Relationship>;
     /** Per-part relationships (word/_rels/<part>.rels). */
     readonly partRelationships?: ReadonlyArray<OpcPartRelationships>;
@@ -24,5 +32,17 @@ export interface OpcWriteOptions {
      */
     readonly defaultsByExtension?: Readonly<Record<string, string>>;
 }
+/**
+ * Assemble parts + relationships into a deterministic OPC ZIP: it synthesizes
+ * `[Content_Types].xml` and the `.rels` parts, then zips everything with a fixed
+ * timestamp so the same input always yields byte-identical output.
+ *
+ * @returns The packaged `.docx`/`.xlsx`/… bytes.
+ */
 export declare function buildOpcPackage(options: OpcWriteOptions): Uint8Array;
+/**
+ * The relationships-part path for a part: `word/document.xml` →
+ * `word/_rels/document.xml.rels`. (`''` (root) is handled separately as
+ * `_rels/.rels`.)
+ */
 export declare function relsPathFor(partPath: string): string;

package/dist/esm/core/opc/opc-writer.js

@@ -4,6 +4,13 @@ var encoder = new TextEncoder();
 var RELS_NS = "http://schemas.openxmlformats.org/package/2006/relationships";
 var CT_NS = "http://schemas.openxmlformats.org/package/2006/content-types";
 var FIXED_MTIME = Date.UTC(1980, 0, 1, 0, 0, 0);
+/**
+* Assemble parts + relationships into a deterministic OPC ZIP: it synthesizes
+* `[Content_Types].xml` and the `.rels` parts, then zips everything with a fixed
+* timestamp so the same input always yields byte-identical output.
+*
+* @returns The packaged `.docx`/`.xlsx`/… bytes.
+*/
 function buildOpcPackage(options) {
 	const entries = {};
 	const add = (path, data) => {
@@ -18,6 +25,11 @@ function buildOpcPackage(options) {
 	}
 	return zipSync(entries);
 }
+/**
+* The relationships-part path for a part: `word/document.xml` →
+* `word/_rels/document.xml.rels`. (`''` (root) is handled separately as
+* `_rels/.rels`.)
+*/
 function relsPathFor(partPath) {
 	const slash = partPath.lastIndexOf("/");
 	const dir = slash >= 0 ? partPath.slice(0, slash) : "";

package/dist/esm/core/opc/package.d.ts

@@ -1,25 +1,80 @@
 import { Relationship } from './relationships.js';
+/**
+ * Resource caps applied while unzipping a package — a defence against
+ * decompression ("zip") bombs and pathological archives. Generous defaults that
+ * never reject a legitimate office document; tighten for untrusted input.
+ */
 export interface OpcOpenOptions {
+    /** Reject an archive whose raw (compressed) size exceeds this (default 128 MiB). */
     readonly maxArchiveBytes?: number;
+    /** Reject any single entry declaring an uncompressed size over this (default 256 MiB). */
     readonly maxEntryBytes?: number;
+    /** Reject if the total declared uncompressed size exceeds this (default 512 MiB). */
     readonly maxTotalBytes?: number;
+    /** Reject archives with more than this many entries (default 65 536). */
     readonly maxEntries?: number;
 }
+/**
+ * An opened OPC package (ECMA-376 Part 2): a ZIP archive's parts plus its
+ * package-level relationships, with helpers to look up parts, resolve part
+ * relationships, and find the main document part.
+ */
 export declare class OpcPackage {
     private readonly parts;
     private readonly rootRelationships;
+    /**
+     * @param parts             The package parts keyed by ZIP-convention path (no leading slash).
+     * @param rootRelationships The package-level relationships from `_rels/.rels`.
+     */
     private constructor();
     private readonly relsCache;
+    /**
+     * Unzip and validate a package's bytes. Rejects an OLE compound file (an
+     * encrypted OOXML container or a legacy binary `.doc`/`.xls`) and enforces the
+     * zip-bomb caps from `options`.
+     *
+     * @throws Error when the bytes are not a ZIP package, a cap is exceeded, or
+     *         `_rels/.rels` is missing.
+     */
     static open(buffer: Uint8Array, options?: OpcOpenOptions): OpcPackage;
+    /** The bytes of the part at `path`, or undefined when absent. */
     getPart(path: string): Uint8Array | undefined;
+    /**
+     * The bytes of the part at `path`.
+     *
+     * @throws Error when the part is absent.
+     */
     requirePart(path: string): Uint8Array;
+    /** Every part path in the package (ZIP convention, no leading slash). */
     listParts(): Array<string>;
+    /**
+     * The relationships of the part at `partPath` (ECMA-376 Part 2 §9.3.4). For a
+     * part at `dir/name.ext` they live at `dir/_rels/name.ext.rels`. Returns `[]`
+     * if the rels part is absent. Parsed rels are cached per part.
+     */
     getPartRelationships(partPath: string): ReadonlyArray<Relationship>;
+    /**
+     * Resolve a relationship against its source part and return the related part's
+     * resolved path + data (Internal relationships only). External relationships
+     * (e.g. http hyperlinks) and unresolvable targets return undefined.
+     */
     resolveRelatedPart(sourcePartPath: string, relationship: Relationship): {
         readonly path: string;
         readonly data: Uint8Array;
     } | undefined;
+    /**
+     * The path of the main document part, from the package's single
+     * `officeDocument` relationship (ECMA-376 Part 2 §11.1).
+     *
+     * @throws Error when there is no such relationship, or more than one.
+     */
     getMainDocumentPath(): string;
+    /**
+     * The main document part's path and bytes.
+     *
+     * @throws Error when the officeDocument relationship is missing/ambiguous or
+     *         the part it points at is absent.
+     */
     getMainDocument(): {
         path: string;
         data: Uint8Array;

package/dist/esm/core/opc/package.js

@@ -4,12 +4,29 @@ import { unzipSync } from "fflate";
 //#region src/core/opc/package.ts
 var ROOT_RELS_PATH = "_rels/.rels";
 var MIB = 1024 * 1024;
+/**
+* An opened OPC package (ECMA-376 Part 2): a ZIP archive's parts plus its
+* package-level relationships, with helpers to look up parts, resolve part
+* relationships, and find the main document part.
+*/
 var OpcPackage = class OpcPackage {
+	/**
+	* @param parts             The package parts keyed by ZIP-convention path (no leading slash).
+	* @param rootRelationships The package-level relationships from `_rels/.rels`.
+	*/
 	constructor(parts, rootRelationships) {
 		this.parts = parts;
 		this.rootRelationships = rootRelationships;
 	}
 	relsCache = /* @__PURE__ */ new Map();
+	/**
+	* Unzip and validate a package's bytes. Rejects an OLE compound file (an
+	* encrypted OOXML container or a legacy binary `.doc`/`.xls`) and enforces the
+	* zip-bomb caps from `options`.
+	*
+	* @throws Error when the bytes are not a ZIP package, a cap is exceeded, or
+	*         `_rels/.rels` is missing.
+	*/
 	static open(buffer, options = {}) {
 		if (buffer.length >= 4 && buffer[0] === 208 && buffer[1] === 207 && buffer[2] === 17 && buffer[3] === 224) throw new Error("OLE compound file: a password-protected (encrypted) OOXML document or a legacy binary .doc/.xls — re-save as an unencrypted .docx/.xlsx");
 		const maxArchive = options.maxArchiveBytes ?? 128 * MIB;
@@ -43,17 +60,29 @@ var OpcPackage = class OpcPackage {
 		if (!relsBytes) throw new Error(`OPC package missing ${ROOT_RELS_PATH}`);
 		return new OpcPackage(parts, parseRelationships(relsBytes));
 	}
+	/** The bytes of the part at `path`, or undefined when absent. */
 	getPart(path) {
 		return this.parts.get(normalizePath(path));
 	}
+	/**
+	* The bytes of the part at `path`.
+	*
+	* @throws Error when the part is absent.
+	*/
 	requirePart(path) {
 		const data = this.getPart(path);
 		if (!data) throw new Error(`OPC part not found: ${path}`);
 		return data;
 	}
+	/** Every part path in the package (ZIP convention, no leading slash). */
 	listParts() {
 		return [...this.parts.keys()];
 	}
+	/**
+	* The relationships of the part at `partPath` (ECMA-376 Part 2 §9.3.4). For a
+	* part at `dir/name.ext` they live at `dir/_rels/name.ext.rels`. Returns `[]`
+	* if the rels part is absent. Parsed rels are cached per part.
+	*/
 	getPartRelationships(partPath) {
 		const normalized = normalizePath(partPath);
 		const cached = this.relsCache.get(normalized);
@@ -67,6 +96,11 @@ var OpcPackage = class OpcPackage {
 		this.relsCache.set(normalized, rels);
 		return rels;
 	}
+	/**
+	* Resolve a relationship against its source part and return the related part's
+	* resolved path + data (Internal relationships only). External relationships
+	* (e.g. http hyperlinks) and unresolvable targets return undefined.
+	*/
 	resolveRelatedPart(sourcePartPath, relationship) {
 		if (relationship.targetMode !== "Internal") return void 0;
 		const resolved = resolveTarget(`/${normalizePath(sourcePartPath)}`, relationship.target);
@@ -77,12 +111,24 @@ var OpcPackage = class OpcPackage {
 			data
 		};
 	}
+	/**
+	* The path of the main document part, from the package's single
+	* `officeDocument` relationship (ECMA-376 Part 2 §11.1).
+	*
+	* @throws Error when there is no such relationship, or more than one.
+	*/
 	getMainDocumentPath() {
 		const candidates = this.rootRelationships.filter((r) => isOoxmlRel(r.type, "officeDocument") && r.targetMode === "Internal");
 		if (candidates.length === 0) throw new Error("OPC package has no officeDocument relationship");
 		if (candidates.length > 1) throw new Error(`OPC package has multiple officeDocument relationships (${candidates.length})`);
 		return resolveTarget("/", candidates[0].target);
 	}
+	/**
+	* The main document part's path and bytes.
+	*
+	* @throws Error when the officeDocument relationship is missing/ambiguous or
+	*         the part it points at is absent.
+	*/
 	getMainDocument() {
 		const path = this.getMainDocumentPath();
 		return {

package/dist/esm/core/opc/relationship-types.d.ts

@@ -1,4 +1,12 @@
+/** Relationship Type URI of the package's main document part (officeDocument). */
 export declare const REL_OFFICE_DOCUMENT = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
+/** Relationship Type URI of the core-properties part (`docProps/core.xml`). */
 export declare const REL_CORE_PROPERTIES = "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
+/** Relationship Type URI of the extended-properties part (`docProps/app.xml`). */
 export declare const REL_EXTENDED_PROPERTIES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
+/**
+ * Whether a relationship `type` URI names the OOXML relationship `name` (e.g.
+ * `'officeDocument'`), matching against both the Transitional
+ * (`schemas.openxmlformats.org`) and Strict (`purl.oclc.org`) base URIs.
+ */
 export declare function isOoxmlRel(type: string, name: string): boolean;

package/dist/esm/core/opc/relationship-types.js

@@ -1,5 +1,10 @@
 //#region src/core/opc/relationship-types.ts
 var OOXML_REL_BASES = ["http://schemas.openxmlformats.org/officeDocument/2006/relationships/", "http://purl.oclc.org/ooxml/officeDocument/relationships/"];
+/**
+* Whether a relationship `type` URI names the OOXML relationship `name` (e.g.
+* `'officeDocument'`), matching against both the Transitional
+* (`schemas.openxmlformats.org`) and Strict (`purl.oclc.org`) base URIs.
+*/
 function isOoxmlRel(type, name) {
 	return OOXML_REL_BASES.some((base) => type === base + name);
 }

package/dist/esm/core/opc/relationships.d.ts

@@ -1,7 +1,19 @@
+/**
+ * One `<Relationship>` (ECMA-376 Part 2 §9.3): its id, Type URI, target, and
+ * whether the target is package-`Internal` or `External` (defaults to Internal
+ * when the attribute is absent).
+ */
 export interface Relationship {
     readonly id: string;
     readonly type: string;
     readonly target: string;
     readonly targetMode: 'Internal' | 'External';
 }
+/**
+ * Parse a relationships part (`_rels/*.rels`) into {@link Relationship}s.
+ * Tolerates a namespace prefix on the elements; returns `[]` when there are no
+ * relationships.
+ *
+ * @throws Error when a `<Relationship>` lacks a required `Id`/`Type`/`Target`.
+ */
 export declare function parseRelationships(data: Uint8Array): Array<Relationship>;

package/dist/esm/core/opc/relationships.js

@@ -9,6 +9,13 @@ var parser = new XMLParser({
 	removeNSPrefix: true,
 	isArray: (tagName) => tagName === "Relationship"
 });
+/**
+* Parse a relationships part (`_rels/*.rels`) into {@link Relationship}s.
+* Tolerates a namespace prefix on the elements; returns `[]` when there are no
+* relationships.
+*
+* @throws Error when a `<Relationship>` lacks a required `Id`/`Type`/`Target`.
+*/
 function parseRelationships(data) {
 	const xml = decoder.decode(data);
 	const list = parser.parse(xml).Relationships?.Relationship;

package/dist/esm/core/po-helpers.d.ts

@@ -1,16 +1,54 @@
+/**
+ * One element node in a fast-xml-parser `preserveOrder` tree: a record with a
+ * single tag-name key (its children) plus an optional `:@` attributes object.
+ */
 export type PoNode = Record<string, unknown>;
+/** An ordered list of sibling {@link PoNode}s (the parser's array form). */
 export type PoTree = ReadonlyArray<PoNode>;
+/** The element's tag name (the one key that is neither `:@` nor `#text`), or undefined. */
 export declare function poTag(node: PoNode | undefined): string | undefined;
+/** Whether the node's tag equals `tag` exactly (prefix-sensitive). */
 export declare function poIs(node: PoNode | undefined, tag: string): boolean;
+/** The node's child elements (the value under its tag key), or `[]`. */
 export declare function poChildren(node: PoNode | undefined): ReadonlyArray<PoNode>;
+/** The node's direct children with tag `tag`. */
 export declare function poChildrenWith(node: PoNode | undefined, tag: string): Array<PoNode>;
+/** The node's first direct child with tag `tag`, or undefined. */
 export declare function poFirstChild(node: PoNode | undefined, tag: string): PoNode | undefined;
+/**
+ * An attribute value by local `name`, trying the common OOXML namespace prefixes
+ * (`w:`/`r:`/`m:`/`xml:`, then bare) in priority order. Returns undefined when
+ * absent or non-string.
+ */
 export declare function poAttr(node: PoNode | undefined, name: string): string | undefined;
+/**
+ * Like `poAttr` but matches by LOCAL name regardless of the prefix — for vendor
+ * extensions whose namespace `poAttr` does not special-case (e.g. `w14:paraId`,
+ * `w15:done`, `w15:paraIdParent`).
+ */
 export declare function poAttrLocal(node: PoNode | undefined, name: string): string | undefined;
+/**
+ * Like `poIs` but matches a tag by LOCAL name, so an element authored under any
+ * prefix (`w15:commentsEx`, `mc:commentsEx`, …) still resolves.
+ */
 export declare function poIsLocal(node: PoNode | undefined, name: string): boolean;
+/** {@link poAttr} parsed as a finite number, or undefined when absent/non-numeric. */
 export declare function poIntAttr(node: PoNode | undefined, name: string): number | undefined;
+/** Shorthand for the `val` attribute (`@w:val`/…). */
 export declare function poVal(node: PoNode | undefined): string | undefined;
+/**
+ * Read an OOXML boolean toggle property (§17.17.4): a present element with no
+ * `val` (or `val` true/1/on) is `true`; `false`/`0`/`off` is `false`; an absent
+ * element (`node` undefined) is undefined ("inherit").
+ */
 export declare function poToggle(node: PoNode | undefined): boolean | undefined;
+/** Concatenate the node's direct `#text` leaf children into a single string. */
 export declare function poText(node: PoNode | undefined): string;
+/**
+ * Walk a chain of tags from the tree root, descending into the first child that
+ * matches each successive `path` segment. Returns the node at the path end, or
+ * undefined if any segment is missing.
+ */
 export declare function poFindByPath(tree: PoTree, path: ReadonlyArray<string>): PoNode | undefined;
+/** Depth-first search for the first descendant with the given `tag`. */
 export declare function poFindDescendant(node: PoNode | undefined, tag: string): PoNode | undefined;

package/dist/esm/core/po-helpers.js

@@ -1,25 +1,35 @@
 //#region src/core/po-helpers.ts
 var ATTRS_KEY = ":@";
 var TEXT_KEY = "#text";
+/** The element's tag name (the one key that is neither `:@` nor `#text`), or undefined. */
 function poTag(node) {
 	if (!node || typeof node !== "object") return void 0;
 	for (const key of Object.keys(node)) if (key !== ATTRS_KEY && key !== TEXT_KEY) return key;
 }
+/** Whether the node's tag equals `tag` exactly (prefix-sensitive). */
 function poIs(node, tag) {
 	return poTag(node) === tag;
 }
+/** The node's child elements (the value under its tag key), or `[]`. */
 function poChildren(node) {
 	const tag = poTag(node);
 	if (!tag || !node) return [];
 	const arr = node[tag];
 	return Array.isArray(arr) ? arr : [];
 }
+/** The node's direct children with tag `tag`. */
 function poChildrenWith(node, tag) {
 	return poChildren(node).filter((c) => poIs(c, tag));
 }
+/** The node's first direct child with tag `tag`, or undefined. */
 function poFirstChild(node, tag) {
 	return poChildren(node).find((c) => poIs(c, tag));
 }
+/**
+* An attribute value by local `name`, trying the common OOXML namespace prefixes
+* (`w:`/`r:`/`m:`/`xml:`, then bare) in priority order. Returns undefined when
+* absent or non-string.
+*/
 function poAttr(node, name) {
 	if (!node || typeof node !== "object") return void 0;
 	const attrs = node[ATTRS_KEY];
@@ -28,6 +38,11 @@ function poAttr(node, name) {
 	const v = a[`@_w:${name}`] ?? a[`@_r:${name}`] ?? a[`@_m:${name}`] ?? a[`@_xml:${name}`] ?? a[`@_${name}`];
 	return typeof v === "string" ? v : void 0;
 }
+/**
+* Like `poAttr` but matches by LOCAL name regardless of the prefix — for vendor
+* extensions whose namespace `poAttr` does not special-case (e.g. `w14:paraId`,
+* `w15:done`, `w15:paraIdParent`).
+*/
 function poAttrLocal(node, name) {
 	if (!node || typeof node !== "object") return void 0;
 	const attrs = node[ATTRS_KEY];
@@ -37,25 +52,37 @@ function poAttrLocal(node, name) {
 		if (k.slice(2).split(":").pop() === name && typeof v === "string") return v;
 	}
 }
+/**
+* Like `poIs` but matches a tag by LOCAL name, so an element authored under any
+* prefix (`w15:commentsEx`, `mc:commentsEx`, …) still resolves.
+*/
 function poIsLocal(node, name) {
 	const tag = poTag(node);
 	return tag !== void 0 && (tag === name || tag.split(":").pop() === name);
 }
+/** {@link poAttr} parsed as a finite number, or undefined when absent/non-numeric. */
 function poIntAttr(node, name) {
 	const v = poAttr(node, name);
 	if (v === void 0) return void 0;
 	const n = Number(v);
 	return Number.isFinite(n) ? n : void 0;
 }
+/** Shorthand for the `val` attribute (`@w:val`/…). */
 function poVal(node) {
 	return poAttr(node, "val");
 }
+/**
+* Read an OOXML boolean toggle property (§17.17.4): a present element with no
+* `val` (or `val` true/1/on) is `true`; `false`/`0`/`off` is `false`; an absent
+* element (`node` undefined) is undefined ("inherit").
+*/
 function poToggle(node) {
 	if (!node) return void 0;
 	const v = poAttr(node, "val");
 	if (v === void 0) return true;
 	return !(v === "false" || v === "0" || v === "off");
 }
+/** Concatenate the node's direct `#text` leaf children into a single string. */
 function poText(node) {
 	if (!node) return "";
 	const children = poChildren(node);
@@ -67,6 +94,11 @@ function poText(node) {
 	}
 	return out;
 }
+/**
+* Walk a chain of tags from the tree root, descending into the first child that
+* matches each successive `path` segment. Returns the node at the path end, or
+* undefined if any segment is missing.
+*/
 function poFindByPath(tree, path) {
 	let cursor = tree;
 	let current;
@@ -77,6 +109,7 @@ function poFindByPath(tree, path) {
 	}
 	return current;
 }
+/** Depth-first search for the first descendant with the given `tag`. */
 function poFindDescendant(node, tag) {
 	if (!node) return void 0;
 	for (const child of poChildren(node)) {