reamkit 1.15.0 → 1.15.2

package/dist/esm/excel/xls/escher.d.ts

@@ -1,7 +1,10 @@
+/** A picture shape: the BLIP store index it references plus its cell anchor. */
 export interface EscherPicture {
+    /** 1-based index into the BLIP store (the OPT `pib` property). */
     readonly blipIndex: number;
     readonly anchor?: EscherAnchor;
 }
+/** A from/to two-cell anchor (each cell index a u16, each offset 1/1024 of the cell). */
 export interface EscherAnchor {
     readonly col1: number;
     readonly row1: number;
@@ -12,13 +15,37 @@ export interface EscherAnchor {
     readonly dx2: number;
     readonly dy2: number;
 }
+/**
+ * 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.
+ */
 export declare function parseBlipStore(msoDrawingGroup: Uint8Array): Array<Uint8Array | undefined>;
+/**
+ * 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.
+ */
 export declare function parseSheetPictures(msoDrawing: Uint8Array): Array<EscherPicture>;
+/**
+ * A non-picture drawing shape: its preset type (MSOSPT), cell anchor, fill/line
+ * colours (when literal RGB) and whether it carries a text box.
+ */
 export interface EscherShape {
+    /** The MSOSPT preset shape type (the Sp record's instance). */
     readonly shapeType: number;
+    /** Whether the shape carries a client text box. */
     readonly hasText: boolean;
     readonly anchor?: EscherAnchor;
     readonly fillColorHex?: string;
     readonly lineColorHex?: string;
 }
+/**
+ * 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}.
+ */
 export declare function parseSheetShapes(msoDrawing: Uint8Array): Array<EscherShape>;

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,32 @@ 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}. The xlsx reader
+ * records no read-time losses.
+ *
+ * @param xlsx    The `.xlsx` (OPC ZIP) bytes.
+ * @param options Projection knobs (the W9 reference date).
+ * @returns The flow document plus an (empty) loss list.
+ */
 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

@@ -34,12 +34,32 @@ 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}. The xlsx reader
+* records no read-time losses.
+*
+* @param xlsx    The `.xlsx` (OPC ZIP) bytes.
+* @param options Projection knobs (the W9 reference date).
+* @returns The flow document plus an (empty) loss list.
+*/
 function readXlsx(xlsx, options = {}) {
 	return {
 		doc: projectSheetDoc(readXlsxToSheetDoc(xlsx), options),
 		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,6 +404,12 @@ 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",

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) => {