single-file-cli 2.9.1 → 2.10.0

package/lib/single-file-script.js

@@ -29,6 +29,8 @@ import { Deno } from "./deno-polyfill.js";
 const FETCH_FUNCTION_NAME = "__singleFileFetch";
 const RESOLVE_FETCH_FUNCTION_NAME = "__singleFileResolveFetch";
 const REJECT_FETCH_FUNCTION_NAME = "__singleFileRejectFetch";
+const SCRIPT_READY_PROPERTY_NAME = "__singleFileScriptReady";
+const SCRIPT_ERROR_PROPERTY_NAME = "__singleFileScriptError";
 
 const { readTextFile } = Deno;
 
@@ -36,6 +38,8 @@ export {
 	FETCH_FUNCTION_NAME,
 	RESOLVE_FETCH_FUNCTION_NAME,
 	REJECT_FETCH_FUNCTION_NAME,
+	SCRIPT_READY_PROPERTY_NAME,
+	SCRIPT_ERROR_PROPERTY_NAME,
 	getScriptSource,
 	getHookScriptSource,
 	getZipScriptSource,
@@ -89,19 +93,21 @@ function initSingleFile(constants) {
 	});
 }
 
-async function getScriptSource(options) {
+async function getScriptSource(options, globalAssignment = "") {
 	let source = "";
 	source += script;
-	source += await readScriptFiles(options && options.browserScripts ? options.browserScripts : []);
+	source += "\n" + globalAssignment;
+	source += "\n" + await readScriptFiles(options && options.browserScripts ? options.browserScripts : []);
 	if (options.browserStylesheets && options.browserStylesheets.length) {
-		source += "addEventListener(\"load\",()=>{const styleElement=document.createElement(\"style\");styleElement.textContent=" + JSON.stringify(await readScriptFiles(options.browserStylesheets)) + ";document.body.appendChild(styleElement);});";
+		source += "\naddEventListener(\"load\",()=>{const styleElement=document.createElement(\"style\");styleElement.textContent=" + JSON.stringify(await readScriptFiles(options.browserStylesheets)) + ";document.body.appendChild(styleElement);});";
 	}
-	source += "(" + initSingleFile.toString() + ")(" + JSON.stringify({
+	source += "\n(" + initSingleFile.toString() + ")(" + JSON.stringify({
 		FETCH_FUNCTION_NAME,
 		RESOLVE_FETCH_FUNCTION_NAME,
 		REJECT_FETCH_FUNCTION_NAME
 	}) + ");";
-	return source;
+	return "try{" + source + "\nglobalThis." + SCRIPT_READY_PROPERTY_NAME + "=true;}" +
+		"catch(error){globalThis." + SCRIPT_ERROR_PROPERTY_NAME + "=String(error);throw error;}";
 }
 
 function getHookScriptSource() {
@@ -156,5 +162,5 @@ function getPageDataScriptSource(options, [SET_SCREENSHOT_FUNCTION_NAME, SET_PDF
 
 
 async function readScriptFiles(paths) {
-	return (await Promise.all(paths.map(path => readTextFile(path)))).join("");
+	return (await Promise.all(paths.map(path => readTextFile(path)))).join("\n");
 }

package/lib/version.js

@@ -1 +1 @@
-export const version = "2.9.1";
+export const version = "2.10.0";

package/options.js

@@ -104,7 +104,7 @@ const OPTIONS_INFO = [{
 	"block-scripts": { description: "Block scripts", type: "boolean", defaultValue: true },
 	"block-stylesheets": { description: "Block stylesheets", type: "boolean", defaultValue: false },
 	"block-videos": { description: "Block videos", type: "boolean", defaultValue: true },
-	"block-mixed-content": { description: "Block mixed contents", type: "boolean" },
+	"block-mixed-content": { description: "Block active content (i.e. stylesheets, scripts, fonts) served from HTTP in HTTPS pages, like browsers do; images, videos and audios are unaffected", type: "boolean" },
 	"blocked-url-pattern": { key: "blockedURLPatterns", description: "Regular expression matching URLs to block (e.g. 'annoying-banners\\.com')", type: "string[]" }
 }, {
 	"load-deferred-images": { description: "Load deferred (a.k.a. lazy-loaded) images", type: "boolean", defaultValue: true },
@@ -113,7 +113,7 @@ const OPTIONS_INFO = [{
 	"load-deferred-images-keep-zoom-level": { description: "Load deferred images by keeping zoomed out the page", type: "boolean" },
 	"load-deferred-images-before-frames": { description: "Load deferred frames before before saving fame contents", type: "boolean" },
 	"max-resource-size-enabled": { description: "Enable removal of embedded resources exceeding a given size", type: "boolean" },
-	"max-resource-size": { description: "Maximum size of embedded resources in MB (i.e. images, stylesheets, scripts and iframes)", type: "number", defaultValue: 10 }
+	"max-resource-size": { description: "Maximum size of embedded resources in MB. It applies to every fetched resource, i.e. images, fonts, stylesheets, scripts, frames, videos and audios; a resource above the limit is left out of the saved page", type: "number", defaultValue: 10 }
 }, {
 	"compress-css": { key: "compressCSS", description: "Compress CSS stylesheets", type: "boolean" },
 	"compress-html": { key: "compressHTML", description: "Compress HTML content", type: "boolean", defaultValue: true },
@@ -141,6 +141,7 @@ const OPTIONS_INFO = [{
 	"extract-data-from-page": { description: "Extract compressed data from the page instead of fetching the page in order to create universal self-extracting HTML files", type: "boolean", defaultValue: true },
 	"prevent-appended-data": { description: "Prevent appending data after the compressed data when creating self-extracting HTML files", type: "boolean" },
 	"declare-appended-data": { description: "Declare the data appended after the compressed data as the comment of the ZIP archive, for readers rejecting undeclared trailing bytes (e.g. java.util.zip); ZIP tools then print that data when listing the archive. Has no effect when the extra data is relocated ahead of the compressed data, because nothing is appended then", type: "boolean" },
+	"max-appended-data-length": { description: "Maximum number of bytes appended after the compressed data when creating self-extracting HTML files, 16361 by default. Readers only tolerate trailing bytes as far back as their end-of-archive scan reaches (16383 bytes for libarchive, 32768 for perl Archive::Zip, 65557 for Python zipfile); the default fits the narrowest. Data over the limit is relocated ahead of the compressed data instead", type: "number" },
 	"embed-screenshot": { description: "Embed a screenshot of the page as a PNG file in the compressed file (self-extracting HTML or ZIP file). When enabled, the resulting file can be read as a ZIP file or a PNG image.", type: "boolean" },
 	"embed-screenshot-options": { description: "Options passed to the CDP method `Page.captureScreenshot()` given as a JSON string (e.g. { \"captureBeyondViewport\": false })", type: "string" },
 	"embedded-image": { description: "Path to a PNG image to embed in the compressed file. Unlike --embed-screenshot it is also compatible with --crawl-save-archive, where it becomes the image of the whole archive.", type: "string" },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "single-file-cli",
-	"version": "2.9.1",
+	"version": "2.10.0",
 	"description": "SingleFile CLI",
 	"author": "Gildas Lormeau",
 	"license": "AGPL-3.0-or-later",

package/single-file-cli-api.js

@@ -27,11 +27,13 @@ import { Buffer } from "node:buffer";
 import * as cdpBackend from "./lib/cdp-client.js";
 import * as bidiBackend from "./lib/bidi-client.js";
 import { getZipScriptSource } from "./lib/single-file-script.js";
-import { createPagesArchive } from "./lib/single-file-archive.js";
+import { createPagesArchive, PROCESS_OPTION_NAMES } from "./lib/single-file-archive.js";
 import { Deno, path } from "./lib/deno-polyfill.js";
 
 const VALID_URL_TEST = /^(https?|file):\/\//;
 
+const ARCHIVE_EXCLUDED_OPTION_NAMES = ["createRootDirectory", "disableCompression", "insertTextBody", "password", "url"];
+
 const DEFAULT_OPTIONS = {
 	removeHiddenElements: true,
 	removeUnusedStyles: true,
@@ -64,7 +66,7 @@ const STATE_PROCESSED = "processed";
 const { readTextFile, writeTextFile, readFile, writeFile, stdout, mkdir, makeTempDir, remove, stat, errors } = Deno;
 let backend = cdpBackend, tasks = [], maxParallelWorkers, sessionFilename, archiveTempDirectory, errorCount = 0;
 
-export { initialize, closeBrowser };
+export { initialize, closeBrowser, getArchiveOptions, ARCHIVE_EXCLUDED_OPTION_NAMES };
 
 async function closeBrowser() {
 	await backend.closeBrowser();
@@ -196,6 +198,23 @@ async function finish(options) {
 	return errorCount;
 }
 
+function getArchiveOptions(options) {
+	const archiveOptions = {
+		zipScript: getZipScriptSource(),
+		dedupPages: options.crawlSaveArchiveDedup,
+		markUnarchivedLinks: options.crawlSaveArchiveMarkUnarchivedLinks,
+		tocPage: options.crawlSaveArchiveToc,
+		pageList: options.crawlSaveArchivePageList,
+		pageTransitions: options.crawlSaveArchivePageTransitions,
+		insertSingleFileComment: options.insertSingleFileComment,
+		removeSavedDate: options.removeSavedDate
+	};
+	PROCESS_OPTION_NAMES
+		.filter(name => !ARCHIVE_EXCLUDED_OPTION_NAMES.includes(name) && !(name in archiveOptions))
+		.forEach(name => archiveOptions[name] = options[name]);
+	return archiveOptions;
+}
+
 async function savePagesArchive(options) {
 	const archiveTasks = tasks.filter(task => task.archiveFilename);
 	if (archiveTasks.length) {
@@ -205,26 +224,7 @@ async function savePagesArchive(options) {
 			title: task.title,
 			getData: () => readFile(task.archiveFilename)
 		}));
-		const content = await createPagesArchive(pages, {
-			zipScript: getZipScriptSource(),
-			dedupPages: options.crawlSaveArchiveDedup,
-			markUnarchivedLinks: options.crawlSaveArchiveMarkUnarchivedLinks,
-			tocPage: options.crawlSaveArchiveToc,
-			pageList: options.crawlSaveArchivePageList,
-			pageTransitions: options.crawlSaveArchivePageTransitions,
-			selfExtractingArchive: options.selfExtractingArchive,
-			extractDataFromPage: options.extractDataFromPage,
-			preventAppendedData: options.preventAppendedData,
-			declareAppendedData: options.declareAppendedData,
-			embeddedPdf: options.embeddedPdf,
-			embeddedImage: options.embeddedImage,
-			includeBOM: options.includeBOM,
-			insertMetaCSP: options.insertMetaCSP,
-			insertCanonicalLink: options.insertCanonicalLink,
-			insertMetaNoIndex: options.insertMetaNoIndex,
-			insertSingleFileComment: options.insertSingleFileComment,
-			removeSavedDate: options.removeSavedDate
-		});
+		const content = await createPagesArchive(pages, getArchiveOptions(options));
 		if (options.dumpContent && !options.output) {
 			await stdout.write(content);
 		} else {

package/test/e2e/browser-script.test.js

@@ -0,0 +1,112 @@
+// The injected script is one concatenation: the SingleFile bundle, then the scripts named by
+// --browser-script, then the call that hands SingleFile its options and its fetch fallback. A
+// throw anywhere in it stops the rest, and nothing reported it — the browser does not surface an
+// exception raised by a preload script, and the only guard was "is `singlefile` defined", which is
+// already true by then. So a script that threw produced a save that looked ordinary and was
+// missing the fetch fallback the CLI installs for the resources the page itself cannot get.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, readFile, writeFile, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { cliDirectory } from "../target.js";
+
+const execFileAsync = promisify(execFile);
+const TEST_TIMEOUT = 120000;
+
+test("a browser script runs in the page it saves", { timeout: TEST_TIMEOUT }, async () => {
+	const MARKER = "browser-script-marker";
+	await withPage(async ({ url, directory }) => {
+		const scriptPath = join(directory, "marker.js");
+		await writeFile(scriptPath, "addEventListener(\"DOMContentLoaded\",()=>{" +
+			"const marker=document.createElement(\"p\");marker.id=\"" + MARKER + "\";document.body.appendChild(marker);});");
+		const outputPath = join(directory, "out.html");
+		await execFileAsync(process.execPath, [
+			"single-file-node.js", url, outputPath,
+			"--browser-script", scriptPath
+		], { cwd: cliDirectory });
+		assert.match(await readFile(outputPath, "utf8"), new RegExp(MARKER));
+	});
+});
+
+test("a browser script that throws fails the save instead of degrading it", { timeout: TEST_TIMEOUT }, async () => {
+	const SCRIPT_ERROR_MESSAGE = "browser script boom";
+	await withPage(async ({ url, directory }) => {
+		const scriptPath = join(directory, "throwing.js");
+		await writeFile(scriptPath, "throw new Error(\"" + SCRIPT_ERROR_MESSAGE + "\");");
+		const outputPath = join(directory, "out.html");
+		let exitCode = 0, stderr = "";
+		try {
+			await execFileAsync(process.execPath, [
+				"single-file-node.js", url, outputPath,
+				"--browser-script", scriptPath
+			], { cwd: cliDirectory });
+		} catch (error) {
+			({ code: exitCode, stderr } = error);
+		}
+		assert.notEqual(exitCode, 0, "a save whose injected script threw was reported as a success");
+		// the message the script threw is what says which script to look at: without it the
+		// failure names the execution context and leaves the cause to be guessed
+		assert.match(stderr, new RegExp(SCRIPT_ERROR_MESSAGE), "the failure does not name the error the script threw");
+		assert.ok(!existsSync(outputPath), "a page was written for a save that failed");
+	});
+});
+
+// The same concatenation swallowed code across file boundaries. The scripts were joined with "",
+// and the initSingleFile call appended straight onto the last one, so a file whose final line was a
+// // comment commented out whatever came next. It only bites when that file has no trailing newline,
+// which is why it went unnoticed: an editor that adds one hides it completely. The last-file case
+// failed loudly (initSingleFile never ran, "no valid SingleFile execution context"), but a file
+// eating the NEXT script was silent — exit 0, a valid save, and one script quietly skipped.
+test("a browser script ending in a comment does not swallow the next one", { timeout: TEST_TIMEOUT }, async () => {
+	const MARKER = "second-script-marker";
+	await withPage(async ({ url, directory }) => {
+		const firstPath = join(directory, "first.js");
+		const secondPath = join(directory, "second.js");
+		// deliberately no trailing newline: that is the whole trigger
+		await writeFile(firstPath, "globalThis.__first = 1; // a trailing comment");
+		await writeFile(secondPath, "addEventListener(\"DOMContentLoaded\",()=>{" +
+			"const marker=document.createElement(\"p\");marker.id=\"" + MARKER + "\";document.body.appendChild(marker);});\n");
+		const outputPath = join(directory, "out.html");
+		await execFileAsync(process.execPath, [
+			"single-file-node.js", url, outputPath,
+			"--browser-script", firstPath,
+			"--browser-script", secondPath
+		], { cwd: cliDirectory });
+		assert.match(await readFile(outputPath, "utf8"), new RegExp(MARKER),
+			"the first script's trailing comment swallowed the second one");
+	});
+});
+
+test("a lone browser script ending in a comment still saves the page", { timeout: TEST_TIMEOUT }, async () => {
+	await withPage(async ({ url, directory }) => {
+		const scriptPath = join(directory, "only.js");
+		await writeFile(scriptPath, "globalThis.__only = 1; // a trailing comment");
+		const outputPath = join(directory, "out.html");
+		await execFileAsync(process.execPath, [
+			"single-file-node.js", url, outputPath,
+			"--browser-script", scriptPath
+		], { cwd: cliDirectory });
+		assert.match(await readFile(outputPath, "utf8"), /<h1>page<\/h1>/,
+			"the trailing comment reached the initSingleFile call");
+	});
+});
+
+async function withPage(run) {
+	const server = createServer((request, response) =>
+		response.writeHead(200, { "content-type": "text/html" }).end("<html><body><h1>page</h1></body></html>"));
+	await new Promise(resolve => server.listen(0, "localhost", resolve));
+	const directory = await mkdtemp(join(tmpdir(), "single-file-test-"));
+	try {
+		await run({ url: "http://localhost:" + server.address().port + "/", directory });
+	} finally {
+		await rm(directory, { recursive: true, force: true });
+		server.close();
+	}
+}

package/test/e2e/canvas-round-trip.test.js

@@ -84,7 +84,11 @@ async function capture(pathname, generations) {
 }
 
 function getCanvasImage(html) {
-	const match = html.match(/background-image:\s*url\(["']?data:image\/png;base64,([^"')]+)["']?\)/);
+	// either property name is correct: core pins every background longhand on the canvas, and once
+	// background-attachment joined them CSSOM had a complete set and serialised them as the
+	// `background` shorthand. Only cssText changed — core reads the value back through
+	// getPropertyValue("background-image"), which is why the round trip above still holds
+	const match = html.match(/background(?:-image)?:\s*url\(["']?data:image\/png;base64,([^"')]+)["']?\)/);
 	return match && match[1];
 }
 

package/test/e2e/font-face-source-order.test.js

@@ -0,0 +1,118 @@
+/* global URL */
+
+// CSS orders @font-face sources two ways at once, and a saved page has to honour both.
+// Within one rule the browser uses the FIRST source that loads. Across duplicate rules sharing the
+// same descriptors the LAST rule wins outright: measured in Chrome, only the later rule's font is
+// fetched and document.fonts reports the earlier face as "unloaded", so it is never a fallback.
+// SingleFile merged every rule sharing a font key into one array built with unshift, which reversed
+// both axes at once. The within-rule axis then read correctly and the across-rule axis backwards,
+// so the save embedded the font from the rule the browser had overridden — the right font was
+// absent from the file entirely. The two cases below pin the axes against each other, because a fix
+// that satisfies only one of them is the bug in the other direction.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import process from "node:process";
+import { Buffer } from "node:buffer";
+import { cliDirectory } from "../target.js";
+
+const execFileAsync = promisify(execFile);
+const TEST_TIMEOUT = 120000;
+const FONTS_DIRECTORY = join(dirname(fileURLToPath(import.meta.url)), "..", "fidelity", "pages", "fonts");
+// three distinct fixtures, told apart in the save by their byte length
+const FONT_NAMES = ["band.ttf", "bar.ttf", "block.ttf"];
+// the two Dup rules differ in size-adjust, which getFontKey does not cover, so they share a key
+// while rendering differently. That is what makes "keep the last rule" the only correct reduction:
+// keeping the first would pair the later rule's font with the earlier rule's metrics
+const PAGE = "<html><head><style>" +
+	"@font-face{font-family:\"Dup\";src:url(/fonts/band.ttf) format(\"truetype\");size-adjust:50%}" +
+	"@font-face{font-family:\"Dup\";src:url(/fonts/bar.ttf) format(\"truetype\");size-adjust:150%}" +
+	"@font-face{font-family:\"Solo\";src:url(/fonts/block.ttf) format(\"truetype\"),url(/fonts/band.ttf) format(\"truetype\")}" +
+	"h1{font-family:\"Dup\",serif}p{font-family:\"Solo\",serif}" +
+	"</style></head><body><h1>Head</h1><p>Body</p></body></html>";
+
+let capturePromise;
+
+test("duplicate @font-face rules resolve to the later rule, as the browser does", { timeout: TEST_TIMEOUT }, async () => {
+	const { embedded, sizes } = await getCaptureResult();
+	const dup = embedded.filter(rule => rule.family === "Dup");
+	assert.ok(dup.length > 0, "no Dup rule survived the save");
+	dup.forEach(rule => assert.equal(rule.length, sizes["bar.ttf"],
+		`a Dup rule embedded ${describe(rule.length, sizes)} instead of bar.ttf, the later rule's font`));
+});
+
+test("a shadowed @font-face rule is dropped, with its own descriptors", { timeout: TEST_TIMEOUT }, async () => {
+	const { embedded } = await getCaptureResult();
+	const dup = embedded.filter(rule => rule.family === "Dup");
+	assert.equal(dup.length, 1, "the shadowed rule was kept, so the font is embedded twice");
+	assert.match(dup[0].text, /size-adjust:\s*150%/, "the surviving rule is not the later one");
+	assert.doesNotMatch(dup[0].text, /size-adjust:\s*50%/, "the earlier rule's metrics survived");
+});
+
+test("a single @font-face rule still resolves to its first source", { timeout: TEST_TIMEOUT }, async () => {
+	const { embedded, sizes } = await getCaptureResult();
+	const solo = embedded.filter(rule => rule.family === "Solo");
+	assert.equal(solo.length, 1, "expected one Solo rule");
+	assert.equal(solo[0].length, sizes["block.ttf"],
+		`the Solo rule embedded ${describe(solo[0].length, sizes)} instead of block.ttf, its first source`);
+});
+
+function describe(length, sizes) {
+	const name = Object.keys(sizes).find(fontName => sizes[fontName] === length);
+	return name || length + " bytes";
+}
+
+function getCaptureResult() {
+	if (!capturePromise) {
+		capturePromise = runCapture();
+	}
+	return capturePromise;
+}
+
+async function runCapture() {
+	const fonts = new Map();
+	const sizes = {};
+	for (const name of FONT_NAMES) {
+		const data = await readFile(join(FONTS_DIRECTORY, name));
+		fonts.set(name, data);
+		sizes[name] = data.length;
+	}
+	const server = createServer((request, response) => {
+		const { pathname } = new URL(request.url, "http://localhost");
+		const name = pathname.startsWith("/fonts/") && pathname.slice("/fonts/".length);
+		if (name && fonts.has(name)) {
+			response.writeHead(200, { "content-type": "font/ttf" }).end(fonts.get(name));
+		} else if (pathname === "/") {
+			response.writeHead(200, { "content-type": "text/html" }).end(PAGE);
+		} else {
+			response.writeHead(404).end();
+		}
+	});
+	await new Promise(resolve => server.listen(0, "localhost", resolve));
+	const directory = await mkdtemp(join(tmpdir(), "single-file-test-"));
+	try {
+		const outputPath = join(directory, "out.html");
+		await execFileAsync(process.execPath, ["single-file-node.js", "http://localhost:" + server.address().port + "/", outputPath], { cwd: cliDirectory });
+		const content = (await readFile(outputPath)).toString("utf8");
+		const embedded = [...content.matchAll(/@font-face\s*{[^}]*}/g)].map(match => {
+			const family = match[0].match(/font-family:\s*"?([^;"}]+)"?/);
+			const data = match[0].match(/base64,([A-Za-z0-9+/=]+)/);
+			return {
+				family: family && family[1].trim(),
+				length: data ? Buffer.from(data[1], "base64").length : 0,
+				text: match[0].replace(/base64,[A-Za-z0-9+/=]+/, "base64,...")
+			};
+		});
+		return { embedded, sizes };
+	} finally {
+		await rm(directory, { recursive: true });
+		server.close();
+	}
+}

package/test/e2e/html-at-media-url.test.js

@@ -5,6 +5,8 @@
 // so a plain save embedded the HTML as src:url(data:text/html;base64,...) inside the @font-face,
 // while --compress-content dropped it because only that path tests the bytes with FontFace. An
 // HTML body at a media URL is never a usable resource, so both modes now treat it like a 404.
+// A @font-face left with no source at all is dropped whole, rather than kept as an "src:" with
+// nothing after it, which is the invalid declaration a browser discards anyway.
 //
 // The controls are a real font and a real image on the same page: they must still be embedded.
 
@@ -39,7 +41,7 @@ const capturePromises = new Map();
 test("an HTML page served at a font URL is dropped from a plain save", { timeout: TEST_TIMEOUT }, async () => {
 	const content = (await getCaptureResult(false)).toString("utf8");
 	assert.ok(!content.includes("data:text/html"), "an HTML body was embedded as a resource");
-	assert.match(content, /font-family:\s*"?Fake"?;\s*src:\s*[;}]/, "the unusable font source was not removed");
+	assert.doesNotMatch(content, /@font-face\s*{[^}]*font-family:\s*"?Fake"?/, "the unusable @font-face rule was kept");
 	assert.match(content, /font-family:\s*"?Real"?;\s*src:\s*url\("?data:font\/ttf;base64,/, "the real font was not embedded");
 });
 

package/test/e2e/max-appended-data-length.test.js

@@ -0,0 +1,100 @@
+/* global URL */
+
+// --max-appended-data-length caps the bytes a self-extracting page leaves after the ZIP end of
+// central directory record. A recovery payload over the cap is relocated ahead of the compressed
+// data instead, which is what makes the file readable by a reader whose end-of-archive scan window
+// is narrow (16383 bytes for libarchive, against 65557 for Python zipfile).
+//
+// The assertion that matters is that the switch REACHES core at all. --declare-appended-data once
+// shipped inert because core filtered the options it forwarded through a hand-written whitelist,
+// and the CLI has an explicit list of its own on the multi-page path, so an option can be declared,
+// parsed, documented and still do nothing. A capture at each end of the range is the cheap proof.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+const { configure, ZipReader, Uint8ArrayReader } = await importLibModule("single-file-archive.js");
+import { cliDirectory, importLibModule } from "../target.js";
+
+const execFileAsync = promisify(execFile);
+const TEST_TIMEOUT = 120000;
+const END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50;
+const END_OF_CENTRAL_DIRECTORY_LENGTH = 22;
+const COMMENT_LENGTH_OFFSET = 20;
+
+const capturePromises = new Map();
+
+test("a payload over --max-appended-data-length is not appended", { timeout: TEST_TIMEOUT }, async () => {
+	const { data, stderr } = await getCaptureResult(0);
+	assert.equal(trailingBytes(data), 0, "nothing may follow the record when the budget is zero, stderr: " + stderr);
+});
+
+test("a payload within --max-appended-data-length is appended", { timeout: TEST_TIMEOUT }, async () => {
+	const { data, stderr } = await getCaptureResult(1000000);
+	assert.ok(trailingBytes(data) > 0, "a generous budget must leave the payload appended, stderr: " + stderr);
+});
+
+test("the archive stays readable at either end of the range", { timeout: TEST_TIMEOUT }, async () => {
+	for (const maxAppendedDataLength of [0, 1000000]) {
+		const { data } = await getCaptureResult(maxAppendedDataLength);
+		configure({ useWebWorkers: false });
+		const zipReader = new ZipReader(new Uint8ArrayReader(data));
+		const entryNames = (await zipReader.getEntries()).map(entry => entry.filename);
+		assert.ok(entryNames.includes("index.html"), "maxAppendedDataLength: " + maxAppendedDataLength);
+	}
+});
+
+function trailingBytes(data) {
+	const { offset, commentLength } = findEndOfCentralDirectory(data);
+	return data.length - (offset + END_OF_CENTRAL_DIRECTORY_LENGTH + commentLength);
+}
+
+function getCaptureResult(maxAppendedDataLength) {
+	if (!capturePromises.has(maxAppendedDataLength)) {
+		capturePromises.set(maxAppendedDataLength, runCapture(maxAppendedDataLength));
+	}
+	return capturePromises.get(maxAppendedDataLength);
+}
+
+async function runCapture(maxAppendedDataLength) {
+	const server = createServer((request, response) => {
+		const { pathname } = new URL(request.url, "http://localhost");
+		if (pathname === "/") {
+			response.writeHead(200, { "content-type": "text/html" })
+				.end("<html><head><title>Budget Page</title></head><body>content</body></html>");
+		} else {
+			response.writeHead(404).end();
+		}
+	});
+	await new Promise(resolve => server.listen(0, "localhost", resolve));
+	const directory = await mkdtemp(join(tmpdir(), "single-file-test-"));
+	try {
+		const origin = "http://localhost:" + server.address().port;
+		const { stderr } = await execFileAsync(process.execPath, [
+			"single-file-node.js", origin + "/", join(directory, "page.html"),
+			"--compress-content",
+			"--max-appended-data-length=" + maxAppendedDataLength
+		], { cwd: cliDirectory });
+		const data = new Uint8Array(await readFile(join(directory, "page.html")));
+		return { data, stderr };
+	} finally {
+		await rm(directory, { recursive: true });
+		server.close();
+	}
+}
+
+function findEndOfCentralDirectory(data) {
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	for (let offset = data.length - END_OF_CENTRAL_DIRECTORY_LENGTH; offset >= 0; offset--) {
+		if (view.getUint32(offset, true) === END_OF_CENTRAL_DIRECTORY_SIGNATURE) {
+			return { offset, commentLength: view.getUint16(offset + COMMENT_LENGTH_OFFSET, true) };
+		}
+	}
+	throw new Error("end of central directory record not found");
+}

package/test/unit/archive-options.test.js

@@ -0,0 +1,51 @@
+// The multi-page archive path used to hand-list the 19 options it forwarded to createPagesArchive.
+// The single-page path passes the whole options object through, so a compression option added to
+// core reached every ordinary capture and was silently ignored by --crawl-save-archive alone —
+// which is the worst shape for this kind of gap, because the option looks wired. Core removed the
+// same trap on its side by exporting PROCESS_OPTION_NAMES instead of copying the names; the
+// forwarding here now derives from that list, and what is deliberately withheld is named.
+//
+// --max-appended-data-length is what found this: it needed a line here as well as in options.js,
+// and would otherwise have shipped working everywhere except archives.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { importLibModule } from "../target.js";
+import { getArchiveOptions, ARCHIVE_EXCLUDED_OPTION_NAMES } from "../../single-file-cli-api.js";
+const { PROCESS_OPTION_NAMES } = await importLibModule("single-file-archive.js");
+
+// the keys forwarded before the refactor, pinned so the derivation cannot quietly change what the
+// archive path receives
+const FORWARDED = [
+	"zipScript", "dedupPages", "markUnarchivedLinks", "tocPage", "pageList", "pageTransitions",
+	"insertSingleFileComment", "removeSavedDate", "declareAppendedData", "embeddedImage",
+	"embeddedPdf", "extractDataFromPage", "includeBOM", "insertCanonicalLink", "insertMetaCSP",
+	"insertMetaNoIndex", "maxAppendedDataLength", "preventAppendedData", "selfExtractingArchive"
+];
+
+test("every compression option is either forwarded to the archive or deliberately withheld", () => {
+	const forwarded = Object.keys(getArchiveOptions({}));
+	const unaccounted = PROCESS_OPTION_NAMES
+		.filter(name => !forwarded.includes(name) && !ARCHIVE_EXCLUDED_OPTION_NAMES.includes(name));
+	assert.deepEqual(unaccounted, [],
+		"core gained a compression option the archive path neither forwards nor names as withheld, so it is silently ignored by --crawl-save-archive; forward it, or add it to ARCHIVE_EXCLUDED_OPTION_NAMES");
+});
+
+test("the archive receives exactly the options it received before the derivation", () => {
+	assert.deepEqual(Object.keys(getArchiveOptions({})).sort(), FORWARDED.slice().sort());
+});
+
+test("the withheld options are real compression options, not typos", () => {
+	const unknown = ARCHIVE_EXCLUDED_OPTION_NAMES.filter(name => !PROCESS_OPTION_NAMES.includes(name));
+	assert.deepEqual(unknown, [], "a withheld name that core does not define hides a real gap behind a dead entry");
+});
+
+test("a crawl option is renamed on its way to the archive", () => {
+	const forwarded = getArchiveOptions({ crawlSaveArchiveDedup: true, crawlSaveArchiveToc: true });
+	assert.equal(forwarded.dedupPages, true);
+	assert.equal(forwarded.tocPage, true);
+});
+
+test("a compression option reaches the archive under its own name", () => {
+	assert.equal(getArchiveOptions({ maxAppendedDataLength: 4096 }).maxAppendedDataLength, 4096);
+});