reamkit 1.15.1 → 1.15.3

package/dist/esm/excel/xls/escher.js

@@ -24,6 +24,15 @@ function* records(d) {
 		off = end;
 	}
 }
+/**
+* Read the workbook-globals MSODrawingGroup's BLIP store: one entry per BSE (so a
+* `pib` index lines up), holding the extracted image bytes — or `undefined` for
+* an entry we cannot read (a metafile blip, an empty slot), which keeps the
+* indices aligned.
+*
+* @param msoDrawingGroup The concatenated MSODrawingGroup record bytes.
+* @returns The image pool, indexed so `pib − 1` selects an entry.
+*/
 function parseBlipStore(msoDrawingGroup) {
 	const store = findContainer(msoDrawingGroup, FBT_BSTORE_CONTAINER, 0);
 	if (!store) return [];
@@ -41,6 +50,10 @@ function findContainer(d, type, depth) {
 		}
 	}
 }
+/**
+* The picture shapes in a sheet's MSODrawing: every SpContainer that carries a
+* `pib` (a picture-fill reference into the BLIP store) with its cell anchor.
+*/
 function parseSheetPictures(msoDrawing) {
 	const out = [];
 	collectPictures(msoDrawing, out, 0);
@@ -63,6 +76,11 @@ var FBT_SP = 61450;
 var FBT_CLIENT_TEXTBOX = 61453;
 var PROP_FILL_COLOR = 385;
 var PROP_LINE_COLOR = 448;
+/**
+* The non-picture shapes (autoshapes, text boxes) in a sheet's MSODrawing — every
+* SpContainer that is NOT a picture (no `pib`). Pictures are handled separately
+* by {@link parseSheetPictures}.
+*/
 function parseSheetShapes(msoDrawing) {
 	const out = [];
 	collectShapes(msoDrawing, out, 0);

package/dist/esm/excel/xls/xls-reader.d.ts

@@ -1,3 +1,9 @@
 import { DocumentReader } from '../../core/ir/adapters.js';
 import { SheetDoc } from '../../core/ir/sheet.js';
+/**
+ * The legacy `.xls` {@link DocumentReader} (XLS-3): sniffs a BIFF8 OLE2/CFB
+ * workbook and reads it into the same {@link SheetDoc} the OOXML xlsx reader
+ * produces, so the whole render pipeline works on a 1997–2003 `.xls`. Reports a
+ * single degraded {@link Loss} for the unread Excel-tables / autofilter feature.
+ */
 export declare const xlsReader: DocumentReader<SheetDoc>;

package/dist/esm/excel/xls/xls-reader.js

@@ -16,6 +16,12 @@ var XLS_LOSSES = [{
 	feature: FEATURES.cellFormatting,
 	detail: "legacy .xls Excel tables / autofilter are not read; the sheet’s cell data, styling, images, charts, drawing shapes, conditional formatting, comments, hyperlinks, data validation, defined names, the page-setup print model, frozen panes and custom row heights are"
 }];
+/**
+* The legacy `.xls` {@link DocumentReader} (XLS-3): sniffs a BIFF8 OLE2/CFB
+* workbook and reads it into the same {@link SheetDoc} the OOXML xlsx reader
+* produces, so the whole render pipeline works on a 1997–2003 `.xls`. Reports a
+* single degraded {@link Loss} for the unread Excel-tables / autofilter feature.
+*/
 var xlsReader = {
 	id: "xls",
 	produces: "sheet",

package/dist/esm/excel/xlsx-reader.d.ts

@@ -2,6 +2,36 @@ import { DocumentReader, ReadResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
 import { SheetDoc } from '../core/ir/sheet.js';
 import { ProjectSheetOptions } from './sheet-to-flow.js';
+/**
+ * Read a `.xlsx` and project it to a {@link FlowDoc} in one step:
+ * {@link readXlsxToSheetDoc} then {@link projectSheetDoc}.
+ *
+ * Parsing itself is lossless — SpreadsheetML maps cleanly onto the sheet IR.
+ * The losses come from the projection: the print model's defence-in-depth caps
+ * (grid size, per-sheet text budget, sparkline range) clip pathological sheets,
+ * and each clip is reported rather than applied in silence.
+ *
+ * @param xlsx    The `.xlsx` (OPC ZIP) bytes.
+ * @param options Projection knobs (the W9 reference date).
+ * @returns The flow document plus whatever the projection had to clip.
+ */
 export declare function readXlsx(xlsx: Uint8Array, options?: ProjectSheetOptions): ReadResult<FlowDoc>;
+/**
+ * Read a `.xlsx` into the {@link SheetDoc} SpreadsheetML IR node. Everything that
+ * needs the OPC package — workbook/worksheet/styles/shared-string parsing, chart
+ * and drawing resolution, tables, pivots, slicers, hyperlinks, comments and
+ * controls — happens here; the SheetDoc → FlowDoc projection (sheet-to-flow) is
+ * then a pure transform.
+ *
+ * @param xlsx The `.xlsx` (OPC ZIP) bytes.
+ * @returns The parsed spreadsheet IR tree.
+ * @throws Error when `xl/workbook.xml` is missing or the workbook has no sheets.
+ */
 export declare function readXlsxToSheetDoc(xlsx: Uint8Array): SheetDoc;
+/**
+ * The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP for
+ * `xl/workbook.xml` and reads it into a {@link SheetDoc}. The reader's native
+ * tree is the SheetDoc; the facade/Ream project it to a {@link FlowDoc} for
+ * rendering (E-SHEET SB1).
+ */
 export declare const xlsxReader: DocumentReader<SheetDoc>;

package/dist/esm/excel/xlsx-reader.js

@@ -1,6 +1,6 @@
 import { ResourceStore } from "../core/ir/resources.js";
 import { FEATURES } from "../core/ir/features.js";
-import { bytesInclude } from "../core/bytes.js";
+import { bytesInclude, bytesIncludePartName } from "../core/bytes.js";
 import { DEFAULT_THEME_PALETTE, makeColorResolver } from "../core/drawingml/colors.js";
 import { parseChart, withChartColorStyle } from "../core/drawingml/chart-parser.js";
 import { parseTheme } from "../core/drawingml/theme-parser.js";
@@ -34,12 +34,40 @@ var SLICER_CACHE_REL_TAIL = "/slicerCache";
 var THREADED_COMMENTS_REL_TAIL = "/threadedComment";
 var PERSON_REL_TAIL = "/person";
 var MAX_SLICER_ITEMS = 256;
+/**
+* Read a `.xlsx` and project it to a {@link FlowDoc} in one step:
+* {@link readXlsxToSheetDoc} then {@link projectSheetDoc}.
+*
+* Parsing itself is lossless — SpreadsheetML maps cleanly onto the sheet IR.
+* The losses come from the projection: the print model's defence-in-depth caps
+* (grid size, per-sheet text budget, sparkline range) clip pathological sheets,
+* and each clip is reported rather than applied in silence.
+*
+* @param xlsx    The `.xlsx` (OPC ZIP) bytes.
+* @param options Projection knobs (the W9 reference date).
+* @returns The flow document plus whatever the projection had to clip.
+*/
 function readXlsx(xlsx, options = {}) {
+	const losses = [];
 	return {
-		doc: projectSheetDoc(readXlsxToSheetDoc(xlsx), options),
-		losses: []
+		doc: projectSheetDoc(readXlsxToSheetDoc(xlsx), {
+			...options,
+			losses
+		}),
+		losses
 	};
 }
+/**
+* Read a `.xlsx` into the {@link SheetDoc} SpreadsheetML IR node. Everything that
+* needs the OPC package — workbook/worksheet/styles/shared-string parsing, chart
+* and drawing resolution, tables, pivots, slicers, hyperlinks, comments and
+* controls — happens here; the SheetDoc → FlowDoc projection (sheet-to-flow) is
+* then a pure transform.
+*
+* @param xlsx The `.xlsx` (OPC ZIP) bytes.
+* @returns The parsed spreadsheet IR tree.
+* @throws Error when `xl/workbook.xml` is missing or the workbook has no sheets.
+*/
 function readXlsxToSheetDoc(xlsx) {
 	const pkg = OpcPackage.open(xlsx);
 	const workbookData = pkg.getPart(WORKBOOK_PART);
@@ -384,11 +412,17 @@ function lighten(hex, amount) {
 	const hx = (c) => c.toString(16).padStart(2, "0").toUpperCase();
 	return `${hx(ch(16))}${hx(ch(8))}${hx(ch(0))}`;
 }
+/**
+* The OOXML `.xlsx` {@link DocumentReader}: sniffs the OPC ZIP for
+* `xl/workbook.xml` and reads it into a {@link SheetDoc}. The reader's native
+* tree is the SheetDoc; the facade/Ream project it to a {@link FlowDoc} for
+* rendering (E-SHEET SB1).
+*/
 var xlsxReader = {
 	id: "xlsx",
 	produces: "sheet",
 	supports: new Set([FEATURES.text, FEATURES.tables]),
-	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && bytesInclude(bytes, "xl/workbook.xml"),
+	sniff: (bytes) => bytes[0] === 80 && bytes[1] === 75 && bytesIncludePartName(bytes, "xl/workbook.xml"),
 	read: (bytes) => ({
 		doc: readXlsxToSheetDoc(bytes),
 		losses: []

package/dist/esm/excel/xlsx-to-pdf.d.ts

@@ -1,13 +1,40 @@
 import { FontBytesByVariant } from '../core/font/index.js';
 import { FetchLike } from '../core/fonts/index.js';
 import { SignatureOptions, StyledRenderOptions } from '../pdf/index.js';
+/**
+ * Options for the xlsx → PDF convenience converters. Extends the low-level
+ * {@link StyledRenderOptions} (minus the font `registry` and `styles`, which the
+ * converter builds itself) with font acquisition and source-touching conveniences.
+ */
 export interface ConvertXlsxOptions extends Omit<StyledRenderOptions, 'registry' | 'styles'> {
+    /** Shorthand for supplying 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. 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 `.xlsx` as an associated source file
+     * (`/AFRelationship /Source`). Ignored for other profiles.
+     */
     readonly embedSource?: boolean;
+    /**
+     * E-SHEET W9 — the reference date for conditional-format `timePeriod` rules and
+     * `TODAY()`/`NOW()` in `expression` rules. An explicit input (never the wall
+     * clock), so output stays deterministic; omitted ⇒ those clock-relative rules
+     * no-op.
+     */
     readonly now?: Date;
+    /**
+     * Digitally sign the output (ISO 32000 §12.8). Requires the async
+     * {@link convertXlsxToPdf} (signing uses WebCrypto). Ignored by the sync
+     * converter.
+     */
     readonly signature?: SignatureOptions;
 }
 /**

package/dist/esm/excel/xlsx-writer.d.ts

@@ -1,4 +1,18 @@
 import { DocumentWriter, WriteResult } from '../core/ir/adapters.js';
 import { SheetDoc } from '../core/ir/sheet.js';
+/**
+ * Serialize a {@link SheetDoc} back to a `.xlsx` (E-SHEET SD1). The first writer
+ * that consumes the SpreadsheetML IR node directly (not the FlowDoc projection),
+ * so the cells keep their RAW value + style index and the SheetDoc is a stable
+ * round-trip fixpoint (SD2). Re-emits the full grid surface — values, shared
+ * strings, styles, merges, column/row geometry, the page model, conditional
+ * formatting, sparklines, table parts and embedded charts — through the core OPC
+ * writer.
+ *
+ * @param sheet The spreadsheet IR tree to write.
+ * @returns The encoded `.xlsx` bytes and any write-time losses (e.g. a chart
+ *   frame whose data could not be resolved).
+ */
 export declare function writeXlsx(sheet: SheetDoc): WriteResult;
+/** The `.xlsx` {@link DocumentWriter}: a thin wrapper over {@link writeXlsx}. */
 export declare const xlsxWriter: DocumentWriter<SheetDoc>;

package/dist/esm/excel/xlsx-writer.js

@@ -24,6 +24,19 @@ var CT_STYLES = "application/vnd.openxmlformats-officedocument.spreadsheetml.sty
 var CT_TABLE = "application/vnd.openxmlformats-officedocument.spreadsheetml.table+xml";
 var MAIN_NS = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
 var R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+/**
+* Serialize a {@link SheetDoc} back to a `.xlsx` (E-SHEET SD1). The first writer
+* that consumes the SpreadsheetML IR node directly (not the FlowDoc projection),
+* so the cells keep their RAW value + style index and the SheetDoc is a stable
+* round-trip fixpoint (SD2). Re-emits the full grid surface — values, shared
+* strings, styles, merges, column/row geometry, the page model, conditional
+* formatting, sparklines, table parts and embedded charts — through the core OPC
+* writer.
+*
+* @param sheet The spreadsheet IR tree to write.
+* @returns The encoded `.xlsx` bytes and any write-time losses (e.g. a chart
+*   frame whose data could not be resolved).
+*/
 function writeXlsx(sheet) {
 	const losses = [];
 	const worksheetParts = [];

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

@@ -1,4 +1,22 @@
 import { DocumentWriter, WriteResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
+/**
+ * Render a {@link FlowDoc} to a self-contained HTML document (ir-design §7).
+ *
+ * A flow medium: no pagination, no layout engine and no fonts to embed, so this
+ * is a pure, zero-I/O transform. `flow.body` already carries FINAL effective
+ * properties (the Stage-6 contract), so values map straight to CSS; every read
+ * still routes through the cascade resolver over the empty sheet, a memoized
+ * identity on reader output. Charts and shapes emit as inline SVG; deliberately
+ * out of scope (reported as losses): inline math and headers/footers (no fixed
+ * pages to band them onto). Page-break hints map to CSS `break-before`.
+ *
+ * @param flow The format-neutral interlayer document tree.
+ * @returns The encoded HTML bytes plus the recorded {@link Loss} list.
+ */
 export declare function writeHtml(flow: FlowDoc): WriteResult;
+/**
+ * The flow-medium {@link DocumentWriter} adapter (id `'html'`), wrapping
+ * {@link writeHtml}, with the set of {@link FEATURES} it renders.
+ */
 export declare const htmlWriter: DocumentWriter<FlowDoc>;

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

@@ -10,6 +10,20 @@ import { buildShapePaths, buildShapeTransform, buildStroke, gradientSvgDef } fro
 import { sanitizeHref } from "../core/links.js";
 import { toBase64 } from "../core/bytes.js";
 //#region src/html/html-writer.ts
+/**
+* Render a {@link FlowDoc} to a self-contained HTML document (ir-design §7).
+*
+* A flow medium: no pagination, no layout engine and no fonts to embed, so this
+* is a pure, zero-I/O transform. `flow.body` already carries FINAL effective
+* properties (the Stage-6 contract), so values map straight to CSS; every read
+* still routes through the cascade resolver over the empty sheet, a memoized
+* identity on reader output. Charts and shapes emit as inline SVG; deliberately
+* out of scope (reported as losses): inline math and headers/footers (no fixed
+* pages to band them onto). Page-break hints map to CSS `break-before`.
+*
+* @param flow The format-neutral interlayer document tree.
+* @returns The encoded HTML bytes plus the recorded {@link Loss} list.
+*/
 function writeHtml(flow) {
 	const losses = [];
 	const out = [];
@@ -50,6 +64,10 @@ function writeHtml(flow) {
 		losses
 	};
 }
+/**
+* The flow-medium {@link DocumentWriter} adapter (id `'html'`), wrapping
+* {@link writeHtml}, with the set of {@link FEATURES} it renders.
+*/
 var htmlWriter = {
 	id: "html",
 	consumes: "flow",

package/dist/esm/index.d.ts

@@ -1,3 +1,26 @@
+/**
+ * The public API for Ream.
+ *
+ * The package reads Word, Excel, PowerPoint and PDF — including the legacy
+ * `.doc` / `.xls` / `.ppt` — and converts any of them to PDF, SVG, HTML, DOCX or
+ * XLSX, implemented from the ECMA-376 and ISO 32000 specifications without
+ * wrapping LibreOffice, headless Office, or any commercial SDK.
+ *
+ * Typical use:
+ *
+ * ```ts
+ * import { Ream } from 'reamkit';
+ * const doc = Ream.parse(bytes); // format sniffed
+ * const pdf = await doc.convert('pdf'); // one parse, any target
+ * ```
+ *
+ * Advanced consumers can build custom pipelines from the reader/writer
+ * interfaces, drive the layout engine directly via {@link renderStyledPdf},
+ * supply a hyphenator, or import the typed document model from the
+ * `reamkit/document-model` subpath.
+ *
+ * @packageDocumentation
+ */
 export { fetchFontSet, resolveFamilyKey } from './core/fonts/index.js';
 export type { FamilyKey, FetchFontSetOptions, FetchLike } from './core/fonts/index.js';
 export { renderStyledPdf } from './pdf/index.js';

package/dist/esm/layout/math-layout.d.ts

@@ -1,14 +1,21 @@
 import { MathNode } from '../core/document-model/index.js';
 import { PathSegment } from '../core/vector.js';
+/** Font variant a math glyph renders in (drives the auto-italic of letters). */
 export type MathVariant = 'regular' | 'italic' | 'bold' | 'boldItalic';
+/**
+ * An ordinary symbol drawn from the font: a string positioned in the box's local
+ * frame (origin = box left, baseline at `y = 0`, y up).
+ */
 export interface MathGlyphItem {
     readonly kind: 'glyph';
     readonly x: number;
+    /** Baseline offset, up positive. */
     readonly y: number;
     readonly text: string;
     readonly variant: MathVariant;
     readonly sizePt: number;
 }
+/** A filled rectangle (fraction bars, accent rules); `(x, y)` is its bottom-left edge. */
 export interface MathRuleItem {
     readonly kind: 'rule';
     readonly x: number;
@@ -16,29 +23,61 @@ export interface MathRuleItem {
     readonly w: number;
     readonly h: number;
 }
+/**
+ * A vector path drawn instead of a math-font glyph (radicals, stretchy
+ * delimiters, big operators) — so no math font is needed.
+ */
 export interface MathPathItem {
     readonly kind: 'path';
     readonly segments: ReadonlyArray<PathSegment>;
+    /** Present ⇒ stroked at this width. */
     readonly strokeWidthPt?: number;
+    /** `true` ⇒ filled. */
     readonly fill?: boolean;
 }
+/** A positioned draw item in a {@link MathBox}'s local frame. */
 export type MathDrawItem = MathGlyphItem | MathRuleItem | MathPathItem;
+/**
+ * A laid-out math box: a width plus ascent (above the baseline) and descent
+ * (below), and a flat list of positioned {@link MathDrawItem}s in a LOCAL frame
+ * (origin = box left, baseline at `y = 0`, y up).
+ */
 export interface MathBox {
     readonly width: number;
     readonly ascent: number;
     readonly descent: number;
     readonly items: ReadonlyArray<MathDrawItem>;
 }
+/** Injected text-measure: the advance width of `text` at `sizePt` in `variant`. */
 export type MeasureMath = (text: string, sizePt: number, variant: MathVariant) => number;
+/** Layout context threaded through {@link layoutMath} — currently just the em size. */
 export interface MathCtx {
     readonly sizePt: number;
 }
+/** Decompose a {@link MathVariant} into its independent bold / italic flags. */
 export declare function variantStyle(v: MathVariant): {
     bold: boolean;
     italic: boolean;
 };
+/**
+ * Recursively lay out an ECMA-376 §22 OfficeMath node into a {@link MathBox}.
+ * Ordinary symbols become {@link MathGlyphItem}s (rendered from the font);
+ * structural elements (fraction rules, radicals, big operators, stretchy
+ * delimiters) become rule/path items drawn as vector graphics. Pure: text widths
+ * arrive through the injected `measure` fn.
+ *
+ * @param node    The math tree node to lay out.
+ * @param ctx     The layout context (em size).
+ * @param measure The injected advance-width measurer.
+ * @returns The positioned box; constructs added in later milestones render empty.
+ */
 export declare function layoutMath(node: MathNode, ctx: MathCtx, measure: MeasureMath): MathBox;
+/** Translate every item in a box by `(dx, dy)`, returning shifted copies. */
 export declare function shiftItems(items: ReadonlyArray<MathDrawItem>, dx: number, dy: number): Array<MathDrawItem>;
+/**
+ * Flatten a math tree into `(variant, text)` glyph segments — used to subset the
+ * right glyphs into the right font variant. Grows alongside {@link layoutMath}.
+ */
 export declare function mathGlyphSegments(node: MathNode): Array<{
     variant: MathVariant;
     text: string;

package/dist/esm/layout/math-layout.js

@@ -6,6 +6,7 @@ var BAR_THICK = .045;
 var FRAC_GAP = .15;
 var FRAC_PAD = .12;
 var SCRIPT_SIZE = .7;
+/** Decompose a {@link MathVariant} into its independent bold / italic flags. */
 function variantStyle(v) {
 	return {
 		bold: v === "bold" || v === "boldItalic",
@@ -20,6 +21,18 @@ function runCharVariant(ch, run) {
 	const bold = run.bold ?? false;
 	return variantOf(run.nor ? false : run.italic ?? isAutoItalic(ch), bold);
 }
+/**
+* Recursively lay out an ECMA-376 §22 OfficeMath node into a {@link MathBox}.
+* Ordinary symbols become {@link MathGlyphItem}s (rendered from the font);
+* structural elements (fraction rules, radicals, big operators, stretchy
+* delimiters) become rule/path items drawn as vector graphics. Pure: text widths
+* arrive through the injected `measure` fn.
+*
+* @param node    The math tree node to lay out.
+* @param ctx     The layout context (em size).
+* @param measure The injected advance-width measurer.
+* @returns The positioned box; constructs added in later milestones render empty.
+*/
 function layoutMath(node, ctx, measure) {
 	switch (node.type) {
 		case "run": return layoutRun(node, ctx, measure);
@@ -1016,6 +1029,7 @@ function layoutGroupChr(node, ctx, measure) {
 		items
 	};
 }
+/** Translate every item in a box by `(dx, dy)`, returning shifted copies. */
 function shiftItems(items, dx, dy) {
 	return items.map((it) => {
 		if (it.kind === "glyph") return {
@@ -1054,6 +1068,10 @@ function shiftSegment(s, dx, dy) {
 		case "close": return s;
 	}
 }
+/**
+* Flatten a math tree into `(variant, text)` glyph segments — used to subset the
+* right glyphs into the right font variant. Grows alongside {@link layoutMath}.
+*/
 function mathGlyphSegments(node) {
 	const out = [];
 	const visit = (n) => {

package/dist/esm/layout/page-doc.d.ts

@@ -3,35 +3,74 @@ import { FontMeasure, ParsedTtf } from '../core/font/index.js';
 import { ResolvedParagraphProperties, ResolvedRunProperties } from '../core/style-cascade/index.js';
 import { PathSegment, VectorShape } from '../core/vector.js';
 import { PreparedImage } from '../core/images.js';
+/** A font bound into a {@link LaidOutDocument}: the parsed face plus what layout/emit need from it. */
 export interface FontResource {
     readonly resourceName: string;
     readonly parsed: ParsedTtf;
+    /**
+     * Pure measurement/encoding (no `PdfDocument`): layout measures with this and
+     * emit encodes with it; the PDF font objects are created in the emit phase.
+     */
     readonly measure: FontMeasure;
+    /** Glyphs collected by the usage walk — the emit phase subsets to these. */
     readonly gids: ReadonlySet<number>;
 }
+/** A run of text on a {@link Line}: the string plus its resolved font, size, width and link/tagging state. */
 export interface TextToken {
     readonly kind: 'text';
     readonly text: string;
     readonly isSpace: boolean;
+    /**
+     * External hyperlink target inherited from the source run (rels-resolved).
+     * Writers MUST sanitize the scheme (`core/links`) before emitting anything
+     * clickable.
+     */
     readonly href?: string;
+    /**
+     * §17.11.14 — the token renders a footnote reference number; pagination
+     * reserves the note's block at the bottom of the page it lands on.
+     */
     readonly footnoteRef?: string;
+    /**
+     * §17.16.22 — internal link target: a bookmark name in this document (not a
+     * URL; resolves to a GoTo destination, never through the scheme list).
+     */
     readonly anchor?: string;
+    /**
+     * List-item marker glyphs (`"1."`, `"•"`) — tagged PDF brackets them in a Lbl
+     * element separate from the item body.
+     */
     readonly listMarker?: true;
+    /**
+     * The token falls inside a comment range (`commentRangeRefs`): the emitter
+     * fills a soft highlight behind it (E-COMMENTS CM2c).
+     */
     readonly highlight?: true;
     readonly resolvedRun: ResolvedRunProperties;
     readonly font: FontResource;
     readonly fontSizePt: number;
     readonly widthPt: number;
+    /**
+     * UAX #9 embedding level of this token's characters (0 for pure-LTR docs).
+     * Even = LTR, odd = RTL. Used for visual reordering at emit time.
+     */
     readonly bidiLevel: number;
 }
+/** An inline image on a {@link Line}: its sized box plus the resource name binding to the page XObject. */
 export interface ImageToken {
     readonly kind: 'image';
     readonly imageResourceName: string;
     readonly widthPt: number;
     readonly heightPt: number;
+    /** Constants kept to satisfy {@link Token} consumers — they never read these for images. */
     readonly isSpace: false;
     readonly bidiLevel: number;
 }
+/**
+ * A math draw item with its font already resolved (`math-layout` emits a
+ * variant; the tokenizer maps it to a {@link FontResource} so the emit phase
+ * needs no fonts).
+ */
 export type ResolvedMathItem = {
     readonly kind: 'glyph';
     readonly x: number;
@@ -51,6 +90,10 @@ export type ResolvedMathItem = {
     readonly strokeWidthPt?: number;
     readonly fill?: boolean;
 };
+/**
+ * An inline OfficeMath object — an atomic box straddling the baseline (its own
+ * ascent/descent extend the line height).
+ */
 export interface MathToken {
     readonly kind: 'math';
     readonly items: ReadonlyArray<ResolvedMathItem>;
@@ -60,7 +103,9 @@ export interface MathToken {
     readonly isSpace: false;
     readonly bidiLevel: number;
 }
+/** A positioned atom on a {@link Line}: a text run, an inline image, or an inline math box. */
 export type Token = TextToken | ImageToken | MathToken;
+/** A laid-out line of a paragraph: its broken tokens plus the geometry pagination needs. */
 export interface Line {
     readonly tokens: ReadonlyArray<Token>;
     readonly contentWidthPt: number;
@@ -69,25 +114,61 @@ export interface Line {
     readonly firstLine: boolean;
     readonly resolved: ResolvedParagraphProperties;
     isLastInParagraph: boolean;
+    /**
+     * Max ascent/descent contributed by math tokens (0 when none) — they straddle
+     * the baseline, so the line height/descent must grow to fit them.
+     */
     readonly mathAscentPt?: number;
     readonly mathDescentPt?: number;
+    /**
+     * E-PARITY: metric-derived single-line height and descent (Pt), the max over
+     * the line's text-token fonts under a non-default `layoutProfile`. Absent under
+     * `'ream'`, where leading stays the flat 1.2×/0.2 model (byte-identical).
+     */
     readonly metricHeightPt?: number;
     readonly metricDescentPt?: number;
 }
+/** An image bound into a {@link LaidOutDocument}: its resource name plus the decoded/validated bytes. */
 export interface ImageResource {
     readonly resourceName: string;
+    /**
+     * Decoded/validated at layout time (the probe); the emit phase replays it
+     * without touching the source bytes again.
+     */
     readonly prepared: PreparedImage;
 }
+/**
+ * The fields every {@link PageItem} shares (ir-design §6, frozen at stage 6.4):
+ * the positioned, layout-output vocabulary a page is made of. Page-frame
+ * geometry is branded `Pt` (PostScript points) with a TOP-LEFT origin, y growing
+ * downward (like CSS/SVG); the PDF emitter converts into PDF's native y-up frame
+ * at emission. Offsets measured from a text baseline (math/inline-image boxes
+ * inside a {@link Line}) and styling magnitudes (font/stroke sizes) stay plain
+ * numbers — they are not page-frame coordinates.
+ */
 export interface PageItemBase {
+    /**
+     * Tagged PDF (§14.8): the logical structure node this item's content belongs
+     * to. Set only on body content in tagged mode; undefined text in the line pass
+     * is treated as an artifact. Ignored when not tagging.
+     */
     readonly structId?: number;
+    /**
+     * Tagged PDF: explicitly mark this item as a pagination artifact (running
+     * header/footer, §14.8.2.2.2). Distinguishes header/footer text from
+     * not-yet-tagged body content so it is typed `/Artifact /Pagination`, never a P.
+     */
     readonly artifact?: 'pagination';
 }
+/** A laid-out line of text (tokens carry their fonts/sizes/positions). */
 export interface TextLineItem extends PageItemBase {
     readonly type: 'line';
     readonly line: Line;
     readonly originX: Pt;
+    /** Distance from the page TOP down to the text baseline. */
     readonly baselineY: Pt;
 }
+/** One edge of a table-cell frame; `(x, y)` is the cell box's top-left corner. */
 export interface BorderItem extends PageItemBase {
     readonly type: 'border';
     readonly side: 'top' | 'right' | 'bottom' | 'left';
@@ -98,6 +179,7 @@ export interface BorderItem extends PageItemBase {
     readonly borderSizePt: number;
     readonly borderColorHex: string;
 }
+/** A filled rectangle (cell shading); `(x, y)` is its top-left corner. */
 export interface FillItem extends PageItemBase {
     readonly type: 'fill';
     readonly x: Pt;
@@ -106,6 +188,10 @@ export interface FillItem extends PageItemBase {
     readonly height: Pt;
     readonly fillColorHex: string;
 }
+/**
+ * A placed raster image (resource name binds to the page XObject dict); `(x, y)`
+ * is its top-left corner.
+ */
 export interface ImageItem extends PageItemBase {
     readonly type: 'image';
     readonly x: Pt;
@@ -114,10 +200,15 @@ export interface ImageItem extends PageItemBase {
     readonly height: Pt;
     readonly imageResourceName: string;
 }
+/**
+ * DrawingML vector geometry. `shape.transform` maps the shape's local y-up frame
+ * into the top-left page frame (see `flipTransform`).
+ */
 export interface ShapeItem extends PageItemBase {
     readonly type: 'shape';
     readonly shape: VectorShape;
 }
+/** A positioned item on a laid-out page: a text line, border, fill, image, or vector shape. */
 export type PageItem = TextLineItem | BorderItem | FillItem | ImageItem | ShapeItem;
 export interface PagePaintPlan {
     readonly fills: ReadonlyArray<FillItem>;