reamkit 1.15.0 → 1.15.2

package/dist/esm/excel/sheet-drawing.d.ts

@@ -1,21 +1,55 @@
 import { OpcPackage } from '../core/opc/index.js';
 import { ParsedWorksheet } from '../core/spreadsheet-model/index.js';
+/** §20.5 — a chart frame anchored over the grid, sized from its cell-range anchor. */
 export interface SheetChartRef {
+    /**
+     * The resolved chart part path (`'xl/charts/chart1.xml'`) — globally unique, used
+     * as the FlowDoc charts key and the `ChartBlock.chartRelId`.
+     */
     readonly chartPartPath: string;
     readonly widthPt: number;
     readonly heightPt: number;
+    /** Anchor top row (0-based) — used only to order charts on the sheet. */
     readonly anchorRow: number;
 }
+/**
+ * §20.5.2.1 `xdr:pic` — a picture anchored over the grid. The reader reads the
+ * resolved media part's bytes into the SheetDoc resource store.
+ */
 export interface SheetPicture {
+    /** The resolved media part path; the reader loads its bytes into the resource store. */
     readonly imagePartPath: string;
     readonly widthPt: number;
     readonly heightPt: number;
+    /** Anchor top row (0-based) — used only to order pictures on the sheet. */
     readonly anchorRow: number;
 }
+/** Both kinds of anchored frame the drawing yields, anchor-ordered. */
 export interface SheetDrawing {
     readonly charts: Array<SheetChartRef>;
     readonly pictures: Array<SheetPicture>;
 }
+/**
+ * Parse a `xl/drawings/drawingN.xml` part (§20.5.2.35/.33/.1 — `xdr:twoCellAnchor`
+ * / `oneCellAnchor` / `absoluteAnchor`) into the {@link SheetDrawing} it yields.
+ * Each anchor frames either a chart (`graphicFrame`) or a picture (`xdr:pic`); both
+ * are sized from the anchor and returned anchor-ordered.
+ *
+ * @param drawingXml      The drawing part bytes.
+ * @param drawingPartPath The drawing part path, for resolving its relationships.
+ * @param pkg             The OPC package, used to resolve relId → part path.
+ * @param worksheet       The host worksheet, for the column/row track geometry.
+ */
 export declare function parseSheetDrawing(drawingXml: Uint8Array, drawingPartPath: string, pkg: OpcPackage, worksheet: ParsedWorksheet): SheetDrawing;
+/**
+ * Build a `col → width-in-points` accessor: a `<col>` override (Excel "chars")
+ * where present, else the default — the same conversions the print model uses.
+ * Exported so the sheet-shape parser (E-SHEET W2) sizes shape anchors with the same
+ * track geometry.
+ */
 export declare function makeColWidthPt(ws: ParsedWorksheet): (col: number) => number;
+/**
+ * Build a `row → height-in-points` accessor: the explicit row height where present,
+ * else the default. Pairs with {@link makeColWidthPt} for the anchor track geometry.
+ */
 export declare function makeRowHeightPt(ws: ParsedWorksheet): (row: number) => number;

package/dist/esm/excel/sheet-drawing.js

@@ -10,6 +10,17 @@ var parser = new XMLParser({
 	parseTagValue: false
 });
 var TWIPS_PER_PT = 20;
+/**
+* Parse a `xl/drawings/drawingN.xml` part (§20.5.2.35/.33/.1 — `xdr:twoCellAnchor`
+* / `oneCellAnchor` / `absoluteAnchor`) into the {@link SheetDrawing} it yields.
+* Each anchor frames either a chart (`graphicFrame`) or a picture (`xdr:pic`); both
+* are sized from the anchor and returned anchor-ordered.
+*
+* @param drawingXml      The drawing part bytes.
+* @param drawingPartPath The drawing part path, for resolving its relationships.
+* @param pkg             The OPC package, used to resolve relId → part path.
+* @param worksheet       The host worksheet, for the column/row track geometry.
+*/
 function parseSheetDrawing(drawingXml, drawingPartPath, pkg, worksheet) {
 	const root = parser.parse(new TextDecoder().decode(drawingXml))["wsDr"];
 	if (!root || typeof root !== "object") return {
@@ -120,12 +131,22 @@ function spanPt(from, fromOffPt, to, toOffPt, trackPt) {
 	for (let i = from; i < to; i++) span += trackPt(i);
 	return span - fromOffPt + toOffPt;
 }
+/**
+* Build a `col → width-in-points` accessor: a `<col>` override (Excel "chars")
+* where present, else the default — the same conversions the print model uses.
+* Exported so the sheet-shape parser (E-SHEET W2) sizes shape anchors with the same
+* track geometry.
+*/
 function makeColWidthPt(ws) {
 	return (col) => {
 		for (const c of ws.columns) if (col >= c.min - 1 && col <= c.max - 1) return c.widthChars * 105 / TWIPS_PER_PT;
 		return 960 / TWIPS_PER_PT;
 	};
 }
+/**
+* Build a `row → height-in-points` accessor: the explicit row height where present,
+* else the default. Pairs with {@link makeColWidthPt} for the anchor track geometry.
+*/
 function makeRowHeightPt(ws) {
 	return (row) => {
 		for (const r of ws.rowHeights) if (r.row === row) return r.heightPt;

package/dist/esm/excel/sheet-shape-parser.d.ts

@@ -1,4 +1,16 @@
 import { ShapeBlock } from '../core/document-model/index.js';
 import { ColorResolver } from '../core/drawingml/colors.js';
 import { ParsedWorksheet } from '../core/spreadsheet-model/index.js';
+/**
+ * Parse a drawing's `xdr:sp` shape anchors (§20.5.2.30) into anchor-ordered
+ * {@link ShapeBlock}s (E-SHEET W2), reusing the shared DrawingML geometry / fill /
+ * line / text readers. A shape's box comes from its sheet anchor (from/to tracks),
+ * not its `a:xfrm`. Returns `[]` when the drawing has no shapes (chart/picture-only),
+ * so the reader's gate keeps non-shape sheets off this second parse.
+ *
+ * @param drawingXml The drawing part bytes (re-parsed via `parseXml` for the
+ *                   preserveOrder tree the shape readers expect).
+ * @param worksheet  The host worksheet, for the column/row track geometry.
+ * @param colors     The theme colour resolver threaded into fill/line parsing.
+ */
 export declare function parseSheetShapes(drawingXml: Uint8Array, worksheet: ParsedWorksheet, colors: ColorResolver): Array<ShapeBlock>;

package/dist/esm/excel/sheet-shape-parser.js

@@ -10,6 +10,18 @@ var ANCHOR_KINDS = [
 	"xdr:oneCellAnchor",
 	"xdr:absoluteAnchor"
 ];
+/**
+* Parse a drawing's `xdr:sp` shape anchors (§20.5.2.30) into anchor-ordered
+* {@link ShapeBlock}s (E-SHEET W2), reusing the shared DrawingML geometry / fill /
+* line / text readers. A shape's box comes from its sheet anchor (from/to tracks),
+* not its `a:xfrm`. Returns `[]` when the drawing has no shapes (chart/picture-only),
+* so the reader's gate keeps non-shape sheets off this second parse.
+*
+* @param drawingXml The drawing part bytes (re-parsed via `parseXml` for the
+*                   preserveOrder tree the shape readers expect).
+* @param worksheet  The host worksheet, for the column/row track geometry.
+* @param colors     The theme colour resolver threaded into fill/line parsing.
+*/
 function parseSheetShapes(drawingXml, worksheet, colors) {
 	const wsDr = parseXml(drawingXml).find((n) => poIs(n, "xdr:wsDr"));
 	if (!wsDr) return [];

package/dist/esm/excel/sheet-to-flow.d.ts

@@ -1,6 +1,25 @@
 import { FlowDoc } from '../core/ir/flow.js';
 import { SheetDoc } from '../core/ir/sheet.js';
+/**
+ * Projection knobs (E-SHEET W9).
+ */
 export interface ProjectSheetOptions {
+    /**
+     * The injected reference date that drives conditional-format `timePeriod`
+     * windows and `TODAY()`/`NOW()` in `expression` rules. Omitted ⇒ those
+     * clock-relative constructs no-op, so the projection stays deterministic and
+     * byte-identical to before.
+     */
     readonly now?: Date;
 }
+/**
+ * Project a {@link SheetDoc} into a {@link FlowDoc} (E-SHEET SA2): each grid sheet
+ * becomes flow blocks (a table + chart/picture/shape/slicer frames, then comment
+ * / control listings), with sheets after the first starting on a new page. The
+ * first sheet's page geometry + header/footer drive the document section.
+ *
+ * @param sheet   The SpreadsheetML IR tree.
+ * @param options Projection knobs (the W9 reference date).
+ * @returns The format-neutral flow document the render path consumes.
+ */
 export declare function projectSheetDoc(sheet: SheetDoc, options?: ProjectSheetOptions): FlowDoc;

package/dist/esm/excel/sheet-to-flow.js

@@ -6,6 +6,16 @@ import { buildHeaderFooterContent } from "./header-footer.js";
 //#region src/excel/sheet-to-flow.ts
 var HEADER_REL = "_xlsxHeaderDefault";
 var FOOTER_REL = "_xlsxFooterDefault";
+/**
+* Project a {@link SheetDoc} into a {@link FlowDoc} (E-SHEET SA2): each grid sheet
+* becomes flow blocks (a table + chart/picture/shape/slicer frames, then comment
+* / control listings), with sheets after the first starting on a new page. The
+* first sheet's page geometry + header/footer drive the document section.
+*
+* @param sheet   The SpreadsheetML IR tree.
+* @param options Projection knobs (the W9 reference date).
+* @returns The format-neutral flow document the render path consumes.
+*/
 function projectSheetDoc(sheet, options = {}) {
 	const body = [];
 	let firstSheetSection;

package/dist/esm/excel/slicer-parser.d.ts

@@ -1,15 +1,38 @@
+/**
+ * §18.3.1 (2009/9/main) `<slicer>` — one slicer panel. `cacheName` (`@cache`) keys
+ * into the workbook's slicer caches; `caption` (`@caption`) titles the box.
+ */
 export interface SlicerDef {
     readonly name: string;
+    /** The slicer-cache name (`@cache`) binding this panel to its source. */
     readonly cacheName: string;
     readonly caption: string;
     readonly columnCount: number;
     readonly styleName?: string;
 }
+/**
+ * `<slicerCacheDefinition>` — binds a slicer to its source. A native-table slicer
+ * carries an `<x14:tableSlicerCache tableId column>` (the table + column whose
+ * values are the buttons). `sourceName` is the field/column name.
+ */
 export interface SlicerCacheDef {
     readonly name: string;
+    /** The source field/column name. */
     readonly sourceName?: string;
+    /** The source table id (a native-table slicer), matched against a parsed table part's id. */
     readonly tableId?: number;
+    /** The source column offset within that table. */
     readonly columnId?: number;
 }
+/**
+ * Parse `xl/slicers/slicerN.xml` into its {@link SlicerDef} panels (caption,
+ * column count, style, cache name). A slicer missing a name or cache name is
+ * skipped.
+ */
 export declare function parseSlicerPart(data: Uint8Array): Array<SlicerDef>;
+/**
+ * Parse `xl/slicerCaches/slicerCacheN.xml` into a {@link SlicerCacheDef}, resolving
+ * a native-table source (`extLst → ext → slicerCacheDefinition → tableSlicerCache`)
+ * to its `tableId` + column. Returns undefined when the root or its name is missing.
+ */
 export declare function parseSlicerCachePart(data: Uint8Array): SlicerCacheDef | undefined;

package/dist/esm/excel/slicer-parser.js

@@ -8,6 +8,11 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `xl/slicers/slicerN.xml` into its {@link SlicerDef} panels (caption,
+* column count, style, cache name). A slicer missing a name or cache name is
+* skipped.
+*/
 function parseSlicerPart(data) {
 	const root = asObj(parser.parse(decoder.decode(data))["slicers"]);
 	if (!root) return [];
@@ -30,6 +35,11 @@ function parseSlicerPart(data) {
 	}
 	return out;
 }
+/**
+* Parse `xl/slicerCaches/slicerCacheN.xml` into a {@link SlicerCacheDef}, resolving
+* a native-table source (`extLst → ext → slicerCacheDefinition → tableSlicerCache`)
+* to its `tableId` + column. Returns undefined when the root or its name is missing.
+*/
 function parseSlicerCachePart(data) {
 	const root = asObj(parser.parse(decoder.decode(data))["slicerCacheDefinition"]);
 	if (!root) return void 0;

package/dist/esm/excel/styles-parser.d.ts

@@ -1,3 +1,11 @@
 import { XlsxStyles } from '../core/spreadsheet-model/index.js';
+/** The empty style table, returned for a workbook with no (or a malformed) `styles.xml`. */
 export declare const EMPTY_XLSX_STYLES: XlsxStyles;
+/**
+ * Parse `xl/styles.xml` (§18.8) into the {@link XlsxStyles} table the renderer
+ * consumes: custom number formats, fonts, fills, borders, the cell formats
+ * (`cellXfs` — each indexing font/fill/border/numFmt + optional alignment) and the
+ * differential formats (`dxfs`) conditional formatting applies. Returns
+ * {@link EMPTY_XLSX_STYLES} when the root is absent or malformed.
+ */
 export declare function parseXlsxStyles(data: Uint8Array): XlsxStyles;

package/dist/esm/excel/styles-parser.js

@@ -10,6 +10,7 @@ var parser = new XMLParser({
 	trimValues: false,
 	removeNSPrefix: true
 });
+/** The empty style table, returned for a workbook with no (or a malformed) `styles.xml`. */
 var EMPTY_XLSX_STYLES = {
 	numFmts: /* @__PURE__ */ new Map(),
 	fonts: [],
@@ -17,6 +18,13 @@ var EMPTY_XLSX_STYLES = {
 	borders: [],
 	cellXfs: []
 };
+/**
+* Parse `xl/styles.xml` (§18.8) into the {@link XlsxStyles} table the renderer
+* consumes: custom number formats, fonts, fills, borders, the cell formats
+* (`cellXfs` — each indexing font/fill/border/numFmt + optional alignment) and the
+* differential formats (`dxfs`) conditional formatting applies. Returns
+* {@link EMPTY_XLSX_STYLES} when the root is absent or malformed.
+*/
 function parseXlsxStyles(data) {
 	const xml = decoder.decode(data);
 	const root = asObject(parser.parse(xml)["styleSheet"]);

package/dist/esm/excel/table-parser.d.ts

@@ -1,12 +1,36 @@
 import { ExcelTable } from '../core/spreadsheet-model/index.js';
+/**
+ * §18.5.1.1 `<autoFilter><filterColumn colId><filters><filter val>` — the values
+ * a column's filter keeps visible. Used only for slicer selection (E-SHEET SV2);
+ * not part of the persisted {@link ExcelTable} (so the writer/roundtrip stay
+ * unchanged).
+ */
 export interface TableFilterColumn {
+    /** 0-based column offset within the table. */
     readonly colId: number;
+    /** The values the filter keeps visible. */
     readonly values: ReadonlyArray<string>;
 }
+/**
+ * The richer parse the reader needs for slicer resolution: the persisted
+ * {@link ExcelTable} plus the table's numeric id and any autofilter value filters.
+ */
 export interface ParsedTablePart {
     readonly table: ExcelTable;
+    /** The table's numeric `@id` (matched against a slicer cache's `tableId`). */
     readonly id?: number;
     readonly filters: ReadonlyArray<TableFilterColumn>;
 }
+/**
+ * Parse `xl/tables/tableN.xml` (§18.5.1.2) into the persisted {@link ExcelTable}
+ * (range, header-row count, autofilter presence, banded-style flags), or undefined
+ * when the root or its `ref` is missing. The slimmer of the two entry points;
+ * {@link parseTablePartFull} also returns the id + filters.
+ */
 export declare function parseTablePart(data: Uint8Array): ExcelTable | undefined;
+/**
+ * Parse a table part into the full {@link ParsedTablePart} — the {@link ExcelTable}
+ * plus the table's numeric id and any autofilter value filters (for slicer
+ * resolution). Returns undefined when the root or its `ref` is missing.
+ */
 export declare function parseTablePartFull(data: Uint8Array): ParsedTablePart | undefined;

package/dist/esm/excel/table-parser.js

@@ -9,6 +9,11 @@ var parser = new XMLParser({
 	parseTagValue: false,
 	removeNSPrefix: true
 });
+/**
+* Parse a table part into the full {@link ParsedTablePart} — the {@link ExcelTable}
+* plus the table's numeric id and any autofilter value filters (for slicer
+* resolution). Returns undefined when the root or its `ref` is missing.
+*/
 function parseTablePartFull(data) {
 	const t = asObj(parser.parse(decoder.decode(data))["table"]);
 	if (!t) return void 0;

package/dist/esm/excel/workbook-parser.d.ts

@@ -1,12 +1,29 @@
 import { DefinedName } from '../core/spreadsheet-model/index.js';
+/** §18.2.19 `<sheet name sheetId r:id>` — one worksheet reference in tab order. */
 export interface SheetReference {
+    /** The sheet (tab) display name. */
     readonly name: string;
+    /** The workbook-internal sheet id (`@sheetId`); `''` when absent. */
     readonly sheetId: string;
+    /** The relationship id (`r:id`) resolving to the sheet's worksheet part. */
     readonly relationshipId: string;
 }
+/** The parsed `workbook.xml`: the ordered sheet list, the date epoch and defined names. */
 export interface ParsedWorkbook {
+    /** The worksheet references in tab order. */
     readonly sheets: ReadonlyArray<SheetReference>;
+    /**
+     * ECMA-376 Part 1 §18.2.28 — `<workbookPr date1904="1"/>`. When true the
+     * serial-to-date conversion uses 1904-01-01 as day 0 instead of the
+     * standard 1899-12-30 epoch (legacy Mac Excel files).
+     */
     readonly date1904: boolean;
+    /** §18.2.5 workbook defined names (print areas/titles, named ranges). */
     readonly definedNames: ReadonlyArray<DefinedName>;
 }
+/**
+ * Parse `workbook.xml` into its ordered {@link SheetReference} list plus the date
+ * epoch and {@link ParsedWorkbook.definedNames}. A sheet entry missing a name or
+ * relationship id is skipped; a malformed root yields an empty workbook.
+ */
 export declare function parseWorkbook(data: Uint8Array): ParsedWorkbook;

package/dist/esm/excel/workbook-parser.js

@@ -10,6 +10,11 @@ var parser = new XMLParser({
 	trimValues: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `workbook.xml` into its ordered {@link SheetReference} list plus the date
+* epoch and {@link ParsedWorkbook.definedNames}. A sheet entry missing a name or
+* relationship id is skipped; a malformed root yields an empty workbook.
+*/
 function parseWorkbook(data) {
 	const xml = decoder.decode(data);
 	const workbook = parser.parse(xml)["workbook"];

package/dist/esm/excel/worksheet-parser.d.ts

@@ -1,2 +1,11 @@
 import { ParsedWorksheet } from '../core/spreadsheet-model/index.js';
+/**
+ * Parse `worksheet.xml` (§18.3.1.99) into a {@link ParsedWorksheet}: a flat list
+ * of cells with absolute row/column addresses and their raw stored values, plus
+ * the per-sheet geometry and print model (columns, merges, row heights,
+ * pageMargins/pageSetup, breaks, frozen pane, conditional formats, data
+ * validations, hyperlinks, header/footer, form controls, OLE objects, sparklines
+ * and table parts). `r=` is optional on `<row>`/`<c>`; absent indices are inferred
+ * from document order. A malformed root or missing `sheetData` yields an empty grid.
+ */
 export declare function parseWorksheet(data: Uint8Array): ParsedWorksheet;

package/dist/esm/excel/worksheet-parser.js

@@ -12,6 +12,15 @@ var parser = new XMLParser({
 	trimValues: false,
 	removeNSPrefix: true
 });
+/**
+* Parse `worksheet.xml` (§18.3.1.99) into a {@link ParsedWorksheet}: a flat list
+* of cells with absolute row/column addresses and their raw stored values, plus
+* the per-sheet geometry and print model (columns, merges, row heights,
+* pageMargins/pageSetup, breaks, frozen pane, conditional formats, data
+* validations, hyperlinks, header/footer, form controls, OLE objects, sparklines
+* and table parts). `r=` is optional on `<row>`/`<c>`; absent indices are inferred
+* from document order. A malformed root or missing `sheetData` yields an empty grid.
+*/
 function parseWorksheet(data) {
 	const xml = decoder.decode(data);
 	const worksheet = parser.parse(xml)["worksheet"];

package/dist/esm/excel/xls/biff-chart.d.ts

@@ -4,5 +4,15 @@ interface Rec {
     readonly type: number;
     readonly data: Uint8Array;
 }
+/**
+ * Parse a BIFF chart substream (XLS-6) into a {@link Chart}. The series values
+ * are read straight from the host sheet's cells through each series' AI ranges
+ * (BIFF caches no plotted numbers, unlike OOXML).
+ *
+ * @param records       The chart substream's records (between its BOF…EOF).
+ * @param cells         The host sheet's cells (the value source for AI ranges).
+ * @param sharedStrings The workbook shared strings (for category / name text).
+ * @returns The chart, or `undefined` when there are no series to plot.
+ */
 export declare function parseBiffChart(records: ReadonlyArray<Rec>, cells: ReadonlyArray<WorksheetCell>, sharedStrings: ReadonlyArray<string>): Chart | undefined;
 export {};

package/dist/esm/excel/xls/biff-chart.js

@@ -8,6 +8,16 @@ var REC_SERIES = 4099;
 var REC_AI = 4177;
 var REC_SERIESTEXT = 4109;
 var COLS = 16384;
+/**
+* Parse a BIFF chart substream (XLS-6) into a {@link Chart}. The series values
+* are read straight from the host sheet's cells through each series' AI ranges
+* (BIFF caches no plotted numbers, unlike OOXML).
+*
+* @param records       The chart substream's records (between its BOF…EOF).
+* @param cells         The host sheet's cells (the value source for AI ranges).
+* @param sharedStrings The workbook shared strings (for category / name text).
+* @returns The chart, or `undefined` when there are no series to plot.
+*/
 function parseBiffChart(records, cells, sharedStrings) {
 	let type = "unknown";
 	let barDir;

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

@@ -1,4 +1,31 @@
 import { SheetDoc } from '../../core/ir/sheet.js';
+/**
+ * Read a legacy `.xls` (BIFF8) workbook into a {@link SheetDoc} — the same IR
+ * tree the OOXML xlsx reader produces. Reads the workbook globals (sheet
+ * directory, shared strings, date system, styles, defined names, Escher BLIP
+ * store) and each worksheet substream's cells, styling and overlays.
+ *
+ * @param xls The `.xls` bytes (an OLE2/CFB container holding a `Workbook` stream).
+ * @returns The parsed spreadsheet IR tree.
+ * @throws Error on a non-OLE / non-BIFF8 input or a workbook with no worksheets
+ *   (the reader's sniff keeps malformed inputs away); a structurally odd record
+ *   is skipped, never fatal.
+ */
 export declare function readXlsToSheetDoc(xls: Uint8Array): SheetDoc;
+/**
+ * §2.5.198.5 RkNumber — decode a packed 30-bit number: bit 0 means ÷100, bit 1
+ * selects integer vs. the 30 high bits of an IEEE double. Exported for unit tests
+ * (the int / ×100 / IEEE paths).
+ */
 export declare function decodeRk(rk: number): number;
+/**
+ * §2.4.265 SST — read the shared-string table: `cstTotal`/`cstUnique` then
+ * `cstUnique` rich strings, via a continuation-aware reader (a string can split
+ * across a CONTINUE boundary, and the byte after the boundary is a fresh
+ * `fHighByte` flag for the rest). Exported for unit tests of the continuation
+ * handling.
+ *
+ * @param blocks The SST record's data followed by each CONTINUE record's data.
+ * @returns The unique shared strings, in index order.
+ */
 export declare function readSst(blocks: ReadonlyArray<Uint8Array>): Array<string>;

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

@@ -57,6 +57,18 @@ var MAX_SHEETS = 4096;
 var MAX_CELLS = 1 << 22;
 var MAX_STRINGS = 1 << 21;
 var MAX_ROW_HEIGHTS = 1 << 20;
+/**
+* Read a legacy `.xls` (BIFF8) workbook into a {@link SheetDoc} — the same IR
+* tree the OOXML xlsx reader produces. Reads the workbook globals (sheet
+* directory, shared strings, date system, styles, defined names, Escher BLIP
+* store) and each worksheet substream's cells, styling and overlays.
+*
+* @param xls The `.xls` bytes (an OLE2/CFB container holding a `Workbook` stream).
+* @returns The parsed spreadsheet IR tree.
+* @throws Error on a non-OLE / non-BIFF8 input or a workbook with no worksheets
+*   (the reader's sniff keeps malformed inputs away); a structurally odd record
+*   is skipped, never fatal.
+*/
 function readXlsToSheetDoc(xls) {
 	const cfb = openCfb(xls);
 	const wb = cfb.readStream("Workbook") ?? cfb.readStream("Book");
@@ -1282,6 +1294,11 @@ function formulaCell(d, next) {
 	}
 	return numCell(row, col, style, String(readF64(d, 6)));
 }
+/**
+* §2.5.198.5 RkNumber — decode a packed 30-bit number: bit 0 means ÷100, bit 1
+* selects integer vs. the 30 high bits of an IEEE double. Exported for unit tests
+* (the int / ×100 / IEEE paths).
+*/
 function decodeRk(rk) {
 	const div100 = (rk & 1) !== 0;
 	let value;
@@ -1330,6 +1347,16 @@ function decodeChars(d, off, cch, highByte) {
 	else for (let i = 0; i < cch && off + i < d.length; i++) s += String.fromCharCode(d[off + i]);
 	return s;
 }
+/**
+* §2.4.265 SST — read the shared-string table: `cstTotal`/`cstUnique` then
+* `cstUnique` rich strings, via a continuation-aware reader (a string can split
+* across a CONTINUE boundary, and the byte after the boundary is a fresh
+* `fHighByte` flag for the rest). Exported for unit tests of the continuation
+* handling.
+*
+* @param blocks The SST record's data followed by each CONTINUE record's data.
+* @returns The unique shared strings, in index order.
+*/
 function readSst(blocks) {
 	const r = new SstReader(blocks);
 	r.u32();
@@ -1338,33 +1365,45 @@ function readSst(blocks) {
 	for (let i = 0; i < cstUnique && !r.atEnd(); i++) out.push(r.readString());
 	return out;
 }
+/**
+* A cursor over the SST's record blocks. Header/flag reads stay within a block
+* (the spec never splits them); only the character array crosses boundaries, and
+* each crossing re-reads the `fHighByte` flag.
+*/
 var SstReader = class {
 	bi = 0;
 	off = 0;
+	/** @param blocks The SST record's data followed by each CONTINUE record's data. */
 	constructor(blocks) {
 		this.blocks = blocks;
 	}
+	/** Whether the cursor has consumed every block. */
 	atEnd() {
 		this.settle();
 		return this.bi >= this.blocks.length;
 	}
+	/** Advance off the end of exhausted blocks (a "skip" crossing — no flag byte). */
 	settle() {
 		while (this.bi < this.blocks.length && this.off >= this.blocks[this.bi].length) {
 			this.bi++;
 			this.off = 0;
 		}
 	}
+	/** Read one byte, advancing across exhausted blocks; 0 past the end. */
 	byte() {
 		this.settle();
 		if (this.bi >= this.blocks.length) return 0;
 		return this.blocks[this.bi][this.off++];
 	}
+	/** Read a little-endian unsigned 16-bit integer. */
 	u16() {
 		return this.byte() | this.byte() << 8;
 	}
+	/** Read a little-endian unsigned 32-bit integer. */
 	u32() {
 		return (this.u16() | this.u16() << 16) >>> 0;
 	}
+	/** Skip `n` bytes (used for the rich-run + phonetic tails, which carry no flags). */
 	skip(n) {
 		let left = n;
 		while (left > 0) {
@@ -1375,6 +1414,11 @@ var SstReader = class {
 			left -= take;
 		}
 	}
+	/**
+	* Read one XLUnicodeRichExtendedString: a 16-bit char count, a flags byte, the
+	* optional rich-run / phonetic sizes, the (possibly continuation-split)
+	* characters, then the skipped rich-run + phonetic tails.
+	*/
 	readString() {
 		const cch = this.u16();
 		const flags = this.byte();

package/dist/esm/excel/xls/biff-styles.d.ts

@@ -3,6 +3,26 @@ interface BiffRec {
     readonly type: number;
     readonly data: Uint8Array;
 }
+/**
+ * Build a palette-index → `"FFRRGGBB"` (8-hex ARGB, like the xlsx `rgb` attr)
+ * resolver from the default 56-colour palette plus any `PALETTE` override.
+ * `0x7FFF` / 64 / 65 are automatic or system colours → `undefined` (the renderer
+ * default). Exported so the conditional-format reader (XLS-13) resolves its dxf
+ * colours the same way.
+ *
+ * @param records The workbook-globals records (scanned for a `PALETTE` override).
+ * @returns A function mapping a colour index (icv) to its hex, or `undefined`.
+ */
 export declare function buildBiffPalette(records: ReadonlyArray<BiffRec>): (icv: number) => string | undefined;
+/**
+ * Read a `.xls` workbook globals' FONT / FORMAT / PALETTE / XF records (XLS-4)
+ * into the shared `XlsxStyles` model the OOXML path uses. BIFF packs each XF's
+ * fill and border inline and stores colours as palette indices; these are
+ * resolved through {@link buildBiffPalette} and de-duplicated into the model's
+ * shared fill/border arrays.
+ *
+ * @param records The workbook-globals record stream.
+ * @returns The style table (numFmts, fonts, fills, borders, cellXfs).
+ */
 export declare function parseBiffStyles(records: ReadonlyArray<BiffRec>): XlsxStyles;
 export {};

package/dist/esm/excel/xls/biff-styles.js

@@ -115,6 +115,16 @@ var PALETTE56 = [
 	"333399",
 	"333333"
 ];
+/**
+* Build a palette-index → `"FFRRGGBB"` (8-hex ARGB, like the xlsx `rgb` attr)
+* resolver from the default 56-colour palette plus any `PALETTE` override.
+* `0x7FFF` / 64 / 65 are automatic or system colours → `undefined` (the renderer
+* default). Exported so the conditional-format reader (XLS-13) resolves its dxf
+* colours the same way.
+*
+* @param records The workbook-globals records (scanned for a `PALETTE` override).
+* @returns A function mapping a colour index (icv) to its hex, or `undefined`.
+*/
 function buildBiffPalette(records) {
 	const palette = [...PALETTE56.slice(0, 8), ...PALETTE56];
 	for (const rec of records) if (rec.type === REC_PALETTE) applyPalette(rec.data, palette);
@@ -124,6 +134,16 @@ function buildBiffPalette(records) {
 		return rgb ? `FF${rgb}` : void 0;
 	};
 }
+/**
+* Read a `.xls` workbook globals' FONT / FORMAT / PALETTE / XF records (XLS-4)
+* into the shared `XlsxStyles` model the OOXML path uses. BIFF packs each XF's
+* fill and border inline and stores colours as palette indices; these are
+* resolved through {@link buildBiffPalette} and de-duplicated into the model's
+* shared fill/border arrays.
+*
+* @param records The workbook-globals record stream.
+* @returns The style table (numFmts, fonts, fills, borders, cellXfs).
+*/
 function parseBiffStyles(records) {
 	const color = buildBiffPalette(records);
 	const fonts = [];