xls-codec 1.0.2 → 2.0.0

package/dist/container.d.cts

@@ -1,10 +1,17 @@
 //#region src/container.d.ts
+/** The [MS-OLEPS] Property Set Stream a .xls's title/author/dates live in when present ([MS-OSHARED] 2.3.3.2.2) -- a genuinely optional stream, unlike Workbook, since a valid BIFF8 workbook need not carry document properties at all. */
+declare const SUMMARY_INFORMATION_STREAM = "SummaryInformation";
+interface WorkbookStreams {
+  readonly workbook: Uint8Array<ArrayBuffer>;
+  /** The raw "\x05SummaryInformation" stream bytes, or undefined when the container carries none. */
+  readonly metadata: Uint8Array<ArrayBuffer> | undefined;
+}
 /**
- * Extracts the BIFF8 record stream from a .xls file's compound-file container.
+ * Extracts the BIFF8 record stream, and the optional metadata stream beside it, from a .xls file's compound-file container.
  *
  * Throws rather than returning undefined for anything that is not a readable BIFF8 workbook: a caller wanting a soft answer asks isXlsFile first.
  */
-declare function readWorkbookStream(bytes: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+declare function readWorkbookStreams(bytes: Uint8Array<ArrayBuffer>): WorkbookStreams;
 /**
  * Whether these bytes are a workbook this package can read.
  *
@@ -12,4 +19,4 @@ declare function readWorkbookStream(bytes: Uint8Array<ArrayBuffer>): Uint8Array<
  */
 declare function isXlsFile(bytes: Uint8Array<ArrayBuffer>): boolean;
 //#endregion
-export { isXlsFile, readWorkbookStream };
+export { SUMMARY_INFORMATION_STREAM, WorkbookStreams, isXlsFile, readWorkbookStreams };

package/dist/container.d.ts

@@ -1,10 +1,17 @@
 //#region src/container.d.ts
+/** The [MS-OLEPS] Property Set Stream a .xls's title/author/dates live in when present ([MS-OSHARED] 2.3.3.2.2) -- a genuinely optional stream, unlike Workbook, since a valid BIFF8 workbook need not carry document properties at all. */
+declare const SUMMARY_INFORMATION_STREAM = "SummaryInformation";
+interface WorkbookStreams {
+  readonly workbook: Uint8Array<ArrayBuffer>;
+  /** The raw "\x05SummaryInformation" stream bytes, or undefined when the container carries none. */
+  readonly metadata: Uint8Array<ArrayBuffer> | undefined;
+}
 /**
- * Extracts the BIFF8 record stream from a .xls file's compound-file container.
+ * Extracts the BIFF8 record stream, and the optional metadata stream beside it, from a .xls file's compound-file container.
  *
  * Throws rather than returning undefined for anything that is not a readable BIFF8 workbook: a caller wanting a soft answer asks isXlsFile first.
  */
-declare function readWorkbookStream(bytes: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+declare function readWorkbookStreams(bytes: Uint8Array<ArrayBuffer>): WorkbookStreams;
 /**
  * Whether these bytes are a workbook this package can read.
  *
@@ -12,4 +19,4 @@ declare function readWorkbookStream(bytes: Uint8Array<ArrayBuffer>): Uint8Array<
  */
 declare function isXlsFile(bytes: Uint8Array<ArrayBuffer>): boolean;
 //#endregion
-export { isXlsFile, readWorkbookStream };
+export { SUMMARY_INFORMATION_STREAM, WorkbookStreams, isXlsFile, readWorkbookStreams };

package/dist/container.js

@@ -5,16 +5,24 @@ import { CompoundFileFormatError, isCompoundFile, readCompoundFile } from "archi
 const WORKBOOK_STREAM = "Workbook";
 /** BIFF5 and BIFF7 workbooks name their stream "Book" instead. Recognised only to say so in an error, never read: those are different formats record-for-record, not older spellings of this one. */
 const LEGACY_WORKBOOK_STREAM = "Book";
+/** The [MS-OLEPS] Property Set Stream a .xls's title/author/dates live in when present ([MS-OSHARED] 2.3.3.2.2) -- a genuinely optional stream, unlike Workbook, since a valid BIFF8 workbook need not carry document properties at all. */
+const SUMMARY_INFORMATION_STREAM = "SummaryInformation";
 /**
-* Extracts the BIFF8 record stream from a .xls file's compound-file container.
+* Extracts the BIFF8 record stream, and the optional metadata stream beside it, from a .xls file's compound-file container.
 *
 * Throws rather than returning undefined for anything that is not a readable BIFF8 workbook: a caller wanting a soft answer asks isXlsFile first.
 */
-function readWorkbookStream(bytes) {
+function readWorkbookStreams(bytes) {
 	if (!isCompoundFile(bytes)) throw new BiffFormatError("not a compound file: a .xls workbook is a [MS-CFB] container holding a 'Workbook' stream");
 	const streams = readWorkbookContainer(bytes);
 	const workbook = streams.find((stream) => stream.path === WORKBOOK_STREAM);
-	if (workbook !== void 0) return workbook.bytes;
+	if (workbook !== void 0) {
+		const metadata = streams.find((stream) => stream.path === SUMMARY_INFORMATION_STREAM);
+		return {
+			workbook: workbook.bytes,
+			metadata: metadata?.bytes
+		};
+	}
 	if (streams.some((stream) => stream.path === LEGACY_WORKBOOK_STREAM)) throw new BiffFormatError("compound file holds a 'Book' stream rather than a 'Workbook' stream, so it is a BIFF5/BIFF7 workbook; this reader implements BIFF8 only");
 	throw new BiffFormatError("compound file holds no 'Workbook' stream, so it is not a .xls workbook");
 }
@@ -41,4 +49,4 @@ function isXlsFile(bytes) {
 	}
 }
 //#endregion
-export { isXlsFile, readWorkbookStream };
+export { SUMMARY_INFORMATION_STREAM, isXlsFile, readWorkbookStreams };

package/dist/content.cjs

@@ -2,48 +2,99 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("./biff/record-types.cjs");
 const require_biff_records = require("./biff/records.cjs");
 const require_container = require("./container.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_number_format = require("./number-format.cjs");
+const require_biff_xf_colors = require("./biff/xf-colors.cjs");
 const require_serial = require("./serial.cjs");
 const require_workbook_globals = require("./workbook/globals.cjs");
 const require_workbook_sheet = require("./workbook/sheet.cjs");
+let archive_codec = require("archive-codec");
 let document_schema_js = require("document-schema.js");
+let excel_number_format = require("excel-number-format");
 //#region src/content.ts
 /** Which BoundSheet8 dt values name a sheet this reader maps. 0x00 is a worksheet or dialog sheet; macro sheets, chart sheets, and VBA modules carry no cell table for ContentSheet to hold. */
 const SHEET_TYPE_WORKSHEET = 0;
 /**
-* Print settings this package emits rather than reads.
+* Excel's own "Normal" page-setup preset, the per-field fallback for a print setting the file states nothing about.
 *
-* ContentSheetPrintSettings makes pageSize, margins, gridlines, headers, and pageOrder REQUIRED, so a sheet cannot be produced without them, and BIFF8 spreads the real values across the Setup, LeftMargin/RightMargin/TopMargin/BottomMargin, PrintGrid, and PrintRowCol records plus a paper-size code table. None of those is read yet, so these are Excel's own documented "Normal" preset -- the same constants ooxml.js falls back to for an xlsx carrying no pageMargins element -- and they are honest defaults rather than the file's own settings. Reading the real ones is tracked as remaining scope rather than guessed at from unverified field offsets.
+* ContentSheetPrintSettings makes pageSize, margins, gridlines, headers, and pageOrder REQUIRED, while [MS-XLS] 2.1.7.20.6's own PAGESETUP production makes every record behind them optional -- so a sheet whose page setup was never touched genuinely carries no Setup and no margin records, and something has to stand in. These are the values Excel itself calls Normal (top/bottom 0.75in, left/right 0.7in, on Letter paper, gridlines and row/column headers not printed, pages down-then-over), and the identical constants ooxml.js falls back to for an xlsx carrying no pageMargins element -- so the same untouched sheet reads the same either way.
+*
+* Each field falls back independently: a sheet that declares a left margin and nothing else keeps its real left margin and takes the preset for the other three, rather than the whole preset displacing the one value the file actually stated.
 */
-const POINTS_PER_INCH = 72;
 const DEFAULT_PRINT_SETTINGS = {
 	pageSize: document_schema_js.PAGE_SIZE_LETTER,
 	margins: {
-		topPt: .75 * POINTS_PER_INCH,
-		rightPt: .7 * POINTS_PER_INCH,
-		bottomPt: .75 * POINTS_PER_INCH,
-		leftPt: .7 * POINTS_PER_INCH
+		topPt: require_units.inchesToPoints(.75),
+		rightPt: require_units.inchesToPoints(.7),
+		bottomPt: require_units.inchesToPoints(.75),
+		leftPt: require_units.inchesToPoints(.7)
 	},
 	gridlines: false,
 	headers: false,
 	pageOrder: "downThenOver"
 };
 /**
+* The iScale value that says "print at actual size", which is what ContentSheetPrintSettings already means by carrying no scalePercent at all.
+*
+* Setup's own iScale is a mandatory field of a mandatory record, with no spelling for "this sheet declares no scale" -- so an untouched sheet still states 100. Reporting that as an explicit scalePercent would put a field on every sheet of every workbook read, carrying nothing a consumer could act on that its absence does not already say, and would mean a document written with no scale came back with one. The two spellings render identically, so collapsing them onto the absent one is lossless in both directions; a scale that is genuinely anything else is reported exactly as the file states it.
+*/
+const ACTUAL_SIZE_SCALE_PERCENT = 100;
+/**
+* The print settings a sheet's own records and its built-in print names state, with the Normal preset filling in what they do not.
+*
+* Two of BIFF8's own conditional rules are honoured rather than flattened. A Setup record whose fNoPls bit is set declares its own paper size and scale undefined ([MS-XLS] 2.4.257: "whether the iPaperSize, iScale, iRes, iVRes, iCopies, fNoOrient, and fPortrait data are undefined and ignored"), so neither is read from it -- the page size falls back to the preset and no scalePercent is reported, rather than a paper code the file itself disowns being resolved into a confident page size. And WsBool's own fFitToPage decides which of Setup's two mutually exclusive scaling fields is live: iFitWidth/iFitHeight when set, iScale when clear. Real producers write both regardless (confirmed against LibreOffice-written BIFF8, which carries iScale=100 alongside a real fit-to-page pair, and a real iScale alongside iFitWidth=iFitHeight=1), so reading both would report a scale and a page count that contradict each other.
+*/
+function mapPrintSettings(raw, names) {
+	const setup = raw.setup;
+	const usable = setup !== void 0 && !setup.noPls;
+	const settings = {
+		pageSize: (usable ? require_biff_print_setup.pageSizeFromSetup(setup) : void 0) ?? DEFAULT_PRINT_SETTINGS.pageSize,
+		margins: {
+			topPt: raw.marginsPt.top ?? DEFAULT_PRINT_SETTINGS.margins.topPt,
+			rightPt: raw.marginsPt.right ?? DEFAULT_PRINT_SETTINGS.margins.rightPt,
+			bottomPt: raw.marginsPt.bottom ?? DEFAULT_PRINT_SETTINGS.margins.bottomPt,
+			leftPt: raw.marginsPt.left ?? DEFAULT_PRINT_SETTINGS.margins.leftPt
+		},
+		gridlines: raw.printGridlines ?? DEFAULT_PRINT_SETTINGS.gridlines,
+		headers: raw.printHeaders ?? DEFAULT_PRINT_SETTINGS.headers,
+		pageOrder: setup?.leftToRight === true ? "overThenDown" : "downThenOver"
+	};
+	if (setup !== void 0 && raw.fitToPage === true) {
+		if (setup.fitWidth > 0 && setup.fitHeight > 0) settings.fitToPages = {
+			width: setup.fitWidth,
+			height: setup.fitHeight
+		};
+	} else if (usable && setup.scalePercent > 0 && setup.scalePercent !== ACTUAL_SIZE_SCALE_PERCENT) settings.scalePercent = setup.scalePercent;
+	if (raw.rowBreaks.length > 0 || raw.columnBreaks.length > 0) settings.manualBreaks = {
+		rows: [...raw.rowBreaks],
+		columns: [...raw.columnBreaks]
+	};
+	if (names?.printRange !== void 0) settings.printRange = names.printRange;
+	if (names?.repeatRows !== void 0) settings.repeatRows = names.repeatRows;
+	if (names?.repeatColumns !== void 0) settings.repeatColumns = names.repeatColumns;
+	return settings;
+}
+/**
 * Reads a .xls file's bytes into a ContentDocument.
 *
 * The counterpart of ooxml.js's readXlsxContent, producing the same shape from the older format.
 */
 function readXlsContent(bytes) {
-	const substreams = require_biff_substreams.splitSubstreams(require_biff_substreams.groupRecords(require_biff_records.readRecords(require_container.readWorkbookStream(bytes))));
+	const { workbook, metadata } = require_container.readWorkbookStreams(bytes);
+	const substreams = require_biff_substreams.splitSubstreams(require_biff_substreams.groupRecords(require_biff_records.readRecords(workbook)));
 	const globalsSubstream = substreams[0];
 	if (globalsSubstream === void 0) throw new require_biff_records.BiffFormatError("workbook stream holds no substreams, so it carries no globals substream");
 	if (globalsSubstream.records.some((rec) => rec.type === 47)) throw new require_biff_records.BiffFormatError("workbook is encrypted (its globals substream carries a FilePass record); this reader does not decrypt");
 	const globals = require_workbook_globals.readWorkbookGlobals(globalsSubstream.records);
+	const sheets = globals.sheets.map((entry, sheetIndex) => ({
+		entry,
+		sheetIndex
+	})).filter(({ entry }) => entry.sheetType === SHEET_TYPE_WORKSHEET).map(({ entry, sheetIndex }) => readSheet(entry, sheetIndex, substreams, globals));
 	return {
 		kind: "spreadsheet",
-		metadata: {},
-		sheets: globals.sheets.filter((entry) => entry.sheetType === SHEET_TYPE_WORKSHEET).map((entry) => readSheet(entry, substreams, globals))
+		metadata: metadata === void 0 ? {} : (0, archive_codec.summaryInformationToLayoutMetadata)((0, archive_codec.readSummaryInformation)(metadata)),
+		sheets
 	};
 }
 /** The tree-form read: readXlsContent composed with the schema's own structural transform, exactly as ooxml.js's readXlsx wraps readXlsxContent. */
@@ -55,21 +106,29 @@ function readXls(bytes) {
 *
 * The substream is found by the byte offset BoundSheet8's lbPlyPos names, not by position: the order sheets appear in the workbook (which is BoundSheet8 order, and therefore the order of `globals.sheets`) is not required to match the order their substreams were written in. A sheet whose substream cannot be found still produces a ContentSheet, empty -- losing the sheet entirely would be a worse answer than losing its cells, since its name and position are real information the workbook did state.
 */
-function readSheet(entry, substreams, globals) {
+function readSheet(entry, sheetIndex, substreams, globals) {
 	const substream = substreams.find((candidate) => candidate.offset === entry.bofPosition && candidate.documentType === 16);
 	const raw = substream === void 0 ? {
 		cells: [],
 		rows: [],
 		columns: [],
-		merges: []
-	} : require_workbook_sheet.readSheetRecords(substream.records, globals.sharedStrings);
+		merges: [],
+		print: {
+			marginsPt: {},
+			rowBreaks: [],
+			columnBreaks: []
+		}
+	} : require_workbook_sheet.readSheetRecords(substream.records, globals.sharedStrings, {
+		sheets: globals.sheets,
+		sheetRanges: globals.sheetRanges
+	});
 	return {
 		name: entry.name,
 		cells: mapCells(raw, globals),
 		columns: mapColumns(raw),
 		rows: mapRows(raw),
 		images: [],
-		printSettings: DEFAULT_PRINT_SETTINGS
+		printSettings: mapPrintSettings(raw.print, globals.printNames.get(sheetIndex))
 	};
 }
 function mapRows(raw) {
@@ -107,10 +166,15 @@ function mapCells(raw, globals) {
 /**
 * Maps one raw cell, or drops it.
 *
-* A blank cell carrying no merge is dropped: ContentSheet's cell array is documented as sparse, holding only cells with something to show, and a Blank or MulBlank record states formatting this reader does not map yet. Dropping it keeps the array honest rather than filling a sheet with thousands of empty entries -- applyMerges below re-materialises the few blanks that anchor a merged range.
+* A blank cell showing nothing at all is dropped: ContentSheet's cell array is documented as sparse, holding only cells with something to show, and dropping the blanks keeps it honest rather than filling a sheet with thousands of empty entries -- applyMerges below re-materialises the few that anchor a merged range.
+*
+* A Blank or MulBlank record whose own XF carries a background or a border is not that case. Its formatting is the entire reason the record exists -- a producer writes one precisely to say "this cell is empty AND looks like this" -- so it becomes an `empty`-kind cell carrying that decoration, which is also what this package's own writer emits for one.
 */
 function mapCell(cell, globals) {
-	if (cell.value.kind === "blank") return;
+	const background = backgroundOf(globals, cell.xfIndex);
+	const borders = bordersOf(globals, cell.xfIndex);
+	const { alignment, verticalAlignment } = alignmentOf(globals, cell.xfIndex);
+	if (cell.value.kind === "blank" && background === void 0 && borders === void 0 && alignment === void 0 && verticalAlignment === void 0) return;
 	const formatCode = require_workbook_globals.formatCodeOf(globals, cell.xfIndex);
 	const value = resolveValue(cell, formatCode, globals.date1904);
 	const mapped = {
@@ -120,9 +184,50 @@ function mapCell(cell, globals) {
 		displayText: displayTextOf(value)
 	};
 	if (formatCode !== void 0) mapped.numberFormatCode = formatCode;
+	if (cell.formula !== void 0) mapped.formula = cell.formula;
+	if (background !== void 0) mapped.background = background;
+	if (borders !== void 0) mapped.borders = borders;
+	if (alignment !== void 0) mapped.alignment = alignment;
+	if (verticalAlignment !== void 0) mapped.verticalAlignment = verticalAlignment;
 	return mapped;
 }
 /**
+* A cell's own resolved fill colour, or undefined for a genuinely unfilled cell AND for every fill pattern beyond solid.
+*
+* A non-solid pattern (the 50%/75%/25% gray shades, the stripe and crosshatch family [MS-XLS]'s FillPattern enumeration also names) is a deliberate, permanent gap rather than an oversight: ContentSheetCell.background models one flat colour, and approximating a striped or crosshatched fill as its own foreground colour alone would misreport what the cell actually shows -- see xls-codec's README, "Cell decoration".
+*/
+function backgroundOf(globals, xfIndex) {
+	const format = globals.cellFormats[xfIndex];
+	if (format === void 0) return;
+	return require_biff_xf_colors.resolveFillBackground(format.decoration.fillPattern, format.decoration.fillForegroundIcv, globals.palette);
+}
+/** A cell's own resolved horizontal/vertical alignment -- already the exact Alignment/verticalAlignment members (or undefined) globals.ts's readCellFormat resolved through xf-colors.ts's unpackXfAlignment, so this is a lookup rather than a further resolution step, mirroring backgroundOf/bordersOf's own shape. Both fields undefined for a cell whose XF resolves to no CellFormat at all (an out-of-range xfIndex), matching every other resolveXOf helper's behaviour in that case. */
+function alignmentOf(globals, xfIndex) {
+	const format = globals.cellFormats[xfIndex];
+	if (format === void 0) return {};
+	const result = {};
+	if (format.alignment.horizontal !== void 0) result.alignment = format.alignment.horizontal;
+	if (format.alignment.vertical !== void 0) result.verticalAlignment = format.alignment.vertical;
+	return result;
+}
+/** A cell's own resolved per-side borders, or undefined when none of its four sides carry a border this reader resolves (no border at all, or a reserved/unrecognised BorderStyle token, or a colour this package cannot express as a fixed RGB value -- see xf-colors.ts's own resolveBorderEdge). */
+function bordersOf(globals, xfIndex) {
+	const format = globals.cellFormats[xfIndex];
+	if (format === void 0) return;
+	const { decoration } = format;
+	const left = require_biff_xf_colors.resolveBorderEdge(decoration.left, globals.palette);
+	const right = require_biff_xf_colors.resolveBorderEdge(decoration.right, globals.palette);
+	const top = require_biff_xf_colors.resolveBorderEdge(decoration.top, globals.palette);
+	const bottom = require_biff_xf_colors.resolveBorderEdge(decoration.bottom, globals.palette);
+	if (left === void 0 && right === void 0 && top === void 0 && bottom === void 0) return;
+	const borders = {};
+	if (left !== void 0) borders.left = left;
+	if (right !== void 0) borders.right = right;
+	if (top !== void 0) borders.top = top;
+	if (bottom !== void 0) borders.bottom = bottom;
+	return borders;
+}
+/**
 * Resolves a raw value into a ContentCellValue, classifying a number through its own format code.
 *
 * This is where BIFF8's lack of temporal and percentage cell types is undone: every date, time, percentage, and currency amount is stored as a bare number, and only the format its XF points at says which. A format naming a date the calendar does not have (the 1900 system's phantom leap day, or a negative serial) degrades to the plain number rather than emitting an invalid ISO string.
@@ -135,7 +240,7 @@ function resolveValue(cell, formatCode, date1904) {
 		kind: "number",
 		value: num
 	};
-	const format = require_number_format.classifyNumberFormat(formatCode);
+	const format = (0, excel_number_format.classifyNumberFormat)(formatCode);
 	switch (format.kind) {
 		case "percentage": return {
 			kind: "percentage",

package/dist/content.js

@@ -1,48 +1,99 @@
 import "./biff/record-types.js";
 import { BiffFormatError, readRecords } from "./biff/records.js";
-import { readWorkbookStream } from "./container.js";
+import { readWorkbookStreams } from "./container.js";
+import { inchesToPoints } from "./units.js";
+import { pageSizeFromSetup } from "./biff/print-setup.js";
 import { groupRecords, splitSubstreams } from "./biff/substreams.js";
-import { classifyNumberFormat } from "./number-format.js";
+import { resolveBorderEdge, resolveFillBackground } from "./biff/xf-colors.js";
 import { serialToIsoDate, serialToIsoDateTime, serialToIsoTime } from "./serial.js";
 import { formatCodeOf, readWorkbookGlobals } from "./workbook/globals.js";
 import { readSheetRecords } from "./workbook/sheet.js";
+import { readSummaryInformation, summaryInformationToLayoutMetadata } from "archive-codec";
 import { PAGE_SIZE_LETTER, assembleTree } from "document-schema.js";
+import { classifyNumberFormat } from "excel-number-format";
 //#region src/content.ts
 /** Which BoundSheet8 dt values name a sheet this reader maps. 0x00 is a worksheet or dialog sheet; macro sheets, chart sheets, and VBA modules carry no cell table for ContentSheet to hold. */
 const SHEET_TYPE_WORKSHEET = 0;
 /**
-* Print settings this package emits rather than reads.
+* Excel's own "Normal" page-setup preset, the per-field fallback for a print setting the file states nothing about.
 *
-* ContentSheetPrintSettings makes pageSize, margins, gridlines, headers, and pageOrder REQUIRED, so a sheet cannot be produced without them, and BIFF8 spreads the real values across the Setup, LeftMargin/RightMargin/TopMargin/BottomMargin, PrintGrid, and PrintRowCol records plus a paper-size code table. None of those is read yet, so these are Excel's own documented "Normal" preset -- the same constants ooxml.js falls back to for an xlsx carrying no pageMargins element -- and they are honest defaults rather than the file's own settings. Reading the real ones is tracked as remaining scope rather than guessed at from unverified field offsets.
+* ContentSheetPrintSettings makes pageSize, margins, gridlines, headers, and pageOrder REQUIRED, while [MS-XLS] 2.1.7.20.6's own PAGESETUP production makes every record behind them optional -- so a sheet whose page setup was never touched genuinely carries no Setup and no margin records, and something has to stand in. These are the values Excel itself calls Normal (top/bottom 0.75in, left/right 0.7in, on Letter paper, gridlines and row/column headers not printed, pages down-then-over), and the identical constants ooxml.js falls back to for an xlsx carrying no pageMargins element -- so the same untouched sheet reads the same either way.
+*
+* Each field falls back independently: a sheet that declares a left margin and nothing else keeps its real left margin and takes the preset for the other three, rather than the whole preset displacing the one value the file actually stated.
 */
-const POINTS_PER_INCH = 72;
 const DEFAULT_PRINT_SETTINGS = {
 	pageSize: PAGE_SIZE_LETTER,
 	margins: {
-		topPt: .75 * POINTS_PER_INCH,
-		rightPt: .7 * POINTS_PER_INCH,
-		bottomPt: .75 * POINTS_PER_INCH,
-		leftPt: .7 * POINTS_PER_INCH
+		topPt: inchesToPoints(.75),
+		rightPt: inchesToPoints(.7),
+		bottomPt: inchesToPoints(.75),
+		leftPt: inchesToPoints(.7)
 	},
 	gridlines: false,
 	headers: false,
 	pageOrder: "downThenOver"
 };
 /**
+* The iScale value that says "print at actual size", which is what ContentSheetPrintSettings already means by carrying no scalePercent at all.
+*
+* Setup's own iScale is a mandatory field of a mandatory record, with no spelling for "this sheet declares no scale" -- so an untouched sheet still states 100. Reporting that as an explicit scalePercent would put a field on every sheet of every workbook read, carrying nothing a consumer could act on that its absence does not already say, and would mean a document written with no scale came back with one. The two spellings render identically, so collapsing them onto the absent one is lossless in both directions; a scale that is genuinely anything else is reported exactly as the file states it.
+*/
+const ACTUAL_SIZE_SCALE_PERCENT = 100;
+/**
+* The print settings a sheet's own records and its built-in print names state, with the Normal preset filling in what they do not.
+*
+* Two of BIFF8's own conditional rules are honoured rather than flattened. A Setup record whose fNoPls bit is set declares its own paper size and scale undefined ([MS-XLS] 2.4.257: "whether the iPaperSize, iScale, iRes, iVRes, iCopies, fNoOrient, and fPortrait data are undefined and ignored"), so neither is read from it -- the page size falls back to the preset and no scalePercent is reported, rather than a paper code the file itself disowns being resolved into a confident page size. And WsBool's own fFitToPage decides which of Setup's two mutually exclusive scaling fields is live: iFitWidth/iFitHeight when set, iScale when clear. Real producers write both regardless (confirmed against LibreOffice-written BIFF8, which carries iScale=100 alongside a real fit-to-page pair, and a real iScale alongside iFitWidth=iFitHeight=1), so reading both would report a scale and a page count that contradict each other.
+*/
+function mapPrintSettings(raw, names) {
+	const setup = raw.setup;
+	const usable = setup !== void 0 && !setup.noPls;
+	const settings = {
+		pageSize: (usable ? pageSizeFromSetup(setup) : void 0) ?? DEFAULT_PRINT_SETTINGS.pageSize,
+		margins: {
+			topPt: raw.marginsPt.top ?? DEFAULT_PRINT_SETTINGS.margins.topPt,
+			rightPt: raw.marginsPt.right ?? DEFAULT_PRINT_SETTINGS.margins.rightPt,
+			bottomPt: raw.marginsPt.bottom ?? DEFAULT_PRINT_SETTINGS.margins.bottomPt,
+			leftPt: raw.marginsPt.left ?? DEFAULT_PRINT_SETTINGS.margins.leftPt
+		},
+		gridlines: raw.printGridlines ?? DEFAULT_PRINT_SETTINGS.gridlines,
+		headers: raw.printHeaders ?? DEFAULT_PRINT_SETTINGS.headers,
+		pageOrder: setup?.leftToRight === true ? "overThenDown" : "downThenOver"
+	};
+	if (setup !== void 0 && raw.fitToPage === true) {
+		if (setup.fitWidth > 0 && setup.fitHeight > 0) settings.fitToPages = {
+			width: setup.fitWidth,
+			height: setup.fitHeight
+		};
+	} else if (usable && setup.scalePercent > 0 && setup.scalePercent !== ACTUAL_SIZE_SCALE_PERCENT) settings.scalePercent = setup.scalePercent;
+	if (raw.rowBreaks.length > 0 || raw.columnBreaks.length > 0) settings.manualBreaks = {
+		rows: [...raw.rowBreaks],
+		columns: [...raw.columnBreaks]
+	};
+	if (names?.printRange !== void 0) settings.printRange = names.printRange;
+	if (names?.repeatRows !== void 0) settings.repeatRows = names.repeatRows;
+	if (names?.repeatColumns !== void 0) settings.repeatColumns = names.repeatColumns;
+	return settings;
+}
+/**
 * Reads a .xls file's bytes into a ContentDocument.
 *
 * The counterpart of ooxml.js's readXlsxContent, producing the same shape from the older format.
 */
 function readXlsContent(bytes) {
-	const substreams = splitSubstreams(groupRecords(readRecords(readWorkbookStream(bytes))));
+	const { workbook, metadata } = readWorkbookStreams(bytes);
+	const substreams = splitSubstreams(groupRecords(readRecords(workbook)));
 	const globalsSubstream = substreams[0];
 	if (globalsSubstream === void 0) throw new BiffFormatError("workbook stream holds no substreams, so it carries no globals substream");
 	if (globalsSubstream.records.some((rec) => rec.type === 47)) throw new BiffFormatError("workbook is encrypted (its globals substream carries a FilePass record); this reader does not decrypt");
 	const globals = readWorkbookGlobals(globalsSubstream.records);
+	const sheets = globals.sheets.map((entry, sheetIndex) => ({
+		entry,
+		sheetIndex
+	})).filter(({ entry }) => entry.sheetType === SHEET_TYPE_WORKSHEET).map(({ entry, sheetIndex }) => readSheet(entry, sheetIndex, substreams, globals));
 	return {
 		kind: "spreadsheet",
-		metadata: {},
-		sheets: globals.sheets.filter((entry) => entry.sheetType === SHEET_TYPE_WORKSHEET).map((entry) => readSheet(entry, substreams, globals))
+		metadata: metadata === void 0 ? {} : summaryInformationToLayoutMetadata(readSummaryInformation(metadata)),
+		sheets
 	};
 }
 /** The tree-form read: readXlsContent composed with the schema's own structural transform, exactly as ooxml.js's readXlsx wraps readXlsxContent. */
@@ -54,21 +105,29 @@ function readXls(bytes) {
 *
 * The substream is found by the byte offset BoundSheet8's lbPlyPos names, not by position: the order sheets appear in the workbook (which is BoundSheet8 order, and therefore the order of `globals.sheets`) is not required to match the order their substreams were written in. A sheet whose substream cannot be found still produces a ContentSheet, empty -- losing the sheet entirely would be a worse answer than losing its cells, since its name and position are real information the workbook did state.
 */
-function readSheet(entry, substreams, globals) {
+function readSheet(entry, sheetIndex, substreams, globals) {
 	const substream = substreams.find((candidate) => candidate.offset === entry.bofPosition && candidate.documentType === 16);
 	const raw = substream === void 0 ? {
 		cells: [],
 		rows: [],
 		columns: [],
-		merges: []
-	} : readSheetRecords(substream.records, globals.sharedStrings);
+		merges: [],
+		print: {
+			marginsPt: {},
+			rowBreaks: [],
+			columnBreaks: []
+		}
+	} : readSheetRecords(substream.records, globals.sharedStrings, {
+		sheets: globals.sheets,
+		sheetRanges: globals.sheetRanges
+	});
 	return {
 		name: entry.name,
 		cells: mapCells(raw, globals),
 		columns: mapColumns(raw),
 		rows: mapRows(raw),
 		images: [],
-		printSettings: DEFAULT_PRINT_SETTINGS
+		printSettings: mapPrintSettings(raw.print, globals.printNames.get(sheetIndex))
 	};
 }
 function mapRows(raw) {
@@ -106,10 +165,15 @@ function mapCells(raw, globals) {
 /**
 * Maps one raw cell, or drops it.
 *
-* A blank cell carrying no merge is dropped: ContentSheet's cell array is documented as sparse, holding only cells with something to show, and a Blank or MulBlank record states formatting this reader does not map yet. Dropping it keeps the array honest rather than filling a sheet with thousands of empty entries -- applyMerges below re-materialises the few blanks that anchor a merged range.
+* A blank cell showing nothing at all is dropped: ContentSheet's cell array is documented as sparse, holding only cells with something to show, and dropping the blanks keeps it honest rather than filling a sheet with thousands of empty entries -- applyMerges below re-materialises the few that anchor a merged range.
+*
+* A Blank or MulBlank record whose own XF carries a background or a border is not that case. Its formatting is the entire reason the record exists -- a producer writes one precisely to say "this cell is empty AND looks like this" -- so it becomes an `empty`-kind cell carrying that decoration, which is also what this package's own writer emits for one.
 */
 function mapCell(cell, globals) {
-	if (cell.value.kind === "blank") return;
+	const background = backgroundOf(globals, cell.xfIndex);
+	const borders = bordersOf(globals, cell.xfIndex);
+	const { alignment, verticalAlignment } = alignmentOf(globals, cell.xfIndex);
+	if (cell.value.kind === "blank" && background === void 0 && borders === void 0 && alignment === void 0 && verticalAlignment === void 0) return;
 	const formatCode = formatCodeOf(globals, cell.xfIndex);
 	const value = resolveValue(cell, formatCode, globals.date1904);
 	const mapped = {
@@ -119,9 +183,50 @@ function mapCell(cell, globals) {
 		displayText: displayTextOf(value)
 	};
 	if (formatCode !== void 0) mapped.numberFormatCode = formatCode;
+	if (cell.formula !== void 0) mapped.formula = cell.formula;
+	if (background !== void 0) mapped.background = background;
+	if (borders !== void 0) mapped.borders = borders;
+	if (alignment !== void 0) mapped.alignment = alignment;
+	if (verticalAlignment !== void 0) mapped.verticalAlignment = verticalAlignment;
 	return mapped;
 }
 /**
+* A cell's own resolved fill colour, or undefined for a genuinely unfilled cell AND for every fill pattern beyond solid.
+*
+* A non-solid pattern (the 50%/75%/25% gray shades, the stripe and crosshatch family [MS-XLS]'s FillPattern enumeration also names) is a deliberate, permanent gap rather than an oversight: ContentSheetCell.background models one flat colour, and approximating a striped or crosshatched fill as its own foreground colour alone would misreport what the cell actually shows -- see xls-codec's README, "Cell decoration".
+*/
+function backgroundOf(globals, xfIndex) {
+	const format = globals.cellFormats[xfIndex];
+	if (format === void 0) return;
+	return resolveFillBackground(format.decoration.fillPattern, format.decoration.fillForegroundIcv, globals.palette);
+}
+/** A cell's own resolved horizontal/vertical alignment -- already the exact Alignment/verticalAlignment members (or undefined) globals.ts's readCellFormat resolved through xf-colors.ts's unpackXfAlignment, so this is a lookup rather than a further resolution step, mirroring backgroundOf/bordersOf's own shape. Both fields undefined for a cell whose XF resolves to no CellFormat at all (an out-of-range xfIndex), matching every other resolveXOf helper's behaviour in that case. */
+function alignmentOf(globals, xfIndex) {
+	const format = globals.cellFormats[xfIndex];
+	if (format === void 0) return {};
+	const result = {};
+	if (format.alignment.horizontal !== void 0) result.alignment = format.alignment.horizontal;
+	if (format.alignment.vertical !== void 0) result.verticalAlignment = format.alignment.vertical;
+	return result;
+}
+/** A cell's own resolved per-side borders, or undefined when none of its four sides carry a border this reader resolves (no border at all, or a reserved/unrecognised BorderStyle token, or a colour this package cannot express as a fixed RGB value -- see xf-colors.ts's own resolveBorderEdge). */
+function bordersOf(globals, xfIndex) {
+	const format = globals.cellFormats[xfIndex];
+	if (format === void 0) return;
+	const { decoration } = format;
+	const left = resolveBorderEdge(decoration.left, globals.palette);
+	const right = resolveBorderEdge(decoration.right, globals.palette);
+	const top = resolveBorderEdge(decoration.top, globals.palette);
+	const bottom = resolveBorderEdge(decoration.bottom, globals.palette);
+	if (left === void 0 && right === void 0 && top === void 0 && bottom === void 0) return;
+	const borders = {};
+	if (left !== void 0) borders.left = left;
+	if (right !== void 0) borders.right = right;
+	if (top !== void 0) borders.top = top;
+	if (bottom !== void 0) borders.bottom = bottom;
+	return borders;
+}
+/**
 * Resolves a raw value into a ContentCellValue, classifying a number through its own format code.
 *
 * This is where BIFF8's lack of temporal and percentage cell types is undone: every date, time, percentage, and currency amount is stored as a bare number, and only the format its XF points at says which. A format naming a date the calendar does not have (the 1900 system's phantom leap day, or a negative serial) degrades to the plain number rather than emitting an invalid ISO string.

package/dist/cursor-VMtw9uVP.d.cts

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

package/dist/cursor-VMtw9uVP.d.ts

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