xls-codec 1.0.2 → 2.0.1

package/dist/workbook/sheet-writer.cjs

@@ -0,0 +1,277 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_record_types = require("../biff/record-types.cjs");
+const require_units = require("../units.cjs");
+const require_biff_print_setup = require("../biff/print-setup.cjs");
+const require_biff_write_errors = require("../biff/write-errors.cjs");
+const require_serial = require("../serial.cjs");
+const require_biff_builder = require("../biff/builder.cjs");
+const require_biff_record_writer = require("../biff/record-writer.cjs");
+const require_biff_errors = require("../biff/errors.cjs");
+const require_biff_bof_writer = require("../biff/bof-writer.cjs");
+const require_workbook_globals_writer = require("./globals-writer.cjs");
+const require_written_cells = require("../written-cells.cjs");
+//#region src/workbook/sheet-writer.ts
+/** BIFF8's own 16-bit row index and 8-bit column index ceilings ([MS-XLS] 2.4.221's Rw structure and 2.4.53's Col256U structure): 65536 rows (0-65535), 256 columns (0-255) -- unlike xlsx's much larger grid. A cell outside this range cannot be expressed in BIFF8 at all, so it is refused rather than silently truncated into a wrapped index. */
+const MAX_ROW_INDEX = 65535;
+const MAX_COLUMN_INDEX = 255;
+/** Excel 97-2003's own classic default row height (12.75pt) and default column width (in coldx units), used for a row/column this writer emits a record for but that carries no explicit size of its own -- a row with only `hidden` declared, or a ColInfo entry with no `widthPt`. */
+const DEFAULT_ROW_HEIGHT_TWIPS = 255;
+const DEFAULT_COLUMN_WIDTH_UNITS = 2340;
+/** [MS-XLS] 2.4.221's own Row.reserved3: "MUST be 1, and MUST be ignored." */
+const ROW_RESERVED3 = 1;
+const ROW_FLAG_HIDDEN_BIT = 5;
+const ROW_FLAG_UNSYNCED_BIT = 6;
+const COLINFO_FLAG_HIDDEN = 1;
+function checkedCellPosition(cell) {
+	if (cell.row > MAX_ROW_INDEX || cell.column > MAX_COLUMN_INDEX) throw new require_biff_write_errors.BiffWriteError(`cell at row ${cell.row}, column ${cell.column} is outside BIFF8's own grid (rows 0-${MAX_ROW_INDEX}, columns 0-${MAX_COLUMN_INDEX}); a .xls workbook cannot address it`);
+}
+/** The smallest and largest of a number list (undefined for an empty one), computed by a single reduce pass rather than `Math.min(...values)`/`Math.max(...values)` -- a spread call over a large cell/row list would risk the same argument-count ceiling biff/strings.ts's own readCharacters comment notes for String.fromCharCode. Folded through `reduce` rather than indexed (`values[0]`) so the accumulator's own null-check is what narrows the running min/max, never an assertion that the array is non-empty. */
+function minMax(values) {
+	return values.reduce((running, value) => running === void 0 ? {
+		min: value,
+		max: value
+	} : {
+		min: Math.min(running.min, value),
+		max: Math.max(running.max, value)
+	}, void 0);
+}
+/** Dimensions ([MS-XLS] 2.4.90): the sheet's used range, derived from exactly the cells this writer emits a record for -- so a decorated empty cell counts (a real producer's used range covers a cell carrying direct formatting) while an undecorated one, having neither data nor formatting, does not. */
+function writeDimensionsRecord(writtenCells) {
+	const rows = minMax(writtenCells.map((cell) => cell.row));
+	const columns = minMax(writtenCells.map((cell) => cell.column));
+	const rwMic = rows?.min ?? 0;
+	const rwMac = rows === void 0 ? 0 : rows.max + 1;
+	const colMic = columns?.min ?? 0;
+	const colMac = columns === void 0 ? 0 : columns.max + 1;
+	const data = new require_biff_builder.RecordBuilder().u32(rwMic).u32(rwMac).u16(colMic).u16(colMac).u16(0).build();
+	return require_biff_record_writer.writeRecord(512, data);
+}
+/** ColInfo ([MS-XLS] 2.4.53): one record per input column entry, covering exactly that one column (colFirst === colLast) rather than merging adjacent same-width columns into a range -- both are legal, and workbook/sheet.ts's own readColInfo expands either shape back into one RawColumn per column, so the two round-trip identically. */
+function writeColInfoRecord(column) {
+	if (column.index > MAX_COLUMN_INDEX) throw new require_biff_write_errors.BiffWriteError(`column ${column.index} is outside BIFF8's own 256-column grid (columns 0-${MAX_COLUMN_INDEX})`);
+	const coldx = column.widthPt !== void 0 ? require_units.pointsToColumnWidth(column.widthPt) : DEFAULT_COLUMN_WIDTH_UNITS;
+	const flags = column.hidden === true ? COLINFO_FLAG_HIDDEN : 0;
+	const data = new require_biff_builder.RecordBuilder().u16(column.index).u16(column.index).u16(coldx).u16(require_workbook_globals_writer.GENERAL_CELL_XF_INDEX).u16(flags).u16(0).build();
+	return require_biff_record_writer.writeRecord(125, data);
+}
+/** Row ([MS-XLS] 2.4.221): the row's own populated-column range (from its cells, not the sheet's own Dimensions), height, and hidden/manually-set flags. */
+function writeRowRecord(rowIndex, cellsInRow, declared) {
+	const columnRange = minMax(cellsInRow.map((cell) => cell.column));
+	const colMic = columnRange?.min ?? 0;
+	const colMac = columnRange === void 0 ? 0 : columnRange.max + 1;
+	const heightTwips = declared?.heightPt !== void 0 ? require_units.pointsToTwips(declared.heightPt) : DEFAULT_ROW_HEIGHT_TWIPS;
+	const fDyZero = declared?.hidden === true ? 1 : 0;
+	const fUnsynced = declared?.heightPt !== void 0 ? 1 : 0;
+	const flagsByte = fDyZero << ROW_FLAG_HIDDEN_BIT | fUnsynced << ROW_FLAG_UNSYNCED_BIT;
+	const data = new require_biff_builder.RecordBuilder().u16(rowIndex).u16(colMic).u16(colMac).u16(heightTwips).u16(0).u16(0).u8(flagsByte).u8(ROW_RESERVED3).u16(0).build();
+	return require_biff_record_writer.writeRecord(520, data);
+}
+/** Every merged range the sheet's own cells declare via colSpan/rowSpan, regardless of whether the anchor cell carries a value -- an 'empty'-kind anchor still merges, and content.ts's own applyMerges reconstructs it independently from the MergeCells record this produces. */
+function mergedRangesOf(cells) {
+	const ranges = [];
+	for (const cell of cells) {
+		const rowSpan = cell.rowSpan ?? 1;
+		const colSpan = cell.colSpan ?? 1;
+		if (rowSpan > 1 || colSpan > 1) ranges.push({
+			startRow: cell.row,
+			startColumn: cell.column,
+			endRow: cell.row + rowSpan - 1,
+			endColumn: cell.column + colSpan - 1
+		});
+	}
+	return ranges;
+}
+/** MergeCells ([MS-XLS] 2.4.168): a count then that many Ref8 structures ([MS-XLS] 2.5.208), each rowFirst/rowLast/colFirst/colLast -- the order workbook/sheet.ts's own readMergeCells reads them in. */
+function writeMergeCellsRecord(ranges) {
+	const builder = new require_biff_builder.RecordBuilder().u16(ranges.length);
+	for (const range of ranges) builder.u16(range.startRow).u16(range.endRow).u16(range.startColumn).u16(range.endColumn);
+	return require_biff_record_writer.writeRecord(229, builder.build());
+}
+/** CalcCount's own cIter ([MS-XLS] 2.4.31): "MUST be greater than or equal to one and less than or equal to 32767". Excel's own default iteration limit, and what a real LibreOffice-written BIFF8 carries. */
+const CALC_ITERATION_LIMIT = 100;
+/** CalcDelta's own numDelta ([MS-XLS] 2.4.32): Excel's own default minimum change for iterative calculation to continue. */
+const CALC_ITERATION_DELTA = .001;
+/**
+* The calculation-state records [MS-XLS] 2.1.7.20.6's GLOBALS production requires ahead of PrintRowCol, none of which carries anything document-schema.js models.
+*
+* They are written for two reasons, one of them empirical. The grammar makes them mandatory -- `GLOBALS = CalcMode CalcCount CalcRefMode CalcIter CalcDelta CalcSaveRecalc PrintRowCol PrintGrid GridSet Guts DefaultRowHeight WsBool ...`, with no brackets on any of them -- so a substream that opens straight with a print setting is not a conformant worksheet at all. And LibreOffice's own BIFF8 importer silently discards whichever page-settings record comes FIRST in a worksheet substream: with PrintRowCol in that slot, a `.xls` this writer produced with row and column headers enabled opened in LibreOffice with them off, while every other print setting in the same file came through correctly. Moving any other record into that slot fixes it, which is what these do -- verified by writing the same workbook with and without them and re-reading each through `soffice --convert-to fods`.
+*
+* The values are Excel's own defaults (automatic recalculation, A1 references, iteration off), matching what a real LibreOffice-written file carries for a workbook nobody has changed the calculation settings of. CalcMode is deliberately not among them: the production names it, but LibreOffice does not write one into a worksheet substream either, and the records below already satisfy the constraint this comment exists for.
+*/
+function writeCalculationStateRecords() {
+	return [
+		require_biff_record_writer.writeRecord(12, new require_biff_builder.RecordBuilder().u16(CALC_ITERATION_LIMIT).build()),
+		require_biff_record_writer.writeRecord(15, new require_biff_builder.RecordBuilder().u16(1).build()),
+		require_biff_record_writer.writeRecord(17, new require_biff_builder.RecordBuilder().u16(0).build()),
+		require_biff_record_writer.writeRecord(16, new require_biff_builder.RecordBuilder().f64(CALC_ITERATION_DELTA).build()),
+		require_biff_record_writer.writeRecord(95, new require_biff_builder.RecordBuilder().u16(1).build())
+	];
+}
+/** Setup's own iRes/iVRes ([MS-XLS] 2.4.257), a printer resolution in DPI. 300 is what a real LibreOffice-written BIFF8 carries and a sane default for a writer with no printer to ask; the field is undefined whenever fNoPls is set, which this writer never sets, so it must carry something real. */
+const SETUP_PRINT_RESOLUTION_DPI = 300;
+/** Setup's own iCopies: one copy, the only sensible value for a file that is not being sent to a printer right now. */
+const SETUP_COPIES = 1;
+/** Setup's own numHdr/numFtr ([MS-XLS] 2.4.257), the header and footer margins in inches. Excel's own Normal preset value; Margins has no header/footer field for a real one to come from, and content.ts's read side discards these for the same reason. */
+const SETUP_HEADER_FOOTER_MARGIN_INCHES = .3;
+/** Setup's own iFitWidth/iFitHeight when the sheet is not in fit-to-page mode at all. Written rather than left at 0 because 0 means "as many pages as necessary" -- a real value a reader must not see while fFitToPage is clear and mistake for an intent the sheet never had. */
+const SETUP_INACTIVE_FIT_PAGES = 1;
+/** Setup's own iScale when the sheet IS in fit-to-page mode: 100%, actual size, the inactive value a real producer leaves behind (confirmed against LibreOffice-written BIFF8, whose fit-to-page sheets carry exactly this). */
+const SETUP_INACTIVE_SCALE_PERCENT = 100;
+/** Setup's own iPaperSize for a page size no entry of its code table names: [MS-XLS] 2.4.257's "The value 0, or values greater than or equal to 256, specify custom printer paper sizes." */
+const SETUP_CUSTOM_PAPER_SIZE = 0;
+/** [MS-XLS] 2.4.257's own ceiling on iFitWidth and iFitHeight: "MUST be less than or equal to 32767." */
+const SETUP_MAX_FIT_PAGES = 32767;
+/** iScale is an unsigned 16-bit percentage with no documented ceiling of its own, so the field's own width is the only bound there is. 1 is the floor: 0 is not a scaling factor, and a sub-1% one has no whole-percent spelling. */
+const SETUP_MIN_SCALE_PERCENT = 1;
+const SETUP_MAX_SCALE_PERCENT = 65535;
+/**
+* Clamps a schema value into the range its own Setup field can hold, since `ContentSheetPrintSettings` bounds neither a scale percentage nor a fit-to-page count from above.
+*
+* Clamping rather than throwing, and rather than letting the value wrap: a print scale is a presentational field, and refusing a whole workbook over an absurd one would lose its cells for no gain (the same trade the paper-code case above settles the same way). Silently wrapping is the option neither of those beats -- a scale of 65540% would land in the file as 4%, which is a different intent stated confidently.
+*/
+function clampedSetupField(value, minimum, maximum) {
+	return Math.min(Math.max(Math.round(value), minimum), maximum);
+}
+/**
+* Setup ([MS-XLS] 2.4.257): iPaperSize, iScale, iPageStart, iFitWidth, iFitHeight, the flags word, iRes, iVRes, numHdr, numFtr, iCopies.
+*
+* fNoPls is deliberately never set. It would declare this record's own paper size, scale, and orientation undefined -- exactly the three fields it exists here to carry -- and [MS-XLS] pairs it with a Pls record holding a printer driver's DEVMODE blob, which this writer has none of.
+*
+* A page size no code in the table names is written as SETUP_CUSTOM_PAPER_SIZE rather than as a standard paper it is not. The dimensions themselves are genuinely unwritable -- Setup addresses paper only by code, and [MS-XLS]'s own escape hatch for a size outside the table is that same Pls record -- so the choice is between saying "custom" and saying something false. Saying "custom" is what the spec's own iPaperSize table provides the value for, and it leaves a reader (this package's own included) free to fall back to its documented default instead of confidently reporting Letter for a page that is not Letter. This matters in practice rather than in theory: a spreadsheet converted from a slide deck or a drawing carries that source's own canvas as its page size, which is almost never a named paper, and refusing the conversion outright over a presentational field would lose the cells too.
+*/
+function writeSetupRecord(settings) {
+	const paper = require_biff_print_setup.paperSelectionFor(settings.pageSize) ?? {
+		code: SETUP_CUSTOM_PAPER_SIZE,
+		portrait: settings.pageSize.widthPt <= settings.pageSize.heightPt
+	};
+	const fitToPages = settings.fitToPages;
+	const fields = {
+		paperCode: paper.code,
+		scalePercent: fitToPages === void 0 ? clampedSetupField(settings.scalePercent ?? SETUP_INACTIVE_SCALE_PERCENT, SETUP_MIN_SCALE_PERCENT, SETUP_MAX_SCALE_PERCENT) : SETUP_INACTIVE_SCALE_PERCENT,
+		fitWidth: fitToPages === void 0 ? SETUP_INACTIVE_FIT_PAGES : clampedSetupField(fitToPages.width, 1, SETUP_MAX_FIT_PAGES),
+		fitHeight: fitToPages === void 0 ? SETUP_INACTIVE_FIT_PAGES : clampedSetupField(fitToPages.height, 1, SETUP_MAX_FIT_PAGES),
+		leftToRight: settings.pageOrder === "overThenDown",
+		portrait: paper.portrait,
+		noPls: false,
+		noOrientation: false
+	};
+	const data = new require_biff_builder.RecordBuilder().u16(fields.paperCode).u16(fields.scalePercent).u16(0).u16(fields.fitWidth).u16(fields.fitHeight).u16(require_biff_print_setup.packSetupFlags(fields)).u16(SETUP_PRINT_RESOLUTION_DPI).u16(SETUP_PRINT_RESOLUTION_DPI).f64(SETUP_HEADER_FOOTER_MARGIN_INCHES).f64(SETUP_HEADER_FOOTER_MARGIN_INCHES).u16(SETUP_COPIES).build();
+	return require_biff_record_writer.writeRecord(161, data);
+}
+/** Any of the four margin records ([MS-XLS] 2.4.151, 2.4.219, 2.4.328, 2.4.27): a single Xnum stating that margin in inches. All four share one field layout, so one writer serves them all -- the mirror of workbook/sheet.ts's own single readMargin. */
+function writeMarginRecord(recordType, points) {
+	return require_biff_record_writer.writeRecord(recordType, new require_biff_builder.RecordBuilder().f64(require_units.pointsToInches(points)).build());
+}
+/** PrintGrid ([MS-XLS] 2.4.202) and PrintRowCol ([MS-XLS] 2.4.203), each a single 16-bit boolean. */
+function writeBooleanRecord(recordType, value) {
+	return require_biff_record_writer.writeRecord(recordType, new require_biff_builder.RecordBuilder().u16(value ? 1 : 0).build());
+}
+/** WsBool ([MS-XLS] 2.4.351). Only fFitToPage is set from real data; every other bit is written clear, which is what a sheet with no outline, no dialog behaviour, no synchronised scrolling, and no transition formula handling means -- and is exactly the set of facts ContentSheet carries nothing about. */
+function writeWsBoolRecord(fitToPage) {
+	return require_biff_record_writer.writeRecord(129, new require_biff_builder.RecordBuilder().u16(fitToPage ? 256 : 0).build());
+}
+/**
+* HorizontalPageBreaks ([MS-XLS] 2.4.142) or VerticalPageBreaks ([MS-XLS] 2.4.343): a count then that many six-byte structures, each the break's own index followed by the start and end of its extent along the other axis.
+*
+* Both structures share that three-field shape, so one writer serves both -- the extent's own end differs, which is what `extentEnd` carries: ContentSheetPrintSettings models a break as a whole-axis index with no extent, so every break written here runs the full width or height of BIFF8's own grid. Written in ascending index order, which is the sort [MS-XLS] requires of both arrays; the caller's own indices are sorted first rather than assumed sorted.
+*/
+function writePageBreaksRecord(recordType, indices, extentEnd) {
+	const sorted = [...new Set(indices)].sort((a, b) => a - b);
+	const builder = new require_biff_builder.RecordBuilder().u16(sorted.length);
+	for (const index of sorted) builder.u16(index).u16(0).u16(extentEnd);
+	return require_biff_record_writer.writeRecord(recordType, builder.build());
+}
+/**
+* `manualBreaks.rows`/`.columns` is not bounded to BIFF8's own grid the way a cell's own row/column is (`writeCellRecord`'s `MAX_ROW_INDEX`/`MAX_COLUMN_INDEX` guard above throws for exactly that reason). `writePageBreaksRecord` writes each index into a 16-bit field regardless (`RecordBuilder.u16` masks with `0xffff`), so an out-of-grid break would otherwise silently wrap to a plausible-looking in-grid one -- a break asked for at row 70000 landing at row 4464 -- with nothing downstream to notice.
+*
+* Dropped rather than clamped: unlike a print range or a repeated header band, where clamping to the grid's own last row/column is genuinely what "to the bottom of the sheet" means once the grid shrinks under it (print-names.ts's own clampToGrid), a page break is a single position, and clamping one would insert a break at the grid's own edge the caller never asked for. Dropping states the honest thing an out-of-grid break means once BIFF8's own ceiling has been applied: no such row/column exists for it to sit at.
+*/
+function inGridBreaks(indices, maxIndex) {
+	return indices.filter((index) => index <= maxIndex);
+}
+/**
+* Every print-settings record one sheet needs, in [MS-XLS] 2.1.7.20.6's own order.
+*
+* That order is two productions, back to back, both of which the worksheet substream places ahead of COLUMNS, Dimensions, and the cell table: `GLOBALS = ... PrintRowCol PrintGrid GridSet Guts DefaultRowHeight WsBool [Sync] [LPr] [HorizontalPageBreaks] [VerticalPageBreaks]` and `PAGESETUP = Header Footer HCenter VCenter [LeftMargin] [RightMargin] [TopMargin] [BottomMargin] [Pls *Continue] [Setup]`. The mandatory records this writer does not emit at all (the calculation-state family, GridSet, Guts, DefaultRowHeight, Header/Footer, HCenter/VCenter) are the same UI and interoperability bookkeeping it already omits everywhere else -- see this package's README -- so what remains is the optional subset that actually carries print settings, in the relative order those two productions give it.
+*
+* Every record here is written unconditionally, including for a sheet whose settings are exactly the Normal preset. A print setting has no "absent" spelling in ContentSheetPrintSettings -- gridlines, headers, page order, page size, and all four margins are required fields -- so there is no way to tell a sheet that asked for the preset from one that never stated anything, and writing the values out is what makes the round trip exact either way.
+*/
+function writePrintSettingsRecords(settings) {
+	const pieces = [
+		...writeCalculationStateRecords(),
+		writeBooleanRecord(42, settings.headers),
+		writeBooleanRecord(43, settings.gridlines),
+		writeWsBoolRecord(settings.fitToPages !== void 0)
+	];
+	const breaks = settings.manualBreaks;
+	if (breaks !== void 0) {
+		const rowBreaks = inGridBreaks(breaks.rows, MAX_ROW_INDEX);
+		if (rowBreaks.length > 0) pieces.push(writePageBreaksRecord(27, rowBreaks, MAX_COLUMN_INDEX));
+		const columnBreaks = inGridBreaks(breaks.columns, MAX_COLUMN_INDEX);
+		if (columnBreaks.length > 0) pieces.push(writePageBreaksRecord(26, columnBreaks, MAX_ROW_INDEX));
+	}
+	pieces.push(writeMarginRecord(38, settings.margins.leftPt), writeMarginRecord(39, settings.margins.rightPt), writeMarginRecord(40, settings.margins.topPt), writeMarginRecord(41, settings.margins.bottomPt), writeSetupRecord(settings));
+	return pieces;
+}
+function cellHeader(cell, xfIndex) {
+	return new require_biff_builder.RecordBuilder().u16(cell.row).u16(cell.column).u16(xfIndex);
+}
+/** One cell record, keyed by ContentCellValue's own discriminant: Number for every numeric/temporal kind ([MS-XLS] 2.4.180 -- always the full IEEE 754 double, never the packed RK encoding, which is a compaction optimisation this writer does not implement), LabelSst for a string ([MS-XLS] 2.4.149, through the workbook-wide shared string table), BoolErr for a boolean or error value ([MS-XLS] 2.4.24), and Blank for an 'empty' cell whose formatting is the only thing it carries ([MS-XLS] 2.4.20 -- a cell header and nothing else, so the XF its ixfe names is the whole content). An unformatted empty cell never reaches here at all: written-cells.ts's own predicate filters it out upstream, since there is nothing for it to say. */
+function writeCellValueRecord(cell, xfIndex, ctx) {
+	const value = cell.value;
+	switch (value.kind) {
+		case "number":
+		case "percentage":
+		case "currency": return require_biff_record_writer.writeRecord(515, cellHeader(cell, xfIndex).f64(value.value).build());
+		case "date": return require_biff_record_writer.writeRecord(515, cellHeader(cell, xfIndex).f64(require_serial.isoDateToSerial(value.value, false)).build());
+		case "time": return require_biff_record_writer.writeRecord(515, cellHeader(cell, xfIndex).f64(require_serial.isoTimeToSerial(value.value)).build());
+		case "dateTime": return require_biff_record_writer.writeRecord(515, cellHeader(cell, xfIndex).f64(require_serial.isoDateTimeToSerial(value.value, false)).build());
+		case "string": {
+			const index = ctx.sstIndexFor(value.value);
+			return require_biff_record_writer.writeRecord(253, cellHeader(cell, xfIndex).u32(index).build());
+		}
+		case "boolean": return require_biff_record_writer.writeRecord(517, cellHeader(cell, xfIndex).u8(value.value ? 1 : 0).u8(0).build());
+		case "error": {
+			const code = require_biff_errors.errorCodeOf(value.value);
+			if (code === void 0) throw new require_biff_write_errors.BiffWriteError(`cell at row ${cell.row}, column ${cell.column} carries error text ${JSON.stringify(value.value)}, which is not one of the eight error values [MS-XLS] 2.5.10 defines`);
+			return require_biff_record_writer.writeRecord(517, cellHeader(cell, xfIndex).u8(code).u8(1).build());
+		}
+		case "empty":
+			if (!require_written_cells.cellCarriesFormatting(cell)) throw new require_biff_write_errors.BiffWriteError(`internal error: writeCellValueRecord was called for the undecorated empty cell at row ${cell.row}, column ${cell.column}, which written-cells.ts's own predicate must filter out before reaching here`);
+			return require_biff_record_writer.writeRecord(513, cellHeader(cell, xfIndex).build());
+	}
+}
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+function buildWorksheetSubstream(sheet, ctx) {
+	for (const cell of sheet.cells) checkedCellPosition(cell);
+	const writtenCells = sheet.cells.filter(require_written_cells.writesCellRecord);
+	const cellsByRow = /* @__PURE__ */ new Map();
+	for (const cell of writtenCells) {
+		const existing = cellsByRow.get(cell.row);
+		if (existing === void 0) cellsByRow.set(cell.row, [cell]);
+		else existing.push(cell);
+	}
+	for (const cells of cellsByRow.values()) cells.sort((a, b) => a.column - b.column);
+	const declaredRows = new Map(sheet.rows.map((row) => [row.index, row]));
+	const sortedRowIndices = [.../* @__PURE__ */ new Set([...cellsByRow.keys(), ...declaredRows.keys()])].sort((a, b) => a - b);
+	const pieces = [
+		require_biff_record_writer.writeRecord(require_biff_record_types.RECORD_BOF, require_biff_bof_writer.writeBofData(16)),
+		...writePrintSettingsRecords(sheet.printSettings),
+		writeDimensionsRecord(writtenCells)
+	];
+	for (const column of sheet.columns) pieces.push(writeColInfoRecord(column));
+	for (const rowIndex of sortedRowIndices) {
+		const cellsInRow = cellsByRow.get(rowIndex) ?? [];
+		pieces.push(writeRowRecord(rowIndex, cellsInRow, declaredRows.get(rowIndex)));
+		for (const cell of cellsInRow) {
+			const xfIndex = ctx.xfIndexForCell(cell);
+			pieces.push(writeCellValueRecord(cell, xfIndex, ctx));
+		}
+	}
+	const merges = mergedRangesOf(sheet.cells);
+	if (merges.length > 0) pieces.push(writeMergeCellsRecord(merges));
+	pieces.push(require_biff_record_writer.writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
+	return require_biff_record_writer.concatRecords(...pieces);
+}
+//#endregion
+exports.buildWorksheetSubstream = buildWorksheetSubstream;

package/dist/workbook/sheet-writer.d.cts

@@ -0,0 +1,12 @@
+import { ContentSheet, ContentSheetCell } from "document-schema.js";
+//#region src/workbook/sheet-writer.d.ts
+interface SheetWriteContext {
+  /** The XF index ([MS-XLS] 2.5.168 IXFCell) a cell's own (number format, alignment, decoration) combination resolves to -- GENERAL_CELL_XF_INDEX for a cell with General formatting, general/bottom alignment, and no background/borders, one of the workbook's other cell XFs otherwise. write.ts's own cell-format interning pass is what assigns and deduplicates these. */
+  xfIndexForCell(cell: ContentSheetCell): number;
+  /** The shared string table index for a string cell's own text; every string a sheet writes must already be registered in the workbook-wide table before this is called. */
+  sstIndexFor(text: string): number;
+}
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext): Uint8Array<ArrayBuffer>;
+//#endregion
+export { SheetWriteContext, buildWorksheetSubstream };

package/dist/workbook/sheet-writer.d.ts

@@ -0,0 +1,12 @@
+import { ContentSheet, ContentSheetCell } from "document-schema.js";
+//#region src/workbook/sheet-writer.d.ts
+interface SheetWriteContext {
+  /** The XF index ([MS-XLS] 2.5.168 IXFCell) a cell's own (number format, alignment, decoration) combination resolves to -- GENERAL_CELL_XF_INDEX for a cell with General formatting, general/bottom alignment, and no background/borders, one of the workbook's other cell XFs otherwise. write.ts's own cell-format interning pass is what assigns and deduplicates these. */
+  xfIndexForCell(cell: ContentSheetCell): number;
+  /** The shared string table index for a string cell's own text; every string a sheet writes must already be registered in the workbook-wide table before this is called. */
+  sstIndexFor(text: string): number;
+}
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext): Uint8Array<ArrayBuffer>;
+//#endregion
+export { SheetWriteContext, buildWorksheetSubstream };

package/dist/workbook/sheet-writer.js

@@ -0,0 +1,276 @@
+import { RECORD_BOF } from "../biff/record-types.js";
+import { pointsToColumnWidth, pointsToInches, pointsToTwips } from "../units.js";
+import { packSetupFlags, paperSelectionFor } from "../biff/print-setup.js";
+import { BiffWriteError } from "../biff/write-errors.js";
+import { isoDateTimeToSerial, isoDateToSerial, isoTimeToSerial } from "../serial.js";
+import { RecordBuilder } from "../biff/builder.js";
+import { concatRecords, writeRecord } from "../biff/record-writer.js";
+import { errorCodeOf } from "../biff/errors.js";
+import { writeBofData } from "../biff/bof-writer.js";
+import { GENERAL_CELL_XF_INDEX } from "./globals-writer.js";
+import { cellCarriesFormatting, writesCellRecord } from "../written-cells.js";
+//#region src/workbook/sheet-writer.ts
+/** BIFF8's own 16-bit row index and 8-bit column index ceilings ([MS-XLS] 2.4.221's Rw structure and 2.4.53's Col256U structure): 65536 rows (0-65535), 256 columns (0-255) -- unlike xlsx's much larger grid. A cell outside this range cannot be expressed in BIFF8 at all, so it is refused rather than silently truncated into a wrapped index. */
+const MAX_ROW_INDEX = 65535;
+const MAX_COLUMN_INDEX = 255;
+/** Excel 97-2003's own classic default row height (12.75pt) and default column width (in coldx units), used for a row/column this writer emits a record for but that carries no explicit size of its own -- a row with only `hidden` declared, or a ColInfo entry with no `widthPt`. */
+const DEFAULT_ROW_HEIGHT_TWIPS = 255;
+const DEFAULT_COLUMN_WIDTH_UNITS = 2340;
+/** [MS-XLS] 2.4.221's own Row.reserved3: "MUST be 1, and MUST be ignored." */
+const ROW_RESERVED3 = 1;
+const ROW_FLAG_HIDDEN_BIT = 5;
+const ROW_FLAG_UNSYNCED_BIT = 6;
+const COLINFO_FLAG_HIDDEN = 1;
+function checkedCellPosition(cell) {
+	if (cell.row > MAX_ROW_INDEX || cell.column > MAX_COLUMN_INDEX) throw new BiffWriteError(`cell at row ${cell.row}, column ${cell.column} is outside BIFF8's own grid (rows 0-${MAX_ROW_INDEX}, columns 0-${MAX_COLUMN_INDEX}); a .xls workbook cannot address it`);
+}
+/** The smallest and largest of a number list (undefined for an empty one), computed by a single reduce pass rather than `Math.min(...values)`/`Math.max(...values)` -- a spread call over a large cell/row list would risk the same argument-count ceiling biff/strings.ts's own readCharacters comment notes for String.fromCharCode. Folded through `reduce` rather than indexed (`values[0]`) so the accumulator's own null-check is what narrows the running min/max, never an assertion that the array is non-empty. */
+function minMax(values) {
+	return values.reduce((running, value) => running === void 0 ? {
+		min: value,
+		max: value
+	} : {
+		min: Math.min(running.min, value),
+		max: Math.max(running.max, value)
+	}, void 0);
+}
+/** Dimensions ([MS-XLS] 2.4.90): the sheet's used range, derived from exactly the cells this writer emits a record for -- so a decorated empty cell counts (a real producer's used range covers a cell carrying direct formatting) while an undecorated one, having neither data nor formatting, does not. */
+function writeDimensionsRecord(writtenCells) {
+	const rows = minMax(writtenCells.map((cell) => cell.row));
+	const columns = minMax(writtenCells.map((cell) => cell.column));
+	const rwMic = rows?.min ?? 0;
+	const rwMac = rows === void 0 ? 0 : rows.max + 1;
+	const colMic = columns?.min ?? 0;
+	const colMac = columns === void 0 ? 0 : columns.max + 1;
+	const data = new RecordBuilder().u32(rwMic).u32(rwMac).u16(colMic).u16(colMac).u16(0).build();
+	return writeRecord(512, data);
+}
+/** ColInfo ([MS-XLS] 2.4.53): one record per input column entry, covering exactly that one column (colFirst === colLast) rather than merging adjacent same-width columns into a range -- both are legal, and workbook/sheet.ts's own readColInfo expands either shape back into one RawColumn per column, so the two round-trip identically. */
+function writeColInfoRecord(column) {
+	if (column.index > MAX_COLUMN_INDEX) throw new BiffWriteError(`column ${column.index} is outside BIFF8's own 256-column grid (columns 0-${MAX_COLUMN_INDEX})`);
+	const coldx = column.widthPt !== void 0 ? pointsToColumnWidth(column.widthPt) : DEFAULT_COLUMN_WIDTH_UNITS;
+	const flags = column.hidden === true ? COLINFO_FLAG_HIDDEN : 0;
+	const data = new RecordBuilder().u16(column.index).u16(column.index).u16(coldx).u16(GENERAL_CELL_XF_INDEX).u16(flags).u16(0).build();
+	return writeRecord(125, data);
+}
+/** Row ([MS-XLS] 2.4.221): the row's own populated-column range (from its cells, not the sheet's own Dimensions), height, and hidden/manually-set flags. */
+function writeRowRecord(rowIndex, cellsInRow, declared) {
+	const columnRange = minMax(cellsInRow.map((cell) => cell.column));
+	const colMic = columnRange?.min ?? 0;
+	const colMac = columnRange === void 0 ? 0 : columnRange.max + 1;
+	const heightTwips = declared?.heightPt !== void 0 ? pointsToTwips(declared.heightPt) : DEFAULT_ROW_HEIGHT_TWIPS;
+	const fDyZero = declared?.hidden === true ? 1 : 0;
+	const fUnsynced = declared?.heightPt !== void 0 ? 1 : 0;
+	const flagsByte = fDyZero << ROW_FLAG_HIDDEN_BIT | fUnsynced << ROW_FLAG_UNSYNCED_BIT;
+	const data = new RecordBuilder().u16(rowIndex).u16(colMic).u16(colMac).u16(heightTwips).u16(0).u16(0).u8(flagsByte).u8(ROW_RESERVED3).u16(0).build();
+	return writeRecord(520, data);
+}
+/** Every merged range the sheet's own cells declare via colSpan/rowSpan, regardless of whether the anchor cell carries a value -- an 'empty'-kind anchor still merges, and content.ts's own applyMerges reconstructs it independently from the MergeCells record this produces. */
+function mergedRangesOf(cells) {
+	const ranges = [];
+	for (const cell of cells) {
+		const rowSpan = cell.rowSpan ?? 1;
+		const colSpan = cell.colSpan ?? 1;
+		if (rowSpan > 1 || colSpan > 1) ranges.push({
+			startRow: cell.row,
+			startColumn: cell.column,
+			endRow: cell.row + rowSpan - 1,
+			endColumn: cell.column + colSpan - 1
+		});
+	}
+	return ranges;
+}
+/** MergeCells ([MS-XLS] 2.4.168): a count then that many Ref8 structures ([MS-XLS] 2.5.208), each rowFirst/rowLast/colFirst/colLast -- the order workbook/sheet.ts's own readMergeCells reads them in. */
+function writeMergeCellsRecord(ranges) {
+	const builder = new RecordBuilder().u16(ranges.length);
+	for (const range of ranges) builder.u16(range.startRow).u16(range.endRow).u16(range.startColumn).u16(range.endColumn);
+	return writeRecord(229, builder.build());
+}
+/** CalcCount's own cIter ([MS-XLS] 2.4.31): "MUST be greater than or equal to one and less than or equal to 32767". Excel's own default iteration limit, and what a real LibreOffice-written BIFF8 carries. */
+const CALC_ITERATION_LIMIT = 100;
+/** CalcDelta's own numDelta ([MS-XLS] 2.4.32): Excel's own default minimum change for iterative calculation to continue. */
+const CALC_ITERATION_DELTA = .001;
+/**
+* The calculation-state records [MS-XLS] 2.1.7.20.6's GLOBALS production requires ahead of PrintRowCol, none of which carries anything document-schema.js models.
+*
+* They are written for two reasons, one of them empirical. The grammar makes them mandatory -- `GLOBALS = CalcMode CalcCount CalcRefMode CalcIter CalcDelta CalcSaveRecalc PrintRowCol PrintGrid GridSet Guts DefaultRowHeight WsBool ...`, with no brackets on any of them -- so a substream that opens straight with a print setting is not a conformant worksheet at all. And LibreOffice's own BIFF8 importer silently discards whichever page-settings record comes FIRST in a worksheet substream: with PrintRowCol in that slot, a `.xls` this writer produced with row and column headers enabled opened in LibreOffice with them off, while every other print setting in the same file came through correctly. Moving any other record into that slot fixes it, which is what these do -- verified by writing the same workbook with and without them and re-reading each through `soffice --convert-to fods`.
+*
+* The values are Excel's own defaults (automatic recalculation, A1 references, iteration off), matching what a real LibreOffice-written file carries for a workbook nobody has changed the calculation settings of. CalcMode is deliberately not among them: the production names it, but LibreOffice does not write one into a worksheet substream either, and the records below already satisfy the constraint this comment exists for.
+*/
+function writeCalculationStateRecords() {
+	return [
+		writeRecord(12, new RecordBuilder().u16(CALC_ITERATION_LIMIT).build()),
+		writeRecord(15, new RecordBuilder().u16(1).build()),
+		writeRecord(17, new RecordBuilder().u16(0).build()),
+		writeRecord(16, new RecordBuilder().f64(CALC_ITERATION_DELTA).build()),
+		writeRecord(95, new RecordBuilder().u16(1).build())
+	];
+}
+/** Setup's own iRes/iVRes ([MS-XLS] 2.4.257), a printer resolution in DPI. 300 is what a real LibreOffice-written BIFF8 carries and a sane default for a writer with no printer to ask; the field is undefined whenever fNoPls is set, which this writer never sets, so it must carry something real. */
+const SETUP_PRINT_RESOLUTION_DPI = 300;
+/** Setup's own iCopies: one copy, the only sensible value for a file that is not being sent to a printer right now. */
+const SETUP_COPIES = 1;
+/** Setup's own numHdr/numFtr ([MS-XLS] 2.4.257), the header and footer margins in inches. Excel's own Normal preset value; Margins has no header/footer field for a real one to come from, and content.ts's read side discards these for the same reason. */
+const SETUP_HEADER_FOOTER_MARGIN_INCHES = .3;
+/** Setup's own iFitWidth/iFitHeight when the sheet is not in fit-to-page mode at all. Written rather than left at 0 because 0 means "as many pages as necessary" -- a real value a reader must not see while fFitToPage is clear and mistake for an intent the sheet never had. */
+const SETUP_INACTIVE_FIT_PAGES = 1;
+/** Setup's own iScale when the sheet IS in fit-to-page mode: 100%, actual size, the inactive value a real producer leaves behind (confirmed against LibreOffice-written BIFF8, whose fit-to-page sheets carry exactly this). */
+const SETUP_INACTIVE_SCALE_PERCENT = 100;
+/** Setup's own iPaperSize for a page size no entry of its code table names: [MS-XLS] 2.4.257's "The value 0, or values greater than or equal to 256, specify custom printer paper sizes." */
+const SETUP_CUSTOM_PAPER_SIZE = 0;
+/** [MS-XLS] 2.4.257's own ceiling on iFitWidth and iFitHeight: "MUST be less than or equal to 32767." */
+const SETUP_MAX_FIT_PAGES = 32767;
+/** iScale is an unsigned 16-bit percentage with no documented ceiling of its own, so the field's own width is the only bound there is. 1 is the floor: 0 is not a scaling factor, and a sub-1% one has no whole-percent spelling. */
+const SETUP_MIN_SCALE_PERCENT = 1;
+const SETUP_MAX_SCALE_PERCENT = 65535;
+/**
+* Clamps a schema value into the range its own Setup field can hold, since `ContentSheetPrintSettings` bounds neither a scale percentage nor a fit-to-page count from above.
+*
+* Clamping rather than throwing, and rather than letting the value wrap: a print scale is a presentational field, and refusing a whole workbook over an absurd one would lose its cells for no gain (the same trade the paper-code case above settles the same way). Silently wrapping is the option neither of those beats -- a scale of 65540% would land in the file as 4%, which is a different intent stated confidently.
+*/
+function clampedSetupField(value, minimum, maximum) {
+	return Math.min(Math.max(Math.round(value), minimum), maximum);
+}
+/**
+* Setup ([MS-XLS] 2.4.257): iPaperSize, iScale, iPageStart, iFitWidth, iFitHeight, the flags word, iRes, iVRes, numHdr, numFtr, iCopies.
+*
+* fNoPls is deliberately never set. It would declare this record's own paper size, scale, and orientation undefined -- exactly the three fields it exists here to carry -- and [MS-XLS] pairs it with a Pls record holding a printer driver's DEVMODE blob, which this writer has none of.
+*
+* A page size no code in the table names is written as SETUP_CUSTOM_PAPER_SIZE rather than as a standard paper it is not. The dimensions themselves are genuinely unwritable -- Setup addresses paper only by code, and [MS-XLS]'s own escape hatch for a size outside the table is that same Pls record -- so the choice is between saying "custom" and saying something false. Saying "custom" is what the spec's own iPaperSize table provides the value for, and it leaves a reader (this package's own included) free to fall back to its documented default instead of confidently reporting Letter for a page that is not Letter. This matters in practice rather than in theory: a spreadsheet converted from a slide deck or a drawing carries that source's own canvas as its page size, which is almost never a named paper, and refusing the conversion outright over a presentational field would lose the cells too.
+*/
+function writeSetupRecord(settings) {
+	const paper = paperSelectionFor(settings.pageSize) ?? {
+		code: SETUP_CUSTOM_PAPER_SIZE,
+		portrait: settings.pageSize.widthPt <= settings.pageSize.heightPt
+	};
+	const fitToPages = settings.fitToPages;
+	const fields = {
+		paperCode: paper.code,
+		scalePercent: fitToPages === void 0 ? clampedSetupField(settings.scalePercent ?? SETUP_INACTIVE_SCALE_PERCENT, SETUP_MIN_SCALE_PERCENT, SETUP_MAX_SCALE_PERCENT) : SETUP_INACTIVE_SCALE_PERCENT,
+		fitWidth: fitToPages === void 0 ? SETUP_INACTIVE_FIT_PAGES : clampedSetupField(fitToPages.width, 1, SETUP_MAX_FIT_PAGES),
+		fitHeight: fitToPages === void 0 ? SETUP_INACTIVE_FIT_PAGES : clampedSetupField(fitToPages.height, 1, SETUP_MAX_FIT_PAGES),
+		leftToRight: settings.pageOrder === "overThenDown",
+		portrait: paper.portrait,
+		noPls: false,
+		noOrientation: false
+	};
+	const data = new RecordBuilder().u16(fields.paperCode).u16(fields.scalePercent).u16(0).u16(fields.fitWidth).u16(fields.fitHeight).u16(packSetupFlags(fields)).u16(SETUP_PRINT_RESOLUTION_DPI).u16(SETUP_PRINT_RESOLUTION_DPI).f64(SETUP_HEADER_FOOTER_MARGIN_INCHES).f64(SETUP_HEADER_FOOTER_MARGIN_INCHES).u16(SETUP_COPIES).build();
+	return writeRecord(161, data);
+}
+/** Any of the four margin records ([MS-XLS] 2.4.151, 2.4.219, 2.4.328, 2.4.27): a single Xnum stating that margin in inches. All four share one field layout, so one writer serves them all -- the mirror of workbook/sheet.ts's own single readMargin. */
+function writeMarginRecord(recordType, points) {
+	return writeRecord(recordType, new RecordBuilder().f64(pointsToInches(points)).build());
+}
+/** PrintGrid ([MS-XLS] 2.4.202) and PrintRowCol ([MS-XLS] 2.4.203), each a single 16-bit boolean. */
+function writeBooleanRecord(recordType, value) {
+	return writeRecord(recordType, new RecordBuilder().u16(value ? 1 : 0).build());
+}
+/** WsBool ([MS-XLS] 2.4.351). Only fFitToPage is set from real data; every other bit is written clear, which is what a sheet with no outline, no dialog behaviour, no synchronised scrolling, and no transition formula handling means -- and is exactly the set of facts ContentSheet carries nothing about. */
+function writeWsBoolRecord(fitToPage) {
+	return writeRecord(129, new RecordBuilder().u16(fitToPage ? 256 : 0).build());
+}
+/**
+* HorizontalPageBreaks ([MS-XLS] 2.4.142) or VerticalPageBreaks ([MS-XLS] 2.4.343): a count then that many six-byte structures, each the break's own index followed by the start and end of its extent along the other axis.
+*
+* Both structures share that three-field shape, so one writer serves both -- the extent's own end differs, which is what `extentEnd` carries: ContentSheetPrintSettings models a break as a whole-axis index with no extent, so every break written here runs the full width or height of BIFF8's own grid. Written in ascending index order, which is the sort [MS-XLS] requires of both arrays; the caller's own indices are sorted first rather than assumed sorted.
+*/
+function writePageBreaksRecord(recordType, indices, extentEnd) {
+	const sorted = [...new Set(indices)].sort((a, b) => a - b);
+	const builder = new RecordBuilder().u16(sorted.length);
+	for (const index of sorted) builder.u16(index).u16(0).u16(extentEnd);
+	return writeRecord(recordType, builder.build());
+}
+/**
+* `manualBreaks.rows`/`.columns` is not bounded to BIFF8's own grid the way a cell's own row/column is (`writeCellRecord`'s `MAX_ROW_INDEX`/`MAX_COLUMN_INDEX` guard above throws for exactly that reason). `writePageBreaksRecord` writes each index into a 16-bit field regardless (`RecordBuilder.u16` masks with `0xffff`), so an out-of-grid break would otherwise silently wrap to a plausible-looking in-grid one -- a break asked for at row 70000 landing at row 4464 -- with nothing downstream to notice.
+*
+* Dropped rather than clamped: unlike a print range or a repeated header band, where clamping to the grid's own last row/column is genuinely what "to the bottom of the sheet" means once the grid shrinks under it (print-names.ts's own clampToGrid), a page break is a single position, and clamping one would insert a break at the grid's own edge the caller never asked for. Dropping states the honest thing an out-of-grid break means once BIFF8's own ceiling has been applied: no such row/column exists for it to sit at.
+*/
+function inGridBreaks(indices, maxIndex) {
+	return indices.filter((index) => index <= maxIndex);
+}
+/**
+* Every print-settings record one sheet needs, in [MS-XLS] 2.1.7.20.6's own order.
+*
+* That order is two productions, back to back, both of which the worksheet substream places ahead of COLUMNS, Dimensions, and the cell table: `GLOBALS = ... PrintRowCol PrintGrid GridSet Guts DefaultRowHeight WsBool [Sync] [LPr] [HorizontalPageBreaks] [VerticalPageBreaks]` and `PAGESETUP = Header Footer HCenter VCenter [LeftMargin] [RightMargin] [TopMargin] [BottomMargin] [Pls *Continue] [Setup]`. The mandatory records this writer does not emit at all (the calculation-state family, GridSet, Guts, DefaultRowHeight, Header/Footer, HCenter/VCenter) are the same UI and interoperability bookkeeping it already omits everywhere else -- see this package's README -- so what remains is the optional subset that actually carries print settings, in the relative order those two productions give it.
+*
+* Every record here is written unconditionally, including for a sheet whose settings are exactly the Normal preset. A print setting has no "absent" spelling in ContentSheetPrintSettings -- gridlines, headers, page order, page size, and all four margins are required fields -- so there is no way to tell a sheet that asked for the preset from one that never stated anything, and writing the values out is what makes the round trip exact either way.
+*/
+function writePrintSettingsRecords(settings) {
+	const pieces = [
+		...writeCalculationStateRecords(),
+		writeBooleanRecord(42, settings.headers),
+		writeBooleanRecord(43, settings.gridlines),
+		writeWsBoolRecord(settings.fitToPages !== void 0)
+	];
+	const breaks = settings.manualBreaks;
+	if (breaks !== void 0) {
+		const rowBreaks = inGridBreaks(breaks.rows, MAX_ROW_INDEX);
+		if (rowBreaks.length > 0) pieces.push(writePageBreaksRecord(27, rowBreaks, MAX_COLUMN_INDEX));
+		const columnBreaks = inGridBreaks(breaks.columns, MAX_COLUMN_INDEX);
+		if (columnBreaks.length > 0) pieces.push(writePageBreaksRecord(26, columnBreaks, MAX_ROW_INDEX));
+	}
+	pieces.push(writeMarginRecord(38, settings.margins.leftPt), writeMarginRecord(39, settings.margins.rightPt), writeMarginRecord(40, settings.margins.topPt), writeMarginRecord(41, settings.margins.bottomPt), writeSetupRecord(settings));
+	return pieces;
+}
+function cellHeader(cell, xfIndex) {
+	return new RecordBuilder().u16(cell.row).u16(cell.column).u16(xfIndex);
+}
+/** One cell record, keyed by ContentCellValue's own discriminant: Number for every numeric/temporal kind ([MS-XLS] 2.4.180 -- always the full IEEE 754 double, never the packed RK encoding, which is a compaction optimisation this writer does not implement), LabelSst for a string ([MS-XLS] 2.4.149, through the workbook-wide shared string table), BoolErr for a boolean or error value ([MS-XLS] 2.4.24), and Blank for an 'empty' cell whose formatting is the only thing it carries ([MS-XLS] 2.4.20 -- a cell header and nothing else, so the XF its ixfe names is the whole content). An unformatted empty cell never reaches here at all: written-cells.ts's own predicate filters it out upstream, since there is nothing for it to say. */
+function writeCellValueRecord(cell, xfIndex, ctx) {
+	const value = cell.value;
+	switch (value.kind) {
+		case "number":
+		case "percentage":
+		case "currency": return writeRecord(515, cellHeader(cell, xfIndex).f64(value.value).build());
+		case "date": return writeRecord(515, cellHeader(cell, xfIndex).f64(isoDateToSerial(value.value, false)).build());
+		case "time": return writeRecord(515, cellHeader(cell, xfIndex).f64(isoTimeToSerial(value.value)).build());
+		case "dateTime": return writeRecord(515, cellHeader(cell, xfIndex).f64(isoDateTimeToSerial(value.value, false)).build());
+		case "string": {
+			const index = ctx.sstIndexFor(value.value);
+			return writeRecord(253, cellHeader(cell, xfIndex).u32(index).build());
+		}
+		case "boolean": return writeRecord(517, cellHeader(cell, xfIndex).u8(value.value ? 1 : 0).u8(0).build());
+		case "error": {
+			const code = errorCodeOf(value.value);
+			if (code === void 0) throw new BiffWriteError(`cell at row ${cell.row}, column ${cell.column} carries error text ${JSON.stringify(value.value)}, which is not one of the eight error values [MS-XLS] 2.5.10 defines`);
+			return writeRecord(517, cellHeader(cell, xfIndex).u8(code).u8(1).build());
+		}
+		case "empty":
+			if (!cellCarriesFormatting(cell)) throw new BiffWriteError(`internal error: writeCellValueRecord was called for the undecorated empty cell at row ${cell.row}, column ${cell.column}, which written-cells.ts's own predicate must filter out before reaching here`);
+			return writeRecord(513, cellHeader(cell, xfIndex).build());
+	}
+}
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, EOF. */
+function buildWorksheetSubstream(sheet, ctx) {
+	for (const cell of sheet.cells) checkedCellPosition(cell);
+	const writtenCells = sheet.cells.filter(writesCellRecord);
+	const cellsByRow = /* @__PURE__ */ new Map();
+	for (const cell of writtenCells) {
+		const existing = cellsByRow.get(cell.row);
+		if (existing === void 0) cellsByRow.set(cell.row, [cell]);
+		else existing.push(cell);
+	}
+	for (const cells of cellsByRow.values()) cells.sort((a, b) => a.column - b.column);
+	const declaredRows = new Map(sheet.rows.map((row) => [row.index, row]));
+	const sortedRowIndices = [.../* @__PURE__ */ new Set([...cellsByRow.keys(), ...declaredRows.keys()])].sort((a, b) => a - b);
+	const pieces = [
+		writeRecord(RECORD_BOF, writeBofData(16)),
+		...writePrintSettingsRecords(sheet.printSettings),
+		writeDimensionsRecord(writtenCells)
+	];
+	for (const column of sheet.columns) pieces.push(writeColInfoRecord(column));
+	for (const rowIndex of sortedRowIndices) {
+		const cellsInRow = cellsByRow.get(rowIndex) ?? [];
+		pieces.push(writeRowRecord(rowIndex, cellsInRow, declaredRows.get(rowIndex)));
+		for (const cell of cellsInRow) {
+			const xfIndex = ctx.xfIndexForCell(cell);
+			pieces.push(writeCellValueRecord(cell, xfIndex, ctx));
+		}
+	}
+	const merges = mergedRangesOf(sheet.cells);
+	if (merges.length > 0) pieces.push(writeMergeCellsRecord(merges));
+	pieces.push(writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
+	return concatRecords(...pieces);
+}
+//#endregion
+export { buildWorksheetSubstream };