xls-codec 1.0.2 → 2.0.0

package/README.md

@@ -2,35 +2,135 @@
 
 [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/xls-codec) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/xls-codec) [![npm version](https://img.shields.io/npm/v/xls-codec)](https://www.npmjs.com/package/xls-codec) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)
 
-> Hand-written reader for the legacy Excel Binary File Format (`.xls`, BIFF8) as specified by [MS-XLS], mapping a workbook's record stream onto the same `document-schema.js` spreadsheet model `ooxml.js`'s xlsx support and `odf.js`'s ods support target. Worker-isomorphic: the same code runs under Node and inside a Cloudflare Workers isolate.
+> Hand-written reader and writer for the legacy Excel Binary File Format (`.xls`, BIFF8) as specified by [MS-XLS], mapping a workbook's record stream onto the same `document-schema.js` spreadsheet model `ooxml.js`'s xlsx support and `odf.js`'s ods support target. Worker-isomorphic: the same code runs under Node and inside a Cloudflare Workers isolate.
 
-A `.xls` file is not one format but two nested ones. The outer container is an [MS-CFB] compound file — the same "filesystem in a file" that carries `.doc` and `.ppt` — holding a stream named `Workbook`. Inside that stream is BIFF8: a flat sequence of records, each a two-byte type, a two-byte size, and that many bytes of data, organised into substreams delimited by `BOF`/`EOF`. This package leaves the outer layer to [`archive-codec`](../archive-codec/README.md)'s bounded CFB reader and implements the inner one, from the record framing up to a `ContentDocument`.
+A `.xls` file is not one format but two nested ones. The outer container is an [MS-CFB] compound file — the same "filesystem in a file" that carries `.doc` and `.ppt` — holding a stream named `Workbook`. Inside that stream is BIFF8: a flat sequence of records, each a two-byte type, a two-byte size, and that many bytes of data, organised into substreams delimited by `BOF`/`EOF`. This package leaves the outer layer to [`archive-codec`](../archive-codec/README.md)'s bounded CFB reader and writer and implements the inner one, from the record framing up to a `ContentDocument` and back.
 
 ## Status
 
-Under active development, **read-only**. Built and shipped:
+Under active development, with real, tested **read and write** support. Built and shipped:
 
-- **Record framing** (`src/biff/records.ts`) — the three-component record structure of [MS-XLS] 2.1.4, with the 8224-byte data ceiling enforced and every malformed stream thrown on rather than silently truncated.
-- **Continuation-aware cursor and strings** (`src/biff/cursor.ts`, `src/biff/strings.ts`) — `Continue` records ([MS-XLS] 2.4.58) joined per the rules of the record being continued, including the case a naive reader gets wrong: an `XLUnicodeRichExtendedString` ([MS-XLS] 2.5.293) resuming after a boundary re-states its own `fHighByte` flag, which may differ from the flag the string started with. All three string shapes (`XLUnicodeString`, `ShortXLUnicodeString`, `XLUnicodeRichExtendedString`) are read.
-- **Workbook globals** (`src/workbook/globals.ts`) — `BoundSheet8` (sheet names, tab order, hidden state, type, and substream offsets), `SST` with its `Continue` chain, `Format` (custom number-format codes), `XF`'s fixed prefix (font index, format identifier, style flag), and `Date1904`.
-- **Worksheet substreams** (`src/workbook/sheet.ts`) — `Dimensions`, `Row` (height and hidden state), `ColInfo` (width and hidden state, expanded across the column range it covers), `MergeCells`, and the whole cell-value family: `Blank`, `MulBlank`, `RK`, `MulRk`, `Number`, `BoolErr`, `LabelSst`, `Label`, and `Formula` with its `String` result record.
-- **Number-format classification and date serials** (`src/number-format.ts`, `src/serial.ts`) — what turns a bare number into the schema's own `percentage`/`currency`/`date`/`time`/`dateTime` value kinds, honouring the workbook's own epoch flag and refusing the 1900 system's phantom leap day.
-- **Schema mapping** (`src/content.ts`) — `readXlsContent` produces a `ContentDocument` of `kind: 'spreadsheet'`, and `readXls` the tree-form `DocumentTree`, in the same shape `readXlsxContent`/`readXlsx` produce: sparse 0-based cells, `displayText` on every cell, merged ranges as `colSpan`/`rowSpan` on the anchor cell, and the producer's raw format code kept alongside the classified value.
+- **Record framing** (`src/biff/records.ts`, `src/biff/record-writer.ts`) — the three-component record structure of [MS-XLS] 2.1.4 in both directions, with the 8224-byte data ceiling enforced and every malformed or oversized stream thrown on rather than silently truncated or split into a `Continue` chain the writer does not implement.
+- **Continuation-aware cursor and strings** (`src/biff/cursor.ts`, `src/biff/strings.ts`, `src/biff/string-writer.ts`) — `Continue` records ([MS-XLS] 2.4.58) joined per the rules of the record being continued on read, including the case a naive reader gets wrong: an `XLUnicodeRichExtendedString` ([MS-XLS] 2.5.293) resuming after a boundary re-states its own `fHighByte` flag, which may differ from the flag the string started with. All three string shapes (`XLUnicodeString`, `ShortXLUnicodeString`, `XLUnicodeRichExtendedString`) are read and written, compressed (one byte per UTF-16 code unit) whenever every character allows it and uncompressed otherwise.
+- **Workbook globals**, read (`src/workbook/globals.ts`) and write (`src/workbook/globals-writer.ts`) — `BoundSheet8` (sheet names, tab order, hidden state, type, and substream offsets), `SST` with its `Continue` chain on read, `Format` (custom number-format codes), `Font`, `XF`'s fixed prefix plus its trailing `CellXF`/`StyleXF` fill/border payload in both directions (`src/biff/xf-colors.ts`'s shared bit-layout packing/unpacking; see [Cell decoration](#cell-decoration)), `Palette` in both directions, the fifteen mandatory built-in `Style` records, and `Date1904`.
+- **Worksheet substreams**, read (`src/workbook/sheet.ts`) and write (`src/workbook/sheet-writer.ts`) — `Dimensions`, `Row` (height and hidden state), `ColInfo` (width and hidden state), `MergeCells`, the print-settings record group (see [Print settings](#print-settings)), and the cell-value family: `Number`, `BoolErr`, `LabelSst`, and `Blank` on write (`MulBlank`, `RK`, `MulRk`, `Label`, and `Formula` with its `String` result record are read-only — see below).
+- **Number-format classification and date serials** ([`excel-number-format`](../excel-number-format/README.md), `src/serial.ts`) — what turns a bare number into the schema's own `percentage`/`currency`/`date`/`time`/`dateTime` value kinds and back, honouring the workbook's own epoch flag (the writer always emits the 1900 system) and refusing the 1900 system's phantom leap day in both directions. The classification itself is a dependency, not local code: this package shares it with `ooxml.js`'s xlsx support, since it is the identical mini-language in both formats (ExaDev/documents.js#848). A cell's own `numberFormatCode` is preserved verbatim on write when present; absent, it resolves to a representative built-in code for its value kind (`General` for a plain number/string/boolean/error, `0%` for a percentage, a bare `$` format for a currency with no code, `mm-dd-yy`/`h:mm:ss`/`m/d/yy h:mm` for date/time/dateTime), and the workbook-wide `Format`/`XF` table is deduplicated across every sheet so two cells sharing one code share one entry.
+- **Formula text recovery** (`src/biff/ptg.ts`, `src/biff/ptg-functions.ts`) — a Formula record's compiled `rgce` token stream ([MS-XLS] 2.5.198's `Ptg` vocabulary) read and rebuilt into the infix text a spreadsheet application would show: literal operands (`PtgInt`/`PtgNum`/`PtgStr`/`PtgBool`/`PtgErr`/`PtgMissArg`), cell and range references including their 3D (cross-sheet) forms (`PtgRef`/`PtgArea`/`PtgRef3d`/`PtgArea3d`, `$`-qualified per their own relative/absolute flags, a 3D reference's sheet name resolved through `EXTERNSHEET` and a self-referencing `SupBook` — `src/workbook/globals.ts`'s own `sheetRanges`), every arithmetic/comparison/unary/percent operator and explicit parentheses, and function calls through both `PtgFunc` (fixed arity, resolved from a curated table of [MS-XLS]'s own Ftab grammar) and `PtgFuncVar` (variable arity, its own on-disk `cparams`) — see "Formula expressions" under Read-side gaps below for the exact boundary of what this does not resolve.
+- **Schema mapping** — `readXlsContent`/`readXls` (`src/content.ts`) as before, now also populating `ContentSheetCell.formula` wherever the Ptg reader above resolves it; `writeXlsContent`/`writeXls` (`src/write.ts`) the counterpart, taking a `ContentDocument`/`DocumentTree` of `kind: 'spreadsheet'` and producing genuine `.xls` bytes: a real BIFF8 `Workbook` stream (globals substream, one worksheet substream per sheet, `BoundSheet8.lbPlyPos` patched to each sheet's real byte offset once every substream's length is known) wrapped in a real [MS-CFB] compound file via `archive-codec`'s `writeCompoundFile`.
+- **Document metadata** — `title`/`subject`/`author`/`keywords`/`createdIso`/`modifiedIso` read from a `"\x05SummaryInformation"` stream when one is present, and written back to one whenever the input's metadata carries anything that stream can hold (see [Metadata](#metadata)).
+- **Cell decoration** — a cell's background fill (solid pattern only) and per-side borders, read from and written to `XF`'s trailing `CellXF` payload plus the workbook's own `Palette` record, in both directions and verified against real LibreOffice-produced BIFF8, not just this package's own round trip (see [Cell decoration](#cell-decoration)).
+- **Print settings** — every field of `ContentSheetPrintSettings`: page size and orientation, all four margins, gridline and row/column-header printing, page order, print scale or fit-to-page counts, manual page breaks, the print range, and the repeated header rows and columns — read from and written to the nine worksheet-substream records and the two built-in defined names that carry them, in both directions and verified against real LibreOffice-produced BIFF8 (see [Print settings](#print-settings)).
+- **Cell alignment** — a cell's own horizontal (`left`/`center`/`right`/`justify`) and vertical (`top`/`middle`) alignment, read from and written to `XF`'s trailing `CellXF`/`StyleXF` payload's own leading word, in both directions and verified against real LibreOffice-produced BIFF8 (see [Cell alignment](#cell-alignment)).
 
-### Not built yet
+Verified primarily by round trip (`src/write.test.ts`, plus a dedicated `test/workers/write.test.ts` proving the whole write path inside a real `workerd` isolate, not just Node): build a `ContentDocument`, write it, read it back through this package's own independently-pinned reader, and check the result. Every record's own byte layout is additionally cited to its [MS-XLS] section in the writer's source, matching the reader's own convention.
 
-**The write path**, which is the substantial one. A conformant workbook has to emit a `BOF` history block, a complete `XF`/`Font`/`Format` table with the fifteen mandatory style records preceding any cell format, an `Index`/`DBCell` row-block lookup structure whose file offsets must agree with where the records actually land, and a compound file to put the resulting `Workbook` stream into. The container half is no longer missing — [`archive-codec`](../archive-codec/README.md)'s `writeCompoundFile` writes [MS-CFB] as well as reading it — so what remains here is the BIFF8 record emission itself. Shipping a plausible-looking writer that produced files Excel rejects would be worse than shipping none. Tracked on [#815](https://github.com/ExaDev/documents.js/issues/815).
+### Writer scope
 
-Read-side gaps, each deliberate rather than overlooked:
+What `writeXlsContent`/`writeXls` cover: every `ContentCellValue` kind a real `.xls` can hold (`number`, `percentage`, `currency`, `boolean`, `date`, `time`, `dateTime`, `string`, `error`; an `empty` cell is written as a `Blank` record when it carries formatting and as nothing at all when it does not — see below), merged ranges (`colSpan`/`rowSpan`), row heights and hidden rows, column widths and hidden columns, multiple sheets, explicit and default number formats, a shared string table deduplicated across the whole workbook, every field of a sheet's own [print settings](#print-settings), a cell's own [alignment](#cell-alignment), and — see [Cell decoration](#cell-decoration) — a cell's own solid background fill and per-side borders, deduplicated across the workbook the same way number formats are. What it deliberately does not:
 
-- **Formula expressions.** A `Formula` record's cached _result_ is read, so a formula cell shows the right value, but `ContentSheetCell.formula` stays absent. BIFF8 stores the expression as a compiled `Ptg` token stream rather than as text, and recovering it means implementing the whole `Ptg` vocabulary plus shared-formula (`ShrFmla`) and external-reference (`SupBook`/`ExternSheet`) resolution.
-- **Cell decoration** — fill, borders, and alignment from `XF`'s trailing `CellXF` payload, whose colours are palette indices needing the `Palette` record and the default colour table to resolve. `Font` records are not read either: `ContentSheetCell` has no cell-level font field, and `ooxml.js`'s xlsx reader likewise maps only the number format and decoration from a cell format.
-- **Print settings** are emitted as Excel's documented "Normal" preset rather than read from the file. The real values need `Setup` (including its paper-size code table), the four margin records, `PrintGrid`, and `PrintRowCol`.
-- **Workbook metadata** — `metadata` is empty. Title, author, and dates live in the `\x05SummaryInformation` property-set stream ([MS-OSHARED]), a different format from BIFF8 sitting beside it in the same container.
-- **Not read at all:** charts, drawings and images, cell comments (`Note`/`Txo`), data validation, conditional formatting, and defined names (`Lbl`).
+| Not written                                                                                                        | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Formula` records                                                                                                  | The read side now recovers a formula's expression for the cells it resolves (see Read-side gaps below), but writing one back out is a materially larger task — encoding text back into `Ptg` tokens, choosing built-in function indices, and (for anything the reader could not resolve in the first place) having no formula to write at all — scoped as its own separate piece of work rather than folded into recovering the read side. A `ContentSheetCell.formula` is silently ignored on write; only the cell's own typed `value` is written.                                                                                                                                                                                                                                |
+| Per-cell font                                                                                                      | The reader does not read one back: `ContentSheetCell` has no cell-level font field at all (`ooxml.js`'s xlsx reader makes the identical font-scope choice), so writing a real value here would be unverifiable by round trip. Every `XF` this writer emits still references the same single font.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `MulBlank`/`RK`/`MulRk`                                                                                            | Pure compaction optimisations over information a plain `Blank`/`Number`/`LabelSst`/`BoolErr` record already carries losslessly. (`Blank` itself _is_ written, for a formatted empty cell — see the `empty` row below.)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| An `empty`-kind cell carrying no formatting                                                                        | Written as nothing at all, which is what round-trips: `content.ts`'s reader drops an unformatted blank cell it reads, and a merged range's empty anchor is independently reconstructed from `MergeCells` alone. A formatted one (a fill, a border, or a non-default alignment) is the opposite case — its formatting exists only in the `XF` a cell record names, so it gets a real `Blank` record ([MS-XLS] 2.4.20) and round-trips with that formatting intact.                                                                                                                                                                                                                                                                                                                  |
+| Images, embedded objects, comments (`Note`/`Txo`), data validation, conditional formatting, defined names (`Lbl`)  | Not read either (see below); there is no round trip to verify a writer for them against.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| A page size no `iPaperSize` code names                                                                             | Written as [MS-XLS] 2.4.257's own custom-paper value rather than as a named paper it is not — the dimensions themselves are unwritable, since `Setup` addresses paper only by code. See [Print settings](#print-settings).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `Window1`/`Window2`, `CodePage`, `Index`/`DBCell`, the legacy interface records (`InterfaceHdr`, `WriteAccess`, …) | UI and interoperability bookkeeping [MS-XLS]'s own grammar names in the globals/worksheet substreams alongside the content-carrying records above, not data. `Index`/`DBCell` specifically is a pure cell-lookup performance optimisation (see [MS-XLS]'s own "Retrieval of Last-Calculated Cell Values Without Loading Cell Table") that this reader — and Excel's own reader — does not require to find a cell; real, well-established minimal BIFF8 writers (e.g. Python's `xlwt`) omit the same set and produce files Excel opens correctly. The calculation-state records (`CalcCount`, `CalcRefMode`, `CalcIter`, `CalcDelta`, `CalcSaveRecalc`) sat in this row until print settings needed them — see [Print settings](#print-settings) for why the writer emits them now. |
+| `Continue`-chain splitting                                                                                         | A record whose data would exceed the 8224-byte single-record ceiling ([MS-XLS] 2.1.4) — an extremely long shared string, an enormous shared string table, or thousands of merged ranges in one sheet — is refused with a thrown `BiffWriteError` rather than silently split across `Continue` records.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+
+Column widths round-trip to the nearest pixel Excel's own integer-pixel-grid quantization allows (matching the read direction's own "honestly approximate" contract, `units.ts`), never narrower than requested. A `.xls` cell outside BIFF8's own grid (65536 rows, 256 columns) is refused rather than silently wrapped or truncated.
+
+### Read-side gaps
+
+Each deliberate rather than overlooked:
+
+- **Formula expressions, mostly recovered.** A `Formula` record's compiled `Ptg` token stream (`src/biff/ptg.ts`) is walked and rebuilt into real formula text — literal operands, cell/range references (`$`-qualified, including 3D cross-sheet references resolved through `EXTERNSHEET` and a self-referencing `SupBook`), every arithmetic/comparison/unary/percent operator, explicit parentheses, and both fixed- and variable-arity function calls, resolved by name against [MS-XLS]'s own built-in function table (`src/biff/ptg-functions.ts`, covering the whole published table — [MS-XLS] 2.5.198.17 — cited to that table's own `iftab` index; PtgFunc's fixed argument count is a curated subset of it, since PtgFunc's own token carries no count and only a function [MS-XLS]'s grammar states a fixed, non-optional arity for is resolved through it, empirically confirmed against real LibreOffice-written BIFF8 rather than assumed from the grammar alone). Three constructs remain genuinely unresolved, each leaving `ContentSheetCell.formula` absent for that cell specifically rather than fabricating text: a **shared formula** (`PtgExp`, whose real expression lives in a separate `ShrFmla` record this reader does not yet join), an **array formula** (`PtgArray`, whose literal values live in a separate `PtgExtraArray` trailer this reader does not yet parse), and a **genuinely external workbook** reference (a `SupBook` naming another file, a DDE/OLE data source, or an add-in, rather than this same workbook) — each is real, meaningfully separate work, not an oversight. A defined name (`PtgName`/`PtgNameX`) and a natural-language "Elf" reference are likewise not resolved, for the same reason `Lbl` (defined names) is not read at all yet (see below).
+- **Cell decoration and alignment resolved for real; font still not.** `XF`'s trailing `CellXF` payload's fill pattern/colour and per-side border style/colour are read and resolved through the `Palette` record (or the default colour table when one is absent) — see [Cell decoration](#cell-decoration) for the full mapping, the fill-pattern-beyond-solid judgment call, and how this was verified against real LibreOffice-produced BIFF8. The same payload's leading word is resolved too — see [Cell alignment](#cell-alignment) for the full `alc`/`alcV` mapping. `Font` records are not read at all: `ContentSheetCell` has no cell-level font field, and `ooxml.js`'s xlsx reader makes the identical scope choice.
+- **Print settings, resolved for real.** Every field of `ContentSheetPrintSettings` is read from the records that carry it, with Excel's own "Normal" preset standing in per field for whatever the file leaves unstated — see [Print settings](#print-settings) for the record map, the two of BIFF8's own conditional rules that decide how to read `Setup`, and the three things that genuinely do not come through.
+- **Not read at all:** charts, drawings and images, cell comments (`Note`/`Txo`), data validation, and conditional formatting. Defined names (`Lbl`) are read only for the two built-in ones a sheet's print range and repeated header bands live in ([Print settings](#print-settings)); a user-defined name has nowhere to land in `document-schema.js`'s spreadsheet model, so it is skipped.
 - **Encrypted workbooks** are refused rather than mis-read: a `FilePass` record means every record after it is ciphertext.
 
-This package is also not yet wired into `documents.js`'s conversion registry — it stands alone.
+This package is wired into `documents.js`'s conversion registry (`xlsToPdf`/`pdfToXls`, `convertDocument("xls", ...)`, and every same-variant spreadsheet bridge) — see that package's own README Fidelity table for exactly which pairs route and which don't. Remaining read+write scope gaps (formula writing, shared/array/external-reference formulas, and per-cell font) are tracked on [#815](https://github.com/ExaDev/documents.js/issues/815).
+
+## Cell decoration
+
+A cell's own solid background fill and per-side borders are read from and written to `XF`'s trailing `CellXF`/`StyleXF` payload ([MS-XLS] 2.4.353) and the workbook's own `Palette` record ([MS-XLS] 2.4.188), verified both by round trip and against a real, independent BIFF8 implementation — [ExaDev/documents.js#815](https://github.com/ExaDev/documents.js/issues/815) as a scoped chunk of that issue's own broader tracking, not a claim of closing it outright. `src/biff/xf-colors.ts` is the one place the payload's border/fill bit layout is packed or unpacked, shared by `workbook/globals.ts`'s read side and `biff/xf-writer.ts`'s write side, so the two directions cannot silently disagree on what a given byte means.
+
+**Colour resolution.** A fill or border colour is a 7-bit `icv` index into BIFF8's own colour table ([MS-XLS] "Icv"): 0-7 name eight fixed built-in colours (this package's writer never emits one of these, per the spec's own "SHOULD NOT be ≤ 0x07"; the reader still resolves them, for a real third-party file that does), 8-63 index into either the workbook's own `Palette` record when one is present or a fixed 56-entry default table when it is not. The writer scans every distinct decoration colour a workbook's cells use before writing anything: when every one already matches the default table exactly, no `Palette` record is written at all, keeping an undecorated-adjacent file as minimal as it always was; the moment even one colour falls outside that table, a real 56-entry `Palette` record is minted, with every distinct colour the workbook actually uses (not only the non-default ones) assigned its own dedicated slot, so the whole table is self-consistent rather than a mix of "the file's own entries" and "the implicit default".
+
+**Fill patterns beyond solid — a deliberate judgment call, not an oversight.** [MS-XLS]'s own `FillPattern` enumeration names nineteen patterns: no fill, solid, four grey shades, and stripe/crosshatch families. `ContentSheetCell.background` models exactly one flat colour, so only `FLSSOLID` maps onto it — using the pattern's own foreground colour (`icvFore`), which [MS-XLS] itself documents as the only colour a solid fill actually renders ("If this value is 1, then only `icvFore` is rendered"). Every other pattern reads as no background at all. Approximating a 50% grey crosshatch or a diagonal stripe as its own foreground colour would misreport what the cell actually shows, so this reader leaves it unmapped rather than guessing; this package's own writer never emits anything but `FLSNULL`/`FLSSOLID` either, so a round trip never needs to invent a lossy pattern encoding on the way back out.
+
+**Borders.** Each of a cell's four sides carries its own [MS-XLS] `BorderStyle` line-style token and colour, mapped onto `ContentBorder`'s `widthPt`/`style` pair the same way `ooxml.js`'s own `typed/xlsx/styles.ts` maps xlsx's border tokens: four named weights — hair/thin/medium/thick, at 0.5/0.75/1.5/2.25pt, derived from Excel's own documented 96-DPI rendering and held once in [`document-schema.js`](../document-schema.js/README.md)'s own `border-weight` module, which this package and `ooxml.js` both import rather than each keeping a copy of it — crossed with a pattern (solid/dashed/dotted/double); the dash-family tokens (`dashDot`, `dashDotDot`, and their medium/slant variants) collapse to `'dashed'`, the closest `ContentStrokeStyle` member, exactly as `ooxml.js`'s equivalent table does for xlsx's own dash tokens. Diagonal borders (`dgDiag`/`grbitDiag`) are out of scope — `ContentCellBordersSchema` has no diagonal member — and are always read as absent, always written as none.
+
+**Verified against a real, independent BIFF8 implementation, not just this package's own reader/writer pair.** A `.xls` built directly by LibreOffice (`soffice --headless --convert-to xls`, from a hand-authored `.fods` declaring real `fo:background-color`/`fo:border*` cell styles) is read correctly by this package's own reader — every fill and border colour matched exactly against what LibreOffice's own subsequent re-export of the same bytes independently confirms them to be, and every border's named weight and pattern resolved to the same [MS-XLS] `BorderStyle` token LibreOffice wrote. The named weight is where the two implementations stop agreeing on a number, and necessarily so: BIFF8 stores a name (`thin`, `medium`, `thick`), not a width, so LibreOffice's re-export states its own rendered widths (0.74/1.76/2.49pt) for the same tokens this package renders at 0.75/1.5/2.25pt. Both are honest readings of the same bytes. And a `.xls` this package writes — including one whose colours force a real `Palette` record, proving that path specifically — opens in LibreOffice with the correct fill and borders, confirmed by converting it back through `soffice --headless --convert-to fods` and inspecting the cell styles LibreOffice itself recovers from it.
+
+The decorated-blank case was checked the same way, in both directions and against the same implementation: a `.fods` whose one styled cell has a fill and four borders but no value converts to a `.xls` in which LibreOffice writes a real `Blank` record, and this reader recovers that cell's fill colour and all four border colours exactly; a `.xls` this package writes for the equivalent `empty` cell converts back to a `.fods` in which LibreOffice recovers a valueless cell carrying the same `fo:background-color` and `fo:border` colours — at its own 0.74pt rendering of the `thin` weight, per the note above.
+
+**Decoration on a cell with no value.** A cell can be empty and still have something to show, and BIFF8 says so with a `Blank` record ([MS-XLS] 2.4.20) — a cell header naming an `XF` and nothing else, written precisely because that `XF` carries a fill or a border. Both directions honour it: a `Blank` or `MulBlank` whose `XF` resolves to real decoration is read as an `empty`-kind cell carrying that decoration rather than dropped, and an `empty` cell carrying a background or a border is written back as a `Blank` record pointing at an `XF` encoding it. An empty cell with no decoration is still written as nothing at all and still read as absent, which is what keeps `ContentSheet`'s cell array sparse; "decoration this reader can express" is the same test the value-cell path applies, so a fill pattern beyond solid or an unresolvable colour leaves a blank cell dropped exactly as before.
+
+A per-cell font remains out of scope in both directions — see [Read-side gaps](#read-side-gaps) and [Writer scope](#writer-scope) above. The payload's leading word, once similarly out of scope, is now [Cell alignment](#cell-alignment) below.
+
+## Cell alignment
+
+A cell's own horizontal and vertical alignment are read from and written to the same `XF` trailing `CellXF`/`StyleXF` payload [Cell decoration](#cell-decoration) covers ([MS-XLS] 2.4.353), but a different pair of fields within it: `alc` and `alcV`, the leading word's own bits 0-2 and 4-6 ([MS-XLS] [`HorizAlign`](https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/75e17a8f-9cd4-4b37-927e-4b0a54ef9266) and [`VertAlign`](https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/1e9eb7d3-0cd8-42a3-af1e-f523105a5e93)) — verified both by round trip and against a real, independent BIFF8 implementation, the identical bar [Cell decoration](#cell-decoration) and [Print settings](#print-settings) are held to. `src/biff/xf-colors.ts` is the one place `alc`/`alcV` are packed or unpacked in either direction (`resolveHorizontalAlignment`/`horizAlignTokenFor` and `resolveVerticalAlignment`/`vertAlignTokenFor`), so the two directions cannot silently disagree on what a given bit pattern means.
+
+**Only the members `ContentSheetCell.alignment`/`verticalAlignment` can express survive, matching `ooxml.js`'s own xlsx alignment policy exactly.** `HorizAlign` names eight members; only `ALCLEFT`/`ALCCTR`/`ALCRIGHT`/`ALCJUST` have an `Alignment` counterpart (`left`/`center`/`right`/`justify`). `ALCGEN` — general alignment — is the identical semantics to `alignment` being absent (the schema's own "numeric right, text left" value-kind default already means the same thing), so it round-trips to and from `undefined` rather than a literal member that would override the default it means to request. `ALCFILL`/`ALCCONTCTR`/`ALCDIST` are real members with no schema counterpart at all and are left unread, the same policy `odf.js`'s own alignment reader applies to a construct its schema has no member for. `VertAlign` names five members; only `ALCVTOP`/`ALCVCTR` have a `verticalAlignment` counterpart (`top`/`middle`). `ALCVBOT` is the schema's own documented default for an absent `verticalAlignment` ("no value-kind default to fall back to, so its own absence means `'bottom'` outright"), so it round-trips to and from `undefined` the same way `ALCGEN` does; `ALCVJUST`/`ALCVDIST` are left unread for the identical reason `ALCFILL`/`ALCCONTCTR`/`ALCDIST` are.
+
+**Interned into the cell-XF table alongside decoration, not a separate table.** `write.ts`'s own `buildCellXfPlan` already deduplicated cells sharing an identical (number format, decoration) pair into one `XF` record; the interning key is now a (number format, alignment, vertical alignment, decoration) tuple, so two cells sharing all four still share one record and a cell differing in only its alignment still mints its own. A cell with General formatting, no alignment, and no decoration still resolves to the workbook's own implicit `GENERAL_CELL_XF_INDEX` with no new `XF` record at all, exactly as before alignment was modelled.
+
+**Formatting on a cell with no value, widened.** [Cell decoration](#cell-decoration)'s own `Blank`-record rule (a decorated empty cell is worth a record; an undecorated one is written as nothing at all) now triggers on alignment too: `written-cells.ts`'s `cellCarriesFormatting` (renamed from `cellCarriesDecoration` when this was added) treats a non-default `alignment` or `verticalAlignment` the same way it already treats a background or a border. An empty cell stating only `alignment: 'center'` therefore gets a real `Blank` record and round-trips with that alignment intact, rather than being silently dropped as if it had nothing to say.
+
+**Verified against a real, independent BIFF8 implementation, not just this package's own reader/writer pair.** A `.xls` this package writes — one cell per `Alignment` member, one per `verticalAlignment` member, and one combining a non-default horizontal and vertical alignment on the same cell — opens in LibreOffice 26.2.5.2 with every alignment intact, confirmed by converting it back through `soffice --headless --convert-to fods` and inspecting the cell styles LibreOffice itself recovers: each `left`/`center`/`right`/`justify` cell reads back as LibreOffice's own `fo:text-align="start"/"center"/"end"/"justify"`, each `top`/`middle` cell as `style:vertical-align="top"/"middle"`, and the combined cell as both at once on the identical style. Going the other way, a `.xls` built directly by LibreOffice (`soffice --headless --convert-to xls`, from a hand-authored `.fods` declaring the same real `fo:text-align`/`style:vertical-align` cell styles) is read correctly by this package's own reader, every cell recovering the exact alignment LibreOffice's own style declared.
+
+## Print settings
+
+Every field of `document-schema.js`'s own `ContentSheetPrintSettings` is read from and written to the BIFF8 records that carry it, verified both by round trip and against a real, independent BIFF8 implementation — [ExaDev/documents.js#815](https://github.com/ExaDev/documents.js/issues/815) as a scoped chunk of that issue's own broader tracking, not a claim of closing it outright. The two directions had to land together: before this, the reader returned Excel's fixed "Normal" preset for every sheet regardless of what the file said, so there was nothing to verify a writer's output against.
+
+**One sheet's print settings live in two substreams, not one.** The page setup is in the sheet's own substream, as the optional records of [MS-XLS] 2.1.7.20.6's own `GLOBALS` and `PAGESETUP` productions. The print range and the repeated header bands are not there at all: BIFF8 keeps them in the workbook globals substream, as ordinary defined names ([MS-XLS] 2.4.150's `Lbl` record) carrying a built-in name index rather than a user-typed name, scoped to one sheet through the record's own `itab`. `src/workbook/print-names.ts` is both directions of exactly those two names; `src/biff/print-setup.ts` is the one place the `Setup` record's own bit layout and paper-size code table are packed or unpacked, shared by the read and write sides so the two cannot silently disagree.
+
+| Schema field                   | Where BIFF8 keeps it                                                                                                                        |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pageSize`                     | `Setup`'s `iPaperSize` code ([MS-XLS] 2.4.257), transposed to landscape by its own `fPortrait`/`fNoOrient` flags                            |
+| `margins`                      | `LeftMargin`/`RightMargin`/`TopMargin`/`BottomMargin` ([MS-XLS] 2.4.151, 2.4.219, 2.4.328, 2.4.27), each a single `Xnum` of inches          |
+| `gridlines`                    | `PrintGrid`'s `fPrintGrid` ([MS-XLS] 2.4.202)                                                                                               |
+| `headers`                      | `PrintRowCol`'s `printRwCol` ([MS-XLS] 2.4.203) — the row/column header chrome, not a repeated print band                                   |
+| `pageOrder`                    | `Setup`'s `fLeftToRight`                                                                                                                    |
+| `scalePercent` / `fitToPages`  | `Setup`'s `iScale` or its `iFitWidth`/`iFitHeight` pair, selected by `WsBool`'s own `fFitToPage` bit ([MS-XLS] 2.4.351)                     |
+| `manualBreaks`                 | `HorizontalPageBreaks`/`VerticalPageBreaks` ([MS-XLS] 2.4.142, 2.4.343)                                                                     |
+| `printRange`                   | The built-in `Print_Area` defined name (`Lbl` with built-in index `0x06`), whose `rgce` is a `PtgArea3d` naming the range                   |
+| `repeatRows` / `repeatColumns` | The built-in `Print_Titles` name (index `0x07`), whose `rgce` is a `PtgMemFunc` wrapping one or two `PtgArea3d` tokens joined by `PtgUnion` |
+
+**Every record behind these is optional, and every field falls back independently.** A sheet whose page setup was never touched carries no `Setup` and no margin records at all, so something has to stand in — Excel's own "Normal" preset (top/bottom 0.75in, left/right 0.7in, Letter paper, gridlines and headers not printed, pages down-then-over), the same constants `ooxml.js` falls back to for an xlsx carrying no `pageMargins` element, so the same untouched sheet reads identically from either format. The fallback is per field rather than wholesale: a sheet declaring a left margin and nothing else keeps its real left margin and takes the preset for the other three.
+
+**Two of BIFF8's own conditional rules are honoured rather than flattened.** A `Setup` record whose `fNoPls` bit is set declares its own paper size and scale undefined ([MS-XLS] 2.4.257: "whether the `iPaperSize`, `iScale`, `iRes`, `iVRes`, `iCopies`, `fNoOrient`, and `fPortrait` data are undefined and ignored"), so neither is read from it — the page size falls back to the preset and no `scalePercent` is reported, rather than a paper code the file itself disowns being resolved into a confident page size. And `WsBool`'s `fFitToPage` decides which of `Setup`'s two mutually exclusive scaling fields is live: real producers write both regardless of which is active (confirmed against LibreOffice-written BIFF8, which carries `iScale=100` alongside a real fit-to-page pair, and a real `iScale` alongside `iFitWidth=iFitHeight=1`), so reading both would report a scale and a page count that contradict each other.
+
+**A repeated band's axis is its shape, not a field.** BIFF8 has no flag saying which axis a `Print_Titles` band repeats along: a repeated row band is written as an area spanning every column of the sheet (`$1:$2`, columns 0-255) and a repeated column band as one spanning every row (`$A:$A`, rows 0-65535). Both directions use that shape as the discriminant, and an area spanning both axes at once names the whole sheet — which is neither — so it is left unclassified rather than assigned to whichever branch happened to be tested first.
+
+**Three things do not come through, each for a reason in the format rather than an oversight:**
+
+- **A page size no `iPaperSize` code names loses its dimensions.** Unlike xlsx's own `pageSetup` element, which can state an explicit `paperWidth`/`paperHeight` pair, `Setup` addresses paper only by code; its escape hatch for a size outside the table is a printer-defined custom size carried in a separate `Pls` record ([MS-XLS] 2.4.199), a printer driver's opaque `DEVMODE` blob rather than a pair of dimensions any reader could recover a size from. So the writer emits `iPaperSize` 0 — that section's own "custom printer paper sizes" — which is true, where substituting Letter would not be; the reading application then falls back to its own default paper (this package to the preset, LibreOffice to its locale's), and every other print setting on the sheet still comes through. Refusing the file outright was the first thing tried and is the wrong trade: a spreadsheet converted from a slide deck or a drawing carries that source's own canvas as its page size, which is almost never a named paper, and failing the conversion would lose the cells too. The code table this package does map is the office paper sizes of [MS-XLS]'s own 118-entry enumeration — the Letter/Legal/Tabloid/Executive/Statement family, A2 through A6, B4/B5 in both the JIS and ISO spellings, Folio and Quarto — each derived from the inches or millimetres that table itself states rather than from pre-converted points, and each matched within half a point so a page size picking up conversion drift on its way between codecs still resolves.
+- **A "fit to as many pages as necessary" axis has no schema spelling.** `Setup` documents `iFitWidth`/`iFitHeight` of 0 as "use as many pages as necessary to print the columns/rows in the sheet", and `ContentSheetPrintSettings.fitToPages` requires both counts to be positive. A fit-to-page sheet with an auto axis therefore reports no `fitToPages` at all rather than a fabricated 1, which would claim the sheet is pinned to a single page along an axis the file left free.
+- **An explicit 100% scale reads back as no declared scale.** `Setup`'s `iScale` is a mandatory field of a mandatory record with no spelling for "this sheet declares no scale", so an untouched sheet still states 100 — and `ContentSheetPrintSettings` already means exactly that by carrying no `scalePercent` at all. The two spellings print identically, so the reader collapses them onto the absent one rather than putting a field carrying no actionable information on every sheet of every workbook it reads. A scale that is genuinely anything else is reported exactly as the file states it.
+
+Two further deliberate narrowings, both because the schema models less than BIFF8 states: a `Print_Area` naming several disjoint areas (legal in BIFF8, and what Excel writes for a multi-area print selection) yields only the first, since `printRange` models one rectangle and merging several into their bounding box would claim cells print that do not; and a BIFF8 page break carries an extent along the perpendicular axis, which `manualBreaks` — an index with no extent — cannot express, so a partial break is carried as a full one and two breaks on the same row collapse into one.
+
+**Verified against a real, independent BIFF8 implementation, not just this package's own reader/writer pair.** Three `.xls` files built directly by LibreOffice (`soffice --headless --convert-to xls`, from hand-authored `.fods` files declaring a real page layout, print range, header rows and columns, and manual breaks) read back through this package with every field matching what was authored: A4 landscape, four distinct margins, gridlines and headers on or off, `overThenDown` page order, an 80% scale and a 2x3 fit-to-page pair, a row break at row 10, a column break at column 3, a `B2:D6` print range, two repeated header rows, and one repeated header column. Going the other way, a `.xls` this package writes for the same content opens in LibreOffice with every one of those fields intact, confirmed by converting it back through `soffice --headless --convert-to fods` and comparing LibreOffice's own re-export of our file against its re-export of its own, attribute by attribute. A fourth file, written with a page size no paper code names, opens in LibreOffice with its own default paper substituted and every other print setting and cell intact — the custom-paper behaviour above, checked rather than assumed. The `Print_Area` record this writer emits is byte-for-byte the one LibreOffice writes for the same range (`src/workbook/print-names.test.ts` asserts exactly that against the real bytes); the `Print_Titles` record differs by one byte, a trailing `PtgParen` display token this writer has no reason to emit.
+
+**Why this writer now emits the calculation-state records.** [MS-XLS] 2.1.7.20.6's `GLOBALS` production makes `CalcCount`, `CalcRefMode`, `CalcIter`, `CalcDelta` and `CalcSaveRecalc` mandatory ahead of `PrintRowCol`, and this writer previously omitted them along with the rest of BIFF8's UI and interoperability bookkeeping. That turned out to matter: LibreOffice's own importer silently discards whichever page-settings record comes first in a worksheet substream, so with `PrintRowCol` in that slot, a `.xls` this package wrote with row and column headers enabled opened in LibreOffice with them off — while every other print setting in the same file came through correctly. Moving any other record into that slot fixes it, and the records the grammar already required there are the honest way to do it. Confirmed by writing the same workbook with and without them and re-reading each through `soffice --convert-to fods`.
+
+## Metadata
+
+A `.xls`'s title, author, and dates do not live in any BIFF8 record at all — they live in a `"\x05SummaryInformation"` stream, a genuinely different format ([MS-OLEPS] Property Set Streams, [MS-OSHARED] 2.3.3.2.2's own naming of the specific properties Office uses) that happens to sit beside `Workbook` in the same [MS-CFB] compound file. `readXlsContent` reads that stream when present (`archive-codec`'s `readSummaryInformation`, since the property-set format itself is zero document-format knowledge, exactly as the [MS-CFB] container it sits inside is) and maps it onto `document-schema.js`'s `LayoutMetadata` (`archive-codec`'s own `summaryInformationToLayoutMetadata` — the mapping is format-agnostic, so it lives there rather than being copied in this package, alongside `doc-codec`'s and `ppt-codec`'s identical need for it); `writeXlsContent` does the inverse (`src/metadata.ts`'s `layoutMetadataToSummaryInformation`, which validates `createdIso`/`modifiedIso` as real dates and throws a `BiffWriteError` naming the offending field before delegating to `archive-codec`'s own mapping), including a `"\x05SummaryInformation"` stream in its `writeCompoundFile` call only when the input's metadata actually carries something that stream can hold — an input whose metadata is `{}`, or carries only fields the mapping below has no destination for, produces no stream at all, matching what an absent-metadata read already returns.
+
+The mapping is not 1:1, and each gap is permanent rather than a remaining TODO:
+
+| Direction                           | Fields covered                                                                         | Gap                                                                                                                                                                                                                                 |
+| ----------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SummaryInformation → LayoutMetadata | `title`, `subject`, `author`, `keywords`, `createdIso`, `lastSavedIso` → `modifiedIso` | `comments` and `lastPrintedIso` have no LayoutMetadata field to land in — no other codec in the family has a "last printed" or free-text "comments" concept, so these are read from the stream but never reach a `ContentDocument`. |
+| LayoutMetadata → SummaryInformation | the same six fields, in reverse                                                        | `creator`, `producer`, and `language` have no SummaryInformation equivalent: `producer` is a PDF-only concept in this schema, and `creator`/`language` are not among the fields the stream this package writes covers.              |
+
+Only the fixed SummaryInformation property set is read or written — the sibling `"\x05DocumentSummaryInformation"` stream (company, manager, and custom user-defined properties, [MS-OLEPS]'s two-property-set spelling) is not attempted at all, an explicit scope boundary `archive-codec`'s own `oleps` support shares.
 
 ## Getting started
 
@@ -65,10 +165,10 @@ if (isXlsFile(bytes)) {
 The record layer is exported in its own right, for a caller inspecting a workbook rather than converting it:
 
 ```ts
-import { readRecords, readWorkbookStream } from "xls-codec";
+import { readRecords, readWorkbookStreams } from "xls-codec";
 
-const stream = readWorkbookStream(bytes); // the raw BIFF8 record stream out of the compound file
-for (const rec of readRecords(stream)) {
+const { workbook } = readWorkbookStreams(bytes); // the raw BIFF8 record stream out of the compound file, plus the optional "\x05SummaryInformation" stream beside it
+for (const rec of readRecords(workbook)) {
   console.log(rec.type.toString(16), rec.data.length);
 }
 ```
@@ -85,9 +185,13 @@ Layered bottom-up, each layer testable against hand-built byte sequences taken f
 - **`src/biff/records.ts`** — the record framing, and nothing above it. Deliberately does not merge `Continue` records: whether a continuation's bytes simply append or re-state a flag byte first is decided by the record being continued, so the blocks are reported as written.
 - **`src/biff/cursor.ts`** — a field cursor over one record's blocks that reads across a continuation boundary transparently while keeping the boundary observable, which is exactly what the string reader needs.
 - **`src/biff/strings.ts`**, **`src/biff/rk.ts`**, **`src/biff/errors.ts`** — the shared value encodings: the three string shapes, the `RkNumber` packed-numeric encoding, and the `BErr` error-value vocabulary.
-- **`src/workbook/globals.ts`**, **`src/workbook/sheet.ts`** — the two substream readers, each walking the record sequence its ABNF in [MS-XLS] 2.1.7.20.3 / 2.1.7.20.5 defines.
-- **`src/number-format.ts`**, **`src/serial.ts`** — number-format classification and date-serial conversion, the two pieces of xlsx semantics BIFF8 shares because ECMA-376 inherited them from BIFF.
+- **`src/biff/ptg.ts`**, **`src/biff/ptg-functions.ts`** — the `Ptg` compiled-formula token stream, walked as a postfix expression and rebuilt into infix formula text (an operand stack tagged with each entry's own operator precedence, so a child is parenthesised only when its precedence genuinely requires it), and the built-in worksheet-function name/fixed-arity table `PtgFunc`/`PtgFuncVar` resolve against.
+- **`src/workbook/globals.ts`**, **`src/workbook/sheet.ts`** — the two substream readers, each walking the record sequence its ABNF in [MS-XLS] 2.1.7.20.3 / 2.1.7.20.5 defines; `globals.ts` also resolves a 3D reference's own `ixti` to a sheet range through `EXTERNSHEET` and a self-referencing `SupBook`, which `sheet.ts` threads into `ptg.ts` for a Formula record's own 3D references, and reads a `Palette` record and each `XF`'s trailing fill/border payload for [Cell decoration](#cell-decoration). Both readers contribute to [Print settings](#print-settings), which BIFF8 splits between them: `sheet.ts` reads the page-setup record group, `globals.ts` the two built-in defined names carrying the print range and the repeated header bands.
+- **`src/biff/xf-colors.ts`** — the `Icv` colour table (both the eight fixed colours and the 56-entry default palette), the `BorderStyle`/`FillPattern` vocabularies, and the `CellXF`/`StyleXF` trailing payload's own border/fill bit-layout packing and unpacking, shared by `globals.ts`'s read side and `biff/xf-writer.ts`'s write side — see [Cell decoration](#cell-decoration).
+- **`src/biff/print-setup.ts`**, **`src/workbook/print-names.ts`** — the two halves of [Print settings](#print-settings). The first is the `Setup` record's own flag bit layout and `iPaperSize` code table, packed and unpacked in one place exactly as `xf-colors.ts` does for the `XF` payload; the second is both directions of the built-in `Print_Area`/`Print_Titles` defined names, which live in the globals substream rather than the sheet's own and so are read by `globals.ts` and written by `globals-writer.ts`.
+- **[`excel-number-format`](../excel-number-format/README.md)**, **`src/serial.ts`** — number-format classification and date-serial conversion, the two pieces of xlsx semantics BIFF8 shares because ECMA-376 inherited them from BIFF. The classifier itself is a dependency shared with `ooxml.js`, not a module in this package (ExaDev/documents.js#848) — `classifyNumberFormat` and `BUILTIN_NUMBER_FORMATS` still ride this package's own barrel (`export * from "excel-number-format"` in `src/index.ts`), so `import { classifyNumberFormat } from "xls-codec"` is unchanged.
 - **`src/content.ts`** — the mapping onto `document-schema.js`.
+- **`src/metadata.ts`** — wraps `archive-codec`'s own `SummaryInformationProperties` <-> `LayoutMetadata` mapping with this package's `createdIso`/`modifiedIso` date validation, throwing `BiffWriteError` for a malformed one rather than letting an opaque `RangeError` escape the FILETIME conversion (see [Metadata](#metadata)).
 
 ### Deliberately not depended on
 
@@ -121,6 +225,7 @@ Conventional Commits, enforced workspace-wide by commitlint through a root `comm
 - [MS-CFB]: [Compound File Binary File Format](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-cfb/53989ce4-7b05-4f8d-829b-d08d6148375b) — the container, read through `archive-codec`.
 - [archive-codec](../archive-codec/README.md) — the bounded CFB reader this package selects the `Workbook` stream through.
 - [document-schema.js](../document-schema.js/README.md) — the `ContentDocument`/`ContentSheet`/`ContentSheetCell` vocabulary this package maps onto, and the `assembleTree` transform behind `readXls`.
+- [excel-number-format](../excel-number-format/README.md) — the number-format classifier this package depends on, shared with `ooxml.js`'s xlsx support.
 - [ooxml.js](../ooxml.js/README.md) — the sibling reading `.xlsx`, BIFF8's successor, onto the same schema.
 
 ## License

package/dist/biff/bof-writer.cjs

@@ -0,0 +1,18 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_record_types = require("./record-types.cjs");
+const require_biff_builder = require("./builder.cjs");
+//#region src/biff/bof-writer.ts
+/** rupBuild ([MS-XLS] 2.4.21): an arbitrary build identifier: no permitted-values table constrains it, so any 16-bit value is spec-legal. */
+const RUP_BUILD = 3515;
+/** rupYear: [MS-XLS] 2.4.21 requires 0x07CC or 0x07CD. */
+const RUP_YEAR = 1996;
+/** The doc-flags dword: bit 0 (fWin) and bit 3 (fWinAny) set, both of which [MS-XLS] 2.4.21 fixes at MUST-be-1; every other bit -- fRisc, fBeta, fMacAny, fBetaAny, the unused/reserved runs, fOOM, fGlJmp, fFontLimit, verXLHigh, unused3 -- left at its own spec-permitted default of 0. */
+const DOC_FLAGS = 9;
+/** The version-tracking dword: verLowestBiff = 6 (offset 0, [MS-XLS] 2.4.21: "the value MUST be 6"), verLastXLSaved = 0 (offset 8, a value the field's own table permits), reserved2 = 0. */
+const VERSION_TRACKING = 6;
+/** Builds a BOF record's 16-byte data for the given substream document type (BOF_TYPE_WORKBOOK, BOF_TYPE_WORKSHEET, ...). */
+function writeBofData(documentType) {
+	return new require_biff_builder.RecordBuilder().u16(require_biff_record_types.BIFF8_VERSION).u16(documentType).u16(RUP_BUILD).u16(RUP_YEAR).u32(DOC_FLAGS).u32(VERSION_TRACKING).build();
+}
+//#endregion
+exports.writeBofData = writeBofData;

package/dist/biff/bof-writer.d.cts

@@ -0,0 +1,5 @@
+//#region src/biff/bof-writer.d.ts
+/** Builds a BOF record's 16-byte data for the given substream document type (BOF_TYPE_WORKBOOK, BOF_TYPE_WORKSHEET, ...). */
+declare function writeBofData(documentType: number): Uint8Array<ArrayBuffer>;
+//#endregion
+export { writeBofData };

package/dist/biff/bof-writer.d.ts

@@ -0,0 +1,5 @@
+//#region src/biff/bof-writer.d.ts
+/** Builds a BOF record's 16-byte data for the given substream document type (BOF_TYPE_WORKBOOK, BOF_TYPE_WORKSHEET, ...). */
+declare function writeBofData(documentType: number): Uint8Array<ArrayBuffer>;
+//#endregion
+export { writeBofData };

package/dist/biff/bof-writer.js

@@ -0,0 +1,17 @@
+import { BIFF8_VERSION } from "./record-types.js";
+import { RecordBuilder } from "./builder.js";
+//#region src/biff/bof-writer.ts
+/** rupBuild ([MS-XLS] 2.4.21): an arbitrary build identifier: no permitted-values table constrains it, so any 16-bit value is spec-legal. */
+const RUP_BUILD = 3515;
+/** rupYear: [MS-XLS] 2.4.21 requires 0x07CC or 0x07CD. */
+const RUP_YEAR = 1996;
+/** The doc-flags dword: bit 0 (fWin) and bit 3 (fWinAny) set, both of which [MS-XLS] 2.4.21 fixes at MUST-be-1; every other bit -- fRisc, fBeta, fMacAny, fBetaAny, the unused/reserved runs, fOOM, fGlJmp, fFontLimit, verXLHigh, unused3 -- left at its own spec-permitted default of 0. */
+const DOC_FLAGS = 9;
+/** The version-tracking dword: verLowestBiff = 6 (offset 0, [MS-XLS] 2.4.21: "the value MUST be 6"), verLastXLSaved = 0 (offset 8, a value the field's own table permits), reserved2 = 0. */
+const VERSION_TRACKING = 6;
+/** Builds a BOF record's 16-byte data for the given substream document type (BOF_TYPE_WORKBOOK, BOF_TYPE_WORKSHEET, ...). */
+function writeBofData(documentType) {
+	return new RecordBuilder().u16(BIFF8_VERSION).u16(documentType).u16(RUP_BUILD).u16(RUP_YEAR).u32(DOC_FLAGS).u32(VERSION_TRACKING).build();
+}
+//#endregion
+export { writeBofData };

package/dist/biff/builder.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/biff/builder.ts
+var RecordBuilder = class {
+	parts = [];
+	pushBytes(...bytes) {
+		this.parts.push(new Uint8Array(bytes));
+		return this;
+	}
+	u8(value) {
+		return this.pushBytes(value & 255);
+	}
+	u16(value) {
+		const bits = value & 65535;
+		return this.pushBytes(bits & 255, bits >>> 8 & 255);
+	}
+	/** Composed with multiplication rather than `<< 24`, matching biff/cursor.ts's own u32 reader: a shift would produce a signed result for any value with the top bit set. */
+	u32(value) {
+		const bits = value >>> 0;
+		return this.pushBytes(bits & 255, bits >>> 8 & 255, bits >>> 16 & 255, bits >>> 24 & 255);
+	}
+	i32(value) {
+		return this.u32(value >>> 0);
+	}
+	/** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
+	f64(value) {
+		const buffer = /* @__PURE__ */ new ArrayBuffer(8);
+		new DataView(buffer).setFloat64(0, value, true);
+		this.parts.push(new Uint8Array(buffer));
+		return this;
+	}
+	/** Appends raw bytes -- for a field already encoded elsewhere (a packed bitfield word, a string's own byte run). */
+	bytes(data) {
+		this.parts.push(data);
+		return this;
+	}
+	build() {
+		const total = this.parts.reduce((sum, part) => sum + part.length, 0);
+		const out = new Uint8Array(total);
+		let offset = 0;
+		for (const part of this.parts) {
+			out.set(part, offset);
+			offset += part.length;
+		}
+		return out;
+	}
+};
+//#endregion
+exports.RecordBuilder = RecordBuilder;

package/dist/biff/builder.d.cts

@@ -0,0 +1,17 @@
+//#region src/biff/builder.d.ts
+declare class RecordBuilder {
+  private readonly parts;
+  private pushBytes;
+  u8(value: number): this;
+  u16(value: number): this;
+  /** Composed with multiplication rather than `<< 24`, matching biff/cursor.ts's own u32 reader: a shift would produce a signed result for any value with the top bit set. */
+  u32(value: number): this;
+  i32(value: number): this;
+  /** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
+  f64(value: number): this;
+  /** Appends raw bytes -- for a field already encoded elsewhere (a packed bitfield word, a string's own byte run). */
+  bytes(data: Uint8Array<ArrayBuffer>): this;
+  build(): Uint8Array<ArrayBuffer>;
+}
+//#endregion
+export { RecordBuilder };

package/dist/biff/builder.d.ts

@@ -0,0 +1,17 @@
+//#region src/biff/builder.d.ts
+declare class RecordBuilder {
+  private readonly parts;
+  private pushBytes;
+  u8(value: number): this;
+  u16(value: number): this;
+  /** Composed with multiplication rather than `<< 24`, matching biff/cursor.ts's own u32 reader: a shift would produce a signed result for any value with the top bit set. */
+  u32(value: number): this;
+  i32(value: number): this;
+  /** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
+  f64(value: number): this;
+  /** Appends raw bytes -- for a field already encoded elsewhere (a packed bitfield word, a string's own byte run). */
+  bytes(data: Uint8Array<ArrayBuffer>): this;
+  build(): Uint8Array<ArrayBuffer>;
+}
+//#endregion
+export { RecordBuilder };

package/dist/biff/builder.js

@@ -0,0 +1,47 @@
+//#region src/biff/builder.ts
+var RecordBuilder = class {
+	parts = [];
+	pushBytes(...bytes) {
+		this.parts.push(new Uint8Array(bytes));
+		return this;
+	}
+	u8(value) {
+		return this.pushBytes(value & 255);
+	}
+	u16(value) {
+		const bits = value & 65535;
+		return this.pushBytes(bits & 255, bits >>> 8 & 255);
+	}
+	/** Composed with multiplication rather than `<< 24`, matching biff/cursor.ts's own u32 reader: a shift would produce a signed result for any value with the top bit set. */
+	u32(value) {
+		const bits = value >>> 0;
+		return this.pushBytes(bits & 255, bits >>> 8 & 255, bits >>> 16 & 255, bits >>> 24 & 255);
+	}
+	i32(value) {
+		return this.u32(value >>> 0);
+	}
+	/** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
+	f64(value) {
+		const buffer = /* @__PURE__ */ new ArrayBuffer(8);
+		new DataView(buffer).setFloat64(0, value, true);
+		this.parts.push(new Uint8Array(buffer));
+		return this;
+	}
+	/** Appends raw bytes -- for a field already encoded elsewhere (a packed bitfield word, a string's own byte run). */
+	bytes(data) {
+		this.parts.push(data);
+		return this;
+	}
+	build() {
+		const total = this.parts.reduce((sum, part) => sum + part.length, 0);
+		const out = new Uint8Array(total);
+		let offset = 0;
+		for (const part of this.parts) {
+			out.set(part, offset);
+			offset += part.length;
+		}
+		return out;
+	}
+};
+//#endregion
+export { RecordBuilder };

package/dist/biff/cursor.cjs

@@ -53,6 +53,10 @@ var BlockCursor = class {
 	i32() {
 		return this.u32() | 0;
 	}
+	/** A signed 16-bit integer, sign-extended by shifting the raw value out of and back into the low 16 bits -- what XTI's itabFirst/itabLast ([MS-XLS] 2.5.344) and a handful of other structures carry. */
+	i16() {
+		return this.u16() << 16 >> 16;
+	}
 	/** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
 	f64() {
 		const raw = this.take(8);

package/dist/biff/cursor.d.cts

@@ -1,28 +1,2 @@
-//#region src/biff/cursor.d.ts
-declare class BlockCursor {
-  private readonly blocks;
-  private blockIndex;
-  private offset;
-  constructor(blocks: readonly Uint8Array<ArrayBuffer>[]);
-  /** Advances past any exhausted or empty blocks, so the cursor always rests either on a readable byte or past the end of the last block. A Continue carrying no data is legal and must not read as the end of the record. */
-  private settle;
-  private nextByte;
-  /** Whether any unread byte remains, in this block or a later one. */
-  hasMore(): boolean;
-  /** How many unread bytes remain in the block the cursor currently rests in -- the distance to the next continuation boundary, which a string's character run must not cross without consuming a new flag byte. */
-  remainingInBlock(): number;
-  /** The index of the block the cursor currently rests in, so a caller can detect that a read crossed into a new one. */
-  blockPosition(): number;
-  u8(): number;
-  u16(): number;
-  u32(): number;
-  i32(): number;
-  /** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
-  f64(): number;
-  /** The next `count` bytes, copied out. Spans block boundaries. */
-  take(count: number): Uint8Array<ArrayBuffer>;
-  /** Advances `count` bytes without materialising them -- for a field this package reads past rather than reads. */
-  skip(count: number): void;
-}
-//#endregion
+import { t as BlockCursor } from "../cursor-VMtw9uVP.cjs";
 export { BlockCursor };

package/dist/biff/cursor.d.ts

@@ -1,28 +1,2 @@
-//#region src/biff/cursor.d.ts
-declare class BlockCursor {
-  private readonly blocks;
-  private blockIndex;
-  private offset;
-  constructor(blocks: readonly Uint8Array<ArrayBuffer>[]);
-  /** Advances past any exhausted or empty blocks, so the cursor always rests either on a readable byte or past the end of the last block. A Continue carrying no data is legal and must not read as the end of the record. */
-  private settle;
-  private nextByte;
-  /** Whether any unread byte remains, in this block or a later one. */
-  hasMore(): boolean;
-  /** How many unread bytes remain in the block the cursor currently rests in -- the distance to the next continuation boundary, which a string's character run must not cross without consuming a new flag byte. */
-  remainingInBlock(): number;
-  /** The index of the block the cursor currently rests in, so a caller can detect that a read crossed into a new one. */
-  blockPosition(): number;
-  u8(): number;
-  u16(): number;
-  u32(): number;
-  i32(): number;
-  /** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
-  f64(): number;
-  /** The next `count` bytes, copied out. Spans block boundaries. */
-  take(count: number): Uint8Array<ArrayBuffer>;
-  /** Advances `count` bytes without materialising them -- for a field this package reads past rather than reads. */
-  skip(count: number): void;
-}
-//#endregion
+import { t as BlockCursor } from "../cursor-VMtw9uVP.js";
 export { BlockCursor };

package/dist/biff/cursor.js

@@ -52,6 +52,10 @@ var BlockCursor = class {
 	i32() {
 		return this.u32() | 0;
 	}
+	/** A signed 16-bit integer, sign-extended by shifting the raw value out of and back into the low 16 bits -- what XTI's itabFirst/itabLast ([MS-XLS] 2.5.344) and a handful of other structures carry. */
+	i16() {
+		return this.u16() << 16 >> 16;
+	}
 	/** An Xnum ([MS-XLS] 2.5.342): a little-endian IEEE 754 double. */
 	f64() {
 		const raw = this.take(8);

package/dist/biff/errors.cjs

@@ -14,5 +14,12 @@ const ERROR_TEXT = /* @__PURE__ */ new Map([
 function errorTextOf(code) {
 	return ERROR_TEXT.get(code);
 }
+/** The write direction's own lookup, built once from ERROR_TEXT rather than as a second hand-maintained table, so the two directions cannot drift apart. */
+const ERROR_CODE = new Map(Array.from(ERROR_TEXT, ([code, text]) => [text, code]));
+/** The BIFF8 error code for a cell's displayed error text, or undefined when the text is not one of the eight [MS-XLS] defines -- which the writer refuses to guess a code for rather than silently substituting a different error. */
+function errorCodeOf(text) {
+	return ERROR_CODE.get(text);
+}
 //#endregion
+exports.errorCodeOf = errorCodeOf;
 exports.errorTextOf = errorTextOf;

package/dist/biff/errors.d.cts

@@ -1,5 +1,7 @@
 //#region src/biff/errors.d.ts
 /** The displayed spelling of a BIFF8 error code, or undefined for a code [MS-XLS] does not define -- which the caller degrades rather than guessing a spelling for. */
 declare function errorTextOf(code: number): string | undefined;
+/** The BIFF8 error code for a cell's displayed error text, or undefined when the text is not one of the eight [MS-XLS] defines -- which the writer refuses to guess a code for rather than silently substituting a different error. */
+declare function errorCodeOf(text: string): number | undefined;
 //#endregion
-export { errorTextOf };
+export { errorCodeOf, errorTextOf };

package/dist/biff/errors.d.ts

@@ -1,5 +1,7 @@
 //#region src/biff/errors.d.ts
 /** The displayed spelling of a BIFF8 error code, or undefined for a code [MS-XLS] does not define -- which the caller degrades rather than guessing a spelling for. */
 declare function errorTextOf(code: number): string | undefined;
+/** The BIFF8 error code for a cell's displayed error text, or undefined when the text is not one of the eight [MS-XLS] defines -- which the writer refuses to guess a code for rather than silently substituting a different error. */
+declare function errorCodeOf(text: string): number | undefined;
 //#endregion
-export { errorTextOf };
+export { errorCodeOf, errorTextOf };