@clearmist-labs/comic-archive-handler 1.3.0 → 1.5.0

package/dist/index.mjs

@@ -14,10 +14,10 @@ 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 { pipeline } from "node:stream/promises";
 import { createHash } from "node:crypto";
 //#region src/errors.ts
 var UnsupportedOperationError = class extends Error {
@@ -90,6 +90,35 @@ function openInputReadStream(input, range) {
 	return Readable.from(slice);
 }
 //#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);
+}
+//#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/internal/asarHeader.ts
 /**
 * Parses an asar archive's header from a byte reader.
@@ -138,10 +167,54 @@ function collectFiles(node, prefix, out) {
 		});
 	}
 }
-/** 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);
+/**
+* Serializes a header object back to the on-disk byte layout `parseAsarHeader`
+* decodes: the exact inverse, byte for byte (outer 8-byte pickle wrapping a
+* uint32 `size`, then a header pickle of [4-byte ignored length][4-byte
+* string byte-length][UTF-8 JSON][zero-padding to a 4-byte boundary]).
+*/
+function serializeAsarHeader(header) {
+	const jsonBytes = Buffer.from(JSON.stringify(header), "utf8");
+	const stringLength = jsonBytes.length;
+	const padding = (4 - stringLength % 4) % 4;
+	const payload = Buffer.concat([
+		uint32LE(stringLength),
+		jsonBytes,
+		Buffer.alloc(padding)
+	]);
+	const headerPickle = Buffer.concat([uint32LE(payload.length), payload]);
+	const outerPrefix = Buffer.concat([uint32LE(4), uint32LE(headerPickle.length)]);
+	return Buffer.concat([outerPrefix, headerPickle]);
+}
+function uint32LE(value) {
+	const buf = Buffer.alloc(4);
+	buf.writeUInt32LE(value, 0);
+	return buf;
+}
+/**
+* Reads an asar archive's header, applies `mutate` to a shallow clone of it,
+* and re-serializes the whole archive with the patched header followed by
+* the original, byte-for-byte unchanged content region. No repackaging via
+* `@electron/asar`'s `createPackage` needed, since file offsets are already
+* relative to the content region's start and never need adjusting when the
+* header's byte length changes.
+*/
+async function writeAsarHeaderPatch(input, mutate, options = {}) {
+	const { header, contentOffset } = await parseAsarHeader((start, end) => readInputRange(input, start, end));
+	const clone = { ...header };
+	mutate(clone);
+	const newHeaderBytes = serializeAsarHeader(clone);
+	const contentStream = openInputReadStream(input, {
+		start: contentOffset,
+		end: await inputSize(input)
+	});
+	return withOutput(options.output, (destination) => new Promise((resolve, reject) => {
+		contentStream.on("error", reject);
+		destination.on("error", reject);
+		destination.on("finish", resolve);
+		destination.write(newHeaderBytes);
+		contentStream.pipe(destination);
+	}));
 }
 //#endregion
 //#region src/detect.ts
@@ -273,8 +346,8 @@ function readZip64ExtraField(extra, overflowed) {
 	throw new ArchiveFormatError("Not a valid zip64 archive: an oversized entry is missing its zip64 extra field.");
 }
 /**
-* Parses a zip's central directory — the entry index at the end of the
-* file — into per-entry metadata (name, sizes, compression method, and the
+* Parses a zip's central directory, the entry index at the end of the
+* file, into per-entry metadata (name, sizes, compression method, and the
 * offset of its local file header). Reading this index costs a couple of
 * small range reads regardless of archive size; it never reads or
 * decompresses entry data itself, which is why entries can then be read in
@@ -324,7 +397,7 @@ async function parseZipCentralDirectory(input) {
 }
 /**
 * Reads and decompresses one entry's data, using its central directory
-* metadata to locate the bytes directly — no scan through other entries.
+* metadata to locate the bytes directly, with no scan through other entries.
 * The local file header still has to be read first because its name/extra
 * field lengths (which can differ from the central directory's) are what
 * determine where the entry's actual data starts.
@@ -384,20 +457,13 @@ const zipAdapter = {
 	}
 };
 //#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);
-}
-//#endregion
 //#region src/archive/tar.ts
 /**
 * The tar-stream v3 package 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
+* 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.
@@ -535,7 +601,7 @@ function resolveSafeEntryPath(root, entryPath) {
 /**
 * 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 —
+* 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
@@ -578,6 +644,13 @@ const asarAdapter = {
 			}
 			const outputFile = path.join(tempDir, "output.asar");
 			await createPackage(stagingDir, outputFile);
+			const comicMetadata = options?.comicMetadata;
+			if (comicMetadata && Object.keys(comicMetadata).length > 0) {
+				await writeAsarHeaderPatch(outputFile, (header) => {
+					header.comicMetadata = comicMetadata;
+				}, { output: destination });
+				return;
+			}
 			await new Promise((resolve, reject) => {
 				const readStream = fs.createReadStream(outputFile);
 				readStream.on("error", reject);
@@ -612,8 +685,8 @@ async function ensureBinaryAvailable() {
 * 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
+* 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) {
@@ -741,28 +814,6 @@ function getAdapter(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",
@@ -829,66 +880,40 @@ async function convertArchiveImages(input, format, options = {}) {
 	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);
+//#region src/removeArchiveEntry.ts
+async function removeArchiveEntry(input, entryPath, options = {}) {
+	const adapter = getAdapter(await detectArchiveType(input));
+	let found = false;
+	for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) if (entry.path === entryPath) {
+		found = true;
+		break;
+	}
+	if (!found) throw new MetadataNotFoundError(`No entry named "${entryPath}" was found in the archive.`);
+	async function* output() {
+		for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) {
+			if (entry.path === entryPath) continue;
 			yield {
-				path: replaceExtension(entry.path, image.format === "jpg" ? "jpg" : image.format),
-				size: converted.length,
-				content: Readable.from(converted)
+				path: entry.path,
+				size: entry.size,
+				content: entry.openReadStream()
 			};
-		} 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;
+	return withOutput(options.output, (destination) => adapter.write(output(), destination, { tempDir: options.tempDir }));
 }
 //#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
+* 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)                       |
+* | title                   | Title                                               | (no equivalent; dropped)                       |
 * | series                  | Series                                              | Series > Name                                   |
 * | seriesSort              | (no equivalent)                                     | Series > SortName                               |
 * | seriesId / seriesLang   | (no equivalent)                                     | Series `id`/`lang` attributes                   |
@@ -896,18 +921,18 @@ async function extractArchive(input, destDir, options = {}) {
 * | seriesIssueCount        | (no equivalent)                                     | Series > IssueCount                             |
 * | seriesVolumeCount       | (no equivalent)                                     | Series > VolumeCount                            |
 * | seriesAlternativeNames  | (no equivalent)                                     | Series > AlternativeNames > AlternativeName[]   |
-* | seriesGroup             | SeriesGroup                                         | (no equivalent — dropped)                       |
+* | 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)                       |
+* | 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)                       |
+* | 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                                 |
@@ -925,7 +950,7 @@ async function extractArchive(input, destDir, options = {}) {
 * | 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)                       |
+* | mainCharacterOrTeam     | MainCharacterOrTeam                                 | (no equivalent; dropped)                       |
 * | stories                 | (no equivalent)                                     | Stories > Story[]                               |
 * | reprints                | (no equivalent)                                     | Reprints > Reprint[]                            |
 * | universes               | (no equivalent)                                     | Universes > Universe[]                          |
@@ -935,9 +960,9 @@ async function extractArchive(input, destDir, options = {}) {
 * | 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)                |
+* | 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",
@@ -1641,7 +1666,7 @@ const SCHEMA_VERSIONS = {
 /**
 * 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
+* (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.
 */
@@ -1709,6 +1734,7 @@ var metadata_exports = /* @__PURE__ */ __exportAll({
 	metadataToXml: () => metadataToXml,
 	metronInfoXmlToMetadata: () => metronInfoXmlToMetadata,
 	readArchiveMetadata: () => readArchiveMetadata,
+	removeComicMetadata: () => removeComicMetadata,
 	resourceId: () => resourceId,
 	resourceName: () => resourceName,
 	splitCommaList: () => splitCommaList,
@@ -1725,21 +1751,30 @@ function metadataToXml(metadata, schema) {
 function xmlToMetadata(xml, schema) {
 	return schema === "ComicInfo" ? comicInfoXmlToMetadata(xml) : metronInfoXmlToMetadata(xml);
 }
+/** The archive's header `comicMetadata` object, if it's an asar archive with one; `{}` otherwise. */
+async function readAsarComicMetadataHeader(input) {
+	const { header } = await parseAsarHeader((start, end) => readInputRange(input, start, end));
+	return header.comicMetadata ?? {};
+}
 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 {
+		const comicMetadata = await readAsarComicMetadataHeader(input);
+		const bothPresent = Boolean(comicMetadata.ComicInfo && comicMetadata.MetronInfo);
+		if (comicMetadata.ComicInfo) return {
 			present: true,
 			schema: "ComicInfo",
-			path: "ComicInfo.xml"
+			bothPresent
 		};
-		if (hasRootFile(header, "MetronInfo.xml")) return {
+		if (comicMetadata.MetronInfo) return {
 			present: true,
 			schema: "MetronInfo",
-			path: "MetronInfo.xml"
+			bothPresent
+		};
+		return {
+			present: false,
+			bothPresent: false
 		};
-		return { present: false };
 	}
 	const adapter = getAdapter(type);
 	for await (const entry of adapter.listEntries(input)) {
@@ -1757,10 +1792,35 @@ async function hasComicMetadata(input) {
 	}
 	return { present: false };
 }
-async function readArchiveMetadata(input) {
+/**
+* Reads embedded comic metadata. With no `schema`, returns whichever schema
+* `hasComicMetadata` finds first (asar prefers ComicInfo when both are
+* present). Pass `schema` to read that specific one regardless of which is
+* preferred. The only way to read a non-preferred schema back out of an
+* asar archive that has both, since its metadata isn't addressable by path.
+*/
+async function readArchiveMetadata(input, schema) {
+	const type = await detectArchiveType(input);
+	if (type === "asar") {
+		const comicMetadata = await readAsarComicMetadataHeader(input);
+		const resolvedSchema = schema ?? (comicMetadata.ComicInfo ? "ComicInfo" : comicMetadata.MetronInfo ? "MetronInfo" : void 0);
+		const metadata = resolvedSchema && comicMetadata[resolvedSchema];
+		return resolvedSchema && metadata ? {
+			schema: resolvedSchema,
+			metadata
+		} : null;
+	}
+	const adapter = getAdapter(type);
+	if (schema) {
+		const fileName = FILE_NAMES[schema];
+		for await (const entry of adapter.listEntries(input)) if (entry.path.split("/").pop() === fileName) return {
+			schema,
+			metadata: xmlToMetadata(await streamToBuffer(entry.openReadStream()), schema)
+		};
+		return null;
+	}
 	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 {
@@ -1771,7 +1831,14 @@ async function readArchiveMetadata(input) {
 	return null;
 }
 async function addMetadataToArchive(input, metadata, schema, options = {}) {
-	const adapter = getAdapter(await detectArchiveType(input));
+	const type = await detectArchiveType(input);
+	if (type === "asar") return writeAsarHeaderPatch(input, (header) => {
+		const record = header;
+		record.comicMetadata ??= {};
+		if (!options.overwrite && record.comicMetadata[schema]) throw new ArchiveFormatError(`Archive already contains ${schema} metadata; pass { overwrite: true } to replace it.`);
+		record.comicMetadata[schema] = metadata;
+	}, options);
+	const adapter = getAdapter(type);
 	const fileName = FILE_NAMES[schema];
 	const xmlBuffer = Buffer.from(metadataToXml(metadata, schema), "utf8");
 	async function* entries() {
@@ -1801,6 +1868,90 @@ async function addMetadataToArchive(input, metadata, schema, options = {}) {
 	}
 	return withOutput(options.output, (destination) => adapter.write(entries(), destination, { tempDir: options.tempDir }));
 }
+/**
+* Removes the embedded `{schema}` metadata, if present; an asar header key
+* removal; or the matching `{schema}.xml` entry for every other format.
+* Throws `ArchiveFormatError` if the archive has no such metadata; a caller
+* that wants a no-op instead should check `hasComicMetadata` first.
+*/
+async function removeComicMetadata(input, schema, options = {}) {
+	const type = await detectArchiveType(input);
+	if (type === "asar") return writeAsarHeaderPatch(input, (header) => {
+		const comicMetadata = header.comicMetadata;
+		if (!comicMetadata?.[schema]) throw new ArchiveFormatError(`Archive does not contain ${schema} metadata.`);
+		delete comicMetadata[schema];
+	}, options);
+	const adapter = getAdapter(type);
+	const fileName = FILE_NAMES[schema];
+	for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) if (entry.path.split("/").pop() === fileName) return removeArchiveEntry(input, entry.path, options);
+	throw new ArchiveFormatError(`Archive does not contain ${fileName}.`);
+}
+//#endregion
+//#region src/convertArchive.ts
+const METADATA_FILE_NAMES = /* @__PURE__ */ new Set(["ComicInfo.xml", "MetronInfo.xml"]);
+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;
+	const metadata = options.metadata;
+	async function* entries() {
+		for await (const entry of sourceAdapter.listEntries(input, { tempDir: options.tempDir })) {
+			if (metadata && METADATA_FILE_NAMES.has(entry.path.split("/").pop() ?? "")) continue;
+			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()
+			};
+		}
+		if (metadata && targetType !== "asar") for (const schema of Object.keys(metadata)) {
+			const value = metadata[schema];
+			if (!value) continue;
+			const xml = Buffer.from(metadataToXml(value, schema), "utf8");
+			yield {
+				path: `${schema}.xml`,
+				size: xml.length,
+				content: Readable.from(xml)
+			};
+		}
+	}
+	return withOutput(options.output, (destination) => targetAdapter.write(entries(), destination, {
+		tempDir: options.tempDir,
+		...metadata && targetType === "asar" ? { comicMetadata: metadata } : {}
+	}));
+}
+//#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/images/phash.ts
 const HASH_SIZE = 32;
@@ -1871,10 +2022,24 @@ async function computeArchiveImagePHash(input, entryPath) {
 	throw new MetadataNotFoundError(`No entry named "${entryPath}" was found in the archive.`);
 }
 //#endregion
+//#region src/images/dimensions.ts
+/** Reads an image's pixel dimensions from its header without decoding it; `null` when the buffer isn't an image `sharp` can read. */
+async function readImageDimensions(buffer) {
+	try {
+		const { width, height } = await sharp(buffer).metadata();
+		return width !== void 0 && height !== void 0 ? {
+			width,
+			height
+		} : null;
+	} catch {
+		return null;
+	}
+}
+//#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
+* 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.
 */
@@ -1898,7 +2063,7 @@ async function sha256ArchiveEntry(input, entryPath) {
 	throw new MetadataNotFoundError(`No entry named "${entryPath}" was found in the archive.`);
 }
 /**
-* SHA256 of the whole archive file — except for asar, where only the
+* 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.
 */
@@ -1999,7 +2164,7 @@ async function readArchiveEntry(input, entryPath) {
 * Reads every entry's bytes and SHA256 in a single pass over the archive.
 * Calling `readArchiveEntry`/`sha256ArchiveEntry` once per entry instead
 * means re-running `listEntries` and re-locating the target entry on every
-* call — cheap for zip (backed by real central-directory random access) and
+* call: cheap for zip (backed by real central-directory random access) and
 * tar/asar, but for the sequential/CLI-driven formats (rar, 7z, ace) each
 * call re-reads the archive from the start, so reading every entry that way
 * costs O(n^2). This also does half the I/O of calling both
@@ -2025,28 +2190,6 @@ async function* readArchiveEntries(input) {
 	}
 }
 //#endregion
-//#region src/removeArchiveEntry.ts
-async function removeArchiveEntry(input, entryPath, options = {}) {
-	const adapter = getAdapter(await detectArchiveType(input));
-	let found = false;
-	for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) if (entry.path === entryPath) {
-		found = true;
-		break;
-	}
-	if (!found) throw new MetadataNotFoundError(`No entry named "${entryPath}" was found in the archive.`);
-	async function* output() {
-		for await (const entry of adapter.listEntries(input, { tempDir: options.tempDir })) {
-			if (entry.path === entryPath) 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/benchmark/timing.ts
 /** Runs `run` `iterations` times and returns the average duration in milliseconds. */
 async function averageDuration(iterations, run) {
@@ -2103,19 +2246,19 @@ function topThreeImageFormats(variants) {
 	}).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`;
+	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`;
+	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));
+	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",
 		"",
@@ -2169,7 +2312,7 @@ function pickRandomSamples(items, count) {
 }
 /**
 * The average byte size of one converted image, independent of which
-* container it ends up packaged in ("transfer size" — what a client
+* container it ends up packaged in ("transfer size": what a client
 * actually downloads to fetch a single page).
 */
 async function averageConvertedImageSize(preConverted, imageFormat, tempDir) {
@@ -2300,6 +2443,6 @@ const comicArchiveHandler = {
 	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, readArchiveEntries, readArchiveEntry, readArchiveMetadata, removeArchiveEntry, renameArchiveImagesSequentially, renderBenchmarkReportMarkdown, resourceId, resourceName, sha256Archive, sha256ArchiveEntry, splitCommaList, stripNonEssentialFiles, validateMetadataXml, xmlToMetadata };
+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, readArchiveEntries, readArchiveEntry, readArchiveMetadata, readImageDimensions, removeArchiveEntry, removeComicMetadata, renameArchiveImagesSequentially, renderBenchmarkReportMarkdown, resourceId, resourceName, sha256Archive, sha256ArchiveEntry, splitCommaList, stripNonEssentialFiles, validateMetadataXml, xmlToMetadata };
 
 //# sourceMappingURL=index.mjs.map