xls-codec 4.14.0 → 4.15.0

package/dist/workbook/drawing-writer.js

@@ -0,0 +1,252 @@
+import "../biff/record-types.js";
+import { DEFAULT_COLUMN_WIDTH_CHARS, columnWidthToPoints } from "../units.js";
+import { RecordBuilder } from "../biff/builder.js";
+import { BiffWriteError } from "../biff/write-errors.js";
+import { writeRecord, writeRecordChain } from "../biff/record-writer.js";
+import { writeXLUnicodeStringNoCch } from "../biff/string-writer.js";
+import { writeEmbeddedObjectPackage } from "./embedded-object.js";
+import { writeDrawingGroupBytes, writeSheetDrawingBytes } from "../drawing/escher-writer.js";
+//#region src/workbook/drawing-writer.ts
+/** The sheet-grid geometry an anchor resolves against and inverts into, the write-side mirror of workbook/drawing.ts's own SheetGridGeometry: declared column widths/row heights with the same Excel "Normal" defaults beneath, so a shape written from a given placement reads back at the identical placement. Derived from the same constants (units.ts) the reader's own geometry uses, so the two cannot disagree about what an undeclared cell sizes. */
+var WriterGridGeometry = class {
+	columnWidths = /* @__PURE__ */ new Map();
+	rowHeights = /* @__PURE__ */ new Map();
+	defaultColumnWidthPt = columnWidthToPoints(DEFAULT_COLUMN_WIDTH_CHARS * 256);
+	constructor(sheet) {
+		for (const column of sheet.columns) if (column.widthPt !== void 0) this.columnWidths.set(column.index, column.widthPt);
+		for (const row of sheet.rows) if (row.heightPt !== void 0) this.rowHeights.set(row.index, row.heightPt);
+	}
+	columnWidthPt(index) {
+		return this.columnWidths.get(index) ?? this.defaultColumnWidthPt;
+	}
+	rowHeightPt(index) {
+		return this.rowHeights.get(index) ?? 15;
+	}
+	/** The absolute x of a column's own left edge -- the cumulative width of every column before it, the identical accumulation the reader's own geometry walks back down. */
+	xPt(column) {
+		let x = 0;
+		for (let index = 0; index < column; index += 1) x += this.columnWidthPt(index);
+		return x;
+	}
+	yPt(row) {
+		let y = 0;
+		for (let index = 0; index < row; index += 1) y += this.rowHeightPt(index);
+		return y;
+	}
+	/** Locates an absolute x as a column plus a 1/1024ths-of-that-column fraction, the pair OfficeArtClientAnchorSheet's own left/right corners state. A point beyond the grid's own last column clamps to that column's far edge: the grid has no column 256 to name, and a shape whose extent runs that far past the grid loses only the overflow, where refusing the workbook would lose the cells too -- the same trade a print range past the grid already draws (print-names.ts's clampToGrid). */
+	locateX(x) {
+		let left = 0;
+		for (let column = 0; column < 255; column += 1) {
+			const width = this.columnWidthPt(column);
+			if (x < left + width) return {
+				column,
+				fraction: Math.min(1023, Math.round((x - left) / width * 1024))
+			};
+			left += width;
+		}
+		return {
+			column: 255,
+			fraction: 1023
+		};
+	}
+	/** The row-axis counterpart: a row plus a 1/256ths-of-that-row fraction, clamped to the grid's own last row. */
+	locateY(y) {
+		let top = 0;
+		for (let row = 0; row < 65535; row += 1) {
+			const height = this.rowHeightPt(row);
+			if (y < top + height) return {
+				row,
+				fraction: Math.min(255, Math.round((y - top) / height * 256))
+			};
+			top += height;
+		}
+		return {
+			row: 65535,
+			fraction: 255
+		};
+	}
+};
+function placementOfImage(image, geometry) {
+	if (image.anchorRow > 65535 || image.anchorColumn > 255) throw new BiffWriteError(`a sheet image anchored at row ${image.anchorRow}, column ${image.anchorColumn} is outside BIFF8's own grid (rows 0-65535, columns 0-255); a .xls workbook cannot address the cell it names`);
+	return {
+		startXPt: geometry.xPt(image.anchorColumn) + image.offsetXPt,
+		startYPt: geometry.yPt(image.anchorRow) + image.offsetYPt,
+		widthPt: image.widthPt,
+		heightPt: image.heightPt
+	};
+}
+function placementOfEmbedded(embedded, geometry) {
+	return {
+		startXPt: embedded.anchorColumn !== void 0 && embedded.offsetXPt !== void 0 ? geometry.xPt(embedded.anchorColumn) + embedded.offsetXPt : embedded.frame.xPt,
+		startYPt: embedded.anchorRow !== void 0 && embedded.offsetYPt !== void 0 ? geometry.yPt(embedded.anchorRow) + embedded.offsetYPt : embedded.frame.yPt,
+		widthPt: embedded.frame.widthPt,
+		heightPt: embedded.frame.heightPt
+	};
+}
+/** Inverts a placement into the OfficeArtClientAnchorSheet corner pair the reader's own resolveAnchorPlacement turns back into that placement: each corner resolved to its containing cell and a 1/1024ths (columns) or 1/256ths (rows) fraction within it. */
+function anchorOf(placement, geometry) {
+	const start = geometry.locateX(placement.startXPt);
+	const end = geometry.locateX(placement.startXPt + placement.widthPt);
+	const top = geometry.locateY(placement.startYPt);
+	const bottom = geometry.locateY(placement.startYPt + placement.heightPt);
+	return {
+		colL: start.column,
+		dxL: start.fraction,
+		rwT: top.row,
+		dyT: top.fraction,
+		colR: end.column,
+		dxR: end.fraction,
+		rwB: bottom.row,
+		dyB: bottom.fraction
+	};
+}
+/** [MS-XLS] 2.5.213's own ot table: the Picture type both a plain image and an embedded OLE object carry -- an OLE object IS hosted through the picture machinery (its FtPictFmla naming the Embedding Storage its data lives in), which is exactly how the Embedding Storage page itself states the pairing ("cmo.ot equal to 8, pictFlags.fPrstm equal to 0, and pictFlags.fDde equal to 0"). */
+const OBJECT_TYPE_PICTURE = 8;
+/** FtCmo ([MS-XLS] 2.5.92, 22 bytes): ft 0x15, cb 0x12, the object type and id, then grbit and three unused dwords all written zero -- the identical shape comment-writer.ts writes for a Note, restated here with the object type as a parameter rather than shared across the two direction modules. */
+function writeFtCmo(ot, id) {
+	return new RecordBuilder().u16(21).u16(18).u16(ot).u16(id).u16(0).u32(0).u32(0).u32(0).build();
+}
+/** FtCf ([MS-XLS] 2.5.142, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/fc5bb3ce-8e35-4393-b22f-9cf54062a3a4): the clipboard format of the picture this object shows. 0xFFFF names "an unspecified format that is neither an enhanced metafile nor a bitmap" -- honest for a shape whose visible rendering is the blip the Escher layer itself carries and for an OLE object this writer has no preview metafile for. */
+function writeFtCf() {
+	return new RecordBuilder().u16(7).u16(2).u16(65535).build();
+}
+/** FtPioGrbit ([MS-XLS] 2.5.151, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/8eee0b3d-9d27-4294-85fc-a66ae8a361c9): a plain picture states fAutoPict (aspect preserved across views); an OLE embedding states no bits at all -- fPrstm and fDde stay clear, the pair the Embedding Storage page requires for storage-based object data. */
+function writeFtPioGrbit(autoPict) {
+	return new RecordBuilder().u16(8).u16(2).u16(autoPict ? 1 : 0).build();
+}
+/** The PtgTbl token byte an embedded object's ObjectParsedFormula carries ([MS-XLS] 2.5.198.92: ptg 0x02, class none) -- the spelling that tells a reader this picture's data lives in an Embedding Storage rather than a linked range. */
+const PTG_TBL = 2;
+/** The class name stated in an embedding's PictFmlaEmbedInfo: "Package" is what a genuine OLE Package embed carries, so a real OLE-aware consumer that cannot decode this package's own JSON payload still sees a recognisable, accurate class rather than an invented one -- the identical choice rtf-codec's own ObjectHeader makes for the same payload shape. */
+const EMBED_CLASS_NAME = "Package";
+/** FtPictFmla ([MS-XLS] 2.5.150, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/00f89d32-67b0-408e-9eaf-f4fecbddb089) for an embedded OLE object: the ObjFmla (cbFmla counting the ObjectParsedFormula, the PictFmlaEmbedInfo, and the padding -- even, per [MS-XLS] 2.5.187's own cbFmla rule), then lPosInCtlStm, the storage id the Embedding Storage's own MBD name is the eight-hex-digit spelling of. The ObjectParsedFormula is the one shape [MS-XLS] pins for an embedding: cce 5, rgce one PtgTbl followed by four undefined bytes. */
+function writeFtPictFmla(storageId) {
+	const formula = new RecordBuilder().u16(5).u32(0).u8(PTG_TBL).bytes(/* @__PURE__ */ new Uint8Array(4)).build();
+	const className = writeXLUnicodeStringNoCch(EMBED_CLASS_NAME);
+	const embedInfo = new RecordBuilder().u8(3).u8(className.length - 1).u8(0).bytes(className).build();
+	const fmlaBytes = new RecordBuilder().bytes(formula).bytes(embedInfo).build();
+	const data = new RecordBuilder().u16(fmlaBytes.length).bytes(fmlaBytes).u32(storageId).build();
+	return new RecordBuilder().u16(9).u16(data.length).bytes(data).build();
+}
+/** The trailing four reserved bytes every Obj not naming a list-box/dropdown object carries ([MS-XLS] 2.4.181's own reserved field: MUST be 0) -- the ftEnd marker a real sub-record walk terminates on. */
+const OBJ_RESERVED_END = /* @__PURE__ */ new Uint8Array(4);
+/** One picture shape's Obj record: FtCmo (ot Picture), FtCf, FtPioGrbit, and the trailing reserved field. No FtPictFmla -- the image's bytes live in the workbook's Blip Store, which the shape's own pib property names, leaving the Obj record itself nothing to locate. */
+function writePictureObjRecord(objectId) {
+	return writeRecord(93, new RecordBuilder().bytes(writeFtCmo(OBJECT_TYPE_PICTURE, objectId)).bytes(writeFtCf()).bytes(writeFtPioGrbit(true)).bytes(OBJ_RESERVED_END).build());
+}
+/** One embedded OLE object's Obj record: FtCmo (ot Picture), FtCf, FtPioGrbit (no bits -- storage-based, per the Embedding Storage page's own fPrstm/fDde requirement), the FtPictFmla naming the storage, and the trailing reserved field. */
+function writeEmbeddedObjRecord(objectId, storageId) {
+	return writeRecord(93, new RecordBuilder().bytes(writeFtCmo(OBJECT_TYPE_PICTURE, objectId)).bytes(writeFtCf()).bytes(writeFtPioGrbit(false)).bytes(writeFtPictFmla(storageId)).bytes(OBJ_RESERVED_END).build());
+}
+/** Base64's own character set, decoded by hand rather than through atob's DOM-string round trip -- mirroring drawing/blips.ts's own hand-written encoder, which exists for the identical reason: byte-exact, allocation-predictable, and identical in Node and a Workers isolate. */
+function bytesFromBase64(base64) {
+	const values = (/* @__PURE__ */ new Int8Array(256)).fill(-1);
+	"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".split("").forEach((char, index) => {
+		values[char.charCodeAt(0)] = index;
+	});
+	const padding = base64.endsWith("==") ? 2 : base64.endsWith("=") ? 1 : 0;
+	const out = new Uint8Array(base64.length / 4 * 3 - padding);
+	let buffer = 0;
+	let bits = 0;
+	let outIndex = 0;
+	for (const char of base64) {
+		const value = values[char.charCodeAt(0)];
+		if (value === void 0 || value < 0) continue;
+		buffer = buffer << 6 | value;
+		bits += 6;
+		if (bits >= 8) {
+			bits -= 8;
+			out[outIndex] = buffer >> bits & 255;
+			outIndex += 1;
+		}
+	}
+	return out;
+}
+function buildDrawingWritePlan(sheets) {
+	const blips = [];
+	const blipIndexByBase64 = /* @__PURE__ */ new Map();
+	const resolveBlip = (image) => {
+		if (image.format !== "png" && image.format !== "jpeg") throw new BiffWriteError(`xls-codec cannot write a sheet image of format "${image.format}": [MS-ODRAW]'s own MSOBLIPTYPE enumeration has no member for it, so no Blip Store entry can carry it`);
+		const existing = blipIndexByBase64.get(image.base64);
+		if (existing !== void 0) {
+			const blip = blips[existing - 1];
+			if (blip === void 0) throw new BiffWriteError("internal error: a blip index resolved that the workbook-wide image scan never assigned");
+			blip.referenceCount += 1;
+			return existing;
+		}
+		const index = blips.length + 1;
+		blipIndexByBase64.set(image.base64, index);
+		blips.push({
+			format: image.format,
+			fileBytes: bytesFromBase64(image.base64),
+			referenceCount: 1
+		});
+		return index;
+	};
+	let nextStorageId = 1;
+	const storageIdOf = () => {
+		const id = nextStorageId;
+		nextStorageId += 1;
+		return id;
+	};
+	let nextSpid = 1024;
+	let nextDrawingId = 1;
+	const drawingBlocks = [];
+	const sheetDrawings = [];
+	const embeddingStreams = [];
+	for (const sheet of sheets) {
+		const geometry = new WriterGridGeometry(sheet);
+		const entries = [];
+		const objRecords = [];
+		let nextObjectId = sheet.cells.filter((cell) => cell.comment !== void 0).length + 1;
+		for (const image of sheet.images) {
+			entries.push({
+				anchor: anchorOf(placementOfImage(image, geometry), geometry),
+				blipIndex: resolveBlip(image),
+				oleShape: false
+			});
+			objRecords.push(writePictureObjRecord(nextObjectId));
+			nextObjectId += 1;
+		}
+		for (const embedded of sheet.embeddedObjects ?? []) {
+			if (embedded.objectKind === "chart") throw new BiffWriteError("xls-codec cannot write a 'chart' embedded object: embedding one means writing a genuine BIFF8 chart substream -- the whole [MS-XLS] chart grammar its series data links drive -- which is a chart engine of its own rather than a container for the flattened series table the schema carries");
+			const storageId = storageIdOf();
+			entries.push({
+				anchor: anchorOf(placementOfEmbedded(embedded, geometry), geometry),
+				blipIndex: void 0,
+				oleShape: true
+			});
+			objRecords.push(writeEmbeddedObjRecord(nextObjectId, storageId));
+			nextObjectId += 1;
+			embeddingStreams.push({
+				path: `MBD${storageId.toString(16).toUpperCase().padStart(8, "0")}/Package`,
+				bytes: writeEmbeddedObjectPackage(embedded)
+			});
+		}
+		if (entries.length === 0) {
+			sheetDrawings.push({
+				msoDrawingRecords: [],
+				objRecords: []
+			});
+			continue;
+		}
+		const escherBytes = writeSheetDrawingBytes(nextDrawingId, nextSpid, entries);
+		drawingBlocks.push({
+			drawingId: nextDrawingId,
+			lastSpid: nextSpid + entries.length,
+			shapeCount: entries.length + 1
+		});
+		nextDrawingId += 1;
+		nextSpid += entries.length + 1;
+		sheetDrawings.push({
+			msoDrawingRecords: writeRecordChain(236, escherBytes),
+			objRecords
+		});
+	}
+	return {
+		drawingGroupBytes: drawingBlocks.length > 0 ? writeDrawingGroupBytes(blips, drawingBlocks) : void 0,
+		sheetDrawings,
+		embeddingStreams
+	};
+}
+//#endregion
+export { buildDrawingWritePlan };

package/dist/workbook/drawing.cjs

@@ -6,6 +6,7 @@ const require_drawing_bytes = require("../drawing/bytes.cjs");
 const require_workbook_comments = require("./comments.cjs");
 const require_drawing_shapes = require("../drawing/shapes.cjs");
 const require_workbook_chart = require("./chart.cjs");
+const require_workbook_embedded_object = require("./embedded-object.cjs");
 let document_schema_js = require("document-schema.js");
 //#region src/workbook/drawing.ts
 /** [MS-XLS] "FtCmo" ot enumeration, the values this reader routes on. */
@@ -69,8 +70,7 @@ function readSheetDrawing(worksheetRecords, context) {
 		const record = worksheetRecords[index];
 		if (record === void 0) continue;
 		if (record.type === 236) {
-			const block = record.blocks[0];
-			if (block !== void 0) drawingChunks.push(block);
+			drawingChunks.push(...record.blocks);
 			continue;
 		}
 		if (record.type === 93) {
@@ -79,7 +79,8 @@ function readSheetDrawing(worksheetRecords, context) {
 			objEntries.push({
 				ot,
 				offset: record.offset,
-				nextOffset
+				nextOffset,
+				group: record
 			});
 		}
 	}
@@ -98,6 +99,11 @@ function readSheetDrawing(worksheetRecords, context) {
 		const obj = objEntries[index];
 		if (shape === void 0 || obj === void 0 || obj.ot === OBJECT_TYPE_NOTE) continue;
 		if (obj.ot === OBJECT_TYPE_PICTURE || shape.shapeType === 75) {
+			const embedded = embeddedObjectFromObjRecord(obj.group, shape, context, geometry);
+			if (embedded !== void 0) {
+				embeddedObjects.push(embedded);
+				continue;
+			}
 			const image = imageFromShape(shape, context, geometry);
 			if (image !== void 0) images.push(image);
 			continue;
@@ -115,6 +121,21 @@ function readSheetDrawing(worksheetRecords, context) {
 		embeddedObjects
 	};
 }
+/** A Picture-type Obj record whose FtPictFmla names an Embedding Storage this workbook's own outer compound file carries: resolved through readEmbeddedObjectPackage rather than the plain Blip Store path imageFromShape covers, since an OLE-embedded object's data lives in that storage's own Package stream instead of a pib reference into the workbook-wide Blip Store. Undefined for a plain picture (no FtPictFmla at all), an FtPictFmla naming a storage id this workbook's container did not report, or a storage whose Package stream is not this codec's own payload (readEmbeddedObjectPackage's own foreign-payload degrade) -- each falls through to imageFromShape instead. */
+function embeddedObjectFromObjRecord(objGroup, shape, context, geometry) {
+	const storageId = require_workbook_comments.readObjPictFmlaStorageId(objGroup);
+	if (storageId === void 0) return;
+	const packageBytes = context.embeddingStreams.get(storageId);
+	if (packageBytes === void 0) return;
+	const placement = resolveAnchorPlacement(shape.anchor, geometry);
+	if (placement.widthPt <= 0 || placement.heightPt <= 0) return;
+	return require_workbook_embedded_object.readEmbeddedObjectPackage(packageBytes, {
+		xPt: placement.xPt,
+		yPt: placement.yPt,
+		widthPt: placement.widthPt,
+		heightPt: placement.heightPt
+	});
+}
 function imageFromShape(shape, context, geometry) {
 	if (shape.blipIndex === void 0) return;
 	const blip = context.blipStore.get(shape.blipIndex);

package/dist/workbook/drawing.d.cts

@@ -18,6 +18,8 @@ interface SheetDrawingContext {
   readonly metadata: LayoutMetadata;
   /** Every substream the workbook stream carries -- searched for the chart substream a Chart-type Obj record's own nested BOF...EOF produced (splitSubstreams reports it as its own entry, positioned by byte offset rather than nested inside the worksheet's own `records`; see biff/substreams.ts's own top comment for why). */
   readonly allSubstreams: readonly Substream[];
+  /** Every "MBD<hex>/Package" Embedding Storage the outer compound file carries, keyed by the storage id a Picture-type Obj record's own FtPictFmla names (container.ts's own readWorkbookStreams) -- resolved here for a Picture Obj record whose data lives in an OLE embedding rather than the workbook-wide Blip Store. */
+  readonly embeddingStreams: ReadonlyMap<number, Uint8Array<ArrayBuffer>>;
 }
 /** Reads one worksheet's own drawing content: every MsoDrawing record's bytes concatenated into one Escher stream (drawing/shapes.ts), each of its real top-level shapes paired 1:1, in document order, with the non-Note Obj records the same substream carries. */
 declare function readSheetDrawing(worksheetRecords: readonly RecordGroup[], context: SheetDrawingContext): SheetDrawing;

package/dist/workbook/drawing.d.ts

@@ -18,6 +18,8 @@ interface SheetDrawingContext {
   readonly metadata: LayoutMetadata;
   /** Every substream the workbook stream carries -- searched for the chart substream a Chart-type Obj record's own nested BOF...EOF produced (splitSubstreams reports it as its own entry, positioned by byte offset rather than nested inside the worksheet's own `records`; see biff/substreams.ts's own top comment for why). */
   readonly allSubstreams: readonly Substream[];
+  /** Every "MBD<hex>/Package" Embedding Storage the outer compound file carries, keyed by the storage id a Picture-type Obj record's own FtPictFmla names (container.ts's own readWorkbookStreams) -- resolved here for a Picture Obj record whose data lives in an OLE embedding rather than the workbook-wide Blip Store. */
+  readonly embeddingStreams: ReadonlyMap<number, Uint8Array<ArrayBuffer>>;
 }
 /** Reads one worksheet's own drawing content: every MsoDrawing record's bytes concatenated into one Escher stream (drawing/shapes.ts), each of its real top-level shapes paired 1:1, in document order, with the non-Note Obj records the same substream carries. */
 declare function readSheetDrawing(worksheetRecords: readonly RecordGroup[], context: SheetDrawingContext): SheetDrawing;

package/dist/workbook/drawing.js

@@ -2,9 +2,10 @@ import "../biff/record-types.js";
 import { DEFAULT_COLUMN_WIDTH_CHARS, columnWidthToPoints } from "../units.js";
 import "../drawing/escher-constants.js";
 import { concatBytes } from "../drawing/bytes.js";
-import { readObjTypeAndId } from "./comments.js";
+import { readObjPictFmlaStorageId, readObjTypeAndId } from "./comments.js";
 import { readSheetShapes } from "../drawing/shapes.js";
 import { readChartSeries } from "./chart.js";
+import { readEmbeddedObjectPackage } from "./embedded-object.js";
 import { PAGE_SIZE_LETTER } from "document-schema.js";
 //#region src/workbook/drawing.ts
 /** [MS-XLS] "FtCmo" ot enumeration, the values this reader routes on. */
@@ -68,8 +69,7 @@ function readSheetDrawing(worksheetRecords, context) {
 		const record = worksheetRecords[index];
 		if (record === void 0) continue;
 		if (record.type === 236) {
-			const block = record.blocks[0];
-			if (block !== void 0) drawingChunks.push(block);
+			drawingChunks.push(...record.blocks);
 			continue;
 		}
 		if (record.type === 93) {
@@ -78,7 +78,8 @@ function readSheetDrawing(worksheetRecords, context) {
 			objEntries.push({
 				ot,
 				offset: record.offset,
-				nextOffset
+				nextOffset,
+				group: record
 			});
 		}
 	}
@@ -97,6 +98,11 @@ function readSheetDrawing(worksheetRecords, context) {
 		const obj = objEntries[index];
 		if (shape === void 0 || obj === void 0 || obj.ot === OBJECT_TYPE_NOTE) continue;
 		if (obj.ot === OBJECT_TYPE_PICTURE || shape.shapeType === 75) {
+			const embedded = embeddedObjectFromObjRecord(obj.group, shape, context, geometry);
+			if (embedded !== void 0) {
+				embeddedObjects.push(embedded);
+				continue;
+			}
 			const image = imageFromShape(shape, context, geometry);
 			if (image !== void 0) images.push(image);
 			continue;
@@ -114,6 +120,21 @@ function readSheetDrawing(worksheetRecords, context) {
 		embeddedObjects
 	};
 }
+/** A Picture-type Obj record whose FtPictFmla names an Embedding Storage this workbook's own outer compound file carries: resolved through readEmbeddedObjectPackage rather than the plain Blip Store path imageFromShape covers, since an OLE-embedded object's data lives in that storage's own Package stream instead of a pib reference into the workbook-wide Blip Store. Undefined for a plain picture (no FtPictFmla at all), an FtPictFmla naming a storage id this workbook's container did not report, or a storage whose Package stream is not this codec's own payload (readEmbeddedObjectPackage's own foreign-payload degrade) -- each falls through to imageFromShape instead. */
+function embeddedObjectFromObjRecord(objGroup, shape, context, geometry) {
+	const storageId = readObjPictFmlaStorageId(objGroup);
+	if (storageId === void 0) return;
+	const packageBytes = context.embeddingStreams.get(storageId);
+	if (packageBytes === void 0) return;
+	const placement = resolveAnchorPlacement(shape.anchor, geometry);
+	if (placement.widthPt <= 0 || placement.heightPt <= 0) return;
+	return readEmbeddedObjectPackage(packageBytes, {
+		xPt: placement.xPt,
+		yPt: placement.yPt,
+		widthPt: placement.widthPt,
+		heightPt: placement.heightPt
+	});
+}
 function imageFromShape(shape, context, geometry) {
 	if (shape.blipIndex === void 0) return;
 	const blip = context.blipStore.get(shape.blipIndex);

package/dist/workbook/embedded-object.cjs

@@ -0,0 +1,43 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let archive_codec = require("archive-codec");
+let document_schema_js = require("document-schema.js");
+//#region src/workbook/embedded-object.ts
+const PACKAGE_LABEL = "xls-codec-embedded-object.json";
+function payloadOf(embedded) {
+	return {
+		objectKind: embedded.objectKind,
+		document: embedded.document,
+		source: embedded.source
+	};
+}
+/** The Package stream bytes for one embedded object: this package's own JSON serialisation of the object's kind, document, and residue, wrapped in the [MS-OLEDS] packaging. */
+function writeEmbeddedObjectPackage(embedded) {
+	const fileBytes = new TextEncoder().encode(JSON.stringify(payloadOf(embedded)));
+	return (0, archive_codec.writeOlePackage)({
+		label: PACKAGE_LABEL,
+		sourcePath: "",
+		tempPath: "",
+		fileBytes
+	});
+}
+/** The inverse of writeEmbeddedObjectPackage: recovers a ContentEmbeddedObject's kind, document, and residue when the Package stream bytes are this package's own payload, or undefined for anything else -- a real OLE object's packaged bytes included -- rather than throwing, since one unreadable embedding must not fail the whole sheet's drawing read. `frame` is the placement the caller derived from the embedding's own Escher anchor: the payload deliberately carries no placement of its own (see payloadOf above), and the full ContentEmbeddedObjectSchema validation needs a frame to accept, so the anchor-derived one is merged in before the parse -- the anchor stays the single authority for where the object sits. */
+function readEmbeddedObjectPackage(packageBytes, frame) {
+	try {
+		const olePackage = (0, archive_codec.readOlePackage)(packageBytes);
+		if (olePackage.label !== PACKAGE_LABEL) return;
+		const text = new TextDecoder("utf-8").decode(olePackage.fileBytes);
+		const parsed = JSON.parse(text);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || !("objectKind" in parsed) || !("document" in parsed)) return;
+		const result = document_schema_js.ContentEmbeddedObjectSchema.safeParse({
+			...parsed,
+			frame
+		});
+		if (!result.success) return;
+		return result.data;
+	} catch {
+		return;
+	}
+}
+//#endregion
+exports.readEmbeddedObjectPackage = readEmbeddedObjectPackage;
+exports.writeEmbeddedObjectPackage = writeEmbeddedObjectPackage;

package/dist/workbook/embedded-object.d.cts

@@ -0,0 +1,8 @@
+import { ContentEmbeddedObject } from "document-schema.js";
+//#region src/workbook/embedded-object.d.ts
+/** The Package stream bytes for one embedded object: this package's own JSON serialisation of the object's kind, document, and residue, wrapped in the [MS-OLEDS] packaging. */
+declare function writeEmbeddedObjectPackage(embedded: ContentEmbeddedObject): Uint8Array<ArrayBuffer>;
+/** The inverse of writeEmbeddedObjectPackage: recovers a ContentEmbeddedObject's kind, document, and residue when the Package stream bytes are this package's own payload, or undefined for anything else -- a real OLE object's packaged bytes included -- rather than throwing, since one unreadable embedding must not fail the whole sheet's drawing read. `frame` is the placement the caller derived from the embedding's own Escher anchor: the payload deliberately carries no placement of its own (see payloadOf above), and the full ContentEmbeddedObjectSchema validation needs a frame to accept, so the anchor-derived one is merged in before the parse -- the anchor stays the single authority for where the object sits. */
+declare function readEmbeddedObjectPackage(packageBytes: Uint8Array<ArrayBuffer>, frame: ContentEmbeddedObject["frame"]): ContentEmbeddedObject | undefined;
+//#endregion
+export { readEmbeddedObjectPackage, writeEmbeddedObjectPackage };

package/dist/workbook/embedded-object.d.ts

@@ -0,0 +1,8 @@
+import { ContentEmbeddedObject } from "document-schema.js";
+//#region src/workbook/embedded-object.d.ts
+/** The Package stream bytes for one embedded object: this package's own JSON serialisation of the object's kind, document, and residue, wrapped in the [MS-OLEDS] packaging. */
+declare function writeEmbeddedObjectPackage(embedded: ContentEmbeddedObject): Uint8Array<ArrayBuffer>;
+/** The inverse of writeEmbeddedObjectPackage: recovers a ContentEmbeddedObject's kind, document, and residue when the Package stream bytes are this package's own payload, or undefined for anything else -- a real OLE object's packaged bytes included -- rather than throwing, since one unreadable embedding must not fail the whole sheet's drawing read. `frame` is the placement the caller derived from the embedding's own Escher anchor: the payload deliberately carries no placement of its own (see payloadOf above), and the full ContentEmbeddedObjectSchema validation needs a frame to accept, so the anchor-derived one is merged in before the parse -- the anchor stays the single authority for where the object sits. */
+declare function readEmbeddedObjectPackage(packageBytes: Uint8Array<ArrayBuffer>, frame: ContentEmbeddedObject["frame"]): ContentEmbeddedObject | undefined;
+//#endregion
+export { readEmbeddedObjectPackage, writeEmbeddedObjectPackage };

package/dist/workbook/embedded-object.js

@@ -0,0 +1,41 @@
+import { readOlePackage, writeOlePackage } from "archive-codec";
+import { ContentEmbeddedObjectSchema } from "document-schema.js";
+//#region src/workbook/embedded-object.ts
+const PACKAGE_LABEL = "xls-codec-embedded-object.json";
+function payloadOf(embedded) {
+	return {
+		objectKind: embedded.objectKind,
+		document: embedded.document,
+		source: embedded.source
+	};
+}
+/** The Package stream bytes for one embedded object: this package's own JSON serialisation of the object's kind, document, and residue, wrapped in the [MS-OLEDS] packaging. */
+function writeEmbeddedObjectPackage(embedded) {
+	const fileBytes = new TextEncoder().encode(JSON.stringify(payloadOf(embedded)));
+	return writeOlePackage({
+		label: PACKAGE_LABEL,
+		sourcePath: "",
+		tempPath: "",
+		fileBytes
+	});
+}
+/** The inverse of writeEmbeddedObjectPackage: recovers a ContentEmbeddedObject's kind, document, and residue when the Package stream bytes are this package's own payload, or undefined for anything else -- a real OLE object's packaged bytes included -- rather than throwing, since one unreadable embedding must not fail the whole sheet's drawing read. `frame` is the placement the caller derived from the embedding's own Escher anchor: the payload deliberately carries no placement of its own (see payloadOf above), and the full ContentEmbeddedObjectSchema validation needs a frame to accept, so the anchor-derived one is merged in before the parse -- the anchor stays the single authority for where the object sits. */
+function readEmbeddedObjectPackage(packageBytes, frame) {
+	try {
+		const olePackage = readOlePackage(packageBytes);
+		if (olePackage.label !== PACKAGE_LABEL) return;
+		const text = new TextDecoder("utf-8").decode(olePackage.fileBytes);
+		const parsed = JSON.parse(text);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || !("objectKind" in parsed) || !("document" in parsed)) return;
+		const result = ContentEmbeddedObjectSchema.safeParse({
+			...parsed,
+			frame
+		});
+		if (!result.success) return;
+		return result.data;
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { readEmbeddedObjectPackage, writeEmbeddedObjectPackage };

package/dist/workbook/globals-writer.cjs

@@ -110,6 +110,7 @@ function buildWorkbookGlobals(plan) {
 		for (const record of require_workbook_print_names.writePrintNameRecords(plan.printNames)) push(record);
 		for (const record of require_workbook_defined_names.writeDefinedNameRecords(plan.definedNames)) push(record);
 	}
+	if (plan.drawingGroupBytes !== void 0) for (const record of require_biff_record_writer.writeRecordChain(235, plan.drawingGroupBytes)) 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 {

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

@@ -35,6 +35,8 @@ interface WorkbookGlobalsPlan {
   readonly printNames: readonly PrintNamePlanEntry[];
   /** The document-level defined names the workbook declares, one Lbl record each, from workbook/defined-names.ts's own compile of the document's names array. */
   readonly definedNames: readonly DefinedNamePlanEntry[];
+  /** The workbook-wide Escher drawing group ([MS-ODRAW] OfficeArtDggContainer, drawing/escher-writer.ts's own writeDrawingGroupBytes) -- the FDGGBlock plus the Blip Store every sheet's picture shapes share -- or undefined when no sheet in the workbook carries an image or embedded object, in which case no MsoDrawingGroup record is written at all. */
+  readonly drawingGroupBytes?: Uint8Array<ArrayBuffer>;
 }
 interface WorkbookGlobalsBuild {
   readonly bytes: Uint8Array<ArrayBuffer>;

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

@@ -35,6 +35,8 @@ interface WorkbookGlobalsPlan {
   readonly printNames: readonly PrintNamePlanEntry[];
   /** The document-level defined names the workbook declares, one Lbl record each, from workbook/defined-names.ts's own compile of the document's names array. */
   readonly definedNames: readonly DefinedNamePlanEntry[];
+  /** The workbook-wide Escher drawing group ([MS-ODRAW] OfficeArtDggContainer, drawing/escher-writer.ts's own writeDrawingGroupBytes) -- the FDGGBlock plus the Blip Store every sheet's picture shapes share -- or undefined when no sheet in the workbook carries an image or embedded object, in which case no MsoDrawingGroup record is written at all. */
+  readonly drawingGroupBytes?: Uint8Array<ArrayBuffer>;
 }
 interface WorkbookGlobalsBuild {
   readonly bytes: Uint8Array<ArrayBuffer>;

package/dist/workbook/globals-writer.js

@@ -1,6 +1,6 @@
 import { RECORD_BOF } from "../biff/record-types.js";
 import { RecordBuilder } from "../biff/builder.js";
-import { concatRecords, writeRecord } from "../biff/record-writer.js";
+import { concatRecords, writeRecord, writeRecordChain } from "../biff/record-writer.js";
 import { writeFontRecord } from "../biff/font.js";
 import { writeRichExtendedString, writeShortXLUnicodeString } from "../biff/string-writer.js";
 import { writeDefinedNameRecords } from "./defined-names.js";
@@ -109,6 +109,7 @@ function buildWorkbookGlobals(plan) {
 		for (const record of writePrintNameRecords(plan.printNames)) push(record);
 		for (const record of writeDefinedNameRecords(plan.definedNames)) push(record);
 	}
+	if (plan.drawingGroupBytes !== void 0) for (const record of writeRecordChain(235, plan.drawingGroupBytes)) push(record);
 	if (plan.sharedStrings.length > 0) push(writeSstRecord(plan.sharedStrings, plan.sharedStringTotalCount));
 	push(writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
 	return {

package/dist/workbook/sheet-writer.cjs

@@ -289,8 +289,8 @@ function writeFormulaRecords(cell, xfIndex) {
 function writeCellRecords(cell, xfIndex, ctx) {
 	return cell.formula !== void 0 ? writeFormulaRecords(cell, xfIndex) : [writeCellValueRecord(cell, xfIndex, ctx)];
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
-function buildWorksheetSubstream(sheet, ctx) {
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, the sheet's own MsoDrawing/Obj records for images and embedded objects, EOF. */
+function buildWorksheetSubstream(sheet, ctx, drawing) {
 	for (const cell of sheet.cells) checkedCellPosition(cell);
 	const writtenCells = sheet.cells.filter(require_written_cells.writesCellRecord);
 	const cellsByRow = /* @__PURE__ */ new Map();
@@ -320,8 +320,9 @@ function buildWorksheetSubstream(sheet, ctx) {
 	if (merges.length > 0) pieces.push(writeMergeCellsRecord(merges));
 	const commentedCells = sheet.cells.filter((cell) => cell.comment !== void 0);
 	if (commentedCells.length > 0) pieces.push(...require_workbook_comment_writer.writeSheetComments(commentedCells));
-	pieces.push(...require_workbook_data_validation_write.writeSheetDataValidations(sheet));
+	pieces.push(...drawing.msoDrawingRecords, ...drawing.objRecords);
 	pieces.push(...require_workbook_conditional_format_write.writeSheetConditionalFormats(sheet, ctx.icvOf));
+	pieces.push(...require_workbook_data_validation_write.writeSheetDataValidations(sheet));
 	pieces.push(require_biff_record_writer.writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
 	return require_biff_record_writer.concatRecords(...pieces);
 }

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

@@ -1,3 +1,4 @@
+import { n as SheetDrawingWrite } from "../drawing-writer-Blm_NUSZ.cjs";
 import { Color, ContentSheet, ContentSheetCell } from "document-schema.js";
 //#region src/workbook/sheet-writer.d.ts
 interface SheetWriteContext {
@@ -8,7 +9,7 @@ interface SheetWriteContext {
   /** The shared string table index for a string cell's own text; every string a sheet writes must already be registered in the workbook-wide table before this is called. */
   sstIndexFor(text: string): number;
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
-declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext): Uint8Array<ArrayBuffer>;
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, the sheet's own MsoDrawing/Obj records for images and embedded objects, EOF. */
+declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext, drawing: SheetDrawingWrite): Uint8Array<ArrayBuffer>;
 //#endregion
 export { SheetWriteContext, buildWorksheetSubstream };

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

@@ -1,3 +1,4 @@
+import { n as SheetDrawingWrite } from "../drawing-writer-Blm_NUSZ.js";
 import { Color, ContentSheet, ContentSheetCell } from "document-schema.js";
 //#region src/workbook/sheet-writer.d.ts
 interface SheetWriteContext {
@@ -8,7 +9,7 @@ interface SheetWriteContext {
   /** The shared string table index for a string cell's own text; every string a sheet writes must already be registered in the workbook-wide table before this is called. */
   sstIndexFor(text: string): number;
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
-declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext): Uint8Array<ArrayBuffer>;
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, the sheet's own MsoDrawing/Obj records for images and embedded objects, EOF. */
+declare function buildWorksheetSubstream(sheet: ContentSheet, ctx: SheetWriteContext, drawing: SheetDrawingWrite): Uint8Array<ArrayBuffer>;
 //#endregion
 export { SheetWriteContext, buildWorksheetSubstream };

package/dist/workbook/sheet-writer.js

@@ -288,8 +288,8 @@ function writeFormulaRecords(cell, xfIndex) {
 function writeCellRecords(cell, xfIndex, ctx) {
 	return cell.formula !== void 0 ? writeFormulaRecords(cell, xfIndex) : [writeCellValueRecord(cell, xfIndex, ctx)];
 }
-/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, EOF. */
-function buildWorksheetSubstream(sheet, ctx) {
+/** Builds one worksheet's own substream: BOF, the print-settings records, Dimensions, ColInfo per column, Row + value-cell records per populated or declared row (in ascending row then column order), MergeCells if the sheet declares any, comment records for cells carrying one, the sheet's own MsoDrawing/Obj records for images and embedded objects, EOF. */
+function buildWorksheetSubstream(sheet, ctx, drawing) {
 	for (const cell of sheet.cells) checkedCellPosition(cell);
 	const writtenCells = sheet.cells.filter(writesCellRecord);
 	const cellsByRow = /* @__PURE__ */ new Map();
@@ -319,8 +319,9 @@ function buildWorksheetSubstream(sheet, ctx) {
 	if (merges.length > 0) pieces.push(writeMergeCellsRecord(merges));
 	const commentedCells = sheet.cells.filter((cell) => cell.comment !== void 0);
 	if (commentedCells.length > 0) pieces.push(...writeSheetComments(commentedCells));
-	pieces.push(...writeSheetDataValidations(sheet));
+	pieces.push(...drawing.msoDrawingRecords, ...drawing.objRecords);
 	pieces.push(...writeSheetConditionalFormats(sheet, ctx.icvOf));
+	pieces.push(...writeSheetDataValidations(sheet));
 	pieces.push(writeRecord(10, /* @__PURE__ */ new Uint8Array(0)));
 	return concatRecords(...pieces);
 }