archive-codec 1.1.0 → 1.1.2

package/README.md

@@ -16,18 +16,28 @@ Requires Node.js `>=20` and pnpm `11.6.0`.
 
 ```sh
 pnpm install
-pnpm build          # tsdown -> dist/ (ESM + CJS + .d.ts)
+pnpm build          # tsdown -> dist/ (ESM + CJS + .d.ts, one file set per src module)
 pnpm typecheck      # tsc -p tsconfig.json && tsc -p tsconfig.node.json (dual tsconfig)
 pnpm lint           # eslint . --fix --cache --max-warnings 0
-pnpm test           # vitest run
-pnpm test:watch     # vitest
+pnpm test           # vitest run --project unit
+pnpm test:watch     # vitest --project unit
 pnpm test:workers   # vitest run --config vitest.workers.config.ts, inside a real Cloudflare Workers (workerd) isolate
+pnpm test:smoke     # builds dist/, then loads the built ESM and CJS barrels and every advertised deep import
 ```
 
 To run a single test file, pass its path to vitest directly, e.g. `pnpm exec vitest run src/zip/walk.test.ts`.
 
 ## What it provides
 
+Every module is importable by package-relative path as well as through the barrel — `tsdown` builds one dist file per src module (`root: 'src'`, the same layout ooxml.js ships), and `package.json`'s `./*` exports wildcard maps each subpath onto it:
+
+```ts
+import { readCompoundFile } from 'archive-codec/cfb/read';
+import { walkArchive } from 'archive-codec/zip/walk';
+```
+
+The smoke suite (`test/smoke.test.mjs`) is the guard on that advertisement: it loads each module below from the built `dist/` in both module systems, so a build config that stops serving an advertised subpath fails the suite — neither publint nor `attw` catches a wildcard whose targets are missing.
+
 | Module | Exports |
 |---|---|
 | `zip/container` | `zipPackage` (ordered-entries ZIP write with stored-uncompressed support), `unzipPackage`, `ZipEntry` |
@@ -96,7 +106,7 @@ npm install archive-codec
 
 ## Release and publishing
 
-Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the mechanism (topological per-package `semantic-release` via `@exadev/semantic-release-workspace`, OIDC trusted npm publishing, automatic sibling dependency-range rewriting) and its [known gap](../../README.md#releases) note on GitHub Packages republishing and SBOM/provenance signing, both dropped in the migration to this monorepo and not yet restored.
+Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the mechanism (topological per-package `semantic-release` via `@exadev/semantic-release-workspace`, OIDC trusted npm publishing, automatic sibling dependency-range rewriting) and its [post-release republishing and attestation](../../README.md#releases) note on the restored GitHub Packages mirrors, npm aliases, and SBOM/provenance signing.
 
 ## Contributing
 

package/dist/cfb/detect.cjs

@@ -0,0 +1,18 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_magic = require("../magic.cjs");
+//#region src/cfb/detect.ts
+const COMPOUND_FILE_MAGIC = [
+	208,
+	207,
+	17,
+	224,
+	161,
+	177,
+	26,
+	225
+];
+function isCompoundFile(bytes) {
+	return require_magic.startsWithMagic(bytes, COMPOUND_FILE_MAGIC);
+}
+//#endregion
+exports.isCompoundFile = isCompoundFile;

package/dist/cfb/detect.d.cts

@@ -0,0 +1,4 @@
+//#region src/cfb/detect.d.ts
+declare function isCompoundFile(bytes: Uint8Array): boolean;
+//#endregion
+export { isCompoundFile };

package/dist/cfb/detect.d.ts

@@ -0,0 +1,4 @@
+//#region src/cfb/detect.d.ts
+declare function isCompoundFile(bytes: Uint8Array): boolean;
+//#endregion
+export { isCompoundFile };

package/dist/cfb/detect.js

@@ -0,0 +1,17 @@
+import { startsWithMagic } from "../magic.js";
+//#region src/cfb/detect.ts
+const COMPOUND_FILE_MAGIC = [
+	208,
+	207,
+	17,
+	224,
+	161,
+	177,
+	26,
+	225
+];
+function isCompoundFile(bytes) {
+	return startsWithMagic(bytes, COMPOUND_FILE_MAGIC);
+}
+//#endregion
+export { isCompoundFile };

package/dist/cfb/ole-package.cjs

@@ -0,0 +1,42 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/cfb/ole-package.ts
+var OlePackageFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OlePackageFormatError";
+	}
+};
+const ANSI_DECODER = new TextDecoder("windows-1252");
+function readZeroTerminated(bytes, offset, fieldName) {
+	let end = offset;
+	while (end < bytes.length && bytes[end] !== 0) end++;
+	if (end >= bytes.length) throw new OlePackageFormatError(`Package stream ends inside its ${fieldName} string with no terminator`);
+	return {
+		value: ANSI_DECODER.decode(bytes.subarray(offset, end)),
+		next: end + 1
+	};
+}
+function readOlePackage(bytes) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let offset = 2;
+	const label = readZeroTerminated(bytes, offset, "label");
+	offset = label.next;
+	const sourcePath = readZeroTerminated(bytes, offset, "source path");
+	offset = sourcePath.next;
+	offset += 8;
+	const tempPath = readZeroTerminated(bytes, offset, "temp path");
+	offset = tempPath.next;
+	if (offset + 4 > bytes.length) throw new OlePackageFormatError("Package stream ends before its packaged file size field");
+	const fileByteCount = view.getUint32(offset, true);
+	offset += 4;
+	if (offset + fileByteCount > bytes.length) throw new OlePackageFormatError(`Package stream declares ${fileByteCount} packaged-file bytes but holds only ${bytes.length - offset}`);
+	return {
+		label: label.value,
+		sourcePath: sourcePath.value,
+		tempPath: tempPath.value,
+		fileBytes: bytes.slice(offset, offset + fileByteCount)
+	};
+}
+//#endregion
+exports.OlePackageFormatError = OlePackageFormatError;
+exports.readOlePackage = readOlePackage;

package/dist/cfb/ole-package.d.cts

@@ -0,0 +1,13 @@
+//#region src/cfb/ole-package.d.ts
+declare class OlePackageFormatError extends Error {
+  constructor(message: string);
+}
+interface OlePackage {
+  readonly label: string;
+  readonly sourcePath: string;
+  readonly tempPath: string;
+  readonly fileBytes: Uint8Array<ArrayBuffer>;
+}
+declare function readOlePackage(bytes: Uint8Array<ArrayBuffer>): OlePackage;
+//#endregion
+export { OlePackage, OlePackageFormatError, readOlePackage };

package/dist/cfb/ole-package.d.ts

@@ -0,0 +1,13 @@
+//#region src/cfb/ole-package.d.ts
+declare class OlePackageFormatError extends Error {
+  constructor(message: string);
+}
+interface OlePackage {
+  readonly label: string;
+  readonly sourcePath: string;
+  readonly tempPath: string;
+  readonly fileBytes: Uint8Array<ArrayBuffer>;
+}
+declare function readOlePackage(bytes: Uint8Array<ArrayBuffer>): OlePackage;
+//#endregion
+export { OlePackage, OlePackageFormatError, readOlePackage };

package/dist/cfb/ole-package.js

@@ -0,0 +1,40 @@
+//#region src/cfb/ole-package.ts
+var OlePackageFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OlePackageFormatError";
+	}
+};
+const ANSI_DECODER = new TextDecoder("windows-1252");
+function readZeroTerminated(bytes, offset, fieldName) {
+	let end = offset;
+	while (end < bytes.length && bytes[end] !== 0) end++;
+	if (end >= bytes.length) throw new OlePackageFormatError(`Package stream ends inside its ${fieldName} string with no terminator`);
+	return {
+		value: ANSI_DECODER.decode(bytes.subarray(offset, end)),
+		next: end + 1
+	};
+}
+function readOlePackage(bytes) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let offset = 2;
+	const label = readZeroTerminated(bytes, offset, "label");
+	offset = label.next;
+	const sourcePath = readZeroTerminated(bytes, offset, "source path");
+	offset = sourcePath.next;
+	offset += 8;
+	const tempPath = readZeroTerminated(bytes, offset, "temp path");
+	offset = tempPath.next;
+	if (offset + 4 > bytes.length) throw new OlePackageFormatError("Package stream ends before its packaged file size field");
+	const fileByteCount = view.getUint32(offset, true);
+	offset += 4;
+	if (offset + fileByteCount > bytes.length) throw new OlePackageFormatError(`Package stream declares ${fileByteCount} packaged-file bytes but holds only ${bytes.length - offset}`);
+	return {
+		label: label.value,
+		sourcePath: sourcePath.value,
+		tempPath: tempPath.value,
+		fileBytes: bytes.slice(offset, offset + fileByteCount)
+	};
+}
+//#endregion
+export { OlePackageFormatError, readOlePackage };

package/dist/cfb/read.cjs

@@ -0,0 +1,206 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_cfb_detect = require("./detect.cjs");
+//#region src/cfb/read.ts
+const ENDOFCHAIN = 4294967294;
+const FREESECT = 4294967295;
+const FATSECT = 4294967293;
+const DIFSECT = 4294967292;
+const NOSTREAM = 4294967295;
+const HEADER_SIZE = 512;
+const HEADER_DIFAT_ENTRIES = 109;
+const OBJECT_TYPE_STORAGE = 1;
+const OBJECT_TYPE_STREAM = 2;
+const OBJECT_TYPE_ROOT = 5;
+const MAX_CFB_TOTAL_STREAM_BYTES = 536870912;
+var CompoundFileFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CompoundFileFormatError";
+	}
+};
+function u32(view, offset) {
+	return view.getUint32(offset, true);
+}
+function u16(view, offset) {
+	return view.getUint16(offset, true);
+}
+function readCompoundFile(bytes, options = {}) {
+	const maxTotalBytes = options.maxTotalBytes ?? 536870912;
+	if (!require_cfb_detect.isCompoundFile(bytes)) throw new CompoundFileFormatError("readCompoundFile input does not carry the compound-file signature (leading magic bytes are not D0 CF 11 E0 A1 B1 1A E1)");
+	if (bytes.length < HEADER_SIZE) throw new CompoundFileFormatError(`compound file is ${bytes.length} bytes, shorter than the fixed ${HEADER_SIZE}-byte header`);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const majorVersion = u16(view, 26);
+	if (majorVersion !== 3 && majorVersion !== 4) throw new CompoundFileFormatError(`compound file major version ${majorVersion} is not 3 or 4`);
+	if (u16(view, 28) !== 65534) throw new CompoundFileFormatError("compound file byte order is not little-endian");
+	const sectorShift = u16(view, 30);
+	if (majorVersion === 3 && sectorShift !== 9 || majorVersion === 4 && sectorShift !== 12) throw new CompoundFileFormatError(`compound file sector shift 2^${sectorShift} does not match major version ${majorVersion} (version 3 requires 512-byte sectors, version 4 requires 4096-byte)`);
+	const miniSectorShift = u16(view, 32);
+	if (miniSectorShift !== 6) throw new CompoundFileFormatError(`compound file mini sector shift 2^${miniSectorShift} is not the mandated 64-byte mini sector`);
+	const sectorSize = 1 << sectorShift;
+	const miniSectorSize = 1 << miniSectorShift;
+	const miniStreamCutoff = u32(view, 56);
+	if (miniStreamCutoff < miniSectorSize) throw new CompoundFileFormatError(`compound file mini stream cutoff ${miniStreamCutoff} is smaller than the ${miniSectorSize}-byte mini sector itself`);
+	const firstDirectorySector = u32(view, 48);
+	const firstMiniFatSector = u32(view, 60);
+	const firstDifatSector = u32(view, 68);
+	const sectorCount = Math.floor(bytes.length / sectorSize) - 1;
+	if (sectorCount < 1) throw new CompoundFileFormatError(`compound file holds no complete ${sectorSize}-byte sector after its header`);
+	const sectorOffset = (sector) => (sector + 1) * sectorSize;
+	const sectorBytes = (sector) => bytes.subarray(sectorOffset(sector), sectorOffset(sector) + sectorSize);
+	const fatSectorIds = [];
+	const acceptFatSector = (sector, provenance) => {
+		if (sector === FREESECT) return;
+		if (sector >= sectorCount) throw new CompoundFileFormatError(`${provenance} names FAT sector ${sector}, which is outside the file's ${sectorCount} sectors`);
+		fatSectorIds.push(sector);
+	};
+	for (let i = 0; i < HEADER_DIFAT_ENTRIES; i++) acceptFatSector(u32(view, 76 + i * 4), "the header DIFAT array");
+	let difatSector = firstDifatSector;
+	let difatSectorsWalked = 0;
+	while (difatSector !== ENDOFCHAIN) {
+		if (difatSector >= sectorCount) throw new CompoundFileFormatError(`the DIFAT chain names sector ${difatSector}, which is outside the file's ${sectorCount} sectors`);
+		if (++difatSectorsWalked > sectorCount) throw new CompoundFileFormatError("the DIFAT chain visits more sectors than the file holds, so it must cycle");
+		const difatView = new DataView(bytes.buffer, bytes.byteOffset + sectorOffset(difatSector), sectorSize);
+		const entriesPerDifatSector = sectorSize / 4 - 1;
+		for (let i = 0; i < entriesPerDifatSector; i++) acceptFatSector(u32(difatView, i * 4), "a DIFAT sector");
+		difatSector = u32(difatView, entriesPerDifatSector * 4);
+	}
+	if (fatSectorIds.length === 0) throw new CompoundFileFormatError("compound file declares no FAT sectors, so no sector chain can be walked");
+	const fatBytes = new Uint8Array(fatSectorIds.length * sectorSize);
+	for (let i = 0; i < fatSectorIds.length; i++) fatBytes.set(sectorBytes(fatSectorIds[i] ?? 0), i * sectorSize);
+	const fat = new DataView(fatBytes.buffer);
+	const fatEntry = (sector) => {
+		const offset = sector * 4;
+		if (offset < 0 || offset + 4 > fatBytes.length) throw new CompoundFileFormatError(`FAT entry for sector ${sector} lies beyond the sectors the DIFAT named`);
+		return fat.getUint32(offset, true);
+	};
+	const chainSectorIds = (start) => {
+		const ids = [];
+		let current = start;
+		while (current !== ENDOFCHAIN) {
+			if (current >= sectorCount) throw new CompoundFileFormatError(`a FAT chain steps to sector ${current}, which is outside the file's ${sectorCount} sectors`);
+			if (ids.length >= sectorCount) throw new CompoundFileFormatError("a FAT chain visits more sectors than the file holds, so it must cycle");
+			ids.push(current);
+			const next = fatEntry(current);
+			if (next === FREESECT || next === FATSECT || next === DIFSECT) throw new CompoundFileFormatError(`a FAT chain steps to sector ${current}'s entry ${next}, which is a sector-role marker, not a chain continuation`);
+			current = next;
+		}
+		return ids;
+	};
+	const chainBytes = (start) => {
+		const ids = chainSectorIds(start);
+		const out = new Uint8Array(ids.length * sectorSize);
+		for (let i = 0; i < ids.length; i++) out.set(sectorBytes(ids[i] ?? 0), i * sectorSize);
+		return out;
+	};
+	const directoryBytes = chainBytes(firstDirectorySector);
+	if (directoryBytes.length === 0) throw new CompoundFileFormatError("compound file has an empty directory chain");
+	const directoryView = new DataView(directoryBytes.buffer);
+	const entryCount = directoryBytes.length / 128;
+	const nameDecoder = new TextDecoder("utf-16le");
+	const entries = [];
+	for (let id = 0; id < entryCount; id++) {
+		const base = id * 128;
+		const nameLength = u16(directoryView, base + 64);
+		entries.push({
+			name: nameDecoder.decode(directoryBytes.subarray(base, base + Math.max(0, nameLength - 2))),
+			nameLength,
+			objectType: directoryView.getUint8(base + 66),
+			leftSibling: u32(directoryView, base + 68),
+			rightSibling: u32(directoryView, base + 72),
+			child: u32(directoryView, base + 76),
+			startSector: u32(directoryView, base + 116),
+			size: u32(directoryView, base + 120) + u32(directoryView, base + 124) * 4294967296
+		});
+	}
+	const root = entries[0];
+	if (root === void 0 || root.objectType !== OBJECT_TYPE_ROOT) throw new CompoundFileFormatError("the first directory entry is not the root storage entry (object type 5), as [MS-CFB] 2.6.1 requires");
+	const miniStream = chainBytes(root.startSector).subarray(0, root.size);
+	const miniSectorCount = Math.floor(miniStream.length / miniSectorSize);
+	const miniFatBytes = chainBytes(firstMiniFatSector);
+	const miniFat = new DataView(miniFatBytes.buffer);
+	const miniChainSectorIds = (start) => {
+		const ids = [];
+		let current = start;
+		while (current !== ENDOFCHAIN) {
+			if (current >= miniSectorCount) throw new CompoundFileFormatError(`a mini-FAT chain steps to mini sector ${current}, which is outside the mini stream's ${miniSectorCount} mini sectors`);
+			if (ids.length >= miniSectorCount) throw new CompoundFileFormatError("a mini-FAT chain visits more mini sectors than the mini stream holds, so it must cycle");
+			ids.push(current);
+			const next = miniFat.getUint32(current * 4, true);
+			if (next === FREESECT || next === FATSECT || next === DIFSECT) throw new CompoundFileFormatError(`a mini-FAT chain steps to mini sector ${current}'s entry ${next}, which is a sector-role marker, not a chain continuation`);
+			current = next;
+		}
+		return ids;
+	};
+	let totalExtractedBytes = 0;
+	const extractStream = (entry) => {
+		if (entry.size === 0) return /* @__PURE__ */ new Uint8Array(0);
+		if (entry.size > Number.MAX_SAFE_INTEGER) throw new CompoundFileFormatError(`stream '${entry.name}' declares a size beyond the integer range this reader addresses`);
+		let out;
+		if (entry.size < miniStreamCutoff) {
+			const ids = miniChainSectorIds(entry.startSector);
+			const raw = new Uint8Array(ids.length * miniSectorSize);
+			for (let i = 0; i < ids.length; i++) {
+				const miniSector = ids[i] ?? 0;
+				raw.set(miniStream.subarray(miniSector * miniSectorSize, (miniSector + 1) * miniSectorSize), i * miniSectorSize);
+			}
+			out = raw;
+		} else out = chainBytes(entry.startSector);
+		if (out.length < entry.size) throw new CompoundFileFormatError(`stream '${entry.name}' declares ${entry.size} bytes but its chain holds only ${out.length}`);
+		totalExtractedBytes += entry.size;
+		if (totalExtractedBytes > maxTotalBytes) throw new CompoundFileFormatError(`cumulative extracted stream size exceeded the ${maxTotalBytes}-byte budget at '${entry.name}'`);
+		return out.slice(0, entry.size);
+	};
+	const streams = [];
+	const visited = /* @__PURE__ */ new Set();
+	const stack = [{
+		id: root.child,
+		prefix: "",
+		stage: "descend"
+	}];
+	for (let frame = stack.pop(); frame !== void 0; frame = stack.pop()) if (frame.stage === "descend") {
+		const { id, prefix } = frame;
+		if (id === NOSTREAM) continue;
+		const entry = entries[id];
+		if (id >= entryCount || entry === void 0) throw new CompoundFileFormatError(`the directory tree links to entry ${id}, which is outside the directory's ${entryCount} entries`);
+		if (visited.has(id)) throw new CompoundFileFormatError(`the directory tree reaches entry ${id} twice, so its sibling and child links cycle`);
+		visited.add(id);
+		if (entry.nameLength < 2 || entry.nameLength > 64 || entry.nameLength % 2 === 1) throw new CompoundFileFormatError(`directory entry ${id} declares name length ${entry.nameLength}, which is not an even byte count between 2 and 64`);
+		if (entry.objectType !== OBJECT_TYPE_STORAGE && entry.objectType !== OBJECT_TYPE_STREAM && entry.objectType !== OBJECT_TYPE_ROOT) throw new CompoundFileFormatError(`directory entry ${id} ('${entry.name}') carries object type ${entry.objectType}, which is not a storage (1), stream (2), or root (5) entry`);
+		stack.push({
+			entry,
+			prefix,
+			stage: "self"
+		});
+		stack.push({
+			id: entry.leftSibling,
+			prefix,
+			stage: "descend"
+		});
+	} else if (frame.entry.objectType === OBJECT_TYPE_STREAM) {
+		streams.push({
+			path: frame.prefix + frame.entry.name,
+			bytes: extractStream(frame.entry)
+		});
+		stack.push({
+			id: frame.entry.rightSibling,
+			prefix: frame.prefix,
+			stage: "descend"
+		});
+	} else if (frame.entry.objectType === OBJECT_TYPE_STORAGE) {
+		stack.push({
+			id: frame.entry.rightSibling,
+			prefix: frame.prefix,
+			stage: "descend"
+		});
+		stack.push({
+			id: frame.entry.child,
+			prefix: `${frame.prefix}${frame.entry.name}/`,
+			stage: "descend"
+		});
+	} else throw new CompoundFileFormatError(`the directory tree reaches entry ${frame.entry.name}, which is not a storage or stream entry`);
+	return streams;
+}
+//#endregion
+exports.CompoundFileFormatError = CompoundFileFormatError;
+exports.MAX_CFB_TOTAL_STREAM_BYTES = MAX_CFB_TOTAL_STREAM_BYTES;
+exports.readCompoundFile = readCompoundFile;

package/dist/cfb/read.d.cts

@@ -0,0 +1,15 @@
+//#region src/cfb/read.d.ts
+declare const MAX_CFB_TOTAL_STREAM_BYTES: number;
+declare class CompoundFileFormatError extends Error {
+  constructor(message: string);
+}
+interface CompoundFileStream {
+  readonly path: string;
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+interface ReadCompoundFileOptions {
+  readonly maxTotalBytes?: number;
+}
+declare function readCompoundFile(bytes: Uint8Array<ArrayBuffer>, options?: ReadCompoundFileOptions): CompoundFileStream[];
+//#endregion
+export { CompoundFileFormatError, CompoundFileStream, MAX_CFB_TOTAL_STREAM_BYTES, ReadCompoundFileOptions, readCompoundFile };

package/dist/cfb/read.d.ts

@@ -0,0 +1,15 @@
+//#region src/cfb/read.d.ts
+declare const MAX_CFB_TOTAL_STREAM_BYTES: number;
+declare class CompoundFileFormatError extends Error {
+  constructor(message: string);
+}
+interface CompoundFileStream {
+  readonly path: string;
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+interface ReadCompoundFileOptions {
+  readonly maxTotalBytes?: number;
+}
+declare function readCompoundFile(bytes: Uint8Array<ArrayBuffer>, options?: ReadCompoundFileOptions): CompoundFileStream[];
+//#endregion
+export { CompoundFileFormatError, CompoundFileStream, MAX_CFB_TOTAL_STREAM_BYTES, ReadCompoundFileOptions, readCompoundFile };

package/dist/cfb/read.js

@@ -0,0 +1,203 @@
+import { isCompoundFile } from "./detect.js";
+//#region src/cfb/read.ts
+const ENDOFCHAIN = 4294967294;
+const FREESECT = 4294967295;
+const FATSECT = 4294967293;
+const DIFSECT = 4294967292;
+const NOSTREAM = 4294967295;
+const HEADER_SIZE = 512;
+const HEADER_DIFAT_ENTRIES = 109;
+const OBJECT_TYPE_STORAGE = 1;
+const OBJECT_TYPE_STREAM = 2;
+const OBJECT_TYPE_ROOT = 5;
+const MAX_CFB_TOTAL_STREAM_BYTES = 536870912;
+var CompoundFileFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CompoundFileFormatError";
+	}
+};
+function u32(view, offset) {
+	return view.getUint32(offset, true);
+}
+function u16(view, offset) {
+	return view.getUint16(offset, true);
+}
+function readCompoundFile(bytes, options = {}) {
+	const maxTotalBytes = options.maxTotalBytes ?? 536870912;
+	if (!isCompoundFile(bytes)) throw new CompoundFileFormatError("readCompoundFile input does not carry the compound-file signature (leading magic bytes are not D0 CF 11 E0 A1 B1 1A E1)");
+	if (bytes.length < HEADER_SIZE) throw new CompoundFileFormatError(`compound file is ${bytes.length} bytes, shorter than the fixed ${HEADER_SIZE}-byte header`);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const majorVersion = u16(view, 26);
+	if (majorVersion !== 3 && majorVersion !== 4) throw new CompoundFileFormatError(`compound file major version ${majorVersion} is not 3 or 4`);
+	if (u16(view, 28) !== 65534) throw new CompoundFileFormatError("compound file byte order is not little-endian");
+	const sectorShift = u16(view, 30);
+	if (majorVersion === 3 && sectorShift !== 9 || majorVersion === 4 && sectorShift !== 12) throw new CompoundFileFormatError(`compound file sector shift 2^${sectorShift} does not match major version ${majorVersion} (version 3 requires 512-byte sectors, version 4 requires 4096-byte)`);
+	const miniSectorShift = u16(view, 32);
+	if (miniSectorShift !== 6) throw new CompoundFileFormatError(`compound file mini sector shift 2^${miniSectorShift} is not the mandated 64-byte mini sector`);
+	const sectorSize = 1 << sectorShift;
+	const miniSectorSize = 1 << miniSectorShift;
+	const miniStreamCutoff = u32(view, 56);
+	if (miniStreamCutoff < miniSectorSize) throw new CompoundFileFormatError(`compound file mini stream cutoff ${miniStreamCutoff} is smaller than the ${miniSectorSize}-byte mini sector itself`);
+	const firstDirectorySector = u32(view, 48);
+	const firstMiniFatSector = u32(view, 60);
+	const firstDifatSector = u32(view, 68);
+	const sectorCount = Math.floor(bytes.length / sectorSize) - 1;
+	if (sectorCount < 1) throw new CompoundFileFormatError(`compound file holds no complete ${sectorSize}-byte sector after its header`);
+	const sectorOffset = (sector) => (sector + 1) * sectorSize;
+	const sectorBytes = (sector) => bytes.subarray(sectorOffset(sector), sectorOffset(sector) + sectorSize);
+	const fatSectorIds = [];
+	const acceptFatSector = (sector, provenance) => {
+		if (sector === FREESECT) return;
+		if (sector >= sectorCount) throw new CompoundFileFormatError(`${provenance} names FAT sector ${sector}, which is outside the file's ${sectorCount} sectors`);
+		fatSectorIds.push(sector);
+	};
+	for (let i = 0; i < HEADER_DIFAT_ENTRIES; i++) acceptFatSector(u32(view, 76 + i * 4), "the header DIFAT array");
+	let difatSector = firstDifatSector;
+	let difatSectorsWalked = 0;
+	while (difatSector !== ENDOFCHAIN) {
+		if (difatSector >= sectorCount) throw new CompoundFileFormatError(`the DIFAT chain names sector ${difatSector}, which is outside the file's ${sectorCount} sectors`);
+		if (++difatSectorsWalked > sectorCount) throw new CompoundFileFormatError("the DIFAT chain visits more sectors than the file holds, so it must cycle");
+		const difatView = new DataView(bytes.buffer, bytes.byteOffset + sectorOffset(difatSector), sectorSize);
+		const entriesPerDifatSector = sectorSize / 4 - 1;
+		for (let i = 0; i < entriesPerDifatSector; i++) acceptFatSector(u32(difatView, i * 4), "a DIFAT sector");
+		difatSector = u32(difatView, entriesPerDifatSector * 4);
+	}
+	if (fatSectorIds.length === 0) throw new CompoundFileFormatError("compound file declares no FAT sectors, so no sector chain can be walked");
+	const fatBytes = new Uint8Array(fatSectorIds.length * sectorSize);
+	for (let i = 0; i < fatSectorIds.length; i++) fatBytes.set(sectorBytes(fatSectorIds[i] ?? 0), i * sectorSize);
+	const fat = new DataView(fatBytes.buffer);
+	const fatEntry = (sector) => {
+		const offset = sector * 4;
+		if (offset < 0 || offset + 4 > fatBytes.length) throw new CompoundFileFormatError(`FAT entry for sector ${sector} lies beyond the sectors the DIFAT named`);
+		return fat.getUint32(offset, true);
+	};
+	const chainSectorIds = (start) => {
+		const ids = [];
+		let current = start;
+		while (current !== ENDOFCHAIN) {
+			if (current >= sectorCount) throw new CompoundFileFormatError(`a FAT chain steps to sector ${current}, which is outside the file's ${sectorCount} sectors`);
+			if (ids.length >= sectorCount) throw new CompoundFileFormatError("a FAT chain visits more sectors than the file holds, so it must cycle");
+			ids.push(current);
+			const next = fatEntry(current);
+			if (next === FREESECT || next === FATSECT || next === DIFSECT) throw new CompoundFileFormatError(`a FAT chain steps to sector ${current}'s entry ${next}, which is a sector-role marker, not a chain continuation`);
+			current = next;
+		}
+		return ids;
+	};
+	const chainBytes = (start) => {
+		const ids = chainSectorIds(start);
+		const out = new Uint8Array(ids.length * sectorSize);
+		for (let i = 0; i < ids.length; i++) out.set(sectorBytes(ids[i] ?? 0), i * sectorSize);
+		return out;
+	};
+	const directoryBytes = chainBytes(firstDirectorySector);
+	if (directoryBytes.length === 0) throw new CompoundFileFormatError("compound file has an empty directory chain");
+	const directoryView = new DataView(directoryBytes.buffer);
+	const entryCount = directoryBytes.length / 128;
+	const nameDecoder = new TextDecoder("utf-16le");
+	const entries = [];
+	for (let id = 0; id < entryCount; id++) {
+		const base = id * 128;
+		const nameLength = u16(directoryView, base + 64);
+		entries.push({
+			name: nameDecoder.decode(directoryBytes.subarray(base, base + Math.max(0, nameLength - 2))),
+			nameLength,
+			objectType: directoryView.getUint8(base + 66),
+			leftSibling: u32(directoryView, base + 68),
+			rightSibling: u32(directoryView, base + 72),
+			child: u32(directoryView, base + 76),
+			startSector: u32(directoryView, base + 116),
+			size: u32(directoryView, base + 120) + u32(directoryView, base + 124) * 4294967296
+		});
+	}
+	const root = entries[0];
+	if (root === void 0 || root.objectType !== OBJECT_TYPE_ROOT) throw new CompoundFileFormatError("the first directory entry is not the root storage entry (object type 5), as [MS-CFB] 2.6.1 requires");
+	const miniStream = chainBytes(root.startSector).subarray(0, root.size);
+	const miniSectorCount = Math.floor(miniStream.length / miniSectorSize);
+	const miniFatBytes = chainBytes(firstMiniFatSector);
+	const miniFat = new DataView(miniFatBytes.buffer);
+	const miniChainSectorIds = (start) => {
+		const ids = [];
+		let current = start;
+		while (current !== ENDOFCHAIN) {
+			if (current >= miniSectorCount) throw new CompoundFileFormatError(`a mini-FAT chain steps to mini sector ${current}, which is outside the mini stream's ${miniSectorCount} mini sectors`);
+			if (ids.length >= miniSectorCount) throw new CompoundFileFormatError("a mini-FAT chain visits more mini sectors than the mini stream holds, so it must cycle");
+			ids.push(current);
+			const next = miniFat.getUint32(current * 4, true);
+			if (next === FREESECT || next === FATSECT || next === DIFSECT) throw new CompoundFileFormatError(`a mini-FAT chain steps to mini sector ${current}'s entry ${next}, which is a sector-role marker, not a chain continuation`);
+			current = next;
+		}
+		return ids;
+	};
+	let totalExtractedBytes = 0;
+	const extractStream = (entry) => {
+		if (entry.size === 0) return /* @__PURE__ */ new Uint8Array(0);
+		if (entry.size > Number.MAX_SAFE_INTEGER) throw new CompoundFileFormatError(`stream '${entry.name}' declares a size beyond the integer range this reader addresses`);
+		let out;
+		if (entry.size < miniStreamCutoff) {
+			const ids = miniChainSectorIds(entry.startSector);
+			const raw = new Uint8Array(ids.length * miniSectorSize);
+			for (let i = 0; i < ids.length; i++) {
+				const miniSector = ids[i] ?? 0;
+				raw.set(miniStream.subarray(miniSector * miniSectorSize, (miniSector + 1) * miniSectorSize), i * miniSectorSize);
+			}
+			out = raw;
+		} else out = chainBytes(entry.startSector);
+		if (out.length < entry.size) throw new CompoundFileFormatError(`stream '${entry.name}' declares ${entry.size} bytes but its chain holds only ${out.length}`);
+		totalExtractedBytes += entry.size;
+		if (totalExtractedBytes > maxTotalBytes) throw new CompoundFileFormatError(`cumulative extracted stream size exceeded the ${maxTotalBytes}-byte budget at '${entry.name}'`);
+		return out.slice(0, entry.size);
+	};
+	const streams = [];
+	const visited = /* @__PURE__ */ new Set();
+	const stack = [{
+		id: root.child,
+		prefix: "",
+		stage: "descend"
+	}];
+	for (let frame = stack.pop(); frame !== void 0; frame = stack.pop()) if (frame.stage === "descend") {
+		const { id, prefix } = frame;
+		if (id === NOSTREAM) continue;
+		const entry = entries[id];
+		if (id >= entryCount || entry === void 0) throw new CompoundFileFormatError(`the directory tree links to entry ${id}, which is outside the directory's ${entryCount} entries`);
+		if (visited.has(id)) throw new CompoundFileFormatError(`the directory tree reaches entry ${id} twice, so its sibling and child links cycle`);
+		visited.add(id);
+		if (entry.nameLength < 2 || entry.nameLength > 64 || entry.nameLength % 2 === 1) throw new CompoundFileFormatError(`directory entry ${id} declares name length ${entry.nameLength}, which is not an even byte count between 2 and 64`);
+		if (entry.objectType !== OBJECT_TYPE_STORAGE && entry.objectType !== OBJECT_TYPE_STREAM && entry.objectType !== OBJECT_TYPE_ROOT) throw new CompoundFileFormatError(`directory entry ${id} ('${entry.name}') carries object type ${entry.objectType}, which is not a storage (1), stream (2), or root (5) entry`);
+		stack.push({
+			entry,
+			prefix,
+			stage: "self"
+		});
+		stack.push({
+			id: entry.leftSibling,
+			prefix,
+			stage: "descend"
+		});
+	} else if (frame.entry.objectType === OBJECT_TYPE_STREAM) {
+		streams.push({
+			path: frame.prefix + frame.entry.name,
+			bytes: extractStream(frame.entry)
+		});
+		stack.push({
+			id: frame.entry.rightSibling,
+			prefix: frame.prefix,
+			stage: "descend"
+		});
+	} else if (frame.entry.objectType === OBJECT_TYPE_STORAGE) {
+		stack.push({
+			id: frame.entry.rightSibling,
+			prefix: frame.prefix,
+			stage: "descend"
+		});
+		stack.push({
+			id: frame.entry.child,
+			prefix: `${frame.prefix}${frame.entry.name}/`,
+			stage: "descend"
+		});
+	} else throw new CompoundFileFormatError(`the directory tree reaches entry ${frame.entry.name}, which is not a storage or stream entry`);
+	return streams;
+}
+//#endregion
+export { CompoundFileFormatError, MAX_CFB_TOTAL_STREAM_BYTES, readCompoundFile };