xls-codec 2.0.2 → 4.0.0

package/README.md

@@ -15,10 +15,10 @@ Under active development, with real, tested **read and write** support. Built an
 - **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.
+- **Formula text recovery, including shared, array, and external-reference formulas** (`src/biff/ptg.ts`, `src/biff/ptg-functions.ts`, `src/workbook/sheet.ts`'s `collectFormulaGroups`, `src/workbook/globals.ts`'s `readSupBook`) — 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), every arithmetic/comparison/unary/percent operator and explicit parentheses, 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`), a **shared formula** (`PtgExp` joined against the `ShrFmla` record that follows its group's base cell, its relative `PtgRefN`/`PtgAreaN` tokens re-expanded for each referencing cell's own position, alongside any ordinary, non-relative token the same shared expression carries), an **array formula** (`PtgExp` joined against an `Array` record instead, its expression returned with no further wrapping — Excel's own `{...}` CSE bracing is formula-bar display syntax, never written into the formula itself, matching `ooxml.js`'s own xlsx convention; a `PtgArray` array-constant literal's `{...}` is genuine syntax, not this bracing, and is resolved from its own `PtgExtraArray` trailer wherever one appears, array-entered or not), and a **3D reference's sheet name**, resolved through `EXTERNSHEET` and `SupBook` for both a self-referencing workbook and a genuinely external one (its own file name and sheet name(s) recovered as far as `SupBook`'s `virtPath`/`rgst` fields allow); a DDE/OLE/add-in/same-sheet/unused link, an unresolved sheet index, or an undecoded `virtPath` form has no real name to recover, and leaves the whole containing formula unresolved exactly like any other unsupported construct, rather than writing a fabricated placeholder into what would otherwise be real formula text (`src/workbook/globals.ts`'s own `sheetRanges`) — see "Formula expressions" under Read-side gaps below for the exact boundary of what still resolves to nothing at all.
 - **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)).
+- **Cell decoration** — a cell's background fill (every named `FillPattern` value, solid and pattern alike) 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)).
 
@@ -26,7 +26,7 @@ Verified primarily by round trip (`src/write.test.ts`, plus a dedicated `test/wo
 
 ### Writer scope
 
-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:
+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 background fill (solid or a genuine two-colour pattern) and per-side borders, deduplicated across the workbook the same way number formats are. What it deliberately does not:
 
 | Not written                                                                                                        | Why                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -45,21 +45,21 @@ Column widths round-trip to the nearest pixel Excel's own integer-pixel-grid qua
 
 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.
+- **Formula expressions, including shared, array, and external-reference formulas.** 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), 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 the read side used to leave `ContentSheetCell.formula` silently absent for are now resolved: a **shared formula** — a `PtgExp` token is joined (`src/workbook/sheet.ts`'s `collectFormulaGroups`) against the `ShrFmla` record that follows its group's base `Formula` record, and the shared expression's own relative tokens (`PtgRefN`/`PtgAreaN`, [MS-XLS] 2.5.198.88/2.5.198.31) are re-expanded for each referencing cell's own row/column, including the format's own sheet-edge wraparound rule, while any ordinary (non-relative) token the same expression carries is resolved once and reused unchanged for every referencing cell; an **array (CSE) formula** — the same `PtgExp` join against an `Array` record instead, its expression returned exactly as parsed, with no formula-bar bracing added (Excel's own `{...}` CSE braces are display syntax the formula-bar shows for an array-entered cell, never characters written into the formula itself — matching `ooxml.js`'s own xlsx convention for the identical construct); and a `PtgArray` array-constant literal (`{1,2,3}`-style, whether inside an array formula or an entirely ordinary one like `=SUM({1,2,3})`) — this bracing genuinely is real, retypeable formula syntax, unlike CSE bracing, and its values are read from the token's own `PtgExtraArray` trailer rather than left unresolved. A 3D reference's sheet name resolves through `EXTERNSHEET` and `SupBook` for both a self-referencing workbook and a genuinely external one — `SupBook`'s `virtPath` (the external workbook's own path, decoded for the common relative-path forms: same-drive, startup, alternate-startup, and library-relative) and `rgst` (its sheet names) recover a real `[Workbook.xlsx]Sheet1`-style label wherever they can, and that label is trusted as real formula text only when both halves were genuinely recovered from the file. An absolute drive volume, a UNC share, or a transfer-protocol URL in `virtPath`; a `virtPath` whose final file-path segment carries a bracket character anywhere in it, not only one already shaped like the bracketed sheet-name form (`[Book.xlsx]Sheet1`) — a bracket-named file is legal per [MS-XLS]'s own grammar, and a bracket's position within that final segment does not settle whether it is genuinely that form: the grammar's own bracketed alternative opens with a literal `[` before any directory at all, so a workbook sitting in a subdirectory (`[sub` + a directory separator + `Book.xlsx]Sheet1`) puts its closing bracket, non-leading, in the very same final segment this reader isolates once split on the separator — a real instance of the bracketed form just as much as the leading-bracket case (`[Book.xlsx]Sheet1` with no directory at all) is; a bracket elsewhere in an otherwise plain, single-directory file name (`My[Draft].xlsx`) is the case this reader can actually rule the bracketed form out for, since with no directory separator to split on, that whole segment's own leading character settles it — but returning it as a plain file name would still collide with this reader's own `[${fileName}]` wrapping of the resolved label, producing a raw, unbalanced bracket inside what should read as one clean `[Book.xlsx]`-style pair — so the whole segment is declined regardless of where the bracket falls or whether this reader could rule the bracketed form out, trading a known false negative for never emitting a mangled label; a `SupBook` that is a DDE/OLE data source, an add-in, a same-sheet, or an unused link in the first place; or a sheet index [MS-XLS] itself marks unresolvable or workbook-level — none of these has a real name to recover, and each leaves the WHOLE containing formula unresolved, exactly like any other construct this reader cannot turn into real formula text, rather than writing a fabricated placeholder into what a spreadsheet application would otherwise treat as live formula content. What remains genuinely unresolved for the same reason, still leaving `formula` absent for that cell: a `PtgTbl` data table, a defined name (`PtgName`/`PtgNameX`, for the same reason `Lbl` is not read at all yet — see below), and a natural-language "Elf" reference.
+- **Cell decoration and alignment resolved for real; font still not.** `XF`'s trailing `CellXF` payload's fill pattern/colours 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, including every named pattern beyond solid, 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 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).
+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 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.
+A cell's own background fill -- solid, or a genuine two-colour pattern -- 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.
+**Fill patterns beyond solid, resolved for real (ExaDev/documents.js#951).** [MS-XLS]/[MS-XLSB]'s own `FillPattern` enumeration names nineteen values: no fill, solid, and seventeen genuine two-colour patterns -- five grey shades (`FLSMEDGRAY`/`FLSDKGRAY`/`FLSLTGRAY`/`FLSGRAY125`/`FLSGRAY0625`) and the stripe/crosshatch families. `ContentSheetCell.background` is `document-schema.js`'s own `ContentCellFill`: a discriminated `'solid'`/`'pattern'` shape, `'pattern'` naming a closed `ContentCellPatternType` vocabulary spanning both this format's own `FillPattern` and WordprocessingML's `ST_Shd` (see that schema's own top comment for the full citation). `FLSSOLID` resolves to a `'solid'` fill of 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") -- `icvBack` carries no meaning for it and is never consulted. Every other named `FillPattern` value resolves to a real `'pattern'` fill via `xf-colors.ts`'s own `FILL_PATTERN_TO_PATTERN_TYPE`, an exact 1:1 mapping onto the identical ECMA-376 `ST_PatternType` token name (`FLSMEDGRAY` through `FLSGRAY0625`, values 0x02-0x12, onto `mediumGray` through `gray0625` in that order) -- carrying whichever of the pattern's own foreground (`icvFore`, drawn as the pattern's strokes) and background (`icvBack`, the colour its gaps show through) colours actually resolve to a fixed RGB value; either may be an "Automatic" icv this package cannot express and is left unstated, matching `ContentCellFillSchema`'s own "a colour can defer instead of asserting" convention. A reserved `FillPattern` value beyond 0x12 still reads as no background at all, there being no pattern name to give it. Writing a `'pattern'` fill states its own colours (automatic where the fill leaves one unstated) under the `FillPattern` value the same table's inverse names for it; a WordprocessingML-only pattern name (the `percentN` family, or a stripe/cross member `ST_Shd` names but `ST_PatternType` does not) throws `BiffWriteError` rather than writing the wrong pattern or silently dropping it.
 
 **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.
 
@@ -67,7 +67,9 @@ A cell's own solid background fill and per-side borders are read from and writte
 
 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 genuine two-colour pattern fill was not checked against LibreOffice in either direction: ODF's own `style:table-cell-properties` has no attribute for a two-colour pattern fill for a hand-authored `.fods` to state one through, so there was no third-party bytes to compare against. Reading and writing every named `FillPattern` value is instead pinned against bytes hand-built from [MS-XLS]/[MS-XLSB]'s own enumeration (`biff/xf-colors.test.ts`) and against a whole-document round trip through this package's own reader and writer (`write.test.ts`).
+
+**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 reserved `FillPattern` value with no pattern name, or an unresolvable colour on every field a cell states, 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.
 
@@ -186,7 +188,7 @@ Layered bottom-up, each layer testable against hand-built byte sequences taken f
 - **`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/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/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 scope through `EXTERNSHEET` and `SupBook` (a plain sheet range for a self-referencing workbook, a fully-formatted label — a real external workbook/sheet name or a diagnostic placeholder — otherwise), 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). `sheet.ts`'s own `collectFormulaGroups` additionally joins a shared or array formula's `PtgExp`-bearing member cells against the `ShrFmla`/`Array` record that carries the group's real expression (see "Formula expressions" under [Read-side gaps](#read-side-gaps)). 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.

package/dist/biff/ptg.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_records = require("./records.cjs");
 const require_biff_cursor = require("./cursor.cjs");
 const require_biff_strings = require("./strings.cjs");
 const require_biff_errors = require("./errors.cjs");
@@ -107,14 +108,107 @@ function readArea(cursor) {
 	const columnLastField = cursor.u16();
 	return [pointFrom(rowFirst, columnFirstField), pointFrom(rowLast, columnLastField)];
 }
+/** Sign-extends the low `bits` bits of `raw` by shifting them out to the top of a 32-bit word and back with an arithmetic shift -- the same trick BlockCursor.i16 uses for a full 16-bit field, generalised here to the 14-bit column delta a relative column field packs ([MS-XLS] 174e856e ColRelNegU: "col (14 bits): A signed integer... MUST be greater than or equal to -255 [and] less than or equal to 255"). */
+function signExtend(raw, bits) {
+	const shift = 32 - bits;
+	return raw << shift >> shift;
+}
+/** RgceLocRel's row field, once known to be relative ([MS-XLS] 2db37ba7 RgceLocRel): a signed 16-bit delta from `currentRow`, wrapped back into 0..65535 exactly as the spec states ("adjusted by 0x00010000") rather than left negative or overflowing -- Excel itself lets a filled-down/across shared formula's relative reference wrap around the sheet edge this way. */
+function resolveRelativeRow(rawRow, currentRow) {
+	const row = currentRow + signExtend(rawRow, 16);
+	if (row < 0) return row + 65536;
+	if (row > 65535) return row - 65536;
+	return row;
+}
+/** RgceLocRel's column field, once known to be relative: a signed 14-bit delta from `currentColumn` (the two flag bits above it already stripped by the caller), wrapped back into 0..255 ([MS-XLS] "adjusted by 0x0100"). */
+function resolveRelativeColumn(rawColumn, currentColumn) {
+	const column = currentColumn + signExtend(rawColumn, 14);
+	if (column < 0) return column + 256;
+	if (column > 255) return column - 256;
+	return column;
+}
+/** One corner of a relative reference ([MS-XLS] 2db37ba7 RgceLocRel, or one half of 75afd109 RgceAreaRel): the same ColRelU-shaped flag bits pointFrom already decodes for an absolute reference, but a set relative bit now means the paired field holds a signed delta from `current` rather than an absolute coordinate. */
+function resolveRelativeCorner(rowField, columnField, current) {
+	const columnAbsolute = (columnField & COLUMN_RELATIVE_BIT) === 0;
+	const rowAbsolute = (columnField & ROW_RELATIVE_BIT) === 0;
+	const rawColumn = columnField & COLUMN_INDEX_MASK;
+	return {
+		row: rowAbsolute ? rowField : resolveRelativeRow(rowField, current.row),
+		column: columnAbsolute ? rawColumn : resolveRelativeColumn(rawColumn, current.column),
+		columnAbsolute,
+		rowAbsolute
+	};
+}
+/** RgceLocRel ([MS-XLS] 2.5.198.111): PtgRefN's own cell shape -- a row field then a ColRelNegU column field, structurally identical to RgceLoc/ColRelU (see readLoc/pointFrom above) but reinterpreting a relative field as an offset from `current` -- the cell this formula is being expanded for -- rather than an absolute coordinate. Meaningful only when expanding a shared formula's own tokens for one specific referencing cell (see workbook/sheet.ts's collectFormulaGroups); every other caller has no `current` cell to offer, which is exactly when this reader has no business meeting one of these tokens at all -- SharedParsedFormula's own grammar is the only place they are legal. */
+function readRelativeLoc(cursor, current) {
+	return resolveRelativeCorner(cursor.u16(), cursor.u16(), current);
+}
+/** RgceAreaRel ([MS-XLS] 75afd109): PtgAreaN's own two-corner shape -- the same field order readArea already uses for an absolute range (both rows, then both corners' own column fields), each corner resolved through the identical relative/absolute rule readRelativeLoc applies to a single cell. */
+function readRelativeArea(cursor, current) {
+	const rowFirst = cursor.u16();
+	const rowLast = cursor.u16();
+	const columnFirstField = cursor.u16();
+	const columnLastField = cursor.u16();
+	return [resolveRelativeCorner(rowFirst, columnFirstField, current), resolveRelativeCorner(rowLast, columnLastField, current)];
+}
+/**
+* PtgExtraArray's own SerAr elements ([MS-XLS] 69ff31ac): every variant but SerStr is a fixed nine bytes -- a one-byte type tag plus eight bytes of payload/padding -- so only SerStr's own XLUnicodeString needs its length read from the data rather than assumed.
+*/
+const SERAR_NIL = 0;
+const SERAR_NUM = 1;
+const SERAR_STR = 2;
+const SERAR_BOOL = 4;
+const SERAR_ERR = 16;
+/** The eight bytes of payload/padding following a SerAr element's own one-byte type tag ([MS-XLS] 69ff31ac): SerNil skips all eight as pure padding, while SerBool and SerErr each consume one real payload byte first and then skip the remaining seven (SERAR_FIXED_PAYLOAD_BYTES - 1). */
+const SERAR_FIXED_PAYLOAD_BYTES = 8;
+/** One SerAr element ([MS-XLS] 69ff31ac) from a PtgExtraArray's `array` field, as the literal text an array-constant token in that position would show -- undefined for a type tag this reader does not recognise, an error code [MS-XLS] does not define, or a SerNil element, in which case the caller aborts the whole PtgArray rather than fabricating a placeholder value. SerNil joins those other two rather than rendering as an empty string: Excel's own array-constant grammar has no way to retype an empty position between two commas (`{1,,3}` is not valid input a spreadsheet application would accept back), and this reader never writes text into `formula` that Excel itself would reject -- see documents.js's own write paths, which take a formula as literal, verbatim text with no further validation. */
+function readArrayElementText(cursor) {
+	switch (cursor.u8()) {
+		case SERAR_NUM: return String(cursor.f64());
+		case SERAR_STR: return quoteStringLiteral(require_biff_strings.readXLUnicodeString(cursor));
+		case SERAR_BOOL: {
+			const value = cursor.u8() !== 0;
+			cursor.skip(7);
+			return value ? "TRUE" : "FALSE";
+		}
+		case SERAR_ERR: {
+			const text = require_biff_errors.errorTextOf(cursor.u8());
+			cursor.skip(7);
+			return text;
+		}
+		case SERAR_NIL:
+			cursor.skip(SERAR_FIXED_PAYLOAD_BYTES);
+			return;
+		default: return;
+	}
+}
+/**
+* PtgExtraArray ([MS-XLS] edd64b46): the literal value grid a PtgArray token's own RgbExtra trailer carries -- one less than the column and row counts, then that many SerAr elements in row-major order. Rendered as Excel's own array-constant syntax (comma between columns, semicolon between rows, e.g. `{1,2;3,4}`), which is the same textual spelling this token has whether it sits inside an ordinary formula's array-constant literal (`=SUM({1,2,3})`) or inside an array formula's own expression -- the array-FORMULA-level `{...}` a CSE entry adds is a separate, outer wrapping applied by the caller, never this one.
+*/
+function readArrayLiteralText(cursor) {
+	const columns = cursor.u8() + 1;
+	const rows = cursor.u16() + 1;
+	const rowTexts = [];
+	for (let row = 0; row < rows; row += 1) {
+		const values = [];
+		for (let column = 0; column < columns; column += 1) {
+			const value = readArrayElementText(cursor);
+			if (value === void 0) return;
+			values.push(value);
+		}
+		rowTexts.push(values.join(","));
+	}
+	return `{${rowTexts.join(";")}}`;
+}
 const SIMPLE_SHEET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_.]*$/;
 function quoteSheetLabel(label) {
 	return SIMPLE_SHEET_NAME_RE.test(label) ? label : `'${label.replaceAll("'", "''")}'`;
 }
-/** The `'Sheet'!` or `'First:Last'!` prefix a 3D reference's own ixti resolves to, or undefined when this reader does not resolve it (see WorkbookGlobals.sheetRanges) -- an unresolved ixti aborts the whole formula's parse, the same as any other unsupported token. */
+/** The `'Sheet'!`, `'First:Last'!`, or `'[Book]Sheet'!` prefix a 3D reference's own ixti resolves to, or undefined whenever this reader has nothing real to say about it -- an ixti past the end of EXTERNSHEET's own array, or an ExternalSheetLabel carrying a diagnostic placeholder rather than a genuinely recovered name (see WorkbookGlobals.sheetRanges). Either way the containing formula still aborts its whole parse, exactly like meeting any other construct this reader cannot turn into real formula text, rather than splicing a fabricated `#REF!(reason)` placeholder into what a spreadsheet application would otherwise treat as live formula content -- see ExternalSheetLabel's own doc comment for why. */
 function resolveSheetLabel(ixti, context) {
 	const range = context.sheetRanges[ixti];
 	if (range === void 0) return;
+	if ("label" in range) return range.diagnostic ? void 0 : `${quoteSheetLabel(range.label)}!`;
 	const first = context.sheets[range.firstSheetIndex]?.name;
 	const last = context.sheets[range.lastSheetIndex]?.name;
 	if (first === void 0 || last === void 0) return;
@@ -160,6 +254,20 @@ const PTG_REF3D_ARRAY = 122;
 const PTG_AREA3D_REF = 59;
 const PTG_AREA3D_VALUE = 91;
 const PTG_AREA3D_ARRAY = 123;
+/** PtgRefN's family ([MS-XLS] 2.5.198.25): a relative-only single-cell reference, legal only inside a shared formula's own SharedParsedFormula -- see readRelativeLoc. */
+const PTG_REFN_REF = 44;
+const PTG_REFN_VALUE = 76;
+const PTG_REFN_ARRAY = 108;
+/** PtgAreaN's family: PtgRefN's area counterpart -- see readRelativeArea. */
+const PTG_AREAN_REF = 45;
+const PTG_AREAN_VALUE = 77;
+const PTG_AREAN_ARRAY = 109;
+/** PtgArray's family ([MS-XLS] 61167ac8): an array-constant literal, whose values live in a PtgExtraArray this token's own bytes never carry -- see ParseFormulaOptions.rgcb and readArrayLiteralText. Each token is a fixed eight bytes: the opcode itself (already consumed by the caller) plus seven bytes this reader never inspects (unused1/2/3), since the real data is the RgbExtra trailer's own PtgExtraArray in the same position-in-sequence as this token. */
+const PTG_ARRAY_REF = 32;
+const PTG_ARRAY_VALUE = 64;
+const PTG_ARRAY_ARRAY = 96;
+/** The seven bytes of a PtgArray token besides its own opcode byte (already consumed as `opcode` by the caller) -- unused1 (1 byte) + unused2 (2 bytes) + unused3 (4 bytes), [MS-XLS] 61167ac8. */
+const PTG_ARRAY_TRAILING_BYTES = 7;
 const PTG_ATTR_OPCODE = 25;
 const PTG_ATTR_SEMI = 1;
 const PTG_ATTR_IF = 2;
@@ -172,14 +280,10 @@ const PTG_ATTR_SPACE = 64;
 const PTG_ATTR_SPACE_SEMI = 65;
 /** The four bytes every PtgAttr subtype but PtgAttrChoose occupies: the shared opcode, the subtype flag byte (already consumed by the caller), and two more this module never inspects. */
 const PTG_ATTR_TRAILING_BYTES = 2;
-/**
-* Parses a Formula record's compiled expression into the text a spreadsheet application would show, or returns undefined for a token this reader does not resolve -- a shared formula's PtgExp, an array constant's PtgArray, a defined name, a natural-language reference, or a 3D reference into a genuinely external workbook (see the module comment for the full list). The caller leaves ContentSheetCell.formula absent in that case, exactly as for any other unsupported construct.
-*
-* `rgce` is the formula's own token bytes, already sliced to their declared length (CellParsedFormula.cce) by the caller -- this function reads exactly that many bytes and nothing past them.
-*/
-function parseFormulaText(rgce, context) {
+function parseFormulaText(rgce, context, options = {}) {
 	const cursor = new require_biff_cursor.BlockCursor([rgce]);
 	const stack = [];
+	const rgcbCursor = options.rgcb === void 0 ? void 0 : new require_biff_cursor.BlockCursor([options.rgcb]);
 	while (cursor.remainingInBlock() > 0) switch (cursor.u8()) {
 		case PTG_ADD:
 			if (!applyBinary(stack, "+", PRECEDENCE_ADD_SUB)) return void 0;
@@ -282,6 +386,36 @@ function parseFormulaText(rgce, context) {
 			pushAtomic(stack, `${label}${formatPoint(start)}:${formatPoint(end)}`);
 			break;
 		}
+		case PTG_REFN_REF:
+		case PTG_REFN_VALUE:
+		case PTG_REFN_ARRAY:
+			if (options.relativeTo === void 0) return void 0;
+			pushAtomic(stack, formatPoint(readRelativeLoc(cursor, options.relativeTo)));
+			break;
+		case PTG_AREAN_REF:
+		case PTG_AREAN_VALUE:
+		case PTG_AREAN_ARRAY: {
+			if (options.relativeTo === void 0) return void 0;
+			const [start, end] = readRelativeArea(cursor, options.relativeTo);
+			pushAtomic(stack, `${formatPoint(start)}:${formatPoint(end)}`);
+			break;
+		}
+		case PTG_ARRAY_REF:
+		case PTG_ARRAY_VALUE:
+		case PTG_ARRAY_ARRAY: {
+			cursor.skip(PTG_ARRAY_TRAILING_BYTES);
+			if (rgcbCursor === void 0) return void 0;
+			let text;
+			try {
+				text = readArrayLiteralText(rgcbCursor);
+			} catch (error) {
+				if (!(error instanceof require_biff_records.BiffFormatError)) throw error;
+				text = void 0;
+			}
+			if (text === void 0) return void 0;
+			pushAtomic(stack, text);
+			break;
+		}
 		case PTG_FUNC_REF:
 		case PTG_FUNC_VALUE:
 		case PTG_FUNC_ARRAY: {
@@ -315,5 +449,24 @@ function parseFormulaText(rgce, context) {
 	}
 	return stack.length === 1 ? stack[0]?.text : void 0;
 }
+/** PtgExp's own opcode ([MS-XLS] f9aa266f): 0x01, a reserved bit, then the row/col of the Formula record that carries the shared or array formula's real expression -- see readPtgExpBase. */
+const PTG_EXP_OPCODE = 1;
+/** PtgExp's own fixed size: the opcode byte plus a Rw (2 bytes) and a Col (2 bytes), [MS-XLS] f9aa266f. */
+const PTG_EXP_SIZE = 5;
+/**
+* If `rgce` is EXACTLY one PtgExp token -- which is the only shape a Formula record belonging to a shared or array formula group ever has, including the group's own base cell, which points at itself -- returns the (row, column) of the Formula record that carries the real expression (a ShrFmla or Array record immediately follows it). Returns undefined for every other rgce, so a caller can try this first and fall back to parseFormulaText for a formula that merely happens to open with byte 0x01 for some other reason (it cannot: no other single-byte-opcode Ptg in this reader's vocabulary is 0x01, but a malformed or foreign rgce is not assumed well-formed here either) or is simply longer than five bytes.
+*
+* Exported for workbook/sheet.ts's collectFormulaGroups, which joins the returned cell against whichever ShrFmla/Array record follows the Formula record found there.
+*/
+function readPtgExpBase(rgce) {
+	if (rgce.length !== PTG_EXP_SIZE || rgce[0] !== PTG_EXP_OPCODE) return;
+	const cursor = new require_biff_cursor.BlockCursor([rgce]);
+	cursor.skip(1);
+	return {
+		row: cursor.u16(),
+		column: cursor.u16()
+	};
+}
 //#endregion
 exports.parseFormulaText = parseFormulaText;
+exports.readPtgExpBase = readPtgExpBase;

package/dist/biff/ptg.d.cts

@@ -1,2 +1,2 @@
-import { n as SheetRange, r as parseFormulaText, t as FormulaSheetContext } from "../ptg-B2K8t3js.cjs";
-export { FormulaSheetContext, SheetRange, parseFormulaText };
+import { a as SheetRange, i as ParseFormulaOptions, n as FormulaOrigin, o as parseFormulaText, r as FormulaSheetContext, s as readPtgExpBase, t as ExternalSheetLabel } from "../ptg-CCBbJLZJ.cjs";
+export { ExternalSheetLabel, FormulaOrigin, FormulaSheetContext, ParseFormulaOptions, SheetRange, parseFormulaText, readPtgExpBase };

package/dist/biff/ptg.d.ts

@@ -1,2 +1,2 @@
-import { n as SheetRange, r as parseFormulaText, t as FormulaSheetContext } from "../ptg-B2K8t3js.js";
-export { FormulaSheetContext, SheetRange, parseFormulaText };
+import { a as SheetRange, i as ParseFormulaOptions, n as FormulaOrigin, o as parseFormulaText, r as FormulaSheetContext, s as readPtgExpBase, t as ExternalSheetLabel } from "../ptg-CCBbJLZJ.js";
+export { ExternalSheetLabel, FormulaOrigin, FormulaSheetContext, ParseFormulaOptions, SheetRange, parseFormulaText, readPtgExpBase };

package/dist/biff/ptg.js

@@ -1,5 +1,6 @@
+import { BiffFormatError } from "./records.js";
 import { BlockCursor } from "./cursor.js";
-import { readShortXLUnicodeString } from "./strings.js";
+import { readShortXLUnicodeString, readXLUnicodeString } from "./strings.js";
 import { errorTextOf } from "./errors.js";
 import { FTAB_FIXED_ARITY, FTAB_NAMES } from "./ptg-functions.js";
 import { columnIndexToLetters } from "document-schema.js";
@@ -106,14 +107,107 @@ function readArea(cursor) {
 	const columnLastField = cursor.u16();
 	return [pointFrom(rowFirst, columnFirstField), pointFrom(rowLast, columnLastField)];
 }
+/** Sign-extends the low `bits` bits of `raw` by shifting them out to the top of a 32-bit word and back with an arithmetic shift -- the same trick BlockCursor.i16 uses for a full 16-bit field, generalised here to the 14-bit column delta a relative column field packs ([MS-XLS] 174e856e ColRelNegU: "col (14 bits): A signed integer... MUST be greater than or equal to -255 [and] less than or equal to 255"). */
+function signExtend(raw, bits) {
+	const shift = 32 - bits;
+	return raw << shift >> shift;
+}
+/** RgceLocRel's row field, once known to be relative ([MS-XLS] 2db37ba7 RgceLocRel): a signed 16-bit delta from `currentRow`, wrapped back into 0..65535 exactly as the spec states ("adjusted by 0x00010000") rather than left negative or overflowing -- Excel itself lets a filled-down/across shared formula's relative reference wrap around the sheet edge this way. */
+function resolveRelativeRow(rawRow, currentRow) {
+	const row = currentRow + signExtend(rawRow, 16);
+	if (row < 0) return row + 65536;
+	if (row > 65535) return row - 65536;
+	return row;
+}
+/** RgceLocRel's column field, once known to be relative: a signed 14-bit delta from `currentColumn` (the two flag bits above it already stripped by the caller), wrapped back into 0..255 ([MS-XLS] "adjusted by 0x0100"). */
+function resolveRelativeColumn(rawColumn, currentColumn) {
+	const column = currentColumn + signExtend(rawColumn, 14);
+	if (column < 0) return column + 256;
+	if (column > 255) return column - 256;
+	return column;
+}
+/** One corner of a relative reference ([MS-XLS] 2db37ba7 RgceLocRel, or one half of 75afd109 RgceAreaRel): the same ColRelU-shaped flag bits pointFrom already decodes for an absolute reference, but a set relative bit now means the paired field holds a signed delta from `current` rather than an absolute coordinate. */
+function resolveRelativeCorner(rowField, columnField, current) {
+	const columnAbsolute = (columnField & COLUMN_RELATIVE_BIT) === 0;
+	const rowAbsolute = (columnField & ROW_RELATIVE_BIT) === 0;
+	const rawColumn = columnField & COLUMN_INDEX_MASK;
+	return {
+		row: rowAbsolute ? rowField : resolveRelativeRow(rowField, current.row),
+		column: columnAbsolute ? rawColumn : resolveRelativeColumn(rawColumn, current.column),
+		columnAbsolute,
+		rowAbsolute
+	};
+}
+/** RgceLocRel ([MS-XLS] 2.5.198.111): PtgRefN's own cell shape -- a row field then a ColRelNegU column field, structurally identical to RgceLoc/ColRelU (see readLoc/pointFrom above) but reinterpreting a relative field as an offset from `current` -- the cell this formula is being expanded for -- rather than an absolute coordinate. Meaningful only when expanding a shared formula's own tokens for one specific referencing cell (see workbook/sheet.ts's collectFormulaGroups); every other caller has no `current` cell to offer, which is exactly when this reader has no business meeting one of these tokens at all -- SharedParsedFormula's own grammar is the only place they are legal. */
+function readRelativeLoc(cursor, current) {
+	return resolveRelativeCorner(cursor.u16(), cursor.u16(), current);
+}
+/** RgceAreaRel ([MS-XLS] 75afd109): PtgAreaN's own two-corner shape -- the same field order readArea already uses for an absolute range (both rows, then both corners' own column fields), each corner resolved through the identical relative/absolute rule readRelativeLoc applies to a single cell. */
+function readRelativeArea(cursor, current) {
+	const rowFirst = cursor.u16();
+	const rowLast = cursor.u16();
+	const columnFirstField = cursor.u16();
+	const columnLastField = cursor.u16();
+	return [resolveRelativeCorner(rowFirst, columnFirstField, current), resolveRelativeCorner(rowLast, columnLastField, current)];
+}
+/**
+* PtgExtraArray's own SerAr elements ([MS-XLS] 69ff31ac): every variant but SerStr is a fixed nine bytes -- a one-byte type tag plus eight bytes of payload/padding -- so only SerStr's own XLUnicodeString needs its length read from the data rather than assumed.
+*/
+const SERAR_NIL = 0;
+const SERAR_NUM = 1;
+const SERAR_STR = 2;
+const SERAR_BOOL = 4;
+const SERAR_ERR = 16;
+/** The eight bytes of payload/padding following a SerAr element's own one-byte type tag ([MS-XLS] 69ff31ac): SerNil skips all eight as pure padding, while SerBool and SerErr each consume one real payload byte first and then skip the remaining seven (SERAR_FIXED_PAYLOAD_BYTES - 1). */
+const SERAR_FIXED_PAYLOAD_BYTES = 8;
+/** One SerAr element ([MS-XLS] 69ff31ac) from a PtgExtraArray's `array` field, as the literal text an array-constant token in that position would show -- undefined for a type tag this reader does not recognise, an error code [MS-XLS] does not define, or a SerNil element, in which case the caller aborts the whole PtgArray rather than fabricating a placeholder value. SerNil joins those other two rather than rendering as an empty string: Excel's own array-constant grammar has no way to retype an empty position between two commas (`{1,,3}` is not valid input a spreadsheet application would accept back), and this reader never writes text into `formula` that Excel itself would reject -- see documents.js's own write paths, which take a formula as literal, verbatim text with no further validation. */
+function readArrayElementText(cursor) {
+	switch (cursor.u8()) {
+		case SERAR_NUM: return String(cursor.f64());
+		case SERAR_STR: return quoteStringLiteral(readXLUnicodeString(cursor));
+		case SERAR_BOOL: {
+			const value = cursor.u8() !== 0;
+			cursor.skip(7);
+			return value ? "TRUE" : "FALSE";
+		}
+		case SERAR_ERR: {
+			const text = errorTextOf(cursor.u8());
+			cursor.skip(7);
+			return text;
+		}
+		case SERAR_NIL:
+			cursor.skip(SERAR_FIXED_PAYLOAD_BYTES);
+			return;
+		default: return;
+	}
+}
+/**
+* PtgExtraArray ([MS-XLS] edd64b46): the literal value grid a PtgArray token's own RgbExtra trailer carries -- one less than the column and row counts, then that many SerAr elements in row-major order. Rendered as Excel's own array-constant syntax (comma between columns, semicolon between rows, e.g. `{1,2;3,4}`), which is the same textual spelling this token has whether it sits inside an ordinary formula's array-constant literal (`=SUM({1,2,3})`) or inside an array formula's own expression -- the array-FORMULA-level `{...}` a CSE entry adds is a separate, outer wrapping applied by the caller, never this one.
+*/
+function readArrayLiteralText(cursor) {
+	const columns = cursor.u8() + 1;
+	const rows = cursor.u16() + 1;
+	const rowTexts = [];
+	for (let row = 0; row < rows; row += 1) {
+		const values = [];
+		for (let column = 0; column < columns; column += 1) {
+			const value = readArrayElementText(cursor);
+			if (value === void 0) return;
+			values.push(value);
+		}
+		rowTexts.push(values.join(","));
+	}
+	return `{${rowTexts.join(";")}}`;
+}
 const SIMPLE_SHEET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_.]*$/;
 function quoteSheetLabel(label) {
 	return SIMPLE_SHEET_NAME_RE.test(label) ? label : `'${label.replaceAll("'", "''")}'`;
 }
-/** The `'Sheet'!` or `'First:Last'!` prefix a 3D reference's own ixti resolves to, or undefined when this reader does not resolve it (see WorkbookGlobals.sheetRanges) -- an unresolved ixti aborts the whole formula's parse, the same as any other unsupported token. */
+/** The `'Sheet'!`, `'First:Last'!`, or `'[Book]Sheet'!` prefix a 3D reference's own ixti resolves to, or undefined whenever this reader has nothing real to say about it -- an ixti past the end of EXTERNSHEET's own array, or an ExternalSheetLabel carrying a diagnostic placeholder rather than a genuinely recovered name (see WorkbookGlobals.sheetRanges). Either way the containing formula still aborts its whole parse, exactly like meeting any other construct this reader cannot turn into real formula text, rather than splicing a fabricated `#REF!(reason)` placeholder into what a spreadsheet application would otherwise treat as live formula content -- see ExternalSheetLabel's own doc comment for why. */
 function resolveSheetLabel(ixti, context) {
 	const range = context.sheetRanges[ixti];
 	if (range === void 0) return;
+	if ("label" in range) return range.diagnostic ? void 0 : `${quoteSheetLabel(range.label)}!`;
 	const first = context.sheets[range.firstSheetIndex]?.name;
 	const last = context.sheets[range.lastSheetIndex]?.name;
 	if (first === void 0 || last === void 0) return;
@@ -159,6 +253,20 @@ const PTG_REF3D_ARRAY = 122;
 const PTG_AREA3D_REF = 59;
 const PTG_AREA3D_VALUE = 91;
 const PTG_AREA3D_ARRAY = 123;
+/** PtgRefN's family ([MS-XLS] 2.5.198.25): a relative-only single-cell reference, legal only inside a shared formula's own SharedParsedFormula -- see readRelativeLoc. */
+const PTG_REFN_REF = 44;
+const PTG_REFN_VALUE = 76;
+const PTG_REFN_ARRAY = 108;
+/** PtgAreaN's family: PtgRefN's area counterpart -- see readRelativeArea. */
+const PTG_AREAN_REF = 45;
+const PTG_AREAN_VALUE = 77;
+const PTG_AREAN_ARRAY = 109;
+/** PtgArray's family ([MS-XLS] 61167ac8): an array-constant literal, whose values live in a PtgExtraArray this token's own bytes never carry -- see ParseFormulaOptions.rgcb and readArrayLiteralText. Each token is a fixed eight bytes: the opcode itself (already consumed by the caller) plus seven bytes this reader never inspects (unused1/2/3), since the real data is the RgbExtra trailer's own PtgExtraArray in the same position-in-sequence as this token. */
+const PTG_ARRAY_REF = 32;
+const PTG_ARRAY_VALUE = 64;
+const PTG_ARRAY_ARRAY = 96;
+/** The seven bytes of a PtgArray token besides its own opcode byte (already consumed as `opcode` by the caller) -- unused1 (1 byte) + unused2 (2 bytes) + unused3 (4 bytes), [MS-XLS] 61167ac8. */
+const PTG_ARRAY_TRAILING_BYTES = 7;
 const PTG_ATTR_OPCODE = 25;
 const PTG_ATTR_SEMI = 1;
 const PTG_ATTR_IF = 2;
@@ -171,14 +279,10 @@ const PTG_ATTR_SPACE = 64;
 const PTG_ATTR_SPACE_SEMI = 65;
 /** The four bytes every PtgAttr subtype but PtgAttrChoose occupies: the shared opcode, the subtype flag byte (already consumed by the caller), and two more this module never inspects. */
 const PTG_ATTR_TRAILING_BYTES = 2;
-/**
-* Parses a Formula record's compiled expression into the text a spreadsheet application would show, or returns undefined for a token this reader does not resolve -- a shared formula's PtgExp, an array constant's PtgArray, a defined name, a natural-language reference, or a 3D reference into a genuinely external workbook (see the module comment for the full list). The caller leaves ContentSheetCell.formula absent in that case, exactly as for any other unsupported construct.
-*
-* `rgce` is the formula's own token bytes, already sliced to their declared length (CellParsedFormula.cce) by the caller -- this function reads exactly that many bytes and nothing past them.
-*/
-function parseFormulaText(rgce, context) {
+function parseFormulaText(rgce, context, options = {}) {
 	const cursor = new BlockCursor([rgce]);
 	const stack = [];
+	const rgcbCursor = options.rgcb === void 0 ? void 0 : new BlockCursor([options.rgcb]);
 	while (cursor.remainingInBlock() > 0) switch (cursor.u8()) {
 		case PTG_ADD:
 			if (!applyBinary(stack, "+", PRECEDENCE_ADD_SUB)) return void 0;
@@ -281,6 +385,36 @@ function parseFormulaText(rgce, context) {
 			pushAtomic(stack, `${label}${formatPoint(start)}:${formatPoint(end)}`);
 			break;
 		}
+		case PTG_REFN_REF:
+		case PTG_REFN_VALUE:
+		case PTG_REFN_ARRAY:
+			if (options.relativeTo === void 0) return void 0;
+			pushAtomic(stack, formatPoint(readRelativeLoc(cursor, options.relativeTo)));
+			break;
+		case PTG_AREAN_REF:
+		case PTG_AREAN_VALUE:
+		case PTG_AREAN_ARRAY: {
+			if (options.relativeTo === void 0) return void 0;
+			const [start, end] = readRelativeArea(cursor, options.relativeTo);
+			pushAtomic(stack, `${formatPoint(start)}:${formatPoint(end)}`);
+			break;
+		}
+		case PTG_ARRAY_REF:
+		case PTG_ARRAY_VALUE:
+		case PTG_ARRAY_ARRAY: {
+			cursor.skip(PTG_ARRAY_TRAILING_BYTES);
+			if (rgcbCursor === void 0) return void 0;
+			let text;
+			try {
+				text = readArrayLiteralText(rgcbCursor);
+			} catch (error) {
+				if (!(error instanceof BiffFormatError)) throw error;
+				text = void 0;
+			}
+			if (text === void 0) return void 0;
+			pushAtomic(stack, text);
+			break;
+		}
 		case PTG_FUNC_REF:
 		case PTG_FUNC_VALUE:
 		case PTG_FUNC_ARRAY: {
@@ -314,5 +448,23 @@ function parseFormulaText(rgce, context) {
 	}
 	return stack.length === 1 ? stack[0]?.text : void 0;
 }
+/** PtgExp's own opcode ([MS-XLS] f9aa266f): 0x01, a reserved bit, then the row/col of the Formula record that carries the shared or array formula's real expression -- see readPtgExpBase. */
+const PTG_EXP_OPCODE = 1;
+/** PtgExp's own fixed size: the opcode byte plus a Rw (2 bytes) and a Col (2 bytes), [MS-XLS] f9aa266f. */
+const PTG_EXP_SIZE = 5;
+/**
+* If `rgce` is EXACTLY one PtgExp token -- which is the only shape a Formula record belonging to a shared or array formula group ever has, including the group's own base cell, which points at itself -- returns the (row, column) of the Formula record that carries the real expression (a ShrFmla or Array record immediately follows it). Returns undefined for every other rgce, so a caller can try this first and fall back to parseFormulaText for a formula that merely happens to open with byte 0x01 for some other reason (it cannot: no other single-byte-opcode Ptg in this reader's vocabulary is 0x01, but a malformed or foreign rgce is not assumed well-formed here either) or is simply longer than five bytes.
+*
+* Exported for workbook/sheet.ts's collectFormulaGroups, which joins the returned cell against whichever ShrFmla/Array record follows the Formula record found there.
+*/
+function readPtgExpBase(rgce) {
+	if (rgce.length !== PTG_EXP_SIZE || rgce[0] !== PTG_EXP_OPCODE) return;
+	const cursor = new BlockCursor([rgce]);
+	cursor.skip(1);
+	return {
+		row: cursor.u16(),
+		column: cursor.u16()
+	};
+}
 //#endregion
-export { parseFormulaText };
+export { parseFormulaText, readPtgExpBase };

package/dist/biff/strings.cjs

@@ -37,6 +37,11 @@ function readXLUnicodeString(cursor) {
 	const startBlock = cursor.blockPosition();
 	return readCharacters(cursor, cursor.u16(), (cursor.u8() & FLAG_HIGH_BYTE) !== 0, startBlock);
 }
+/** An XLUnicodeStringNoCch ([MS-XLS] 2.5.296): a flags byte then the characters, with no character-count field of its own -- the containing structure states the count separately (SupBook's own `cch`, for its `virtPath` field), so the caller supplies it here rather than this function reading a fresh prefix. */
+function readXLUnicodeStringNoCch(cursor, count) {
+	const startBlock = cursor.blockPosition();
+	return readCharacters(cursor, count, (cursor.u8() & FLAG_HIGH_BYTE) !== 0, startBlock);
+}
 /** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
 function readShortXLUnicodeString(cursor) {
 	const startBlock = cursor.blockPosition();
@@ -64,3 +69,4 @@ function readRichExtendedString(cursor) {
 exports.readRichExtendedString = readRichExtendedString;
 exports.readShortXLUnicodeString = readShortXLUnicodeString;
 exports.readXLUnicodeString = readXLUnicodeString;
+exports.readXLUnicodeStringNoCch = readXLUnicodeStringNoCch;

package/dist/biff/strings.d.cts

@@ -2,6 +2,8 @@ import { t as BlockCursor } from "../cursor-VMtw9uVP.cjs";
 //#region src/biff/strings.d.ts
 /** An XLUnicodeString ([MS-XLS] 2.5.294): a two-byte character count, a flags byte, then the characters. Continuable, since the String record ([MS-XLS] 2.4.268) carrying a formula's string result is one of these and its own production admits trailing Continues. */
 declare function readXLUnicodeString(cursor: BlockCursor): string;
+/** An XLUnicodeStringNoCch ([MS-XLS] 2.5.296): a flags byte then the characters, with no character-count field of its own -- the containing structure states the count separately (SupBook's own `cch`, for its `virtPath` field), so the caller supplies it here rather than this function reading a fresh prefix. */
+declare function readXLUnicodeStringNoCch(cursor: BlockCursor, count: number): string;
 /** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
 declare function readShortXLUnicodeString(cursor: BlockCursor): string;
 /**
@@ -11,4 +13,4 @@ declare function readShortXLUnicodeString(cursor: BlockCursor): string;
  */
 declare function readRichExtendedString(cursor: BlockCursor): string;
 //#endregion
-export { readRichExtendedString, readShortXLUnicodeString, readXLUnicodeString };
+export { readRichExtendedString, readShortXLUnicodeString, readXLUnicodeString, readXLUnicodeStringNoCch };