reamkit 1.15.1 → 1.15.2

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