@clearmist-labs/comic-archive-handler 1.0.0

package/dist/index.mjs

@@ -0,0 +1,2157 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { fileTypeFromBuffer, fileTypeFromFile } from "file-type";
+import * as fs from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import * as fsp from "node:fs/promises";
+import { PassThrough, Readable } from "node:stream";
+import { Unzip, UnzipInflate, Zip, ZipDeflate } from "fflate";
+import * as tarStream from "tar-stream";
+import { createExtractorFromData } from "node-unrar-js";
+import * as path from "node:path";
+import { dirname, join } from "node:path";
+import { createPackage } from "@electron/asar";
+import * as os from "node:os";
+import { spawn } from "node:child_process";
+import sevenBin from "7zip-bin-full";
+import sharp from "sharp";
+import { pipeline } from "node:stream/promises";
+import { XMLBuilder, XMLParser } from "fast-xml-parser";
+import { validateXML } from "xmllint-wasm";
+import { fileURLToPath } from "node:url";
+import { createHash } from "node:crypto";
+//#region src/errors.ts
+var UnsupportedOperationError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UnsupportedOperationError";
+	}
+};
+var ArchiveFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ArchiveFormatError";
+	}
+};
+var MetadataNotFoundError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MetadataNotFoundError";
+	}
+};
+var FilesystemAccessError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FilesystemAccessError";
+	}
+};
+var SevenZipUnavailableError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "SevenZipUnavailableError";
+	}
+};
+var NoImagesFoundError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "NoImagesFoundError";
+	}
+};
+//#endregion
+//#region src/internal/inputSource.ts
+function isPathInput(input) {
+	return typeof input === "string";
+}
+async function inputToBuffer(input) {
+	return isPathInput(input) ? fsp.readFile(input) : input;
+}
+async function inputSize(input) {
+	if (isPathInput(input)) return (await fsp.stat(input)).size;
+	return input.length;
+}
+/** Reads the half-open byte range [start, end) from a Buffer or file path. */
+async function readInputRange(input, start, end) {
+	if (!isPathInput(input)) return Buffer.from(input.subarray(start, end));
+	const fd = await fsp.open(input, "r");
+	try {
+		const length = Math.max(0, end - start);
+		const buf = Buffer.alloc(length);
+		const { bytesRead } = await fd.read(buf, 0, length, start);
+		return buf.subarray(0, bytesRead);
+	} finally {
+		await fd.close();
+	}
+}
+function openInputReadStream(input, range) {
+	if (isPathInput(input)) return fs.createReadStream(input, range ? {
+		start: range.start,
+		end: range.end - 1
+	} : void 0);
+	const slice = range ? input.subarray(range.start, range.end) : input;
+	return Readable.from(slice);
+}
+//#endregion
+//#region src/internal/asarHeader.ts
+/**
+* Parses an asar archive's header from a byte reader.
+*
+* On-disk layout (Chromium Pickle format, two levels of nesting):
+*   [8 bytes: outer pickle wrapping a uint32 `size`]
+*   [`size` bytes: header pickle == [4-byte LE payload length][payload]]
+*     payload == string pickle == [4-byte LE string byte-length][UTF-8 bytes (+padding, ignored here)]
+*   [content region: raw concatenated file bytes, starting at 8 + size]
+*/
+async function parseAsarHeader(readRange) {
+	const prefix = await readRange(0, 8);
+	if (prefix.length < 8) throw new ArchiveFormatError("File is too small to be a valid asar archive.");
+	if (prefix.readUInt32LE(0) !== 4) throw new ArchiveFormatError("Not a valid asar archive (unexpected pickle header).");
+	const size = prefix.readUInt32LE(4);
+	const headerBuf = await readRange(8, 8 + size);
+	if (headerBuf.length < 8) throw new ArchiveFormatError("Not a valid asar archive (truncated header).");
+	const stringLength = headerBuf.readUInt32LE(4);
+	if (8 + stringLength > headerBuf.length) throw new ArchiveFormatError("Not a valid asar archive (truncated header string).");
+	const headerString = headerBuf.subarray(8, 8 + stringLength).toString("utf8");
+	let header;
+	try {
+		header = JSON.parse(headerString);
+	} catch {
+		throw new ArchiveFormatError("Not a valid asar archive (header is not valid JSON).");
+	}
+	if (!header || typeof header !== "object" || !header.files) throw new ArchiveFormatError("Not a valid asar archive (header has no files index).");
+	const contentOffset = 8 + size;
+	const files = [];
+	collectFiles(header, "", files);
+	return {
+		header,
+		files,
+		contentOffset
+	};
+}
+function collectFiles(node, prefix, out) {
+	if (!node.files) return;
+	for (const [name, child] of Object.entries(node.files)) {
+		const entryPath = prefix ? `${prefix}/${name}` : name;
+		if (child.files) collectFiles(child, entryPath, out);
+		else if (typeof child.offset === "string" && typeof child.size === "number") out.push({
+			path: entryPath,
+			offset: Number(child.offset),
+			size: child.size
+		});
+	}
+}
+/** True if the header's file tree contains an entry at the archive root named `name`. */
+function hasRootFile(header, name) {
+	const root = header;
+	return Boolean(root?.files?.[name] && !root.files[name]?.files);
+}
+//#endregion
+//#region src/detect.ts
+var detect_exports = /* @__PURE__ */ __exportAll({
+	detectArchiveType: () => detectArchiveType,
+	is7z: () => is7z,
+	isAce: () => isAce,
+	isAsar: () => isAsar,
+	isRar: () => isRar,
+	isTar: () => isTar,
+	isZip: () => isZip
+});
+const EXT_TO_TYPE = {
+	zip: "zip",
+	rar: "rar",
+	tar: "tar",
+	"7z": "7z",
+	ace: "ace"
+};
+async function detectViaFileType(input) {
+	const result = isPathInput(input) ? await fileTypeFromFile(input) : await fileTypeFromBuffer(input);
+	if (!result) return;
+	return EXT_TO_TYPE[result.ext];
+}
+async function looksLikeAsar(input) {
+	try {
+		const header = await parseAsarHeader((start, end) => readInputRange(input, start, end));
+		return Boolean(header.files);
+	} catch {
+		return false;
+	}
+}
+async function detectArchiveType(input) {
+	const viaMagicBytes = await detectViaFileType(input);
+	if (viaMagicBytes) return viaMagicBytes;
+	if (await looksLikeAsar(input)) return "asar";
+	return "unknown";
+}
+async function isZip(input) {
+	return await detectArchiveType(input) === "zip";
+}
+async function isRar(input) {
+	return await detectArchiveType(input) === "rar";
+}
+async function isTar(input) {
+	return await detectArchiveType(input) === "tar";
+}
+async function isAsar(input) {
+	return await detectArchiveType(input) === "asar";
+}
+async function is7z(input) {
+	return await detectArchiveType(input) === "7z";
+}
+async function isAce(input) {
+	return await detectArchiveType(input) === "ace";
+}
+//#endregion
+//#region src/internal/streamUtils.ts
+async function streamToBuffer(stream) {
+	const chunks = [];
+	for await (const chunk of stream) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+	return Buffer.concat(chunks);
+}
+/** Bridges a callback-driven push source into an async iterable, in arrival order. */
+var AsyncQueue = class {
+	items = [];
+	waiter = null;
+	done = false;
+	error = null;
+	push(item) {
+		this.items.push(item);
+		this.waiter?.();
+	}
+	finish() {
+		this.done = true;
+		this.waiter?.();
+	}
+	fail(err) {
+		this.error = err;
+		this.done = true;
+		this.waiter?.();
+	}
+	async *[Symbol.asyncIterator]() {
+		for (;;) {
+			if (this.items.length) {
+				yield this.items.shift();
+				continue;
+			}
+			if (this.error) throw this.error;
+			if (this.done) return;
+			await new Promise((resolve) => {
+				this.waiter = resolve;
+			});
+			this.waiter = null;
+		}
+	}
+};
+//#endregion
+//#region src/archive/zip.ts
+function toEntry(file) {
+	return {
+		path: file.name,
+		size: file.originalSize,
+		openReadStream() {
+			const pass = new PassThrough();
+			file.ondata = (err, data, final) => {
+				if (err) {
+					pass.destroy(err);
+					return;
+				}
+				if (data.length) pass.write(Buffer.from(data));
+				if (final) pass.end();
+			};
+			file.start();
+			return pass;
+		}
+	};
+}
+const zipAdapter = {
+	type: "zip",
+	canWrite: true,
+	async *listEntries(input) {
+		const source = openInputReadStream(input);
+		const queue = new AsyncQueue();
+		const unzip = new Unzip();
+		unzip.register(UnzipInflate);
+		unzip.onfile = (file) => {
+			if (file.name.endsWith("/")) return;
+			queue.push(toEntry(file));
+		};
+		source.on("data", (chunk) => unzip.push(new Uint8Array(chunk), false));
+		source.on("end", () => {
+			unzip.push(/* @__PURE__ */ new Uint8Array(0), true);
+			queue.finish();
+		});
+		source.on("error", (err) => queue.fail(err));
+		yield* queue;
+	},
+	async write(entries, destination) {
+		await new Promise((resolve, reject) => {
+			const zip = new Zip((err, data, final) => {
+				if (err) {
+					destination.destroy(err);
+					reject(err);
+					return;
+				}
+				destination.write(Buffer.from(data));
+				if (final) {
+					destination.end();
+					resolve();
+				}
+			});
+			(async () => {
+				for await (const entry of entries) {
+					const zipFile = new ZipDeflate(entry.path);
+					zip.add(zipFile);
+					for await (const chunk of entry.content) zipFile.push(new Uint8Array(chunk), false);
+					zipFile.push(/* @__PURE__ */ new Uint8Array(0), true);
+				}
+				zip.end();
+			})().catch(reject);
+		});
+	}
+};
+//#endregion
+//#region src/archive/tar.ts
+/**
+* tar-stream v3 is built on `streamx`, not Node's native streams; its
+* `extract()` result is directly async-iterable over per-entry streams, and
+* both directions interop with Node streams via `.pipe()`. Each entry's
+* content is buffered fully before being yielded — bounded by a single
+* entry's size (one comic page), not the whole archive — since the
+* underlying iterator only advances once the current entry is drained,
+* which doesn't reconcile with this package's lazily-pulled
+* `ArchiveEntry.openReadStream()` contract.
+*/
+const tarAdapter = {
+	type: "tar",
+	canWrite: true,
+	async *listEntries(input) {
+		const source = openInputReadStream(input);
+		const extract = tarStream.extract();
+		source.pipe(extract);
+		for await (const entryStream of extract) {
+			const header = entryStream.header;
+			const buffer = await streamToBuffer(entryStream);
+			if (header.type === "directory") continue;
+			yield {
+				path: header.name,
+				size: buffer.length,
+				openReadStream: () => Readable.from(buffer)
+			};
+		}
+	},
+	async write(entries, destination) {
+		const pack = tarStream.pack();
+		pack.pipe(destination);
+		for await (const entry of entries) {
+			const buffer = await streamToBuffer(entry.content);
+			await new Promise((resolve, reject) => {
+				pack.entry({
+					name: entry.path,
+					size: buffer.length
+				}, buffer, (err) => err ? reject(err) : resolve());
+			});
+		}
+		pack.finalize();
+		await new Promise((resolve, reject) => {
+			destination.on("finish", resolve);
+			destination.on("error", reject);
+		});
+	}
+};
+//#endregion
+//#region src/archive/rar.ts
+function toArrayBuffer(buf) {
+	return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}
+/**
+* node-unrar-js cannot extract entries one at a time (a confirmed library
+* limitation) — it decodes the whole archive into memory up front. This
+* adapter still exposes the lazily-pulled ArchiveAdapter shape, but does not
+* get the memory-efficiency win the interface provides for zip/tar/asar.
+*/
+const rarAdapter = {
+	type: "rar",
+	canWrite: false,
+	async *listEntries(input) {
+		const buffer = await inputToBuffer(input);
+		const extractor = await createExtractorFromData({ data: toArrayBuffer(buffer) });
+		const names = [...extractor.getFileList().fileHeaders].filter((header) => !header.flags.directory).map((header) => header.name);
+		const extracted = extractor.extract({ files: names });
+		for (const file of extracted.files) {
+			if (!file.extraction) continue;
+			const data = Buffer.from(file.extraction);
+			yield {
+				path: file.fileHeader.name,
+				size: data.length,
+				openReadStream: () => Readable.from(data)
+			};
+		}
+	},
+	async write() {
+		throw new UnsupportedOperationError("Creating RAR archives is not supported: the UnRAR source license permits decompression only, not building a compatible compressor. Convert to zip, tar, or asar instead.");
+	}
+};
+//#endregion
+//#region src/internal/tempDir.ts
+async function isWritableDir(dir) {
+	const probe = path.join(dir, `.cah-write-probe-${process.pid}-${Date.now()}`);
+	try {
+		await fsp.writeFile(probe, "");
+		await fsp.rm(probe, { force: true });
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Resolves a writable staging directory for operations that require real
+* filesystem access (asar writes, any 7z operation).
+*
+* - If `preferredDir` is given, it must already exist and be writable, or a
+*   FilesystemAccessError is thrown naming the path (no silent fallback).
+* - Otherwise, attempts `fs.mkdtemp()` under `os.tmpdir()`.
+* - If that also fails (no writable tmp available, e.g. a locked-down
+*   sandbox), throws FilesystemAccessError telling the caller to pass
+*   `{ tempDir }` explicitly.
+*
+* Returns a freshly created subdirectory the caller owns and is responsible
+* for cleaning up.
+*/
+async function resolveWritableTempDir(preferredDir) {
+	if (preferredDir) {
+		if (!await isWritableDir(preferredDir)) throw new FilesystemAccessError(`The provided tempDir "${preferredDir}" is not writable. Pass a writable directory via { tempDir }.`);
+		return fsp.mkdtemp(path.join(preferredDir, "cah-"));
+	}
+	try {
+		return await fsp.mkdtemp(path.join(os.tmpdir(), "cah-"));
+	} catch (err) {
+		throw new FilesystemAccessError(`No writable temporary directory is available (${err.message}). Supply one explicitly via { tempDir: "<writable path>" }.`);
+	}
+}
+async function cleanupTempDir(dir) {
+	await fsp.rm(dir, {
+		recursive: true,
+		force: true
+	});
+}
+//#endregion
+//#region src/internal/safePath.ts
+/**
+* Resolves an archive entry path against a staging root and verifies the
+* result stays within that root, guarding against zip-slip style path
+* traversal (`../../etc/passwd`, absolute paths, etc.) before anything is
+* written to a real filesystem location.
+*/
+function resolveSafeEntryPath(root, entryPath) {
+	const normalizedEntry = entryPath.replace(/\\/g, "/");
+	const resolved = path.resolve(root, `.${path.sep}${normalizedEntry}`);
+	const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+	if (resolved !== root && !resolved.startsWith(rootWithSep)) throw new ArchiveFormatError(`Refusing to write entry outside staging directory: "${entryPath}"`);
+	return resolved;
+}
+//#endregion
+//#region src/archive/asar.ts
+/**
+* Reads bypass @electron/asar's extract API entirely: the header is parsed
+* directly (src/internal/asarHeader.ts) to get each file's byte offset/size,
+* then entries are read via direct byte-range reads against the archive —
+* no extraction step, no temp directory, for reads.
+*
+* Writes still require a staging directory, since @electron/asar's
+* `createPackage(srcDir, destFile)` only accepts a source directory on
+* disk, not streams or buffers.
+*/
+const asarAdapter = {
+	type: "asar",
+	canWrite: true,
+	async *listEntries(input) {
+		const { files, contentOffset } = await parseAsarHeader((start, end) => readInputRange(input, start, end));
+		for (const file of files) {
+			const start = contentOffset + file.offset;
+			const end = start + file.size;
+			yield {
+				path: file.path,
+				size: file.size,
+				openReadStream: () => openInputReadStream(input, {
+					start,
+					end
+				})
+			};
+		}
+	},
+	async write(entries, destination, options) {
+		const tempDir = await resolveWritableTempDir(options?.tempDir);
+		const stagingDir = path.join(tempDir, "staging");
+		await fsp.mkdir(stagingDir, { recursive: true });
+		try {
+			for await (const entry of entries) {
+				const target = resolveSafeEntryPath(stagingDir, entry.path);
+				await fsp.mkdir(path.dirname(target), { recursive: true });
+				await new Promise((resolve, reject) => {
+					const out = fs.createWriteStream(target);
+					entry.content.on("error", reject);
+					out.on("error", reject);
+					out.on("finish", resolve);
+					entry.content.pipe(out);
+				});
+			}
+			const outputFile = path.join(tempDir, "output.asar");
+			await createPackage(stagingDir, outputFile);
+			await new Promise((resolve, reject) => {
+				const readStream = fs.createReadStream(outputFile);
+				readStream.on("error", reject);
+				destination.on("error", reject);
+				destination.on("finish", resolve);
+				readStream.pipe(destination);
+			});
+		} finally {
+			await cleanupTempDir(tempDir);
+		}
+	}
+};
+//#endregion
+//#region src/archive/sevenZip.ts
+async function ensureBinaryAvailable() {
+	const binPath = sevenBin.path7zzs;
+	if (!fs.existsSync(binPath)) throw new SevenZipUnavailableError(`No 7-Zip binary is available for this platform/architecture (expected at "${binPath}"). 7z read/write is unavailable here; 7z detection via magic bytes still works.`);
+	try {
+		await fsp.access(binPath, fs.constants.X_OK);
+	} catch {
+		try {
+			await fsp.chmod(binPath, 493);
+			await fsp.access(binPath, fs.constants.X_OK);
+		} catch {
+			throw new SevenZipUnavailableError(`The bundled 7-Zip binary at "${binPath}" is not executable and could not be made executable.`);
+		}
+	}
+	return binPath;
+}
+/**
+* Spawns the bundled 7zzs (standalone 7-Zip) binary directly rather than
+* going through the `node-7z` wrapper: that package has no way to set the
+* child process's working directory, which is required here to get archive
+* entries stored with paths relative to the staging directory (rather than
+* either leaking absolute host paths, or — as discovered during
+* implementation testing — silently operating against this process's actual
+* cwd instead of the intended staging directory).
+*/
+function run7z(binPath, args, options) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(binPath, args, {
+			cwd: options.cwd,
+			windowsHide: true
+		});
+		let stderr = "";
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", reject);
+		child.on("close", (code) => {
+			if (code === 0) resolve();
+			else reject(new ArchiveFormatError(`7zzs exited with code ${code}: ${stderr.trim()}`));
+		});
+	});
+}
+async function* walkFiles(root, prefix = "") {
+	const dirents = await fsp.readdir(path.join(root, prefix), { withFileTypes: true });
+	for (const dirent of dirents) {
+		const relPath = prefix ? `${prefix}/${dirent.name}` : dirent.name;
+		if (dirent.isDirectory()) yield* walkFiles(root, relPath);
+		else if (dirent.isFile()) yield {
+			absPath: path.join(root, relPath),
+			relPath
+		};
+	}
+}
+/**
+* Both directions round-trip through a staging directory: the 7z CLI
+* operates on real files, not stdin/stdout, for multi-file archives. Entries
+* are still streamed to/from disk one at a time rather than collected into
+* memory first.
+*/
+const sevenZipAdapter = {
+	type: "7z",
+	canWrite: true,
+	async *listEntries(input, options) {
+		const binPath = await ensureBinaryAvailable();
+		const tempDir = await resolveWritableTempDir(options?.tempDir);
+		try {
+			const archivePath = path.join(tempDir, "input.7z");
+			await fsp.writeFile(archivePath, await inputToBuffer(input));
+			const extractDir = path.join(tempDir, "extracted");
+			await fsp.mkdir(extractDir, { recursive: true });
+			await run7z(binPath, [
+				"x",
+				archivePath,
+				`-o${extractDir}`,
+				"-y"
+			], { cwd: tempDir });
+			for await (const { absPath, relPath } of walkFiles(extractDir)) yield {
+				path: relPath,
+				size: (await fsp.stat(absPath)).size,
+				openReadStream: () => fs.createReadStream(absPath)
+			};
+		} finally {
+			await cleanupTempDir(tempDir);
+		}
+	},
+	async write(entries, destination, options) {
+		const binPath = await ensureBinaryAvailable();
+		const tempDir = await resolveWritableTempDir(options?.tempDir);
+		const stagingDir = path.join(tempDir, "staging");
+		await fsp.mkdir(stagingDir, { recursive: true });
+		try {
+			for await (const entry of entries) {
+				const target = resolveSafeEntryPath(stagingDir, entry.path);
+				await fsp.mkdir(path.dirname(target), { recursive: true });
+				await new Promise((resolve, reject) => {
+					const out = fs.createWriteStream(target);
+					entry.content.on("error", reject);
+					out.on("error", reject);
+					out.on("finish", resolve);
+					entry.content.pipe(out);
+				});
+			}
+			const outputFile = path.join(tempDir, "output.7z");
+			await run7z(binPath, [
+				"a",
+				"-y",
+				outputFile,
+				"*",
+				"-r"
+			], { cwd: stagingDir });
+			await new Promise((resolve, reject) => {
+				const readStream = fs.createReadStream(outputFile);
+				readStream.on("error", reject);
+				destination.on("error", reject);
+				destination.on("finish", resolve);
+				readStream.pipe(destination);
+			});
+		} finally {
+			await cleanupTempDir(tempDir);
+		}
+	}
+};
+//#endregion
+//#region src/archive/ace.ts
+const ACE_UNSUPPORTED_MESSAGE = "ACE (CBA) archives are not supported: ACE is a dead format that hasn't been updated since 2011 and has multiple known security vulnerabilities.";
+//#endregion
+//#region src/archive/index.ts
+const adapters = {
+	zip: zipAdapter,
+	tar: tarAdapter,
+	rar: rarAdapter,
+	asar: asarAdapter,
+	"7z": sevenZipAdapter,
+	ace: {
+		type: "ace",
+		canWrite: false,
+		listEntries() {
+			throw new UnsupportedOperationError(ACE_UNSUPPORTED_MESSAGE);
+		},
+		async write() {
+			throw new UnsupportedOperationError(ACE_UNSUPPORTED_MESSAGE);
+		}
+	}
+};
+function getAdapter(type) {
+	const adapter = adapters[type];
+	if (!adapter) throw new ArchiveFormatError(`No archive adapter is available for type "${type}".`);
+	return adapter;
+}
+//#endregion
+//#region src/internal/collectOutput.ts
+/**
+* Runs `run` against a destination stream. When `output` is given (a path or
+* a Writable), the result streams directly there and this resolves to
+* `undefined`. Otherwise the result is collected into a Buffer for
+* convenience.
+*/
+async function withOutput(output, run) {
+	if (typeof output === "string") {
+		await run(fs.createWriteStream(output));
+		return;
+	}
+	if (output) {
+		await run(output);
+		return;
+	}
+	const pass = new PassThrough();
+	const bufferPromise = streamToBuffer(pass);
+	await run(pass);
+	return bufferPromise;
+}
+//#endregion
+//#region src/images/isImage.ts
+const IMAGE_EXTENSIONS = [
+	"jpg",
+	"jpeg",
+	"png",
+	"gif",
+	"webp",
+	"bmp",
+	"tiff",
+	"tif"
+];
+function getExtension(entryPath) {
+	const match = /\.([^./\\]+)$/.exec(entryPath);
+	return match ? match[1].toLowerCase() : "";
+}
+function isImagePath(entryPath) {
+	return IMAGE_EXTENSIONS.includes(getExtension(entryPath));
+}
+//#endregion
+//#region src/images/convert.ts
+async function convertImageBuffer(image, format, options = {}) {
+	let pipeline = sharp(image);
+	if (format === "webp") {
+		const webp = options.webp ?? {};
+		pipeline = pipeline.webp({
+			quality: webp.quality ?? 92,
+			effort: webp.effort ?? 6,
+			smartSubsample: webp.smartSubsample ?? true
+		});
+	} else if (format === "jpg") {
+		const jpeg = options.jpeg ?? {};
+		pipeline = pipeline.jpeg({ quality: jpeg.quality ?? 90 });
+	} else {
+		const png = options.png ?? {};
+		pipeline = pipeline.png({
+			quality: png.quality,
+			compressionLevel: png.compressionLevel,
+			palette: png.palette
+		});
+	}
+	return pipeline.toBuffer();
+}
+function replaceExtension$1(entryPath, format) {
+	const newExt = format === "jpg" ? "jpg" : format;
+	return `${entryPath.replace(/\.[^./\\]+$/, "")}.${newExt}`;
+}
+async function convertArchiveImages(input, format, options = {}) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	const { tempDir, output, ...imageOptions } = options;
+	async function* entries() {
+		for await (const entry of adapter.listEntries(input, { tempDir })) if (isImagePath(entry.path) && getExtension(entry.path) !== (format === "jpg" ? "jpg" : format)) {
+			const converted = await convertImageBuffer(await streamToBuffer(entry.openReadStream()), format, imageOptions);
+			yield {
+				path: replaceExtension$1(entry.path, format),
+				size: converted.length,
+				content: Readable.from(converted)
+			};
+		} else yield {
+			path: entry.path,
+			size: entry.size,
+			content: entry.openReadStream()
+		};
+	}
+	return withOutput(output, (destination) => adapter.write(entries(), destination, { tempDir }));
+}
+//#endregion
+//#region src/convertArchive.ts
+function replaceExtension(entryPath, format) {
+	return `${entryPath.replace(/\.[^./\\]+$/, "")}.${format}`;
+}
+async function convertArchive(input, targetType, options = {}) {
+	const sourceType = await detectArchiveType(input);
+	if (sourceType === "unknown") throw new ArchiveFormatError("Could not determine the source archive type.");
+	const sourceAdapter = getAdapter(sourceType);
+	const targetAdapter = getAdapter(targetType);
+	const image = options.image;
+	async function* entries() {
+		for await (const entry of sourceAdapter.listEntries(input, { tempDir: options.tempDir })) if (image && isImagePath(entry.path) && getExtension(entry.path) !== (image.format === "jpg" ? "jpg" : image.format)) {
+			const converted = await convertImageBuffer(await streamToBuffer(entry.openReadStream()), image.format, image.options);
+			yield {
+				path: replaceExtension(entry.path, image.format === "jpg" ? "jpg" : image.format),
+				size: converted.length,
+				content: Readable.from(converted)
+			};
+		} else yield {
+			path: entry.path,
+			size: entry.size,
+			content: entry.openReadStream()
+		};
+	}
+	return withOutput(options.output, (destination) => targetAdapter.write(entries(), destination, { tempDir: options.tempDir }));
+}
+//#endregion
+//#region src/extractArchive.ts
+/**
+* Extracts every entry in an archive to real files under `destDir`,
+* preserving relative paths (`destDir` is created if missing). Throws
+* `ArchiveFormatError` for an undetectable/unknown format, or
+* `UnsupportedOperationError` for ACE. Returns the archive-relative entry
+* paths that were written, in archive iteration order.
+*/
+async function extractArchive(input, destDir, options = {}) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	await fs.promises.mkdir(destDir, { recursive: true });
+	const written = [];
+	for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) {
+		const target = resolveSafeEntryPath(destDir, entry.path);
+		await fs.promises.mkdir(path.dirname(target), { recursive: true });
+		await pipeline(entry.openReadStream(), fs.createWriteStream(target));
+		written.push(entry.path);
+	}
+	return written;
+}
+//#endregion
+//#region src/metadata/schema.ts
+/**
+* Authoritative field-mapping table between the canonical ComicMetadata
+* shape and each external XML schema (ComicInfo.xml v2.1, MetronInfo.xml
+* v1.1 — see `schemas/`). Conversion is intentionally lossy in both
+* directions; a field with no equivalent in the target schema is dropped
+* unless the source and target schema happen to be the same one (in which
+* case `comicInfoExtra`/`metronInfoExtra` round-trips it).
+*
+* | Canonical field         | ComicInfo.xml                                      | MetronInfo.xml                                |
+* |-------------------------|-----------------------------------------------------|------------------------------------------------|
+* | title                   | Title                                               | (no equivalent — dropped)                       |
+* | series                  | Series                                              | Series > Name                                   |
+* | seriesSort              | (no equivalent)                                     | Series > SortName                               |
+* | seriesId / seriesLang   | (no equivalent)                                     | Series `id`/`lang` attributes                   |
+* | seriesStartYear         | (no equivalent)                                     | Series > StartYear                              |
+* | seriesIssueCount        | (no equivalent)                                     | Series > IssueCount                             |
+* | seriesVolumeCount       | (no equivalent)                                     | Series > VolumeCount                            |
+* | seriesAlternativeNames  | (no equivalent)                                     | Series > AlternativeNames > AlternativeName[]   |
+* | seriesGroup             | SeriesGroup                                         | (no equivalent — dropped)                       |
+* | volume                  | Volume                                              | Series > Volume                                 |
+* | number                  | Number                                              | Number                                          |
+* | alternateNumber         | AlternateNumber                                     | AlternativeNumber                               |
+* | alternateSeries         | AlternateSeries                                     | (no equivalent — dropped)                       |
+* | alternateCount          | AlternateCount                                      | (no equivalent — dropped)                       |
+* | count                   | Count                                               | (no equivalent)                                 |
+* | pageCount               | PageCount                                           | PageCount                                       |
+* | summary                 | Summary                                             | Summary                                         |
+* | notes                   | Notes                                               | Notes                                           |
+* | review                  | Review                                              | (no equivalent — dropped)                       |
+* | scanInformation         | ScanInformation                                     | (no equivalent — dropped)                       |
+* | publisher / publisherId | Publisher                                           | Publisher > Name / `id` attribute               |
+* | imprint / imprintId     | Imprint                                             | Publisher > Imprint / `id` attribute            |
+* | collectionTitle         | (no equivalent)                                     | CollectionTitle                                 |
+* | mangaVolume             | (no equivalent)                                     | MangaVolume                                     |
+* | format                  | Format                                              | Series > Format                                 |
+* | language                | LanguageISO                                         | (no equivalent)                                 |
+* | ageRating               | AgeRating                                           | AgeRating                                       |
+* | communityRating(Count)  | CommunityRating                                     | CommunityRating > AverageRating / RatingCount   |
+* | coverDate               | Year / Month / Day                                  | CoverDate (YYYY-MM-DD)                          |
+* | storeDate               | (no equivalent)                                     | StoreDate (YYYY-MM-DD)                          |
+* | lastModified            | (no equivalent)                                     | LastModified                                    |
+* | genres                  | Genre (comma-separated string)                      | Genres > Genre[] (`id` attribute preserved)     |
+* | tags                    | Tags (comma-separated string)                       | Tags > Tag[] (`id` attribute preserved)         |
+* | characters              | Characters (comma-separated string)                 | Characters > Character[] (`id` attribute)       |
+* | teams                   | Teams (comma-separated string)                      | Teams > Team[] (`id` attribute)                 |
+* | locations               | Locations (comma-separated string)                  | Locations > Location[] (`id` attribute)         |
+* | storyArcs               | StoryArc / StoryArcNumber (parallel comma lists)    | Arcs > Arc[] (Name + Number + `id`)             |
+* | mainCharacterOrTeam     | MainCharacterOrTeam                                 | (no equivalent — dropped)                       |
+* | stories                 | (no equivalent)                                     | Stories > Story[]                               |
+* | reprints                | (no equivalent)                                     | Reprints > Reprint[]                            |
+* | universes               | (no equivalent)                                     | Universes > Universe[]                          |
+* | identifiers             | (no equivalent)                                     | IDS > ID[]                                      |
+* | prices                  | (no equivalent)                                     | Prices > Price[]                                |
+* | credits                 | Writer/Penciller/Inker/Colorist/Letterer/CoverArtist/Editor/Translator (comma-separated per role) | Credits > Credit[] (Creator + Roles > Role[], `id` attributes) |
+* | web                     | Web (single URL)                                    | URLs > URL[] (`primary` attribute)              |
+* | gtin                    | GTIN                                                | GTIN > ISBN                                     |
+* | gtinUpc                 | (no equivalent)                                     | GTIN > UPC                                      |
+* | blackAndWhite           | BlackAndWhite (Yes/No)                              | (no equivalent — ComicInfo-only)                |
+* | manga                   | Manga                                               | (no equivalent — ComicInfo-only)                |
+* | pages                   | Pages > Page[] (Image/Type/DoublePage/... attrs)    | (no equivalent — ComicInfo-only)                |
+*/
+const COMIC_INFO_CREDIT_ROLES = [
+	"Writer",
+	"Penciller",
+	"Inker",
+	"Colorist",
+	"Letterer",
+	"CoverArtist",
+	"Editor",
+	"Translator"
+];
+/** ComicInfo.xml `YesNo` simple type. */
+const COMIC_INFO_YES_NO_VALUES = [
+	"Unknown",
+	"No",
+	"Yes"
+];
+/** ComicInfo.xml `Manga` simple type. */
+const COMIC_INFO_MANGA_VALUES = [
+	"Unknown",
+	"No",
+	"Yes",
+	"YesAndRightToLeft"
+];
+/** ComicInfo.xml `AgeRating` simple type. */
+const COMIC_INFO_AGE_RATING_VALUES = [
+	"Unknown",
+	"Adults Only 18+",
+	"Early Childhood",
+	"Everyone",
+	"Everyone 10+",
+	"G",
+	"Kids to Adults",
+	"M",
+	"MA15+",
+	"Mature 17+",
+	"PG",
+	"R18+",
+	"Rating Pending",
+	"Teen",
+	"X18+"
+];
+/** ComicInfo.xml `ComicPageType` simple type. */
+const COMIC_INFO_PAGE_TYPE_VALUES = [
+	"FrontCover",
+	"InnerCover",
+	"Roundup",
+	"Story",
+	"Advertisement",
+	"Editorial",
+	"Letters",
+	"Preview",
+	"BackCover",
+	"Other",
+	"Deleted"
+];
+/** MetronInfo.xml `formatType` simple type (Series > Format). */
+const METRON_FORMAT_VALUES = [
+	"Annual",
+	"Digital Chapter",
+	"Graphic Novel",
+	"Hardcover",
+	"Limited Series",
+	"Omnibus",
+	"One-Shot",
+	"Single Issue",
+	"Trade Paperback"
+];
+/** MetronInfo.xml `informationSource` simple type (IDS > ID `source` attribute). */
+const METRON_INFORMATION_SOURCE_VALUES = [
+	"AniList",
+	"Comic Vine",
+	"Grand Comics Database",
+	"Kitsu",
+	"MangaDex",
+	"MangaUpdates",
+	"Marvel",
+	"Metron",
+	"MyAnimeList",
+	"League of Comic Geeks"
+];
+/** MetronInfo.xml `roleValues` simple type (Credits > Credit > Roles > Role). */
+const METRON_ROLE_VALUES = [
+	"Writer",
+	"Script",
+	"Story",
+	"Plot",
+	"Interviewer",
+	"Artist",
+	"Penciller",
+	"Breakdowns",
+	"Illustrator",
+	"Layouts",
+	"Inker",
+	"Embellisher",
+	"Finishes",
+	"Ink Assists",
+	"Colorist",
+	"Color Separations",
+	"Color Assists",
+	"Color Flats",
+	"Digital Art Technician",
+	"Gray Tone",
+	"Letterer",
+	"Cover",
+	"Editor",
+	"Consulting Editor",
+	"Assistant Editor",
+	"Associate Editor",
+	"Group Editor",
+	"Senior Editor",
+	"Managing Editor",
+	"Collection Editor",
+	"Production",
+	"Designer",
+	"Logo Design",
+	"Translator",
+	"Supervising Editor",
+	"Executive Editor",
+	"Editor In Chief",
+	"President",
+	"Publisher",
+	"Chief Creative Officer",
+	"Executive Producer",
+	"Other"
+];
+/** MetronInfo.xml `ageRatingType` simple type. */
+const METRON_AGE_RATING_VALUES = [
+	"Unknown",
+	"Everyone",
+	"Teen",
+	"Teen Plus",
+	"Mature",
+	"Explicit",
+	"Adult"
+];
+function splitCommaList(value) {
+	if (!value) return;
+	const parts = value.split(",").map((part) => part.trim()).filter(Boolean);
+	return parts.length ? parts : void 0;
+}
+function joinCommaList(values) {
+	return values && values.length ? values.join(", ") : void 0;
+}
+/** Extracts the plain text value from a resource that may carry a MetronInfo `id` attribute. */
+function resourceName(item) {
+	return typeof item === "string" ? item : item.name;
+}
+/** Extracts the MetronInfo `id` attribute from a resource, if any. */
+function resourceId(item) {
+	return typeof item === "string" ? void 0 : item.id;
+}
+function joinResourceNames(values) {
+	return joinCommaList(values?.map(resourceName));
+}
+//#endregion
+//#region src/metadata/comicInfo.ts
+const PARSE_OPTIONS$1 = {
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	isArray: (name) => name === "Page"
+};
+const BUILD_OPTIONS$1 = {
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	format: true,
+	suppressEmptyNode: true,
+	suppressBooleanAttributes: false
+};
+const KNOWN_KEYS = /* @__PURE__ */ new Set([
+	"Title",
+	"Series",
+	"Number",
+	"Count",
+	"Volume",
+	"AlternateSeries",
+	"AlternateNumber",
+	"AlternateCount",
+	"Summary",
+	"Notes",
+	"Year",
+	"Month",
+	"Day",
+	"Publisher",
+	"Imprint",
+	"Genre",
+	"Tags",
+	"Web",
+	"PageCount",
+	"LanguageISO",
+	"Format",
+	"BlackAndWhite",
+	"Manga",
+	"Characters",
+	"Teams",
+	"Locations",
+	"ScanInformation",
+	"StoryArc",
+	"StoryArcNumber",
+	"SeriesGroup",
+	"AgeRating",
+	"Pages",
+	"CommunityRating",
+	"MainCharacterOrTeam",
+	"Review",
+	"GTIN",
+	...COMIC_INFO_CREDIT_ROLES
+]);
+function metadataToComicInfoXml(metadata) {
+	const root = {};
+	if (metadata.title !== void 0) root.Title = metadata.title;
+	if (metadata.series !== void 0) root.Series = metadata.series;
+	if (metadata.number !== void 0) root.Number = metadata.number;
+	if (metadata.count !== void 0) root.Count = metadata.count;
+	if (metadata.volume !== void 0) root.Volume = metadata.volume;
+	if (metadata.alternateSeries !== void 0) root.AlternateSeries = metadata.alternateSeries;
+	if (metadata.alternateNumber !== void 0) root.AlternateNumber = metadata.alternateNumber;
+	if (metadata.alternateCount !== void 0) root.AlternateCount = metadata.alternateCount;
+	if (metadata.summary !== void 0) root.Summary = metadata.summary;
+	if (metadata.notes !== void 0) root.Notes = metadata.notes;
+	if (metadata.coverDate?.year !== void 0) root.Year = metadata.coverDate.year;
+	if (metadata.coverDate?.month !== void 0) root.Month = metadata.coverDate.month;
+	if (metadata.coverDate?.day !== void 0) root.Day = metadata.coverDate.day;
+	for (const role of COMIC_INFO_CREDIT_ROLES) {
+		const joined = joinCommaList((metadata.credits ?? []).filter((credit) => credit.role === role).map((credit) => credit.name));
+		if (joined) root[role] = joined;
+	}
+	if (metadata.publisher !== void 0) root.Publisher = metadata.publisher;
+	if (metadata.imprint !== void 0) root.Imprint = metadata.imprint;
+	const genres = joinResourceNames(metadata.genres);
+	if (genres) root.Genre = genres;
+	const tags = joinResourceNames(metadata.tags);
+	if (tags) root.Tags = tags;
+	const web = metadata.web?.[0];
+	if (web !== void 0) root.Web = typeof web === "string" ? web : web.url;
+	if (metadata.pageCount !== void 0) root.PageCount = metadata.pageCount;
+	if (metadata.language !== void 0) root.LanguageISO = metadata.language;
+	if (metadata.format !== void 0) root.Format = metadata.format;
+	if (metadata.blackAndWhite !== void 0) root.BlackAndWhite = metadata.blackAndWhite ? "Yes" : "No";
+	if (metadata.manga !== void 0) root.Manga = metadata.manga;
+	const characters = joinResourceNames(metadata.characters);
+	if (characters) root.Characters = characters;
+	const teams = joinResourceNames(metadata.teams);
+	if (teams) root.Teams = teams;
+	const locations = joinResourceNames(metadata.locations);
+	if (locations) root.Locations = locations;
+	if (metadata.scanInformation !== void 0) root.ScanInformation = metadata.scanInformation;
+	const storyArcs = joinCommaList(metadata.storyArcs?.map((arc) => arc.name));
+	if (storyArcs) root.StoryArc = storyArcs;
+	if (metadata.storyArcs?.some((arc) => arc.number !== void 0)) root.StoryArcNumber = metadata.storyArcs.map((arc) => arc.number ?? "").join(", ");
+	if (metadata.seriesGroup !== void 0) root.SeriesGroup = metadata.seriesGroup;
+	if (metadata.ageRating !== void 0) root.AgeRating = metadata.ageRating;
+	if (metadata.pages?.length) root.Pages = { Page: metadata.pages.map((page) => {
+		const attrs = { "@_Image": page.index };
+		if (page.type !== void 0) attrs["@_Type"] = page.type;
+		if (page.doublePage !== void 0) attrs["@_DoublePage"] = page.doublePage;
+		if (page.imageSize !== void 0) attrs["@_ImageSize"] = page.imageSize;
+		if (page.imageWidth !== void 0) attrs["@_ImageWidth"] = page.imageWidth;
+		if (page.imageHeight !== void 0) attrs["@_ImageHeight"] = page.imageHeight;
+		if (page.key !== void 0) attrs["@_Key"] = page.key;
+		if (page.bookmark !== void 0) attrs["@_Bookmark"] = page.bookmark;
+		return attrs;
+	}) };
+	if (metadata.communityRating !== void 0) root.CommunityRating = metadata.communityRating;
+	if (metadata.mainCharacterOrTeam !== void 0) root.MainCharacterOrTeam = metadata.mainCharacterOrTeam;
+	if (metadata.review !== void 0) root.Review = metadata.review;
+	if (metadata.gtin !== void 0) root.GTIN = metadata.gtin;
+	if (metadata.comicInfoExtra) Object.assign(root, metadata.comicInfoExtra);
+	return `<?xml version="1.0" encoding="utf-8"?>\n${new XMLBuilder(BUILD_OPTIONS$1).build({ ComicInfo: root })}`;
+}
+function comicInfoXmlToMetadata(xml) {
+	const root = new XMLParser(PARSE_OPTIONS$1).parse(xml.toString("utf8")).ComicInfo ?? {};
+	const metadata = {};
+	if (root.Title !== void 0) metadata.title = String(root.Title);
+	if (root.Series !== void 0) metadata.series = String(root.Series);
+	if (root.Number !== void 0) metadata.number = String(root.Number);
+	if (root.Count !== void 0) metadata.count = Number(root.Count);
+	if (root.Volume !== void 0) metadata.volume = String(root.Volume);
+	if (root.AlternateSeries !== void 0) metadata.alternateSeries = String(root.AlternateSeries);
+	if (root.AlternateNumber !== void 0) metadata.alternateNumber = String(root.AlternateNumber);
+	if (root.AlternateCount !== void 0) metadata.alternateCount = Number(root.AlternateCount);
+	if (root.Summary !== void 0) metadata.summary = String(root.Summary);
+	if (root.Notes !== void 0) metadata.notes = String(root.Notes);
+	if (root.Year !== void 0 || root.Month !== void 0 || root.Day !== void 0) metadata.coverDate = {
+		year: root.Year !== void 0 ? Number(root.Year) : void 0,
+		month: root.Month !== void 0 ? Number(root.Month) : void 0,
+		day: root.Day !== void 0 ? Number(root.Day) : void 0
+	};
+	if (root.Publisher !== void 0) metadata.publisher = String(root.Publisher);
+	if (root.Imprint !== void 0) metadata.imprint = String(root.Imprint);
+	if (root.Genre !== void 0) metadata.genres = splitCommaList(String(root.Genre));
+	if (root.Tags !== void 0) metadata.tags = splitCommaList(String(root.Tags));
+	if (root.Web !== void 0) metadata.web = [String(root.Web)];
+	if (root.PageCount !== void 0) metadata.pageCount = Number(root.PageCount);
+	if (root.LanguageISO !== void 0) metadata.language = String(root.LanguageISO);
+	if (root.Format !== void 0) metadata.format = String(root.Format);
+	if (root.BlackAndWhite !== void 0) metadata.blackAndWhite = String(root.BlackAndWhite).toLowerCase() === "yes";
+	if (root.Manga !== void 0) metadata.manga = String(root.Manga);
+	if (root.Characters !== void 0) metadata.characters = splitCommaList(String(root.Characters));
+	if (root.Teams !== void 0) metadata.teams = splitCommaList(String(root.Teams));
+	if (root.Locations !== void 0) metadata.locations = splitCommaList(String(root.Locations));
+	if (root.ScanInformation !== void 0) metadata.scanInformation = String(root.ScanInformation);
+	if (root.StoryArc !== void 0) {
+		const names = splitCommaList(String(root.StoryArc)) ?? [];
+		const numbers = root.StoryArcNumber !== void 0 ? String(root.StoryArcNumber).split(",").map((part) => part.trim()) : [];
+		metadata.storyArcs = names.map((name, i) => ({
+			name,
+			number: numbers[i] ? Number(numbers[i]) : void 0
+		}));
+	}
+	if (root.SeriesGroup !== void 0) metadata.seriesGroup = String(root.SeriesGroup);
+	if (root.AgeRating !== void 0) metadata.ageRating = String(root.AgeRating);
+	if (root.CommunityRating !== void 0) metadata.communityRating = Number(root.CommunityRating);
+	if (root.MainCharacterOrTeam !== void 0) metadata.mainCharacterOrTeam = String(root.MainCharacterOrTeam);
+	if (root.Review !== void 0) metadata.review = String(root.Review);
+	if (root.GTIN !== void 0) metadata.gtin = String(root.GTIN);
+	const credits = [];
+	for (const role of COMIC_INFO_CREDIT_ROLES) {
+		const value = root[role];
+		if (value !== void 0) for (const name of splitCommaList(String(value)) ?? []) credits.push({
+			name,
+			role
+		});
+	}
+	if (credits.length) metadata.credits = credits;
+	const pagesNode = root.Pages;
+	if (pagesNode?.Page?.length) metadata.pages = pagesNode.Page.map((page) => ({
+		index: Number(page["@_Image"] ?? 0),
+		type: page["@_Type"] !== void 0 ? String(page["@_Type"]) : void 0,
+		doublePage: page["@_DoublePage"] !== void 0 ? String(page["@_DoublePage"]) === "true" : void 0,
+		imageSize: page["@_ImageSize"] !== void 0 ? Number(page["@_ImageSize"]) : void 0,
+		imageWidth: page["@_ImageWidth"] !== void 0 ? Number(page["@_ImageWidth"]) : void 0,
+		imageHeight: page["@_ImageHeight"] !== void 0 ? Number(page["@_ImageHeight"]) : void 0,
+		key: page["@_Key"] !== void 0 ? String(page["@_Key"]) : void 0,
+		bookmark: page["@_Bookmark"] !== void 0 ? String(page["@_Bookmark"]) : void 0
+	}));
+	const extra = {};
+	for (const [key, value] of Object.entries(root)) if (!KNOWN_KEYS.has(key)) extra[key] = value;
+	if (Object.keys(extra).length) metadata.comicInfoExtra = extra;
+	return metadata;
+}
+//#endregion
+//#region src/metadata/metronInfo.ts
+const REPEATING_ELEMENTS = /* @__PURE__ */ new Set([
+	"ID",
+	"Genre",
+	"Tag",
+	"Character",
+	"Team",
+	"Universe",
+	"Location",
+	"Reprint",
+	"Arc",
+	"Credit",
+	"Role",
+	"URL",
+	"Story",
+	"Price",
+	"AlternativeName"
+]);
+const PARSE_OPTIONS = {
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	isArray: (name) => REPEATING_ELEMENTS.has(name)
+};
+const BUILD_OPTIONS = {
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	format: true,
+	suppressEmptyNode: true,
+	suppressBooleanAttributes: false
+};
+const KNOWN_ROOT_KEYS = /* @__PURE__ */ new Set([
+	"IDS",
+	"Publisher",
+	"Series",
+	"MangaVolume",
+	"CollectionTitle",
+	"Number",
+	"AlternativeNumber",
+	"Stories",
+	"Summary",
+	"Prices",
+	"CoverDate",
+	"StoreDate",
+	"PageCount",
+	"Notes",
+	"Genres",
+	"Tags",
+	"Arcs",
+	"Characters",
+	"Teams",
+	"Universes",
+	"Locations",
+	"Reprints",
+	"GTIN",
+	"AgeRating",
+	"CommunityRating",
+	"URLs",
+	"Credits",
+	"LastModified"
+]);
+function formatDate(date) {
+	if (!date || date.year === void 0) return;
+	const month = String(date.month ?? 1).padStart(2, "0");
+	const day = String(date.day ?? 1).padStart(2, "0");
+	return `${date.year}-${month}-${day}`;
+}
+function parseDate(value) {
+	if (typeof value !== "string") return;
+	const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+	if (!match) return;
+	return {
+		year: Number(match[1]),
+		month: Number(match[2]),
+		day: Number(match[3])
+	};
+}
+/** Builds a MetronInfo `resourceType` node: plain text, or `{ #text, @_id }` when an id is present. */
+function buildResourceItem(item) {
+	const id = resourceId(item);
+	return id !== void 0 ? {
+		"#text": resourceName(item),
+		"@_id": id
+	} : resourceName(item);
+}
+/** Parses a MetronInfo `resourceType` node back into a plain string or `MetronResource`. */
+function parseResourceItem(item) {
+	if (item !== null && typeof item === "object") {
+		const obj = item;
+		const id = obj["@_id"];
+		const text = String(obj["#text"] ?? "");
+		return id !== void 0 ? {
+			name: text,
+			id: String(id)
+		} : text;
+	}
+	return String(item);
+}
+function buildUrlItem(item) {
+	if (typeof item === "string") return item;
+	return item.primary !== void 0 ? {
+		"#text": item.url,
+		"@_primary": item.primary
+	} : item.url;
+}
+function parseUrlItem(item) {
+	if (item !== null && typeof item === "object") {
+		const obj = item;
+		const primary = obj["@_primary"];
+		const text = String(obj["#text"] ?? "");
+		return primary !== void 0 ? {
+			url: text,
+			primary: String(primary) === "true"
+		} : text;
+	}
+	return String(item);
+}
+function buildIdentifierItem(id) {
+	return {
+		"#text": id.value,
+		"@_source": id.source,
+		...id.primary !== void 0 ? { "@_primary": id.primary } : {}
+	};
+}
+function parseIdentifierItem(item) {
+	const obj = item ?? {};
+	return {
+		source: String(obj["@_source"] ?? ""),
+		value: String(obj["#text"] ?? ""),
+		primary: obj["@_primary"] !== void 0 ? String(obj["@_primary"]) === "true" : void 0
+	};
+}
+function buildAlternativeNameItem(item) {
+	const attrs = {};
+	if (item.id !== void 0) attrs["@_id"] = item.id;
+	if (item.lang !== void 0) attrs["@_lang"] = item.lang;
+	return Object.keys(attrs).length ? {
+		"#text": item.name,
+		...attrs
+	} : item.name;
+}
+function parseAlternativeNameItem(item) {
+	if (item === null || typeof item !== "object") return { name: String(item) };
+	const obj = item;
+	return {
+		name: String(obj["#text"] ?? ""),
+		id: obj["@_id"] !== void 0 ? String(obj["@_id"]) : void 0,
+		lang: obj["@_lang"] !== void 0 ? String(obj["@_lang"]) : void 0
+	};
+}
+function buildUniverseItem(universe) {
+	return {
+		Name: universe.name,
+		...universe.designation !== void 0 ? { Designation: universe.designation } : {},
+		...universe.id !== void 0 ? { "@_id": universe.id } : {}
+	};
+}
+function parseUniverseItem(item) {
+	return {
+		name: String(item.Name ?? ""),
+		designation: item.Designation !== void 0 ? String(item.Designation) : void 0,
+		id: item["@_id"] !== void 0 ? String(item["@_id"]) : void 0
+	};
+}
+function buildArcItem(arc) {
+	return {
+		Name: arc.name,
+		...arc.number !== void 0 ? { Number: arc.number } : {},
+		...arc.id !== void 0 ? { "@_id": arc.id } : {}
+	};
+}
+function parseArcItem(item) {
+	return {
+		name: String(item.Name ?? ""),
+		number: item.Number !== void 0 ? Number(item.Number) : void 0,
+		id: item["@_id"] !== void 0 ? String(item["@_id"]) : void 0
+	};
+}
+function buildPriceItem(price) {
+	return {
+		"#text": price.amount,
+		"@_country": price.country
+	};
+}
+function parsePriceItem(item) {
+	const obj = item ?? {};
+	return {
+		amount: Number(obj["#text"]),
+		country: String(obj["@_country"] ?? "")
+	};
+}
+function metadataToMetronInfoXml(metadata) {
+	const root = {};
+	if (metadata.identifiers?.length) root.IDS = { ID: metadata.identifiers.map(buildIdentifierItem) };
+	if (metadata.publisher !== void 0 || metadata.imprint !== void 0 || metadata.publisherId !== void 0) root.Publisher = {
+		...metadata.publisher !== void 0 ? { Name: metadata.publisher } : {},
+		...metadata.imprint !== void 0 ? { Imprint: buildResourceItem(metadata.imprintId !== void 0 ? {
+			name: metadata.imprint,
+			id: metadata.imprintId
+		} : metadata.imprint) } : {},
+		...metadata.publisherId !== void 0 ? { "@_id": metadata.publisherId } : {}
+	};
+	if (metadata.series !== void 0 || metadata.seriesSort !== void 0 || metadata.volume !== void 0 || metadata.format !== void 0 || metadata.seriesStartYear !== void 0 || metadata.seriesIssueCount !== void 0 || metadata.seriesVolumeCount !== void 0 || metadata.seriesAlternativeNames?.length || metadata.seriesId !== void 0 || metadata.seriesLang !== void 0) root.Series = {
+		...metadata.series !== void 0 ? { Name: metadata.series } : {},
+		...metadata.seriesSort !== void 0 ? { SortName: metadata.seriesSort } : {},
+		...metadata.volume !== void 0 ? { Volume: metadata.volume } : {},
+		...metadata.format !== void 0 ? { Format: metadata.format } : {},
+		...metadata.seriesStartYear !== void 0 ? { StartYear: metadata.seriesStartYear } : {},
+		...metadata.seriesIssueCount !== void 0 ? { IssueCount: metadata.seriesIssueCount } : {},
+		...metadata.seriesVolumeCount !== void 0 ? { VolumeCount: metadata.seriesVolumeCount } : {},
+		...metadata.seriesAlternativeNames?.length ? { AlternativeNames: { AlternativeName: metadata.seriesAlternativeNames.map(buildAlternativeNameItem) } } : {},
+		...metadata.seriesId !== void 0 ? { "@_id": metadata.seriesId } : {},
+		...metadata.seriesLang !== void 0 ? { "@_lang": metadata.seriesLang } : {}
+	};
+	if (metadata.mangaVolume !== void 0) root.MangaVolume = metadata.mangaVolume;
+	if (metadata.collectionTitle !== void 0) root.CollectionTitle = metadata.collectionTitle;
+	if (metadata.number !== void 0) root.Number = metadata.number;
+	if (metadata.alternateNumber !== void 0) root.AlternativeNumber = metadata.alternateNumber;
+	if (metadata.stories?.length) root.Stories = { Story: metadata.stories.map(buildResourceItem) };
+	if (metadata.summary !== void 0) root.Summary = metadata.summary;
+	if (metadata.prices?.length) root.Prices = { Price: metadata.prices.map(buildPriceItem) };
+	const coverDate = formatDate(metadata.coverDate);
+	if (coverDate) root.CoverDate = coverDate;
+	const storeDate = formatDate(metadata.storeDate);
+	if (storeDate) root.StoreDate = storeDate;
+	if (metadata.pageCount !== void 0) root.PageCount = metadata.pageCount;
+	if (metadata.notes !== void 0) root.Notes = metadata.notes;
+	if (metadata.genres?.length) root.Genres = { Genre: metadata.genres.map(buildResourceItem) };
+	if (metadata.tags?.length) root.Tags = { Tag: metadata.tags.map(buildResourceItem) };
+	if (metadata.storyArcs?.length) root.Arcs = { Arc: metadata.storyArcs.map(buildArcItem) };
+	if (metadata.characters?.length) root.Characters = { Character: metadata.characters.map(buildResourceItem) };
+	if (metadata.teams?.length) root.Teams = { Team: metadata.teams.map(buildResourceItem) };
+	if (metadata.universes?.length) root.Universes = { Universe: metadata.universes.map(buildUniverseItem) };
+	if (metadata.locations?.length) root.Locations = { Location: metadata.locations.map(buildResourceItem) };
+	if (metadata.reprints?.length) root.Reprints = { Reprint: metadata.reprints.map(buildResourceItem) };
+	if (metadata.gtin !== void 0 || metadata.gtinUpc !== void 0) root.GTIN = {
+		...metadata.gtin !== void 0 ? { ISBN: metadata.gtin } : {},
+		...metadata.gtinUpc !== void 0 ? { UPC: metadata.gtinUpc } : {}
+	};
+	if (metadata.ageRating !== void 0) root.AgeRating = metadata.ageRating;
+	if (metadata.communityRating !== void 0) root.CommunityRating = {
+		AverageRating: metadata.communityRating,
+		...metadata.communityRatingCount !== void 0 ? { RatingCount: metadata.communityRatingCount } : {}
+	};
+	if (metadata.web?.length) root.URLs = { URL: metadata.web.map(buildUrlItem) };
+	if (metadata.credits?.length) root.Credits = { Credit: metadata.credits.map((credit) => ({
+		Creator: buildResourceItem(credit.creatorId !== void 0 ? {
+			name: credit.name,
+			id: credit.creatorId
+		} : credit.name),
+		Roles: { Role: [buildResourceItem(credit.roleId !== void 0 ? {
+			name: credit.role,
+			id: credit.roleId
+		} : credit.role)] }
+	})) };
+	if (metadata.lastModified !== void 0) root.LastModified = metadata.lastModified;
+	if (metadata.metronInfoExtra) Object.assign(root, metadata.metronInfoExtra);
+	return `<?xml version="1.0" encoding="utf-8"?>\n${new XMLBuilder(BUILD_OPTIONS).build({ MetronInfo: root })}`;
+}
+function metronInfoXmlToMetadata(xml) {
+	const root = new XMLParser(PARSE_OPTIONS).parse(xml.toString("utf8")).MetronInfo ?? {};
+	const metadata = {};
+	const ids = root.IDS;
+	if (ids?.ID?.length) metadata.identifiers = ids.ID.map(parseIdentifierItem);
+	const publisher = root.Publisher;
+	if (publisher?.Name !== void 0) metadata.publisher = String(publisher.Name);
+	if (publisher?.Imprint !== void 0) {
+		const imprint = parseResourceItem(publisher.Imprint);
+		metadata.imprint = resourceName(imprint);
+		metadata.imprintId = resourceId(imprint);
+	}
+	if (publisher?.["@_id"] !== void 0) metadata.publisherId = String(publisher["@_id"]);
+	const series = root.Series;
+	if (series?.Name !== void 0) metadata.series = String(series.Name);
+	if (series?.SortName !== void 0) metadata.seriesSort = String(series.SortName);
+	if (series?.Volume !== void 0) metadata.volume = String(series.Volume);
+	if (series?.Format !== void 0) metadata.format = String(series.Format);
+	if (series?.StartYear !== void 0) metadata.seriesStartYear = Number(series.StartYear);
+	if (series?.IssueCount !== void 0) metadata.seriesIssueCount = Number(series.IssueCount);
+	if (series?.VolumeCount !== void 0) metadata.seriesVolumeCount = Number(series.VolumeCount);
+	if (series?.AlternativeNames?.AlternativeName?.length) metadata.seriesAlternativeNames = series.AlternativeNames.AlternativeName.map(parseAlternativeNameItem);
+	if (series?.["@_id"] !== void 0) metadata.seriesId = String(series["@_id"]);
+	if (series?.["@_lang"] !== void 0) metadata.seriesLang = String(series["@_lang"]);
+	if (root.MangaVolume !== void 0) metadata.mangaVolume = String(root.MangaVolume);
+	if (root.CollectionTitle !== void 0) metadata.collectionTitle = String(root.CollectionTitle);
+	if (root.Number !== void 0) metadata.number = String(root.Number);
+	if (root.AlternativeNumber !== void 0) metadata.alternateNumber = String(root.AlternativeNumber);
+	const stories = root.Stories;
+	if (stories?.Story?.length) metadata.stories = stories.Story.map(parseResourceItem);
+	if (root.Summary !== void 0) metadata.summary = String(root.Summary);
+	const prices = root.Prices;
+	if (prices?.Price?.length) metadata.prices = prices.Price.map(parsePriceItem);
+	metadata.coverDate = parseDate(root.CoverDate);
+	metadata.storeDate = parseDate(root.StoreDate);
+	if (root.PageCount !== void 0) metadata.pageCount = Number(root.PageCount);
+	if (root.Notes !== void 0) metadata.notes = String(root.Notes);
+	const genres = root.Genres;
+	if (genres?.Genre?.length) metadata.genres = genres.Genre.map(parseResourceItem);
+	const tags = root.Tags;
+	if (tags?.Tag?.length) metadata.tags = tags.Tag.map(parseResourceItem);
+	const arcs = root.Arcs;
+	if (arcs?.Arc?.length) metadata.storyArcs = arcs.Arc.map(parseArcItem);
+	const characters = root.Characters;
+	if (characters?.Character?.length) metadata.characters = characters.Character.map(parseResourceItem);
+	const teams = root.Teams;
+	if (teams?.Team?.length) metadata.teams = teams.Team.map(parseResourceItem);
+	const universes = root.Universes;
+	if (universes?.Universe?.length) metadata.universes = universes.Universe.map(parseUniverseItem);
+	const locations = root.Locations;
+	if (locations?.Location?.length) metadata.locations = locations.Location.map(parseResourceItem);
+	const reprints = root.Reprints;
+	if (reprints?.Reprint?.length) metadata.reprints = reprints.Reprint.map(parseResourceItem);
+	const gtin = root.GTIN;
+	if (gtin?.ISBN !== void 0) metadata.gtin = String(gtin.ISBN);
+	if (gtin?.UPC !== void 0) metadata.gtinUpc = String(gtin.UPC);
+	if (root.AgeRating !== void 0) metadata.ageRating = String(root.AgeRating);
+	const communityRating = root.CommunityRating;
+	if (communityRating?.AverageRating !== void 0) metadata.communityRating = Number(communityRating.AverageRating);
+	if (communityRating?.RatingCount !== void 0) metadata.communityRatingCount = Number(communityRating.RatingCount);
+	const urls = root.URLs;
+	if (urls?.URL?.length) metadata.web = urls.URL.map(parseUrlItem);
+	const credits = root.Credits;
+	if (credits?.Credit?.length) {
+		const list = [];
+		for (const credit of credits.Credit) {
+			const creator = parseResourceItem(credit.Creator ?? "");
+			const name = resourceName(creator);
+			const creatorId = resourceId(creator);
+			const roleItems = credit.Roles?.Role?.length ? credit.Roles.Role : ["Unknown"];
+			for (const roleItem of roleItems) {
+				const role = parseResourceItem(roleItem);
+				list.push({
+					name,
+					role: resourceName(role),
+					creatorId,
+					roleId: resourceId(role)
+				});
+			}
+		}
+		metadata.credits = list;
+	}
+	if (root.LastModified !== void 0) metadata.lastModified = String(root.LastModified);
+	const extra = {};
+	for (const [key, value] of Object.entries(root)) if (!KNOWN_ROOT_KEYS.has(key)) extra[key] = value;
+	if (Object.keys(extra).length) metadata.metronInfoExtra = extra;
+	return metadata;
+}
+//#endregion
+//#region src/metadata/schemaVersions.ts
+/**
+* Update these when the XSDs in `schemas/` are replaced with a newer
+* release. Every place that needs to read a bundled schema file (tests,
+* dev tooling, runtime validation) derives its filename from here instead
+* of hardcoding a version number.
+*/
+const SCHEMA_VERSIONS = {
+	ComicInfo: "2.1",
+	MetronInfo: "1.1"
+};
+/**
+* Walks up from this module's location to find the package root (the
+* directory containing `schemas/`). This module runs both from `src/`
+* (tests, ts-node) and from the single-file bundle in `dist/` — those sit
+* at different depths relative to the package root, so the depth can't be
+* hardcoded.
+*/
+function findPackageRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	for (let i = 0; i < 5; i++) {
+		if (existsSync(join(dir, "schemas"))) return dir;
+		dir = join(dir, "..");
+	}
+	throw new Error("Could not locate the \"schemas\" directory relative to the package root.");
+}
+/** Absolute path to the bundled XSD for `schema`, e.g. ".../schemas/ComicInfo v2.1.xsd". */
+function schemaFilePath(schema) {
+	return join(findPackageRoot(), "schemas", `${schema} v${SCHEMA_VERSIONS[schema]}.xsd`);
+}
+//#endregion
+//#region src/metadata/validate.ts
+const schemaCache = /* @__PURE__ */ new Map();
+function loadSchema(schema) {
+	const cached = schemaCache.get(schema);
+	if (cached !== void 0) return cached;
+	const xsd = readFileSync(schemaFilePath(schema), "utf8").replace(/<xs:assert\b[^>]*\/>\n?/g, "");
+	schemaCache.set(schema, xsd);
+	return xsd;
+}
+/**
+* Validates an XML document against the bundled ComicInfo.xml or
+* MetronInfo.xml XSD. Returns `{ valid: true, issues: [] }` when the
+* document conforms, or `{ valid: false, issues }` with one entry per
+* schema violation (element/attribute name and line number, where
+* available) otherwise.
+*/
+async function validateMetadataXml(xml, schema) {
+	const result = await validateXML({
+		xml: xml.toString(),
+		schema: loadSchema(schema)
+	});
+	return {
+		valid: result.valid,
+		issues: result.errors.map((error) => ({
+			message: error.message,
+			line: error.loc?.lineNumber
+		}))
+	};
+}
+//#endregion
+//#region src/metadata/index.ts
+var metadata_exports = /* @__PURE__ */ __exportAll({
+	COMIC_INFO_AGE_RATING_VALUES: () => COMIC_INFO_AGE_RATING_VALUES,
+	COMIC_INFO_CREDIT_ROLES: () => COMIC_INFO_CREDIT_ROLES,
+	COMIC_INFO_MANGA_VALUES: () => COMIC_INFO_MANGA_VALUES,
+	COMIC_INFO_PAGE_TYPE_VALUES: () => COMIC_INFO_PAGE_TYPE_VALUES,
+	COMIC_INFO_YES_NO_VALUES: () => COMIC_INFO_YES_NO_VALUES,
+	METRON_AGE_RATING_VALUES: () => METRON_AGE_RATING_VALUES,
+	METRON_FORMAT_VALUES: () => METRON_FORMAT_VALUES,
+	METRON_INFORMATION_SOURCE_VALUES: () => METRON_INFORMATION_SOURCE_VALUES,
+	METRON_ROLE_VALUES: () => METRON_ROLE_VALUES,
+	addMetadataToArchive: () => addMetadataToArchive,
+	comicInfoXmlToMetadata: () => comicInfoXmlToMetadata,
+	hasComicMetadata: () => hasComicMetadata,
+	joinCommaList: () => joinCommaList,
+	joinResourceNames: () => joinResourceNames,
+	metadataToComicInfoXml: () => metadataToComicInfoXml,
+	metadataToMetronInfoXml: () => metadataToMetronInfoXml,
+	metadataToXml: () => metadataToXml,
+	metronInfoXmlToMetadata: () => metronInfoXmlToMetadata,
+	readArchiveMetadata: () => readArchiveMetadata,
+	resourceId: () => resourceId,
+	resourceName: () => resourceName,
+	splitCommaList: () => splitCommaList,
+	validateMetadataXml: () => validateMetadataXml,
+	xmlToMetadata: () => xmlToMetadata
+});
+const FILE_NAMES = {
+	ComicInfo: "ComicInfo.xml",
+	MetronInfo: "MetronInfo.xml"
+};
+function metadataToXml(metadata, schema) {
+	return schema === "ComicInfo" ? metadataToComicInfoXml(metadata) : metadataToMetronInfoXml(metadata);
+}
+function xmlToMetadata(xml, schema) {
+	return schema === "ComicInfo" ? comicInfoXmlToMetadata(xml) : metronInfoXmlToMetadata(xml);
+}
+async function hasComicMetadata(input) {
+	const type = await detectArchiveType(input);
+	if (type === "asar") {
+		const { header } = await parseAsarHeader((start, end) => readInputRange(input, start, end));
+		if (hasRootFile(header, "ComicInfo.xml")) return {
+			present: true,
+			schema: "ComicInfo",
+			path: "ComicInfo.xml"
+		};
+		if (hasRootFile(header, "MetronInfo.xml")) return {
+			present: true,
+			schema: "MetronInfo",
+			path: "MetronInfo.xml"
+		};
+		return { present: false };
+	}
+	const adapter = getAdapter(type);
+	for await (const entry of adapter.listEntries(input)) {
+		const base = entry.path.split("/").pop();
+		if (base === "ComicInfo.xml") return {
+			present: true,
+			schema: "ComicInfo",
+			path: entry.path
+		};
+		if (base === "MetronInfo.xml") return {
+			present: true,
+			schema: "MetronInfo",
+			path: entry.path
+		};
+	}
+	return { present: false };
+}
+async function readArchiveMetadata(input) {
+	const found = await hasComicMetadata(input);
+	if (!found.present || !found.schema || !found.path) return null;
+	const adapter = getAdapter(await detectArchiveType(input));
+	for await (const entry of adapter.listEntries(input)) if (entry.path === found.path) {
+		const buffer = await streamToBuffer(entry.openReadStream());
+		return {
+			schema: found.schema,
+			metadata: xmlToMetadata(buffer, found.schema)
+		};
+	}
+	return null;
+}
+async function addMetadataToArchive(input, metadata, schema, options = {}) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	const fileName = FILE_NAMES[schema];
+	const xmlBuffer = Buffer.from(metadataToXml(metadata, schema), "utf8");
+	async function* entries() {
+		let replaced = false;
+		for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) {
+			if (entry.path.split("/").pop() === fileName) {
+				if (!options.overwrite) throw new ArchiveFormatError(`Archive already contains ${fileName}; pass { overwrite: true } to replace it.`);
+				replaced = true;
+				yield {
+					path: entry.path,
+					size: xmlBuffer.length,
+					content: Readable.from(xmlBuffer)
+				};
+				continue;
+			}
+			yield {
+				path: entry.path,
+				size: entry.size,
+				content: entry.openReadStream()
+			};
+		}
+		if (!replaced) yield {
+			path: fileName,
+			size: xmlBuffer.length,
+			content: Readable.from(xmlBuffer)
+		};
+	}
+	return withOutput(options.output, (destination) => adapter.write(entries(), destination, { tempDir: options.tempDir }));
+}
+//#endregion
+//#region src/images/phash.ts
+const HASH_SIZE = 32;
+const BLOCK_SIZE = 8;
+function dct1d(vector) {
+	const n = vector.length;
+	const result = Array.from({ length: n }, () => 0);
+	for (let k = 0; k < n; k++) {
+		let sum = 0;
+		for (let i = 0; i < n; i++) sum += vector[i] * Math.cos(Math.PI / n * (i + .5) * k);
+		result[k] = sum;
+	}
+	return result;
+}
+function dct2d(matrix) {
+	const size = matrix.length;
+	const rowsTransformed = matrix.map(dct1d);
+	const result = Array.from({ length: size }, () => Array.from({ length: size }, () => 0));
+	for (let col = 0; col < size; col++) {
+		const transformed = dct1d(rowsTransformed.map((row) => row[col]));
+		for (let row = 0; row < size; row++) result[row][col] = transformed[row];
+	}
+	return result;
+}
+function median(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+/**
+* Standard 8x8 DCT perceptual hash: resize to 32x32 greyscale, run a 2D
+* DCT-II, threshold the top-left 8x8 block against the median of that block
+* (excluding the DC term at [0][0] from the median calculation, though it is
+* still included positionally as bit 0). Returned as a bigint since JS
+* `Number` cannot losslessly represent all 64-bit patterns.
+*/
+async function computeImagePHash(image) {
+	const pixels = await sharp(image).resize(HASH_SIZE, HASH_SIZE, { fit: "fill" }).greyscale().raw().toBuffer();
+	const matrix = [];
+	for (let y = 0; y < HASH_SIZE; y++) {
+		const row = [];
+		for (let x = 0; x < HASH_SIZE; x++) row.push(pixels[y * HASH_SIZE + x]);
+		matrix.push(row);
+	}
+	const dct = dct2d(matrix);
+	const block = [];
+	for (let y = 0; y < BLOCK_SIZE; y++) for (let x = 0; x < BLOCK_SIZE; x++) block.push(dct[y][x]);
+	const threshold = median(block.slice(1));
+	let hash = 0n;
+	for (const value of block) hash = hash << 1n | (value > threshold ? 1n : 0n);
+	return hash;
+}
+function phashToHex(hash) {
+	return hash.toString(16).padStart(16, "0");
+}
+function hammingDistance(a, b) {
+	let diff = a ^ b;
+	let count = 0;
+	while (diff > 0n) {
+		count += Number(diff & 1n);
+		diff >>= 1n;
+	}
+	return count;
+}
+async function computeArchiveImagePHash(input, entryPath) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	for await (const entry of adapter.listEntries(input)) if (entry.path === entryPath) return computeImagePHash(await streamToBuffer(entry.openReadStream()));
+	throw new MetadataNotFoundError(`No entry named "${entryPath}" was found in the archive.`);
+}
+//#endregion
+//#region src/hashing/asarContent.ts
+/**
+* Locates the byte range of an asar archive's content region (everything
+* after the header), so it can be hashed without the header/index — meaning
+* header-only changes (e.g. re-ordering the file index) never change the
+* content hash.
+*/
+async function locateAsarContentRegion(input, totalSize) {
+	const { contentOffset } = await parseAsarHeader((start, end) => readInputRange(input, start, end));
+	return {
+		start: contentOffset,
+		end: totalSize
+	};
+}
+//#endregion
+//#region src/hashing/sha256.ts
+async function hashStream(stream) {
+	const hash = createHash("sha256");
+	for await (const chunk of stream) hash.update(chunk);
+	return hash.digest("hex");
+}
+async function sha256ArchiveEntry(input, entryPath) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	for await (const entry of adapter.listEntries(input)) if (entry.path === entryPath) return hashStream(entry.openReadStream());
+	throw new MetadataNotFoundError(`No entry named "${entryPath}" was found in the archive.`);
+}
+/**
+* SHA256 of the whole archive file — except for asar, where only the
+* content region (bytes after the header) is hashed, so header/index
+* reordering never changes the content hash.
+*/
+async function sha256Archive(input) {
+	if (await detectArchiveType(input) === "asar") {
+		const { start, end } = await locateAsarContentRegion(input, await inputSize(input));
+		return hashStream(openInputReadStream(input, {
+			start,
+			end
+		}));
+	}
+	return hashStream(openInputReadStream(input));
+}
+//#endregion
+//#region src/internal/naturalSort.ts
+function naturalCompare(a, b) {
+	return a.localeCompare(b, void 0, {
+		numeric: true,
+		sensitivity: "base"
+	});
+}
+//#endregion
+//#region src/rename.ts
+/**
+* Renames image entries to the standard `P#####` pattern in natural sort
+* order of their current names, leaving non-image entries (like
+* ComicInfo.xml/MetronInfo.xml) untouched.
+*
+* This requires two passes over the archive: `listEntries` is called once to
+* collect image paths (metadata only — no content is read, so no
+* decompression work is wasted) to compute the sort-order rename map, then
+* called again to stream entries out under their new names. Streaming
+* adapters (zip in particular) can't be "rewound" mid-read, so the second
+* pass re-invokes `listEntries` from the start rather than reusing entry
+* objects collected in the first pass.
+*/
+async function renameArchiveImagesSequentially(input, options = {}) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	const pad = options.pad ?? 5;
+	const start = options.start ?? 1;
+	const imagePaths = [];
+	for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) if (isImagePath(entry.path)) imagePaths.push(entry.path);
+	imagePaths.sort(naturalCompare);
+	const renameMap = /* @__PURE__ */ new Map();
+	imagePaths.forEach((entryPath, index) => {
+		const ext = getExtension(entryPath);
+		renameMap.set(entryPath, `P${String(start + index).padStart(pad, "0")}.${ext}`);
+	});
+	async function* output() {
+		for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) yield {
+			path: renameMap.get(entry.path) ?? entry.path,
+			size: entry.size,
+			content: entry.openReadStream()
+		};
+	}
+	return withOutput(options.output, (destination) => adapter.write(output(), destination, { tempDir: options.tempDir }));
+}
+//#endregion
+//#region src/strip.ts
+async function stripNonEssentialFiles(input, options = {}) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	const keepExtensions = new Set([
+		...IMAGE_EXTENSIONS,
+		"xml",
+		...options.extraKeepExtensions ?? []
+	].map((ext) => ext.toLowerCase()));
+	async function* output() {
+		for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) {
+			if (!keepExtensions.has(getExtension(entry.path))) continue;
+			yield {
+				path: entry.path,
+				size: entry.size,
+				content: entry.openReadStream()
+			};
+		}
+	}
+	return withOutput(options.output, (destination) => adapter.write(output(), destination, { tempDir: options.tempDir }));
+}
+//#endregion
+//#region src/listFiles.ts
+async function listArchiveFiles(input) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	const paths = [];
+	for await (const entry of adapter.listEntries(input)) paths.push(entry.path);
+	return paths;
+}
+//#endregion
+//#region src/benchmark/timing.ts
+/** Runs `run` `iterations` times and returns the average duration in milliseconds. */
+async function averageDuration(iterations, run) {
+	if (iterations <= 0) return 0;
+	let total = 0;
+	for (let i = 0; i < iterations; i++) {
+		const start = performance.now();
+		await run();
+		total += performance.now() - start;
+	}
+	return total / iterations;
+}
+/** Times `run` once per item and returns the average duration in milliseconds. */
+async function averageDurationOverItems(items, run) {
+	if (items.length === 0) return 0;
+	let total = 0;
+	for (const item of items) {
+		const start = performance.now();
+		await run(item);
+		total += performance.now() - start;
+	}
+	return total / items.length;
+}
+//#endregion
+//#region src/benchmark/report.ts
+function formatBytes(bytes) {
+	if (bytes < 1024) return `${Math.round(bytes)} B`;
+	const units = [
+		"KB",
+		"MB",
+		"GB"
+	];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex += 1;
+	}
+	return `${value.toFixed(2)} ${units[unitIndex]}`;
+}
+function formatMs(ms) {
+	return `${ms.toFixed(2)} ms`;
+}
+function topThree(variants, key) {
+	return [...variants].sort((a, b) => key(a) - key(b)).slice(0, 3);
+}
+/** Ranks by image format rather than by variant: transfer size depends only on image format, not container choice. */
+function topThreeImageFormats(variants) {
+	const seenFormats = /* @__PURE__ */ new Set();
+	return [...variants].sort((a, b) => a.avgImageSizeBytes - b.avgImageSizeBytes).filter((variant) => {
+		if (seenFormats.has(variant.imageFormat)) return false;
+		seenFormats.add(variant.imageFormat);
+		return true;
+	}).slice(0, 3);
+}
+function renderRankedSection(title, description, ranked, format) {
+	return `### ${title}\n\n${description}\n\n${ranked.map((variant, index) => `${index + 1}. **${variant.fileName}** (${variant.archiveType}/${variant.imageFormat}) — ${format(variant)}`).join("\n")}\n`;
+}
+function renderImageFormatRankedSection(title, description, ranked) {
+	return `### ${title}\n\n${description}\n\n${ranked.map((variant, index) => `${index + 1}. **${variant.imageFormat}** — ${formatBytes(variant.avgImageSizeBytes)} avg. per page`).join("\n")}\n`;
+}
+function renderBenchmarkReportMarkdown(result) {
+	const { variants } = result;
+	const tableHeader = "| Archive | Image | File | Storage size | Avg. page size | Pages | Avg. creation time | Avg. random read time |\n| --- | --- | --- | --- | --- | --- | --- | --- |";
+	const tableRows = variants.map((variant) => `| ${variant.archiveType} | ${variant.imageFormat} | \`${variant.fileName}\` | ${formatBytes(variant.fileSizeBytes)} | ${formatBytes(variant.avgImageSizeBytes)} | ${variant.pageCount} | ${formatMs(variant.avgCreationMs)} | ${formatMs(variant.avgSeekMs)} |`).join("\n");
+	const readSpeed = renderRankedSection("Read speed", "Fastest average random single-file read time — best for serving individual pages on demand (e.g. a remote reader).", topThree(variants, (variant) => variant.avgSeekMs), (variant) => formatMs(variant.avgSeekMs));
+	const storageSize = renderRankedSection("Storage size", "Smallest resulting archive on disk — best when total storage footprint is the priority.", topThree(variants, (variant) => variant.fileSizeBytes), (variant) => formatBytes(variant.fileSizeBytes));
+	const transferSize = renderImageFormatRankedSection("Transfer size", "Smallest average individual page — best when the cost of sending a single page over the network is the priority (e.g. a client fetching one page at a time). Depends only on image format, not container choice.", topThreeImageFormats(variants));
+	const creationSpeed = renderRankedSection("Creation speed", "Fastest average archive creation time — best when generating or converting archives on the fly.", topThree(variants, (variant) => variant.avgCreationMs), (variant) => formatMs(variant.avgCreationMs));
+	return [
+		"# Archive Benchmark Report",
+		"",
+		`- Source: \`${result.sourcePath}\``,
+		`- Generated: ${result.generatedAt}`,
+		`- Variants: ${variants.length}`,
+		"",
+		"## Results",
+		"",
+		tableHeader,
+		tableRows,
+		"",
+		"## Summary",
+		"",
+		readSpeed,
+		storageSize,
+		transferSize,
+		creationSpeed
+	].join("\n");
+}
+//#endregion
+//#region src/benchmark/types.ts
+const WRITABLE_ARCHIVE_TYPES = [
+	"zip",
+	"tar",
+	"asar",
+	"7z"
+];
+const BENCHMARK_IMAGE_FORMATS = [
+	"webp",
+	"png",
+	"jpg"
+];
+/** Conventional comic archive extension for each writable container format. */
+const ARCHIVE_TYPE_EXTENSIONS = {
+	zip: "cbz",
+	tar: "cbt",
+	asar: "cbas",
+	"7z": "cb7"
+};
+//#endregion
+//#region src/benchmark/benchmarkArchive.ts
+function timestampForDirName(date) {
+	return date.toISOString().replace(/:/g, "-").replace(/\.\d+Z$/, "Z");
+}
+function pickRandomSamples(items, count) {
+	if (items.length === 0) return [];
+	const samples = [];
+	for (let i = 0; i < count; i++) samples.push(items[Math.floor(Math.random() * items.length)]);
+	return samples;
+}
+/**
+* The average byte size of one converted image, independent of which
+* container it ends up packaged in ("transfer size" — what a client
+* actually downloads to fetch a single page).
+*/
+async function averageConvertedImageSize(preConverted, imageFormat, tempDir) {
+	const extractDir = path.join(tempDir, `preconverted-${imageFormat}`);
+	const imagePaths = (await extractArchive(preConverted, extractDir, { tempDir })).filter((entryPath) => isImagePath(entryPath));
+	let totalBytes = 0;
+	for (const entryPath of imagePaths) {
+		const { size } = await fsp.stat(path.join(extractDir, entryPath));
+		totalBytes += size;
+	}
+	return totalBytes / imagePaths.length;
+}
+/**
+* Extracts a comic archive, validates it contains image files, then
+* generates one archive per (writable container format) x (page image
+* format) combination, benchmarks each variant's creation speed and random
+* single-file read speed, and writes a markdown report summarizing the
+* results.
+*
+* Images are re-encoded to each target format once per image format, before
+* any timing starts; `avgCreationMs` measures only packaging already-encoded
+* entries into the target container, not the image re-encoding cost.
+*
+* Throws `ArchiveFormatError` (undetectable format) or
+* `UnsupportedOperationError` (ACE) if `filePath` is not extractable,
+* `NoImagesFoundError` if the archive contains no image files, and
+* `RangeError` if `options.imageFormats` is empty or names an unsupported
+* format.
+*/
+async function benchmarkArchive(filePath, options = {}) {
+	try {
+		await fsp.access(filePath);
+	} catch {
+		throw new FilesystemAccessError(`No file exists at "${filePath}".`);
+	}
+	const creationIterations = Math.max(1, options.creationIterations ?? 3);
+	const seekSamples = Math.max(1, options.seekSamples ?? 10);
+	const imageFormats = options.imageFormats ?? BENCHMARK_IMAGE_FORMATS;
+	if (imageFormats.length === 0) throw new RangeError("options.imageFormats must include at least one image format.");
+	const unsupportedFormats = imageFormats.filter((format) => !BENCHMARK_IMAGE_FORMATS.includes(format));
+	if (unsupportedFormats.length > 0) throw new RangeError(`Unsupported image format(s): ${unsupportedFormats.join(", ")}. Supported formats: ${BENCHMARK_IMAGE_FORMATS.join(", ")}.`);
+	const tempDir = await resolveWritableTempDir(options.tempDir);
+	try {
+		const generatedAt = /* @__PURE__ */ new Date();
+		const reportsRoot = options.reportsDir ?? path.join(process.cwd(), "reports");
+		const reportDir = path.join(reportsRoot, timestampForDirName(generatedAt));
+		const sourceDir = path.join(reportDir, "source");
+		const archivesDir = path.join(reportDir, "archives");
+		await fsp.mkdir(archivesDir, { recursive: true });
+		if (!(await extractArchive(filePath, sourceDir, { tempDir })).some((entryPath) => isImagePath(entryPath))) throw new NoImagesFoundError(`Archive "${filePath}" does not contain any image files.`);
+		const stripped = await stripNonEssentialFiles(filePath, { tempDir });
+		const variants = [];
+		for (const imageFormat of imageFormats) {
+			const preConverted = await convertArchiveImages(stripped, imageFormat, {
+				...options.image,
+				tempDir
+			});
+			const avgImageSizeBytes = await averageConvertedImageSize(preConverted, imageFormat, tempDir);
+			for (const archiveType of WRITABLE_ARCHIVE_TYPES) {
+				const fileName = `${archiveType}-${imageFormat}.${ARCHIVE_TYPE_EXTENSIONS[archiveType]}`;
+				const outputPath = path.join(archivesDir, fileName);
+				const avgCreationMs = await averageDuration(creationIterations, async () => {
+					await convertArchive(preConverted, archiveType, {
+						tempDir,
+						output: outputPath
+					});
+				});
+				const imageEntries = (await listArchiveFiles(outputPath)).filter((entryPath) => isImagePath(entryPath));
+				const avgSeekMs = await averageDurationOverItems(pickRandomSamples(imageEntries, seekSamples), async (entryPath) => {
+					await sha256ArchiveEntry(outputPath, entryPath);
+				});
+				const { size } = await fsp.stat(outputPath);
+				variants.push({
+					archiveType,
+					imageFormat,
+					fileName,
+					filePath: outputPath,
+					fileSizeBytes: size,
+					pageCount: imageEntries.length,
+					avgImageSizeBytes,
+					avgCreationMs,
+					avgSeekMs
+				});
+			}
+		}
+		const result = {
+			sourcePath: filePath,
+			generatedAt: generatedAt.toISOString(),
+			reportDir,
+			reportPath: path.join(reportDir, "report.md"),
+			sourceDir,
+			archivesDir,
+			variants
+		};
+		await fsp.writeFile(result.reportPath, renderBenchmarkReportMarkdown(result), "utf8");
+		return result;
+	} finally {
+		await cleanupTempDir(tempDir);
+	}
+}
+//#endregion
+//#region src/index.ts
+const comicArchiveHandler = {
+	...detect_exports,
+	convertArchive,
+	extractArchive,
+	...metadata_exports,
+	convertImageBuffer,
+	convertArchiveImages,
+	computeImagePHash,
+	phashToHex,
+	computeArchiveImagePHash,
+	hammingDistance,
+	IMAGE_EXTENSIONS,
+	isImagePath,
+	sha256ArchiveEntry,
+	sha256Archive,
+	renameArchiveImagesSequentially,
+	stripNonEssentialFiles,
+	listArchiveFiles,
+	benchmarkArchive,
+	renderBenchmarkReportMarkdown,
+	WRITABLE_ARCHIVE_TYPES,
+	BENCHMARK_IMAGE_FORMATS,
+	ARCHIVE_TYPE_EXTENSIONS
+};
+//#endregion
+export { ARCHIVE_TYPE_EXTENSIONS, ArchiveFormatError, BENCHMARK_IMAGE_FORMATS, COMIC_INFO_AGE_RATING_VALUES, COMIC_INFO_CREDIT_ROLES, COMIC_INFO_MANGA_VALUES, COMIC_INFO_PAGE_TYPE_VALUES, COMIC_INFO_YES_NO_VALUES, FilesystemAccessError, IMAGE_EXTENSIONS, METRON_AGE_RATING_VALUES, METRON_FORMAT_VALUES, METRON_INFORMATION_SOURCE_VALUES, METRON_ROLE_VALUES, MetadataNotFoundError, NoImagesFoundError, SevenZipUnavailableError, UnsupportedOperationError, WRITABLE_ARCHIVE_TYPES, addMetadataToArchive, benchmarkArchive, comicInfoXmlToMetadata, computeArchiveImagePHash, computeImagePHash, convertArchive, convertArchiveImages, convertImageBuffer, comicArchiveHandler as default, detectArchiveType, extractArchive, getExtension, hammingDistance, hasComicMetadata, is7z, isAce, isAsar, isImagePath, isRar, isTar, isZip, joinCommaList, joinResourceNames, listArchiveFiles, metadataToComicInfoXml, metadataToMetronInfoXml, metadataToXml, metronInfoXmlToMetadata, phashToHex, readArchiveMetadata, renameArchiveImagesSequentially, renderBenchmarkReportMarkdown, resourceId, resourceName, sha256Archive, sha256ArchiveEntry, splitCommaList, stripNonEssentialFiles, validateMetadataXml, xmlToMetadata };
+
+//# sourceMappingURL=index.mjs.map