reamkit 1.15.0 → 1.15.2

package/dist/esm/core/ir/features.d.ts

@@ -1,4 +1,11 @@
+/**
+ * A capability/loss feature name. A plain string, hierarchical via dot-segments
+ * (`'tables.nested'` ⊂ `'tables'`); the vocabulary is OPEN so third-party
+ * adapters can introduce their own. {@link FEATURES} canonicalizes the names the
+ * core uses.
+ */
 export type Feature = string;
+/** The feature names the core declares, so the docs' capability matrix is code-generated. */
 export declare const FEATURES: {
     readonly text: "text";
     readonly tables: "tables";
@@ -23,6 +30,7 @@ export declare const FEATURES: {
     readonly pdfTagged: "pdf.tagged";
     readonly pdfSignatures: "pdf.signatures";
 };
+/** Union of the canonical {@link FEATURES} values. */
 export type KnownFeature = (typeof FEATURES)[keyof typeof FEATURES];
 /** True when `feature` equals `prefix` or sits under it ('tables.nested' ⊂ 'tables'). */
 export declare function featureWithin(feature: Feature, prefix: Feature): boolean;

package/dist/esm/core/ir/features.js

@@ -1,4 +1,5 @@
 //#region src/core/ir/features.ts
+/** The feature names the core declares, so the docs' capability matrix is code-generated. */
 var FEATURES = {
 	text: "text",
 	tables: "tables",

package/dist/esm/core/ir/flow.d.ts

@@ -1,14 +1,34 @@
 import { BodyElement, Chart, Comment, DocumentInfo, Numbering, Section, SectionProperties, StyleSheet } from '../document-model/index.js';
 import { FontRegistry } from '../font/index.js';
 import { ResourceStore } from './resources.js';
+/**
+ * The semantic IR tree (ir-design §5): everything a reader extracts from the
+ * document bytes, format-neutrally — the flow `body` plus its document-scoped
+ * companions (styles, numbering, header/footer bands, notes, charts, binary
+ * resources, metadata). Caller-supplied conversion options (fonts, PDF/A
+ * profile, signature, …) are deliberately NOT part of the tree; they
+ * parameterize transforms, not the document.
+ *
+ * `body` carries FINAL effective properties — readers materialize list markers
+ * and resolve the style cascade while building it — so render projections must
+ * not re-apply `styles`/`numbering`, which remain only as round-trip material.
+ */
 export interface FlowDoc {
+    /** Discriminant for {@link SourceDoc} (a FlowDoc passes through projection). */
     readonly kind: 'flow';
+    /** The document flow content, carrying resolved, effective properties. */
     readonly body: ReadonlyArray<BodyElement>;
     /** Multi-section page geometry (docx). Empty for single-geometry sources. */
     readonly sections: ReadonlyArray<Section>;
     /** Single-section page geometry (xlsx print setup). */
     readonly section?: SectionProperties;
+    /** Resolved style sheet, kept as round-trip material (already folded into `body`). */
     readonly styles: StyleSheet;
+    /**
+     * Raw numbering definitions (round-trip material). `body` already carries the
+     * materialized list markers — readers apply numbering as a FlowDoc transform,
+     * so render projections must not re-apply it.
+     */
     readonly numbering?: Numbering;
     readonly headersFooters?: ReadonlyMap<string, ReadonlyArray<BodyElement>>;
     /** §17.11 footnotes/endnotes content by id (separator stubs excluded). */

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

@@ -6,6 +6,13 @@ export type { Feature, KnownFeature } from './features.js';
 export { FEATURES, featureWithin } from './features.js';
 export type { Loss, LossReport, LossSeverity } from './loss.js';
 export { ConversionLossError, formatLoss } from './loss.js';
+/**
+ * Passthrough bag for the round-trip door (ir-design §4): a node MAY carry the
+ * source format's raw fragment keyed by format id (e.g. `{ ooxml: <fragment> }`).
+ * Writers for other formats ignore it; a same-format writer may use it to
+ * reproduce constructs the neutral core does not model. v1 promises only
+ * cross-format fidelity — this keeps the door open without promising more.
+ */
 export interface NativeBag {
     readonly [formatId: string]: unknown;
 }

package/dist/esm/core/ir/loss.d.ts

@@ -5,18 +5,30 @@ import { Feature } from './features.js';
  * - `substituted` — content was replaced by an equivalent (e.g. font substitution).
  */
 export type LossSeverity = 'dropped' | 'degraded' | 'substituted';
+/** A single conversion loss: something the pipeline dropped, degraded or substituted. */
 export interface Loss {
+    /** How badly the content was affected. */
     readonly severity: LossSeverity;
+    /** The affected {@link Feature} (drives the capability/loss matrix). */
     readonly feature: Feature;
     /** Human-readable specifics: what exactly happened to what. */
     readonly detail: string;
     /** Optional location hint (page/paragraph/sheet reference). */
     readonly where?: string;
 }
+/** An ordered, read-only list of {@link Loss} entries, returned alongside the output. */
 export type LossReport = ReadonlyArray<Loss>;
+/**
+ * Format a {@link Loss} as one human-readable line, e.g.
+ * `[degraded] charts at sheet "Q3": gradient flattened`.
+ *
+ * @param loss The loss to format.
+ * @returns The one-line description.
+ */
 export declare function formatLoss(loss: Loss): string;
 /** Thrown by strict-mode conversions on the first recorded loss. */
 export declare class ConversionLossError extends Error {
     readonly loss: Loss;
+    /** @param loss The first loss that tripped strict mode (retained on the error). */
     constructor(loss: Loss);
 }

package/dist/esm/core/ir/loss.js

@@ -1,10 +1,18 @@
 //#region src/core/ir/loss.ts
+/**
+* Format a {@link Loss} as one human-readable line, e.g.
+* `[degraded] charts at sheet "Q3": gradient flattened`.
+*
+* @param loss The loss to format.
+* @returns The one-line description.
+*/
 function formatLoss(loss) {
 	const where = loss.where ? ` at ${loss.where}` : "";
 	return `[${loss.severity}] ${loss.feature}${where}: ${loss.detail}`;
 }
 /** Thrown by strict-mode conversions on the first recorded loss. */
 var ConversionLossError = class extends Error {
+	/** @param loss The first loss that tripped strict mode (retained on the error). */
 	constructor(loss) {
 		super(`strict conversion failed — ${formatLoss(loss)}`);
 		this.loss = loss;

package/dist/esm/core/ir/resources.d.ts

@@ -1,6 +1,14 @@
+/** A content-addressed id for a binary resource held in a {@link ResourceStore}. */
 export type ResourceId = string & {
     readonly __brand: 'resource-id';
 };
+/**
+ * A content-addressed store for the IR's binary payloads (images, fonts). IR
+ * trees stay pure JSON and reference bytes by {@link ResourceId}; ids derive
+ * from the bytes (a synchronous 64-bit FNV-1a), so identical payloads
+ * deduplicate for free and equal documents get equal ids — which keeps IR-level
+ * diffs and the byte-identical gates meaningful.
+ */
 export declare class ResourceStore {
     private readonly byId;
     /**
@@ -9,8 +17,12 @@ export declare class ResourceStore {
      * different bytes probes deterministic `~n` suffixes.
      */
     put(bytes: Uint8Array): ResourceId;
+    /** Look up the bytes for an id, or `undefined` when absent. */
     get(id: ResourceId): Uint8Array | undefined;
+    /** Whether an id is present in the store. */
     has(id: ResourceId): boolean;
+    /** All stored ids, in insertion order. */
     ids(): ReadonlyArray<ResourceId>;
+    /** The number of distinct resources stored. */
     get size(): number;
 }

package/dist/esm/core/ir/resources.js

@@ -14,6 +14,13 @@ function equalBytes(x, y) {
 	for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
 	return true;
 }
+/**
+* A content-addressed store for the IR's binary payloads (images, fonts). IR
+* trees stay pure JSON and reference bytes by {@link ResourceId}; ids derive
+* from the bytes (a synchronous 64-bit FNV-1a), so identical payloads
+* deduplicate for free and equal documents get equal ids — which keeps IR-level
+* diffs and the byte-identical gates meaningful.
+*/
 var ResourceStore = class {
 	byId = /* @__PURE__ */ new Map();
 	/**
@@ -33,15 +40,19 @@ var ResourceStore = class {
 			if (equalBytes(existing, bytes)) return id;
 		}
 	}
+	/** Look up the bytes for an id, or `undefined` when absent. */
 	get(id) {
 		return this.byId.get(id);
 	}
+	/** Whether an id is present in the store. */
 	has(id) {
 		return this.byId.has(id);
 	}
+	/** All stored ids, in insertion order. */
 	ids() {
 		return [...this.byId.keys()];
 	}
+	/** The number of distinct resources stored. */
 	get size() {
 		return this.byId.size;
 	}

package/dist/esm/core/ir/sheet.d.ts

@@ -1,65 +1,146 @@
 import { Chart, DocumentInfo, ShapeBlock } from '../document-model/index.js';
 import { DefinedName, MergedRange, ParsedWorksheet, SheetRichRun, XlsxStyles } from '../spreadsheet-model/index.js';
 import { ResourceId, ResourceStore } from './resources.js';
+/**
+ * §20.5 SpreadsheetDrawingML — a chart frame anchored over a sheet's grid,
+ * already sized from its two-cell anchor. `chartPartPath` keys into
+ * {@link SheetDoc.chartData} for the resolved chart.
+ */
 export interface SheetChartRef {
     readonly chartPartPath: string;
     readonly widthPt: number;
     readonly heightPt: number;
 }
+/**
+ * §20.5.2.1 xdr:pic — a picture anchored over a sheet's grid, sized from its
+ * anchor. The bytes live in {@link SheetDoc.resources}; `resourceId` keys into
+ * it. The projection emits an ImageBlock per picture after the grid.
+ */
 export interface SheetImageRef {
     readonly resourceId: ResourceId;
     readonly widthPt: number;
     readonly heightPt: number;
 }
+/** One item (label + selection state) in a {@link SheetSlicer}. */
 export interface SheetSlicerItem {
+    /** The item's display label. */
     readonly label: string;
+    /** Whether the item is currently selected (filtered in). */
     readonly selected: boolean;
 }
+/**
+ * A slicer panel (xl/slicers + xl/slicerCaches, E-SHEET SV2) resolved against
+ * its source so the projection can render it as a captioned button box after the
+ * grid. Items + selection resolve for native-table slicers; an OLAP/pivot slicer
+ * the cache cannot resolve inline degrades to a caption-only box.
+ */
 export interface SheetSlicer {
     readonly caption: string;
     readonly columnCount: number;
     readonly items: ReadonlyArray<SheetSlicerItem>;
+    /**
+     * Resolved fills + header text colour from the slicer style name + workbook
+     * theme (the same accent heuristic as tables/pivots). Absent ⇒ a plain box.
+     */
     readonly headerHex?: string;
     readonly selectedHex?: string;
     readonly headerTextHex?: string;
     readonly selectedTextHex?: string;
 }
+/**
+ * §18.3.1.47 — a cell (or range) hyperlink resolved to an external URL (E-SHEET
+ * W3). The projection stamps `run.href` on every cell the range covers.
+ */
 export interface SheetHyperlink {
     readonly ref: MergedRange;
     readonly url: string;
 }
+/**
+ * A cell comment / note (E-SHEET W7): an A1 anchor, the resolved author display
+ * name, the text body, and whether it came from the modern threaded comments
+ * part (a conversation) or the legacy note part.
+ */
 export interface SheetComment {
     readonly ref: string;
     readonly author?: string;
     readonly text: string;
     readonly threaded: boolean;
 }
+/**
+ * A form control resolved against its ctrlProp part (E-SHEET W8): the display
+ * name, the `objectType` (CheckBox / Radio / Spin / …) and the bit of state the
+ * listing shows — `checked` for check/option buttons, `value` for
+ * spin/scroll/list controls. Render-only.
+ */
 export interface SheetFormControl {
     readonly name?: string;
     readonly objectType?: string;
     readonly checked?: boolean;
     readonly value?: number;
 }
+/**
+ * An ActiveX control resolved against its activeX part (E-SHEET W10): the control
+ * class (`type`, from the `<oleObject progId>`) plus the visible state persisted
+ * in the property bag — `caption`, `value` (checked/text/number, as a string)
+ * and OptionButton `groupName`. Render-only.
+ */
 export interface SheetActiveXControl {
     readonly type: string;
     readonly caption?: string;
     readonly value?: string;
     readonly groupName?: string;
 }
+/** One worksheet: the parsed grid plus its resolved, anchor-ordered overlays. */
 export interface Sheet {
+    /** The sheet (tab) name. */
     readonly name: string;
+    /**
+     * The grid + per-sheet geometry exactly as parsed: cells, columns, rows,
+     * merges, dimensions, pageSetup/printOptions, manual breaks, drawingRelId.
+     */
     readonly grid: ParsedWorksheet;
+    /** Chart frames on this sheet, anchor-ordered (resolved data in {@link SheetDoc.chartData}). */
     readonly charts?: ReadonlyArray<SheetChartRef>;
+    /** Picture frames on this sheet, anchor-ordered (bytes in {@link SheetDoc.resources}). */
     readonly images?: ReadonlyArray<SheetImageRef>;
+    /** Drawing shapes on this sheet (E-SHEET W2), fully resolved + anchor-ordered. */
     readonly shapes?: ReadonlyArray<ShapeBlock>;
+    /**
+     * Cell hyperlinks resolved to external URLs (E-SHEET W3); the projection sets
+     * `run.href` on covered cells. In-workbook (location-only) links are not carried.
+     */
     readonly hyperlinks?: ReadonlyArray<SheetHyperlink>;
+    /** Slicer panels on this sheet (E-SHEET SV2), rendered after the grid + charts. */
     readonly slicers?: ReadonlyArray<SheetSlicer>;
+    /**
+     * Cell comments / notes (E-SHEET W7), legacy and threaded. The projection
+     * lists them in a "Comments" section after the grid (mirroring Excel's "print
+     * comments at end of sheet"); render-only.
+     */
     readonly comments?: ReadonlyArray<SheetComment>;
+    /**
+     * Form controls on this sheet (E-SHEET W8), resolved to type + state. Listed
+     * in a "Form controls" section after the grid; render-only.
+     */
     readonly formControls?: ReadonlyArray<SheetFormControl>;
+    /**
+     * ActiveX controls on this sheet (E-SHEET W10), resolved to type + visible
+     * state. Listed in an "ActiveX controls" section after the grid; render-only.
+     */
     readonly activeXControls?: ReadonlyArray<SheetActiveXControl>;
 }
+/**
+ * The SpreadsheetML IR tree (E-SHEET): a workbook of grid {@link Sheet}s plus
+ * its workbook-scoped companions — the style table, shared-string table, defined
+ * names, date system, parsed charts, binary resources and metadata. Cells keep
+ * their RAW stored value + a style index; resolution (shared strings, number
+ * formats, the style cascade, the print model) happens at the projection
+ * boundary, never in the tree.
+ */
 export interface SheetDoc {
+    /** Discriminant for {@link SourceDoc} (projected to a FlowDoc for rendering). */
     readonly kind: 'sheet';
+    /** The workbook's worksheets, in tab order. */
     readonly sheets: ReadonlyArray<Sheet>;
     /** §18.8 workbook style table (cellXfs + fonts/fills/borders/numFmts). */
     readonly styles: XlsxStyles;

package/dist/esm/core/ir/units.d.ts

@@ -1,3 +1,10 @@
+/**
+ * The IR's one length unit: PostScript points (1/72 inch), as a branded number.
+ * Readers convert their format-native units (twips, half-points, EMU, …) to `Pt`
+ * at the boundary, and writers convert out the same way. The brand is shallow —
+ * a `Pt` is assignable to `number` so layout arithmetic reads it freely; only
+ * *constructing* one requires {@link pt} or a `*ToPt` converter.
+ */
 export type Pt = number & {
     readonly __brand: 'pt';
 };
@@ -12,5 +19,7 @@ export declare function eighthPtToPt(eighthPt: number): Pt;
 export declare function emuToPt(emu: number): Pt;
 /** CSS reference pixels: 96 px = 1 inch = 72 pt. */
 export declare function pxToPt(px: number): Pt;
+/** Inches: 1 inch = 72 pt. */
 export declare function inchToPt(inches: number): Pt;
+/** Millimetres: 25.4 mm = 1 inch = 72 pt. */
 export declare function mmToPt(mm: number): Pt;

package/dist/esm/core/ir/units.js

@@ -31,9 +31,11 @@ function emuToPt(emu) {
 function pxToPt(px) {
 	return px * .75;
 }
+/** Inches: 1 inch = 72 pt. */
 function inchToPt(inches) {
 	return inches * 72;
 }
+/** Millimetres: 25.4 mm = 1 inch = 72 pt. */
 function mmToPt(mm) {
 	return mm / 25.4 * 72;
 }

package/dist/esm/core/line-breaker/cjk.d.ts

@@ -0,0 +1,26 @@
+/** True for a "wide" CJK code point that carries inter-character break opportunities. */
+export declare function isCjkWide(cp: number): boolean;
+/** True for a wide closing punctuation / non-starter that must not start a line. */
+export declare function isCjkNoBreakBefore(cp: number): boolean;
+/** True for a wide opening punctuation that must not end a line (break after it). */
+export declare function isCjkNoBreakAfter(cp: number): boolean;
+/**
+ * Split a whitespace-free segment so each wide CJK character becomes its own
+ * piece, while non-CJK runs stay grouped. Returns the input as a single-element
+ * array when it holds no CJK — so Latin / non-CJK tokenization stays byte-identical.
+ *
+ * @param seg A run of non-whitespace text.
+ * @returns The pieces, in order.
+ */
+export declare function splitCjkSegment(seg: string): Array<string>;
+/**
+ * Whether a line may break between code point `left` (end of the piece before the
+ * boundary) and `right` (start of the piece after it). A break needs at least one
+ * wide character on the boundary, and is suppressed before a non-starter or after
+ * a non-ender.
+ *
+ * @param left  The last code point of the left piece.
+ * @param right The first code point of the right piece.
+ * @returns `true` when a break is allowed here.
+ */
+export declare function cjkBreakBetween(left: number, right: number): boolean;

package/dist/esm/core/line-breaker/cjk.js

@@ -0,0 +1,60 @@
+//#region src/core/line-breaker/cjk.ts
+/** True for a "wide" CJK code point that carries inter-character break opportunities. */
+function isCjkWide(cp) {
+	return cp >= 11904 && cp <= 12031 || cp >= 12288 && cp <= 12351 || cp >= 12352 && cp <= 12543 || cp >= 13312 && cp <= 19903 || cp >= 19968 && cp <= 40959 || cp >= 63744 && cp <= 64255 || cp >= 65280 && cp <= 65519 || cp >= 131072 && cp <= 262143;
+}
+var NO_BREAK_BEFORE = new Set([..."、。，．！？：；」』】）〕〉》｝〞〟｣‐・…‥ー〜々ゝゞ", ..."ぁぃぅぇぉっゃゅょゎァィゥェォッャュョヮ"].map((c) => c.codePointAt(0)));
+var NO_BREAK_AFTER = new Set([..."（｛「『【〔〈《〝｟"].map((c) => c.codePointAt(0)));
+/** True for a wide closing punctuation / non-starter that must not start a line. */
+function isCjkNoBreakBefore(cp) {
+	return NO_BREAK_BEFORE.has(cp);
+}
+/** True for a wide opening punctuation that must not end a line (break after it). */
+function isCjkNoBreakAfter(cp) {
+	return NO_BREAK_AFTER.has(cp);
+}
+/**
+* Split a whitespace-free segment so each wide CJK character becomes its own
+* piece, while non-CJK runs stay grouped. Returns the input as a single-element
+* array when it holds no CJK — so Latin / non-CJK tokenization stays byte-identical.
+*
+* @param seg A run of non-whitespace text.
+* @returns The pieces, in order.
+*/
+function splitCjkSegment(seg) {
+	let hasWide = false;
+	for (const ch of seg) if (isCjkWide(ch.codePointAt(0))) {
+		hasWide = true;
+		break;
+	}
+	if (!hasWide) return [seg];
+	const out = [];
+	let buf = "";
+	for (const ch of seg) if (isCjkWide(ch.codePointAt(0))) {
+		if (buf) {
+			out.push(buf);
+			buf = "";
+		}
+		out.push(ch);
+	} else buf += ch;
+	if (buf) out.push(buf);
+	return out;
+}
+/**
+* Whether a line may break between code point `left` (end of the piece before the
+* boundary) and `right` (start of the piece after it). A break needs at least one
+* wide character on the boundary, and is suppressed before a non-starter or after
+* a non-ender.
+*
+* @param left  The last code point of the left piece.
+* @param right The first code point of the right piece.
+* @returns `true` when a break is allowed here.
+*/
+function cjkBreakBetween(left, right) {
+	if (!isCjkWide(left) && !isCjkWide(right)) return false;
+	if (isCjkNoBreakAfter(left)) return false;
+	if (isCjkNoBreakBefore(right)) return false;
+	return true;
+}
+//#endregion
+export { cjkBreakBetween, isCjkWide, splitCjkSegment };

package/dist/esm/core/line-breaker/greedy.d.ts

@@ -1,2 +1,16 @@
 import { Item } from './knuth-plass.js';
+/**
+ * Break a paragraph into lines greedily (first-fit, E-PARITY FP3): each line
+ * ends at the last feasible breakpoint that still fits the target width, never
+ * looking ahead to balance the paragraph — matching Word/LibreOffice line (and
+ * page) counts under a renderer-compatibility `layoutProfile`. An over-long run
+ * with no earlier break gets an emergency break so it cannot merge forward.
+ *
+ * @param items      The box/glue/penalty stream, sharing the {@link Item} shape
+ *                   and feasibility convention of {@link breakLines}.
+ * @param lineWidths Target width: a single number (uniform) or a per-line array
+ *                   (0-based), reusing the last entry for trailing lines.
+ * @returns Indices into `items` where each line ends — the same shape
+ *          {@link breakLines} returns, so the layout consumer is identical.
+ */
 export declare function greedyBreakLines(items: ReadonlyArray<Item>, lineWidths: number | ReadonlyArray<number>): ReadonlyArray<number>;

package/dist/esm/core/line-breaker/greedy.js

@@ -1,5 +1,19 @@
 import { FORBIDDEN_BREAK } from "./knuth-plass.js";
 //#region src/core/line-breaker/greedy.ts
+/**
+* Break a paragraph into lines greedily (first-fit, E-PARITY FP3): each line
+* ends at the last feasible breakpoint that still fits the target width, never
+* looking ahead to balance the paragraph — matching Word/LibreOffice line (and
+* page) counts under a renderer-compatibility `layoutProfile`. An over-long run
+* with no earlier break gets an emergency break so it cannot merge forward.
+*
+* @param items      The box/glue/penalty stream, sharing the {@link Item} shape
+*                   and feasibility convention of {@link breakLines}.
+* @param lineWidths Target width: a single number (uniform) or a per-line array
+*                   (0-based), reusing the last entry for trailing lines.
+* @returns Indices into `items` where each line ends — the same shape
+*          {@link breakLines} returns, so the layout consumer is identical.
+*/
 function greedyBreakLines(items, lineWidths) {
 	if (items.length === 0) return [];
 	const widthFor = (line) => typeof lineWidths === "number" ? lineWidths : lineWidths[Math.min(line, lineWidths.length - 1)];

package/dist/esm/core/line-breaker/index.d.ts

@@ -1,3 +1,4 @@
 export { FORCED_BREAK, breakLines } from './knuth-plass.js';
 export { greedyBreakLines } from './greedy.js';
+export { splitCjkSegment, cjkBreakBetween, isCjkWide } from './cjk.js';
 export type { Item, BoxItem, GlueItem, PenaltyItem, BreakResult, } from './knuth-plass.js';

package/dist/esm/core/line-breaker/index.js

@@ -0,0 +1,3 @@
+import "./knuth-plass.js";
+import "./greedy.js";
+import "./cjk.js";

package/dist/esm/core/line-breaker/knuth-plass.d.ts

@@ -1,32 +1,56 @@
+/** A box: unbreakable content (a word or glyph cluster) of fixed `width`. */
 export interface BoxItem {
     readonly type: 'box';
     readonly width: number;
 }
+/** Glue: flexible inter-word space, a candidate breakpoint after a {@link BoxItem}. */
 export interface GlueItem {
     readonly type: 'glue';
+    /** Natural width. */
     readonly width: number;
+    /** How far it can expand (positive). */
     readonly stretch: number;
+    /** How far it can contract (positive). */
     readonly shrink: number;
 }
+/** A penalty: an optional breakpoint with a cost (e.g. a hyphenation point). */
 export interface PenaltyItem {
     readonly type: 'penalty';
+    /** Width added if the break is taken here (e.g. the hyphen char). */
     readonly width: number;
+    /** Break cost: negative = forced, `+Infinity` = forbidden. */
     readonly penalty: number;
+    /** True for hyphenation points — two flagged breaks in a row are penalized. */
     readonly flagged: boolean;
 }
+/** One item in the box/glue/penalty stream {@link breakLines} consumes. */
 export type Item = BoxItem | GlueItem | PenaltyItem;
+/** The output of {@link breakLines}: where each line breaks and how it stretches. */
 export interface BreakResult {
+    /**
+     * Indices into `items[]` where the line breaks happen (the last index is also
+     * the final forced break / sentinel penalty).
+     */
     readonly breaks: ReadonlyArray<number>;
+    /**
+     * Per-line adjustment ratio in `[-1, ∞)`. Used by the layout consumer to
+     * distribute extra space across the glues on each line.
+     */
     readonly ratios: ReadonlyArray<number>;
 }
+/** A penalty `≤` this forces a break here; writers push the paragraph-final break with it. */
 export declare const FORCED_BREAK = -10000;
+/** A penalty `≥` this forbids a break here (shared with the greedy breaker). */
 export declare const FORBIDDEN_BREAK = 10000;
 /**
- * Break a paragraph into lines using the Knuth-Plass total-fit algorithm.
+ * Break a paragraph into lines using the Knuth-Plass total-fit algorithm:
+ * dynamic programming over the box/glue/penalty stream that minimizes total
+ * demerits across the whole paragraph.
  *
- * `lineWidths`: either a number (uniform width) or an array indexed by line
- * (0-based). When the array is shorter than the paragraph the last entry is
- * reused for trailing lines — this matches the common case of "first line
- * different, rest the same".
+ * @param items      The box/glue/penalty stream.
+ * @param lineWidths Target width: a number (uniform) or an array indexed by line
+ *                   (0-based); a shorter array reuses its last entry for trailing
+ *                   lines (the common "first line different, rest the same" case).
+ * @returns The break indices and per-line adjustment ratios ({@link BreakResult}).
  */
 export declare function breakLines(items: ReadonlyArray<Item>, lineWidths: number | ReadonlyArray<number>): BreakResult;

package/dist/esm/core/line-breaker/knuth-plass.js

@@ -1,5 +1,7 @@
 //#region src/core/line-breaker/knuth-plass.ts
+/** A penalty `≤` this forces a break here; writers push the paragraph-final break with it. */
 var FORCED_BREAK = -1e4;
+/** A penalty `≥` this forbids a break here (shared with the greedy breaker). */
 var FORBIDDEN_BREAK = 1e4;
 var LINE_PENALTY = 10;
 var FITNESS_PENALTY = 100;
@@ -17,12 +19,15 @@ function fitnessClass(r) {
 	return FIT_VERY_LOOSE;
 }
 /**
-* Break a paragraph into lines using the Knuth-Plass total-fit algorithm.
+* Break a paragraph into lines using the Knuth-Plass total-fit algorithm:
+* dynamic programming over the box/glue/penalty stream that minimizes total
+* demerits across the whole paragraph.
 *
-* `lineWidths`: either a number (uniform width) or an array indexed by line
-* (0-based). When the array is shorter than the paragraph the last entry is
-* reused for trailing lines — this matches the common case of "first line
-* different, rest the same".
+* @param items      The box/glue/penalty stream.
+* @param lineWidths Target width: a number (uniform) or an array indexed by line
+*                   (0-based); a shorter array reuses its last entry for trailing
+*                   lines (the common "first line different, rest the same" case).
+* @returns The break indices and per-line adjustment ratios ({@link BreakResult}).
 */
 function breakLines(items, lineWidths) {
 	if (items.length === 0) return {

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

@@ -1,3 +1,22 @@
 import { BodyElement, Numbering } from '../document-model/index.js';
+/**
+ * Apply list numbering to a body as a FlowDoc transform (§17.9): walk the
+ * elements (recursing into table cells), advancing list counters and prepending
+ * each numbered paragraph's resolved marker as a leading `listMarker` run, with
+ * level-inherited indents. Shapes and charts do not advance counters. Returns the
+ * body unchanged when there is no numbering.
+ *
+ * @param body      The body elements to transform.
+ * @param numbering The parsed numbering definitions, or `undefined`.
+ * @returns A new body with markers materialized.
+ */
 export declare function applyNumbering(body: ReadonlyArray<BodyElement>, numbering: Numbering | undefined): Array<BodyElement>;
+/**
+ * Apply {@link applyNumbering} to each header/footer band independently (each
+ * gets its own counter state), keyed as in the input map.
+ *
+ * @param hf        The header/footer bodies by key, or `undefined`.
+ * @param numbering The parsed numbering definitions, or `undefined`.
+ * @returns A new map with numbering applied (empty when `hf` is empty/absent).
+ */
 export declare function applyNumberingToHeadersFooters(hf: ReadonlyMap<string, ReadonlyArray<BodyElement>> | undefined, numbering: Numbering | undefined): ReadonlyMap<string, ReadonlyArray<BodyElement>>;

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

@@ -1,5 +1,16 @@
 import { NumberingState } from "./state.js";
 //#region src/core/numbering/apply.ts
+/**
+* Apply list numbering to a body as a FlowDoc transform (§17.9): walk the
+* elements (recursing into table cells), advancing list counters and prepending
+* each numbered paragraph's resolved marker as a leading `listMarker` run, with
+* level-inherited indents. Shapes and charts do not advance counters. Returns the
+* body unchanged when there is no numbering.
+*
+* @param body      The body elements to transform.
+* @param numbering The parsed numbering definitions, or `undefined`.
+* @returns A new body with markers materialized.
+*/
 function applyNumbering(body, numbering) {
 	if (!numbering || numbering.abstractNums.size === 0) return body.map((b) => b);
 	const state = new NumberingState();
@@ -54,6 +65,14 @@ function mergeIndentFromLevel(paragraphProps, levelProps) {
 	if (out.indentFirstLine === void 0 && levelProps.indentFirstLine !== void 0) out.indentFirstLine = levelProps.indentFirstLine;
 	return out;
 }
+/**
+* Apply {@link applyNumbering} to each header/footer band independently (each
+* gets its own counter state), keyed as in the input map.
+*
+* @param hf        The header/footer bodies by key, or `undefined`.
+* @param numbering The parsed numbering definitions, or `undefined`.
+* @returns A new map with numbering applied (empty when `hf` is empty/absent).
+*/
 function applyNumberingToHeadersFooters(hf, numbering) {
 	if (!hf || hf.size === 0) return /* @__PURE__ */ new Map();
 	if (!numbering || numbering.abstractNums.size === 0) return hf;