xls-codec 4.7.6 → 4.8.0

package/dist/drawing/blips.cjs

@@ -0,0 +1,83 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_cursor = require("../biff/cursor.cjs");
+const require_drawing_escher_constants = require("./escher-constants.cjs");
+const require_drawing_escher = require("./escher.cjs");
+//#region src/drawing/blips.ts
+const RGB_UID_SIZE = 16;
+const BLIP_TAG_SIZE = 1;
+/** [MS-ODRAW] OfficeArtFBSE's own fixed fields up to and including unused3, before the optional nameData and the nested embedded blip -- btWin32(1) + btMacOS(1) + rgbUid(16) + tag(2) + size(4) + cRef(4) + foDelay(4) + unused1(1) + cbName(1) + unused2(1) + unused3(1). */
+const BSE_FIXED_SIZE = 36;
+/** A Blip record's own recInstance, mapped to how many 16-byte rgbUid fields precede its `tag` byte and the raw file bytes -- one UID for a blip embedded once, two when [MS-ODRAW] also records a second, "printer" representation's own hash. Only PNG/JPEG instances are named: every other blip type resolves to no image at all (see readBlipImage), so its own UID count is never needed. */
+const BLIP_UID_COUNTS = /* @__PURE__ */ new Map([
+	[1760, 1],
+	[1761, 2],
+	[1130, 1],
+	[1131, 2],
+	[1762, 1],
+	[1763, 2]
+]);
+/** Reads every BSE entry the workbook's own drawing-group Escher stream declares, keyed by its 1-based position in the Blip Store array -- the same index a picture shape's `pib` property names. A BSE this reader cannot turn into a real image (no embedded blip, or a blip type document-schema.js's ContentImageBlockSchema has no lossless slot for -- DIB, EMF, WMF, PICT, TIFF) is simply absent from the map, exactly like any other unsupported construct elsewhere in this package: a picture shape whose `pib` resolves to one of these is recognised as a picture but produces no ContentSheetImage, rather than a fabricated or mistranscoded one. */
+function readBlipStore(drawingGroupBytes) {
+	const store = /* @__PURE__ */ new Map();
+	if (drawingGroupBytes.length === 0) return store;
+	const dgg = require_drawing_escher.readEscherRecords(drawingGroupBytes).find((record) => record.kind === "container" && record.recType === 61440);
+	if (dgg === void 0) return store;
+	const bstore = require_drawing_escher.childrenOfType(dgg, require_drawing_escher_constants.ESCHER_BSTORE_CONTAINER)[0];
+	if (bstore?.kind !== "container") return store;
+	require_drawing_escher.childrenOfType(bstore, require_drawing_escher_constants.ESCHER_BSE).forEach((bse, index) => {
+		if (bse.kind !== "atom") return;
+		const image = readBseImage(bse.data);
+		if (image !== void 0) store.set(index + 1, image);
+	});
+	return store;
+}
+/** One BSE atom's own body ([MS-ODRAW] OfficeArtFBSE): the fixed fields, an optional nameData string, then the nested embedded blip record -- present whenever the image is stored inline rather than only linked externally (foDelay !== 0xFFFFFFFF), which is the only case this reader can recover bytes for at all. */
+function readBseImage(data) {
+	if (data.length < BSE_FIXED_SIZE) return;
+	const cursor = new require_biff_cursor.BlockCursor([data]);
+	cursor.skip(1);
+	cursor.skip(1);
+	cursor.skip(RGB_UID_SIZE);
+	cursor.skip(2);
+	cursor.skip(4);
+	cursor.skip(4);
+	cursor.skip(4);
+	cursor.skip(1);
+	const cbName = cursor.u8();
+	cursor.skip(1);
+	cursor.skip(1);
+	const embeddedStart = BSE_FIXED_SIZE + (cbName > 0 ? cbName : 0);
+	if (embeddedStart >= data.length) return;
+	const embeddedBytes = data.subarray(embeddedStart);
+	const blip = require_drawing_escher.readEscherRecords(embeddedBytes)[0];
+	if (blip?.kind !== "atom") return;
+	return readBlipImage(blip.recType, blip.recInstance, blip.data);
+}
+/** One embedded OfficeArtBlip record's own body -- one or two 16-byte rgbUid fields, a one-byte tag, then the literal image file bytes to the end of the record. PNG and JPEG blips carry their literal file bytes verbatim ([MS-ODRAW] OfficeArtBlipPNG/OfficeArtBlipJPEG); every other recognised blip type (DIB -- an in-memory Windows DIB, not a standalone .bmp file, and carrying no BITMAPFILEHEADER of its own to become one) has no lossless target in document-schema.js's ContentImageBlockSchema (png/jpeg/svg/gif only) and resolves to undefined rather than a mistranscoded image. */
+function readBlipImage(recType, recInstance, data) {
+	const format = blipFormatOf(recType);
+	if (format === void 0) return;
+	const uidCount = BLIP_UID_COUNTS.get(recInstance);
+	if (uidCount === void 0) return;
+	const headerSize = uidCount * RGB_UID_SIZE + BLIP_TAG_SIZE;
+	if (data.length < headerSize) return;
+	return {
+		format,
+		base64: bytesToBase64(data.subarray(headerSize))
+	};
+}
+function blipFormatOf(recType) {
+	if (recType === 61470) return "png";
+	if (recType === 61469 || recType === 61482) return "jpeg";
+}
+function bytesToBase64(bytes) {
+	let binary = "";
+	const chunkSize = 32768;
+	for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+		const chunk = bytes.subarray(offset, offset + chunkSize);
+		binary += String.fromCharCode(...chunk);
+	}
+	return btoa(binary);
+}
+//#endregion
+exports.readBlipStore = readBlipStore;

package/dist/drawing/blips.d.cts

@@ -0,0 +1,10 @@
+//#region src/drawing/blips.d.ts
+/** One resolved image: the bytes document-schema.js's ContentImageBlockSchema can actually carry (png/jpeg only -- see readBlipImage below), base64-encoded. */
+interface BlipImage {
+  readonly format: "png" | "jpeg";
+  readonly base64: string;
+}
+/** Reads every BSE entry the workbook's own drawing-group Escher stream declares, keyed by its 1-based position in the Blip Store array -- the same index a picture shape's `pib` property names. A BSE this reader cannot turn into a real image (no embedded blip, or a blip type document-schema.js's ContentImageBlockSchema has no lossless slot for -- DIB, EMF, WMF, PICT, TIFF) is simply absent from the map, exactly like any other unsupported construct elsewhere in this package: a picture shape whose `pib` resolves to one of these is recognised as a picture but produces no ContentSheetImage, rather than a fabricated or mistranscoded one. */
+declare function readBlipStore(drawingGroupBytes: Uint8Array<ArrayBuffer>): ReadonlyMap<number, BlipImage>;
+//#endregion
+export { BlipImage, readBlipStore };

package/dist/drawing/blips.d.ts

@@ -0,0 +1,10 @@
+//#region src/drawing/blips.d.ts
+/** One resolved image: the bytes document-schema.js's ContentImageBlockSchema can actually carry (png/jpeg only -- see readBlipImage below), base64-encoded. */
+interface BlipImage {
+  readonly format: "png" | "jpeg";
+  readonly base64: string;
+}
+/** Reads every BSE entry the workbook's own drawing-group Escher stream declares, keyed by its 1-based position in the Blip Store array -- the same index a picture shape's `pib` property names. A BSE this reader cannot turn into a real image (no embedded blip, or a blip type document-schema.js's ContentImageBlockSchema has no lossless slot for -- DIB, EMF, WMF, PICT, TIFF) is simply absent from the map, exactly like any other unsupported construct elsewhere in this package: a picture shape whose `pib` resolves to one of these is recognised as a picture but produces no ContentSheetImage, rather than a fabricated or mistranscoded one. */
+declare function readBlipStore(drawingGroupBytes: Uint8Array<ArrayBuffer>): ReadonlyMap<number, BlipImage>;
+//#endregion
+export { BlipImage, readBlipStore };

package/dist/drawing/blips.js

@@ -0,0 +1,82 @@
+import { BlockCursor } from "../biff/cursor.js";
+import { ESCHER_BSE, ESCHER_BSTORE_CONTAINER } from "./escher-constants.js";
+import { childrenOfType, readEscherRecords } from "./escher.js";
+//#region src/drawing/blips.ts
+const RGB_UID_SIZE = 16;
+const BLIP_TAG_SIZE = 1;
+/** [MS-ODRAW] OfficeArtFBSE's own fixed fields up to and including unused3, before the optional nameData and the nested embedded blip -- btWin32(1) + btMacOS(1) + rgbUid(16) + tag(2) + size(4) + cRef(4) + foDelay(4) + unused1(1) + cbName(1) + unused2(1) + unused3(1). */
+const BSE_FIXED_SIZE = 36;
+/** A Blip record's own recInstance, mapped to how many 16-byte rgbUid fields precede its `tag` byte and the raw file bytes -- one UID for a blip embedded once, two when [MS-ODRAW] also records a second, "printer" representation's own hash. Only PNG/JPEG instances are named: every other blip type resolves to no image at all (see readBlipImage), so its own UID count is never needed. */
+const BLIP_UID_COUNTS = /* @__PURE__ */ new Map([
+	[1760, 1],
+	[1761, 2],
+	[1130, 1],
+	[1131, 2],
+	[1762, 1],
+	[1763, 2]
+]);
+/** Reads every BSE entry the workbook's own drawing-group Escher stream declares, keyed by its 1-based position in the Blip Store array -- the same index a picture shape's `pib` property names. A BSE this reader cannot turn into a real image (no embedded blip, or a blip type document-schema.js's ContentImageBlockSchema has no lossless slot for -- DIB, EMF, WMF, PICT, TIFF) is simply absent from the map, exactly like any other unsupported construct elsewhere in this package: a picture shape whose `pib` resolves to one of these is recognised as a picture but produces no ContentSheetImage, rather than a fabricated or mistranscoded one. */
+function readBlipStore(drawingGroupBytes) {
+	const store = /* @__PURE__ */ new Map();
+	if (drawingGroupBytes.length === 0) return store;
+	const dgg = readEscherRecords(drawingGroupBytes).find((record) => record.kind === "container" && record.recType === 61440);
+	if (dgg === void 0) return store;
+	const bstore = childrenOfType(dgg, ESCHER_BSTORE_CONTAINER)[0];
+	if (bstore?.kind !== "container") return store;
+	childrenOfType(bstore, ESCHER_BSE).forEach((bse, index) => {
+		if (bse.kind !== "atom") return;
+		const image = readBseImage(bse.data);
+		if (image !== void 0) store.set(index + 1, image);
+	});
+	return store;
+}
+/** One BSE atom's own body ([MS-ODRAW] OfficeArtFBSE): the fixed fields, an optional nameData string, then the nested embedded blip record -- present whenever the image is stored inline rather than only linked externally (foDelay !== 0xFFFFFFFF), which is the only case this reader can recover bytes for at all. */
+function readBseImage(data) {
+	if (data.length < BSE_FIXED_SIZE) return;
+	const cursor = new BlockCursor([data]);
+	cursor.skip(1);
+	cursor.skip(1);
+	cursor.skip(RGB_UID_SIZE);
+	cursor.skip(2);
+	cursor.skip(4);
+	cursor.skip(4);
+	cursor.skip(4);
+	cursor.skip(1);
+	const cbName = cursor.u8();
+	cursor.skip(1);
+	cursor.skip(1);
+	const embeddedStart = BSE_FIXED_SIZE + (cbName > 0 ? cbName : 0);
+	if (embeddedStart >= data.length) return;
+	const embeddedBytes = data.subarray(embeddedStart);
+	const blip = readEscherRecords(embeddedBytes)[0];
+	if (blip?.kind !== "atom") return;
+	return readBlipImage(blip.recType, blip.recInstance, blip.data);
+}
+/** One embedded OfficeArtBlip record's own body -- one or two 16-byte rgbUid fields, a one-byte tag, then the literal image file bytes to the end of the record. PNG and JPEG blips carry their literal file bytes verbatim ([MS-ODRAW] OfficeArtBlipPNG/OfficeArtBlipJPEG); every other recognised blip type (DIB -- an in-memory Windows DIB, not a standalone .bmp file, and carrying no BITMAPFILEHEADER of its own to become one) has no lossless target in document-schema.js's ContentImageBlockSchema (png/jpeg/svg/gif only) and resolves to undefined rather than a mistranscoded image. */
+function readBlipImage(recType, recInstance, data) {
+	const format = blipFormatOf(recType);
+	if (format === void 0) return;
+	const uidCount = BLIP_UID_COUNTS.get(recInstance);
+	if (uidCount === void 0) return;
+	const headerSize = uidCount * RGB_UID_SIZE + BLIP_TAG_SIZE;
+	if (data.length < headerSize) return;
+	return {
+		format,
+		base64: bytesToBase64(data.subarray(headerSize))
+	};
+}
+function blipFormatOf(recType) {
+	if (recType === 61470) return "png";
+	if (recType === 61469 || recType === 61482) return "jpeg";
+}
+function bytesToBase64(bytes) {
+	let binary = "";
+	const chunkSize = 32768;
+	for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+		const chunk = bytes.subarray(offset, offset + chunkSize);
+		binary += String.fromCharCode(...chunk);
+	}
+	return btoa(binary);
+}
+//#endregion
+export { readBlipStore };

package/dist/drawing/bytes.cjs

@@ -0,0 +1,15 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/drawing/bytes.ts
+/** Concatenates several byte chunks into one contiguous array -- shared by every reader that joins BIFF8's own MsoDrawing/MsoDrawingGroup record chunks into one Escher stream (content.ts's own workbook-wide MsoDrawingGroup concatenation, workbook/drawing.ts's per-sheet MsoDrawing concatenation). */
+function concatBytes(chunks) {
+	const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return out;
+}
+//#endregion
+exports.concatBytes = concatBytes;

package/dist/drawing/bytes.d.cts

@@ -0,0 +1,5 @@
+//#region src/drawing/bytes.d.ts
+/** Concatenates several byte chunks into one contiguous array -- shared by every reader that joins BIFF8's own MsoDrawing/MsoDrawingGroup record chunks into one Escher stream (content.ts's own workbook-wide MsoDrawingGroup concatenation, workbook/drawing.ts's per-sheet MsoDrawing concatenation). */
+declare function concatBytes(chunks: readonly Uint8Array<ArrayBuffer>[]): Uint8Array<ArrayBuffer>;
+//#endregion
+export { concatBytes };

package/dist/drawing/bytes.d.ts

@@ -0,0 +1,5 @@
+//#region src/drawing/bytes.d.ts
+/** Concatenates several byte chunks into one contiguous array -- shared by every reader that joins BIFF8's own MsoDrawing/MsoDrawingGroup record chunks into one Escher stream (content.ts's own workbook-wide MsoDrawingGroup concatenation, workbook/drawing.ts's per-sheet MsoDrawing concatenation). */
+declare function concatBytes(chunks: readonly Uint8Array<ArrayBuffer>[]): Uint8Array<ArrayBuffer>;
+//#endregion
+export { concatBytes };

package/dist/drawing/bytes.js

@@ -0,0 +1,14 @@
+//#region src/drawing/bytes.ts
+/** Concatenates several byte chunks into one contiguous array -- shared by every reader that joins BIFF8's own MsoDrawing/MsoDrawingGroup record chunks into one Escher stream (content.ts's own workbook-wide MsoDrawingGroup concatenation, workbook/drawing.ts's per-sheet MsoDrawing concatenation). */
+function concatBytes(chunks) {
+	const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return out;
+}
+//#endregion
+export { concatBytes };

package/dist/drawing/escher-constants.cjs

@@ -0,0 +1,52 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/drawing/escher-constants.ts
+/** The workbook-wide drawing group's own root container, from the MsoDrawingGroup stream: holds the Blip Store and the drawing document's shared shape-id state ([MS-ODRAW] OfficeArtDggContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f). */
+const ESCHER_DGG_CONTAINER = 61440;
+/** The Blip Store: one BSE atom per distinct embedded/linked image the drawing group references ([MS-ODRAW] OfficeArtBstoreContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/561cb6d4-d38b-4666-b2b4-10abc1dce44c). */
+const ESCHER_BSTORE_CONTAINER = 61441;
+/** One worksheet's own drawing container, from that sheet's MsoDrawing records: wraps the Dg atom and the sheet's own shape tree. */
+const ESCHER_DG_CONTAINER = 61442;
+/** A group of shapes -- the sheet's own root shape group (the "patriarch", holding every top-level shape as a child) and any nested shape group a real drawing groups shapes into. */
+const ESCHER_SPGR_CONTAINER = 61443;
+/** One shape: wraps its Sp atom (type/id/flags), its Opt property table, and its anchor/text/client-data atoms ([MS-ODRAW] OfficeArtSpContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/16194cb9-b4b0-476c-9678-a6ac1f06b034). */
+const ESCHER_SP_CONTAINER = 61444;
+/** A single Blip Store Entry: one embedded or linked image's own metadata plus, when embedded, the image bytes themselves nested inside its own body ([MS-ODRAW] OfficeArtFBSE, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/2f2d7f5e-d5c4-4cb7-b230-59b3fe8f10d6). */
+const ESCHER_BSE = 61447;
+/** A shape's own fixed fields: its shape-type ID (carried in the record header's own `recInstance`, an MSOSPT value -- see the SHAPE_TYPE_* constants below) plus its own group/flip/anchor flags ([MS-ODRAW] OfficeArtFSP, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/8a7e7be3-0582-4461-9400-29d7eda8497d). */
+const ESCHER_SP = 61450;
+/** A shape's own property table (fopt): a run of fixed-size property entries this reader consults for exactly one property, `pib` -- see FOPT_PROPERTY_PIB below ([MS-ODRAW] OfficeArtFOPT, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/10dc2fe1-9e69-48dc-a1d1-2921dfb9c28e). */
+const ESCHER_OPT = 61451;
+/** A shape's cell-anchor placement in a worksheet, macro sheet, or dialog sheet substream -- [MS-ODRAW]'s own generic ClientAnchor atom carries a host-defined payload, and [MS-XLS] 2.5.163 OfficeArtClientAnchorSheet (https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/fd656a2c-d5ee-4171-8f65-17a08b9f2262) is what that payload actually is here (a chart-sheet substream uses the distinct OfficeArtClientAnchorChart instead, not read by this package). */
+const ESCHER_CLIENT_ANCHOR = 61456;
+const ESCHER_BLIP_JPEG_A = 61469;
+const ESCHER_BLIP_JPEG_B = 61482;
+const ESCHER_BLIP_PNG = 61470;
+const ESCHER_BLIP_DIB = 61471;
+/** A custom/freeform shape with no named geometry preset -- MS-ODRAW's own escape value, not a shape type this reader has anything special to say about. */
+const SHAPE_TYPE_NOT_PRIMITIVE = 0;
+/** A picture frame: the shape carries an image via its own `pib` property rather than vector geometry. */
+const SHAPE_TYPE_PICTURE_FRAME = 75;
+/** A text box shape. */
+const SHAPE_TYPE_TEXT_BOX = 202;
+/** The `pib` property ([MS-ODRAW] https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/a12e8c5e-a764-49d5-b407-c27bf933920d): a picture shape's own 1-based index into the Blip Store's BSE array, carried in the FOPTE's plain `op` field when `fComplex` (the opid's own top bit) is clear. */
+const FOPT_OPID_PIB = 260;
+const FOPT_FCOMPLEX_MASK = 32768;
+//#endregion
+exports.ESCHER_BLIP_DIB = ESCHER_BLIP_DIB;
+exports.ESCHER_BLIP_JPEG_A = ESCHER_BLIP_JPEG_A;
+exports.ESCHER_BLIP_JPEG_B = ESCHER_BLIP_JPEG_B;
+exports.ESCHER_BLIP_PNG = ESCHER_BLIP_PNG;
+exports.ESCHER_BSE = ESCHER_BSE;
+exports.ESCHER_BSTORE_CONTAINER = ESCHER_BSTORE_CONTAINER;
+exports.ESCHER_CLIENT_ANCHOR = ESCHER_CLIENT_ANCHOR;
+exports.ESCHER_DGG_CONTAINER = ESCHER_DGG_CONTAINER;
+exports.ESCHER_DG_CONTAINER = ESCHER_DG_CONTAINER;
+exports.ESCHER_OPT = ESCHER_OPT;
+exports.ESCHER_SP = ESCHER_SP;
+exports.ESCHER_SPGR_CONTAINER = ESCHER_SPGR_CONTAINER;
+exports.ESCHER_SP_CONTAINER = ESCHER_SP_CONTAINER;
+exports.FOPT_FCOMPLEX_MASK = FOPT_FCOMPLEX_MASK;
+exports.FOPT_OPID_PIB = FOPT_OPID_PIB;
+exports.SHAPE_TYPE_NOT_PRIMITIVE = SHAPE_TYPE_NOT_PRIMITIVE;
+exports.SHAPE_TYPE_PICTURE_FRAME = SHAPE_TYPE_PICTURE_FRAME;
+exports.SHAPE_TYPE_TEXT_BOX = SHAPE_TYPE_TEXT_BOX;

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

@@ -0,0 +1,34 @@
+//#region src/drawing/escher-constants.d.ts
+/** The workbook-wide drawing group's own root container, from the MsoDrawingGroup stream: holds the Blip Store and the drawing document's shared shape-id state ([MS-ODRAW] OfficeArtDggContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f). */
+declare const ESCHER_DGG_CONTAINER = 61440;
+/** The Blip Store: one BSE atom per distinct embedded/linked image the drawing group references ([MS-ODRAW] OfficeArtBstoreContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/561cb6d4-d38b-4666-b2b4-10abc1dce44c). */
+declare const ESCHER_BSTORE_CONTAINER = 61441;
+/** One worksheet's own drawing container, from that sheet's MsoDrawing records: wraps the Dg atom and the sheet's own shape tree. */
+declare const ESCHER_DG_CONTAINER = 61442;
+/** A group of shapes -- the sheet's own root shape group (the "patriarch", holding every top-level shape as a child) and any nested shape group a real drawing groups shapes into. */
+declare const ESCHER_SPGR_CONTAINER = 61443;
+/** One shape: wraps its Sp atom (type/id/flags), its Opt property table, and its anchor/text/client-data atoms ([MS-ODRAW] OfficeArtSpContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/16194cb9-b4b0-476c-9678-a6ac1f06b034). */
+declare const ESCHER_SP_CONTAINER = 61444;
+/** A single Blip Store Entry: one embedded or linked image's own metadata plus, when embedded, the image bytes themselves nested inside its own body ([MS-ODRAW] OfficeArtFBSE, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/2f2d7f5e-d5c4-4cb7-b230-59b3fe8f10d6). */
+declare const ESCHER_BSE = 61447;
+/** A shape's own fixed fields: its shape-type ID (carried in the record header's own `recInstance`, an MSOSPT value -- see the SHAPE_TYPE_* constants below) plus its own group/flip/anchor flags ([MS-ODRAW] OfficeArtFSP, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/8a7e7be3-0582-4461-9400-29d7eda8497d). */
+declare const ESCHER_SP = 61450;
+/** A shape's own property table (fopt): a run of fixed-size property entries this reader consults for exactly one property, `pib` -- see FOPT_PROPERTY_PIB below ([MS-ODRAW] OfficeArtFOPT, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/10dc2fe1-9e69-48dc-a1d1-2921dfb9c28e). */
+declare const ESCHER_OPT = 61451;
+/** A shape's cell-anchor placement in a worksheet, macro sheet, or dialog sheet substream -- [MS-ODRAW]'s own generic ClientAnchor atom carries a host-defined payload, and [MS-XLS] 2.5.163 OfficeArtClientAnchorSheet (https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/fd656a2c-d5ee-4171-8f65-17a08b9f2262) is what that payload actually is here (a chart-sheet substream uses the distinct OfficeArtClientAnchorChart instead, not read by this package). */
+declare const ESCHER_CLIENT_ANCHOR = 61456;
+declare const ESCHER_BLIP_JPEG_A = 61469;
+declare const ESCHER_BLIP_JPEG_B = 61482;
+declare const ESCHER_BLIP_PNG = 61470;
+declare const ESCHER_BLIP_DIB = 61471;
+/** A custom/freeform shape with no named geometry preset -- MS-ODRAW's own escape value, not a shape type this reader has anything special to say about. */
+declare const SHAPE_TYPE_NOT_PRIMITIVE = 0;
+/** A picture frame: the shape carries an image via its own `pib` property rather than vector geometry. */
+declare const SHAPE_TYPE_PICTURE_FRAME = 75;
+/** A text box shape. */
+declare const SHAPE_TYPE_TEXT_BOX = 202;
+/** The `pib` property ([MS-ODRAW] https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/a12e8c5e-a764-49d5-b407-c27bf933920d): a picture shape's own 1-based index into the Blip Store's BSE array, carried in the FOPTE's plain `op` field when `fComplex` (the opid's own top bit) is clear. */
+declare const FOPT_OPID_PIB = 260;
+declare const FOPT_FCOMPLEX_MASK = 32768;
+//#endregion
+export { ESCHER_BLIP_DIB, ESCHER_BLIP_JPEG_A, ESCHER_BLIP_JPEG_B, ESCHER_BLIP_PNG, ESCHER_BSE, ESCHER_BSTORE_CONTAINER, ESCHER_CLIENT_ANCHOR, ESCHER_DGG_CONTAINER, ESCHER_DG_CONTAINER, ESCHER_OPT, ESCHER_SP, ESCHER_SPGR_CONTAINER, ESCHER_SP_CONTAINER, FOPT_FCOMPLEX_MASK, FOPT_OPID_PIB, SHAPE_TYPE_NOT_PRIMITIVE, SHAPE_TYPE_PICTURE_FRAME, SHAPE_TYPE_TEXT_BOX };

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

@@ -0,0 +1,34 @@
+//#region src/drawing/escher-constants.d.ts
+/** The workbook-wide drawing group's own root container, from the MsoDrawingGroup stream: holds the Blip Store and the drawing document's shared shape-id state ([MS-ODRAW] OfficeArtDggContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f). */
+declare const ESCHER_DGG_CONTAINER = 61440;
+/** The Blip Store: one BSE atom per distinct embedded/linked image the drawing group references ([MS-ODRAW] OfficeArtBstoreContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/561cb6d4-d38b-4666-b2b4-10abc1dce44c). */
+declare const ESCHER_BSTORE_CONTAINER = 61441;
+/** One worksheet's own drawing container, from that sheet's MsoDrawing records: wraps the Dg atom and the sheet's own shape tree. */
+declare const ESCHER_DG_CONTAINER = 61442;
+/** A group of shapes -- the sheet's own root shape group (the "patriarch", holding every top-level shape as a child) and any nested shape group a real drawing groups shapes into. */
+declare const ESCHER_SPGR_CONTAINER = 61443;
+/** One shape: wraps its Sp atom (type/id/flags), its Opt property table, and its anchor/text/client-data atoms ([MS-ODRAW] OfficeArtSpContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/16194cb9-b4b0-476c-9678-a6ac1f06b034). */
+declare const ESCHER_SP_CONTAINER = 61444;
+/** A single Blip Store Entry: one embedded or linked image's own metadata plus, when embedded, the image bytes themselves nested inside its own body ([MS-ODRAW] OfficeArtFBSE, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/2f2d7f5e-d5c4-4cb7-b230-59b3fe8f10d6). */
+declare const ESCHER_BSE = 61447;
+/** A shape's own fixed fields: its shape-type ID (carried in the record header's own `recInstance`, an MSOSPT value -- see the SHAPE_TYPE_* constants below) plus its own group/flip/anchor flags ([MS-ODRAW] OfficeArtFSP, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/8a7e7be3-0582-4461-9400-29d7eda8497d). */
+declare const ESCHER_SP = 61450;
+/** A shape's own property table (fopt): a run of fixed-size property entries this reader consults for exactly one property, `pib` -- see FOPT_PROPERTY_PIB below ([MS-ODRAW] OfficeArtFOPT, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/10dc2fe1-9e69-48dc-a1d1-2921dfb9c28e). */
+declare const ESCHER_OPT = 61451;
+/** A shape's cell-anchor placement in a worksheet, macro sheet, or dialog sheet substream -- [MS-ODRAW]'s own generic ClientAnchor atom carries a host-defined payload, and [MS-XLS] 2.5.163 OfficeArtClientAnchorSheet (https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/fd656a2c-d5ee-4171-8f65-17a08b9f2262) is what that payload actually is here (a chart-sheet substream uses the distinct OfficeArtClientAnchorChart instead, not read by this package). */
+declare const ESCHER_CLIENT_ANCHOR = 61456;
+declare const ESCHER_BLIP_JPEG_A = 61469;
+declare const ESCHER_BLIP_JPEG_B = 61482;
+declare const ESCHER_BLIP_PNG = 61470;
+declare const ESCHER_BLIP_DIB = 61471;
+/** A custom/freeform shape with no named geometry preset -- MS-ODRAW's own escape value, not a shape type this reader has anything special to say about. */
+declare const SHAPE_TYPE_NOT_PRIMITIVE = 0;
+/** A picture frame: the shape carries an image via its own `pib` property rather than vector geometry. */
+declare const SHAPE_TYPE_PICTURE_FRAME = 75;
+/** A text box shape. */
+declare const SHAPE_TYPE_TEXT_BOX = 202;
+/** The `pib` property ([MS-ODRAW] https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/a12e8c5e-a764-49d5-b407-c27bf933920d): a picture shape's own 1-based index into the Blip Store's BSE array, carried in the FOPTE's plain `op` field when `fComplex` (the opid's own top bit) is clear. */
+declare const FOPT_OPID_PIB = 260;
+declare const FOPT_FCOMPLEX_MASK = 32768;
+//#endregion
+export { ESCHER_BLIP_DIB, ESCHER_BLIP_JPEG_A, ESCHER_BLIP_JPEG_B, ESCHER_BLIP_PNG, ESCHER_BSE, ESCHER_BSTORE_CONTAINER, ESCHER_CLIENT_ANCHOR, ESCHER_DGG_CONTAINER, ESCHER_DG_CONTAINER, ESCHER_OPT, ESCHER_SP, ESCHER_SPGR_CONTAINER, ESCHER_SP_CONTAINER, FOPT_FCOMPLEX_MASK, FOPT_OPID_PIB, SHAPE_TYPE_NOT_PRIMITIVE, SHAPE_TYPE_PICTURE_FRAME, SHAPE_TYPE_TEXT_BOX };

package/dist/drawing/escher-constants.js

@@ -0,0 +1,34 @@
+//#region src/drawing/escher-constants.ts
+/** The workbook-wide drawing group's own root container, from the MsoDrawingGroup stream: holds the Blip Store and the drawing document's shared shape-id state ([MS-ODRAW] OfficeArtDggContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/dd7133b6-ed10-4bcb-be29-67b0544f884f). */
+const ESCHER_DGG_CONTAINER = 61440;
+/** The Blip Store: one BSE atom per distinct embedded/linked image the drawing group references ([MS-ODRAW] OfficeArtBstoreContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/561cb6d4-d38b-4666-b2b4-10abc1dce44c). */
+const ESCHER_BSTORE_CONTAINER = 61441;
+/** One worksheet's own drawing container, from that sheet's MsoDrawing records: wraps the Dg atom and the sheet's own shape tree. */
+const ESCHER_DG_CONTAINER = 61442;
+/** A group of shapes -- the sheet's own root shape group (the "patriarch", holding every top-level shape as a child) and any nested shape group a real drawing groups shapes into. */
+const ESCHER_SPGR_CONTAINER = 61443;
+/** One shape: wraps its Sp atom (type/id/flags), its Opt property table, and its anchor/text/client-data atoms ([MS-ODRAW] OfficeArtSpContainer, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/16194cb9-b4b0-476c-9678-a6ac1f06b034). */
+const ESCHER_SP_CONTAINER = 61444;
+/** A single Blip Store Entry: one embedded or linked image's own metadata plus, when embedded, the image bytes themselves nested inside its own body ([MS-ODRAW] OfficeArtFBSE, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/2f2d7f5e-d5c4-4cb7-b230-59b3fe8f10d6). */
+const ESCHER_BSE = 61447;
+/** A shape's own fixed fields: its shape-type ID (carried in the record header's own `recInstance`, an MSOSPT value -- see the SHAPE_TYPE_* constants below) plus its own group/flip/anchor flags ([MS-ODRAW] OfficeArtFSP, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/8a7e7be3-0582-4461-9400-29d7eda8497d). */
+const ESCHER_SP = 61450;
+/** A shape's own property table (fopt): a run of fixed-size property entries this reader consults for exactly one property, `pib` -- see FOPT_PROPERTY_PIB below ([MS-ODRAW] OfficeArtFOPT, https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/10dc2fe1-9e69-48dc-a1d1-2921dfb9c28e). */
+const ESCHER_OPT = 61451;
+/** A shape's cell-anchor placement in a worksheet, macro sheet, or dialog sheet substream -- [MS-ODRAW]'s own generic ClientAnchor atom carries a host-defined payload, and [MS-XLS] 2.5.163 OfficeArtClientAnchorSheet (https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/fd656a2c-d5ee-4171-8f65-17a08b9f2262) is what that payload actually is here (a chart-sheet substream uses the distinct OfficeArtClientAnchorChart instead, not read by this package). */
+const ESCHER_CLIENT_ANCHOR = 61456;
+const ESCHER_BLIP_JPEG_A = 61469;
+const ESCHER_BLIP_JPEG_B = 61482;
+const ESCHER_BLIP_PNG = 61470;
+const ESCHER_BLIP_DIB = 61471;
+/** A custom/freeform shape with no named geometry preset -- MS-ODRAW's own escape value, not a shape type this reader has anything special to say about. */
+const SHAPE_TYPE_NOT_PRIMITIVE = 0;
+/** A picture frame: the shape carries an image via its own `pib` property rather than vector geometry. */
+const SHAPE_TYPE_PICTURE_FRAME = 75;
+/** A text box shape. */
+const SHAPE_TYPE_TEXT_BOX = 202;
+/** The `pib` property ([MS-ODRAW] https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-odraw/a12e8c5e-a764-49d5-b407-c27bf933920d): a picture shape's own 1-based index into the Blip Store's BSE array, carried in the FOPTE's plain `op` field when `fComplex` (the opid's own top bit) is clear. */
+const FOPT_OPID_PIB = 260;
+const FOPT_FCOMPLEX_MASK = 32768;
+//#endregion
+export { ESCHER_BLIP_DIB, ESCHER_BLIP_JPEG_A, ESCHER_BLIP_JPEG_B, ESCHER_BLIP_PNG, ESCHER_BSE, ESCHER_BSTORE_CONTAINER, ESCHER_CLIENT_ANCHOR, ESCHER_DGG_CONTAINER, ESCHER_DG_CONTAINER, ESCHER_OPT, ESCHER_SP, ESCHER_SPGR_CONTAINER, ESCHER_SP_CONTAINER, FOPT_FCOMPLEX_MASK, FOPT_OPID_PIB, SHAPE_TYPE_NOT_PRIMITIVE, SHAPE_TYPE_PICTURE_FRAME, SHAPE_TYPE_TEXT_BOX };

package/dist/drawing/escher.cjs

@@ -0,0 +1,84 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_biff_records = require("../biff/records.cjs");
+//#region src/drawing/escher.ts
+const HEADER_SIZE = 8;
+const CONTAINER_REC_VER = 15;
+/**
+* Reads every top-level Escher record in `bytes`, recursing into containers.
+*
+* `bytes` is the whole concatenated Escher stream one worksheet's MsoDrawing records (or the workbook globals substream's MsoDrawingGroup records) build up in stream order -- BIFF8 splits one logical Escher byte sequence across as many of those BIFF records as it needs, and [MS-XLS] states plainly that their own data simply concatenates; nothing about the record framing itself lives at that BIFF layer, so by the time this function runs the split is already invisible.
+*/
+function readEscherRecords(bytes) {
+	const records = [];
+	let offset = 0;
+	while (offset < bytes.length) {
+		const { record, nextOffset } = readOneRecord(bytes, offset);
+		records.push(record);
+		offset = nextOffset;
+	}
+	return records;
+}
+function readOneRecord(bytes, offset) {
+	if (offset + HEADER_SIZE > bytes.length) throw new require_biff_records.BiffFormatError(`Escher record header at offset ${offset} runs past the end of the ${bytes.length}-byte stream`);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const verInstance = view.getUint16(offset, true);
+	const recVer = verInstance & 15;
+	const recInstance = verInstance >> 4;
+	const recType = view.getUint16(offset + 2, true);
+	const recLen = view.getUint32(offset + 4, true);
+	const bodyStart = offset + HEADER_SIZE;
+	const bodyEnd = bodyStart + recLen;
+	if (bodyEnd > bytes.length) throw new require_biff_records.BiffFormatError(`Escher record 0x${recType.toString(16)} at offset ${offset} declares ${recLen} bytes of body, running past the end of the ${bytes.length}-byte stream`);
+	if (recVer === CONTAINER_REC_VER) return {
+		record: {
+			kind: "container",
+			recInstance,
+			recType,
+			children: readChildren(bytes, bodyStart, bodyEnd)
+		},
+		nextOffset: bodyEnd
+	};
+	return {
+		record: {
+			kind: "atom",
+			recInstance,
+			recType,
+			data: bytes.subarray(bodyStart, bodyEnd)
+		},
+		nextOffset: bodyEnd
+	};
+}
+function readChildren(bytes, start, end) {
+	const children = [];
+	let offset = start;
+	while (offset < end) {
+		const { record, nextOffset } = readOneRecord(bytes, offset);
+		if (nextOffset > end) throw new require_biff_records.BiffFormatError(`Escher child record at offset ${offset} extends past its own container's declared end`);
+		children.push(record);
+		offset = nextOffset;
+	}
+	return children;
+}
+/** The first direct child of `container` with the given `recType`, container or atom alike -- undefined when none matches. */
+function firstChild(container, recType) {
+	return container.children.find((child) => child.recType === recType);
+}
+/** Every direct child of `container` with the given `recType`, in document order. */
+function childrenOfType(container, recType) {
+	return container.children.filter((child) => child.recType === recType);
+}
+/** Recursively finds the first descendant record (depth-first, this container's own children before their children) with the given `recType` -- for a record known to appear exactly once at an unspecified depth (the Blip Store, the drawing group's own Dgg), as opposed to childrenOfType's direct-children-only contract. */
+function findDescendant(container, recType) {
+	for (const child of container.children) {
+		if (child.recType === recType) return child;
+		if (child.kind === "container") {
+			const found = findDescendant(child, recType);
+			if (found !== void 0) return found;
+		}
+	}
+}
+//#endregion
+exports.childrenOfType = childrenOfType;
+exports.findDescendant = findDescendant;
+exports.firstChild = firstChild;
+exports.readEscherRecords = readEscherRecords;

package/dist/drawing/escher.d.cts

@@ -0,0 +1,30 @@
+//#region src/drawing/escher.d.ts
+/** One Escher atom: `recLen` bytes of record-specific data this module leaves opaque. */
+interface EscherAtom {
+  readonly kind: "atom";
+  readonly recInstance: number;
+  readonly recType: number;
+  readonly data: Uint8Array<ArrayBuffer>;
+}
+/** One Escher container: its own children, read the identical way, recursively. */
+interface EscherContainer {
+  readonly kind: "container";
+  readonly recInstance: number;
+  readonly recType: number;
+  readonly children: readonly EscherRecord[];
+}
+type EscherRecord = EscherAtom | EscherContainer;
+/**
+ * Reads every top-level Escher record in `bytes`, recursing into containers.
+ *
+ * `bytes` is the whole concatenated Escher stream one worksheet's MsoDrawing records (or the workbook globals substream's MsoDrawingGroup records) build up in stream order -- BIFF8 splits one logical Escher byte sequence across as many of those BIFF records as it needs, and [MS-XLS] states plainly that their own data simply concatenates; nothing about the record framing itself lives at that BIFF layer, so by the time this function runs the split is already invisible.
+ */
+declare function readEscherRecords(bytes: Uint8Array<ArrayBuffer>): readonly EscherRecord[];
+/** The first direct child of `container` with the given `recType`, container or atom alike -- undefined when none matches. */
+declare function firstChild(container: EscherContainer, recType: number): EscherRecord | undefined;
+/** Every direct child of `container` with the given `recType`, in document order. */
+declare function childrenOfType(container: EscherContainer, recType: number): readonly EscherRecord[];
+/** Recursively finds the first descendant record (depth-first, this container's own children before their children) with the given `recType` -- for a record known to appear exactly once at an unspecified depth (the Blip Store, the drawing group's own Dgg), as opposed to childrenOfType's direct-children-only contract. */
+declare function findDescendant(container: EscherContainer, recType: number): EscherRecord | undefined;
+//#endregion
+export { EscherAtom, EscherContainer, EscherRecord, childrenOfType, findDescendant, firstChild, readEscherRecords };

package/dist/drawing/escher.d.ts

@@ -0,0 +1,30 @@
+//#region src/drawing/escher.d.ts
+/** One Escher atom: `recLen` bytes of record-specific data this module leaves opaque. */
+interface EscherAtom {
+  readonly kind: "atom";
+  readonly recInstance: number;
+  readonly recType: number;
+  readonly data: Uint8Array<ArrayBuffer>;
+}
+/** One Escher container: its own children, read the identical way, recursively. */
+interface EscherContainer {
+  readonly kind: "container";
+  readonly recInstance: number;
+  readonly recType: number;
+  readonly children: readonly EscherRecord[];
+}
+type EscherRecord = EscherAtom | EscherContainer;
+/**
+ * Reads every top-level Escher record in `bytes`, recursing into containers.
+ *
+ * `bytes` is the whole concatenated Escher stream one worksheet's MsoDrawing records (or the workbook globals substream's MsoDrawingGroup records) build up in stream order -- BIFF8 splits one logical Escher byte sequence across as many of those BIFF records as it needs, and [MS-XLS] states plainly that their own data simply concatenates; nothing about the record framing itself lives at that BIFF layer, so by the time this function runs the split is already invisible.
+ */
+declare function readEscherRecords(bytes: Uint8Array<ArrayBuffer>): readonly EscherRecord[];
+/** The first direct child of `container` with the given `recType`, container or atom alike -- undefined when none matches. */
+declare function firstChild(container: EscherContainer, recType: number): EscherRecord | undefined;
+/** Every direct child of `container` with the given `recType`, in document order. */
+declare function childrenOfType(container: EscherContainer, recType: number): readonly EscherRecord[];
+/** Recursively finds the first descendant record (depth-first, this container's own children before their children) with the given `recType` -- for a record known to appear exactly once at an unspecified depth (the Blip Store, the drawing group's own Dgg), as opposed to childrenOfType's direct-children-only contract. */
+declare function findDescendant(container: EscherContainer, recType: number): EscherRecord | undefined;
+//#endregion
+export { EscherAtom, EscherContainer, EscherRecord, childrenOfType, findDescendant, firstChild, readEscherRecords };

package/dist/drawing/escher.js

@@ -0,0 +1,80 @@
+import { BiffFormatError } from "../biff/records.js";
+//#region src/drawing/escher.ts
+const HEADER_SIZE = 8;
+const CONTAINER_REC_VER = 15;
+/**
+* Reads every top-level Escher record in `bytes`, recursing into containers.
+*
+* `bytes` is the whole concatenated Escher stream one worksheet's MsoDrawing records (or the workbook globals substream's MsoDrawingGroup records) build up in stream order -- BIFF8 splits one logical Escher byte sequence across as many of those BIFF records as it needs, and [MS-XLS] states plainly that their own data simply concatenates; nothing about the record framing itself lives at that BIFF layer, so by the time this function runs the split is already invisible.
+*/
+function readEscherRecords(bytes) {
+	const records = [];
+	let offset = 0;
+	while (offset < bytes.length) {
+		const { record, nextOffset } = readOneRecord(bytes, offset);
+		records.push(record);
+		offset = nextOffset;
+	}
+	return records;
+}
+function readOneRecord(bytes, offset) {
+	if (offset + HEADER_SIZE > bytes.length) throw new BiffFormatError(`Escher record header at offset ${offset} runs past the end of the ${bytes.length}-byte stream`);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const verInstance = view.getUint16(offset, true);
+	const recVer = verInstance & 15;
+	const recInstance = verInstance >> 4;
+	const recType = view.getUint16(offset + 2, true);
+	const recLen = view.getUint32(offset + 4, true);
+	const bodyStart = offset + HEADER_SIZE;
+	const bodyEnd = bodyStart + recLen;
+	if (bodyEnd > bytes.length) throw new BiffFormatError(`Escher record 0x${recType.toString(16)} at offset ${offset} declares ${recLen} bytes of body, running past the end of the ${bytes.length}-byte stream`);
+	if (recVer === CONTAINER_REC_VER) return {
+		record: {
+			kind: "container",
+			recInstance,
+			recType,
+			children: readChildren(bytes, bodyStart, bodyEnd)
+		},
+		nextOffset: bodyEnd
+	};
+	return {
+		record: {
+			kind: "atom",
+			recInstance,
+			recType,
+			data: bytes.subarray(bodyStart, bodyEnd)
+		},
+		nextOffset: bodyEnd
+	};
+}
+function readChildren(bytes, start, end) {
+	const children = [];
+	let offset = start;
+	while (offset < end) {
+		const { record, nextOffset } = readOneRecord(bytes, offset);
+		if (nextOffset > end) throw new BiffFormatError(`Escher child record at offset ${offset} extends past its own container's declared end`);
+		children.push(record);
+		offset = nextOffset;
+	}
+	return children;
+}
+/** The first direct child of `container` with the given `recType`, container or atom alike -- undefined when none matches. */
+function firstChild(container, recType) {
+	return container.children.find((child) => child.recType === recType);
+}
+/** Every direct child of `container` with the given `recType`, in document order. */
+function childrenOfType(container, recType) {
+	return container.children.filter((child) => child.recType === recType);
+}
+/** Recursively finds the first descendant record (depth-first, this container's own children before their children) with the given `recType` -- for a record known to appear exactly once at an unspecified depth (the Blip Store, the drawing group's own Dgg), as opposed to childrenOfType's direct-children-only contract. */
+function findDescendant(container, recType) {
+	for (const child of container.children) {
+		if (child.recType === recType) return child;
+		if (child.kind === "container") {
+			const found = findDescendant(child, recType);
+			if (found !== void 0) return found;
+		}
+	}
+}
+//#endregion
+export { childrenOfType, findDescendant, firstChild, readEscherRecords };