xls-codec 3.0.0 → 4.1.0

package/dist/workbook/globals.js

@@ -1,8 +1,9 @@
 import { RECORD_FORMAT } from "../biff/record-types.js";
 import { BiffFormatError } from "../biff/records.js";
+import { recordByteLength } from "../biff/substreams.js";
 import { readLongRgbColor, unpackXfAlignment, unpackXfDecoration } from "../biff/xf-colors.js";
 import { BlockCursor } from "../biff/cursor.js";
-import { readRichExtendedString, readShortXLUnicodeString, readXLUnicodeString } from "../biff/strings.js";
+import { readRichExtendedString, readShortXLUnicodeString, readXLUnicodeString, readXLUnicodeStringNoCch } from "../biff/strings.js";
 import { readPrintNames } from "./print-names.js";
 import { BUILTIN_NUMBER_FORMATS } from "excel-number-format";
 //#region src/workbook/globals.ts
@@ -18,7 +19,7 @@ function readWorkbookGlobals(records) {
 	const sheets = [];
 	const cellFormats = [];
 	const customFormats = /* @__PURE__ */ new Map();
-	const supBookSelfReferencing = [];
+	const supBooks = [];
 	let sharedStrings = [];
 	let date1904 = false;
 	let externSheet;
@@ -42,7 +43,7 @@ function readWorkbookGlobals(records) {
 			date1904 = readDate1904(record);
 			break;
 		case 430:
-			supBookSelfReferencing.push(isSelfReferencingSupBook(record));
+			supBooks.push(readSupBookSafely(record));
 			break;
 		case 23:
 			externSheet = record;
@@ -51,7 +52,7 @@ function readWorkbookGlobals(records) {
 	}
 	const numberFormats = new Map(BUILTIN_NUMBER_FORMATS);
 	for (const [id, code] of customFormats) numberFormats.set(id, code);
-	const sheetRanges = externSheet === void 0 ? [] : readSheetRanges(externSheet, supBookSelfReferencing);
+	const sheetRanges = externSheet === void 0 ? [] : readSheetRanges(externSheet, supBooks);
 	return {
 		sheets,
 		sharedStrings,
@@ -63,16 +64,141 @@ function readWorkbookGlobals(records) {
 		printNames: readPrintNames(records)
 	};
 }
-/** [MS-XLS] 2.4.271's own cch table: a SupBook whose cch is exactly this value is a self-referencing supporting link -- this workbook itself -- rather than another workbook, a DDE/OLE data source, or an add-in. This is the only kind of supporting link a 3D reference resolves through here; every other kind genuinely needs bytes from outside this file. */
+/** [MS-XLS] 2.4.271's own cch table: a SupBook whose cch is exactly this value is a self-referencing supporting link -- this workbook itself -- rather than another workbook, a DDE/OLE data source, or an add-in. */
 const SUPBOOK_SELF_REFERENCING_CCH = 1025;
-/** SupBook ([MS-XLS] 2.4.271): a two-byte ctab then a two-byte cch. Only cch is read here -- ctab is undefined for a self-referencing SupBook and unused for every other kind this reader does not resolve, and the virtPath/rgst payload that would follow for a non-self-referencing link is never reached. */
-function isSelfReferencingSupBook(record) {
+/** The cch table's other named sentinel: an add-in-referencing supporting link, whose ExternName records name add-in functions this reader has no workbook or sheet to resolve a name from. */
+const SUPBOOK_ADDIN_CCH = 14849;
+/** The inclusive cch range meaning "virtPath is present, and its own grammar (rather than a further sentinel) says what kind of supporting link this is" ([MS-XLS] 2.4.271's own cch table). */
+const SUPBOOK_VIRTPATH_MAX_CCH = 255;
+/** virtPath's own single-character sentinels ([MS-XLS] 31ed3738's own virtPath value table): a lone NUL marks a same-sheet reference, a lone SPACE an unused supporting link. */
+const SUPBOOK_SAME_SHEET_CHAR = "\0";
+const SUPBOOK_UNUSED_CHAR = " ";
+/**
+* SupBook ([MS-XLS] 2.4.271): a two-byte ctab, a two-byte cch, then -- for every kind but self-referencing and add-in-referencing -- a virtPath (an XLUnicodeStringNoCch, cch characters long) and, for an external-workbook or unused link specifically, ctab sheet names (XLUnicodeString) in rgst.
+*/
+function readSupBook(record) {
 	const cursor = new BlockCursor(record.blocks);
-	cursor.skip(2);
-	return cursor.u16() === SUPBOOK_SELF_REFERENCING_CCH;
+	const ctab = cursor.u16();
+	const cch = cursor.u16();
+	if (cch === SUPBOOK_SELF_REFERENCING_CCH) return { kind: "self" };
+	if (cch === SUPBOOK_ADDIN_CCH) return {
+		kind: "unresolvable",
+		diagnostic: "add-in function reference"
+	};
+	if (cch < 1 || cch > SUPBOOK_VIRTPATH_MAX_CCH) return {
+		kind: "unresolvable",
+		diagnostic: `supporting link of unrecognised type (cch=0x${cch.toString(16).padStart(4, "0")})`
+	};
+	const virtPath = readXLUnicodeStringNoCch(cursor, cch);
+	if (virtPath === SUPBOOK_SAME_SHEET_CHAR) return {
+		kind: "unresolvable",
+		diagnostic: "same-sheet reference"
+	};
+	if (virtPath === SUPBOOK_UNUSED_CHAR) return {
+		kind: "unresolvable",
+		diagnostic: "unused supporting link"
+	};
+	if (ctab === 0) return {
+		kind: "unresolvable",
+		diagnostic: "DDE or OLE data source reference"
+	};
+	const fileName = fileNameFromVirtPath(virtPath);
+	const sheetNames = [];
+	for (let index = 0; index < ctab; index += 1) sheetNames.push(readXLUnicodeString(cursor));
+	return {
+		kind: "external-workbook",
+		fileName,
+		sheetNames
+	};
+}
+/**
+* readSupBook, degrading a malformed record (an rgst shorter than its own declared ctab, most concretely) to an unresolvable diagnostic rather than letting a BiffFormatError propagate out of this one SupBook and abort the whole globals read -- and with it, the whole workbook. This is entirely new territory added alongside external-3D-reference resolution: before it, this reader never walked a SupBook's own virtPath/rgst at all, so a malformed one had nothing here to trip over. The per-record boundary keeps the damage to the XTI entries that resolve through this one SupBook, which already carry their own `unresolvable` label path for every other kind this reader cannot fully resolve.
+*/
+function readSupBookSafely(record) {
+	try {
+		return readSupBook(record);
+	} catch (error) {
+		if (!(error instanceof BiffFormatError)) throw error;
+		return {
+			kind: "unresolvable",
+			diagnostic: "malformed supporting link"
+		};
+	}
+}
+/** [MS-XLS] 480c3d2a's own VirtualPath grammar directory separator (U+0003) -- never a printable character a real file or sheet name may contain, so splitting on it to find the trailing segment is unambiguous. */
+const VIRTPATH_DIRECTORY_SEPARATOR = "";
+/** [MS-XLS] 480c3d2a's own two-character virt-path markers this reader still resolves a trailing file name through: rel-volume, startup, alt-startup, and library -- each %x0001 followed by one of these bytes, then file-path itself. Distinct from simple-file-path, whose own leading %x0001 (when present at all) stands ALONE, with no second marker byte, directly followed by file-path -- so any OTHER second character belongs to that file-path, not to a marker this function should also consume. */
+const VIRTPATH_REL_VOLUME_MARKER = 2;
+const VIRTPATH_STARTUP_MARKER = 6;
+const VIRTPATH_ALT_STARTUP_MARKER = 7;
+const VIRTPATH_LIBRARY_MARKER = 8;
+/**
+* Isolates a plain trailing file name from a SupBook's own virtPath, when it uses one of the VirtualPath grammar's simpler forms: simple-file-path (no marker at all, or its own optional lone %x0001 with no second marker byte), or a genuine two-character marker saying the path is relative to the referencing workbook's own drive, the startup directory, the alternate startup directory, or the library directory (rel-volume/startup/alt-startup/library -- [MS-XLS] 480c3d2a's own virt-path alternatives). An absolute drive volume, a UNC share, or a transfer-protocol URL needs more of the grammar than a trailing path segment to reproduce faithfully, so those return undefined rather than a guess -- readSupBook's own caller then shows the sheet name(s) (still fully resolvable from rgst) against a placeholder workbook label instead of discarding them. file-path's own bracketed form (`"[" relative-path "]" sheet-name`, naming a sheet directly in the path rather than through SupBook's separate rgst array) is outside what this reader reconstructs too, and is declined the same way rather than folded into the file name and doubled up with the caller's own `[bookLabel]` bracketing.
+*/
+function fileNameFromVirtPath(virtPath) {
+	let path = virtPath;
+	if (path.startsWith("
")) switch (path.codePointAt(1)) {
+		case 1:
+		case 5: return;
+		case VIRTPATH_REL_VOLUME_MARKER:
+		case VIRTPATH_STARTUP_MARKER:
+		case VIRTPATH_ALT_STARTUP_MARKER:
+		case VIRTPATH_LIBRARY_MARKER:
+			path = path.slice(2);
+			break;
+		default: path = path.slice(1);
+	}
+	if (path.length === 0) return;
+	const last = path.split(VIRTPATH_DIRECTORY_SEPARATOR).at(-1);
+	if (last === void 0 || last.length === 0) return;
+	return last.includes("[") || last.includes("]") ? void 0 : last;
+}
+/** A bracketed diagnostic placeholder for a sheet label this reader could not fully resolve -- deliberately distinct from Excel's own bare `#REF!` error literal (which is valid, retypeable formula syntax on its own): this always carries a parenthesised reason, and resolveSheetLabel's own quoting (biff/ptg.ts) wraps the whole thing in single quotes regardless, since neither the reason text nor the surrounding punctuation matches a bare sheet-name pattern. */
+function diagnosticLabel(reason) {
+	return `#REF!(${reason})`;
+}
+/**
+* One XTI's own scope resolved against its SupBook -- a plain SheetRange when the SupBook is this same, self-referencing workbook and both sheet indices are real ([MS-XLS] 2.5.344's own `-1` "could not be found" and `-2` "workbook-level" sentinels aside), otherwise an ExternalSheetLabel carrying whatever this reader could recover (an external workbook's own file name and sheet name(s), when the SupBook resolves that far) or a diagnostic placeholder, for a supporting-link kind or a sheet index this reader does not resolve a name from at all.
+*
+* The SupBook's own kind is checked before the `-2` sentinel, not after: [MS-XLS] 2.5.344's itabFirst/itabLast table produces `-2` for a same-sheet, add-in, DDE, and OLE supporting link alike (none of them names a sheet at all), so treating every `-2` as a generic "workbook-level reference" before asking what kind of SupBook it belongs to would overwrite each of those already-specific `unresolvable` diagnostics with a less useful, wrong one. `-2` only means "workbook-level" for the two kinds that otherwise resolve a real sheet scope -- self and external-workbook -- so the sentinel is scoped to those.
+*/
+function resolveXti(supBook, itabFirst, itabLast) {
+	if (supBook === void 0) return {
+		label: diagnosticLabel("supporting link index out of range"),
+		diagnostic: true
+	};
+	if (supBook.kind === "unresolvable") return {
+		label: diagnosticLabel(supBook.diagnostic),
+		diagnostic: true
+	};
+	if (itabFirst === -2 || itabLast === -2) return {
+		label: diagnosticLabel("workbook-level reference"),
+		diagnostic: true
+	};
+	if (supBook.kind === "self") return itabFirst >= 0 && itabLast >= 0 ? {
+		firstSheetIndex: itabFirst,
+		lastSheetIndex: itabLast
+	} : {
+		label: diagnosticLabel("sheet not found"),
+		diagnostic: true
+	};
+	const first = itabFirst >= 0 ? supBook.sheetNames[itabFirst] : void 0;
+	const last = itabLast >= 0 ? supBook.sheetNames[itabLast] : void 0;
+	if (first === void 0 || last === void 0) return {
+		label: `[${supBook.fileName ?? "EXTERNAL"}]${diagnosticLabel("sheet not found")}`,
+		diagnostic: true
+	};
+	if (supBook.fileName === void 0) return {
+		label: `[EXTERNAL]${first === last ? first : `${first}:${last}`}`,
+		diagnostic: true
+	};
+	return {
+		label: `[${supBook.fileName}]${first === last ? first : `${first}:${last}`}`,
+		diagnostic: false
+	};
 }
 /** ExternSheet ([MS-XLS] 2.4.106): a two-byte cXTI then that many XTI structures ([MS-XLS] 2.5.344) -- a two-byte iSupBook and two signed 16-bit sheet-scope bounds each. iSupBook indexes the SupBook collection positionally, in the order those records appeared. */
-function readSheetRanges(record, supBookSelfReferencing) {
+function readSheetRanges(record, supBooks) {
 	const cursor = new BlockCursor(record.blocks);
 	const count = cursor.u16();
 	const ranges = [];
@@ -80,10 +206,7 @@ function readSheetRanges(record, supBookSelfReferencing) {
 		const iSupBook = cursor.u16();
 		const itabFirst = cursor.i16();
 		const itabLast = cursor.i16();
-		ranges.push((supBookSelfReferencing[iSupBook] ?? false) && itabFirst >= 0 && itabLast >= 0 ? {
-			firstSheetIndex: itabFirst,
-			lastSheetIndex: itabLast
-		} : void 0);
+		ranges.push(resolveXti(supBooks[iSupBook], itabFirst, itabLast));
 	}
 	return ranges;
 }
@@ -106,7 +229,7 @@ function readSharedStrings(record) {
 	cursor.i32();
 	const uniqueCount = cursor.i32();
 	if (uniqueCount < 0) throw new BiffFormatError(`SST declares a negative unique-string count (${uniqueCount})`);
-	const totalBytes = record.blocks.reduce((sum, block) => sum + block.length, 0);
+	const totalBytes = recordByteLength(record);
 	if (uniqueCount * MIN_SST_ENTRY_BYTES > totalBytes) throw new BiffFormatError(`SST declares ${uniqueCount} unique strings, more than its ${totalBytes} bytes could carry`);
 	const strings = [];
 	for (let index = 0; index < uniqueCount; index += 1) strings.push(readRichExtendedString(cursor));

package/dist/workbook/print-names.d.cts

@@ -1,2 +1,2 @@
-import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-D-njuzVw.cjs";
+import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-DyYloloV.cjs";
 export { PrintNamePlanEntry, SheetPrintNames, printNameEntriesFor, readPrintNames, writePrintNameRecords };

package/dist/workbook/print-names.d.ts

@@ -1,2 +1,2 @@
-import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-DUlpVE00.js";
+import { a as writePrintNameRecords, i as readPrintNames, n as SheetPrintNames, r as printNameEntriesFor, t as PrintNamePlanEntry } from "../print-names-C-PQ2vAy.js";
 export { PrintNamePlanEntry, SheetPrintNames, printNameEntriesFor, readPrintNames, writePrintNameRecords };

package/dist/workbook/sheet.cjs

@@ -3,6 +3,7 @@ require("../biff/record-types.cjs");
 const require_biff_records = require("../biff/records.cjs");
 const require_units = require("../units.cjs");
 const require_biff_print_setup = require("../biff/print-setup.cjs");
+const require_biff_substreams = require("../biff/substreams.cjs");
 const require_biff_cursor = require("../biff/cursor.cjs");
 const require_biff_strings = require("../biff/strings.cjs");
 const require_biff_errors = require("../biff/errors.cjs");
@@ -31,8 +32,80 @@ const EMPTY_FORMULA_SHEET_CONTEXT = {
 	sheets: [],
 	sheetRanges: []
 };
+/** The key collectFormulaGroups and its lookup agree on: a shared/array formula group's own base cell, the same (row, column) a PtgExp token elsewhere in the sheet points back to. */
+function groupKey(row, column) {
+	return `${row},${column}`;
+}
+/**
+* Walks every record once, looking for a Formula record immediately followed by a ShrFmla or Array record ([MS-XLS] 2.1.7.20.6's own FORMULA production, and 984826cc/c6ee7512's own "this record is preceded by a single Formula record"), and returns the shared/array expression each one carries, keyed by that Formula record's own cell -- the same (row, column) a PtgExp token names when it points back to this group (see readPtgExpBase, and readFormula below which performs the actual lookup).
+*
+* Built as a single upfront pass over the whole sheet rather than interleaved into readSheetRecords' own per-record loop: every Formula record that uses a shared/array formula (including the group's own base cell, which points at itself) needs this map already complete when it is reached, and although [MS-XLS] guarantees the base pair precedes every other use, resolving the whole map first removes that ordering as a correctness dependency rather than merely relying on it.
+*/
+function collectFormulaGroups(records) {
+	const groups = /* @__PURE__ */ new Map();
+	for (let index = 0; index < records.length; index += 1) {
+		const record = records[index];
+		const next = records[index + 1];
+		if (record === void 0 || next === void 0) continue;
+		if (record.type !== 6) continue;
+		if (next.type === 1212) collectFormulaGroup(groups, record, next, readShrFmlaGroup);
+		else if (next.type === 545) collectFormulaGroup(groups, record, next, readArrayGroup);
+	}
+	return groups;
+}
+/**
+* Reads one shared/array formula group and keys it by its base Formula record's own cell, degrading a malformed ShrFmla/Array record to "no group recovered for this base cell" rather than letting a BiffFormatError propagate out of collectFormulaGroups and abort the whole sheet read (and every other cell in it, formula or not). readCellHeader and readGroup (readShrFmlaGroup or readArrayGroup) between them make several cursor reads capable of raising that error, not only the final `cursor.take(cce)` that copies out rgce itself: an undersized record already runs out of bytes during readCellHeader's own Cell fields, or during readShrFmlaGroup/readArrayGroup's leading `cursor.skip` past their fixed header, or during the `cursor.u16()` that reads cce -- every one of those, like the `take`, is a plain read past this record's own declared bytes, and every one is caught here the same way. This is the same per-record boundary readSupBookSafely already draws for a malformed SupBook (workbook/globals.ts): before this reader ever walked a ShrFmla/Array record's own length fields, a malformed one had nothing here to trip over, so this is entirely new territory the read-every-record-once contract now needs to hold against. A cell whose Formula record points at this base through a PtgExp then resolves to no formula text at all -- exactly the same outcome "leaves formula absent for a PtgExp whose base cell has no matching ShrFmla/Array group" already documents for a dangling reference, since from resolveFormulaText's own vantage point the two cases are indistinguishable.
+*/
+function collectFormulaGroup(groups, record, next, readGroup) {
+	try {
+		const header = readCellHeader(new require_biff_cursor.BlockCursor(record.blocks));
+		groups.set(groupKey(header.row, header.column), readGroup(next));
+	} catch (error) {
+		if (!(error instanceof require_biff_records.BiffFormatError)) throw error;
+	}
+}
+/** ShrFmla ([MS-XLS] 984826cc): a RefU range (6 bytes, not needed here -- the group is looked up by its base cell's own coordinates, not by re-deriving them from this range), a reserved byte, a cUse byte, then a SharedParsedFormula (458bbec0): a two-byte cce and that many bytes of rgce. Its own rgce is forbidden from containing PtgArray ([MS-XLS] 458bbec0's own "MUST NOT contain... PtgArray"), so no rgcb is read here. */
+const SHRFMLA_HEADER_BYTES = 8;
+function readShrFmlaGroup(record) {
+	const cursor = new require_biff_cursor.BlockCursor(record.blocks);
+	cursor.skip(SHRFMLA_HEADER_BYTES);
+	const cce = cursor.u16();
+	return {
+		kind: "shared",
+		rgce: cursor.take(cce)
+	};
+}
+/** Array ([MS-XLS] c6ee7512): a Ref range (6 bytes), a flags word (fAlwaysCalc plus reserved bits), four unused bytes, then an ArrayParsedFormula (242bcf20): a two-byte cce, that many bytes of rgce, and -- unlike ShrFmla's own SharedParsedFormula -- a real rgcb trailer, since an array formula's rgce CAN contain a PtgArray for an array-constant literal used within it (e.g. `{=A1:A3+{1;2;3}}`). rgcb's own length is never stated directly: it is whatever bytes remain in the record once the header and rgce are accounted for. */
+const ARRAY_HEADER_BYTES = 12;
+function readArrayGroup(record) {
+	const cursor = new require_biff_cursor.BlockCursor(record.blocks);
+	cursor.skip(ARRAY_HEADER_BYTES);
+	const cce = cursor.u16();
+	const rgce = cursor.take(cce);
+	const rgcbLength = require_biff_substreams.recordByteLength(record) - (14 + cce);
+	if (rgcbLength <= 0) return {
+		kind: "array",
+		rgce,
+		rgcb: void 0
+	};
+	try {
+		return {
+			kind: "array",
+			rgce,
+			rgcb: cursor.take(rgcbLength)
+		};
+	} catch (error) {
+		if (!(error instanceof require_biff_records.BiffFormatError)) throw error;
+		return {
+			kind: "array",
+			rgce,
+			rgcb: void 0
+		};
+	}
+}
 /** Reads one worksheet substream's records. */
 function readSheetRecords(records, sharedStrings, formulaSheets = EMPTY_FORMULA_SHEET_CONTEXT) {
+	const formulaGroups = collectFormulaGroups(records);
 	const cells = [];
 	const rows = [];
 	const columns = [];
@@ -88,7 +161,7 @@ function readSheetRecords(records, sharedStrings, formulaSheets = EMPTY_FORMULA_
 				cells.push(readLabel(record));
 				break;
 			case 6:
-				cells.push(readFormula(record, stringResultAfter(records, index), formulaSheets));
+				cells.push(readFormula(record, stringResultAfter(records, index), formulaSheets, formulaGroups));
 				break;
 			case 161:
 				setup = readSetup(record);
@@ -345,7 +418,7 @@ function readMulRk(record) {
 }
 /** Both Mul records put colLast after their variable-length array, so the entry count follows from the record's own length: total = rw + colFirst + N*entry + colLast. */
 function mulEntryCount(record, entryBytes) {
-	const total = record.blocks.reduce((sum, block) => sum + block.length, 0);
+	const total = require_biff_substreams.recordByteLength(record);
 	const payload = total - MUL_FIXED_BYTES;
 	if (payload < 0 || payload % entryBytes !== 0) throw new require_biff_records.BiffFormatError(`multiple-cell record of ${total} bytes does not hold a whole number of ${entryBytes}-byte entries`);
 	return payload / entryBytes;
@@ -417,12 +490,14 @@ function readLabel(record) {
 /** The Formula record's own flags field ([MS-XLS] 2.4.127) and calculation cache, between the cached value and the compiled expression -- neither read for its own content; see the two-byte and four-byte skips in readFormula. */
 const FORMULA_FLAGS_BYTES = 2;
 const FORMULA_CALC_CACHE_BYTES = 4;
+/** The Cell (6 bytes) and FormulaValue (8 bytes) fields readFormula has already consumed by the time it reaches cce, plus the flags and calculation-cache fields above and the cce field itself (2 bytes) -- what's left of the record past `FORMULA_HEADER_BYTES + cce` is the CellParsedFormula's own rgcb trailer. */
+const FORMULA_HEADER_BYTES = 22;
 /**
-* Formula ([MS-XLS] 2.4.127): a Cell, an eight-byte FormulaValue, flags, a calculation cache, then a CellParsedFormula -- a two-byte cce followed by exactly that many bytes of compiled Ptg tokens ([MS-XLS] 2.5.198.3).
+* Formula ([MS-XLS] 2.4.127): a Cell, an eight-byte FormulaValue, flags, a calculation cache, then a CellParsedFormula -- a two-byte cce, that many bytes of compiled Ptg tokens ([MS-XLS] 2.5.198.3), and (whenever rgce contains a PtgArray -- an inline array-constant literal like `=SUM({1,2,3})`, unrelated to whether the cell itself is CSE-array-entered) an RgbExtra trailer of whatever bytes remain in the record.
 *
-* Both the cached value and the expression are read: the value from the FormulaValue exactly as before, and the expression by handing the token bytes to biff/ptg.ts's parseFormulaText, which resolves the whole Ptg vocabulary this reader supports and returns undefined for the constructs it does not (a shared formula, an array formula, a defined name, a natural-language reference, a genuinely external 3D reference -- see that module's own boundary). `formula` is attached only when it resolves; a cell it does not resolve for keeps exactly the behaviour this reader always had, its cached value present and `formula` absent.
+* Both the cached value and the expression are read: the value from the FormulaValue exactly as before, and the expression by resolveFormulaText below, which joins a lone PtgExp against the shared/array formula group collectFormulaGroups found for it and otherwise hands the token bytes straight to biff/ptg.ts's parseFormulaText. `formula` is attached only when it resolves; a cell it does not resolve for keeps exactly the behaviour this reader always had, its cached value present and `formula` absent.
 */
-function readFormula(record, next, formulaSheets) {
+function readFormula(record, next, formulaSheets, formulaGroups) {
 	const cursor = new require_biff_cursor.BlockCursor(record.blocks);
 	const header = readCellHeader(cursor);
 	const bytes = cursor.take(8);
@@ -434,7 +509,18 @@ function readFormula(record, next, formulaSheets) {
 	cursor.skip(FORMULA_FLAGS_BYTES);
 	cursor.skip(FORMULA_CALC_CACHE_BYTES);
 	const cce = cursor.u16();
-	const formula = require_biff_ptg.parseFormulaText(cursor.take(cce), formulaSheets);
+	let rgce;
+	let rgcb;
+	try {
+		rgce = cursor.take(cce);
+		const rgcbLength = require_biff_substreams.recordByteLength(record) - (FORMULA_HEADER_BYTES + cce);
+		rgcb = rgcbLength > 0 ? cursor.take(rgcbLength) : void 0;
+	} catch (error) {
+		if (!(error instanceof require_biff_records.BiffFormatError)) throw error;
+		rgce = void 0;
+		rgcb = void 0;
+	}
+	const formula = rgce === void 0 ? void 0 : resolveFormulaText(rgce, rgcb, header, formulaSheets, formulaGroups);
 	return formula === void 0 ? {
 		...header,
 		value,
@@ -446,6 +532,23 @@ function readFormula(record, next, formulaSheets) {
 		formula
 	};
 }
+/**
+* A Formula record's rgce resolves one of three ways: a lone PtgExp pointing back to a shared-formula base cell, whose real expression (a ShrFmla's SharedParsedFormula) is expanded relative to THIS cell's own position; a lone PtgExp pointing back to an array-formula base cell, whose real expression (an Array's ArrayParsedFormula) is identical for every cell in the range and is returned as-is, with no CSE bracing (see ArrayFormulaGroup's own comment for why); or an ordinary rgce, handed to parseFormulaText as-is (with this record's own rgcb, for an inline array-constant literal). A PtgExp with no matching group -- a dangling or malformed reference this reader cannot join -- resolves to undefined exactly like any other unsupported construct.
+*
+* All three branches share the same hazard and are wrapped in one catch below: a token's own embedded length (a PtgStr's character count is the reachable case, [MS-XLS] 2.5.240's cch, read straight from the file with nothing to cross-check it against) can claim more bytes than the buffer parseFormulaText's cursor was actually handed, running that cursor past its end -- for the group-joining branches because `group.rgce` was extracted from a DIFFERENT, well-formed record whose own cce correctly bounds it, and for the ordinary-rgce branch because THIS record's own cce can just as easily be too short for the token it claims to end after (or a token inside an otherwise-correctly-bounded rgce can lie the same way `group.rgce`'s can). Neither case is a bug in this reader's own token walking; both are file-controlled malformed input, and left uncaught either would propagate out of readFormula and abort every other cell on the sheet along with the one cell whose formula this is -- exactly the failure collectFormulaGroup already prevents for a group whose OWN record is malformed, extended here to malformed token content reached through any of the three paths above.
+*/
+function resolveFormulaText(rgce, rgcb, header, formulaSheets, formulaGroups) {
+	const base = require_biff_ptg.readPtgExpBase(rgce);
+	try {
+		if (base === void 0) return require_biff_ptg.parseFormulaText(rgce, formulaSheets, { rgcb });
+		const group = formulaGroups.get(groupKey(base.row, base.column));
+		if (group === void 0) return;
+		return group.kind === "shared" ? require_biff_ptg.parseFormulaText(group.rgce, formulaSheets, { relativeTo: header }) : require_biff_ptg.parseFormulaText(group.rgce, formulaSheets, { rgcb: group.rgcb });
+	} catch (error) {
+		if (!(error instanceof require_biff_records.BiffFormatError)) throw error;
+		return;
+	}
+}
 /** The non-numeric readings of a FormulaValue ([MS-XLS] 2.5.133), selected by its first byte. */
 function taggedFormulaValue(view, next) {
 	switch (view.getUint8(0)) {

package/dist/workbook/sheet.d.cts

@@ -1,6 +1,6 @@
 import { n as SetupFields } from "../print-setup-B_ihDvm5.cjs";
-import { t as FormulaSheetContext } from "../ptg-B2K8t3js.cjs";
-import { t as RecordGroup } from "../substreams-Ddtvn_Vr.cjs";
+import { r as FormulaSheetContext } from "../ptg-CCBbJLZJ.cjs";
+import { t as RecordGroup } from "../substreams-Cpy5Fi3d.cjs";
 //#region src/workbook/sheet.d.ts
 /** A cell's value as its own record carries it, before number-format classification decides whether a number is really a date, a percentage, or an amount of money. */
 type RawCellValue = {
@@ -27,7 +27,7 @@ interface RawCell {
   readonly value: RawCellValue;
   /** True when the value is a Formula record's CACHED result rather than a literal. */
   readonly fromFormula: boolean;
-  /** The formula's own text, recovered from its compiled Ptg token stream ([MS-XLS] 2.5.198), when every token in it is one this reader resolves -- absent for a shared-formula member, an array formula, a defined-name or natural-language reference, or a 3D reference into a genuinely external workbook (see biff/ptg.ts). */
+  /** The formula's own text, recovered from its compiled Ptg token stream ([MS-XLS] 2.5.198), when every token in it is one this reader resolves -- absent for a defined-name or natural-language reference, or a data table (see biff/ptg.ts). */
   readonly formula?: string;
 }
 interface RawRow {

package/dist/workbook/sheet.d.ts

@@ -1,6 +1,6 @@
 import { n as SetupFields } from "../print-setup-B_ihDvm5.js";
-import { t as FormulaSheetContext } from "../ptg-B2K8t3js.js";
-import { t as RecordGroup } from "../substreams-D7dQiJbp.js";
+import { r as FormulaSheetContext } from "../ptg-CCBbJLZJ.js";
+import { t as RecordGroup } from "../substreams-CmyZMtuM.js";
 //#region src/workbook/sheet.d.ts
 /** A cell's value as its own record carries it, before number-format classification decides whether a number is really a date, a percentage, or an amount of money. */
 type RawCellValue = {
@@ -27,7 +27,7 @@ interface RawCell {
   readonly value: RawCellValue;
   /** True when the value is a Formula record's CACHED result rather than a literal. */
   readonly fromFormula: boolean;
-  /** The formula's own text, recovered from its compiled Ptg token stream ([MS-XLS] 2.5.198), when every token in it is one this reader resolves -- absent for a shared-formula member, an array formula, a defined-name or natural-language reference, or a 3D reference into a genuinely external workbook (see biff/ptg.ts). */
+  /** The formula's own text, recovered from its compiled Ptg token stream ([MS-XLS] 2.5.198), when every token in it is one this reader resolves -- absent for a defined-name or natural-language reference, or a data table (see biff/ptg.ts). */
   readonly formula?: string;
 }
 interface RawRow {

package/dist/workbook/sheet.js

@@ -2,10 +2,11 @@ import "../biff/record-types.js";
 import { BiffFormatError } from "../biff/records.js";
 import { columnWidthToPoints, inchesToPoints, twipsToPoints } from "../units.js";
 import { unpackSetupFlags } from "../biff/print-setup.js";
+import { recordByteLength } from "../biff/substreams.js";
 import { BlockCursor } from "../biff/cursor.js";
 import { readXLUnicodeString } from "../biff/strings.js";
 import { errorTextOf } from "../biff/errors.js";
-import { parseFormulaText } from "../biff/ptg.js";
+import { parseFormulaText, readPtgExpBase } from "../biff/ptg.js";
 import { decodeRkNumber } from "../biff/rk.js";
 //#region src/workbook/sheet.ts
 /** Row record flag bits, in the 32-bit field following unused1 ([MS-XLS] 2.4.221). */
@@ -30,8 +31,80 @@ const EMPTY_FORMULA_SHEET_CONTEXT = {
 	sheets: [],
 	sheetRanges: []
 };
+/** The key collectFormulaGroups and its lookup agree on: a shared/array formula group's own base cell, the same (row, column) a PtgExp token elsewhere in the sheet points back to. */
+function groupKey(row, column) {
+	return `${row},${column}`;
+}
+/**
+* Walks every record once, looking for a Formula record immediately followed by a ShrFmla or Array record ([MS-XLS] 2.1.7.20.6's own FORMULA production, and 984826cc/c6ee7512's own "this record is preceded by a single Formula record"), and returns the shared/array expression each one carries, keyed by that Formula record's own cell -- the same (row, column) a PtgExp token names when it points back to this group (see readPtgExpBase, and readFormula below which performs the actual lookup).
+*
+* Built as a single upfront pass over the whole sheet rather than interleaved into readSheetRecords' own per-record loop: every Formula record that uses a shared/array formula (including the group's own base cell, which points at itself) needs this map already complete when it is reached, and although [MS-XLS] guarantees the base pair precedes every other use, resolving the whole map first removes that ordering as a correctness dependency rather than merely relying on it.
+*/
+function collectFormulaGroups(records) {
+	const groups = /* @__PURE__ */ new Map();
+	for (let index = 0; index < records.length; index += 1) {
+		const record = records[index];
+		const next = records[index + 1];
+		if (record === void 0 || next === void 0) continue;
+		if (record.type !== 6) continue;
+		if (next.type === 1212) collectFormulaGroup(groups, record, next, readShrFmlaGroup);
+		else if (next.type === 545) collectFormulaGroup(groups, record, next, readArrayGroup);
+	}
+	return groups;
+}
+/**
+* Reads one shared/array formula group and keys it by its base Formula record's own cell, degrading a malformed ShrFmla/Array record to "no group recovered for this base cell" rather than letting a BiffFormatError propagate out of collectFormulaGroups and abort the whole sheet read (and every other cell in it, formula or not). readCellHeader and readGroup (readShrFmlaGroup or readArrayGroup) between them make several cursor reads capable of raising that error, not only the final `cursor.take(cce)` that copies out rgce itself: an undersized record already runs out of bytes during readCellHeader's own Cell fields, or during readShrFmlaGroup/readArrayGroup's leading `cursor.skip` past their fixed header, or during the `cursor.u16()` that reads cce -- every one of those, like the `take`, is a plain read past this record's own declared bytes, and every one is caught here the same way. This is the same per-record boundary readSupBookSafely already draws for a malformed SupBook (workbook/globals.ts): before this reader ever walked a ShrFmla/Array record's own length fields, a malformed one had nothing here to trip over, so this is entirely new territory the read-every-record-once contract now needs to hold against. A cell whose Formula record points at this base through a PtgExp then resolves to no formula text at all -- exactly the same outcome "leaves formula absent for a PtgExp whose base cell has no matching ShrFmla/Array group" already documents for a dangling reference, since from resolveFormulaText's own vantage point the two cases are indistinguishable.
+*/
+function collectFormulaGroup(groups, record, next, readGroup) {
+	try {
+		const header = readCellHeader(new BlockCursor(record.blocks));
+		groups.set(groupKey(header.row, header.column), readGroup(next));
+	} catch (error) {
+		if (!(error instanceof BiffFormatError)) throw error;
+	}
+}
+/** ShrFmla ([MS-XLS] 984826cc): a RefU range (6 bytes, not needed here -- the group is looked up by its base cell's own coordinates, not by re-deriving them from this range), a reserved byte, a cUse byte, then a SharedParsedFormula (458bbec0): a two-byte cce and that many bytes of rgce. Its own rgce is forbidden from containing PtgArray ([MS-XLS] 458bbec0's own "MUST NOT contain... PtgArray"), so no rgcb is read here. */
+const SHRFMLA_HEADER_BYTES = 8;
+function readShrFmlaGroup(record) {
+	const cursor = new BlockCursor(record.blocks);
+	cursor.skip(SHRFMLA_HEADER_BYTES);
+	const cce = cursor.u16();
+	return {
+		kind: "shared",
+		rgce: cursor.take(cce)
+	};
+}
+/** Array ([MS-XLS] c6ee7512): a Ref range (6 bytes), a flags word (fAlwaysCalc plus reserved bits), four unused bytes, then an ArrayParsedFormula (242bcf20): a two-byte cce, that many bytes of rgce, and -- unlike ShrFmla's own SharedParsedFormula -- a real rgcb trailer, since an array formula's rgce CAN contain a PtgArray for an array-constant literal used within it (e.g. `{=A1:A3+{1;2;3}}`). rgcb's own length is never stated directly: it is whatever bytes remain in the record once the header and rgce are accounted for. */
+const ARRAY_HEADER_BYTES = 12;
+function readArrayGroup(record) {
+	const cursor = new BlockCursor(record.blocks);
+	cursor.skip(ARRAY_HEADER_BYTES);
+	const cce = cursor.u16();
+	const rgce = cursor.take(cce);
+	const rgcbLength = recordByteLength(record) - (14 + cce);
+	if (rgcbLength <= 0) return {
+		kind: "array",
+		rgce,
+		rgcb: void 0
+	};
+	try {
+		return {
+			kind: "array",
+			rgce,
+			rgcb: cursor.take(rgcbLength)
+		};
+	} catch (error) {
+		if (!(error instanceof BiffFormatError)) throw error;
+		return {
+			kind: "array",
+			rgce,
+			rgcb: void 0
+		};
+	}
+}
 /** Reads one worksheet substream's records. */
 function readSheetRecords(records, sharedStrings, formulaSheets = EMPTY_FORMULA_SHEET_CONTEXT) {
+	const formulaGroups = collectFormulaGroups(records);
 	const cells = [];
 	const rows = [];
 	const columns = [];
@@ -87,7 +160,7 @@ function readSheetRecords(records, sharedStrings, formulaSheets = EMPTY_FORMULA_
 				cells.push(readLabel(record));
 				break;
 			case 6:
-				cells.push(readFormula(record, stringResultAfter(records, index), formulaSheets));
+				cells.push(readFormula(record, stringResultAfter(records, index), formulaSheets, formulaGroups));
 				break;
 			case 161:
 				setup = readSetup(record);
@@ -344,7 +417,7 @@ function readMulRk(record) {
 }
 /** Both Mul records put colLast after their variable-length array, so the entry count follows from the record's own length: total = rw + colFirst + N*entry + colLast. */
 function mulEntryCount(record, entryBytes) {
-	const total = record.blocks.reduce((sum, block) => sum + block.length, 0);
+	const total = recordByteLength(record);
 	const payload = total - MUL_FIXED_BYTES;
 	if (payload < 0 || payload % entryBytes !== 0) throw new BiffFormatError(`multiple-cell record of ${total} bytes does not hold a whole number of ${entryBytes}-byte entries`);
 	return payload / entryBytes;
@@ -416,12 +489,14 @@ function readLabel(record) {
 /** The Formula record's own flags field ([MS-XLS] 2.4.127) and calculation cache, between the cached value and the compiled expression -- neither read for its own content; see the two-byte and four-byte skips in readFormula. */
 const FORMULA_FLAGS_BYTES = 2;
 const FORMULA_CALC_CACHE_BYTES = 4;
+/** The Cell (6 bytes) and FormulaValue (8 bytes) fields readFormula has already consumed by the time it reaches cce, plus the flags and calculation-cache fields above and the cce field itself (2 bytes) -- what's left of the record past `FORMULA_HEADER_BYTES + cce` is the CellParsedFormula's own rgcb trailer. */
+const FORMULA_HEADER_BYTES = 22;
 /**
-* Formula ([MS-XLS] 2.4.127): a Cell, an eight-byte FormulaValue, flags, a calculation cache, then a CellParsedFormula -- a two-byte cce followed by exactly that many bytes of compiled Ptg tokens ([MS-XLS] 2.5.198.3).
+* Formula ([MS-XLS] 2.4.127): a Cell, an eight-byte FormulaValue, flags, a calculation cache, then a CellParsedFormula -- a two-byte cce, that many bytes of compiled Ptg tokens ([MS-XLS] 2.5.198.3), and (whenever rgce contains a PtgArray -- an inline array-constant literal like `=SUM({1,2,3})`, unrelated to whether the cell itself is CSE-array-entered) an RgbExtra trailer of whatever bytes remain in the record.
 *
-* Both the cached value and the expression are read: the value from the FormulaValue exactly as before, and the expression by handing the token bytes to biff/ptg.ts's parseFormulaText, which resolves the whole Ptg vocabulary this reader supports and returns undefined for the constructs it does not (a shared formula, an array formula, a defined name, a natural-language reference, a genuinely external 3D reference -- see that module's own boundary). `formula` is attached only when it resolves; a cell it does not resolve for keeps exactly the behaviour this reader always had, its cached value present and `formula` absent.
+* Both the cached value and the expression are read: the value from the FormulaValue exactly as before, and the expression by resolveFormulaText below, which joins a lone PtgExp against the shared/array formula group collectFormulaGroups found for it and otherwise hands the token bytes straight to biff/ptg.ts's parseFormulaText. `formula` is attached only when it resolves; a cell it does not resolve for keeps exactly the behaviour this reader always had, its cached value present and `formula` absent.
 */
-function readFormula(record, next, formulaSheets) {
+function readFormula(record, next, formulaSheets, formulaGroups) {
 	const cursor = new BlockCursor(record.blocks);
 	const header = readCellHeader(cursor);
 	const bytes = cursor.take(8);
@@ -433,7 +508,18 @@ function readFormula(record, next, formulaSheets) {
 	cursor.skip(FORMULA_FLAGS_BYTES);
 	cursor.skip(FORMULA_CALC_CACHE_BYTES);
 	const cce = cursor.u16();
-	const formula = parseFormulaText(cursor.take(cce), formulaSheets);
+	let rgce;
+	let rgcb;
+	try {
+		rgce = cursor.take(cce);
+		const rgcbLength = recordByteLength(record) - (FORMULA_HEADER_BYTES + cce);
+		rgcb = rgcbLength > 0 ? cursor.take(rgcbLength) : void 0;
+	} catch (error) {
+		if (!(error instanceof BiffFormatError)) throw error;
+		rgce = void 0;
+		rgcb = void 0;
+	}
+	const formula = rgce === void 0 ? void 0 : resolveFormulaText(rgce, rgcb, header, formulaSheets, formulaGroups);
 	return formula === void 0 ? {
 		...header,
 		value,
@@ -445,6 +531,23 @@ function readFormula(record, next, formulaSheets) {
 		formula
 	};
 }
+/**
+* A Formula record's rgce resolves one of three ways: a lone PtgExp pointing back to a shared-formula base cell, whose real expression (a ShrFmla's SharedParsedFormula) is expanded relative to THIS cell's own position; a lone PtgExp pointing back to an array-formula base cell, whose real expression (an Array's ArrayParsedFormula) is identical for every cell in the range and is returned as-is, with no CSE bracing (see ArrayFormulaGroup's own comment for why); or an ordinary rgce, handed to parseFormulaText as-is (with this record's own rgcb, for an inline array-constant literal). A PtgExp with no matching group -- a dangling or malformed reference this reader cannot join -- resolves to undefined exactly like any other unsupported construct.
+*
+* All three branches share the same hazard and are wrapped in one catch below: a token's own embedded length (a PtgStr's character count is the reachable case, [MS-XLS] 2.5.240's cch, read straight from the file with nothing to cross-check it against) can claim more bytes than the buffer parseFormulaText's cursor was actually handed, running that cursor past its end -- for the group-joining branches because `group.rgce` was extracted from a DIFFERENT, well-formed record whose own cce correctly bounds it, and for the ordinary-rgce branch because THIS record's own cce can just as easily be too short for the token it claims to end after (or a token inside an otherwise-correctly-bounded rgce can lie the same way `group.rgce`'s can). Neither case is a bug in this reader's own token walking; both are file-controlled malformed input, and left uncaught either would propagate out of readFormula and abort every other cell on the sheet along with the one cell whose formula this is -- exactly the failure collectFormulaGroup already prevents for a group whose OWN record is malformed, extended here to malformed token content reached through any of the three paths above.
+*/
+function resolveFormulaText(rgce, rgcb, header, formulaSheets, formulaGroups) {
+	const base = readPtgExpBase(rgce);
+	try {
+		if (base === void 0) return parseFormulaText(rgce, formulaSheets, { rgcb });
+		const group = formulaGroups.get(groupKey(base.row, base.column));
+		if (group === void 0) return;
+		return group.kind === "shared" ? parseFormulaText(group.rgce, formulaSheets, { relativeTo: header }) : parseFormulaText(group.rgce, formulaSheets, { rgcb: group.rgcb });
+	} catch (error) {
+		if (!(error instanceof BiffFormatError)) throw error;
+		return;
+	}
+}
 /** The non-numeric readings of a FormulaValue ([MS-XLS] 2.5.133), selected by its first byte. */
 function taggedFormulaValue(view, next) {
 	switch (view.getUint8(0)) {