reamkit 1.15.1 → 1.15.3

package/dist/esm/core/arc-to-bezier.d.ts

@@ -1,5 +1,28 @@
 import { PathSegment } from './vector.js';
+/**
+ * Point on an axis-aligned ellipse at angle θ (radians, CCW from +x): returns
+ * `[cx + rx·cosθ, cy + ry·sinθ]`.
+ */
 export declare function arcPoint(cx: number, cy: number, rx: number, ry: number, angleRad: number): readonly [number, number];
+/**
+ * Decompose an arc into cubic segments, ≤90° each. Returns ONLY `cubic`
+ * segments — the pen is assumed to already sit at the arc's start point
+ * (`arcPoint(..., startAngleRad)`); the caller emits a leading move/line.
+ * Degenerate input (non-positive radius or zero sweep) yields no segments,
+ * so no NaN can reach the serializer.
+ *
+ * @param startAngleRad Start angle in radians (CCW from +x).
+ * @param sweepAngleRad Signed angular extent in radians (sign = winding direction).
+ */
 export declare function arcToBeziers(cx: number, cy: number, rx: number, ry: number, startAngleRad: number, sweepAngleRad: number): Array<PathSegment>;
+/**
+ * Full ellipse inscribed in the `(0,0)`–`(w,h)` box, as a closed path. Starts at
+ * the rightmost point and sweeps a full turn CCW.
+ */
 export declare function ellipseSegments(w: number, h: number): ReadonlyArray<PathSegment>;
+/**
+ * Rounded rectangle in the `(0,0)`–`(w,h)` box (y-up) with uniform corner radius
+ * `r` (clamped to half the shorter side). Traversed CCW: bottom edge → BR corner
+ * → right edge → TR corner → top edge → TL corner → left edge → BL corner.
+ */
 export declare function roundRectSegments(w: number, h: number, r: number): ReadonlyArray<PathSegment>;

package/dist/esm/core/arc-to-bezier.js

@@ -1,8 +1,22 @@
 import { PathBuilder } from "./vector.js";
 //#region src/core/arc-to-bezier.ts
+/**
+* Point on an axis-aligned ellipse at angle θ (radians, CCW from +x): returns
+* `[cx + rx·cosθ, cy + ry·sinθ]`.
+*/
 function arcPoint(cx, cy, rx, ry, angleRad) {
 	return [cx + rx * Math.cos(angleRad), cy + ry * Math.sin(angleRad)];
 }
+/**
+* Decompose an arc into cubic segments, ≤90° each. Returns ONLY `cubic`
+* segments — the pen is assumed to already sit at the arc's start point
+* (`arcPoint(..., startAngleRad)`); the caller emits a leading move/line.
+* Degenerate input (non-positive radius or zero sweep) yields no segments,
+* so no NaN can reach the serializer.
+*
+* @param startAngleRad Start angle in radians (CCW from +x).
+* @param sweepAngleRad Signed angular extent in radians (sign = winding direction).
+*/
 function arcToBeziers(cx, cy, rx, ry, startAngleRad, sweepAngleRad) {
 	const segments = [];
 	if (!(rx > 0) || !(ry > 0) || sweepAngleRad === 0 || !Number.isFinite(sweepAngleRad)) return segments;
@@ -29,6 +43,10 @@ function arcToBeziers(cx, cy, rx, ry, startAngleRad, sweepAngleRad) {
 	}
 	return segments;
 }
+/**
+* Full ellipse inscribed in the `(0,0)`–`(w,h)` box, as a closed path. Starts at
+* the rightmost point and sweeps a full turn CCW.
+*/
 function ellipseSegments(w, h) {
 	const rx = w / 2;
 	const ry = h / 2;
@@ -37,6 +55,11 @@ function ellipseSegments(w, h) {
 	const start = arcPoint(cx, cy, rx, ry, 0);
 	return new PathBuilder().moveTo(start[0], start[1]).append(arcToBeziers(cx, cy, rx, ry, 0, 2 * Math.PI)).close().build().segments;
 }
+/**
+* Rounded rectangle in the `(0,0)`–`(w,h)` box (y-up) with uniform corner radius
+* `r` (clamped to half the shorter side). Traversed CCW: bottom edge → BR corner
+* → right edge → TR corner → top edge → TL corner → left edge → BL corner.
+*/
 function roundRectSegments(w, h, r) {
 	const rr = Math.max(0, Math.min(r, Math.min(w, h) / 2));
 	const b = new PathBuilder();

package/dist/esm/core/bidi/algorithm.d.ts

@@ -1,9 +1,35 @@
 import { BidiClass } from './char-types.js';
+/** Base paragraph direction: explicit `'ltr'`/`'rtl'`, or `'auto'` to derive it from the first strong character (P2/P3). */
 export type Direction = 'ltr' | 'rtl' | 'auto';
+/** The result of {@link computeBidi}: per-code-point embedding levels, the paragraph base level, and the final working types. */
 export interface BidiResult {
+    /** One entry per input code point. */
     readonly levels: ReadonlyArray<number>;
+    /** The resolved paragraph embedding level (0 = LTR, 1 = RTL). */
     readonly paragraphLevel: number;
+    /** Working types after all resolution (useful for tests / debugging). */
     readonly types: ReadonlyArray<BidiClass>;
 }
+/**
+ * Run the full UAX #9 Bidirectional Algorithm over a sequence of code points and
+ * return the resolved embedding levels. Applies, in order: P2/P3 (paragraph
+ * level), X1–X8 (explicit levels & directions, including isolates), X9 (remove
+ * explicit format/BN chars from rule processing), X10/BD13 (isolating run
+ * sequences), W1–W7, N0–N2, I1–I2 and L1. L2 reordering is left to the caller
+ * via {@link reorderVisual}.
+ *
+ * @param codePoints The paragraph's code points, in logical order.
+ * @param dir        The base direction; `'auto'` derives the paragraph level from
+ *                   the first strong character.
+ * @returns The {@link BidiResult} (levels, paragraph level, final working types).
+ */
 export declare function computeBidi(codePoints: ReadonlyArray<number>, dir: Direction): BidiResult;
+/**
+ * Rule L2 — given the resolved levels for a (sub)range, return the visual order
+ * as a permutation `visual[k] = logical index`. Reverses contiguous runs from the
+ * highest level down to the lowest odd level.
+ *
+ * @param levels One resolved embedding level per position, in logical order.
+ * @returns The visual order as a permutation where `result[k]` is the logical index at visual position `k`.
+ */
 export declare function reorderVisual(levels: ReadonlyArray<number>): Array<number>;

package/dist/esm/core/bidi/algorithm.js

@@ -25,6 +25,19 @@ function computeBaseLevel(types, start, end) {
 	}
 	return 0;
 }
+/**
+* Run the full UAX #9 Bidirectional Algorithm over a sequence of code points and
+* return the resolved embedding levels. Applies, in order: P2/P3 (paragraph
+* level), X1–X8 (explicit levels & directions, including isolates), X9 (remove
+* explicit format/BN chars from rule processing), X10/BD13 (isolating run
+* sequences), W1–W7, N0–N2, I1–I2 and L1. L2 reordering is left to the caller
+* via {@link reorderVisual}.
+*
+* @param codePoints The paragraph's code points, in logical order.
+* @param dir        The base direction; `'auto'` derives the paragraph level from
+*                   the first strong character.
+* @returns The {@link BidiResult} (levels, paragraph level, final working types).
+*/
 function computeBidi(codePoints, dir) {
 	const n = codePoints.length;
 	const origTypes = new Array(n);
@@ -421,6 +434,14 @@ function applyL1(origTypes, types, levels, paragraphLevel) {
 		j--;
 	}
 }
+/**
+* Rule L2 — given the resolved levels for a (sub)range, return the visual order
+* as a permutation `visual[k] = logical index`. Reverses contiguous runs from the
+* highest level down to the lowest odd level.
+*
+* @param levels One resolved embedding level per position, in logical order.
+* @returns The visual order as a permutation where `result[k]` is the logical index at visual position `k`.
+*/
 function reorderVisual(levels) {
 	const n = levels.length;
 	const order = Array.from({ length: n }, (_, i) => i);

package/dist/esm/core/bidi/char-types.d.ts

@@ -1,2 +1,19 @@
+/**
+ * Unicode UAX #9 Bidi_Class values, grouped as in the spec: strong (`L`, `R`,
+ * `AL`), weak (`EN`/`ES`/`ET`/`AN`/`CS`/`NSM`/`BN`), neutral (`B`/`S`/`WS`/`ON`)
+ * and explicit formatting (`LRE`…`PDI`). Only the classes used by the scripts we
+ * target (Latin, Hebrew, Arabic) plus the shared punctuation/format characters
+ * are produced; everything else defaults to `L`.
+ */
 export type BidiClass = 'L' | 'R' | 'AL' | 'EN' | 'ES' | 'ET' | 'AN' | 'CS' | 'NSM' | 'BN' | 'B' | 'S' | 'WS' | 'ON' | 'LRE' | 'LRO' | 'RLE' | 'RLO' | 'PDF' | 'LRI' | 'RLI' | 'FSI' | 'PDI';
+/**
+ * Classify a code point into its UAX #9 {@link BidiClass}. Explicit single code
+ * points are checked first (highest precedence), then the ordered, non-overlapping
+ * ranges (first match wins). Code points outside every listed range default to
+ * `L`, the correct default for the CJK / symbol / private-use blocks we do not
+ * yet shape specially.
+ *
+ * @param cp The Unicode code point.
+ * @returns The character's bidirectional class.
+ */
 export declare function bidiClass(cp: number): BidiClass;

package/dist/esm/core/bidi/char-types.js

@@ -429,6 +429,16 @@ var RANGES = [
 		cls: "ON"
 	}
 ];
+/**
+* Classify a code point into its UAX #9 {@link BidiClass}. Explicit single code
+* points are checked first (highest precedence), then the ordered, non-overlapping
+* ranges (first match wins). Code points outside every listed range default to
+* `L`, the correct default for the CJK / symbol / private-use blocks we do not
+* yet shape specially.
+*
+* @param cp The Unicode code point.
+* @returns The character's bidirectional class.
+*/
 function bidiClass(cp) {
 	const single = SINGLE.get(cp);
 	if (single !== void 0) return single;

package/dist/esm/core/bidi/index.d.ts

@@ -3,14 +3,56 @@ export type { Direction, BidiResult } from './algorithm.js';
 export type { BidiClass } from './char-types.js';
 export { computeBidi, reorderVisual } from './algorithm.js';
 export { bidiClass } from './char-types.js';
+/** The result of {@link analyzeString}: per-code-point embedding levels for a string plus its paragraph base level. */
 export interface StringBidi {
+    /**
+     * Embedding level per *code point* (not per UTF-16 unit). Index aligns with
+     * `[...string]` iteration order.
+     */
     readonly levels: ReadonlyArray<number>;
+    /** The string's code points, in logical order (parallel to `levels`). */
     readonly codePoints: ReadonlyArray<number>;
+    /** The resolved paragraph embedding level (0 = LTR, 1 = RTL). */
     readonly paragraphLevel: number;
 }
+/**
+ * Run the UAX #9 algorithm over a string, returning per-code-point embedding
+ * levels and the paragraph base level. Iterates by code point so surrogate pairs
+ * stay intact and the result indices align with `[...text]`.
+ *
+ * @param text The paragraph text.
+ * @param dir  The base direction; `'auto'` (the default) derives it from the
+ *             first strong character (P2/P3).
+ * @returns The {@link StringBidi} levels for `text`.
+ */
 export declare function analyzeString(text: string, dir?: Direction): StringBidi;
+/**
+ * Whether a string contains any character that could trigger RTL reordering
+ * (`R` or `AL` strong types, or Arabic/Hebrew presentation forms). Used as a fast
+ * gate so pure-LTR paragraphs skip the BiDi machinery entirely.
+ *
+ * @param text The string to scan.
+ * @returns `true` if any code point falls in the Hebrew/Arabic/Syriac/Thaana/NKo
+ *          or Arabic presentation-form ranges.
+ */
 export declare function hasBidiCharacters(text: string): boolean;
+/**
+ * Reverse a string by code point (so surrogate pairs stay intact). Used to emit
+ * an RTL run's glyphs in visual (right-to-left) order, since our glyph placement
+ * advances left-to-right.
+ *
+ * @param text The string to reverse.
+ * @returns `text` with its code points in reverse order.
+ */
 export declare function reverseByCodePoint(text: string): string;
+/**
+ * Given the embedding levels for a contiguous array of *tokens* (each token
+ * carrying a single resolved level), return the visual order as a permutation of
+ * token indices. A thin token-granularity wrapper over {@link reorderVisual} (L2).
+ *
+ * @param tokenLevels One resolved embedding level per token, in logical order.
+ * @returns The visual order as a permutation where `result[k]` is the logical token index.
+ */
 export declare function reorderTokens(tokenLevels: ReadonlyArray<number>): Array<number>;
 export { segmentLevels } from './segments.js';
 export type { BidiSegment } from './segments.js';

package/dist/esm/core/bidi/index.js

@@ -2,6 +2,16 @@ import "./char-types.js";
 import { computeBidi } from "./algorithm.js";
 import "./segments.js";
 //#region src/core/bidi/index.ts
+/**
+* Run the UAX #9 algorithm over a string, returning per-code-point embedding
+* levels and the paragraph base level. Iterates by code point so surrogate pairs
+* stay intact and the result indices align with `[...text]`.
+*
+* @param text The paragraph text.
+* @param dir  The base direction; `'auto'` (the default) derives it from the
+*             first strong character (P2/P3).
+* @returns The {@link StringBidi} levels for `text`.
+*/
 function analyzeString(text, dir = "auto") {
 	const codePoints = [];
 	for (const ch of text) codePoints.push(ch.codePointAt(0));
@@ -12,6 +22,15 @@ function analyzeString(text, dir = "auto") {
 		paragraphLevel
 	};
 }
+/**
+* Whether a string contains any character that could trigger RTL reordering
+* (`R` or `AL` strong types, or Arabic/Hebrew presentation forms). Used as a fast
+* gate so pure-LTR paragraphs skip the BiDi machinery entirely.
+*
+* @param text The string to scan.
+* @returns `true` if any code point falls in the Hebrew/Arabic/Syriac/Thaana/NKo
+*          or Arabic presentation-form ranges.
+*/
 function hasBidiCharacters(text) {
 	for (const ch of text) {
 		const cp = ch.codePointAt(0);
@@ -19,6 +38,14 @@ function hasBidiCharacters(text) {
 	}
 	return false;
 }
+/**
+* Reverse a string by code point (so surrogate pairs stay intact). Used to emit
+* an RTL run's glyphs in visual (right-to-left) order, since our glyph placement
+* advances left-to-right.
+*
+* @param text The string to reverse.
+* @returns `text` with its code points in reverse order.
+*/
 function reverseByCodePoint(text) {
 	return [...text].reverse().join("");
 }

package/dist/esm/core/bidi/segments.d.ts

@@ -1,6 +1,28 @@
+/**
+ * One piece of a paragraph handed to {@link segmentLevels}: a plain text run, or
+ * an atomic object (inline image / math box). A segment may carry a run-level
+ * direction override, applied via explicit RLE/LRE…PDF wrapping.
+ */
 export interface BidiSegment {
+    /** Text content; ignored when `object` is true. */
     readonly text: string;
+    /** Atomic neutral object (inline image / math box) — counts as ONE position. */
     readonly object?: boolean;
+    /** Run-level direction override (`w:rtl`). */
     readonly rtl?: boolean;
 }
+/**
+ * Resolve UAX #9 embedding levels for a paragraph described as a flat list of
+ * {@link BidiSegment}s, returning one level per "real" position: one per text
+ * code point, one per object. Carries the explicit-formatting protocol: an `rtl`
+ * segment is wrapped in RLE…PDF (an LTR segment inside an RTL paragraph in
+ * LRE…PDF) so run-level direction overrides neutral resolution, and each object
+ * participates as U+FFFC (Object Replacement Character). The inserted control
+ * characters are not reflected in the output — their levels are projected back
+ * onto the real positions only.
+ *
+ * @param segments The paragraph's segments, in logical order.
+ * @param baseDir  The paragraph base direction.
+ * @returns One embedding level per real position (text code point or object).
+ */
 export declare function segmentLevels(segments: ReadonlyArray<BidiSegment>, baseDir: 'ltr' | 'rtl'): Array<number>;

package/dist/esm/core/bidi/segments.js

@@ -4,6 +4,20 @@ var OBJECT_REPLACEMENT = 65532;
 var RLE = 8235;
 var PDF_FMT = 8236;
 var LRE = 8234;
+/**
+* Resolve UAX #9 embedding levels for a paragraph described as a flat list of
+* {@link BidiSegment}s, returning one level per "real" position: one per text
+* code point, one per object. Carries the explicit-formatting protocol: an `rtl`
+* segment is wrapped in RLE…PDF (an LTR segment inside an RTL paragraph in
+* LRE…PDF) so run-level direction overrides neutral resolution, and each object
+* participates as U+FFFC (Object Replacement Character). The inserted control
+* characters are not reflected in the output — their levels are projected back
+* onto the real positions only.
+*
+* @param segments The paragraph's segments, in logical order.
+* @param baseDir  The paragraph base direction.
+* @returns One embedding level per real position (text code point or object).
+*/
 function segmentLevels(segments, baseDir) {
 	const bidiCps = [];
 	const realIndexOfBidi = [];

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

@@ -1,2 +1,22 @@
+/**
+ * Base64-encode raw bytes for `data:` URIs (the svg + html writers). `btoa` is
+ * available in browsers, workers and Node 16+; chunking keeps the intermediate
+ * binary string small.
+ */
 export declare function toBase64(bytes: Uint8Array): string;
+/**
+ * Naive scan for an ASCII `needle` inside raw `haystack` bytes — used by reader
+ * sniffs to spot OPC part names (e.g. `'word/document.xml'`) without unzipping.
+ */
+/**
+ * Scan raw package bytes for an OPC part name (e.g. `'xl/workbook.xml'`)
+ * without unzipping — the reader sniffs' cheap format probe. Accepts both the
+ * spec's `/` separator and the `\` that Windows producers write.
+ */
+export declare function bytesIncludePartName(haystack: Uint8Array, partName: string): boolean;
+/**
+ * Naive scan for an ASCII `needle` inside raw `haystack` bytes. Prefer
+ * {@link bytesIncludePartName} for OPC part names — it also accepts the
+ * backslash spelling real archives use.
+ */
 export declare function bytesInclude(haystack: Uint8Array, needle: string): boolean;

package/dist/esm/core/bytes.js

@@ -1,9 +1,32 @@
 //#region src/core/bytes.ts
+/**
+* Base64-encode raw bytes for `data:` URIs (the svg + html writers). `btoa` is
+* available in browsers, workers and Node 16+; chunking keeps the intermediate
+* binary string small.
+*/
 function toBase64(bytes) {
 	let bin = "";
 	for (const b of bytes) bin += String.fromCharCode(b);
 	return btoa(bin);
 }
+/**
+* Naive scan for an ASCII `needle` inside raw `haystack` bytes — used by reader
+* sniffs to spot OPC part names (e.g. `'word/document.xml'`) without unzipping.
+*/
+/**
+* Scan raw package bytes for an OPC part name (e.g. `'xl/workbook.xml'`)
+* without unzipping — the reader sniffs' cheap format probe. Accepts both the
+* spec's `/` separator and the `\` that Windows producers write.
+*/
+function bytesIncludePartName(haystack, partName) {
+	if (bytesInclude(haystack, partName)) return true;
+	return partName.includes("/") && bytesInclude(haystack, partName.replace(/\//g, "\\"));
+}
+/**
+* Naive scan for an ASCII `needle` inside raw `haystack` bytes. Prefer
+* {@link bytesIncludePartName} for OPC part names — it also accepts the
+* backslash spelling real archives use.
+*/
 function bytesInclude(haystack, needle) {
 	const n = new TextEncoder().encode(needle);
 	outer: for (let i = 0; i + n.length <= haystack.length; i++) {
@@ -13,4 +36,4 @@ function bytesInclude(haystack, needle) {
 	return false;
 }
 //#endregion
-export { bytesInclude, toBase64 };
+export { bytesInclude, bytesIncludePartName, toBase64 };

package/dist/esm/core/converter/facade.d.ts

@@ -6,6 +6,7 @@ import { FontProvider } from '../fonts/provider.js';
 import { Loss, LossReport } from '../ir/index.js';
 import { FontBytesByVariant } from '../font/index.js';
 import { ProjectSheetOptions } from '../../excel/sheet-to-flow.js';
+/** Options for a {@link Converter.convert} call (extends the docx PDF options). */
 export interface ConvertOptions extends ConvertDocxOptions {
     /**
      * Target: 'pdf' (default), 'svg' (page-stack preview), 'html'/'docx' (flowed),
@@ -33,25 +34,61 @@ export interface ConvertOptions extends ConvertDocxOptions {
      */
     readonly fontProviders?: ReadonlyArray<FontProvider>;
 }
+/** The output of a conversion: the encoded bytes and the accumulated losses. */
 export interface ConvertResult {
+    /** The encoded output bytes (PDF / SVG / HTML / DOCX / XLSX). */
     readonly bytes: Uint8Array;
+    /** Every {@link Loss} recorded while reading the source and writing the target. */
     readonly losses: LossReport;
 }
+/**
+ * One of the source IR trees a reader yields. The render path is {@link FlowDoc},
+ * so a {@link SheetDoc} is projected to a FlowDoc at the boundary (E-SHEET SB1);
+ * the discriminant `kind` selects the projection and a FlowDoc passes through.
+ */
 export type SourceDoc = FlowDoc | SheetDoc;
+/**
+ * Normalize a {@link SourceDoc} to a {@link FlowDoc}: a {@link SheetDoc} is run
+ * through the print-model projection; a FlowDoc passes through unchanged.
+ *
+ * @param doc     The reader's native tree.
+ * @param options Projection options (e.g. the `now` reference date).
+ * @returns The flow tree the render path consumes.
+ */
 export declare function toFlowDoc(doc: SourceDoc, options?: ProjectSheetOptions): FlowDoc;
+/** A registry-driven converter: readers → layout → writers (ir-design §7). */
 export interface Converter {
     /** The registered readers, in sniffing order. */
     readonly readers: ReadonlyArray<DocumentReader<SourceDoc>>;
     /** Detect the input format by reader sniffing; undefined when unknown. */
     detect: (bytes: Uint8Array) => DocumentReader<SourceDoc> | undefined;
+    /** Read the bytes and convert them to the requested target (default `'pdf'`). */
     convert: (bytes: Uint8Array, options?: ConvertOptions) => Promise<ConvertResult>;
 }
+/** Options for {@link createConverter}. */
 export interface CreateConverterOptions {
-    /** Override / extend the reader registry (defaults to docx + xlsx). */
+    /** Override / extend the reader registry (defaults to {@link DEFAULT_READERS}). */
     readonly readers?: ReadonlyArray<DocumentReader<SourceDoc>>;
 }
+/** The built-in readers, in sniffing order: docx, doc, xlsx, xls, pptx, ppt, pdf. */
 export declare const DEFAULT_READERS: ReadonlyArray<DocumentReader<SourceDoc>>;
+/**
+ * Build a {@link Converter} over a reader registry. The async boundary (font
+ * fetching) lives here; readers and writers stay synchronous.
+ *
+ * @param opts Optional reader-registry override.
+ * @returns A converter exposing `readers`, `detect` and `convert`.
+ */
 export declare function createConverter(opts?: CreateConverterOptions): Converter;
+/**
+ * Resolve the regular/bold/italic/bold-italic variants of the document-default
+ * family through a {@link FontProvider} chain. A `remote` or `local` winner is
+ * reported as a substitution {@link Loss}.
+ *
+ * @param providers The provider chain, highest priority first.
+ * @returns The resolved font bytes (present when the regular variant resolves)
+ *          and an optional substitution loss.
+ */
 export declare function resolveFontsViaChain(providers: ReadonlyArray<FontProvider>): Promise<{
     fonts?: FontBytesByVariant;
     loss?: Loss;

package/dist/esm/core/converter/facade.js

@@ -22,6 +22,14 @@ import { xlsReader } from "../../excel/xls/xls-reader.js";
 import { pptReader } from "../../pptx/ppt/ppt-reader.js";
 import { pdfReader } from "../../pdf-reader/reader.js";
 //#region src/core/converter/facade.ts
+/**
+* Normalize a {@link SourceDoc} to a {@link FlowDoc}: a {@link SheetDoc} is run
+* through the print-model projection; a FlowDoc passes through unchanged.
+*
+* @param doc     The reader's native tree.
+* @param options Projection options (e.g. the `now` reference date).
+* @returns The flow tree the render path consumes.
+*/
 function toFlowDoc(doc, options = {}) {
 	return doc.kind === "sheet" ? projectSheetDoc(doc, options) : doc;
 }
@@ -32,6 +40,7 @@ function readToFlow(reader, bytes, options = {}) {
 		losses
 	};
 }
+/** The built-in readers, in sniffing order: docx, doc, xlsx, xls, pptx, ppt, pdf. */
 var DEFAULT_READERS = [
 	docxReader,
 	docReader,
@@ -41,6 +50,13 @@ var DEFAULT_READERS = [
 	pptReader,
 	pdfReader
 ];
+/**
+* Build a {@link Converter} over a reader registry. The async boundary (font
+* fetching) lives here; readers and writers stay synchronous.
+*
+* @param opts Optional reader-registry override.
+* @returns A converter exposing `readers`, `detect` and `convert`.
+*/
 function createConverter(opts = {}) {
 	const readers = opts.readers ?? DEFAULT_READERS;
 	const detect = (bytes) => readers.find((r) => r.sniff(bytes));
@@ -137,6 +153,15 @@ async function renderSheetReaderToPdf(reader, bytes, conv, now) {
 		...conv.section ? { section: conv.section } : {}
 	});
 }
+/**
+* Resolve the regular/bold/italic/bold-italic variants of the document-default
+* family through a {@link FontProvider} chain. A `remote` or `local` winner is
+* reported as a substitution {@link Loss}.
+*
+* @param providers The provider chain, highest priority first.
+* @returns The resolved font bytes (present when the regular variant resolves)
+*          and an optional substitution loss.
+*/
 async function resolveFontsViaChain(providers) {
 	const chain = chainProviders(providers);
 	const ask = (bold, italic) => chain.resolve({

package/dist/esm/core/converter/project.d.ts

@@ -1,4 +1,16 @@
 import { FlowDoc } from '../ir/flow.js';
 import { StyledRenderOptions } from '../../pdf/index.js';
+/** Styled-render options projected from a {@link FlowDoc} (everything but the font `registry`). */
 export type FlowRenderOptions = Omit<StyledRenderOptions, 'registry'>;
+/**
+ * Project a {@link FlowDoc} to the {@link StyledRenderOptions} the layout/PDF path
+ * consumes (minus the font `registry`, which the caller supplies). This is the
+ * single owner of the field-by-field mapping the converters and the facade used
+ * to repeat by hand. Key presence is significant — the conditional spreads are
+ * semantics, not style.
+ *
+ * @param flow The parsed interlayer.
+ * @returns The render options, threading the document's own sections,
+ *          header/footer bands, notes, resources, charts, fonts and language.
+ */
 export declare function flowRenderOptions(flow: FlowDoc): FlowRenderOptions;

package/dist/esm/core/converter/project.js

@@ -1,6 +1,17 @@
 import { EMPTY_STYLE_SHEET } from "../style-cascade/resolver.js";
 import "../style-cascade/index.js";
 //#region src/core/converter/project.ts
+/**
+* Project a {@link FlowDoc} to the {@link StyledRenderOptions} the layout/PDF path
+* consumes (minus the font `registry`, which the caller supplies). This is the
+* single owner of the field-by-field mapping the converters and the facade used
+* to repeat by hand. Key presence is significant — the conditional spreads are
+* semantics, not style.
+*
+* @param flow The parsed interlayer.
+* @returns The render options, threading the document's own sections,
+*          header/footer bands, notes, resources, charts, fonts and language.
+*/
 function flowRenderOptions(flow) {
 	return {
 		styles: EMPTY_STYLE_SHEET,