@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsb/read-worksheet.js

@@ -0,0 +1,301 @@
+// The BIFF12 worksheet-body reader: one `xl/worksheets/sheetN.bin` in, one populated {@link Worksheet}
+// out — the binary counterpart of `../xlsx/read-worksheet.ts`, filling the very same model.
+//
+// The cell table is a flat, row-major run of records: a `BrtRowHdr` opens a row and every cell record
+// until the next one belongs to it, so the open row is a single variable rather than nested state.
+// Each cell record is a `Cell` header followed by a value shaped by the record's own type — which is
+// what makes the binary form quick to parse: there is no `t=` attribute to interpret, the record
+// number *is* the type.
+//
+// A formula cell carries both halves of what the XML form spells in `<f>` and `<v>`: a `Ptg` token
+// stream, decoded back to text by `./formula.ts`, and the result Excel last computed. The two are
+// filled independently — a formula whose stream uses a token this reader does not decode still
+// surfaces its cached value, which is exactly what the reader could see before the decoder existed.
+//
+// One shape needs a second look at the sheet. An array formula's member cells hold a `PtgExp`
+// pointing at the group's top-left, and the `BrtArrFmla` record carrying the group's actual formula
+// comes *after* those cells in the stream. Those cells are therefore parked and resolved once the
+// whole part has been read.
+import { encodeAddress, MAX_COLUMN } from "../../core/address.js";
+import { isDateFormat, serialToDate } from "../../core/date.js";
+import { unmangleFunctions } from "../../core/formula.js";
+import { assignStyleFacets } from "../../core/style.js";
+import { applyXfToCell } from "../style/xf-style.js";
+import { decodeFormula, formulaAnchor } from "./formula.js";
+import { errorCodeFor, RecordReader } from "./primitives.js";
+import { readRecords } from "./record-stream.js";
+import { BRT } from "./record-types.js";
+// Every record that carries a plain cell — one whose payload is a value and nothing else. Membership
+// drives the dispatch below, so a record type absent from both this set and {@link FORMULA_RECORDS}
+// is skipped whole rather than being mistaken for a cell and consuming the reader.
+const CELL_RECORDS = new Set([
+    BRT.CellBlank,
+    BRT.CellRk,
+    BRT.CellError,
+    BRT.CellBool,
+    BRT.CellReal,
+    BRT.CellSt,
+    BRT.CellIsst,
+    BRT.CellRString,
+]);
+// Every record that carries a formula: a cached result of the record's own kind, then the token
+// stream that produced it.
+const FORMULA_RECORDS = new Set([
+    BRT.FmlaString,
+    BRT.FmlaNum,
+    BRT.FmlaBool,
+    BRT.FmlaError,
+]);
+/**
+ * Read a worksheet part into `sheet`: its column and row geometry, its merged ranges, and every
+ * non-empty cell with the style its index resolves to in `xfStyles` and, for a formula cell, the text
+ * its token stream decodes to through `scope`.
+ */
+export function parseWorksheet(part, sheet, sharedStrings, xfStyles, scope) {
+    // The open row, one-based as the model counts them. -1 means none is open, which a cell record
+    // arriving before any row header (a malformed sheet) is dropped against rather than guessed at.
+    let row = -1;
+    // A row that declares a format supplies the default for its cells that carry none, as a column
+    // does; the next row header replaces it.
+    let rowStyle = -1;
+    // A column's format is the last fallback. Column records always precede the cell table.
+    const columnStyle = new Map();
+    // The sheet's default row height, in twips. Every row header restates its height whether or not the
+    // row has one of its own, so the default is what tells the two apart — see {@link applyRow}.
+    // `BrtWsFmtInfo` precedes the cell table, so it is always known by the time a row is read.
+    let defaultRowHeight = -1;
+    // The formula of each array-formula group, keyed by the group's top-left cell, and the member cells
+    // waiting on one. Both are needed because `BrtArrFmla` follows the cells it speaks for.
+    const groups = new Map();
+    const deferred = [];
+    for (const record of readRecords(part)) {
+        const reader = new RecordReader(record.data);
+        if (record.type === BRT.WsFmtInfo) {
+            reader.skip(6); // dxGCol, cchDefColWidth: the default *column* width, which the model does not read.
+            defaultRowHeight = reader.u16();
+        }
+        else if (record.type === BRT.ColInfo) {
+            applyColumn(reader, sheet, xfStyles, columnStyle);
+        }
+        else if (record.type === BRT.RowHdr) {
+            const header = applyRow(reader, sheet, defaultRowHeight);
+            row = header.row;
+            rowStyle = header.styleIndex;
+        }
+        else if (record.type === BRT.MergeCell) {
+            const { rowFirst, rowLast, colFirst, colLast } = reader.range();
+            if (inGrid(colFirst, rowFirst) && inGrid(colLast, rowLast)) {
+                sheet.mergeCells(`${encodeAddress(colFirst + 1, rowFirst + 1)}:${encodeAddress(colLast + 1, rowLast + 1)}`);
+            }
+        }
+        else if (record.type === BRT.ArrFmla) {
+            const { rowFirst, colFirst } = reader.range();
+            reader.skip(1); // fAlwaysCalc: a recalculation hint, not part of the formula.
+            groups.set(groupKey(rowFirst, colFirst), {
+                rgce: reader.bytes(reader.u32()),
+                rgcb: reader.bytes(reader.u32()),
+            });
+        }
+        else if ((CELL_RECORDS.has(record.type) || FORMULA_RECORDS.has(record.type)) && row > 0) {
+            const { column, styleIndex } = reader.cell();
+            if (!inGrid(column, row - 1))
+                continue;
+            // A cell's own format wins, then its row's, then its column's — the order Excel applies.
+            // Index 0 is the default xf, which BIFF12 writes where XML simply omits `s`, so it means
+            // "no format of my own" and lets the row/column default through.
+            const resolved = styleIndex > 0 ? styleIndex : rowStyle >= 0 ? rowStyle : (columnStyle.get(column) ?? -1);
+            const style = resolved >= 0 ? xfStyles[resolved] : xfStyles[0];
+            const cell = sheet.getCell(encodeAddress(column + 1, row));
+            applyXfToCell(cell, style);
+            if (!FORMULA_RECORDS.has(record.type)) {
+                cell.value = decodeCell(record.type, reader, sharedStrings, style?.numFmt);
+                continue;
+            }
+            const result = cachedResult(record.type, reader, style?.numFmt);
+            reader.skip(2); // grbitFlags: per-cell recalculation hints the model does not carry.
+            const rgce = reader.bytes(reader.u32());
+            const rgcb = reader.bytes(reader.u32());
+            const anchor = formulaAnchor(rgce, rgcb);
+            if (anchor === undefined) {
+                cell.value = formulaValue(decodeFormula(rgce, rgcb, scope), result);
+            }
+            else {
+                deferred.push({
+                    cell,
+                    row: row - 1,
+                    column,
+                    anchorRow: anchor.row,
+                    anchorColumn: anchor.column,
+                    result,
+                });
+            }
+        }
+    }
+    for (const member of deferred) {
+        // Only the group's top-left cell states the formula; the rest carry the value it produced, which
+        // is exactly what the XML form writes for them.
+        const group = groups.get(groupKey(member.anchorRow, member.anchorColumn));
+        const own = member.row === member.anchorRow && member.column === member.anchorColumn;
+        member.cell.value =
+            group === undefined || !own
+                ? (member.result ?? null)
+                : formulaValue(decodeFormula(group.rgce, group.rgcb, scope), member.result);
+    }
+}
+function groupKey(row, column) {
+    return `${row}:${column}`;
+}
+// Pair a decoded formula with its cached result, in the shape the XML reader produces for the same
+// cell. A formula the decoder could not read leaves the value alone: the cached result is still true,
+// and is what this reader surfaced before formulas were decoded at all.
+function formulaValue(formula, result) {
+    if (formula === undefined)
+        return result ?? null;
+    // Strip the `_xlfn.`/`_xlpm.` on-disk mangling, as the XML reader does, so the model never holds it.
+    const stored = unmangleFunctions(formula);
+    return result === undefined ? { formula: stored } : { formula: stored, result };
+}
+// The result a formula record cached, decoded by the record's own kind — the binary counterpart of
+// reading `<v>` under the `t` attribute.
+function cachedResult(type, reader, numFmt) {
+    switch (type) {
+        case BRT.FmlaNum:
+            // A formula's cached numeric result honours the cell's date format exactly as a bare number
+            // does, so a date-valued formula reads back as a Date rather than a serial.
+            return asNumberOrDate(reader.f64(), numFmt);
+        case BRT.FmlaBool:
+            return reader.u8() !== 0;
+        case BRT.FmlaError: {
+            const error = errorCodeFor(reader.u8());
+            return error === undefined ? undefined : { error };
+        }
+        default:
+            return reader.wideString();
+    }
+}
+// Excel's grid bounds, zero-based as the binary format counts. [MS-XLSB] states them as MUST
+// constraints, which is exactly why a reader has to check them: a damaged or hostile file states
+// whatever it likes, and an address beyond the grid has nowhere to go. Everything positional funnels
+// through here before it reaches the model, so an out-of-grid record is dropped rather than turned
+// into an unrepresentable address (which the address encoder would reject) or, worse, a column loop
+// four billion iterations long.
+const MAX_ROW_INDEX = 1048575;
+const MAX_COLUMN_INDEX = MAX_COLUMN - 1;
+function inGrid(column, row) {
+    return column >= 0 && column <= MAX_COLUMN_INDEX && row >= 0 && row <= MAX_ROW_INDEX;
+}
+// Decode a cell record's payload — the reader is positioned just past the shared `Cell` header, so
+// what remains is exactly the value this record type carries.
+function decodeCell(type, reader, sharedStrings, numFmt) {
+    switch (type) {
+        case BRT.CellRk:
+            return asNumberOrDate(reader.rk(), numFmt);
+        case BRT.CellReal:
+            return asNumberOrDate(reader.f64(), numFmt);
+        case BRT.CellBool:
+            return reader.u8() !== 0;
+        case BRT.CellError: {
+            // An unrecognised error byte keeps the cell non-empty without inventing an error the model
+            // does not define; there is no text form to fall back to as there is in XML.
+            const error = errorCodeFor(reader.u8());
+            return error === undefined ? null : { error };
+        }
+        case BRT.CellSt:
+            return reader.wideString();
+        case BRT.CellRString:
+            // Rich runs are not modelled in this cut; the flattened text is what a consumer sees.
+            return reader.richString();
+        case BRT.CellIsst:
+            return sharedStrings[reader.u32()] ?? '';
+        default:
+            // BrtCellBlank: formatted but empty. The style is already applied; the value is genuinely none.
+            return null;
+    }
+}
+// A number stored under a date format is a date serial — surface it as a Date so a date read from an
+// `.xlsb` is the same value the `.xlsx` twin yields, not a bare number.
+function asNumberOrDate(value, numFmt) {
+    return numFmt !== undefined && isDateFormat(numFmt) ? serialToDate(value) : value;
+}
+// `BrtRowHdr` ([MS-XLSB] 2.4.770): the row index, its default format, its height, and a byte of
+// layout flags. Returns the open row (one-based) and the style index its cells inherit.
+function applyRow(reader, sheet, defaultRowHeight) {
+    const index = reader.u32();
+    const styleIndex = reader.u32();
+    const height = reader.u16();
+    reader.skip(1); // fExtraAsc/fExtraDsc: border padding, a rendering hint the model does not carry.
+    const flags = reader.u8();
+    // A row beyond the grid closes the open row without opening another, so its cells are dropped too.
+    if (index > MAX_ROW_INDEX)
+        return { row: -1, styleIndex: -1 };
+    const row = index + 1;
+    const handle = sheet.getRow(row);
+    // Every row header restates a height; only a row whose height is its *own* has one to record. That
+    // is a row the user sized by hand, or one Excel auto-fitted to a taller font or wrapped text — both
+    // differ from the sheet default, which is exactly when XML emits `ht`. A row merely restating the
+    // default carries no height, so it must not read back with one.
+    if ((flags & ROW_CUSTOM_HEIGHT) !== 0 || height !== defaultRowHeight) {
+        handle.height = height / TWIPS_PER_POINT;
+    }
+    if ((flags & ROW_HIDDEN) !== 0)
+        handle.hidden = true;
+    const outlineLevel = flags & ROW_OUTLINE_LEVEL;
+    if (outlineLevel > 0)
+        handle.outlineLevel = outlineLevel;
+    if ((flags & ROW_COLLAPSED) !== 0)
+        handle.collapsed = true;
+    // The row's format applies only when it says so, mirroring XML's `customFormat="1"` gate.
+    return { row, styleIndex: (flags & ROW_CUSTOM_FORMAT) !== 0 ? styleIndex : -1 };
+}
+const TWIPS_PER_POINT = 20;
+const ROW_OUTLINE_LEVEL = 0b0000_0111;
+const ROW_COLLAPSED = 0b0000_1000;
+const ROW_HIDDEN = 0b0001_0000;
+const ROW_CUSTOM_HEIGHT = 0b0010_0000;
+const ROW_CUSTOM_FORMAT = 0b0100_0000;
+// `BrtColInfo` ([MS-XLSB] 2.4.319): one record per run of identically-sized columns.
+function applyColumn(reader, sheet, xfStyles, columnStyle) {
+    const first = reader.u32();
+    const last = reader.u32();
+    const width = reader.u32();
+    const styleIndex = reader.u32();
+    const flags = reader.u16();
+    const style = styleIndex > 0 ? xfStyles[styleIndex] : undefined;
+    const outlineLevel = (flags >> COLUMN_OUTLINE_SHIFT) & 0b111;
+    // A run can name every column to the right of the data; materialising all 16 384 of them would
+    // turn a two-column sheet into a 16 384-entry model, so a run is only applied where it carries
+    // something a default column does not.
+    if (style === undefined &&
+        outlineLevel === 0 &&
+        (flags & (COLUMN_HIDDEN | COLUMN_CUSTOM_WIDTH | COLUMN_COLLAPSED)) === 0) {
+        return;
+    }
+    // The loop bound comes from the file, so it is clamped to the grid before it is one: an unclamped
+    // run declaring four billion columns is a denial of service, not a wide sheet.
+    const lastInGrid = Math.min(last, MAX_COLUMN_INDEX);
+    if (first > lastInGrid)
+        return;
+    for (let index = first; index <= lastInGrid; index++) {
+        const column = sheet.getColumn(index + 1);
+        // The stored width is taken whether or not the file marks it user-set, matching the XML reader:
+        // a `<col>`/`BrtColInfo` exists only for a column that differs from the sheet default in *some*
+        // way, and it always states the width that column actually has.
+        column.width = width / COLUMN_WIDTH_UNITS;
+        if ((flags & COLUMN_HIDDEN) !== 0)
+            column.hidden = true;
+        if (outlineLevel > 0)
+            column.outlineLevel = outlineLevel;
+        if ((flags & COLUMN_COLLAPSED) !== 0)
+            column.collapsed = true;
+        if (style !== undefined)
+            assignStyleFacets(column, style);
+        if (styleIndex > 0)
+            columnStyle.set(index, styleIndex);
+    }
+}
+// Column width is stored in 1/256ths of a character, where XML states the character count directly.
+const COLUMN_WIDTH_UNITS = 256;
+const COLUMN_HIDDEN = 0b0000_0001;
+const COLUMN_CUSTOM_WIDTH = 0b0000_0010;
+const COLUMN_COLLAPSED = 0b1000_0000_0000;
+const COLUMN_OUTLINE_SHIFT = 8;

package/dist/io/xlsb/read.d.ts

@@ -0,0 +1,20 @@
+import { Workbook } from '../../core/workbook.ts';
+import { type ReadXlsxOptions } from '../opc/read-options.ts';
+/** The office-document part every `.xlsb` package is entered through. */
+export declare const XLSB_WORKBOOK_PART = "xl/workbook.bin";
+/**
+ * Read an `.xlsb` (binary BIFF12) package into a {@link Workbook}.
+ *
+ * @throws {UnsupportedFormatError} if the input is not an `.xlsb` package — a legacy `.xls`
+ *   (`.format === 'xls'`), an XML `.xlsx` or unrecognised blob (`'unknown'`).
+ * @throws {XlsbParseError} if a binary part is malformed.
+ * @throws {@link PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
+ */
+export declare function readXlsb(data: Uint8Array, options?: ReadXlsxOptions): Workbook;
+/**
+ * Build the model from an already-inflated `.xlsb` package. Separate from {@link readXlsb} so the
+ * `.xlsx` reader can hand over a package it has already inflated and classified, rather than
+ * inflating the same bytes twice.
+ */
+export declare function readXlsbPackage(files: Record<string, Uint8Array>): Workbook;

package/dist/io/xlsb/read.js

@@ -0,0 +1,199 @@
+// The buffered `.xlsb` reader: a binary OPC package in, a {@link Workbook} model out.
+//
+// An `.xlsb` is the *same* OPC/ZIP container and the *same* relationship graph as an `.xlsx` — the
+// workbook part points at its sheets, its shared strings, and its style sheet through ordinary
+// `.rels` XML. Only the office-document parts differ: `xl/workbook.bin`, `xl/worksheets/sheetN.bin`
+// and friends are BIFF12 record streams instead of XML. So this module reuses the container layer
+// wholesale (`../opc/`, the bounded inflater) and swaps only the part parsers, which is
+// exactly the "two codecs over one model" shape the format note argues for.
+//
+// The model produced is the one `readXlsx` produces, not a parallel one: the same `Workbook`, the
+// same `XfStyle` table, the same cells. That is what lets a caller convert between the two forms —
+// and what the corpus asserts, by reading a workbook Excel saved in both forms and comparing.
+//
+// Not yet decoded (each its own slice of work, none silently wrong): rich-text runs, tables, pivots,
+// and conditional formatting.
+import { unmangleFunctions } from "../../core/formula.js";
+import { INTERNAL } from "../../core/internal.js";
+import { Workbook } from "../../core/workbook.js";
+import { UnsupportedFormatError } from "../opc/errors.js";
+import { packageAccessors, parseRelationships, resolveWorkbookPart } from "../opc/read-opc.js";
+import { DEFAULT_MAX_UNCOMPRESSED } from "../opc/read-options.js";
+import { inflateSpreadsheetPackage } from "../opc/sniff-format.js";
+import { decodeFormula } from "./formula.js";
+import { RecordReader } from "./primitives.js";
+import { parseSharedStrings } from "./read-shared-strings.js";
+import { parseStyleTable } from "./read-styles.js";
+import { parseWorksheet } from "./read-worksheet.js";
+import { readRecords } from "./record-stream.js";
+import { BRT } from "./record-types.js";
+/** The office-document part every `.xlsb` package is entered through. */
+export const XLSB_WORKBOOK_PART = 'xl/workbook.bin';
+/**
+ * Read an `.xlsb` (binary BIFF12) package into a {@link Workbook}.
+ *
+ * @throws {UnsupportedFormatError} if the input is not an `.xlsb` package — a legacy `.xls`
+ *   (`.format === 'xls'`), an XML `.xlsx` or unrecognised blob (`'unknown'`).
+ * @throws {XlsbParseError} if a binary part is malformed.
+ * @throws {@link PackageReadError} if the input is a ZIP that cannot be unpacked — a corrupt or
+ *   truncated archive, or one exceeding the inflate bound (a probable zip bomb).
+ */
+export function readXlsb(data, options = {}) {
+    const cap = options.maxUncompressedBytes ?? DEFAULT_MAX_UNCOMPRESSED;
+    return readXlsbPackage(inflateSpreadsheetPackage(data, cap));
+}
+/**
+ * Build the model from an already-inflated `.xlsb` package. Separate from {@link readXlsb} so the
+ * `.xlsx` reader can hand over a package it has already inflated and classified, rather than
+ * inflating the same bytes twice.
+ */
+export function readXlsbPackage(files) {
+    const { partText, partBytes } = packageAccessors(files);
+    const workbookPart = partBytes(XLSB_WORKBOOK_PART);
+    if (workbookPart === undefined) {
+        throw new UnsupportedFormatError('unknown', `not a valid .xlsb package: ${XLSB_WORKBOOK_PART} is missing`);
+    }
+    const rels = parseRelationships(partText('xl/_rels/workbook.bin.rels') ?? '');
+    const sharedStrings = parseSharedStrings(partBytes('xl/sharedStrings.bin'));
+    const { cellXfs, namedStyles, defaultFont } = parseStyleTable(partBytes('xl/styles.bin'));
+    const workbook = new Workbook();
+    // As in the XML reader, the named-style layer is restored only when a file declares more than the
+    // Normal default, so an ordinary workbook keeps an empty table and writes just that default back.
+    if (namedStyles.length > 1)
+        workbook[INTERNAL].restoreNamedStyles(namedStyles);
+    // As in the XML reader, font 0 is the workbook's declared default and must survive a re-write; an
+    // assumed Calibri in its place changes every empty cell and every character-unit column width.
+    workbook[INTERNAL].restoreDefaultFont(defaultFont);
+    const declaration = readWorkbookPart(workbookPart);
+    const scope = {
+        sheetNames: declaration.sheets.map((sheet) => sheet.name),
+        externSheets: declaration.externSheets,
+        selfSupBook: declaration.selfSupBook,
+        names: declaration.names.map((name) => name.name),
+    };
+    for (const declared of declaration.sheets) {
+        const sheet = workbook.addWorksheet(declared.name, { state: declared.state });
+        const target = declared.relId === undefined ? undefined : rels.get(declared.relId);
+        const part = target === undefined ? undefined : partBytes(resolveWorkbookPart(target));
+        if (part !== undefined)
+            parseWorksheet(part, sheet, sharedStrings, cellXfs, scope);
+    }
+    for (const defined of definedNames(declaration, scope))
+        workbook.defineName(defined);
+    return workbook;
+}
+// One pass over `xl/workbook.bin`, gathering everything the rest of the read depends on: the sheet
+// bundle, the externals block a 3-D reference resolves through, and the defined names.
+function readWorkbookPart(part) {
+    const sheets = [];
+    const names = [];
+    let externSheets = [];
+    let inBundle = false;
+    let inExternals = false;
+    // A workbook with no external links declares exactly one supporting book: itself. Rather than
+    // enumerate every record type that could open another — and risk miscounting into a *wrong* sheet
+    // name — anything else inside the externals block disqualifies the whole table.
+    let supportingBooks = 0;
+    let selfSupBook;
+    for (const record of readRecords(part)) {
+        if (record.type === BRT.BeginBundleShs)
+            inBundle = true;
+        else if (record.type === BRT.EndBundleShs)
+            inBundle = false;
+        else if (record.type === BRT.BundleSh && inBundle)
+            sheets.push(readSheet(record.data));
+        else if (record.type === BRT.BeginExternals)
+            inExternals = true;
+        else if (record.type === BRT.EndExternals)
+            inExternals = false;
+        else if (record.type === BRT.ExternSheet)
+            externSheets = readExternSheets(record.data);
+        else if (record.type === BRT.SupSelf)
+            selfSupBook = supportingBooks++;
+        else if (inExternals)
+            supportingBooks++;
+        else if (record.type === BRT.Name)
+            names.push(readName(record.data));
+    }
+    return {
+        sheets,
+        names,
+        externSheets,
+        selfSupBook: supportingBooks === 1 ? selfSupBook : undefined,
+    };
+}
+// `BrtBundleSh` ([MS-XLSB] 2.4.303) — the binary spelling of `<sheet name state r:id/>`.
+function readSheet(data) {
+    const reader = new RecordReader(data);
+    const state = SHEET_STATES[reader.u32()] ?? 'visible';
+    reader.skip(4); // iTabId: the sheet's stable id, which the model assigns itself.
+    const relId = reader.nullableWideString();
+    return { name: reader.wideString(), relId, state };
+}
+// `BrtExternSheet` ([MS-XLSB] 2.4.677): the `Xti` table every 3-D reference indexes into.
+function readExternSheets(data) {
+    const reader = new RecordReader(data);
+    const count = reader.u32();
+    const entries = [];
+    // Each entry is three 4-byte fields; checking the count against what the record holds keeps a forged
+    // one from driving the loop rather than the record's own length.
+    if (count * XTI_BYTES > reader.remaining)
+        return entries;
+    for (let index = 0; index < count; index++) {
+        entries.push({ supBook: reader.u32(), firstSheet: reader.i32(), lastSheet: reader.i32() });
+    }
+    return entries;
+}
+const XTI_BYTES = 12;
+// `BrtName` ([MS-XLSB] 2.4.673). The target is left undecoded here: it is a token stream that may cite
+// a sheet by index, and the sheet bundle is not necessarily complete at this point in the stream.
+function readName(data) {
+    const reader = new RecordReader(data);
+    const flags = reader.u32();
+    reader.skip(1); // chKey: the Alt-key shortcut a macro name can carry.
+    const itab = reader.u32();
+    const name = reader.wideString();
+    const rgce = reader.bytes(reader.u32());
+    const rgcb = reader.bytes(reader.u32());
+    return {
+        name,
+        scopeSheet: itab === GLOBAL_NAME_SCOPE ? undefined : itab,
+        isFunction: (flags & NAME_IS_FUNCTION) !== 0,
+        rgce,
+        rgcb,
+    };
+}
+// `itab` for a workbook-global name; any other value is a zero-based sheet index.
+const GLOBAL_NAME_SCOPE = 0xffffffff;
+// `fFunc`: the name registers something callable rather than a range.
+const NAME_IS_FUNCTION = 0x00000002;
+// The workbook's defined names, as the model holds them.
+//
+// Two kinds of `BrtName` are dropped, both because the XML form does not persist them either — so
+// carrying them through would make the two readings of one workbook disagree. A *function* name is
+// Excel's registration of a callable (every post-2007 function gets one, `_xlfn.TEXTJOIN` and
+// friends); its target is the placeholder `#NAME?`, not a range. And `_xlnm._FilterDatabase` is the
+// built-in Excel derives from a sheet's autofilter, which the model reconstructs from the autofilter
+// itself. A name whose target uses a token this reader cannot decode is dropped too, rather than
+// surfaced with a target that is a guess.
+function definedNames(declaration, scope) {
+    const names = [];
+    for (const declared of declaration.names) {
+        if (declared.isFunction || declared.name === FILTER_DATABASE_NAME)
+            continue;
+        const refersTo = decodeFormula(declared.rgce, declared.rgcb, scope);
+        if (refersTo === undefined)
+            continue;
+        const sheet = declared.scopeSheet === undefined ? undefined : scope.sheetNames[declared.scopeSheet];
+        names.push({
+            name: declared.name,
+            ...(sheet === undefined ? {} : { scope: sheet }),
+            // Stripped back to the readable form, the same normalisation the XML reader applies.
+            refersTo: unmangleFunctions(refersTo),
+        });
+    }
+    return names;
+}
+const FILTER_DATABASE_NAME = '_xlnm._FilterDatabase';
+// `hsState` ([MS-XLSB] 2.4.303), indexed by its stored value.
+const SHEET_STATES = ['visible', 'hidden', 'veryHidden'];

package/dist/io/xlsb/record-stream.d.ts

@@ -0,0 +1,14 @@
+/** One framed BIFF12 record: its type, and a **view** onto its payload (never a copy). */
+export interface BiffRecord {
+    readonly type: number;
+    readonly data: Uint8Array;
+}
+/**
+ * Decode a `.bin` part into its record sequence, in order.
+ *
+ * Lazy: a caller that stops early (having found what it needs) never frames the rest of the part.
+ *
+ * @throws {XlsbParseError} if a record header is truncated or a record's declared size runs past the
+ *   end of the part.
+ */
+export declare function readRecords(part: Uint8Array): Generator<BiffRecord>;

package/dist/io/xlsb/record-stream.js

@@ -0,0 +1,56 @@
+// The BIFF12 record framing every `.bin` part of an `.xlsb` package is built from ([MS-XLSB] 2.1.4).
+//
+// A part is a bare concatenation of records — no header, no index, no terminator — each framed as a
+// variable-length type, a variable-length size, and that many payload bytes. Both prefixes are
+// 7-bits-per-byte with the high bit meaning "one more byte follows": the type is 1–2 bytes (so the
+// single-byte space is reserved for the hot records — a cell is one byte of framing), the size is 1–4.
+//
+// **This is the reader's hostile-input frontier.** The declared size is attacker-controlled, so it is
+// never allowed to drive an allocation: a record's payload is handed out as a `subarray` *view* onto
+// the part the inflate bound already materialised and capped, and a size that would run past the end
+// of the part is rejected outright rather than clamped. A lying length therefore costs nothing and
+// fails closed, and the whole stream's memory is exactly the part's own bytes.
+import { XlsbParseError } from "./errors.js";
+/**
+ * Decode a `.bin` part into its record sequence, in order.
+ *
+ * Lazy: a caller that stops early (having found what it needs) never frames the rest of the part.
+ *
+ * @throws {XlsbParseError} if a record header is truncated or a record's declared size runs past the
+ *   end of the part.
+ */
+export function* readRecords(part) {
+    let offset = 0;
+    while (offset < part.length) {
+        const lowType = byteAt(part, offset++);
+        let type = lowType & 0x7f;
+        if ((lowType & 0x80) !== 0)
+            type |= (byteAt(part, offset++) & 0x7f) << 7;
+        // Up to four size bytes, least-significant seven bits first. The fourth byte's continuation bit
+        // is specified as ignored, which the fixed bound expresses: the loop simply stops there.
+        let size = 0;
+        for (let index = 0; index < 4; index++) {
+            const piece = byteAt(part, offset++);
+            size |= (piece & 0x7f) << (7 * index);
+            if ((piece & 0x80) === 0)
+                break;
+        }
+        // The one check that makes a forged size harmless: compare it against what the part *actually*
+        // holds, before anything is handed out. `part.length - offset` cannot be negative here — byteAt
+        // has already proven every header byte was in range.
+        if (size > part.length - offset) {
+            throw new XlsbParseError(`BIFF12 record ${type} declares ${size} bytes but only ${part.length - offset} remain in the part`);
+        }
+        yield { type, data: part.subarray(offset, offset + size) };
+        offset += size;
+    }
+}
+// Every header byte goes through here, so a part that ends mid-header fails closed rather than
+// folding `undefined` into the arithmetic (which `noUncheckedIndexedAccess` would otherwise let
+// through as a silent NaN-shaped type or size).
+function byteAt(part, index) {
+    const value = part[index];
+    if (value === undefined)
+        throw new XlsbParseError('truncated BIFF12 record header');
+    return value;
+}

package/dist/io/xlsb/record-types.d.ts

@@ -0,0 +1,55 @@
+/** BIFF12 record numbers, grouped by the part whose stream they appear in. */
+export declare const BRT: {
+    readonly RowHdr: 0;
+    readonly CellBlank: 1;
+    readonly CellRk: 2;
+    readonly CellError: 3;
+    readonly CellBool: 4;
+    readonly CellReal: 5;
+    readonly CellSt: 6;
+    readonly CellIsst: 7;
+    readonly FmlaString: 8;
+    readonly FmlaNum: 9;
+    readonly FmlaBool: 10;
+    readonly FmlaError: 11;
+    readonly CellRString: 62;
+    readonly ColInfo: 60;
+    readonly MergeCell: 176;
+    readonly SSTItem: 19;
+    readonly BeginSst: 159;
+    readonly EndSst: 160;
+    readonly Fmt: 44;
+    readonly Font: 43;
+    readonly Fill: 45;
+    readonly Border: 46;
+    readonly XF: 47;
+    readonly Style: 48;
+    readonly BeginFmts: 615;
+    readonly EndFmts: 616;
+    readonly BeginFonts: 611;
+    readonly EndFonts: 612;
+    readonly BeginFills: 603;
+    readonly EndFills: 604;
+    readonly BeginBorders: 613;
+    readonly EndBorders: 614;
+    readonly BeginCellStyleXFs: 626;
+    readonly EndCellStyleXFs: 627;
+    readonly BeginCellXFs: 617;
+    readonly EndCellXFs: 618;
+    readonly BeginStyles: 619;
+    readonly EndStyles: 620;
+    readonly BundleSh: 156;
+    readonly BeginBundleShs: 143;
+    readonly EndBundleShs: 144;
+    readonly Name: 39;
+    readonly BeginExternals: 353;
+    readonly EndExternals: 354;
+    readonly SupSelf: 357;
+    readonly ExternSheet: 362;
+    readonly WsProp: 147;
+    readonly WsDim: 148;
+    readonly WsFmtInfo: 485;
+    readonly BeginSheetData: 145;
+    readonly EndSheetData: 146;
+    readonly ArrFmla: 426;
+};