@shbernal/ts-xlsx 1.1.0 → 1.2.0

package/dist/io/opc/rels.js

@@ -1,28 +1,15 @@
-// The write side of the relationship graph: a single `<Relationship>` element and the `.rels` part
-// envelope that wraps a set of them. Pure OPC — a `.rels` part has the same shape whatever the parts
-// it wires together are spelled in, so this is stated once here rather than inside a codec.
-//
-// The reader's half of the same graph (resolving targets, walking a part closure) is in `read-opc.ts`.
 import { escapeAttr, XML_DECLARATION } from '../../xml/xml.js';
 import { PKG_RELS_NS } from './namespaces.js';
-// A single `<Relationship>`. An `external` target lives outside the package (a hyperlink URL), so the
-// element carries `TargetMode="External"`; a package-internal target (the default) omits it. The caller
-// escapes the target when it is not a writer-controlled package path.
 export function relationship(id, type, target, options) {
     const mode = options?.external ? ' TargetMode="External"' : '';
     return `<Relationship Id="${id}" Type="${type}" Target="${target}"${mode}/>`;
 }
-// Wrap a part's `<Relationship>` elements in the OPC `.rels` envelope (XML declaration + the namespaced
-// `<Relationships>` root). Every `.rels` part the writer emits shares this envelope; only the elements
-// inside differ, so each caller builds its own list of {@link relationship} strings and hands them here.
 export function relationshipsPart(relationships) {
     return `${XML_DECLARATION}<Relationships xmlns="${PKG_RELS_NS}">${relationships.join('')}</Relationships>`;
 }
 export function preservedRelsXml(rels) {
     return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, escapeAttr(rel.target), rel.external ? { external: true } : {})));
 }
-// A `.rels` part for a generated part chain (pivot table → cache definition → cache records). Targets
-// are writer-controlled package paths, so no attribute escaping is needed.
 export function relsPartXml(rels) {
     return relationshipsPart(rels.map((rel) => relationship(rel.id, rel.type, rel.target)));
 }

package/dist/io/opc/sniff-format.js

@@ -1,31 +1,7 @@
-// Front of the read pipe: format detection, the inflate bound both readers share, and the typed
-// rejection of everything that is neither an `.xlsx` nor an `.xlsb`.
-//
-// The reader's first job on an arbitrary blob is to reject what it cannot read with a clear, typed
-// error rather than a raw fflate crash. A cheap magic-byte sniff runs *before* the zip layer (so a
-// legacy `.xls` compound file or non-ZIP garbage fails fast, before fflate throws its opaque "end of
-// central directory" error — which can also leak an absolute path from below), and a malformed ZIP is
-// translated after it.
-//
-// The two outcomes are deliberately different types, because they answer different questions. A blob
-// the sniff rejects is the *wrong kind of thing* — {@link UnsupportedFormatError}, branchable on
-// `.format`. A `PK`-headed blob the zip layer then chokes on is the right kind of thing we cannot
-// unpack — {@link PackageReadError}. Whichever it is, the message states the check that actually ran,
-// and callers branch on the type, never on message text.
-//
-// The `.xlsx` and `.xlsb` serialisations share this whole layer — same container, same bound, same
-// rejections — so it is stated once here and neither reader owns it.
 import { PackageReadError, UnsupportedFormatError } from './errors.js';
 import { inflatePackage } from './inflate.js';
-// The OLE2 / Compound File Binary signature ([MS-CFB] 2.2) that opens every legacy `.xls` (and the
-// `.doc`/`.ppt` siblings). `src/vba/cfb.ts` reads this same magic for `vbaProject.bin`; here we need
-// only recognise it, not parse the container.
 const CFB_MAGIC = Uint8Array.of(0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1);
-// The ZIP local-file-header signature (`PK\x03\x04`) that opens every OPC package — `.xlsx`, `.xlsb`,
-// and the rest. An empty or spanned archive starts with a different `PK` marker, but a real workbook
-// package always leads with a local file header.
 const ZIP_LOCAL_FILE_MAGIC = Uint8Array.of(0x50, 0x4b, 0x03, 0x04);
-/** Classify a blob's container by its leading magic bytes alone — no allocation, no inflation. */
 export function sniffContainer(data) {
     if (startsWith(data, CFB_MAGIC))
         return 'cfb';
@@ -42,24 +18,10 @@ function startsWith(data, magic) {
     }
     return true;
 }
-/**
- * Inflate a spreadsheet package (`.xlsx` or `.xlsb` — the container is the same), translating input
- * that is neither into a typed error before or instead of a raw zip failure:
- * - a legacy `.xls` (CFB) blob → {@link UnsupportedFormatError} `'xls'`, caught by the magic sniff so
- *   fflate never runs on it;
- * - a non-ZIP blob → {@link UnsupportedFormatError} `'unknown'`, likewise caught before inflation;
- * - a `PK`-headed blob that fflate then rejects as malformed → {@link PackageReadError}, with the
- *   underlying zip message discarded so no internals (or path) leak.
- *
- * The bounded-inflation guard (a probable zip bomb) already raises {@link PackageReadError} with its
- * own informative message, and is re-thrown unchanged.
- */
 export function inflateSpreadsheetPackage(data, cap) {
     const container = sniffContainer(data);
     if (container === 'cfb')
         throw new UnsupportedFormatError('xls');
-    // Not the default message: nothing here has looked for a workbook part, and saying so would point
-    // an investigation a layer past the one that actually refused.
     if (container === 'other') {
         throw new UnsupportedFormatError('unknown', 'not a valid .xlsx package: the input is not a ZIP');
     }
@@ -67,23 +29,11 @@ export function inflateSpreadsheetPackage(data, cap) {
         return inflatePackage(data, cap);
     }
     catch (err) {
-        // The bomb guard already throws the right type with a better message — surface it. Anything else
-        // is fflate reporting a malformed archive: same classification (a ZIP we cannot unpack), but its
-        // raw text is replaced wholesale rather than wrapped or attached as `cause`, because it comes from
-        // a layer whose strings may name internals — or an absolute path — that must not reach a caller.
         if (err instanceof PackageReadError)
             throw err;
         throw new PackageReadError('not a readable .xlsx package: the ZIP container is corrupt or truncated and could not be inflated');
     }
 }
-/**
- * The typed error for an inflated package that carries no `xl/workbook.xml`: a `.xlsb` if its binary
- * `xl/workbook.bin` office document is present, otherwise an unrecognised (non-workbook) ZIP.
- *
- * The `.xlsb` branch takes the caller's own explanation, because whether a binary workbook is
- * readable now depends on *which* entry point was asked: `readXlsx` reads one, the row streamer
- * cannot yet. A single baked-in "not supported" message would be wrong for one of them.
- */
 export function unsupportedWorkbookPart(partText, xlsbMessage) {
     if (partText('xl/workbook.bin') !== undefined) {
         return new UnsupportedFormatError('xlsb', xlsbMessage);

package/dist/io/style/xf-style.js

@@ -1,17 +1,5 @@
-// The resolved cell-format table both codecs read into: what an xf *is* once its id-indirection is
-// flattened, which of the two number-format tables an id resolves against, and what applying an xf to
-// a cell means.
-//
-// None of that is a property of how the style table is spelled — `xl/styles.xml` and `xl/styles.bin`
-// state the same model in XML and BIFF12 records — so it is stated once here, above both codecs. The
-// XML parsing lives in `../xlsx/read-styles.ts`, the record parsing in `../xlsb/read-styles.ts`, and
-// each hands back the same {@link StyleTable}.
 import { applyCellStyle } from '../../core/cell.js';
 import { NAMED_STYLE_ID } from '../../core/internal.js';
-// ECMA-376 reserves numFmt ids below 164 for formats every consumer knows implicitly, so a
-// foreign file may name one with no <numFmt> entry. This maps the standard ids to their
-// codes; id 0 (General) and any unknown id resolve to no format. The writer never emits
-// these — it always defines a custom id — but reading them keeps foreign files faithful.
 const BUILTIN_NUMFMTS = new Map([
     [1, '0'],
     [2, '0.00'],
@@ -40,11 +28,6 @@ const BUILTIN_NUMFMTS = new Map([
     [47, 'mmss.0'],
     [48, '##0.0E+0'],
     [49, '@'],
-    // Ids 27..36 and 50..58 are reserved for locale-specific built-in East Asian date/time formats;
-    // a file authored in a CJK locale styles date cells with them and, being built-ins, emits no
-    // <numFmt>. The exact code is locale-defined — these are the representative Excel forms — but what
-    // matters for reading is that each resolves to a non-empty date/time code so the serial reads as a
-    // date rather than a bare number.
     [27, '[$-404]e/m/d'],
     [28, '[$-404]e"年"m"月"d"日"'],
     [29, '[$-404]e"年"m"月"d"日"'],
@@ -65,25 +48,11 @@ const BUILTIN_NUMFMTS = new Map([
     [57, '[$-404]yyyy"年"m"月"'],
     [58, '[$-404]m"月"d"日"'],
 ]);
-/**
- * The format code a number-format id denotes: the file's own `<numFmt>`/`BrtFmt` declaration if it
- * has one, else the built-in Excel defines for that id. Id 0 is General — the absence of a format —
- * and resolves to nothing so an ordinary cell carries no `numFmt`.
- */
 export function numFmtCodeFor(id, custom) {
     if (!Number.isInteger(id) || id === 0)
         return undefined;
     return custom.get(id) ?? BUILTIN_NUMFMTS.get(id);
 }
-/**
- * Apply a resolved xf's non-value facets to a cell — the six {@link CellStyle} facets through the
- * shared {@link applyCellStyle}, plus the two links that live on the xf itself rather than in the
- * facet tuple (`quotePrefix`, and the `xfId` pointer into the named-style layer).
- *
- * Shared by every path that commits a cell: the XML reader's ordinary and shared-formula-clone paths,
- * and the BIFF12 reader — so a styled cell keeps its look regardless of which serialisation it came
- * from, and the two cannot drift on what "applying a style" means.
- */
 export function applyXfToCell(cell, style) {
     if (style === undefined)
         return;

package/dist/io/xlsb/errors.js

@@ -1,14 +1,4 @@
 import { XlsxError } from '../../errors.js';
-/**
- * Thrown when an `.xlsb` package's binary BIFF12 content cannot be parsed — a record whose declared
- * size runs past the end of its part, a truncated record header, or a structure that does not conform
- * to [MS-XLSB].
- *
- * The record streams are hostile input (a spreadsheet library parses untrusted files), so a malformed
- * part fails closed with this error rather than crashing, hanging, or over-allocating. It is distinct
- * from {@link UnsupportedFormatError}, which reports that the *container* is not a format we read at
- * all; by the time this is raised the input has already been recognised as an `.xlsb`.
- */
 export class XlsbParseError extends XlsxError {
     name = 'XlsbParseError';
     code = 'malformed-input';

package/dist/io/xlsb/formula.js

@@ -1,47 +1,11 @@
-// Decoding a BIFF12 `Ptg` token stream back into formula text — the one place where the binary and
-// XML serialisations of a workbook are genuinely different *languages* rather than different spellings.
-//
-// An `.xlsx` stores `SUM(A1:A5)/COUNT(A1:A5)` as those nineteen characters. An `.xlsb` stores the same
-// formula as a postfix (reverse-Polish) token stream: two range operands, two calls, a divide. So the
-// decoder is a stack machine — each operand pushes its own text, each operator pops what it needs and
-// pushes the joined result, and a well-formed stream leaves exactly one string behind.
-//
-// Two things make the reconstruction exact rather than approximate:
-//
-//   - **Parentheses are stored, not inferred.** Excel emits an explicit `PtgParen` wherever the author
-//     typed one, so there is no precedence arithmetic here and no risk of `(1+2)*3` reading back as
-//     `1+2*3`. The token stream already says which is which.
-//   - **A reference names no sheet.** A 3-D reference carries an *index* into the workbook's
-//     `BrtExternSheet` table, which in turn names a span of sheets in a supporting book. Resolving
-//     that indirection — and re-quoting the sheet name the way Excel would — is what turns token
-//     `ixti=2` back into `'Odd Name'!A1`.
-//
-// **A token this decoder does not know makes the whole formula undecodable, by design.** The stream is
-// self-describing only if every token's length is known, so guessing past an unrecognised token would
-// desynchronise the parse and produce confident nonsense. Instead the decoder returns `undefined` and
-// its caller keeps what it can still trust — the cached result Excel stored beside the formula. The
-// gaps that reach that path are listed in `docs/knowledge/specs/xlsb-binary-format-output.md`.
 import { MAX_COLUMN, numberToColumn } from '../../core/address.js';
 import { quoteSheetName } from '../../core/formula.js';
 import { errorCodeFor, RecordReader } from './primitives.js';
 import { FTAB_USER_DEFINED, fixedArityFor, functionNameFor } from './ptg-functions.js';
-/**
- * Decode a `CellParsedFormula`'s token stream into formula text, in the same on-disk spelling the XML
- * form writes into `<f>` — `_xlfn.`-prefixed function names included, so the caller applies the same
- * `unmangleFunctions` normalisation to either serialisation.
- *
- * @param rgce the token stream.
- * @param rgcb the trailing extra-data block: the array constants, and the cell ranges a precomputed
- *   range token refers to. Its entries are consumed in token order.
- * @returns the formula text, or `undefined` if the stream uses a token this reader does not decode.
- * @throws {XlsbParseError} if a token runs past the end of the stream (a malformed formula).
- */
 export function decodeFormula(rgce, rgcb, scope) {
     const tokens = new RecordReader(rgce);
     const extra = new RecordReader(rgcb);
     const stack = [];
-    // Pushing `undefined` is how an undecodable token is reported without unwinding: the loop stops and
-    // the arity check below rejects the stream. It keeps every token case a plain expression.
     const push = (text) => {
         if (text === undefined)
             return false;
@@ -54,13 +18,6 @@ export function decodeFormula(rgce, rgcb, scope) {
     }
     return stack.length === 1 ? stack[0] : undefined;
 }
-/**
- * The master cell a token stream defers to, when the stream is nothing but a `PtgExp` (a shared or
- * array formula's member) or a `PtgTbl` (a data-table cell) rather than a formula of its own.
- *
- * The column lives in the extra-data block rather than the token, which is the one place BIFF12
- * splits a single reference across the two halves of a `CellParsedFormula`.
- */
 export function formulaAnchor(rgce, rgcb) {
     if (rgce.length !== 5 || (rgce[0] !== PTG.Exp && rgce[0] !== PTG.Tbl))
         return undefined;
@@ -72,7 +29,6 @@ export function formulaAnchor(rgce, rgcb) {
         return undefined;
     return { row, column: extra.u32() };
 }
-// One token: decode it, mutate the stack, and report whether the stream is still decodable.
 function step(ptg, tokens, extra, stack, scope, push) {
     const binary = BINARY_OPERATORS.get(ptg);
     if (binary !== undefined) {
@@ -94,7 +50,6 @@ function step(ptg, tokens, extra, stack, scope, push) {
             return operand !== undefined && push(`(${operand})`);
         }
         case PTG.MissArg:
-            // An omitted argument — `IF(A1>0,,1)` — is a real operand whose text is nothing at all.
             return push('');
         case PTG.Str:
             return push(quoteString(tokens.shortString()));
@@ -109,18 +64,15 @@ function step(ptg, tokens, extra, stack, scope, push) {
         case PTG.Num:
             return push(numberText(tokens.f64()));
         default:
-            // Every remaining token is an operand or call whose meaning is independent of its result class
-            // (reference, value, or array) — the class only tells the calculation engine how to coerce it.
             return ptg >= CLASSED_TOKEN_FLOOR
                 ? operand((ptg & CLASSED_TOKEN_MASK) | CLASSED_TOKEN_FLOOR, tokens, extra, stack, scope, push)
                 : false;
     }
 }
-// A class-carrying operand or call token, reduced to its base ptg.
 function operand(base, tokens, extra, stack, scope, push) {
     switch (base) {
         case PTG.Array:
-            tokens.skip(14); // A size hint the extra-data block restates; the block is the authority.
+            tokens.skip(14);
             return push(arrayConstant(extra));
         case PTG.Func: {
             const name = functionNameFor(tokens.u16());
@@ -130,8 +82,6 @@ function operand(base, tokens, extra, stack, scope, push) {
         case PTG.FuncVar:
             return variadicCall(tokens, stack, push);
         case PTG.Name: {
-            // Cited 1-based, and into the *unfiltered* name list — the placeholder names Excel registers for
-            // post-2007 functions occupy indices too, even though they are not the workbook's defined names.
             return push(scope.names[tokens.u32() - 1]);
         }
         case PTG.Ref:
@@ -161,38 +111,23 @@ function operand(base, tokens, extra, stack, scope, push) {
             tokens.skip(14);
             return push(REFERENCE_ERROR);
         case PTG.MemArea:
-            // A precomputed range: the tokens it was computed from follow inline, so the header is skipped
-            // and the walk simply continues into them. Its extra-data entry — the resulting rectangles — is
-            // a calculation shortcut with nothing to say about the text, but must still be consumed in order.
             tokens.skip(6);
             return skipExtraRanges(extra);
         default:
             return false;
     }
 }
-// `PtgAttr` ([MS-XLSB] 2.5.97.1): a family of hints the calculation engine leaves in the stream.
-// Almost all are invisible in the formula text — the jump offsets an `IF` uses to skip the branch it
-// did not take, the marker on a volatile function. The one that carries meaning is `bitSum`, Excel's
-// encoding of a single-argument `SUM`, which is a call by any other name.
 function attribute(tokens, stack, push) {
     const flags = tokens.u8();
     const data = tokens.u16();
     if ((flags & ATTR_CHOOSE) !== 0) {
-        // The one variable-length attribute: `data` counts CHOOSE's branches, each with a jump offset,
-        // plus one for the end of the call.
         tokens.skip((data + 1) * 2);
         return true;
     }
     if ((flags & ATTR_SUM) !== 0)
         return push(call('SUM', 1, stack));
-    // `bitSpace` records whitespace the author typed around a token. It is cosmetic — Excel redisplays
-    // the formula identically without it — and reattaching it to the right operand is not something a
-    // postfix walk can do, so it is dropped rather than misplaced.
     return true;
 }
-// `PtgFuncVar` ([MS-XLSB] 2.5.97.4): a call whose argument count is in the token. Index 255 is not a
-// function at all but the indirection every post-2007 function is called through: the name comes from
-// the stream's first operand, which is a `PtgName` pointing at Excel's `_xlfn.`-prefixed placeholder.
 function variadicCall(tokens, stack, push) {
     const count = tokens.u8() & FUNCVAR_PARAM_MASK;
     const index = tokens.u16() & FUNCVAR_INDEX_MASK;
@@ -206,16 +141,11 @@ function variadicCall(tokens, stack, push) {
     const [name, ...args] = parts;
     return push(`${name}(${args.join(',')})`);
 }
-// Pop `arity` arguments and push the call. Arguments were pushed left to right, so they come off the
-// stack as one contiguous run in source order.
 function call(name, arity, stack) {
     if (stack.length < arity)
         return undefined;
     return `${name}(${stack.splice(stack.length - arity, arity).join(',')})`;
 }
-// `PtgExtraArray` ([MS-XLSB] 2.5.97.2): the elements of an array constant, row-major, behind a
-// row/column count. The element encodings are fixed-width apart from the string, which carries its
-// own length — so the block is walked, never indexed.
 function arrayConstant(extra) {
     const rows = extra.u32();
     const columns = extra.u32();
@@ -234,7 +164,6 @@ function arrayConstant(extra) {
     }
     return `{${lines.join(';')}}`;
 }
-// One `SerAr` ([MS-XLSB] 2.5.129) element of an array constant.
 function arrayElement(extra) {
     switch (extra.u8()) {
         case SER_NUM:
@@ -252,7 +181,6 @@ function arrayElement(extra) {
             return undefined;
     }
 }
-// Consume the `PtgExtraMem` a precomputed-range token owns: a count, then that many cell ranges.
 function skipExtraRanges(extra) {
     const count = extra.u32();
     if (count * RANGE_BYTES > extra.remaining)
@@ -260,8 +188,6 @@ function skipExtraRanges(extra) {
     extra.skip(count * RANGE_BYTES);
     return true;
 }
-// The sheet part of a 3-D reference, `Data!` or `'Odd Name'!` or `Data:More!`, from the index the
-// token carries into the workbook's extern-sheet table.
 function sheetPrefix(ixti, scope) {
     const xti = scope.externSheets[ixti];
     if (xti === undefined || xti.supBook !== scope.selfSupBook)
@@ -272,8 +198,6 @@ function sheetPrefix(ixti, scope) {
         return undefined;
     return `${first === last ? quoteSheetName(first) : quoteSheetName(first, last)}!`;
 }
-// A single cell, from the row and the packed column word every reference token shares. The two high
-// bits of that word say whether each axis is relative, which is exactly where the `$` signs go.
 function cellText(row, packedColumn) {
     const column = packedColumn & COLUMN_MASK;
     if (row > MAX_ROW_INDEX || column >= MAX_COLUMN)
@@ -282,9 +206,6 @@ function cellText(row, packedColumn) {
     const rowAbs = (packedColumn & ROW_RELATIVE) === 0 ? '$' : '';
     return `${columnAbs}${numberToColumn(column + 1)}${rowAbs}${row + 1}`;
 }
-// A range. A range that spans every row of its columns, or every column of its rows, is written in
-// Excel's abbreviated form (`A:A`, `2:2`) — which is not cosmetic: it is the only spelling Excel
-// writes for a whole-column reference, so anything else would fail to match the XML twin.
 function rangeText(rowFirst, rowLast, packedFirst, packedLast) {
     if (rowFirst === 0 && rowLast === MAX_ROW_INDEX) {
         const first = columnOnly(packedFirst);
@@ -309,19 +230,13 @@ function columnOnly(packedColumn) {
 function rowOnly(row, packedColumn) {
     return `${(packedColumn & ROW_RELATIVE) === 0 ? '$' : ''}${row + 1}`;
 }
-// A string literal, in the formula's own escaping: the delimiter is a double quote, and a double quote
-// inside the text is doubled.
 function quoteString(text) {
     return `"${text.replace(/"/g, '""')}"`;
 }
-// A numeric literal. JavaScript and Excel agree on every ordinary number; they part company only at
-// the exponent's case, which is normalised here so `1E+21` does not read back as `1e+21`.
 function numberText(value) {
     return String(value).toUpperCase();
 }
 const REFERENCE_ERROR = '#REF!';
-// The infix operators, by their ptg. `PtgIsect` is Excel's space operator (`A1:A3 A2:A5`) and
-// `PtgUnion` its comma — both are operators despite looking like punctuation.
 const BINARY_OPERATORS = new Map([
     [0x03, '+'],
     [0x04, '-'],
@@ -339,9 +254,6 @@ const BINARY_OPERATORS = new Map([
     [0x10, ','],
     [0x11, ':'],
 ]);
-// The token numbers this decoder names. Operand tokens are listed at their *base* value: the stream
-// carries them offset by a result class (+0x20 value, +0x40 array), which changes how the calculation
-// engine coerces the operand but never what it says.
 const PTG = {
     Exp: 0x01,
     Tbl: 0x02,
@@ -372,27 +284,17 @@ const PTG = {
 };
 const CLASSED_TOKEN_FLOOR = 0x20;
 const CLASSED_TOKEN_MASK = 0x1f;
-// `PtgAttr` flag bits.
 const ATTR_CHOOSE = 0x04;
 const ATTR_SUM = 0x10;
-// `PtgFuncVar`'s two packed fields each reserve their top bit for a flag the text does not carry.
 const FUNCVAR_PARAM_MASK = 0x7f;
 const FUNCVAR_INDEX_MASK = 0x7fff;
-// The packed column word shared by every reference token: 14 bits of column, then the two relative-
-// axis flags.
 const COLUMN_MASK = 0x3fff;
 const COLUMN_RELATIVE = 0x4000;
 const ROW_RELATIVE = 0x8000;
 const MAX_ROW_INDEX = 1048575;
-// `SerAr` element tags.
 const SER_NUM = 0x00;
 const SER_STR = 0x01;
 const SER_BOOL = 0x02;
 const SER_ERR = 0x04;
-// An `UncheckedRfX` is four 32-bit bounds.
 const RANGE_BYTES = 16;
-// A bound on an array constant's declared size. The elements themselves are read from the extra-data
-// block, which cannot outrun its own record — but the row × column product is multiplied *before* any
-// of it is read, and a forged pair would otherwise buy a loop of its own choosing. Excel's own limit
-// on an array constant is far below this.
 const MAX_ARRAY_ELEMENTS = 1 << 20;

package/dist/io/xlsb/primitives.js

@@ -1,35 +1,8 @@
-// The [MS-XLSB] primitive types a record payload is built from, behind one bounds-checked cursor.
-//
-// Binary parsing is where a reader most easily goes wrong in two directions at once: silently reading
-// past the end of a buffer, and allocating on a length the file (not the reader) chose. `RecordReader`
-// closes both. Every read goes through a single `#take`, so overrunning the record is impossible
-// rather than merely unlikely; and a length-prefixed string checks its byte count against what the
-// record actually holds *before* a single character is materialised, so a forged `cch` costs one
-// comparison instead of gigabytes.
-//
-// Structures decoded here — RkNumber, XLWideString, BrtColor, Cell, UncheckedRfX, BErr — are shared
-// across the workbook, worksheet, styles, and shared-string parsers; nothing part-specific lives here.
 import { isErrorCode } from '../../core/value.js';
 import { XlsbParseError } from './errors.js';
-// A length-prefixed string is decoded in code-unit batches rather than one `String.fromCharCode` call
-// per character (quadratic concatenation) or one spread of every unit (which blows the argument limit
-// on a long string). 4096 is comfortably under every engine's limit and makes the batching invisible.
 const CHARS_PER_BATCH = 4096;
-// `XLNullableWideString` marks "no string" with a character count of 0xFFFFFFFF rather than 0 — an
-// empty string and an absent one are different values (a sheet's relationship id is nullable; its
-// name is not).
 const NULL_STRING_LENGTH = 0xffffffff;
-// One reusable 8-byte window for reassembling an RkNumber's truncated double. The alternative — a
-// fresh ArrayBuffer per RK cell — would allocate once per numeric cell in the workbook, on the single
-// hottest path in the reader. Safe to share: the write and the read below are one synchronous pair.
 const rkScratch = new DataView(new ArrayBuffer(8));
-/**
- * A bounds-checked cursor over one record's payload.
- *
- * Each accessor advances the cursor by exactly the bytes it consumed, so a record is decoded by
- * naming its fields in order. Reading past the payload throws {@link XlsbParseError} — a record that
- * is shorter than its own definition is a malformed file, not a case to guess through.
- */
 export class RecordReader {
     #data;
     #view;
@@ -38,24 +11,15 @@ export class RecordReader {
         this.#data = data;
         this.#view = new DataView(data.buffer, data.byteOffset, data.byteLength);
     }
-    /** Bytes left in the record. */
     get remaining() {
         return this.#data.length - this.#offset;
     }
-    /** Whether the whole payload has been consumed. */
     get done() {
         return this.remaining <= 0;
     }
-    /** Advance past `count` bytes without decoding them — a reserved or unmodelled field. */
     skip(count) {
         this.#take(count);
     }
-    /**
-     * The next `count` bytes as a **view**, for a field whose own decoding happens elsewhere — a formula
-     * token stream, whose meaning depends on workbook tables this record knows nothing about. A view
-     * rather than a copy for the same reason a record's payload is one: the declared length comes from
-     * the file, so it must bound a read, never an allocation.
-     */
     bytes(count) {
         return this.#data.subarray(this.#take(count), this.#offset);
     }
@@ -74,57 +38,32 @@ export class RecordReader {
     i32() {
         return this.#view.getInt32(this.#take(4), true);
     }
-    /** An `Xnum` ([MS-XLSB] 2.5.172): a little-endian IEEE-754 double. */
     f64() {
         return this.#view.getFloat64(this.#take(8), true);
     }
-    /**
-     * An `RkNumber` ([MS-XLSB] 2.5.122): a number packed into 32 bits. Two flag bits steal the low end
-     * of the word — `fInt` says the remaining 30 bits are a signed integer rather than the *high* 30
-     * bits of a double whose low 34 bits are zero, and `fX100` says the result was scaled up by 100 to
-     * keep two decimal places in the integer form. It exists because most real spreadsheet numbers are
-     * small integers or two-decimal currency, and this stores them in half the bytes of a double.
-     */
     rk() {
-        // Read signed: the `fInt` branch needs an arithmetic shift to sign-extend a negative 30-bit
-        // integer, which only works on a value JavaScript already considers negative.
         const raw = this.i32();
         const value = (raw & 0b10) !== 0 ? raw >> 2 : truncatedDouble(raw & ~0b11);
         return (raw & 0b01) !== 0 ? value / 100 : value;
     }
-    /** An `XLWideString` ([MS-XLSB] 2.5.169): a 4-byte character count then that many UTF-16LE units. */
     wideString() {
         return this.#characters(this.u32());
     }
-    /**
-     * A UTF-16 string whose character count is 16-bit rather than 32-bit — the form used *inside* a
-     * formula token stream (`PtgStr`, and the string elements of an array constant), where a 4-byte
-     * count on every literal would be pure overhead.
-     */
     shortString() {
         return this.#characters(this.u16());
     }
-    /** An `XLNullableWideString` ([MS-XLSB] 2.5.166): an {@link wideString} that can also be absent. */
     nullableWideString() {
         const length = this.u32();
         return length === NULL_STRING_LENGTH ? undefined : this.#characters(length);
     }
-    /**
-     * A `RichStr` ([MS-XLSB] 2.5.124): a string that may carry per-run formatting and phonetic guides.
-     * Only the text is returned — the run and phonetic tails are left unread, which is safe because the
-     * record's framing (not this cursor) bounds where the payload ends.
-     */
     richString() {
-        this.skip(1); // fRichStr / fExtStr flags: which optional tails follow the text.
+        this.skip(1);
         return this.wideString();
     }
-    /** The `Cell` structure ([MS-XLSB] 2.5.10) that opens every cell record. */
     cell() {
         const column = this.u32();
-        // The style index shares its word with a phonetic-display flag in the high byte.
         return { column, styleIndex: this.u32() & 0x00ffffff };
     }
-    /** An `UncheckedRfX` ([MS-XLSB] 2.5.155): four zero-based, inclusive range bounds. */
     range() {
         return {
             rowFirst: this.u32(),
@@ -133,14 +72,6 @@ export class RecordReader {
             colLast: this.u32(),
         };
     }
-    /**
-     * A `BrtColor` ([MS-XLSB] 2.4.337), mapped onto the model's {@link Color}.
-     *
-     * The four encodings are mutually exclusive and the type tag picks which of the payload's fields
-     * carry meaning; the rest are explicitly undefined. An *automatic* colour (type 0) names nothing at
-     * all, and reads back as no colour — the same absence the XML reader produces for `<color auto="1"/>`,
-     * so a cell whose font colour was never set does not gain one on read.
-     */
     color() {
         const flags = this.u8();
         const index = this.u8();
@@ -152,15 +83,11 @@ export class RecordReader {
         const base = colorByType(flags >> 1, index, alpha, red, green, blue);
         if (base === undefined)
             return undefined;
-        // Tint is stored as a fraction of the signed 16-bit range, where the extreme values mean 100%
-        // lightening/darkening; the model carries it as OOXML does, in [-1, 1].
         if (tintAndShade === 0)
             return base;
         return { ...base, tint: Math.max(-1, Math.min(1, tintAndShade / 0x7fff)) };
     }
     #characters(count) {
-        // Check the byte count against the record *before* building anything: this is the guard that
-        // makes a forged character count a cheap failure rather than an allocation the file chose.
         const start = this.#take(count * 2);
         let text = '';
         let batch = [];
@@ -173,8 +100,6 @@ export class RecordReader {
         }
         return batch.length > 0 ? text + String.fromCharCode(...batch) : text;
     }
-    // The single choke point every read passes through. Returns the offset the caller may read from,
-    // having proven that `count` bytes are there.
     #take(count) {
         if (count > this.remaining) {
             throw new XlsbParseError(`BIFF12 record field needs ${count} bytes but only ${this.remaining} remain in the record`);
@@ -184,7 +109,6 @@ export class RecordReader {
         return start;
     }
 }
-/** A `BErr` ([MS-XLSB] 2.5.98.2) error code, as the model's error string. */
 export function errorCodeFor(code) {
     const text = BERR_CODES.get(code);
     return text !== undefined && isErrorCode(text) ? text : undefined;
@@ -199,14 +123,11 @@ const BERR_CODES = new Map([
     [0x2a, '#N/A'],
     [0x2b, '#GETTING_DATA'],
 ]);
-// Rebuild the double whose *high* 32 bits are `high` and whose low 34 bits [MS-XLSB] guarantees to be
-// zero. Written big-endian so the given word lands in the high half regardless of host endianness.
 function truncatedDouble(high) {
     rkScratch.setInt32(0, high, false);
     rkScratch.setUint32(4, 0, false);
     return rkScratch.getFloat64(0, false);
 }
-// The `xColorType` tag ([MS-XLSB] 2.4.337) selects which of a BrtColor's fields carry the colour.
 const COLOR_TYPE_INDEXED = 1;
 const COLOR_TYPE_RGB = 2;
 const COLOR_TYPE_THEME = 3;
@@ -217,9 +138,6 @@ function colorByType(type, index, alpha, red, green, blue) {
         case COLOR_TYPE_RGB:
             return { argb: hexByte(alpha) + hexByte(red) + hexByte(green) + hexByte(blue) };
         case COLOR_TYPE_THEME:
-            // The binary theme index and OOXML's `theme="…"` attribute both count the `clrScheme`
-            // subelements in declaration order (dk1, lt1, dk2, lt2, accent1–6, hlink, folHlink), so the
-            // index carries across unchanged.
             return { theme: index };
         default:
             return undefined;