xls-codec 1.0.2 → 2.0.1

package/dist/serial.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_write_errors = require("./biff/write-errors.cjs");
 //#region src/serial.ts
 const MS_PER_DAY = 864e5;
 const MS_PER_HOUR = 36e5;
@@ -56,7 +57,47 @@ function serialToIsoDateTime(serial, date1904) {
 	const date = isoDateOfDayCount(days, date1904);
 	return date === void 0 ? void 0 : `${date}T${isoTimeOfMsWithinDay(msWithinDay)}`;
 }
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_TIME_PATTERN = /^(\d{2}):(\d{2}):(\d{2})$/;
+/** The calendar day count a real date maps to, inverting isoDateOfDayCount: below the 1900 system's phantom leap day (1900-02-29) the day count is a plain offset from 1899-12-31; on or after it, one day is added to skip over the phantom date the calendar never had. The date1904 system has no such adjustment -- 1904 genuinely was a leap year, so its serial 0 origin needs no correction. */
+function isoDateToDayCount(isoDate, date1904) {
+	const match = ISO_DATE_PATTERN.exec(isoDate);
+	if (match === null) throw new require_biff_write_errors.BiffWriteError(`date value ${JSON.stringify(isoDate)} is not an ISO 8601 calendar date (YYYY-MM-DD), which is the only spelling document-schema.js's 'date' cell value permits`);
+	const [, year, month, day] = match;
+	const utcMs = Date.UTC(Number(year), Number(month) - 1, Number(day));
+	if (date1904) return Math.round((utcMs - ORIGIN_1904_UTC_MS) / MS_PER_DAY);
+	const daysBelowPhantom = Math.round((utcMs - ORIGIN_1900_BELOW_PHANTOM_UTC_MS) / MS_PER_DAY);
+	const days = daysBelowPhantom < PHANTOM_LEAP_DAY_SERIAL ? daysBelowPhantom : daysBelowPhantom + 1;
+	if (days < 0) throw new require_biff_write_errors.BiffWriteError(`date value ${JSON.stringify(isoDate)} is before the epoch a BIFF8 serial can represent (1899-12-31)`);
+	return days;
+}
+/** The fraction-of-a-day a wall-clock time maps to, inverting isoTimeOfMsWithinDay. Exact for any whole-second HH:MM:SS input, which is the only shape document-schema.js's 'time'/'dateTime' cell values permit. */
+function isoTimeToDayFraction(isoTime) {
+	const match = ISO_TIME_PATTERN.exec(isoTime);
+	if (match === null) throw new require_biff_write_errors.BiffWriteError(`time value ${JSON.stringify(isoTime)} is not an ISO 8601 wall-clock time (HH:MM:SS), which is the only spelling document-schema.js's 'time'/'dateTime' cell values permit`);
+	const [, hours, minutes, seconds] = match;
+	return (Number(hours) * MS_PER_HOUR + Number(minutes) * MS_PER_MINUTE + Number(seconds) * MS_PER_SECOND) / MS_PER_DAY;
+}
+function isoDateToSerial(isoDate, date1904) {
+	return isoDateToDayCount(isoDate, date1904);
+}
+function isoTimeToSerial(isoTime) {
+	return isoTimeToDayFraction(isoTime);
+}
+/**
+* A combined ISO date-time back to its serial. Accepts a trailing fractional-seconds part and/or a 'Z'/offset suffix -- document-schema.js's own wire contract permits both when the source genuinely carried one -- but a BIFF8 serial has no timezone concept at all (see the read direction's own comment above), so any offset is dropped rather than applied: the wall-clock digits are taken as written, exactly as they would be typed into Excel directly.
+*/
+function isoDateTimeToSerial(isoDateTime, date1904) {
+	const separatorIndex = isoDateTime.indexOf("T");
+	if (separatorIndex !== 10) throw new require_biff_write_errors.BiffWriteError(`dateTime value ${JSON.stringify(isoDateTime)} is not an ISO 8601 combined date and time (YYYY-MM-DDTHH:MM:SS), which is the only spelling document-schema.js's 'dateTime' cell value permits`);
+	const datePart = isoDateTime.slice(0, separatorIndex);
+	const timePart = isoDateTime.slice(separatorIndex + 1).slice(0, 8);
+	return isoDateToDayCount(datePart, date1904) + isoTimeToDayFraction(timePart);
+}
 //#endregion
+exports.isoDateTimeToSerial = isoDateTimeToSerial;
+exports.isoDateToSerial = isoDateToSerial;
+exports.isoTimeToSerial = isoTimeToSerial;
 exports.serialToIsoDate = serialToIsoDate;
 exports.serialToIsoDateTime = serialToIsoDateTime;
 exports.serialToIsoTime = serialToIsoTime;

package/dist/serial.d.cts

@@ -3,5 +3,11 @@ declare function serialToIsoDate(serial: number, date1904: boolean): string | un
 /** A time-of-day format renders only the fractional part -- a serial of 2.5 under `h:mm` displays as noon, not as "two days and twelve hours" -- so the day count is discarded here rather than made an error. Sub-second precision is discarded too: ContentCellValue's own 'time' spelling is fixed at HH:MM:SS. */
 declare function serialToIsoTime(serial: number): string | undefined;
 declare function serialToIsoDateTime(serial: number, date1904: boolean): string | undefined;
+declare function isoDateToSerial(isoDate: string, date1904: boolean): number;
+declare function isoTimeToSerial(isoTime: string): number;
+/**
+ * A combined ISO date-time back to its serial. Accepts a trailing fractional-seconds part and/or a 'Z'/offset suffix -- document-schema.js's own wire contract permits both when the source genuinely carried one -- but a BIFF8 serial has no timezone concept at all (see the read direction's own comment above), so any offset is dropped rather than applied: the wall-clock digits are taken as written, exactly as they would be typed into Excel directly.
+ */
+declare function isoDateTimeToSerial(isoDateTime: string, date1904: boolean): number;
 //#endregion
-export { serialToIsoDate, serialToIsoDateTime, serialToIsoTime };
+export { isoDateTimeToSerial, isoDateToSerial, isoTimeToSerial, serialToIsoDate, serialToIsoDateTime, serialToIsoTime };

package/dist/serial.d.ts

@@ -3,5 +3,11 @@ declare function serialToIsoDate(serial: number, date1904: boolean): string | un
 /** A time-of-day format renders only the fractional part -- a serial of 2.5 under `h:mm` displays as noon, not as "two days and twelve hours" -- so the day count is discarded here rather than made an error. Sub-second precision is discarded too: ContentCellValue's own 'time' spelling is fixed at HH:MM:SS. */
 declare function serialToIsoTime(serial: number): string | undefined;
 declare function serialToIsoDateTime(serial: number, date1904: boolean): string | undefined;
+declare function isoDateToSerial(isoDate: string, date1904: boolean): number;
+declare function isoTimeToSerial(isoTime: string): number;
+/**
+ * A combined ISO date-time back to its serial. Accepts a trailing fractional-seconds part and/or a 'Z'/offset suffix -- document-schema.js's own wire contract permits both when the source genuinely carried one -- but a BIFF8 serial has no timezone concept at all (see the read direction's own comment above), so any offset is dropped rather than applied: the wall-clock digits are taken as written, exactly as they would be typed into Excel directly.
+ */
+declare function isoDateTimeToSerial(isoDateTime: string, date1904: boolean): number;
 //#endregion
-export { serialToIsoDate, serialToIsoDateTime, serialToIsoTime };
+export { isoDateTimeToSerial, isoDateToSerial, isoTimeToSerial, serialToIsoDate, serialToIsoDateTime, serialToIsoTime };

package/dist/serial.js

@@ -1,3 +1,4 @@
+import { BiffWriteError } from "./biff/write-errors.js";
 //#region src/serial.ts
 const MS_PER_DAY = 864e5;
 const MS_PER_HOUR = 36e5;
@@ -55,5 +56,42 @@ function serialToIsoDateTime(serial, date1904) {
 	const date = isoDateOfDayCount(days, date1904);
 	return date === void 0 ? void 0 : `${date}T${isoTimeOfMsWithinDay(msWithinDay)}`;
 }
+const ISO_DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_TIME_PATTERN = /^(\d{2}):(\d{2}):(\d{2})$/;
+/** The calendar day count a real date maps to, inverting isoDateOfDayCount: below the 1900 system's phantom leap day (1900-02-29) the day count is a plain offset from 1899-12-31; on or after it, one day is added to skip over the phantom date the calendar never had. The date1904 system has no such adjustment -- 1904 genuinely was a leap year, so its serial 0 origin needs no correction. */
+function isoDateToDayCount(isoDate, date1904) {
+	const match = ISO_DATE_PATTERN.exec(isoDate);
+	if (match === null) throw new BiffWriteError(`date value ${JSON.stringify(isoDate)} is not an ISO 8601 calendar date (YYYY-MM-DD), which is the only spelling document-schema.js's 'date' cell value permits`);
+	const [, year, month, day] = match;
+	const utcMs = Date.UTC(Number(year), Number(month) - 1, Number(day));
+	if (date1904) return Math.round((utcMs - ORIGIN_1904_UTC_MS) / MS_PER_DAY);
+	const daysBelowPhantom = Math.round((utcMs - ORIGIN_1900_BELOW_PHANTOM_UTC_MS) / MS_PER_DAY);
+	const days = daysBelowPhantom < PHANTOM_LEAP_DAY_SERIAL ? daysBelowPhantom : daysBelowPhantom + 1;
+	if (days < 0) throw new BiffWriteError(`date value ${JSON.stringify(isoDate)} is before the epoch a BIFF8 serial can represent (1899-12-31)`);
+	return days;
+}
+/** The fraction-of-a-day a wall-clock time maps to, inverting isoTimeOfMsWithinDay. Exact for any whole-second HH:MM:SS input, which is the only shape document-schema.js's 'time'/'dateTime' cell values permit. */
+function isoTimeToDayFraction(isoTime) {
+	const match = ISO_TIME_PATTERN.exec(isoTime);
+	if (match === null) throw new BiffWriteError(`time value ${JSON.stringify(isoTime)} is not an ISO 8601 wall-clock time (HH:MM:SS), which is the only spelling document-schema.js's 'time'/'dateTime' cell values permit`);
+	const [, hours, minutes, seconds] = match;
+	return (Number(hours) * MS_PER_HOUR + Number(minutes) * MS_PER_MINUTE + Number(seconds) * MS_PER_SECOND) / MS_PER_DAY;
+}
+function isoDateToSerial(isoDate, date1904) {
+	return isoDateToDayCount(isoDate, date1904);
+}
+function isoTimeToSerial(isoTime) {
+	return isoTimeToDayFraction(isoTime);
+}
+/**
+* A combined ISO date-time back to its serial. Accepts a trailing fractional-seconds part and/or a 'Z'/offset suffix -- document-schema.js's own wire contract permits both when the source genuinely carried one -- but a BIFF8 serial has no timezone concept at all (see the read direction's own comment above), so any offset is dropped rather than applied: the wall-clock digits are taken as written, exactly as they would be typed into Excel directly.
+*/
+function isoDateTimeToSerial(isoDateTime, date1904) {
+	const separatorIndex = isoDateTime.indexOf("T");
+	if (separatorIndex !== 10) throw new BiffWriteError(`dateTime value ${JSON.stringify(isoDateTime)} is not an ISO 8601 combined date and time (YYYY-MM-DDTHH:MM:SS), which is the only spelling document-schema.js's 'dateTime' cell value permits`);
+	const datePart = isoDateTime.slice(0, separatorIndex);
+	const timePart = isoDateTime.slice(separatorIndex + 1).slice(0, 8);
+	return isoDateToDayCount(datePart, date1904) + isoTimeToDayFraction(timePart);
+}
 //#endregion
-export { serialToIsoDate, serialToIsoDateTime, serialToIsoTime };
+export { isoDateTimeToSerial, isoDateToSerial, isoTimeToSerial, serialToIsoDate, serialToIsoDateTime, serialToIsoTime };

package/dist/substreams-D7dQiJbp.d.ts

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

package/dist/substreams-Ddtvn_Vr.d.cts

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

package/dist/units.cjs

@@ -5,6 +5,8 @@ const POINTS_PER_INCH = 72;
 const PIXELS_PER_INCH = 96;
 /** A twip is a twentieth of a point; a Row record's miyRw is in twips ([MS-XLS] 2.4.221). */
 const TWIPS_PER_POINT = 20;
+/** The inch's own definition in millimetres, which is what turns [MS-XLS] 2.4.257's metric paper sizes into points. */
+const MILLIMETRES_PER_INCH = 25.4;
 /**
 * The "maximum digit width": the widest rendered width, in pixels, of the digits 0-9 in the workbook's Normal-style font, which is the unit a column width is expressed in multiples of.
 *
@@ -15,6 +17,18 @@ const MAX_DIGIT_WIDTH_PX = 7;
 function twipsToPoints(twips) {
 	return twips / TWIPS_PER_POINT;
 }
+/** A margin record's own Xnum ([MS-XLS] 2.4.151 and its three siblings), in inches, as points. */
+function inchesToPoints(inches) {
+	return inches * POINTS_PER_INCH;
+}
+/** The inverse, for writing a margin back out. Exact for every value inchesToPoints produces, since the conversion is a single multiplication by an integer. */
+function pointsToInches(points) {
+	return points / POINTS_PER_INCH;
+}
+/** A paper size [MS-XLS] 2.4.257's own code table states in millimetres, as points. */
+function millimetresToPoints(millimetres) {
+	return millimetres / MILLIMETRES_PER_INCH * POINTS_PER_INCH;
+}
 /**
 * A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
 *
@@ -25,6 +39,29 @@ function columnWidthToPoints(coldx) {
 	const digitWidthAllowance = Math.trunc(128 / MAX_DIGIT_WIDTH_PX);
 	return Math.trunc((256 * chars + digitWidthAllowance) / 256 * MAX_DIGIT_WIDTH_PX) / PIXELS_PER_INCH * POINTS_PER_INCH;
 }
+/** A Row record's own height field ([MS-XLS] 2.4.221 miyRw), in twips, rounded to the nearest whole twip and clamped to the field's own documented range (2-8192). The inverse of twipsToPoints, and exact for it: twipsToPoints(pointsToTwips(pt)) === pt for any pt this function does not clamp, since twips-per-point is an integer. */
+function pointsToTwips(points) {
+	const MIN_ROW_HEIGHT_TWIPS = 2;
+	const MAX_ROW_HEIGHT_TWIPS = 8192;
+	const twips = Math.round(points * TWIPS_PER_POINT);
+	return Math.min(Math.max(twips, MIN_ROW_HEIGHT_TWIPS), MAX_ROW_HEIGHT_TWIPS);
+}
+/**
+* The inverse of columnWidthToPoints: the smallest ColInfo coldx whose own forward pixel-quantized width is at least as wide as the given points. Because columnWidthToPoints truncates to a whole pixel, no coldx reproduces an arbitrary points value exactly; this picks the smallest coldx that rounds UP to (rather than under) the requested width, so a column written from a given widthPt and read back through columnWidthToPoints never comes back narrower than what was asked for -- the same "honestly approximate" contract columnWidthToPoints's own comment already documents for the read direction.
+*
+* Derived directly from columnWidthToPoints's own forward formula: pixels(coldx) = floor((coldx + digitWidthAllowance) * MAX_DIGIT_WIDTH_PX / 256). Solving for the smallest coldx with pixels(coldx) >= targetPixels gives coldx = ceil(targetPixels * 256 / MAX_DIGIT_WIDTH_PX) - digitWidthAllowance.
+*/
+function pointsToColumnWidth(points) {
+	const digitWidthAllowance = Math.trunc(128 / MAX_DIGIT_WIDTH_PX);
+	const targetPixels = Math.round(points / POINTS_PER_INCH * PIXELS_PER_INCH);
+	const coldx = Math.ceil(targetPixels * 256 / MAX_DIGIT_WIDTH_PX - digitWidthAllowance);
+	return Math.max(coldx, 0);
+}
 //#endregion
 exports.columnWidthToPoints = columnWidthToPoints;
+exports.inchesToPoints = inchesToPoints;
+exports.millimetresToPoints = millimetresToPoints;
+exports.pointsToColumnWidth = pointsToColumnWidth;
+exports.pointsToInches = pointsToInches;
+exports.pointsToTwips = pointsToTwips;
 exports.twipsToPoints = twipsToPoints;

package/dist/units.d.cts

@@ -1,11 +1,25 @@
 //#region src/units.d.ts
 /** A Row record's height, in twips, as points. */
 declare function twipsToPoints(twips: number): number;
+/** A margin record's own Xnum ([MS-XLS] 2.4.151 and its three siblings), in inches, as points. */
+declare function inchesToPoints(inches: number): number;
+/** The inverse, for writing a margin back out. Exact for every value inchesToPoints produces, since the conversion is a single multiplication by an integer. */
+declare function pointsToInches(points: number): number;
+/** A paper size [MS-XLS] 2.4.257's own code table states in millimetres, as points. */
+declare function millimetresToPoints(millimetres: number): number;
 /**
  * A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
  *
  * The pixel step reproduces Excel's own integer-pixel-grid truncation rather than smoothing it into a continuous formula, so a width read here matches the pixel count Excel itself would render, and matches what ooxml.js computes for the equivalent xlsx column.
  */
 declare function columnWidthToPoints(coldx: number): number;
+/** A Row record's own height field ([MS-XLS] 2.4.221 miyRw), in twips, rounded to the nearest whole twip and clamped to the field's own documented range (2-8192). The inverse of twipsToPoints, and exact for it: twipsToPoints(pointsToTwips(pt)) === pt for any pt this function does not clamp, since twips-per-point is an integer. */
+declare function pointsToTwips(points: number): number;
+/**
+ * The inverse of columnWidthToPoints: the smallest ColInfo coldx whose own forward pixel-quantized width is at least as wide as the given points. Because columnWidthToPoints truncates to a whole pixel, no coldx reproduces an arbitrary points value exactly; this picks the smallest coldx that rounds UP to (rather than under) the requested width, so a column written from a given widthPt and read back through columnWidthToPoints never comes back narrower than what was asked for -- the same "honestly approximate" contract columnWidthToPoints's own comment already documents for the read direction.
+ *
+ * Derived directly from columnWidthToPoints's own forward formula: pixels(coldx) = floor((coldx + digitWidthAllowance) * MAX_DIGIT_WIDTH_PX / 256). Solving for the smallest coldx with pixels(coldx) >= targetPixels gives coldx = ceil(targetPixels * 256 / MAX_DIGIT_WIDTH_PX) - digitWidthAllowance.
+ */
+declare function pointsToColumnWidth(points: number): number;
 //#endregion
-export { columnWidthToPoints, twipsToPoints };
+export { columnWidthToPoints, inchesToPoints, millimetresToPoints, pointsToColumnWidth, pointsToInches, pointsToTwips, twipsToPoints };

package/dist/units.d.ts

@@ -1,11 +1,25 @@
 //#region src/units.d.ts
 /** A Row record's height, in twips, as points. */
 declare function twipsToPoints(twips: number): number;
+/** A margin record's own Xnum ([MS-XLS] 2.4.151 and its three siblings), in inches, as points. */
+declare function inchesToPoints(inches: number): number;
+/** The inverse, for writing a margin back out. Exact for every value inchesToPoints produces, since the conversion is a single multiplication by an integer. */
+declare function pointsToInches(points: number): number;
+/** A paper size [MS-XLS] 2.4.257's own code table states in millimetres, as points. */
+declare function millimetresToPoints(millimetres: number): number;
 /**
  * A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
  *
  * The pixel step reproduces Excel's own integer-pixel-grid truncation rather than smoothing it into a continuous formula, so a width read here matches the pixel count Excel itself would render, and matches what ooxml.js computes for the equivalent xlsx column.
  */
 declare function columnWidthToPoints(coldx: number): number;
+/** A Row record's own height field ([MS-XLS] 2.4.221 miyRw), in twips, rounded to the nearest whole twip and clamped to the field's own documented range (2-8192). The inverse of twipsToPoints, and exact for it: twipsToPoints(pointsToTwips(pt)) === pt for any pt this function does not clamp, since twips-per-point is an integer. */
+declare function pointsToTwips(points: number): number;
+/**
+ * The inverse of columnWidthToPoints: the smallest ColInfo coldx whose own forward pixel-quantized width is at least as wide as the given points. Because columnWidthToPoints truncates to a whole pixel, no coldx reproduces an arbitrary points value exactly; this picks the smallest coldx that rounds UP to (rather than under) the requested width, so a column written from a given widthPt and read back through columnWidthToPoints never comes back narrower than what was asked for -- the same "honestly approximate" contract columnWidthToPoints's own comment already documents for the read direction.
+ *
+ * Derived directly from columnWidthToPoints's own forward formula: pixels(coldx) = floor((coldx + digitWidthAllowance) * MAX_DIGIT_WIDTH_PX / 256). Solving for the smallest coldx with pixels(coldx) >= targetPixels gives coldx = ceil(targetPixels * 256 / MAX_DIGIT_WIDTH_PX) - digitWidthAllowance.
+ */
+declare function pointsToColumnWidth(points: number): number;
 //#endregion
-export { columnWidthToPoints, twipsToPoints };
+export { columnWidthToPoints, inchesToPoints, millimetresToPoints, pointsToColumnWidth, pointsToInches, pointsToTwips, twipsToPoints };

package/dist/units.js

@@ -4,6 +4,8 @@ const POINTS_PER_INCH = 72;
 const PIXELS_PER_INCH = 96;
 /** A twip is a twentieth of a point; a Row record's miyRw is in twips ([MS-XLS] 2.4.221). */
 const TWIPS_PER_POINT = 20;
+/** The inch's own definition in millimetres, which is what turns [MS-XLS] 2.4.257's metric paper sizes into points. */
+const MILLIMETRES_PER_INCH = 25.4;
 /**
 * The "maximum digit width": the widest rendered width, in pixels, of the digits 0-9 in the workbook's Normal-style font, which is the unit a column width is expressed in multiples of.
 *
@@ -14,6 +16,18 @@ const MAX_DIGIT_WIDTH_PX = 7;
 function twipsToPoints(twips) {
 	return twips / TWIPS_PER_POINT;
 }
+/** A margin record's own Xnum ([MS-XLS] 2.4.151 and its three siblings), in inches, as points. */
+function inchesToPoints(inches) {
+	return inches * POINTS_PER_INCH;
+}
+/** The inverse, for writing a margin back out. Exact for every value inchesToPoints produces, since the conversion is a single multiplication by an integer. */
+function pointsToInches(points) {
+	return points / POINTS_PER_INCH;
+}
+/** A paper size [MS-XLS] 2.4.257's own code table states in millimetres, as points. */
+function millimetresToPoints(millimetres) {
+	return millimetres / MILLIMETRES_PER_INCH * POINTS_PER_INCH;
+}
 /**
 * A ColInfo record's coldx -- a width in 1/256ths of a character width ([MS-XLS] 2.4.53) -- as points.
 *
@@ -24,5 +38,23 @@ function columnWidthToPoints(coldx) {
 	const digitWidthAllowance = Math.trunc(128 / MAX_DIGIT_WIDTH_PX);
 	return Math.trunc((256 * chars + digitWidthAllowance) / 256 * MAX_DIGIT_WIDTH_PX) / PIXELS_PER_INCH * POINTS_PER_INCH;
 }
+/** A Row record's own height field ([MS-XLS] 2.4.221 miyRw), in twips, rounded to the nearest whole twip and clamped to the field's own documented range (2-8192). The inverse of twipsToPoints, and exact for it: twipsToPoints(pointsToTwips(pt)) === pt for any pt this function does not clamp, since twips-per-point is an integer. */
+function pointsToTwips(points) {
+	const MIN_ROW_HEIGHT_TWIPS = 2;
+	const MAX_ROW_HEIGHT_TWIPS = 8192;
+	const twips = Math.round(points * TWIPS_PER_POINT);
+	return Math.min(Math.max(twips, MIN_ROW_HEIGHT_TWIPS), MAX_ROW_HEIGHT_TWIPS);
+}
+/**
+* The inverse of columnWidthToPoints: the smallest ColInfo coldx whose own forward pixel-quantized width is at least as wide as the given points. Because columnWidthToPoints truncates to a whole pixel, no coldx reproduces an arbitrary points value exactly; this picks the smallest coldx that rounds UP to (rather than under) the requested width, so a column written from a given widthPt and read back through columnWidthToPoints never comes back narrower than what was asked for -- the same "honestly approximate" contract columnWidthToPoints's own comment already documents for the read direction.
+*
+* Derived directly from columnWidthToPoints's own forward formula: pixels(coldx) = floor((coldx + digitWidthAllowance) * MAX_DIGIT_WIDTH_PX / 256). Solving for the smallest coldx with pixels(coldx) >= targetPixels gives coldx = ceil(targetPixels * 256 / MAX_DIGIT_WIDTH_PX) - digitWidthAllowance.
+*/
+function pointsToColumnWidth(points) {
+	const digitWidthAllowance = Math.trunc(128 / MAX_DIGIT_WIDTH_PX);
+	const targetPixels = Math.round(points / POINTS_PER_INCH * PIXELS_PER_INCH);
+	const coldx = Math.ceil(targetPixels * 256 / MAX_DIGIT_WIDTH_PX - digitWidthAllowance);
+	return Math.max(coldx, 0);
+}
 //#endregion
-export { columnWidthToPoints, twipsToPoints };
+export { columnWidthToPoints, inchesToPoints, millimetresToPoints, pointsToColumnWidth, pointsToInches, pointsToTwips, twipsToPoints };

package/dist/workbook/globals-writer.cjs

@@ -0,0 +1,122 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_record_types = require("../biff/record-types.cjs");
+const require_biff_builder = require("../biff/builder.cjs");
+const require_biff_record_writer = require("../biff/record-writer.cjs");
+const require_workbook_print_names = require("./print-names.cjs");
+const require_biff_bof_writer = require("../biff/bof-writer.cjs");
+const require_biff_string_writer = require("../biff/string-writer.cjs");
+const require_biff_xf_writer = require("../biff/xf-writer.cjs");
+//#region src/workbook/globals-writer.ts
+const GENERAL_FORMAT_ID = 0;
+const NORMAL_FONT_INDEX = 0;
+const NORMAL_FONT_NAME = "Arial";
+/** Excel 97-2003's own Normal-style default: 10pt, in twips (dyHeight's own unit, [MS-XLS] 2.4.122). */
+const NORMAL_FONT_HEIGHT_TWIPS = 200;
+/** [MS-XLS] "BuiltInStyle" istyBuiltIn values (ECMA-376 Part 1 18.8.7's cellStyle builtinId table): 0 Normal, 1 RowLevel, 2 ColLevel -- the only three this writer emits, since it never groups rows/columns into an outline. */
+const BUILTIN_STYLE_NORMAL = 0;
+const BUILTIN_STYLE_ROW_LEVEL = 1;
+const BUILTIN_STYLE_COL_LEVEL = 2;
+/** BuiltInStyle's own iLevel sentinel for a style other than RowLevel/ColLevel: "otherwise, this value MUST be 0xFF". */
+const NO_OUTLINE_LEVEL = 255;
+/** RowLevel/ColLevel each cover seven outline depths ([MS-XLS] "BuiltInStyle"'s own 0x00-0x06 iLevel table). */
+const OUTLINE_LEVEL_COUNT = 7;
+/** The fifteen built-in cell styles, XF index 0 through 14, in the order every real Excel-written workbook carries them: Normal, then RowLevel_1..7, then ColLevel_1..7. */
+const BUILTIN_STYLES = [
+	{
+		istyBuiltIn: BUILTIN_STYLE_NORMAL,
+		iLevel: NO_OUTLINE_LEVEL
+	},
+	...Array.from({ length: OUTLINE_LEVEL_COUNT }, (_unused, level) => ({
+		istyBuiltIn: BUILTIN_STYLE_ROW_LEVEL,
+		iLevel: level
+	})),
+	...Array.from({ length: OUTLINE_LEVEL_COUNT }, (_unused, level) => ({
+		istyBuiltIn: BUILTIN_STYLE_COL_LEVEL,
+		iLevel: level
+	}))
+];
+/** [MS-XLS] 2.1.7.20.3's own XFS production requires at least sixteen XF records before any cell can reference one: BUILTIN_STYLES.length built-in cell styles, then at least one cell XF -- the "General, no declared format" one every workbook needs unconditionally, written immediately after them. Derived from BUILTIN_STYLES's own length rather than restated as a literal, so the two can never drift apart. */
+const GENERAL_CELL_XF_INDEX = BUILTIN_STYLES.length;
+/** BoundSheet8 ([MS-XLS] 2.4.28) with lbPlyPos left at 0: a placeholder the caller patches in place, since the real value -- the byte offset of this sheet's own BOF within the finished workbook stream -- is only known once every substream's length has been measured. */
+function writeBoundSheet8Placeholder(name) {
+	const data = new require_biff_builder.RecordBuilder().u32(0).u8(0).u8(0).bytes(require_biff_string_writer.writeShortXLUnicodeString(name)).build();
+	return require_biff_record_writer.writeRecord(133, data);
+}
+/** [MS-XLS] 2.4.271's own cch table: the value a self-referencing SupBook -- this workbook itself, rather than another workbook, a DDE/OLE data source, or an add-in -- carries in place of a virtual path. The one kind of supporting link this package writes, and the one kind workbook/globals.ts's own reader resolves a 3D reference through. */
+const SUPBOOK_SELF_REFERENCING_CCH = 1025;
+/** SupBook ([MS-XLS] 2.4.271), self-referencing: a two-byte sheet count then that cch sentinel, and nothing else -- the virtPath/rgst payload a real external link would carry has no meaning for a link that names this same workbook. */
+function writeSupBookRecord(sheetCount) {
+	return require_biff_record_writer.writeRecord(430, new require_biff_builder.RecordBuilder().u16(sheetCount).u16(SUPBOOK_SELF_REFERENCING_CCH).build());
+}
+/**
+* ExternSheet ([MS-XLS] 2.4.106): a two-byte cXTI then that many XTI structures ([MS-XLS] 2.5.344), each an iSupBook and a signed itabFirst/itabLast sheet-scope pair -- the write-side mirror of workbook/globals.ts's own readSheetRanges.
+*
+* One XTI per sheet, each scoped to that one sheet and pointing at the single self-referencing SupBook above, so a print name's own PtgArea3d can name its sheet by using that sheet's index as its ixti. The 3D reference machinery exists here purely because [MS-XLS] gives a defined name no other way to say which sheet its range is on.
+*/
+function writeExternSheetRecord(sheetCount) {
+	const builder = new require_biff_builder.RecordBuilder().u16(sheetCount);
+	for (let sheetIndex = 0; sheetIndex < sheetCount; sheetIndex += 1) builder.u16(0).u16(sheetIndex).u16(sheetIndex);
+	return require_biff_record_writer.writeRecord(23, builder.build());
+}
+/** SST ([MS-XLS] 2.4.265): a total reference count, a unique-string count, then that many XLUnicodeRichExtendedStrings, packed with no offsets -- the write-side mirror of workbook/globals.ts's own readSharedStrings. */
+function writeSstRecord(strings, totalCount) {
+	const builder = new require_biff_builder.RecordBuilder().i32(totalCount).i32(strings.length);
+	for (const text of strings) builder.bytes(require_biff_string_writer.writeRichExtendedString(text));
+	return require_biff_record_writer.writeRecord(252, builder.build());
+}
+function buildWorkbookGlobals(plan) {
+	const pieces = [];
+	let offset = 0;
+	const push = (piece) => {
+		pieces.push(piece);
+		offset += piece.length;
+	};
+	push(require_biff_record_writer.writeRecord(require_biff_record_types.RECORD_BOF, require_biff_bof_writer.writeBofData(5)));
+	push(require_biff_xf_writer.writeFontRecord(NORMAL_FONT_NAME, NORMAL_FONT_HEIGHT_TWIPS));
+	for (const code of plan.customFormats) push(require_biff_xf_writer.writeFormatRecord(code.id, code.code));
+	BUILTIN_STYLES.forEach(() => {
+		push(require_biff_xf_writer.writeStyleXfRecord({
+			fontIndex: NORMAL_FONT_INDEX,
+			formatId: GENERAL_FORMAT_ID
+		}));
+	});
+	push(require_biff_xf_writer.writeCellXfRecord({
+		fontIndex: NORMAL_FONT_INDEX,
+		formatId: GENERAL_FORMAT_ID
+	}));
+	for (const entry of plan.cellXfEntries) push(require_biff_xf_writer.writeCellXfRecord({
+		fontIndex: NORMAL_FONT_INDEX,
+		formatId: entry.formatId,
+		alignment: entry.alignment,
+		verticalAlignment: entry.verticalAlignment,
+		decoration: entry.decoration
+	}));
+	BUILTIN_STYLES.forEach((builtin, index) => {
+		push(require_biff_xf_writer.writeStyleRecord({
+			xfIndex: index,
+			istyBuiltIn: builtin.istyBuiltIn,
+			iLevel: builtin.iLevel
+		}));
+	});
+	if (plan.paletteColors !== void 0) push(require_biff_xf_writer.writePaletteRecord(plan.paletteColors));
+	const lbPlyPosOffsets = [];
+	for (const name of plan.sheetNames) {
+		const recordStart = offset;
+		lbPlyPosOffsets.push(recordStart + 4);
+		push(writeBoundSheet8Placeholder(name));
+	}
+	if (plan.printNames.length > 0) {
+		push(writeSupBookRecord(plan.sheetNames.length));
+		push(writeExternSheetRecord(plan.sheetNames.length));
+		for (const record of require_workbook_print_names.writePrintNameRecords(plan.printNames)) push(record);
+	}
+	if (plan.sharedStrings.length > 0) push(writeSstRecord(plan.sharedStrings, plan.sharedStringTotalCount));
+	push(require_biff_record_writer.writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
+	return {
+		bytes: require_biff_record_writer.concatRecords(...pieces),
+		lbPlyPosOffsets
+	};
+}
+//#endregion
+exports.GENERAL_CELL_XF_INDEX = GENERAL_CELL_XF_INDEX;
+exports.buildWorkbookGlobals = buildWorkbookGlobals;

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

@@ -0,0 +1,39 @@
+import { T as XfDecorationFields } from "../xf-colors-CehHZtBy.cjs";
+import { t as PrintNamePlanEntry } from "../print-names-D-njuzVw.cjs";
+import { Alignment, Color } from "document-schema.js";
+//#region src/workbook/globals-writer.d.ts
+/** [MS-XLS] 2.1.7.20.3's own XFS production requires at least sixteen XF records before any cell can reference one: BUILTIN_STYLES.length built-in cell styles, then at least one cell XF -- the "General, no declared format" one every workbook needs unconditionally, written immediately after them. Derived from BUILTIN_STYLES's own length rather than restated as a literal, so the two can never drift apart. */
+declare const GENERAL_CELL_XF_INDEX: number;
+/** One cell XF beyond the implicit General one at GENERAL_CELL_XF_INDEX: the number-format identifier it displays through, the cell's own horizontal/vertical alignment (general/bottom, this writer's own defaults, when omitted), and -- when the cell it serves carries a background or borders -- the fill/border fields its CellXF payload packs. Undefined decoration writes the same undecorated defaults this writer always wrote before decoration existed. */
+interface CellXfPlanEntry {
+  readonly formatId: number;
+  readonly alignment?: Alignment;
+  readonly verticalAlignment?: "top" | "middle" | "bottom";
+  readonly decoration?: XfDecorationFields;
+}
+interface WorkbookGlobalsPlan {
+  readonly sheetNames: readonly string[];
+  /** Custom number-format codes needing their own Format record, each with the identifier already assigned to it (always >= 164, [MS-XLS] 2.4.126's own custom-identifier floor). A code equal to one of the built-in table's own strings needs no Format record here -- number-format.ts's BUILTIN_NUMBER_FORMATS already covers ids 0-49 for both this package's reader and any other. */
+  readonly customFormats: readonly {
+    readonly id: number;
+    readonly code: string;
+  }[];
+  /** Every cell XF beyond the implicit General one at GENERAL_CELL_XF_INDEX, in the order their XF records are written: index GENERAL_CELL_XF_INDEX + 1 + i is entry cellXfEntries[i]. write.ts's own cell-format interning pass assigns one entry to every distinct (number format, decoration) combination the workbook's cells actually use. */
+  readonly cellXfEntries: readonly CellXfPlanEntry[];
+  /** The shared string table, in SST order -- a LabelSst cell's own isst indexes into this array. */
+  readonly sharedStrings: readonly string[];
+  /** SST's own cstTotal: the total number of string-cell references across the whole workbook, not just the unique count. Not read by this package's own reader (which discards the field), but a real conformant value rather than a placeholder. */
+  readonly sharedStringTotalCount: number;
+  /** The workbook's own custom colour table (56 entries, icv 8 first), when write.ts's own palette-interning pass decided the workbook needs one -- undefined when every decoration colour the workbook's cells use already matches the fixed default table, in which case no Palette record is written at all and those colours resolve through the default table instead ([MS-XLS] "Icv"'s own documented fallback). */
+  readonly paletteColors?: readonly Color[];
+  /** The built-in Print_Area/Print_Titles defined names the workbook's sheets declare, one Lbl record each. Empty when no sheet declares a print range or a repeated header band, in which case no SupBook, ExternSheet, or Lbl record is written at all -- exactly like Palette above, a workbook that needs none stays as minimal as it always was. */
+  readonly printNames: readonly PrintNamePlanEntry[];
+}
+interface WorkbookGlobalsBuild {
+  readonly bytes: Uint8Array<ArrayBuffer>;
+  /** Byte offset, within `bytes`, of each sheet's own BoundSheet8.lbPlyPos field ([MS-XLS] 2.4.28) -- a 4-byte little-endian integer the caller patches once every sheet substream's own length in the final workbook stream is known. In `plan.sheetNames` order. */
+  readonly lbPlyPosOffsets: readonly number[];
+}
+declare function buildWorkbookGlobals(plan: WorkbookGlobalsPlan): WorkbookGlobalsBuild;
+//#endregion
+export { CellXfPlanEntry, GENERAL_CELL_XF_INDEX, WorkbookGlobalsBuild, WorkbookGlobalsPlan, buildWorkbookGlobals };

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

@@ -0,0 +1,39 @@
+import { T as XfDecorationFields } from "../xf-colors-CpykR3B9.js";
+import { t as PrintNamePlanEntry } from "../print-names-DUlpVE00.js";
+import { Alignment, Color } from "document-schema.js";
+//#region src/workbook/globals-writer.d.ts
+/** [MS-XLS] 2.1.7.20.3's own XFS production requires at least sixteen XF records before any cell can reference one: BUILTIN_STYLES.length built-in cell styles, then at least one cell XF -- the "General, no declared format" one every workbook needs unconditionally, written immediately after them. Derived from BUILTIN_STYLES's own length rather than restated as a literal, so the two can never drift apart. */
+declare const GENERAL_CELL_XF_INDEX: number;
+/** One cell XF beyond the implicit General one at GENERAL_CELL_XF_INDEX: the number-format identifier it displays through, the cell's own horizontal/vertical alignment (general/bottom, this writer's own defaults, when omitted), and -- when the cell it serves carries a background or borders -- the fill/border fields its CellXF payload packs. Undefined decoration writes the same undecorated defaults this writer always wrote before decoration existed. */
+interface CellXfPlanEntry {
+  readonly formatId: number;
+  readonly alignment?: Alignment;
+  readonly verticalAlignment?: "top" | "middle" | "bottom";
+  readonly decoration?: XfDecorationFields;
+}
+interface WorkbookGlobalsPlan {
+  readonly sheetNames: readonly string[];
+  /** Custom number-format codes needing their own Format record, each with the identifier already assigned to it (always >= 164, [MS-XLS] 2.4.126's own custom-identifier floor). A code equal to one of the built-in table's own strings needs no Format record here -- number-format.ts's BUILTIN_NUMBER_FORMATS already covers ids 0-49 for both this package's reader and any other. */
+  readonly customFormats: readonly {
+    readonly id: number;
+    readonly code: string;
+  }[];
+  /** Every cell XF beyond the implicit General one at GENERAL_CELL_XF_INDEX, in the order their XF records are written: index GENERAL_CELL_XF_INDEX + 1 + i is entry cellXfEntries[i]. write.ts's own cell-format interning pass assigns one entry to every distinct (number format, decoration) combination the workbook's cells actually use. */
+  readonly cellXfEntries: readonly CellXfPlanEntry[];
+  /** The shared string table, in SST order -- a LabelSst cell's own isst indexes into this array. */
+  readonly sharedStrings: readonly string[];
+  /** SST's own cstTotal: the total number of string-cell references across the whole workbook, not just the unique count. Not read by this package's own reader (which discards the field), but a real conformant value rather than a placeholder. */
+  readonly sharedStringTotalCount: number;
+  /** The workbook's own custom colour table (56 entries, icv 8 first), when write.ts's own palette-interning pass decided the workbook needs one -- undefined when every decoration colour the workbook's cells use already matches the fixed default table, in which case no Palette record is written at all and those colours resolve through the default table instead ([MS-XLS] "Icv"'s own documented fallback). */
+  readonly paletteColors?: readonly Color[];
+  /** The built-in Print_Area/Print_Titles defined names the workbook's sheets declare, one Lbl record each. Empty when no sheet declares a print range or a repeated header band, in which case no SupBook, ExternSheet, or Lbl record is written at all -- exactly like Palette above, a workbook that needs none stays as minimal as it always was. */
+  readonly printNames: readonly PrintNamePlanEntry[];
+}
+interface WorkbookGlobalsBuild {
+  readonly bytes: Uint8Array<ArrayBuffer>;
+  /** Byte offset, within `bytes`, of each sheet's own BoundSheet8.lbPlyPos field ([MS-XLS] 2.4.28) -- a 4-byte little-endian integer the caller patches once every sheet substream's own length in the final workbook stream is known. In `plan.sheetNames` order. */
+  readonly lbPlyPosOffsets: readonly number[];
+}
+declare function buildWorkbookGlobals(plan: WorkbookGlobalsPlan): WorkbookGlobalsBuild;
+//#endregion
+export { CellXfPlanEntry, GENERAL_CELL_XF_INDEX, WorkbookGlobalsBuild, WorkbookGlobalsPlan, buildWorkbookGlobals };