xls-codec 0.0.0 → 1.0.1

package/dist/biff/record-types.d.ts

@@ -0,0 +1,73 @@
+//#region src/biff/record-types.d.ts
+/** Marks the beginning of a substream and names its document type ([MS-XLS] 2.4.21). */
+declare const RECORD_BOF = 2057;
+/** Marks the end of a substream ([MS-XLS] 2.4.103). */
+declare const RECORD_EOF = 10;
+/** Carries the overflow of a preceding record whose data exceeds what one record can hold ([MS-XLS] 2.4.58). */
+declare const RECORD_CONTINUE = 60;
+/** One per sheet: its name, hidden state, type, and the stream offset of its own BOF ([MS-XLS] 2.4.28). */
+declare const RECORD_BOUNDSHEET8 = 133;
+/** The shared string table every LabelSst cell indexes into ([MS-XLS] 2.4.265). */
+declare const RECORD_SST = 252;
+/** A custom number-format code and the identifier cells reference it by ([MS-XLS] 2.4.126). */
+declare const RECORD_FORMAT = 1054;
+/** A cell or cell-style extended format record ([MS-XLS] 2.4.353). */
+declare const RECORD_XF = 224;
+/** A font definition, referenced by index from an XF ([MS-XLS] 2.4.122). */
+declare const RECORD_FONT = 49;
+/** Which of the two date epochs this workbook's serials count from ([MS-XLS] 2.4.77). */
+declare const RECORD_DATE1904 = 34;
+/** Present only in an encrypted workbook, where every record after it is ciphertext ([MS-XLS] 2.4.117). */
+declare const RECORD_FILEPASS = 47;
+/** The sheet's used range ([MS-XLS] 2.4.90). */
+declare const RECORD_DIMENSIONS = 512;
+/** A single row's height, hidden state, and formatting ([MS-XLS] 2.4.221). */
+declare const RECORD_ROW = 520;
+/** Column width, hidden state, and default format for a range of columns ([MS-XLS] 2.4.53). */
+declare const RECORD_COLINFO = 125;
+/** The sheet's default column width, in whole character widths ([MS-XLS] 2.4.89). */
+declare const RECORD_DEFCOLWIDTH = 85;
+/** The sheet's default row height ([MS-XLS] 2.4.87). */
+declare const RECORD_DEFAULTROWHEIGHT = 549;
+/** Merged cell ranges ([MS-XLS] 2.4.168). */
+declare const RECORD_MERGECELLS = 229;
+/** An empty cell carrying only formatting ([MS-XLS] 2.4.20). */
+declare const RECORD_BLANK = 513;
+/** A run of empty cells in one row ([MS-XLS] 2.4.174). */
+declare const RECORD_MULBLANK = 190;
+/** A cell holding an RK-encoded number ([MS-XLS] 2.4.220). */
+declare const RECORD_RK = 638;
+/** A run of RK-encoded numeric cells in one row ([MS-XLS] 2.4.175). */
+declare const RECORD_MULRK = 189;
+/** A cell holding an IEEE 754 double ([MS-XLS] 2.4.180). */
+declare const RECORD_NUMBER = 515;
+/** A cell holding a boolean or an error value ([MS-XLS] 2.4.24). */
+declare const RECORD_BOOLERR = 517;
+/** A cell holding a string by index into the shared string table ([MS-XLS] 2.4.149). */
+declare const RECORD_LABELSST = 253;
+/** A cell holding an inline string ([MS-XLS] 2.4.148). See the reader's own note on why BIFF8 still meets this in the wild. */
+declare const RECORD_LABEL = 516;
+/** A cell holding a formula, its cached result, and its parsed expression ([MS-XLS] 2.4.127). */
+declare const RECORD_FORMULA = 6;
+/** The string result of the Formula record preceding it ([MS-XLS] 2.4.268). */
+declare const RECORD_STRING = 519;
+/** The expression of an array formula, following the Formula record of its top-left cell ([MS-XLS] 2.4.4). */
+declare const RECORD_ARRAY = 545;
+/** A data-table definition following a Formula record ([MS-XLS] 2.4.334). */
+declare const RECORD_TABLE = 566;
+/** The shared expression a run of Formula records refers to ([MS-XLS] 2.4.260). */
+declare const RECORD_SHRFMLA = 1212;
+/** The workbook globals substream. */
+declare const BOF_TYPE_WORKBOOK = 5;
+/** A worksheet or dialog sheet substream. */
+declare const BOF_TYPE_WORKSHEET = 16;
+/** A chart sheet substream. */
+declare const BOF_TYPE_CHART = 32;
+/** A macro sheet substream. */
+declare const BOF_TYPE_MACRO = 64;
+/** The BIFF version every BOF in a BIFF8 workbook stream declares ([MS-XLS] 2.4.21: "The value MUST be 0x0600"). */
+declare const BIFF8_VERSION = 1536;
+/** [MS-XLS] 2.1.4: "The record size ... MUST be less than or equal to 8224." The ceiling a writer splits a record at, and the bound a reader can sanity-check a declared size against. */
+declare const MAX_RECORD_DATA_SIZE = 8224;
+//#endregion
+export { BIFF8_VERSION, BOF_TYPE_CHART, BOF_TYPE_MACRO, BOF_TYPE_WORKBOOK, BOF_TYPE_WORKSHEET, MAX_RECORD_DATA_SIZE, RECORD_ARRAY, RECORD_BLANK, RECORD_BOF, RECORD_BOOLERR, RECORD_BOUNDSHEET8, RECORD_COLINFO, RECORD_CONTINUE, RECORD_DATE1904, RECORD_DEFAULTROWHEIGHT, RECORD_DEFCOLWIDTH, RECORD_DIMENSIONS, RECORD_EOF, RECORD_FILEPASS, RECORD_FONT, RECORD_FORMAT, RECORD_FORMULA, RECORD_LABEL, RECORD_LABELSST, RECORD_MERGECELLS, RECORD_MULBLANK, RECORD_MULRK, RECORD_NUMBER, RECORD_RK, RECORD_ROW, RECORD_SHRFMLA, RECORD_SST, RECORD_STRING, RECORD_TABLE, RECORD_XF };

package/dist/biff/record-types.js

@@ -0,0 +1,73 @@
+//#region src/biff/record-types.ts
+/** Marks the beginning of a substream and names its document type ([MS-XLS] 2.4.21). */
+const RECORD_BOF = 2057;
+/** Marks the end of a substream ([MS-XLS] 2.4.103). */
+const RECORD_EOF = 10;
+/** Carries the overflow of a preceding record whose data exceeds what one record can hold ([MS-XLS] 2.4.58). */
+const RECORD_CONTINUE = 60;
+/** One per sheet: its name, hidden state, type, and the stream offset of its own BOF ([MS-XLS] 2.4.28). */
+const RECORD_BOUNDSHEET8 = 133;
+/** The shared string table every LabelSst cell indexes into ([MS-XLS] 2.4.265). */
+const RECORD_SST = 252;
+/** A custom number-format code and the identifier cells reference it by ([MS-XLS] 2.4.126). */
+const RECORD_FORMAT = 1054;
+/** A cell or cell-style extended format record ([MS-XLS] 2.4.353). */
+const RECORD_XF = 224;
+/** A font definition, referenced by index from an XF ([MS-XLS] 2.4.122). */
+const RECORD_FONT = 49;
+/** Which of the two date epochs this workbook's serials count from ([MS-XLS] 2.4.77). */
+const RECORD_DATE1904 = 34;
+/** Present only in an encrypted workbook, where every record after it is ciphertext ([MS-XLS] 2.4.117). */
+const RECORD_FILEPASS = 47;
+/** The sheet's used range ([MS-XLS] 2.4.90). */
+const RECORD_DIMENSIONS = 512;
+/** A single row's height, hidden state, and formatting ([MS-XLS] 2.4.221). */
+const RECORD_ROW = 520;
+/** Column width, hidden state, and default format for a range of columns ([MS-XLS] 2.4.53). */
+const RECORD_COLINFO = 125;
+/** The sheet's default column width, in whole character widths ([MS-XLS] 2.4.89). */
+const RECORD_DEFCOLWIDTH = 85;
+/** The sheet's default row height ([MS-XLS] 2.4.87). */
+const RECORD_DEFAULTROWHEIGHT = 549;
+/** Merged cell ranges ([MS-XLS] 2.4.168). */
+const RECORD_MERGECELLS = 229;
+/** An empty cell carrying only formatting ([MS-XLS] 2.4.20). */
+const RECORD_BLANK = 513;
+/** A run of empty cells in one row ([MS-XLS] 2.4.174). */
+const RECORD_MULBLANK = 190;
+/** A cell holding an RK-encoded number ([MS-XLS] 2.4.220). */
+const RECORD_RK = 638;
+/** A run of RK-encoded numeric cells in one row ([MS-XLS] 2.4.175). */
+const RECORD_MULRK = 189;
+/** A cell holding an IEEE 754 double ([MS-XLS] 2.4.180). */
+const RECORD_NUMBER = 515;
+/** A cell holding a boolean or an error value ([MS-XLS] 2.4.24). */
+const RECORD_BOOLERR = 517;
+/** A cell holding a string by index into the shared string table ([MS-XLS] 2.4.149). */
+const RECORD_LABELSST = 253;
+/** A cell holding an inline string ([MS-XLS] 2.4.148). See the reader's own note on why BIFF8 still meets this in the wild. */
+const RECORD_LABEL = 516;
+/** A cell holding a formula, its cached result, and its parsed expression ([MS-XLS] 2.4.127). */
+const RECORD_FORMULA = 6;
+/** The string result of the Formula record preceding it ([MS-XLS] 2.4.268). */
+const RECORD_STRING = 519;
+/** The expression of an array formula, following the Formula record of its top-left cell ([MS-XLS] 2.4.4). */
+const RECORD_ARRAY = 545;
+/** A data-table definition following a Formula record ([MS-XLS] 2.4.334). */
+const RECORD_TABLE = 566;
+/** The shared expression a run of Formula records refers to ([MS-XLS] 2.4.260). */
+const RECORD_SHRFMLA = 1212;
+/** The workbook globals substream. */
+const BOF_TYPE_WORKBOOK = 5;
+/** A worksheet or dialog sheet substream. */
+const BOF_TYPE_WORKSHEET = 16;
+/** A chart sheet substream. */
+const BOF_TYPE_CHART = 32;
+/** A macro sheet substream. */
+const BOF_TYPE_MACRO = 64;
+/** The BIFF version every BOF in a BIFF8 workbook stream declares ([MS-XLS] 2.4.21: "The value MUST be 0x0600"). */
+const BIFF8_VERSION = 1536;
+/** [MS-XLS] 2.1.4: "The record size ... MUST be less than or equal to 8224." The ceiling a writer splits a record at, and the bound a reader can sanity-check a declared size against. */
+const MAX_RECORD_DATA_SIZE = 8224;
+//#endregion
+export { BIFF8_VERSION, BOF_TYPE_CHART, BOF_TYPE_MACRO, BOF_TYPE_WORKBOOK, BOF_TYPE_WORKSHEET, MAX_RECORD_DATA_SIZE, RECORD_ARRAY, RECORD_BLANK, RECORD_BOF, RECORD_BOOLERR, RECORD_BOUNDSHEET8, RECORD_COLINFO, RECORD_CONTINUE, RECORD_DATE1904, RECORD_DEFAULTROWHEIGHT, RECORD_DEFCOLWIDTH, RECORD_DIMENSIONS, RECORD_EOF, RECORD_FILEPASS, RECORD_FONT, RECORD_FORMAT, RECORD_FORMULA, RECORD_LABEL, RECORD_LABELSST, RECORD_MERGECELLS, RECORD_MULBLANK, RECORD_MULRK, RECORD_NUMBER, RECORD_RK, RECORD_ROW, RECORD_SHRFMLA, RECORD_SST, RECORD_STRING, RECORD_TABLE, RECORD_XF };

package/dist/biff/records.cjs

@@ -0,0 +1,40 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_record_types = require("./record-types.cjs");
+//#region src/biff/records.ts
+/** Thrown when a byte sequence cannot be read as the structure [MS-XLS] specifies, at any level from the record framing up to a record's own fields. */
+var BiffFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BiffFormatError";
+	}
+};
+/** The four-byte record header: a two-byte type followed by a two-byte size. */
+const HEADER_SIZE = 4;
+/**
+* Splits a BIFF record stream into its records, in stream order.
+*
+* Every failure is thrown rather than tolerated, because there is no safe way to resume: a record's size field is the only thing that says where the next record begins, so a stream that stops making sense at one record makes no sense from there on, and returning the records read so far would be reporting a truncated workbook as a complete one.
+*/
+function readRecords(stream) {
+	const view = new DataView(stream.buffer, stream.byteOffset, stream.byteLength);
+	const records = [];
+	let offset = 0;
+	while (offset < stream.length) {
+		if (offset + HEADER_SIZE > stream.length) throw new BiffFormatError(`record header at offset ${offset} runs past the end of the ${stream.length}-byte stream`);
+		const type = view.getUint16(offset, true);
+		const size = view.getUint16(offset + 2, true);
+		if (size > 8224) throw new BiffFormatError(`record 0x${type.toString(16)} at offset ${offset} declares ${size} bytes of data, above the ${require_biff_record_types.MAX_RECORD_DATA_SIZE}-byte maximum`);
+		const dataStart = offset + HEADER_SIZE;
+		if (dataStart + size > stream.length) throw new BiffFormatError(`record 0x${type.toString(16)} at offset ${offset} declares ${size} bytes of data, running past the end of the ${stream.length}-byte stream`);
+		records.push({
+			type,
+			data: stream.slice(dataStart, dataStart + size),
+			offset
+		});
+		offset = dataStart + size;
+	}
+	return records;
+}
+//#endregion
+exports.BiffFormatError = BiffFormatError;
+exports.readRecords = readRecords;

package/dist/biff/records.d.cts

@@ -0,0 +1,2 @@
+import { n as BiffRecord, r as readRecords, t as BiffFormatError } from "../records-DVIqXFKk.cjs";
+export { BiffFormatError, BiffRecord, readRecords };

package/dist/biff/records.d.ts

@@ -0,0 +1,2 @@
+import { n as BiffRecord, r as readRecords, t as BiffFormatError } from "../records-DVIqXFKk.js";
+export { BiffFormatError, BiffRecord, readRecords };

package/dist/biff/records.js

@@ -0,0 +1,38 @@
+import { MAX_RECORD_DATA_SIZE } from "./record-types.js";
+//#region src/biff/records.ts
+/** Thrown when a byte sequence cannot be read as the structure [MS-XLS] specifies, at any level from the record framing up to a record's own fields. */
+var BiffFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "BiffFormatError";
+	}
+};
+/** The four-byte record header: a two-byte type followed by a two-byte size. */
+const HEADER_SIZE = 4;
+/**
+* Splits a BIFF record stream into its records, in stream order.
+*
+* Every failure is thrown rather than tolerated, because there is no safe way to resume: a record's size field is the only thing that says where the next record begins, so a stream that stops making sense at one record makes no sense from there on, and returning the records read so far would be reporting a truncated workbook as a complete one.
+*/
+function readRecords(stream) {
+	const view = new DataView(stream.buffer, stream.byteOffset, stream.byteLength);
+	const records = [];
+	let offset = 0;
+	while (offset < stream.length) {
+		if (offset + HEADER_SIZE > stream.length) throw new BiffFormatError(`record header at offset ${offset} runs past the end of the ${stream.length}-byte stream`);
+		const type = view.getUint16(offset, true);
+		const size = view.getUint16(offset + 2, true);
+		if (size > 8224) throw new BiffFormatError(`record 0x${type.toString(16)} at offset ${offset} declares ${size} bytes of data, above the ${MAX_RECORD_DATA_SIZE}-byte maximum`);
+		const dataStart = offset + HEADER_SIZE;
+		if (dataStart + size > stream.length) throw new BiffFormatError(`record 0x${type.toString(16)} at offset ${offset} declares ${size} bytes of data, running past the end of the ${stream.length}-byte stream`);
+		records.push({
+			type,
+			data: stream.slice(dataStart, dataStart + size),
+			offset
+		});
+		offset = dataStart + size;
+	}
+	return records;
+}
+//#endregion
+export { BiffFormatError, readRecords };

package/dist/biff/rk.cjs

@@ -0,0 +1,29 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/biff/rk.ts
+const FLAG_X100 = 1;
+const FLAG_INT = 2;
+/** The payload is a signed 30-bit integer; 2^29 is its sign bit and 2^30 the modulus to subtract. */
+const INT_SIGN_BIT = 536870912;
+const INT_MODULUS = 1073741824;
+/** [MS-XLS] 2.5.217's own fX100 divisor. */
+const X100_DIVISOR = 100;
+/** Decodes the 32-bit word of an RkNumber ([MS-XLS] 2.5.217) into the number it stands for. */
+function decodeRkNumber(word) {
+	const bits = word >>> 0;
+	const value = (bits & FLAG_INT) !== 0 ? decodeSignedPayload(bits) : decodeTruncatedDouble(bits);
+	return (bits & FLAG_X100) !== 0 ? value / X100_DIVISOR : value;
+}
+/** The payload read as a signed 30-bit integer: shifted down unsigned, then folded into its negative range from bit 29 rather than sign-extended from bit 31. */
+function decodeSignedPayload(bits) {
+	const payload = (bits & -4) >>> 2;
+	return (payload & INT_SIGN_BIT) !== 0 ? payload - INT_MODULUS : payload;
+}
+/** The payload read as the high 32 bits of a double whose low 32 bits are zero, with the two flag bits (the double's own bits 32 and 33, which the spec requires be zero) cleared first. */
+function decodeTruncatedDouble(bits) {
+	const view = /* @__PURE__ */ new DataView(/* @__PURE__ */ new ArrayBuffer(8));
+	view.setUint32(0, (bits & -4) >>> 0, false);
+	view.setUint32(4, 0, false);
+	return view.getFloat64(0, false);
+}
+//#endregion
+exports.decodeRkNumber = decodeRkNumber;

package/dist/biff/rk.d.cts

@@ -0,0 +1,5 @@
+//#region src/biff/rk.d.ts
+/** Decodes the 32-bit word of an RkNumber ([MS-XLS] 2.5.217) into the number it stands for. */
+declare function decodeRkNumber(word: number): number;
+//#endregion
+export { decodeRkNumber };

package/dist/biff/rk.d.ts

@@ -0,0 +1,5 @@
+//#region src/biff/rk.d.ts
+/** Decodes the 32-bit word of an RkNumber ([MS-XLS] 2.5.217) into the number it stands for. */
+declare function decodeRkNumber(word: number): number;
+//#endregion
+export { decodeRkNumber };

package/dist/biff/rk.js

@@ -0,0 +1,28 @@
+//#region src/biff/rk.ts
+const FLAG_X100 = 1;
+const FLAG_INT = 2;
+/** The payload is a signed 30-bit integer; 2^29 is its sign bit and 2^30 the modulus to subtract. */
+const INT_SIGN_BIT = 536870912;
+const INT_MODULUS = 1073741824;
+/** [MS-XLS] 2.5.217's own fX100 divisor. */
+const X100_DIVISOR = 100;
+/** Decodes the 32-bit word of an RkNumber ([MS-XLS] 2.5.217) into the number it stands for. */
+function decodeRkNumber(word) {
+	const bits = word >>> 0;
+	const value = (bits & FLAG_INT) !== 0 ? decodeSignedPayload(bits) : decodeTruncatedDouble(bits);
+	return (bits & FLAG_X100) !== 0 ? value / X100_DIVISOR : value;
+}
+/** The payload read as a signed 30-bit integer: shifted down unsigned, then folded into its negative range from bit 29 rather than sign-extended from bit 31. */
+function decodeSignedPayload(bits) {
+	const payload = (bits & -4) >>> 2;
+	return (payload & INT_SIGN_BIT) !== 0 ? payload - INT_MODULUS : payload;
+}
+/** The payload read as the high 32 bits of a double whose low 32 bits are zero, with the two flag bits (the double's own bits 32 and 33, which the spec requires be zero) cleared first. */
+function decodeTruncatedDouble(bits) {
+	const view = /* @__PURE__ */ new DataView(/* @__PURE__ */ new ArrayBuffer(8));
+	view.setUint32(0, (bits & -4) >>> 0, false);
+	view.setUint32(4, 0, false);
+	return view.getFloat64(0, false);
+}
+//#endregion
+export { decodeRkNumber };

package/dist/biff/strings.cjs

@@ -0,0 +1,66 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/biff/strings.ts
+/** Bit 0 of a string's flags byte: set when each character occupies a full two-byte UTF-16 code unit. */
+const FLAG_HIGH_BYTE = 1;
+/** Bit 2 of an XLUnicodeRichExtendedString's flags byte: set when phonetic (ExtRst) data trails the characters. */
+const FLAG_EXT_ST = 4;
+/** Bit 3 of an XLUnicodeRichExtendedString's flags byte: set when formatting runs (rgRun) trail the characters. */
+const FLAG_RICH_ST = 8;
+/** [MS-XLS] 2.5.132: a FormatRun is four bytes (a character index and a font index). */
+const FORMAT_RUN_SIZE = 4;
+/**
+* Reads `count` characters, consuming the re-stated flag byte at every continuation boundary the run crosses.
+*
+* `startBlock` is the block the string's own header was read in, captured by the caller before reading cch. Comparing against that rather than against the cursor's position at entry is what makes the boundary-at-the-first-character case work: a string whose fixed fields fill their record exactly, leaving every character to the Continue, still opens that Continue with a flag byte, and a position captured after the header was read would already have settled onto the Continue and missed it.
+*
+* The boundary byte is consumed only when characters genuinely remain, so a string whose last character lands on the final byte of a block leaves the next block's first byte alone -- that byte belongs to whatever the record holds next, which for the SST is the following string's own cch.
+*/
+function readCharacters(cursor, count, initialHighByte, startBlock) {
+	let highByte = initialHighByte;
+	let block = startBlock;
+	const units = [];
+	for (let index = 0; index < count; index += 1) {
+		const currentBlock = cursor.blockPosition();
+		if (currentBlock !== block) {
+			highByte = (cursor.u8() & FLAG_HIGH_BYTE) !== 0;
+			block = currentBlock;
+		}
+		units.push(highByte ? cursor.u16() : cursor.u8());
+	}
+	const CHUNK = 4096;
+	let text = "";
+	for (let start = 0; start < units.length; start += CHUNK) text += String.fromCharCode(...units.slice(start, start + CHUNK));
+	return text;
+}
+/** 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. */
+function readXLUnicodeString(cursor) {
+	const startBlock = cursor.blockPosition();
+	return readCharacters(cursor, cursor.u16(), (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();
+	return readCharacters(cursor, cursor.u8(), (cursor.u8() & FLAG_HIGH_BYTE) !== 0, startBlock);
+}
+/**
+* An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+*
+* Only the text is returned. A rich string's per-run font changes and an extended string's phonetic guide data are read past rather than modelled: `ContentSheetCell.runs` could carry the former, but resolving a FormatRun's font index into real run formatting needs the globals substream's Font table threaded down here, and the phonetic data has no representation in the shared schema at all. Both payloads must still be CONSUMED exactly, because the SST is a packed array -- leaving a single byte of either behind would desynchronise every string after it.
+*/
+function readRichExtendedString(cursor) {
+	const startBlock = cursor.blockPosition();
+	const cch = cursor.u16();
+	const flags = cursor.u8();
+	const rich = (flags & FLAG_RICH_ST) !== 0;
+	const extended = (flags & FLAG_EXT_ST) !== 0;
+	const runCount = rich ? cursor.u16() : 0;
+	const extendedSize = extended ? cursor.i32() : 0;
+	const text = readCharacters(cursor, cch, (flags & FLAG_HIGH_BYTE) !== 0, startBlock);
+	if (runCount > 0) cursor.skip(runCount * FORMAT_RUN_SIZE);
+	if (extendedSize > 0) cursor.skip(extendedSize);
+	return text;
+}
+//#endregion
+exports.readRichExtendedString = readRichExtendedString;
+exports.readShortXLUnicodeString = readShortXLUnicodeString;
+exports.readXLUnicodeString = readXLUnicodeString;

package/dist/biff/strings.d.cts

@@ -0,0 +1,14 @@
+import { BlockCursor } from "./cursor.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;
+/** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
+declare function readShortXLUnicodeString(cursor: BlockCursor): string;
+/**
+ * An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+ *
+ * Only the text is returned. A rich string's per-run font changes and an extended string's phonetic guide data are read past rather than modelled: `ContentSheetCell.runs` could carry the former, but resolving a FormatRun's font index into real run formatting needs the globals substream's Font table threaded down here, and the phonetic data has no representation in the shared schema at all. Both payloads must still be CONSUMED exactly, because the SST is a packed array -- leaving a single byte of either behind would desynchronise every string after it.
+ */
+declare function readRichExtendedString(cursor: BlockCursor): string;
+//#endregion
+export { readRichExtendedString, readShortXLUnicodeString, readXLUnicodeString };

package/dist/biff/strings.d.ts

@@ -0,0 +1,14 @@
+import { BlockCursor } from "./cursor.js";
+//#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;
+/** A ShortXLUnicodeString ([MS-XLS] 2.5.240): as above, with a one-byte character count. */
+declare function readShortXLUnicodeString(cursor: BlockCursor): string;
+/**
+ * An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+ *
+ * Only the text is returned. A rich string's per-run font changes and an extended string's phonetic guide data are read past rather than modelled: `ContentSheetCell.runs` could carry the former, but resolving a FormatRun's font index into real run formatting needs the globals substream's Font table threaded down here, and the phonetic data has no representation in the shared schema at all. Both payloads must still be CONSUMED exactly, because the SST is a packed array -- leaving a single byte of either behind would desynchronise every string after it.
+ */
+declare function readRichExtendedString(cursor: BlockCursor): string;
+//#endregion
+export { readRichExtendedString, readShortXLUnicodeString, readXLUnicodeString };

package/dist/biff/strings.js

@@ -0,0 +1,63 @@
+//#region src/biff/strings.ts
+/** Bit 0 of a string's flags byte: set when each character occupies a full two-byte UTF-16 code unit. */
+const FLAG_HIGH_BYTE = 1;
+/** Bit 2 of an XLUnicodeRichExtendedString's flags byte: set when phonetic (ExtRst) data trails the characters. */
+const FLAG_EXT_ST = 4;
+/** Bit 3 of an XLUnicodeRichExtendedString's flags byte: set when formatting runs (rgRun) trail the characters. */
+const FLAG_RICH_ST = 8;
+/** [MS-XLS] 2.5.132: a FormatRun is four bytes (a character index and a font index). */
+const FORMAT_RUN_SIZE = 4;
+/**
+* Reads `count` characters, consuming the re-stated flag byte at every continuation boundary the run crosses.
+*
+* `startBlock` is the block the string's own header was read in, captured by the caller before reading cch. Comparing against that rather than against the cursor's position at entry is what makes the boundary-at-the-first-character case work: a string whose fixed fields fill their record exactly, leaving every character to the Continue, still opens that Continue with a flag byte, and a position captured after the header was read would already have settled onto the Continue and missed it.
+*
+* The boundary byte is consumed only when characters genuinely remain, so a string whose last character lands on the final byte of a block leaves the next block's first byte alone -- that byte belongs to whatever the record holds next, which for the SST is the following string's own cch.
+*/
+function readCharacters(cursor, count, initialHighByte, startBlock) {
+	let highByte = initialHighByte;
+	let block = startBlock;
+	const units = [];
+	for (let index = 0; index < count; index += 1) {
+		const currentBlock = cursor.blockPosition();
+		if (currentBlock !== block) {
+			highByte = (cursor.u8() & FLAG_HIGH_BYTE) !== 0;
+			block = currentBlock;
+		}
+		units.push(highByte ? cursor.u16() : cursor.u8());
+	}
+	const CHUNK = 4096;
+	let text = "";
+	for (let start = 0; start < units.length; start += CHUNK) text += String.fromCharCode(...units.slice(start, start + CHUNK));
+	return text;
+}
+/** 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. */
+function readXLUnicodeString(cursor) {
+	const startBlock = cursor.blockPosition();
+	return readCharacters(cursor, cursor.u16(), (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();
+	return readCharacters(cursor, cursor.u8(), (cursor.u8() & FLAG_HIGH_BYTE) !== 0, startBlock);
+}
+/**
+* An XLUnicodeRichExtendedString ([MS-XLS] 2.5.293): the SST's own element shape.
+*
+* Only the text is returned. A rich string's per-run font changes and an extended string's phonetic guide data are read past rather than modelled: `ContentSheetCell.runs` could carry the former, but resolving a FormatRun's font index into real run formatting needs the globals substream's Font table threaded down here, and the phonetic data has no representation in the shared schema at all. Both payloads must still be CONSUMED exactly, because the SST is a packed array -- leaving a single byte of either behind would desynchronise every string after it.
+*/
+function readRichExtendedString(cursor) {
+	const startBlock = cursor.blockPosition();
+	const cch = cursor.u16();
+	const flags = cursor.u8();
+	const rich = (flags & FLAG_RICH_ST) !== 0;
+	const extended = (flags & FLAG_EXT_ST) !== 0;
+	const runCount = rich ? cursor.u16() : 0;
+	const extendedSize = extended ? cursor.i32() : 0;
+	const text = readCharacters(cursor, cch, (flags & FLAG_HIGH_BYTE) !== 0, startBlock);
+	if (runCount > 0) cursor.skip(runCount * FORMAT_RUN_SIZE);
+	if (extendedSize > 0) cursor.skip(extendedSize);
+	return text;
+}
+//#endregion
+export { readRichExtendedString, readShortXLUnicodeString, readXLUnicodeString };

package/dist/biff/substreams.cjs

@@ -0,0 +1,71 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("./record-types.cjs");
+const require_biff_records = require("./records.cjs");
+//#region src/biff/substreams.ts
+/** Joins each record to the Continue records following it, keeping the blocks separate. */
+function groupRecords(records) {
+	const groups = [];
+	for (const record of records) {
+		if (record.type === 60) {
+			const current = groups[groups.length - 1];
+			if (current === void 0) throw new require_biff_records.BiffFormatError("Continue record with no preceding record to continue");
+			current.blocks.push(record.data);
+			continue;
+		}
+		groups.push({
+			type: record.type,
+			blocks: [record.data],
+			offset: record.offset
+		});
+	}
+	return groups;
+}
+/** The BOF record's own fixed prefix: a two-byte vers followed by a two-byte dt. */
+const BOF_PREFIX_SIZE = 4;
+/** Splits a grouped record sequence into its substreams, verifying each BOF declares BIFF8. */
+function splitSubstreams(groups) {
+	const substreams = [];
+	let current;
+	for (const group of groups) {
+		if (group.type === 2057) {
+			if (current !== void 0) substreams.push({
+				...current,
+				index: substreams.length
+			});
+			current = {
+				documentType: readBofDocumentType(group),
+				records: [],
+				offset: group.offset
+			};
+			continue;
+		}
+		if (group.type === 10) {
+			if (current !== void 0) {
+				substreams.push({
+					...current,
+					index: substreams.length
+				});
+				current = void 0;
+			}
+			continue;
+		}
+		current?.records.push(group);
+	}
+	if (current !== void 0) substreams.push({
+		...current,
+		index: substreams.length
+	});
+	return substreams;
+}
+/** Reads a BOF's vers and dt ([MS-XLS] 2.4.21), rejecting anything that is not BIFF8. */
+function readBofDocumentType(group) {
+	const data = group.blocks[0];
+	if (data === void 0 || data.length < BOF_PREFIX_SIZE) throw new require_biff_records.BiffFormatError(`BOF record carries ${data?.length ?? 0} bytes, too few for its own version and document type`);
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	const version = view.getUint16(0, true);
+	if (version !== 1536) throw new require_biff_records.BiffFormatError(`BOF declares BIFF version 0x${version.toString(16).padStart(4, "0")}; this reader implements BIFF8 (0x0600) only`);
+	return view.getUint16(2, true);
+}
+//#endregion
+exports.groupRecords = groupRecords;
+exports.splitSubstreams = splitSubstreams;

package/dist/biff/substreams.d.cts

@@ -0,0 +1,21 @@
+import { n as BiffRecord } from "../records-DVIqXFKk.cjs";
+//#region src/biff/substreams.d.ts
+/** One logical record: its type, its data blocks -- the base record's, then one per Continue that followed it -- and the base record's own offset in the stream. */
+interface RecordGroup {
+  readonly type: number;
+  readonly blocks: readonly Uint8Array<ArrayBuffer>[];
+  readonly offset: number;
+}
+/** One substream: the document type its BOF declared, the records between that BOF and its EOF, its ordinal position among the stream's substreams, and the stream offset of its own BOF -- which is what a BoundSheet8's lbPlyPos names. */
+interface Substream {
+  readonly documentType: number;
+  readonly records: readonly RecordGroup[];
+  readonly index: number;
+  readonly offset: number;
+}
+/** Joins each record to the Continue records following it, keeping the blocks separate. */
+declare function groupRecords(records: readonly BiffRecord[]): readonly RecordGroup[];
+/** Splits a grouped record sequence into its substreams, verifying each BOF declares BIFF8. */
+declare function splitSubstreams(groups: readonly RecordGroup[]): readonly Substream[];
+//#endregion
+export { RecordGroup, Substream, groupRecords, splitSubstreams };

package/dist/biff/substreams.d.ts

@@ -0,0 +1,21 @@
+import { n as BiffRecord } from "../records-DVIqXFKk.js";
+//#region src/biff/substreams.d.ts
+/** One logical record: its type, its data blocks -- the base record's, then one per Continue that followed it -- and the base record's own offset in the stream. */
+interface RecordGroup {
+  readonly type: number;
+  readonly blocks: readonly Uint8Array<ArrayBuffer>[];
+  readonly offset: number;
+}
+/** One substream: the document type its BOF declared, the records between that BOF and its EOF, its ordinal position among the stream's substreams, and the stream offset of its own BOF -- which is what a BoundSheet8's lbPlyPos names. */
+interface Substream {
+  readonly documentType: number;
+  readonly records: readonly RecordGroup[];
+  readonly index: number;
+  readonly offset: number;
+}
+/** Joins each record to the Continue records following it, keeping the blocks separate. */
+declare function groupRecords(records: readonly BiffRecord[]): readonly RecordGroup[];
+/** Splits a grouped record sequence into its substreams, verifying each BOF declares BIFF8. */
+declare function splitSubstreams(groups: readonly RecordGroup[]): readonly Substream[];
+//#endregion
+export { RecordGroup, Substream, groupRecords, splitSubstreams };