xls-codec 4.14.0 → 4.15.1

package/dist/drawing/escher-writer.cjs

@@ -0,0 +1,107 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_builder = require("../biff/builder.cjs");
+const require_biff_write_errors = require("../biff/write-errors.cjs");
+const require_drawing_escher_constants = require("./escher-constants.cjs");
+const require_drawing_md4 = require("./md4.cjs");
+//#region src/drawing/escher-writer.ts
+/** One Escher atom's own bytes: header plus `data` verbatim. */
+function escherAtom(recVer, recInstance, recType, data) {
+	return new require_biff_builder.RecordBuilder().u16(recVer & 15 | (recInstance & 4095) << 4).u16(recType).u32(data.length).bytes(data).build();
+}
+/** One Escher container's own bytes: header (recVer 0xF, [MS-ODRAW] 2.2.1's container marker, in the verInstance word's low nibble) plus its children concatenated -- recLen is then the children's total size with their own headers included, exactly what the format defines. `recInstance` is the verInstance word's upper 12 bits, which every container this writer states pins to 0x000 except the Blip Store, whose own page requires the count of BSE children. */
+function escherContainer(recType, recInstance, children) {
+	const body = children.reduce((sum, child) => sum + child.length, 0);
+	const builder = new require_biff_builder.RecordBuilder().u16(15 | (recInstance & 4095) << 4).u16(recType).u32(body);
+	for (const child of children) builder.bytes(child);
+	return builder.build();
+}
+const MSOBLIP_JPEG = 5;
+const MSOBLIP_PNG = 6;
+const BLIP_PNG_RECTYPE = 61470;
+const BLIP_JPEG_RECTYPE = 61469;
+const BLIP_PNG_INSTANCE_ONE_UID = 1760;
+const BLIP_JPEG_INSTANCE_ONE_UID = 1130;
+/** rgbUid's own fixed size: [MS-ODRAW]'s FBSE and Blip records each open with one 16-byte MD4 digest of the image data. */
+const UID_SIZE = 16;
+function blipFormatFields(format) {
+	if (format === "png") return {
+		msoBlip: MSOBLIP_PNG,
+		recType: BLIP_PNG_RECTYPE,
+		recInstance: BLIP_PNG_INSTANCE_ONE_UID
+	};
+	return {
+		msoBlip: MSOBLIP_JPEG,
+		recType: BLIP_JPEG_RECTYPE,
+		recInstance: BLIP_JPEG_INSTANCE_ONE_UID
+	};
+}
+/** One OfficeArtBlipPNG/JPEG record ([MS-ODRAW] 2.2.28/2.2.27): one rgbUid (the MD4 of the file bytes -- a digest of the UNCOMPRESSED blip data per 2.2.28's own field text, which for PNG and JPEG is the file bytes themselves), the tag byte, then the literal file bytes. The tag byte is 0xFF, "internal resource tag" -- the value real producers write for data embedded in the record. */
+function writeBlipRecord(format, uidBytes, fileBytes) {
+	const fields = blipFormatFields(format);
+	return escherAtom(0, fields.recInstance, fields.recType, new require_biff_builder.RecordBuilder().bytes(uidBytes).u8(255).bytes(fileBytes).build());
+}
+/** One OfficeArtFBSE ([MS-ODRAW] 2.2.24.1, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/2f2d7f5e-d5c4-4cb7-b230-59b3fe8f10d6): the blip's type pair, its rgbUid, a tag, the embedded blip record's own total size, the reference count, a foDelay this writer always states as "not in a delay stream" alongside an inline embeddedBlip (which [MS-ODRAW] says makes foDelay ignored), the name-length byte (0 -- no name), and the embedded blip record itself. recLen's own rule -- "the size of nameData plus size plus 36" for an embedded blip -- falls out of the fixed fields plus the blip record's length. */
+function writeBseRecord(blip) {
+	const fields = blipFormatFields(blip.format);
+	const uidBytes = hexToBytes(require_drawing_md4.md4(blip.fileBytes));
+	if (uidBytes.length !== UID_SIZE) throw new require_biff_write_errors.BiffWriteError(`internal error: md4 produced a ${uidBytes.length}-byte digest, not the ${UID_SIZE} bytes rgbUid ([MS-ODRAW]'s own FBSE/Blip field) requires`);
+	const embedded = writeBlipRecord(blip.format, uidBytes, blip.fileBytes);
+	const fixed = new require_biff_builder.RecordBuilder().u8(fields.msoBlip).u8(fields.msoBlip).bytes(uidBytes).u16(255).u32(embedded.length).u32(blip.referenceCount).u32(0).u8(0).u8(0).u8(0).u8(0);
+	return escherAtom(2, fields.msoBlip, require_drawing_escher_constants.ESCHER_BSE, new require_biff_builder.RecordBuilder().bytes(fixed.build()).bytes(embedded).build());
+}
+function hexToBytes(hex) {
+	const out = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < out.length; index += 1) out[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	return out;
+}
+/**
+* The workbook-wide OfficeArtDggContainer ([MS-ODRAW] 2.2.12, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f): a FDGGBlock (the FDGG atom plus one OfficeArtIDCL per drawing, cidcl = drawing count + 1 per 2.2.14's own field definition) followed by the Blip Store when the workbook carries any image. The DggContainer's own optional children this writer has no data for -- drawingPrimaryOptions, colorMRU, splitColors -- are omitted, which the container's own production permits.
+*/
+function writeDrawingGroupBytes(blips, drawings) {
+	const spidMax = drawings.reduce((max, drawing) => Math.max(max, drawing.lastSpid), 0);
+	const cspSaved = drawings.reduce((sum, drawing) => sum + drawing.shapeCount, 0);
+	const fdgg = new require_biff_builder.RecordBuilder().u32(spidMax).u32(drawings.length + 1).u32(cspSaved).u32(drawings.length);
+	for (const drawing of drawings) fdgg.u32(drawing.drawingId).u32(drawing.lastSpid);
+	const children = [escherAtom(0, 0, 61446, fdgg.build())];
+	if (blips.length > 0) children.push(escherContainer(require_drawing_escher_constants.ESCHER_BSTORE_CONTAINER, blips.length, blips.map((blip) => writeBseRecord(blip))));
+	return escherContainer(require_drawing_escher_constants.ESCHER_DGG_CONTAINER, 0, children);
+}
+const FSP_FLAG_OLE_SHAPE = 16;
+/** OfficeArtFSP ([MS-ODRAW] 2.2.40, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/8a7e7be3-0582-4461-9400-29d7eda8497d): recVer 0x2, recInstance carrying the shape's own MSOSPT type, then spid and the flags word. Every shape this writer states is a picture frame (MSOSPT 0x4B) -- a picture because it holds an image, an OLE object because [MS-ODRAW]'s own model hosts one through the picture machinery with fOleShape set. */
+function writeFspRecord(spid, flags, shapeType) {
+	return escherAtom(2, shapeType, require_drawing_escher_constants.ESCHER_SP, new require_biff_builder.RecordBuilder().u32(spid).u32(flags >>> 0).build());
+}
+/** OfficeArtFOPT ([MS-ODRAW] 2.2.9): recVer 0x3, recInstance carrying the property count, then that many 6-byte FOPTE entries (opid, op). The one property this writer states is `pib` -- the picture's own 1-based Blip Store index, opid 0x0104 with fComplex clear. */
+function writePibOptRecord(blipIndex) {
+	return escherAtom(3, 1, require_drawing_escher_constants.ESCHER_OPT, new require_biff_builder.RecordBuilder().u16(260).u32(blipIndex).build());
+}
+/** OfficeArtClientAnchorSheet ([MS-XLS] 2.5.193): recVer 0, recLen 18, a flags word (fMove and fSize both set -- the shape moves and sizes with its cells, the behaviour an image anchored to cells means), then the corner-cell-plus-fractional-offset pair -- eight u16 fields, 18 bytes total (2 for flags + 8*2), matching the record's own declared recLen and drawing/shapes.ts's own readClientAnchor, which reads each of dxL/dyT/dxR/dyB as a 2-byte i16, not a 4-byte i32. dxL/dxR are 1/1024ths of their column's own width, dyT/dyB 1/256ths of their row's own height, both always non-negative in this writer's own range (0-1023, 0-255), so the identical bit pattern u16 writes here is what i16 reads back unchanged. */
+function writeClientAnchorRecord(anchor) {
+	return escherAtom(0, 0, require_drawing_escher_constants.ESCHER_CLIENT_ANCHOR, new require_biff_builder.RecordBuilder().u16(3).u16(anchor.colL).u16(anchor.dxL).u16(anchor.rwT).u16(anchor.dyT).u16(anchor.colR).u16(anchor.dxR).u16(anchor.rwB).u16(anchor.dyB).build());
+}
+/** OfficeArtClientData: an empty atom (recLen 0) whose presence is what tells a reader that the next BIFF record after the MsoDrawing is this shape's own Obj record -- see [MS-XLS] MsoDrawing's own prose, cited on ESCHER_CLIENT_DATA above. */
+function writeClientDataRecord() {
+	return escherAtom(0, 0, require_drawing_escher_constants.ESCHER_CLIENT_DATA, /* @__PURE__ */ new Uint8Array(0));
+}
+/** One shape's own SpContainer ([MS-ODRAW] 2.2.14, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/16194cb9-b4b0-476c-9678-a6ac1f06b034): shapeProp (the FSP), then shapePrimaryOptions only for a picture (the pib property table), then the clientAnchor and the clientData -- the reader's own SpContainer walk reads exactly these atoms and no others. */
+function writeShapeContainer(spid, entry) {
+	const children = [writeFspRecord(spid, (entry.oleShape ? FSP_FLAG_OLE_SHAPE : 0) | 2560, 75)];
+	if (entry.blipIndex !== void 0) children.push(writePibOptRecord(entry.blipIndex));
+	children.push(writeClientAnchorRecord(entry.anchor), writeClientDataRecord());
+	return escherContainer(require_drawing_escher_constants.ESCHER_SP_CONTAINER, 0, children);
+}
+/**
+* One worksheet's own OfficeArtDgContainer: the FDG atom (recInstance carrying the drawing identifier, csp counting the patriarch alongside every real shape, spidCur the last shape id this drawing allocated), then the one SpgrContainer holding the patriarch -- an SpContainer whose FSPGR states the all-zero coordinate rectangle and whose FSP carries fGroup|fPatriarch -- followed by one SpContainer per real shape in document order, the order the sheet's Obj records then pair with 1:1. `spidBase` is the first unallocated shape id of the whole drawing group (1024 for the first sheet carrying shapes, Excel's own convention): the patriarch takes it, the real shapes take the following ids, and the caller continues allocating from the returned drawing's own lastSpid.
+*
+* The DgContainer's own further optional children (a SolverContainer, deleted shapes) are omitted: this writer states no solver rules and no deleted shapes, which the container's own production permits.
+*/
+function writeSheetDrawingBytes(drawingId, spidBase, entries) {
+	const lastSpid = spidBase + entries.length;
+	const fdg = escherAtom(0, drawingId, 61448, new require_biff_builder.RecordBuilder().u32(entries.length + 1).u32(lastSpid).build());
+	const patriarch = escherContainer(require_drawing_escher_constants.ESCHER_SP_CONTAINER, 0, [escherAtom(0, 0, require_drawing_escher_constants.ESCHER_FSPGR, /* @__PURE__ */ new Uint8Array(16)), writeFspRecord(spidBase, 5, 0)]);
+	const spgr = escherContainer(require_drawing_escher_constants.ESCHER_SPGR_CONTAINER, 0, [patriarch, ...entries.map((entry, index) => writeShapeContainer(spidBase + index + 1, entry))]);
+	return escherContainer(require_drawing_escher_constants.ESCHER_DG_CONTAINER, 0, [fdg, spgr]);
+}
+//#endregion
+exports.writeDrawingGroupBytes = writeDrawingGroupBytes;
+exports.writeSheetDrawingBytes = writeSheetDrawingBytes;

package/dist/drawing/escher-writer.d.cts

@@ -0,0 +1,32 @@
+import { ShapeAnchor } from "./shapes.cjs";
+//#region src/drawing/escher-writer.d.ts
+/** One distinct image the workbook's sheets share: its decoded bytes, and how many picture shapes reference it (the FBSE's own cRef, which [MS-ODRAW] defines as the number of references to the BLIP). */
+interface StoredBlip {
+  readonly format: "png" | "jpeg";
+  readonly fileBytes: Uint8Array<ArrayBuffer>;
+  readonly referenceCount: number;
+}
+/** One drawing's own contribution to the drawing group's shape-id state: the drawing identifier its FDG and IDCL both name, and the last shape identifier it allocated. */
+interface DrawingIdBlock {
+  readonly drawingId: number;
+  readonly lastSpid: number;
+  readonly shapeCount: number;
+}
+/**
+ * The workbook-wide OfficeArtDggContainer ([MS-ODRAW] 2.2.12, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f): a FDGGBlock (the FDGG atom plus one OfficeArtIDCL per drawing, cidcl = drawing count + 1 per 2.2.14's own field definition) followed by the Blip Store when the workbook carries any image. The DggContainer's own optional children this writer has no data for -- drawingPrimaryOptions, colorMRU, splitColors -- are omitted, which the container's own production permits.
+ */
+declare function writeDrawingGroupBytes(blips: readonly StoredBlip[], drawings: readonly DrawingIdBlock[]): Uint8Array<ArrayBuffer>;
+/** One real (non-patriarch) shape this writer places on a sheet: its anchor, its 1-based Blip Store reference when it is a picture, and whether it hosts an embedded OLE object (which sets FSP's own fOleShape and takes no pib). */
+interface SheetShapeEntry {
+  readonly anchor: ShapeAnchor;
+  readonly blipIndex: number | undefined;
+  readonly oleShape: boolean;
+}
+/**
+ * One worksheet's own OfficeArtDgContainer: the FDG atom (recInstance carrying the drawing identifier, csp counting the patriarch alongside every real shape, spidCur the last shape id this drawing allocated), then the one SpgrContainer holding the patriarch -- an SpContainer whose FSPGR states the all-zero coordinate rectangle and whose FSP carries fGroup|fPatriarch -- followed by one SpContainer per real shape in document order, the order the sheet's Obj records then pair with 1:1. `spidBase` is the first unallocated shape id of the whole drawing group (1024 for the first sheet carrying shapes, Excel's own convention): the patriarch takes it, the real shapes take the following ids, and the caller continues allocating from the returned drawing's own lastSpid.
+ *
+ * The DgContainer's own further optional children (a SolverContainer, deleted shapes) are omitted: this writer states no solver rules and no deleted shapes, which the container's own production permits.
+ */
+declare function writeSheetDrawingBytes(drawingId: number, spidBase: number, entries: readonly SheetShapeEntry[]): Uint8Array<ArrayBuffer>;
+//#endregion
+export { DrawingIdBlock, SheetShapeEntry, StoredBlip, writeDrawingGroupBytes, writeSheetDrawingBytes };

package/dist/drawing/escher-writer.d.ts

@@ -0,0 +1,32 @@
+import { ShapeAnchor } from "./shapes.js";
+//#region src/drawing/escher-writer.d.ts
+/** One distinct image the workbook's sheets share: its decoded bytes, and how many picture shapes reference it (the FBSE's own cRef, which [MS-ODRAW] defines as the number of references to the BLIP). */
+interface StoredBlip {
+  readonly format: "png" | "jpeg";
+  readonly fileBytes: Uint8Array<ArrayBuffer>;
+  readonly referenceCount: number;
+}
+/** One drawing's own contribution to the drawing group's shape-id state: the drawing identifier its FDG and IDCL both name, and the last shape identifier it allocated. */
+interface DrawingIdBlock {
+  readonly drawingId: number;
+  readonly lastSpid: number;
+  readonly shapeCount: number;
+}
+/**
+ * The workbook-wide OfficeArtDggContainer ([MS-ODRAW] 2.2.12, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f): a FDGGBlock (the FDGG atom plus one OfficeArtIDCL per drawing, cidcl = drawing count + 1 per 2.2.14's own field definition) followed by the Blip Store when the workbook carries any image. The DggContainer's own optional children this writer has no data for -- drawingPrimaryOptions, colorMRU, splitColors -- are omitted, which the container's own production permits.
+ */
+declare function writeDrawingGroupBytes(blips: readonly StoredBlip[], drawings: readonly DrawingIdBlock[]): Uint8Array<ArrayBuffer>;
+/** One real (non-patriarch) shape this writer places on a sheet: its anchor, its 1-based Blip Store reference when it is a picture, and whether it hosts an embedded OLE object (which sets FSP's own fOleShape and takes no pib). */
+interface SheetShapeEntry {
+  readonly anchor: ShapeAnchor;
+  readonly blipIndex: number | undefined;
+  readonly oleShape: boolean;
+}
+/**
+ * One worksheet's own OfficeArtDgContainer: the FDG atom (recInstance carrying the drawing identifier, csp counting the patriarch alongside every real shape, spidCur the last shape id this drawing allocated), then the one SpgrContainer holding the patriarch -- an SpContainer whose FSPGR states the all-zero coordinate rectangle and whose FSP carries fGroup|fPatriarch -- followed by one SpContainer per real shape in document order, the order the sheet's Obj records then pair with 1:1. `spidBase` is the first unallocated shape id of the whole drawing group (1024 for the first sheet carrying shapes, Excel's own convention): the patriarch takes it, the real shapes take the following ids, and the caller continues allocating from the returned drawing's own lastSpid.
+ *
+ * The DgContainer's own further optional children (a SolverContainer, deleted shapes) are omitted: this writer states no solver rules and no deleted shapes, which the container's own production permits.
+ */
+declare function writeSheetDrawingBytes(drawingId: number, spidBase: number, entries: readonly SheetShapeEntry[]): Uint8Array<ArrayBuffer>;
+//#endregion
+export { DrawingIdBlock, SheetShapeEntry, StoredBlip, writeDrawingGroupBytes, writeSheetDrawingBytes };

package/dist/drawing/escher-writer.js

@@ -0,0 +1,105 @@
+import { RecordBuilder } from "../biff/builder.js";
+import { BiffWriteError } from "../biff/write-errors.js";
+import { ESCHER_BSE, ESCHER_BSTORE_CONTAINER, ESCHER_CLIENT_ANCHOR, ESCHER_CLIENT_DATA, ESCHER_DGG_CONTAINER, ESCHER_DG_CONTAINER, ESCHER_FSPGR, ESCHER_OPT, ESCHER_SP, ESCHER_SPGR_CONTAINER, ESCHER_SP_CONTAINER } from "./escher-constants.js";
+import { md4 } from "./md4.js";
+//#region src/drawing/escher-writer.ts
+/** One Escher atom's own bytes: header plus `data` verbatim. */
+function escherAtom(recVer, recInstance, recType, data) {
+	return new RecordBuilder().u16(recVer & 15 | (recInstance & 4095) << 4).u16(recType).u32(data.length).bytes(data).build();
+}
+/** One Escher container's own bytes: header (recVer 0xF, [MS-ODRAW] 2.2.1's container marker, in the verInstance word's low nibble) plus its children concatenated -- recLen is then the children's total size with their own headers included, exactly what the format defines. `recInstance` is the verInstance word's upper 12 bits, which every container this writer states pins to 0x000 except the Blip Store, whose own page requires the count of BSE children. */
+function escherContainer(recType, recInstance, children) {
+	const body = children.reduce((sum, child) => sum + child.length, 0);
+	const builder = new RecordBuilder().u16(15 | (recInstance & 4095) << 4).u16(recType).u32(body);
+	for (const child of children) builder.bytes(child);
+	return builder.build();
+}
+const MSOBLIP_JPEG = 5;
+const MSOBLIP_PNG = 6;
+const BLIP_PNG_RECTYPE = 61470;
+const BLIP_JPEG_RECTYPE = 61469;
+const BLIP_PNG_INSTANCE_ONE_UID = 1760;
+const BLIP_JPEG_INSTANCE_ONE_UID = 1130;
+/** rgbUid's own fixed size: [MS-ODRAW]'s FBSE and Blip records each open with one 16-byte MD4 digest of the image data. */
+const UID_SIZE = 16;
+function blipFormatFields(format) {
+	if (format === "png") return {
+		msoBlip: MSOBLIP_PNG,
+		recType: BLIP_PNG_RECTYPE,
+		recInstance: BLIP_PNG_INSTANCE_ONE_UID
+	};
+	return {
+		msoBlip: MSOBLIP_JPEG,
+		recType: BLIP_JPEG_RECTYPE,
+		recInstance: BLIP_JPEG_INSTANCE_ONE_UID
+	};
+}
+/** One OfficeArtBlipPNG/JPEG record ([MS-ODRAW] 2.2.28/2.2.27): one rgbUid (the MD4 of the file bytes -- a digest of the UNCOMPRESSED blip data per 2.2.28's own field text, which for PNG and JPEG is the file bytes themselves), the tag byte, then the literal file bytes. The tag byte is 0xFF, "internal resource tag" -- the value real producers write for data embedded in the record. */
+function writeBlipRecord(format, uidBytes, fileBytes) {
+	const fields = blipFormatFields(format);
+	return escherAtom(0, fields.recInstance, fields.recType, new RecordBuilder().bytes(uidBytes).u8(255).bytes(fileBytes).build());
+}
+/** One OfficeArtFBSE ([MS-ODRAW] 2.2.24.1, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/2f2d7f5e-d5c4-4cb7-b230-59b3fe8f10d6): the blip's type pair, its rgbUid, a tag, the embedded blip record's own total size, the reference count, a foDelay this writer always states as "not in a delay stream" alongside an inline embeddedBlip (which [MS-ODRAW] says makes foDelay ignored), the name-length byte (0 -- no name), and the embedded blip record itself. recLen's own rule -- "the size of nameData plus size plus 36" for an embedded blip -- falls out of the fixed fields plus the blip record's length. */
+function writeBseRecord(blip) {
+	const fields = blipFormatFields(blip.format);
+	const uidBytes = hexToBytes(md4(blip.fileBytes));
+	if (uidBytes.length !== UID_SIZE) throw new BiffWriteError(`internal error: md4 produced a ${uidBytes.length}-byte digest, not the ${UID_SIZE} bytes rgbUid ([MS-ODRAW]'s own FBSE/Blip field) requires`);
+	const embedded = writeBlipRecord(blip.format, uidBytes, blip.fileBytes);
+	const fixed = new RecordBuilder().u8(fields.msoBlip).u8(fields.msoBlip).bytes(uidBytes).u16(255).u32(embedded.length).u32(blip.referenceCount).u32(0).u8(0).u8(0).u8(0).u8(0);
+	return escherAtom(2, fields.msoBlip, ESCHER_BSE, new RecordBuilder().bytes(fixed.build()).bytes(embedded).build());
+}
+function hexToBytes(hex) {
+	const out = new Uint8Array(hex.length / 2);
+	for (let index = 0; index < out.length; index += 1) out[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+	return out;
+}
+/**
+* The workbook-wide OfficeArtDggContainer ([MS-ODRAW] 2.2.12, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f): a FDGGBlock (the FDGG atom plus one OfficeArtIDCL per drawing, cidcl = drawing count + 1 per 2.2.14's own field definition) followed by the Blip Store when the workbook carries any image. The DggContainer's own optional children this writer has no data for -- drawingPrimaryOptions, colorMRU, splitColors -- are omitted, which the container's own production permits.
+*/
+function writeDrawingGroupBytes(blips, drawings) {
+	const spidMax = drawings.reduce((max, drawing) => Math.max(max, drawing.lastSpid), 0);
+	const cspSaved = drawings.reduce((sum, drawing) => sum + drawing.shapeCount, 0);
+	const fdgg = new RecordBuilder().u32(spidMax).u32(drawings.length + 1).u32(cspSaved).u32(drawings.length);
+	for (const drawing of drawings) fdgg.u32(drawing.drawingId).u32(drawing.lastSpid);
+	const children = [escherAtom(0, 0, 61446, fdgg.build())];
+	if (blips.length > 0) children.push(escherContainer(ESCHER_BSTORE_CONTAINER, blips.length, blips.map((blip) => writeBseRecord(blip))));
+	return escherContainer(ESCHER_DGG_CONTAINER, 0, children);
+}
+const FSP_FLAG_OLE_SHAPE = 16;
+/** OfficeArtFSP ([MS-ODRAW] 2.2.40, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/8a7e7be3-0582-4461-9400-29d7eda8497d): recVer 0x2, recInstance carrying the shape's own MSOSPT type, then spid and the flags word. Every shape this writer states is a picture frame (MSOSPT 0x4B) -- a picture because it holds an image, an OLE object because [MS-ODRAW]'s own model hosts one through the picture machinery with fOleShape set. */
+function writeFspRecord(spid, flags, shapeType) {
+	return escherAtom(2, shapeType, ESCHER_SP, new RecordBuilder().u32(spid).u32(flags >>> 0).build());
+}
+/** OfficeArtFOPT ([MS-ODRAW] 2.2.9): recVer 0x3, recInstance carrying the property count, then that many 6-byte FOPTE entries (opid, op). The one property this writer states is `pib` -- the picture's own 1-based Blip Store index, opid 0x0104 with fComplex clear. */
+function writePibOptRecord(blipIndex) {
+	return escherAtom(3, 1, ESCHER_OPT, new RecordBuilder().u16(260).u32(blipIndex).build());
+}
+/** OfficeArtClientAnchorSheet ([MS-XLS] 2.5.193): recVer 0, recLen 18, a flags word (fMove and fSize both set -- the shape moves and sizes with its cells, the behaviour an image anchored to cells means), then the corner-cell-plus-fractional-offset pair -- eight u16 fields, 18 bytes total (2 for flags + 8*2), matching the record's own declared recLen and drawing/shapes.ts's own readClientAnchor, which reads each of dxL/dyT/dxR/dyB as a 2-byte i16, not a 4-byte i32. dxL/dxR are 1/1024ths of their column's own width, dyT/dyB 1/256ths of their row's own height, both always non-negative in this writer's own range (0-1023, 0-255), so the identical bit pattern u16 writes here is what i16 reads back unchanged. */
+function writeClientAnchorRecord(anchor) {
+	return escherAtom(0, 0, ESCHER_CLIENT_ANCHOR, new RecordBuilder().u16(3).u16(anchor.colL).u16(anchor.dxL).u16(anchor.rwT).u16(anchor.dyT).u16(anchor.colR).u16(anchor.dxR).u16(anchor.rwB).u16(anchor.dyB).build());
+}
+/** OfficeArtClientData: an empty atom (recLen 0) whose presence is what tells a reader that the next BIFF record after the MsoDrawing is this shape's own Obj record -- see [MS-XLS] MsoDrawing's own prose, cited on ESCHER_CLIENT_DATA above. */
+function writeClientDataRecord() {
+	return escherAtom(0, 0, ESCHER_CLIENT_DATA, /* @__PURE__ */ new Uint8Array(0));
+}
+/** One shape's own SpContainer ([MS-ODRAW] 2.2.14, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/16194cb9-b4b0-476c-9678-a6ac1f06b034): shapeProp (the FSP), then shapePrimaryOptions only for a picture (the pib property table), then the clientAnchor and the clientData -- the reader's own SpContainer walk reads exactly these atoms and no others. */
+function writeShapeContainer(spid, entry) {
+	const children = [writeFspRecord(spid, (entry.oleShape ? FSP_FLAG_OLE_SHAPE : 0) | 2560, 75)];
+	if (entry.blipIndex !== void 0) children.push(writePibOptRecord(entry.blipIndex));
+	children.push(writeClientAnchorRecord(entry.anchor), writeClientDataRecord());
+	return escherContainer(ESCHER_SP_CONTAINER, 0, children);
+}
+/**
+* One worksheet's own OfficeArtDgContainer: the FDG atom (recInstance carrying the drawing identifier, csp counting the patriarch alongside every real shape, spidCur the last shape id this drawing allocated), then the one SpgrContainer holding the patriarch -- an SpContainer whose FSPGR states the all-zero coordinate rectangle and whose FSP carries fGroup|fPatriarch -- followed by one SpContainer per real shape in document order, the order the sheet's Obj records then pair with 1:1. `spidBase` is the first unallocated shape id of the whole drawing group (1024 for the first sheet carrying shapes, Excel's own convention): the patriarch takes it, the real shapes take the following ids, and the caller continues allocating from the returned drawing's own lastSpid.
+*
+* The DgContainer's own further optional children (a SolverContainer, deleted shapes) are omitted: this writer states no solver rules and no deleted shapes, which the container's own production permits.
+*/
+function writeSheetDrawingBytes(drawingId, spidBase, entries) {
+	const lastSpid = spidBase + entries.length;
+	const fdg = escherAtom(0, drawingId, 61448, new RecordBuilder().u32(entries.length + 1).u32(lastSpid).build());
+	const patriarch = escherContainer(ESCHER_SP_CONTAINER, 0, [escherAtom(0, 0, ESCHER_FSPGR, /* @__PURE__ */ new Uint8Array(16)), writeFspRecord(spidBase, 5, 0)]);
+	const spgr = escherContainer(ESCHER_SPGR_CONTAINER, 0, [patriarch, ...entries.map((entry, index) => writeShapeContainer(spidBase + index + 1, entry))]);
+	return escherContainer(ESCHER_DG_CONTAINER, 0, [fdg, spgr]);
+}
+//#endregion
+export { writeDrawingGroupBytes, writeSheetDrawingBytes };

package/dist/drawing/md4.cjs

@@ -0,0 +1,146 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/drawing/md4.ts
+/** RFC 1320 3.3's own round constants: "0x5A827999" and "0x6ED9EBA1", the integer parts the spec spells out for rounds 2 and 3. */
+const ROUND_2_CONSTANT = 1518500249;
+const ROUND_3_CONSTANT = 1859775393;
+/** RFC 1320 2.2: "Let A = 0x67452301, B = 0xefcdab89, C = 0x98badcfe, D = 0x10325476". */
+const INITIAL_A = 1732584193;
+const INITIAL_B = 4023233417;
+const INITIAL_C = 2562383102;
+const INITIAL_D = 271733878;
+const BLOCK_SIZE = 64;
+/** The three auxiliary functions of RFC 1320 2.2, each a bit-selection over x/y/z -- G and H are MD4's own, not MD5's similarly-named ones. */
+function f(x, y, z) {
+	return x & y | ~x & z;
+}
+function g(x, y, z) {
+	return x & y | x & z | y & z;
+}
+function h(x, y, z) {
+	return x ^ y ^ z;
+}
+/** A 32-bit rotate left; the final >>> 0 keeps the result unsigned where << would sign it. */
+function rotateLeft(x, count) {
+	return (x << count | x >>> 32 - count) >>> 0;
+}
+/** The padding of RFC 1320 3.1: the message, a single 1 bit, zeros, then the 64-bit little-endian bit length, filling the final block(s) to a 64-byte multiple. */
+function padMessage(message) {
+	const bitLength = message.length * 8;
+	const paddedLength = Math.ceil((message.length + 1 + 8) / BLOCK_SIZE) * BLOCK_SIZE;
+	const out = new Uint8Array(paddedLength);
+	out.set(message);
+	out[message.length] = 128;
+	const view = new DataView(out.buffer);
+	view.setUint32(paddedLength - 8, bitLength >>> 0, true);
+	view.setUint32(paddedLength - 4, Math.floor(bitLength / 4294967296), true);
+	return out;
+}
+/** RFC 1320 A.3's register rotation, restated once: after an operation updates the frame's first register, the frame rotates right so the next operation's target is first again -- exactly the ABCD/DABC/CDAB/BCDA cycling the printed schedule shows. */
+function rotateRegisters(frame, updated) {
+	return [
+		frame[3],
+		updated,
+		frame[1],
+		frame[2]
+	];
+}
+/**
+* The MD4 digest of `message`, as 32 lowercase hex characters -- the digest bytes in order, which RFC 1320 3.5 states begin with the LOW-order byte of A ("beginning with the low-order byte of A, and ending with the high-order byte of D"), so each register is emitted little-endian rather than as a big-endian hex word.
+*/
+function md4(message) {
+	const padded = padMessage(message);
+	const view = new DataView(padded.buffer, padded.byteOffset, padded.byteLength);
+	let a = INITIAL_A;
+	let b = INITIAL_B;
+	let c = INITIAL_C;
+	let d = INITIAL_D;
+	for (let offset = 0; offset < padded.length; offset += BLOCK_SIZE) {
+		const x = [];
+		for (let index = 0; index < 16; index += 1) x.push(view.getUint32(offset + index * 4, true));
+		const savedA = a;
+		const savedB = b;
+		const savedC = c;
+		const savedD = d;
+		const op = (kind, index, rotation, roundConstant) => {
+			const word = x[index];
+			if (word === void 0) throw new Error(`internal error: MD4 block word ${index} is missing -- x is always filled with all 16 words above before any operation reads it`);
+			const updated = rotateLeft(a + kind(b, c, d) + word + roundConstant >>> 0, rotation);
+			[a, b, c, d] = rotateRegisters([
+				a,
+				b,
+				c,
+				d
+			], updated);
+		};
+		const ff = (index, rotation) => {
+			op(f, index, rotation, 0);
+		};
+		const gg = (index, rotation) => {
+			op(g, index, rotation, ROUND_2_CONSTANT);
+		};
+		const hh = (index, rotation) => {
+			op(h, index, rotation, ROUND_3_CONSTANT);
+		};
+		ff(0, 3);
+		ff(1, 7);
+		ff(2, 11);
+		ff(3, 19);
+		ff(4, 3);
+		ff(5, 7);
+		ff(6, 11);
+		ff(7, 19);
+		ff(8, 3);
+		ff(9, 7);
+		ff(10, 11);
+		ff(11, 19);
+		ff(12, 3);
+		ff(13, 7);
+		ff(14, 11);
+		ff(15, 19);
+		gg(0, 3);
+		gg(4, 5);
+		gg(8, 9);
+		gg(12, 13);
+		gg(1, 3);
+		gg(5, 5);
+		gg(9, 9);
+		gg(13, 13);
+		gg(2, 3);
+		gg(6, 5);
+		gg(10, 9);
+		gg(14, 13);
+		gg(3, 3);
+		gg(7, 5);
+		gg(11, 9);
+		gg(15, 13);
+		hh(0, 3);
+		hh(8, 9);
+		hh(4, 11);
+		hh(12, 15);
+		hh(2, 3);
+		hh(10, 9);
+		hh(6, 11);
+		hh(14, 15);
+		hh(1, 3);
+		hh(9, 9);
+		hh(5, 11);
+		hh(13, 15);
+		hh(3, 3);
+		hh(11, 9);
+		hh(7, 11);
+		hh(15, 15);
+		a = a + savedA >>> 0;
+		b = b + savedB >>> 0;
+		c = c + savedC >>> 0;
+		d = d + savedD >>> 0;
+	}
+	const out = /* @__PURE__ */ new Uint8Array(16);
+	const outView = new DataView(out.buffer);
+	outView.setUint32(0, a >>> 0, true);
+	outView.setUint32(4, b >>> 0, true);
+	outView.setUint32(8, c >>> 0, true);
+	outView.setUint32(12, d >>> 0, true);
+	return Array.from(out, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+exports.md4 = md4;

package/dist/drawing/md4.d.cts

@@ -0,0 +1,7 @@
+//#region src/drawing/md4.d.ts
+/**
+ * The MD4 digest of `message`, as 32 lowercase hex characters -- the digest bytes in order, which RFC 1320 3.5 states begin with the LOW-order byte of A ("beginning with the low-order byte of A, and ending with the high-order byte of D"), so each register is emitted little-endian rather than as a big-endian hex word.
+ */
+declare function md4(message: Uint8Array<ArrayBuffer>): string;
+//#endregion
+export { md4 };

package/dist/drawing/md4.d.ts

@@ -0,0 +1,7 @@
+//#region src/drawing/md4.d.ts
+/**
+ * The MD4 digest of `message`, as 32 lowercase hex characters -- the digest bytes in order, which RFC 1320 3.5 states begin with the LOW-order byte of A ("beginning with the low-order byte of A, and ending with the high-order byte of D"), so each register is emitted little-endian rather than as a big-endian hex word.
+ */
+declare function md4(message: Uint8Array<ArrayBuffer>): string;
+//#endregion
+export { md4 };

package/dist/drawing/md4.js

@@ -0,0 +1,145 @@
+//#region src/drawing/md4.ts
+/** RFC 1320 3.3's own round constants: "0x5A827999" and "0x6ED9EBA1", the integer parts the spec spells out for rounds 2 and 3. */
+const ROUND_2_CONSTANT = 1518500249;
+const ROUND_3_CONSTANT = 1859775393;
+/** RFC 1320 2.2: "Let A = 0x67452301, B = 0xefcdab89, C = 0x98badcfe, D = 0x10325476". */
+const INITIAL_A = 1732584193;
+const INITIAL_B = 4023233417;
+const INITIAL_C = 2562383102;
+const INITIAL_D = 271733878;
+const BLOCK_SIZE = 64;
+/** The three auxiliary functions of RFC 1320 2.2, each a bit-selection over x/y/z -- G and H are MD4's own, not MD5's similarly-named ones. */
+function f(x, y, z) {
+	return x & y | ~x & z;
+}
+function g(x, y, z) {
+	return x & y | x & z | y & z;
+}
+function h(x, y, z) {
+	return x ^ y ^ z;
+}
+/** A 32-bit rotate left; the final >>> 0 keeps the result unsigned where << would sign it. */
+function rotateLeft(x, count) {
+	return (x << count | x >>> 32 - count) >>> 0;
+}
+/** The padding of RFC 1320 3.1: the message, a single 1 bit, zeros, then the 64-bit little-endian bit length, filling the final block(s) to a 64-byte multiple. */
+function padMessage(message) {
+	const bitLength = message.length * 8;
+	const paddedLength = Math.ceil((message.length + 1 + 8) / BLOCK_SIZE) * BLOCK_SIZE;
+	const out = new Uint8Array(paddedLength);
+	out.set(message);
+	out[message.length] = 128;
+	const view = new DataView(out.buffer);
+	view.setUint32(paddedLength - 8, bitLength >>> 0, true);
+	view.setUint32(paddedLength - 4, Math.floor(bitLength / 4294967296), true);
+	return out;
+}
+/** RFC 1320 A.3's register rotation, restated once: after an operation updates the frame's first register, the frame rotates right so the next operation's target is first again -- exactly the ABCD/DABC/CDAB/BCDA cycling the printed schedule shows. */
+function rotateRegisters(frame, updated) {
+	return [
+		frame[3],
+		updated,
+		frame[1],
+		frame[2]
+	];
+}
+/**
+* The MD4 digest of `message`, as 32 lowercase hex characters -- the digest bytes in order, which RFC 1320 3.5 states begin with the LOW-order byte of A ("beginning with the low-order byte of A, and ending with the high-order byte of D"), so each register is emitted little-endian rather than as a big-endian hex word.
+*/
+function md4(message) {
+	const padded = padMessage(message);
+	const view = new DataView(padded.buffer, padded.byteOffset, padded.byteLength);
+	let a = INITIAL_A;
+	let b = INITIAL_B;
+	let c = INITIAL_C;
+	let d = INITIAL_D;
+	for (let offset = 0; offset < padded.length; offset += BLOCK_SIZE) {
+		const x = [];
+		for (let index = 0; index < 16; index += 1) x.push(view.getUint32(offset + index * 4, true));
+		const savedA = a;
+		const savedB = b;
+		const savedC = c;
+		const savedD = d;
+		const op = (kind, index, rotation, roundConstant) => {
+			const word = x[index];
+			if (word === void 0) throw new Error(`internal error: MD4 block word ${index} is missing -- x is always filled with all 16 words above before any operation reads it`);
+			const updated = rotateLeft(a + kind(b, c, d) + word + roundConstant >>> 0, rotation);
+			[a, b, c, d] = rotateRegisters([
+				a,
+				b,
+				c,
+				d
+			], updated);
+		};
+		const ff = (index, rotation) => {
+			op(f, index, rotation, 0);
+		};
+		const gg = (index, rotation) => {
+			op(g, index, rotation, ROUND_2_CONSTANT);
+		};
+		const hh = (index, rotation) => {
+			op(h, index, rotation, ROUND_3_CONSTANT);
+		};
+		ff(0, 3);
+		ff(1, 7);
+		ff(2, 11);
+		ff(3, 19);
+		ff(4, 3);
+		ff(5, 7);
+		ff(6, 11);
+		ff(7, 19);
+		ff(8, 3);
+		ff(9, 7);
+		ff(10, 11);
+		ff(11, 19);
+		ff(12, 3);
+		ff(13, 7);
+		ff(14, 11);
+		ff(15, 19);
+		gg(0, 3);
+		gg(4, 5);
+		gg(8, 9);
+		gg(12, 13);
+		gg(1, 3);
+		gg(5, 5);
+		gg(9, 9);
+		gg(13, 13);
+		gg(2, 3);
+		gg(6, 5);
+		gg(10, 9);
+		gg(14, 13);
+		gg(3, 3);
+		gg(7, 5);
+		gg(11, 9);
+		gg(15, 13);
+		hh(0, 3);
+		hh(8, 9);
+		hh(4, 11);
+		hh(12, 15);
+		hh(2, 3);
+		hh(10, 9);
+		hh(6, 11);
+		hh(14, 15);
+		hh(1, 3);
+		hh(9, 9);
+		hh(5, 11);
+		hh(13, 15);
+		hh(3, 3);
+		hh(11, 9);
+		hh(7, 11);
+		hh(15, 15);
+		a = a + savedA >>> 0;
+		b = b + savedB >>> 0;
+		c = c + savedC >>> 0;
+		d = d + savedD >>> 0;
+	}
+	const out = /* @__PURE__ */ new Uint8Array(16);
+	const outView = new DataView(out.buffer);
+	outView.setUint32(0, a >>> 0, true);
+	outView.setUint32(4, b >>> 0, true);
+	outView.setUint32(8, c >>> 0, true);
+	outView.setUint32(12, d >>> 0, true);
+	return Array.from(out, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+//#endregion
+export { md4 };

package/dist/drawing-writer-Blm_NUSZ.d.cts

@@ -0,0 +1,19 @@
+import { ContentSheet } from "document-schema.js";
+//#region src/workbook/drawing-writer.d.ts
+/** One sheet's own drawing records, positioned into the worksheet substream's OBJECTS section by sheet-writer.ts. Empty arrays when the sheet carries no shapes at all -- a sheet with nothing to draw writes no MsoDrawing and no Obj, staying as minimal as it always was. */
+interface SheetDrawingWrite {
+  readonly msoDrawingRecords: readonly Uint8Array<ArrayBuffer>[];
+  readonly objRecords: readonly Uint8Array<ArrayBuffer>[];
+}
+/** The workbook-wide drawing plan: the drawing-group Escher bytes the globals substream's MsoDrawingGroup record carries (undefined when no sheet carries shapes, in which case no such record is written at all), one drawing write per sheet, and the Embedding Storage streams the outer compound file carries beside the Workbook stream. */
+interface DrawingWritePlan {
+  readonly drawingGroupBytes: Uint8Array<ArrayBuffer> | undefined;
+  readonly sheetDrawings: readonly SheetDrawingWrite[];
+  readonly embeddingStreams: readonly {
+    readonly path: string;
+    readonly bytes: Uint8Array<ArrayBuffer>;
+  }[];
+}
+declare function buildDrawingWritePlan(sheets: readonly ContentSheet[]): DrawingWritePlan;
+//#endregion
+export { SheetDrawingWrite as n, buildDrawingWritePlan as r, DrawingWritePlan as t };

package/dist/drawing-writer-Blm_NUSZ.d.ts

@@ -0,0 +1,19 @@
+import { ContentSheet } from "document-schema.js";
+//#region src/workbook/drawing-writer.d.ts
+/** One sheet's own drawing records, positioned into the worksheet substream's OBJECTS section by sheet-writer.ts. Empty arrays when the sheet carries no shapes at all -- a sheet with nothing to draw writes no MsoDrawing and no Obj, staying as minimal as it always was. */
+interface SheetDrawingWrite {
+  readonly msoDrawingRecords: readonly Uint8Array<ArrayBuffer>[];
+  readonly objRecords: readonly Uint8Array<ArrayBuffer>[];
+}
+/** The workbook-wide drawing plan: the drawing-group Escher bytes the globals substream's MsoDrawingGroup record carries (undefined when no sheet carries shapes, in which case no such record is written at all), one drawing write per sheet, and the Embedding Storage streams the outer compound file carries beside the Workbook stream. */
+interface DrawingWritePlan {
+  readonly drawingGroupBytes: Uint8Array<ArrayBuffer> | undefined;
+  readonly sheetDrawings: readonly SheetDrawingWrite[];
+  readonly embeddingStreams: readonly {
+    readonly path: string;
+    readonly bytes: Uint8Array<ArrayBuffer>;
+  }[];
+}
+declare function buildDrawingWritePlan(sheets: readonly ContentSheet[]): DrawingWritePlan;
+//#endregion
+export { SheetDrawingWrite as n, buildDrawingWritePlan as r, DrawingWritePlan as t };

package/dist/index.cjs

@@ -149,6 +149,7 @@ exports.writeCellXfRecord = require_biff_xf_writer.writeCellXfRecord;
 exports.writeFormatRecord = require_biff_xf_writer.writeFormatRecord;
 exports.writePaletteRecord = require_biff_xf_writer.writePaletteRecord;
 exports.writeRecord = require_biff_record_writer.writeRecord;
+exports.writeRecordChain = require_biff_record_writer.writeRecordChain;
 exports.writeRichExtendedString = require_biff_string_writer.writeRichExtendedString;
 exports.writeShortXLUnicodeString = require_biff_string_writer.writeShortXLUnicodeString;
 exports.writeStyleRecord = require_biff_xf_writer.writeStyleRecord;