xls-codec 1.0.2 → 2.0.1

package/dist/write.cjs

@@ -0,0 +1,311 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_container = require("./container.cjs");
+const require_biff_xf_colors = require("./biff/xf-colors.cjs");
+const require_biff_write_errors = require("./biff/write-errors.cjs");
+const require_workbook_print_names = require("./workbook/print-names.cjs");
+const require_metadata = require("./metadata.cjs");
+const require_workbook_globals_writer = require("./workbook/globals-writer.cjs");
+const require_written_cells = require("./written-cells.cjs");
+const require_workbook_sheet_writer = require("./workbook/sheet-writer.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/write.ts
+const WORKBOOK_STREAM_NAME = "Workbook";
+/** [MS-XLS] 2.4.126: a Format record's own ifmt is constrained to the ranges 5-8, 23-26, 41-44, 63-66, and 164-382 for a custom (non-built-in) code; 164 is the first identifier every real producer actually uses for a custom code, and this writer follows suit, incrementing sequentially and refusing to exceed the range's own ceiling. */
+const FIRST_CUSTOM_FORMAT_ID = 164;
+const LAST_CUSTOM_FORMAT_ID = 382;
+const BUILTIN_FORMAT_PERCENTAGE = 9;
+const BUILTIN_FORMAT_CURRENCY = 44;
+const BUILTIN_FORMAT_DATE = 14;
+const BUILTIN_FORMAT_TIME = 21;
+const BUILTIN_FORMAT_DATE_TIME = 22;
+const GENERAL_FORMAT_ID = 0;
+function builtinCode(id) {
+	const code = excel_number_format.BUILTIN_NUMBER_FORMATS.get(id);
+	if (code === void 0) throw new require_biff_write_errors.BiffWriteError(`internal error: BUILTIN_NUMBER_FORMATS has no entry for id ${id}`);
+	return code;
+}
+/** The default format identifier a value kind resolves to when its own cell carries no numberFormatCode -- chosen so excel-number-format's classifyNumberFormat, run against the resulting code on the way back in, reclassifies to the identical kind. A plain number/string/boolean/error needs no distinguishing code at all: General classifies as 'number', which is exactly the fallback content.ts's own resolveValue already takes for a numeric cell with no format. */
+function defaultFormatIdForKind(kind) {
+	switch (kind) {
+		case "percentage": return BUILTIN_FORMAT_PERCENTAGE;
+		case "currency": return BUILTIN_FORMAT_CURRENCY;
+		case "date": return BUILTIN_FORMAT_DATE;
+		case "time": return BUILTIN_FORMAT_TIME;
+		case "dateTime": return BUILTIN_FORMAT_DATE_TIME;
+		case "number":
+		case "string":
+		case "boolean":
+		case "error":
+		case "empty": return GENERAL_FORMAT_ID;
+	}
+}
+/** The number-format code a cell resolves through -- its own explicit numberFormatCode, or the built-in code for its value kind's own default identifier. This is called identically during the workbook-wide format scan and later per cell, so the two can never resolve a cell to different codes. */
+function formatCodeForCell(cell) {
+	return cell.numberFormatCode ?? builtinCode(defaultFormatIdForKind(cell.value.kind));
+}
+/** Scans every sheet's cells once, assigning each distinct number-format code a formatId: reusing a built-in id for a code matching one of excel-number-format's own BUILTIN_NUMBER_FORMATS strings exactly, minting a new custom id from FIRST_CUSTOM_FORMAT_ID otherwise. Cell XF index assignment is a separate, later pass (buildCellXfPlan below) -- a formatId alone no longer determines a cell's XF index once decoration exists, since two cells sharing a format but differing in background/borders need two distinct XFs. */
+function buildFormatPlan(sheets) {
+	const codeToFormatId = /* @__PURE__ */ new Map();
+	const builtinIdByCode = new Map(Array.from(excel_number_format.BUILTIN_NUMBER_FORMATS, ([id, code]) => [code, id]));
+	const customFormats = [];
+	let nextCustomId = FIRST_CUSTOM_FORMAT_ID;
+	const resolve = (code) => {
+		const existing = codeToFormatId.get(code);
+		if (existing !== void 0) return existing;
+		const builtinId = builtinIdByCode.get(code);
+		let formatId;
+		if (builtinId !== void 0) formatId = builtinId;
+		else {
+			if (nextCustomId > LAST_CUSTOM_FORMAT_ID) throw new require_biff_write_errors.BiffWriteError(`workbook needs more than 219 distinct custom number formats, more than [MS-XLS] 2.4.126's own ${FIRST_CUSTOM_FORMAT_ID}-${LAST_CUSTOM_FORMAT_ID} custom-identifier range allows`);
+			formatId = nextCustomId;
+			nextCustomId += 1;
+			customFormats.push({
+				id: formatId,
+				code
+			});
+		}
+		codeToFormatId.set(code, formatId);
+		return formatId;
+	};
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (!require_written_cells.writesCellRecord(cell)) continue;
+		resolve(formatCodeForCell(cell));
+	}
+	return {
+		customFormats,
+		formatIdOf: (code) => {
+			const id = codeToFormatId.get(code);
+			if (id === void 0) throw new require_biff_write_errors.BiffWriteError(`internal error: number-format code ${JSON.stringify(code)} was not registered during the workbook-wide format scan`);
+			return id;
+		}
+	};
+}
+/** Scans every sheet's cells once for the distinct fill/border colours the workbook actually uses (background, and each present border side's own colour), then decides whether they all already have a home in the fixed default table (no Palette record needed) or whether at least one genuinely custom colour forces a real one -- in which case every distinct colour, not just the non-default ones, is allocated its own dedicated slot, so the whole 56-entry table is self-consistent and every reference resolves through it rather than a mix of "the file's own table" and "the implicit default". */
+function buildPalettePlan(sheets) {
+	const colorByHex = /* @__PURE__ */ new Map();
+	const record = (color) => {
+		if (color === void 0) return;
+		const hex = (0, document_schema_js.colorToRgbHex)(color);
+		if (!colorByHex.has(hex)) colorByHex.set(hex, color);
+	};
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (!require_written_cells.writesCellRecord(cell)) continue;
+		record(cell.background);
+		record(cell.borders?.left?.color);
+		record(cell.borders?.right?.color);
+		record(cell.borders?.top?.color);
+		record(cell.borders?.bottom?.color);
+	}
+	const missing = (hex) => {
+		throw new require_biff_write_errors.BiffWriteError(`internal error: colour ${hex} was not registered during the workbook-wide palette scan`);
+	};
+	if (colorByHex.size === 0) return {
+		paletteColors: void 0,
+		icvOf: (color) => missing((0, document_schema_js.colorToRgbHex)(color))
+	};
+	const defaultIcvByHex = /* @__PURE__ */ new Map();
+	let needsCustomPalette = false;
+	for (const hex of colorByHex.keys()) {
+		const icv = require_biff_xf_colors.DEFAULT_PALETTE_HEX_TO_ICV.get(hex);
+		if (icv === void 0) {
+			needsCustomPalette = true;
+			break;
+		}
+		defaultIcvByHex.set(hex, icv);
+	}
+	if (!needsCustomPalette) return {
+		paletteColors: void 0,
+		icvOf: (color) => defaultIcvByHex.get((0, document_schema_js.colorToRgbHex)(color)) ?? missing((0, document_schema_js.colorToRgbHex)(color))
+	};
+	if (colorByHex.size > 56) throw new require_biff_write_errors.BiffWriteError(`workbook needs ${colorByHex.size} distinct decoration colours, more than the 56 entries [MS-XLS] 2.4.188's own Palette record can hold`);
+	const icvByHex = /* @__PURE__ */ new Map();
+	const paletteColors = [];
+	let nextIcv = 8;
+	for (const [hex, color] of colorByHex) {
+		icvByHex.set(hex, nextIcv);
+		paletteColors.push(color);
+		nextIcv += 1;
+	}
+	while (paletteColors.length < 56) paletteColors.push({
+		r: 0,
+		g: 0,
+		b: 0
+	});
+	return {
+		paletteColors,
+		icvOf: (color) => icvByHex.get((0, document_schema_js.colorToRgbHex)(color)) ?? missing((0, document_schema_js.colorToRgbHex)(color))
+	};
+}
+const UNDECORATED_EDGE = {
+	style: 0,
+	icv: 0
+};
+function resolveWriteEdge(border, icvOf) {
+	if (border === void 0) return UNDECORATED_EDGE;
+	return {
+		style: require_biff_xf_colors.borderStyleTokenFor(border),
+		icv: icvOf(border.color)
+	};
+}
+/** A cell's own decoration, resolved into the raw XfDecorationFields the CellXF payload packs -- undefined for a cell with neither a background nor any border, so it shares the workbook's plain undecorated XF exactly as it did before decoration existed. The "has decoration at all" question is written-cells.ts's, since the writer's own record-emission predicate turns on the identical answer. */
+function resolveDecorationForCell(cell, icvOf) {
+	if (!require_written_cells.cellCarriesFormatting(cell)) return;
+	return {
+		fillPattern: cell.background === void 0 ? 0 : 1,
+		fillForegroundIcv: cell.background === void 0 ? 64 : icvOf(cell.background),
+		left: resolveWriteEdge(cell.borders?.left, icvOf),
+		right: resolveWriteEdge(cell.borders?.right, icvOf),
+		top: resolveWriteEdge(cell.borders?.top, icvOf),
+		bottom: resolveWriteEdge(cell.borders?.bottom, icvOf)
+	};
+}
+/** A deterministic signature for one cell XF's own (formatId, alignment, verticalAlignment, decoration) tuple, so two cells sharing all four share one XF record -- the interning key buildCellXfPlan below dedupes on, mirroring how CellFormatTable in ooxml.js's typed/xlsx/styles.ts dedupes an <xf> on (number format, decoration) together rather than on format alone, widened here by the cell's own alignment. */
+function signatureOfCellXf(formatId, alignment, verticalAlignment, decoration) {
+	let signature = `f${formatId}|a${alignment ?? ""}|v${verticalAlignment ?? ""}`;
+	if (decoration === void 0) return signature;
+	signature += `|p${decoration.fillPattern}:${decoration.fillForegroundIcv}|l${decoration.left.style}:${decoration.left.icv}|r${decoration.right.style}:${decoration.right.icv}|t${decoration.top.style}:${decoration.top.icv}|b${decoration.bottom.style}:${decoration.bottom.icv}`;
+	return signature;
+}
+/**
+* Scans every sheet's cells once, interning each distinct (number format, decoration) combination into its own cell XF index -- a cell with General formatting and no decoration resolves to the workbook's own implicit GENERAL_CELL_XF_INDEX with no new XF record at all, exactly as before; every other combination mints one XF record the first time it is seen and is reused by every later cell sharing it.
+*
+* The returned xfIndexForCell only ever LOOKS UP -- it cannot mint an entry, and refuses a signature this scan never saw. buildWorkbookGlobals is handed cellXfEntries before any sheet's records are built, so an entry minted later than this scan would be one no XF record was written for, and the cell record naming its index would point past the end of the workbook's XF table. Nothing about the resulting bytes says so: a reader resolves that index to whatever XF happens to sit there, or to none, and the cell's format is silently wrong either way. Refusing the lookup is the only place that divergence can still be caught.
+*/
+function buildCellXfPlan(sheets, formatPlan, palettePlan) {
+	const cellXfEntries = [];
+	const xfIndexBySignature = /* @__PURE__ */ new Map([[signatureOfCellXf(GENERAL_FORMAT_ID, void 0, void 0, void 0), require_workbook_globals_writer.GENERAL_CELL_XF_INDEX]]);
+	let nextXfIndex = require_workbook_globals_writer.GENERAL_CELL_XF_INDEX + 1;
+	const signatureOf = (cell) => signatureOfCellXf(formatPlan.formatIdOf(formatCodeForCell(cell)), cell.alignment, cell.verticalAlignment, resolveDecorationForCell(cell, palettePlan.icvOf));
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (!require_written_cells.writesCellRecord(cell)) continue;
+		const formatId = formatPlan.formatIdOf(formatCodeForCell(cell));
+		const decoration = resolveDecorationForCell(cell, palettePlan.icvOf);
+		const signature = signatureOfCellXf(formatId, cell.alignment, cell.verticalAlignment, decoration);
+		if (xfIndexBySignature.has(signature)) continue;
+		xfIndexBySignature.set(signature, nextXfIndex);
+		nextXfIndex += 1;
+		cellXfEntries.push({
+			formatId,
+			alignment: cell.alignment,
+			verticalAlignment: cell.verticalAlignment,
+			decoration
+		});
+	}
+	return {
+		cellXfEntries,
+		xfIndexForCell: (cell) => {
+			const signature = signatureOf(cell);
+			const index = xfIndexBySignature.get(signature);
+			if (index === void 0) throw new require_biff_write_errors.BiffWriteError(`internal error: the cell at row ${cell.row}, column ${cell.column} resolves to cell-XF signature ${JSON.stringify(signature)}, which the workbook-wide cell-format scan never saw -- the writer's own "does this cell get a record" predicate and its XF-interning pass disagree about this cell`);
+			return index;
+		}
+	};
+}
+/** Scans every sheet's string-kind cells once, in sheet then cell order, assigning each distinct value the shared string table index every LabelSst cell referencing it uses. */
+function buildSstPlan(sheets) {
+	const indexOf = /* @__PURE__ */ new Map();
+	const strings = [];
+	let totalCount = 0;
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (cell.value.kind !== "string") continue;
+		totalCount += 1;
+		if (!indexOf.has(cell.value.value)) {
+			indexOf.set(cell.value.value, strings.length);
+			strings.push(cell.value.value);
+		}
+	}
+	return {
+		strings,
+		totalCount,
+		indexOf: (text) => {
+			const index = indexOf.get(text);
+			if (index === void 0) throw new require_biff_write_errors.BiffWriteError(`internal error: string ${JSON.stringify(text)} was not registered during the workbook-wide shared-string scan`);
+			return index;
+		}
+	};
+}
+/**
+* The built-in Print_Area/Print_Titles defined names every sheet's own print settings need, across the whole workbook.
+*
+* Workbook-wide rather than per-sheet because that is where BIFF8 puts them: an Lbl lives in the globals substream and names its sheet through its own itab, so a sheet's print RANGE is written nowhere near the sheet's own records. The ixti each name's PtgArea3d refers to is the sheet's own index, matching the one-XTI-per-sheet ExternSheet record globals-writer.ts writes alongside them.
+*/
+function buildPrintNamePlan(sheets) {
+	return sheets.flatMap((sheet, sheetIndex) => require_workbook_print_names.printNameEntriesFor(sheetIndex, sheetIndex, sheet.printSettings));
+}
+/** Patches a BoundSheet8's own lbPlyPos field in place: a 4-byte little-endian integer at a byte offset globals-writer.ts already reported, once the real value -- where that sheet's own substream landed in the finished workbook stream -- is known. */
+function patchBoundSheetOffsets(globalsBytes, offsets, values) {
+	const view = new DataView(globalsBytes.buffer, globalsBytes.byteOffset, globalsBytes.byteLength);
+	offsets.forEach((offset, index) => {
+		view.setUint32(offset, values[index] ?? 0, true);
+	});
+}
+function concatBytes(parts) {
+	const total = parts.reduce((sum, part) => sum + part.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+/** Builds the [MS-XLS] Workbook stream: the globals substream followed by one worksheet substream per sheet, with every BoundSheet8's own lbPlyPos patched to the real byte offset its sheet's substream landed at. */
+function buildWorkbookStream(content) {
+	if (content.sheets.length === 0) throw new require_biff_write_errors.BiffWriteError("a .xls workbook must contain at least one sheet ([MS-XLS] 2.1.7.20.3's own BUNDLESHEET production requires 1*BoundSheet8), but the document being written has none");
+	const formatPlan = buildFormatPlan(content.sheets);
+	const sstPlan = buildSstPlan(content.sheets);
+	const palettePlan = buildPalettePlan(content.sheets);
+	const cellXfPlan = buildCellXfPlan(content.sheets, formatPlan, palettePlan);
+	const globalsPlan = {
+		sheetNames: content.sheets.map((sheet) => sheet.name),
+		customFormats: formatPlan.customFormats,
+		cellXfEntries: cellXfPlan.cellXfEntries,
+		sharedStrings: sstPlan.strings,
+		sharedStringTotalCount: sstPlan.totalCount,
+		paletteColors: palettePlan.paletteColors,
+		printNames: buildPrintNamePlan(content.sheets)
+	};
+	const globals = require_workbook_globals_writer.buildWorkbookGlobals(globalsPlan);
+	const sheetContext = {
+		xfIndexForCell: cellXfPlan.xfIndexForCell,
+		sstIndexFor: (text) => sstPlan.indexOf(text)
+	};
+	const sheetStreams = content.sheets.map((sheet) => require_workbook_sheet_writer.buildWorksheetSubstream(sheet, sheetContext));
+	const sheetOffsets = [];
+	let offset = globals.bytes.length;
+	for (const stream of sheetStreams) {
+		sheetOffsets.push(offset);
+		offset += stream.length;
+	}
+	const globalsBytes = globals.bytes.slice();
+	patchBoundSheetOffsets(globalsBytes, globals.lbPlyPosOffsets, sheetOffsets);
+	return concatBytes([globalsBytes, ...sheetStreams]);
+}
+/**
+* Writes a spreadsheet ContentDocument to real .xls bytes: a BIFF8 Workbook stream wrapped in an [MS-CFB] compound file.
+*
+* The counterpart of content.ts's readXlsContent. See this package's README for the writer's full scope.
+*/
+function writeXlsContent(content) {
+	const stream = buildWorkbookStream(content);
+	const streams = [{
+		path: WORKBOOK_STREAM_NAME,
+		bytes: stream
+	}];
+	if ((0, archive_codec.hasSummaryInformationFields)(content.metadata)) streams.push({
+		path: require_container.SUMMARY_INFORMATION_STREAM,
+		bytes: (0, archive_codec.writeSummaryInformationStream)(require_metadata.layoutMetadataToSummaryInformation(content.metadata))
+	});
+	return (0, archive_codec.writeCompoundFile)(streams);
+}
+/** Writes a DocumentTree of kind 'spreadsheet' to real .xls bytes, flattening it to a ContentDocument first -- the counterpart of content.ts's readXls. */
+function writeXls(tree) {
+	const content = (0, document_schema_js.flattenTree)(tree);
+	if (content.kind !== "spreadsheet") throw new require_biff_write_errors.BiffWriteError(`writeXls was given a DocumentTree of kind '${content.kind}', but a .xls workbook can only be written from a 'spreadsheet' document`);
+	return writeXlsContent(content);
+}
+//#endregion
+exports.writeXls = writeXls;
+exports.writeXlsContent = writeXlsContent;

package/dist/write.d.cts

@@ -0,0 +1,13 @@
+import { XlsContentDocument } from "./content.cjs";
+import { DocumentTree } from "document-schema.js";
+//#region src/write.d.ts
+/**
+ * Writes a spreadsheet ContentDocument to real .xls bytes: a BIFF8 Workbook stream wrapped in an [MS-CFB] compound file.
+ *
+ * The counterpart of content.ts's readXlsContent. See this package's README for the writer's full scope.
+ */
+declare function writeXlsContent(content: XlsContentDocument): Uint8Array<ArrayBuffer>;
+/** Writes a DocumentTree of kind 'spreadsheet' to real .xls bytes, flattening it to a ContentDocument first -- the counterpart of content.ts's readXls. */
+declare function writeXls(tree: DocumentTree): Uint8Array<ArrayBuffer>;
+//#endregion
+export { writeXls, writeXlsContent };

package/dist/write.d.ts

@@ -0,0 +1,13 @@
+import { XlsContentDocument } from "./content.js";
+import { DocumentTree } from "document-schema.js";
+//#region src/write.d.ts
+/**
+ * Writes a spreadsheet ContentDocument to real .xls bytes: a BIFF8 Workbook stream wrapped in an [MS-CFB] compound file.
+ *
+ * The counterpart of content.ts's readXlsContent. See this package's README for the writer's full scope.
+ */
+declare function writeXlsContent(content: XlsContentDocument): Uint8Array<ArrayBuffer>;
+/** Writes a DocumentTree of kind 'spreadsheet' to real .xls bytes, flattening it to a ContentDocument first -- the counterpart of content.ts's readXls. */
+declare function writeXls(tree: DocumentTree): Uint8Array<ArrayBuffer>;
+//#endregion
+export { writeXls, writeXlsContent };

package/dist/write.js

@@ -0,0 +1,309 @@
+import { SUMMARY_INFORMATION_STREAM } from "./container.js";
+import { DEFAULT_PALETTE_HEX_TO_ICV, borderStyleTokenFor } from "./biff/xf-colors.js";
+import { BiffWriteError } from "./biff/write-errors.js";
+import { printNameEntriesFor } from "./workbook/print-names.js";
+import { layoutMetadataToSummaryInformation as layoutMetadataToSummaryInformation$1 } from "./metadata.js";
+import { GENERAL_CELL_XF_INDEX, buildWorkbookGlobals } from "./workbook/globals-writer.js";
+import { cellCarriesFormatting, writesCellRecord } from "./written-cells.js";
+import { buildWorksheetSubstream } from "./workbook/sheet-writer.js";
+import { hasSummaryInformationFields, writeCompoundFile, writeSummaryInformationStream } from "archive-codec";
+import { colorToRgbHex, flattenTree } from "document-schema.js";
+import { BUILTIN_NUMBER_FORMATS } from "excel-number-format";
+//#region src/write.ts
+const WORKBOOK_STREAM_NAME = "Workbook";
+/** [MS-XLS] 2.4.126: a Format record's own ifmt is constrained to the ranges 5-8, 23-26, 41-44, 63-66, and 164-382 for a custom (non-built-in) code; 164 is the first identifier every real producer actually uses for a custom code, and this writer follows suit, incrementing sequentially and refusing to exceed the range's own ceiling. */
+const FIRST_CUSTOM_FORMAT_ID = 164;
+const LAST_CUSTOM_FORMAT_ID = 382;
+const BUILTIN_FORMAT_PERCENTAGE = 9;
+const BUILTIN_FORMAT_CURRENCY = 44;
+const BUILTIN_FORMAT_DATE = 14;
+const BUILTIN_FORMAT_TIME = 21;
+const BUILTIN_FORMAT_DATE_TIME = 22;
+const GENERAL_FORMAT_ID = 0;
+function builtinCode(id) {
+	const code = BUILTIN_NUMBER_FORMATS.get(id);
+	if (code === void 0) throw new BiffWriteError(`internal error: BUILTIN_NUMBER_FORMATS has no entry for id ${id}`);
+	return code;
+}
+/** The default format identifier a value kind resolves to when its own cell carries no numberFormatCode -- chosen so excel-number-format's classifyNumberFormat, run against the resulting code on the way back in, reclassifies to the identical kind. A plain number/string/boolean/error needs no distinguishing code at all: General classifies as 'number', which is exactly the fallback content.ts's own resolveValue already takes for a numeric cell with no format. */
+function defaultFormatIdForKind(kind) {
+	switch (kind) {
+		case "percentage": return BUILTIN_FORMAT_PERCENTAGE;
+		case "currency": return BUILTIN_FORMAT_CURRENCY;
+		case "date": return BUILTIN_FORMAT_DATE;
+		case "time": return BUILTIN_FORMAT_TIME;
+		case "dateTime": return BUILTIN_FORMAT_DATE_TIME;
+		case "number":
+		case "string":
+		case "boolean":
+		case "error":
+		case "empty": return GENERAL_FORMAT_ID;
+	}
+}
+/** The number-format code a cell resolves through -- its own explicit numberFormatCode, or the built-in code for its value kind's own default identifier. This is called identically during the workbook-wide format scan and later per cell, so the two can never resolve a cell to different codes. */
+function formatCodeForCell(cell) {
+	return cell.numberFormatCode ?? builtinCode(defaultFormatIdForKind(cell.value.kind));
+}
+/** Scans every sheet's cells once, assigning each distinct number-format code a formatId: reusing a built-in id for a code matching one of excel-number-format's own BUILTIN_NUMBER_FORMATS strings exactly, minting a new custom id from FIRST_CUSTOM_FORMAT_ID otherwise. Cell XF index assignment is a separate, later pass (buildCellXfPlan below) -- a formatId alone no longer determines a cell's XF index once decoration exists, since two cells sharing a format but differing in background/borders need two distinct XFs. */
+function buildFormatPlan(sheets) {
+	const codeToFormatId = /* @__PURE__ */ new Map();
+	const builtinIdByCode = new Map(Array.from(BUILTIN_NUMBER_FORMATS, ([id, code]) => [code, id]));
+	const customFormats = [];
+	let nextCustomId = FIRST_CUSTOM_FORMAT_ID;
+	const resolve = (code) => {
+		const existing = codeToFormatId.get(code);
+		if (existing !== void 0) return existing;
+		const builtinId = builtinIdByCode.get(code);
+		let formatId;
+		if (builtinId !== void 0) formatId = builtinId;
+		else {
+			if (nextCustomId > LAST_CUSTOM_FORMAT_ID) throw new BiffWriteError(`workbook needs more than 219 distinct custom number formats, more than [MS-XLS] 2.4.126's own ${FIRST_CUSTOM_FORMAT_ID}-${LAST_CUSTOM_FORMAT_ID} custom-identifier range allows`);
+			formatId = nextCustomId;
+			nextCustomId += 1;
+			customFormats.push({
+				id: formatId,
+				code
+			});
+		}
+		codeToFormatId.set(code, formatId);
+		return formatId;
+	};
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (!writesCellRecord(cell)) continue;
+		resolve(formatCodeForCell(cell));
+	}
+	return {
+		customFormats,
+		formatIdOf: (code) => {
+			const id = codeToFormatId.get(code);
+			if (id === void 0) throw new BiffWriteError(`internal error: number-format code ${JSON.stringify(code)} was not registered during the workbook-wide format scan`);
+			return id;
+		}
+	};
+}
+/** Scans every sheet's cells once for the distinct fill/border colours the workbook actually uses (background, and each present border side's own colour), then decides whether they all already have a home in the fixed default table (no Palette record needed) or whether at least one genuinely custom colour forces a real one -- in which case every distinct colour, not just the non-default ones, is allocated its own dedicated slot, so the whole 56-entry table is self-consistent and every reference resolves through it rather than a mix of "the file's own table" and "the implicit default". */
+function buildPalettePlan(sheets) {
+	const colorByHex = /* @__PURE__ */ new Map();
+	const record = (color) => {
+		if (color === void 0) return;
+		const hex = colorToRgbHex(color);
+		if (!colorByHex.has(hex)) colorByHex.set(hex, color);
+	};
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (!writesCellRecord(cell)) continue;
+		record(cell.background);
+		record(cell.borders?.left?.color);
+		record(cell.borders?.right?.color);
+		record(cell.borders?.top?.color);
+		record(cell.borders?.bottom?.color);
+	}
+	const missing = (hex) => {
+		throw new BiffWriteError(`internal error: colour ${hex} was not registered during the workbook-wide palette scan`);
+	};
+	if (colorByHex.size === 0) return {
+		paletteColors: void 0,
+		icvOf: (color) => missing(colorToRgbHex(color))
+	};
+	const defaultIcvByHex = /* @__PURE__ */ new Map();
+	let needsCustomPalette = false;
+	for (const hex of colorByHex.keys()) {
+		const icv = DEFAULT_PALETTE_HEX_TO_ICV.get(hex);
+		if (icv === void 0) {
+			needsCustomPalette = true;
+			break;
+		}
+		defaultIcvByHex.set(hex, icv);
+	}
+	if (!needsCustomPalette) return {
+		paletteColors: void 0,
+		icvOf: (color) => defaultIcvByHex.get(colorToRgbHex(color)) ?? missing(colorToRgbHex(color))
+	};
+	if (colorByHex.size > 56) throw new BiffWriteError(`workbook needs ${colorByHex.size} distinct decoration colours, more than the 56 entries [MS-XLS] 2.4.188's own Palette record can hold`);
+	const icvByHex = /* @__PURE__ */ new Map();
+	const paletteColors = [];
+	let nextIcv = 8;
+	for (const [hex, color] of colorByHex) {
+		icvByHex.set(hex, nextIcv);
+		paletteColors.push(color);
+		nextIcv += 1;
+	}
+	while (paletteColors.length < 56) paletteColors.push({
+		r: 0,
+		g: 0,
+		b: 0
+	});
+	return {
+		paletteColors,
+		icvOf: (color) => icvByHex.get(colorToRgbHex(color)) ?? missing(colorToRgbHex(color))
+	};
+}
+const UNDECORATED_EDGE = {
+	style: 0,
+	icv: 0
+};
+function resolveWriteEdge(border, icvOf) {
+	if (border === void 0) return UNDECORATED_EDGE;
+	return {
+		style: borderStyleTokenFor(border),
+		icv: icvOf(border.color)
+	};
+}
+/** A cell's own decoration, resolved into the raw XfDecorationFields the CellXF payload packs -- undefined for a cell with neither a background nor any border, so it shares the workbook's plain undecorated XF exactly as it did before decoration existed. The "has decoration at all" question is written-cells.ts's, since the writer's own record-emission predicate turns on the identical answer. */
+function resolveDecorationForCell(cell, icvOf) {
+	if (!cellCarriesFormatting(cell)) return;
+	return {
+		fillPattern: cell.background === void 0 ? 0 : 1,
+		fillForegroundIcv: cell.background === void 0 ? 64 : icvOf(cell.background),
+		left: resolveWriteEdge(cell.borders?.left, icvOf),
+		right: resolveWriteEdge(cell.borders?.right, icvOf),
+		top: resolveWriteEdge(cell.borders?.top, icvOf),
+		bottom: resolveWriteEdge(cell.borders?.bottom, icvOf)
+	};
+}
+/** A deterministic signature for one cell XF's own (formatId, alignment, verticalAlignment, decoration) tuple, so two cells sharing all four share one XF record -- the interning key buildCellXfPlan below dedupes on, mirroring how CellFormatTable in ooxml.js's typed/xlsx/styles.ts dedupes an <xf> on (number format, decoration) together rather than on format alone, widened here by the cell's own alignment. */
+function signatureOfCellXf(formatId, alignment, verticalAlignment, decoration) {
+	let signature = `f${formatId}|a${alignment ?? ""}|v${verticalAlignment ?? ""}`;
+	if (decoration === void 0) return signature;
+	signature += `|p${decoration.fillPattern}:${decoration.fillForegroundIcv}|l${decoration.left.style}:${decoration.left.icv}|r${decoration.right.style}:${decoration.right.icv}|t${decoration.top.style}:${decoration.top.icv}|b${decoration.bottom.style}:${decoration.bottom.icv}`;
+	return signature;
+}
+/**
+* Scans every sheet's cells once, interning each distinct (number format, decoration) combination into its own cell XF index -- a cell with General formatting and no decoration resolves to the workbook's own implicit GENERAL_CELL_XF_INDEX with no new XF record at all, exactly as before; every other combination mints one XF record the first time it is seen and is reused by every later cell sharing it.
+*
+* The returned xfIndexForCell only ever LOOKS UP -- it cannot mint an entry, and refuses a signature this scan never saw. buildWorkbookGlobals is handed cellXfEntries before any sheet's records are built, so an entry minted later than this scan would be one no XF record was written for, and the cell record naming its index would point past the end of the workbook's XF table. Nothing about the resulting bytes says so: a reader resolves that index to whatever XF happens to sit there, or to none, and the cell's format is silently wrong either way. Refusing the lookup is the only place that divergence can still be caught.
+*/
+function buildCellXfPlan(sheets, formatPlan, palettePlan) {
+	const cellXfEntries = [];
+	const xfIndexBySignature = /* @__PURE__ */ new Map([[signatureOfCellXf(GENERAL_FORMAT_ID, void 0, void 0, void 0), GENERAL_CELL_XF_INDEX]]);
+	let nextXfIndex = GENERAL_CELL_XF_INDEX + 1;
+	const signatureOf = (cell) => signatureOfCellXf(formatPlan.formatIdOf(formatCodeForCell(cell)), cell.alignment, cell.verticalAlignment, resolveDecorationForCell(cell, palettePlan.icvOf));
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (!writesCellRecord(cell)) continue;
+		const formatId = formatPlan.formatIdOf(formatCodeForCell(cell));
+		const decoration = resolveDecorationForCell(cell, palettePlan.icvOf);
+		const signature = signatureOfCellXf(formatId, cell.alignment, cell.verticalAlignment, decoration);
+		if (xfIndexBySignature.has(signature)) continue;
+		xfIndexBySignature.set(signature, nextXfIndex);
+		nextXfIndex += 1;
+		cellXfEntries.push({
+			formatId,
+			alignment: cell.alignment,
+			verticalAlignment: cell.verticalAlignment,
+			decoration
+		});
+	}
+	return {
+		cellXfEntries,
+		xfIndexForCell: (cell) => {
+			const signature = signatureOf(cell);
+			const index = xfIndexBySignature.get(signature);
+			if (index === void 0) throw new BiffWriteError(`internal error: the cell at row ${cell.row}, column ${cell.column} resolves to cell-XF signature ${JSON.stringify(signature)}, which the workbook-wide cell-format scan never saw -- the writer's own "does this cell get a record" predicate and its XF-interning pass disagree about this cell`);
+			return index;
+		}
+	};
+}
+/** Scans every sheet's string-kind cells once, in sheet then cell order, assigning each distinct value the shared string table index every LabelSst cell referencing it uses. */
+function buildSstPlan(sheets) {
+	const indexOf = /* @__PURE__ */ new Map();
+	const strings = [];
+	let totalCount = 0;
+	for (const sheet of sheets) for (const cell of sheet.cells) {
+		if (cell.value.kind !== "string") continue;
+		totalCount += 1;
+		if (!indexOf.has(cell.value.value)) {
+			indexOf.set(cell.value.value, strings.length);
+			strings.push(cell.value.value);
+		}
+	}
+	return {
+		strings,
+		totalCount,
+		indexOf: (text) => {
+			const index = indexOf.get(text);
+			if (index === void 0) throw new BiffWriteError(`internal error: string ${JSON.stringify(text)} was not registered during the workbook-wide shared-string scan`);
+			return index;
+		}
+	};
+}
+/**
+* The built-in Print_Area/Print_Titles defined names every sheet's own print settings need, across the whole workbook.
+*
+* Workbook-wide rather than per-sheet because that is where BIFF8 puts them: an Lbl lives in the globals substream and names its sheet through its own itab, so a sheet's print RANGE is written nowhere near the sheet's own records. The ixti each name's PtgArea3d refers to is the sheet's own index, matching the one-XTI-per-sheet ExternSheet record globals-writer.ts writes alongside them.
+*/
+function buildPrintNamePlan(sheets) {
+	return sheets.flatMap((sheet, sheetIndex) => printNameEntriesFor(sheetIndex, sheetIndex, sheet.printSettings));
+}
+/** Patches a BoundSheet8's own lbPlyPos field in place: a 4-byte little-endian integer at a byte offset globals-writer.ts already reported, once the real value -- where that sheet's own substream landed in the finished workbook stream -- is known. */
+function patchBoundSheetOffsets(globalsBytes, offsets, values) {
+	const view = new DataView(globalsBytes.buffer, globalsBytes.byteOffset, globalsBytes.byteLength);
+	offsets.forEach((offset, index) => {
+		view.setUint32(offset, values[index] ?? 0, true);
+	});
+}
+function concatBytes(parts) {
+	const total = parts.reduce((sum, part) => sum + part.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+}
+/** Builds the [MS-XLS] Workbook stream: the globals substream followed by one worksheet substream per sheet, with every BoundSheet8's own lbPlyPos patched to the real byte offset its sheet's substream landed at. */
+function buildWorkbookStream(content) {
+	if (content.sheets.length === 0) throw new BiffWriteError("a .xls workbook must contain at least one sheet ([MS-XLS] 2.1.7.20.3's own BUNDLESHEET production requires 1*BoundSheet8), but the document being written has none");
+	const formatPlan = buildFormatPlan(content.sheets);
+	const sstPlan = buildSstPlan(content.sheets);
+	const palettePlan = buildPalettePlan(content.sheets);
+	const cellXfPlan = buildCellXfPlan(content.sheets, formatPlan, palettePlan);
+	const globalsPlan = {
+		sheetNames: content.sheets.map((sheet) => sheet.name),
+		customFormats: formatPlan.customFormats,
+		cellXfEntries: cellXfPlan.cellXfEntries,
+		sharedStrings: sstPlan.strings,
+		sharedStringTotalCount: sstPlan.totalCount,
+		paletteColors: palettePlan.paletteColors,
+		printNames: buildPrintNamePlan(content.sheets)
+	};
+	const globals = buildWorkbookGlobals(globalsPlan);
+	const sheetContext = {
+		xfIndexForCell: cellXfPlan.xfIndexForCell,
+		sstIndexFor: (text) => sstPlan.indexOf(text)
+	};
+	const sheetStreams = content.sheets.map((sheet) => buildWorksheetSubstream(sheet, sheetContext));
+	const sheetOffsets = [];
+	let offset = globals.bytes.length;
+	for (const stream of sheetStreams) {
+		sheetOffsets.push(offset);
+		offset += stream.length;
+	}
+	const globalsBytes = globals.bytes.slice();
+	patchBoundSheetOffsets(globalsBytes, globals.lbPlyPosOffsets, sheetOffsets);
+	return concatBytes([globalsBytes, ...sheetStreams]);
+}
+/**
+* Writes a spreadsheet ContentDocument to real .xls bytes: a BIFF8 Workbook stream wrapped in an [MS-CFB] compound file.
+*
+* The counterpart of content.ts's readXlsContent. See this package's README for the writer's full scope.
+*/
+function writeXlsContent(content) {
+	const stream = buildWorkbookStream(content);
+	const streams = [{
+		path: WORKBOOK_STREAM_NAME,
+		bytes: stream
+	}];
+	if (hasSummaryInformationFields(content.metadata)) streams.push({
+		path: SUMMARY_INFORMATION_STREAM,
+		bytes: writeSummaryInformationStream(layoutMetadataToSummaryInformation$1(content.metadata))
+	});
+	return writeCompoundFile(streams);
+}
+/** Writes a DocumentTree of kind 'spreadsheet' to real .xls bytes, flattening it to a ContentDocument first -- the counterpart of content.ts's readXls. */
+function writeXls(tree) {
+	const content = flattenTree(tree);
+	if (content.kind !== "spreadsheet") throw new BiffWriteError(`writeXls was given a DocumentTree of kind '${content.kind}', but a .xls workbook can only be written from a 'spreadsheet' document`);
+	return writeXlsContent(content);
+}
+//#endregion
+export { writeXls, writeXlsContent };