single-file-core 1.5.128 → 1.5.129

package/core/index.js

@@ -464,7 +464,7 @@ class Processor {
 			content = await util.getContent(this.baseURI, {
 				inline: !this.options.compressContent,
 				maxResourceSize: this.options.maxResourceSize,
-				maxResourceSizeEnabled: this.options.maxResourceSizeEnabled,
+				maxResourceSizeEnabled: this.options.maxResourceSizeEnabled && !this.options.rootDocument,
 				charset,
 				frameId: this.options.windowId,
 				resourceReferrer: this.options.resourceReferrer,

package/core/infobar.js

@@ -75,6 +75,21 @@ const INFOBAR_STYLES = `
   animation-iteration-count: 2;
 }
 
+.infobar:not(:focus-within):not(.infobar-focus)::after {
+  content: "";
+  position: absolute;
+  inset: -2px;
+  border: 2px solid #dd6a00;
+  border-radius: inherit;
+  opacity: 0;
+  pointer-events: none;
+  animation-name: ripple;
+  animation-duration: 3s;
+  animation-timing-function: ease-out;
+  animation-delay: 2s;
+  animation-iteration-count: 3;
+}
+
 .infobar:valid, .infobar:not(:focus-within):not(.infobar-focus) .infobar-content {
   display: none;
 }
@@ -133,6 +148,24 @@ const INFOBAR_STYLES = `
   }
 }
 
+@keyframes ripple {
+  0% {
+	transform: scale(1);
+	opacity: 1;
+  }
+  45%, 100% {
+	transform: scale(2);
+	opacity: 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .infobar,
+  .infobar:not(:focus-within):not(.infobar-focus)::after {
+	animation-name: none;
+  }
+}
+
 .infobar:focus-within .infobar-icon, .infobar.infobar-focus .infobar-icon {
   z-index: -1;
   background-image: none;

package/deno.lock

@@ -0,0 +1,19 @@
+{
+  "version": "5",
+  "specifiers": {
+    "jsr:@b-fuze/deno-dom@0.1.56": "0.1.56"
+  },
+  "jsr": {
+    "@b-fuze/deno-dom@0.1.56": {
+      "integrity": "8030e2dc1d8750f1682b53462ab893d9c3470f2287feecbe22f44a88c54ab148"
+    }
+  },
+  "workspace": {
+    "packageJson": {
+      "dependencies": [
+        "npm:@eslint/js@^9.39.5",
+        "npm:eslint@^10.9.1"
+      ]
+    }
+  }
+}

package/doc/singlefile-archive.md

@@ -1079,13 +1079,31 @@ trailing bytes open it (§8.1). The parser closes the open
 comment or element at end of file, and `</body></html>` are implied, so the page
 renders the same.
 
-Relocation is not a move at constant size, and it can end either way. Two effects pull
-against each other: the room the writer sets aside, which in the reference writer is
-`Math.ceil(length * 1.01) + 32` bytes — a percentage of the payload plus a constant, so
-the constant dominates a small payload and the percentage a large one — and the 17 bytes
-of wrapper terminator and end tags it stops emitting. Measured on three files the net ran
-from 9 bytes saved to 190 bytes spent, so a writer sizing a file should quote that range
-rather than a single figure.
+Relocation moves the element rather than copying it, but it is not a move at constant
+size, and wherever there is an element to move it costs bytes. The appended placement
+emits the wrapper terminator, the element and the end tags, the element plus 17; the
+relocated placement emits none of those and reserves room ahead of the archive instead,
+`Math.ceil(length * 1.01) + 32` bytes in the reference writer, where *length* is the
+element with its tags. The net is that reservation less the element and less the 17
+bytes, so about one percent of the element plus fifteen: what relocation costs is the
+margin, not a second copy. Measured on elements from 61 to 17577 bytes the formula holds
+to within a few bytes, the residual being the element itself changing length between the
+two passes, since the reservation lengthens the prologue and moves every
+central-directory offset with it. The wrapper rung sets the constant: fifteen bytes
+behind a comment, nine behind `</script>` or `]]></svg>`, six behind `</plaintext>`.
+With extraction disabled there is no element and nothing is reserved, so suppressing the
+appended run drops those 17 bytes and nothing else.
+
+The two cases a writer meets differ by an order of magnitude, and the budget is what
+separates them. A relocation forced by `preventAppendedData` acts on whatever element
+exists, which on a small archive is small: 16 bytes on a 2848-byte ZIP region, 35 bytes
+on a 1.3 MB one. A relocation the budget triggers cannot be cheap, because it happens
+only once the element no longer fits: at the default 16361 that means an element past
+16344 bytes, and 185 bytes measured on a 12.7 MB region is near the least it can cost.
+It keeps rising from there, since a relocated element sits in the prologue and no comment
+ceiling bounds it — at the ratio above, a 40 MB archive carries roughly 57 KB of element
+and costs roughly 590 bytes. A writer sizing a file should compute the cost from the
+element it produced rather than quote any of these figures.
 
 ### 5.3 Offset bookkeeping
 

package/eslint.config.mjs

@@ -56,5 +56,19 @@ export default [
 		rules: {
 			"no-console": "off"
 		}
+	},
+	{
+		files: ["test/capture/**", "test/run.js"],
+		languageOptions: {
+			globals: {
+				Deno: "readonly",
+				Response: "readonly",
+				TextDecoder: "readonly",
+				URL: "readonly"
+			}
+		},
+		rules: {
+			"no-console": "off"
+		}
 	}
 ];

package/package.json

@@ -1,11 +1,11 @@
 {
 	"name": "single-file-core",
-	"version": "1.5.128",
+	"version": "1.5.129",
 	"description": "SingleFile Core",
 	"author": "Gildas Lormeau",
 	"license": "AGPL-3.0-or-later",
 	"scripts": {
-		"test": "deno run --allow-read test/sfz-harness/format-rules.js && deno run --allow-read test/sfz-harness/stored-trigger.js && deno run --allow-read test/sfz-harness/check-determinism.js && deno run --allow-read test/sfz-harness/option-wiring.js && deno run --allow-read test/sfz-harness/css-property-filter.js && deno run --allow-read test/sfz-harness/adopted-stylesheets-hook.js && deno run --allow-read test/sfz-harness/css-fonts-minifier.js && deno run --allow-read test/sfz-harness/font-face-composite.js && deno run --allow-read test/sfz-harness/inlined-functions.js && deno run --allow-read test/sfz-harness/pages-archive.js && deno run --allow-read test/sfz-harness/pages-router.js && deno run --allow-read test/sfz-harness/filename-max-length.js && deno run --allow-read test/sfz-harness/content-type-sniffing.js && deno run --allow-read test/sfz-harness/entry-compression.js && deno run --allow-read test/sfz-harness/filename-characters.js && deno run --allow-read test/sfz-harness/byte-map.js && deno run --allow-read test/sfz-harness/zip64.js && deno run --allow-read test/sfz-harness/charset-round-trip.js",
+		"test": "deno run --allow-read --allow-run test/run.js",
 		"bump-patch": "npm version patch --no-git-tag-version && npm run bump-commit",
 		"bump-minor": "npm version minor --no-git-tag-version && npm run bump-commit",
 		"bump-major": "npm version major --no-git-tag-version && npm run bump-commit",

package/processors/compression/compression-packager.js

@@ -67,7 +67,7 @@ async function createPagesArchive(pages, options) {
 	}
 	const manifest = {
 		pages: pages.map((page, pageIndex) => ({
-			path: getPagePath(pageIndex),
+			path: getPagePath(pageIndex, options.createRootDirectory),
 			url: page.url,
 			originalUrls: page.originalUrls,
 			title: page.title
@@ -97,7 +97,7 @@ async function createPagesArchive(pages, options) {
 	const aliases = {};
 	const blob = await createArchive(pageData, archiveOptions, options.zipScript, async zipWriter => {
 		for (let pageIndex = 0; pageIndex < pages.length; pageIndex++) {
-			const pagePath = getPagePath(pageIndex);
+			const pagePath = getPagePath(pageIndex, options.createRootDirectory);
 			const zipReader = new ZipReader(new Uint8ArrayReader(await pages[pageIndex].getData()));
 			for (const entry of await zipReader.getEntries()) {
 				const filename = pagePath + entry.filename;
@@ -163,8 +163,8 @@ function getRelativePath(filename, targetFilename) {
 	return "../".repeat(baseSegments.length) + targetSegments.join("/");
 }
 
-function getPagePath(pageIndex) {
-	return pageIndex == 0 ? "" : PAGES_PREFIX + (pageIndex + 1) + "/";
+function getPagePath(pageIndex, createRootDirectory) {
+	return pageIndex == 0 && !createRootDirectory ? "" : PAGES_PREFIX + (pageIndex + 1) + "/";
 }
 
 function getComment(url, options) {

package/test/capture/README.md

@@ -0,0 +1,74 @@
+# Capture harness
+
+Tests that drive the real capture pipeline — `getPageData()`, `Processor`, `loadPage`, the batch
+fetch layer — in Deno, with an injected fetch and a parser instead of a browser. Every resource a
+capture asks for is served from a map declared in the suite, so there is no network and no page.
+
+It exists because the [SFZ harness](../sfz-harness/README.md) next door covers the archive writer and
+its neighbours, and nothing covered `core/index.js`. A defect in the capture pipeline could only be
+caught by driving Chrome from `single-file-cli`, in another repository, against a published build.
+
+Run them with Deno, from the repository root:
+
+```
+npm test
+```
+
+or this directory alone, through the same runner:
+
+```
+deno run --allow-read --allow-run test/run.js capture
+```
+
+or one suite at a time, which needs no runner:
+
+```
+deno run --allow-read test/capture/resource-cap.js
+```
+
+`common.js` and `dom.js` are named in the runner's `NOT_SUITES` list because they assert
+nothing. Every other `.js` file here is run.
+
+Unlike the SFZ harness, these download `@b-fuze/deno-dom` from JSR, so a cold cache needs network.
+The version is pinned in `dom.js` and `deno.lock` carries its integrity hash, so a cold run fetches
+that exact build or fails. `test/*` is ignored by `.gitignore` with one exception per directory, so a
+new test directory needs its own `!` line or nothing in it is ever committed.
+
+## The suites
+
+| Script | What it covers |
+|---|---|
+| `resource-cap.js` | That `maxResourceSize` applies to what the capture fetches and never to the page document itself. A page supplied as content is untouched, a page fetched by `saveRawPage` is untouched, an image over the cap is still dropped, frame content supplied as data is untouched, and a frame fetched in raw mode is still dropped. The raw-page case is a regression test: the cap used to empty the document, so a 2.5 MB page was saved as 525 bytes with no body, exit code 0 and no warning. |
+
+## How it works
+
+`dom.js` installs the globals core reads when its modules are evaluated — `DOMParser`, `Document`,
+`window`, `MutationObserver`. Import it before core, which is why `common.js` imports `single-file.js`
+dynamically.
+
+`common.js` exports `capture(resources, options)`, which returns the saved page as a string. Two
+things about it are forced by core rather than chosen. `init()` builds the util instance once per
+process and returns early ever after, so the injected fetch cannot be swapped per capture: one
+dispatcher is installed and `capture()` points it at the map for the run in progress. And a capture
+that passes no document never runs `preProcessDoc`, so the arrays it would have produced have to be
+supplied empty — `processWorklets` and its neighbours read `.length` with no guard.
+
+`frameData(windowId, baseURI, content)` builds the frame data a content script would have captured,
+matched to a frame element carrying the same window id. `html(body, head)` wraps a fixture.
+
+## What it cannot test
+
+Anything that reads a live document: `preProcessDoc`, `removeHiddenElements` and its marked elements,
+and the `getComputedStyle` callers in `core/infobar.js` and `modules/css-fonts-minifier.js`. Leave
+those options off here. The browser rigs in `single-file-cli` and `single-file-tests` cover them.
+
+deno-dom is not a browser parser. It materializes a whole `NodeList` when `children` is read, and
+`buildTrackIdMap` walks the tree child by child, so a fixture with 100k siblings overflows the stack.
+Size a fixture with long text in few elements.
+
+## Adding a case
+
+Same rule as the SFZ harness: add checks to the suite that already covers the area rather than making
+a file per rule, write the comment that says *why* the rule exists, and confirm the check can fail.
+For `resource-cap.js` that was done by reverting the `&& !this.options.rootDocument` conjunct in
+`core/index.js`: exactly one check goes red, which is the check that names it.

package/test/capture/common.js

@@ -0,0 +1,72 @@
+import "./dom.js";
+
+const { init, getPageData, helper } = await import("../../single-file.js");
+
+const WIN_ID_ATTRIBUTE_NAME = helper.WIN_ID_ATTRIBUTE_NAME;
+
+// preProcessDoc fills these from the live document, and it only runs when a doc is passed. A capture
+// driven from here passes none, so the arrays it would have produced have to be supplied empty:
+// processWorklets and its neighbours read .length with no guard.
+const EMPTY_DOC_DATA = {
+	adoptedStyleSheets: [],
+	canvases: [],
+	fonts: [],
+	images: [],
+	posters: [],
+	referrer: "",
+	shadowRoots: [],
+	stylesheets: [],
+	usedFonts: [],
+	videos: [],
+	worklets: []
+};
+
+// init() builds the util instance once per process and returns early ever after, so the fetch cannot
+// be swapped per capture. One dispatcher is installed here and capture() points it at the resources
+// of the run in progress; captures are sequential, so nothing races.
+let resources = new Map();
+
+const initOptions = {
+	fetch: fetchResource,
+	frameFetch: fetchResource
+};
+
+init(initOptions);
+
+export {
+	capture,
+	frameData,
+	html,
+	WIN_ID_ATTRIBUTE_NAME
+};
+
+async function capture(pageResources, options) {
+	resources = pageResources instanceof Map ? pageResources : new Map(Object.entries(pageResources));
+	const pageData = await getPageData({ ...EMPTY_DOC_DATA, ...options }, initOptions, null, null);
+	return pageData.content;
+}
+
+function fetchResource(url) {
+	const resource = resources.get(url);
+	if (!resource) {
+		return Promise.resolve(new Response("", { status: 404 }));
+	}
+	const contentType = resource.contentType || "text/html";
+	return Promise.resolve(new Response(resource.body, {
+		status: resource.status || 200,
+		headers: { "content-type": contentType }
+	}));
+}
+
+// A frame whose content was captured by the content script arrives as frame data keyed by the window
+// id its element carries. Outside raw mode this is the only way a frame is ever filled.
+function frameData(windowId, baseURI, content) {
+	return { ...EMPTY_DOC_DATA, windowId, baseURI, content, scrollPosition: { x: 0, y: 0 } };
+}
+
+// deno-dom materializes a whole NodeList when children is read, and buildTrackIdMap walks the tree
+// child by child, so a fixture with 100k siblings overflows the stack. Size a fixture with long text
+// in few elements, never with many elements.
+function html(body, head = "") {
+	return "<!DOCTYPE html><html><head>" + head + "</head><body>" + body + "</body></html>";
+}

package/test/capture/dom.js

@@ -0,0 +1,14 @@
+// Three modules read globals when they are evaluated, so every one of them has to exist before core
+// is imported: core/util.js captures DOMParser, and processors/hooks/content/content-hooks-frames.js
+// reads globalThis.window, then calls init() and new MutationObserver(init) at module scope. That
+// hook belongs to the page world and does nothing useful here; it only has to load without throwing.
+// Import this module first and import single-file.js dynamically, the way common.js does.
+import { DOMParser, Document } from "jsr:@b-fuze/deno-dom@0.1.56";
+
+globalThis.DOMParser = DOMParser;
+globalThis.Document = Document;
+globalThis.window = globalThis;
+globalThis.MutationObserver = class {
+	observe() { }
+	disconnect() { }
+};

package/test/capture/resource-cap.js

@@ -0,0 +1,79 @@
+import { capture, frameData, html, WIN_ID_ATTRIBUTE_NAME } from "./common.js";
+
+const PAGE_URL = "https://example.com/big.html";
+const HOST_URL = "https://example.com/host.html";
+const IMAGE_URL = "https://example.com/big.png";
+const PAGE_MARKER = "BIG PAGE MARKER";
+const HOST_MARKER = "HOST PAGE MARKER";
+
+// One paragraph of 2.1 MB rather than many small ones, for the reason common.js gives.
+const BIG_PAGE = html("<h1>" + PAGE_MARKER + "</h1><p>" + "filler ".repeat(300000) + "</p>");
+const HOST_PAGE = html("<h1>" + HOST_MARKER + "</h1><iframe src=\"" + PAGE_URL + "\" " + WIN_ID_ATTRIBUTE_NAME + "=\"0.1\"></iframe>");
+const IMAGE_PAGE = html("<h1>" + HOST_MARKER + "</h1><img src=\"" + IMAGE_URL + "\">");
+const BIG_IMAGE = new Uint8Array(2 * 1024 * 1024).fill(0x21);
+
+const resources = {
+	[PAGE_URL]: { body: BIG_PAGE },
+	[HOST_URL]: { body: HOST_PAGE },
+	[IMAGE_URL]: { body: BIG_IMAGE, contentType: "image/png" }
+};
+
+// One megabyte, so every fixture above is over it and the default of ten is not in the way.
+const CAP = { maxResourceSizeEnabled: true, maxResourceSize: 1 };
+
+let failed = false;
+
+// The content a browser captured is handed to core as a string and never fetched, so the cap has no
+// point at which it could fire. This is what every extension save and every non-raw CLI capture does.
+{
+	const content = await capture(resources, { url: PAGE_URL, content: BIG_PAGE, ...CAP });
+	check("a page supplied as content is never capped", content.includes(PAGE_MARKER), true);
+}
+
+// The regression test. loadPage fetches the document itself in raw mode, and until rootDocument was
+// excluded the cap emptied it: a 2.5 MB page came out as 525 bytes with no body at all, exit code 0
+// and no warning. The cap is documented to apply to "images, fonts, stylesheets, scripts, frames,
+// videos and audios", never to the page.
+{
+	const content = await capture(resources, { url: PAGE_URL, saveRawPage: true, ...CAP });
+	check("a raw page over the cap keeps its content", content.includes(PAGE_MARKER), true);
+}
+
+// The control for the test above: the same cap, in the same capture, still has to drop a resource.
+// A fix that exempted everything would pass the raw-page check and break the option.
+{
+	const capped = await capture(resources, { url: HOST_URL, content: IMAGE_PAGE, ...CAP });
+	const uncapped = await capture(resources, { url: HOST_URL, content: IMAGE_PAGE });
+	check("an image over the cap is left out", capped.includes("data:image/png;base64"), false);
+	check("the page holding it is kept", capped.includes(HOST_MARKER), true);
+	check("the same image is embedded with the cap off", uncapped.includes("data:image/png;base64"), true);
+}
+
+// Frame content captured by the content script arrives as data, like the top document above, so the
+// cap cannot reach it either.
+{
+	const frames = [frameData("0.1", PAGE_URL, BIG_PAGE)];
+	const content = await capture(resources, { url: HOST_URL, content: HOST_PAGE, frames, ...CAP });
+	check("a frame supplied as data is never capped", content.includes(PAGE_MARKER), true);
+	check("its host is kept", content.includes(HOST_MARKER), true);
+}
+
+// In raw mode there is no frame data: resolveFrameURLs pushes a frame with no content and its runner
+// fetches the frame document, which is the one caller the cap is meant for. Dropping it is correct.
+{
+	const content = await capture(resources, { url: HOST_URL, saveRawPage: true, ...CAP });
+	check("a raw frame over the cap is dropped", content.includes(PAGE_MARKER), false);
+	check("its host is kept", content.includes(HOST_MARKER), true);
+}
+
+if (failed) {
+	console.log("FAILED");
+	Deno.exit(1);
+}
+console.log("OK");
+
+function check(label, actual, expected) {
+	const ok = actual === expected;
+	console.log(`${ok ? "PASS" : "FAIL"} ${label}: ${actual}${ok ? "" : " (expected " + expected + ")"}`);
+	failed ||= !ok;
+}

package/test/run.js

@@ -0,0 +1,109 @@
+// Runs every suite under test/, so that adding one means adding a file rather than editing a chain
+// of shell commands. Two failure modes are worth naming, because this exists to remove the first
+// without introducing the second: a suite nobody added to a hand-written list is never run and
+// nobody notices, and a runner that takes every file it finds runs a scratch file that was never a
+// test — single-file-tests did exactly that inside a release gate. So the files that are NOT suites
+// are named below and anything else in these directories is run, which fails loudly rather than
+// quietly. Keep this list in step when a helper or a tool is added.
+//
+// Unlike the chain it replaces, one red suite no longer hides the nineteen behind it: everything
+// runs, and the summary says what failed.
+//
+//   deno run --allow-read --allow-run test/run.js            every suite
+//   deno run --allow-read --allow-run test/run.js cap font   suites whose path matches an argument
+//   deno run --allow-read --allow-run test/run.js --verbose  with the output of the suites that pass
+
+const SUITE_DIRECTORIES = ["sfz-harness", "capture"];
+const NOT_SUITES = [
+	"sfz-harness/common.js",
+	"sfz-harness/dom-stub.js",
+	"sfz-harness/gen-e2e-page.js",
+	"sfz-harness/search-triggers.js",
+	"sfz-harness/smoke.js",
+	"capture/common.js",
+	"capture/dom.js"
+];
+
+const verbose = Deno.args.includes("--verbose");
+const filters = Deno.args.filter(argument => !argument.startsWith("--"));
+const suites = await findSuites();
+const selected = filters.length ? suites.filter(suite => filters.some(filter => suite.includes(filter))) : suites;
+
+if (!selected.length) {
+	console.log(filters.length ? `no suite matches ${filters.join(", ")}` : "no suite found");
+	Deno.exit(1);
+}
+
+let checksPassed = 0, checksFailed = 0;
+const failures = [];
+for (const suite of selected) {
+	const result = await runSuite(suite);
+	checksPassed += result.passed;
+	checksFailed += result.failed;
+	if (result.ok) {
+		console.log(`PASS ${suite}${result.passed ? ` (${result.passed} checks)` : ""}`);
+		if (verbose) {
+			console.log(indent(result.output));
+		}
+	} else {
+		failures.push(suite);
+		console.log(`FAIL ${suite}${result.failed ? ` (${result.failed} of ${result.passed + result.failed} checks)` : ` (exit ${result.code})`}`);
+		// a suite that fails a check has already said which one; a suite that crashed has not, and
+		// its output is the only thing that explains the exit code
+		console.log(indent(result.failed ? result.failedLines : result.output));
+	}
+}
+
+const skipped = NOT_SUITES.length;
+console.log(`\n${selected.length} suites, ${checksPassed + checksFailed} checks, ${skipped} files skipped as tools or helpers`);
+if (failures.length) {
+	console.log(`FAILED: ${failures.join(", ")}`);
+	Deno.exit(1);
+}
+console.log("all suites passed");
+
+async function findSuites() {
+	const found = [];
+	for (const directory of SUITE_DIRECTORIES) {
+		const names = [];
+		for await (const entry of Deno.readDir(new URL(directory + "/", import.meta.url))) {
+			if (entry.isFile && entry.name.endsWith(".js")) {
+				names.push(entry.name);
+			}
+		}
+		names.sort();
+		for (const name of names) {
+			const path = directory + "/" + name;
+			if (!NOT_SUITES.includes(path)) {
+				found.push(path);
+			}
+		}
+	}
+	return found;
+}
+
+async function runSuite(suite) {
+	const command = new Deno.Command(Deno.execPath(), {
+		args: ["run", "--allow-read", new URL(suite, import.meta.url).pathname],
+		stdout: "piped",
+		stderr: "piped"
+	});
+	const { code, stdout, stderr } = await command.output();
+	const decoder = new TextDecoder();
+	const output = (decoder.decode(stdout) + decoder.decode(stderr)).trimEnd();
+	// the space matters: a suite ends on a bare "FAILED" line, which is a verdict and not a check
+	const lines = output.split("\n");
+	const failedLines = lines.filter(line => line.startsWith("FAIL ")).join("\n");
+	return {
+		code,
+		ok: code === 0,
+		output,
+		failedLines,
+		passed: lines.filter(line => line.startsWith("PASS ")).length,
+		failed: lines.filter(line => line.startsWith("FAIL ")).length
+	};
+}
+
+function indent(text) {
+	return text.split("\n").map(line => "  " + line).join("\n");
+}

package/test/sfz-harness/README.md

@@ -14,7 +14,14 @@ Run them with Deno, from the repository root:
 npm test
 ```
 
-or one at a time:
+which is [`test/run.js`](../run.js), the runner for every suite under `test/`. It takes
+name filters, so this directory alone is:
+
+```
+deno run --allow-read --allow-run test/run.js sfz-harness
+```
+
+or one at a time, which needs no runner:
 
 ```
 deno run --allow-read test/sfz-harness/format-rules.js
@@ -42,12 +49,16 @@ any check failed.
 | `filename-characters.js` | That `getValidFilename` maps a full-width lookalike one character at a time — `C++` used to be saved as `C＋` — while a run of characters with no lookalike still collapses to a single replacement. |
 | `zip64.js` | That the `page.pdf` record injection accounts for the zip64 end of central directory record (§5.7): all four EOCD fields left at their sentinels, the entry counts and directory size carried in the zip64 record, the directory offset pointing at the injected record, and the archive still readable. The branch runs only past 4 GiB or 65535 entries, so nothing reached it before; the suite forces zip64 through `zipWriter.options` from inside the `writeEntries` callback, with no production lever. |
 | `byte-map.js` | That the byte offsets §8.2 of the specification prints still describe what the writer emits: the prologue order, the doctype and root tag with nothing between them, the identifier's length ahead of the region, absolute EOCD offsets, and the entry order. The specimen §8.2 documents is saved from a live URL and has never been in this repository, so none of its numbers could be checked; three of them were wrong. This builds an equivalent with no network. |
+| `relocation-cost.js` | That the figures §5.2 prints for relocating the extra-data element reconstruct. Two of the three came from live captures and did not: the paragraph subtracted the terminator and the end tags from the reservation without subtracting the element, which the appended placement carries too, so it over-counted by the whole element. This pins the corrected arithmetic — the cost is the reservation margin alone, it is positive on every rung whenever an element exists, and the only way relocation saves bytes is to have no element to relocate. |
 | `charset-round-trip.js` | That the encoding tables §8.4 prints still describe the WHATWG index: which 20 of the 38 encodings carry all 256 byte values through a decode injectively, the sizes of the reverse tables they need, and the five windows-1252 positions a platform codec of the same name leaves undefined. It also re-derives the reverse table the extractor ships as a literal, which no build step checks and which corrupts one byte per occurrence when wrong. |
 | `css-fonts-minifier.js` | That `removeUnusedFonts` reads the font families it prunes on correctly: a `var()` family resolved from the values the document declares and not only from the ones the body inherits, every font kept when the value is genuinely undetermined, and a multi-word family name that does not also claim a font named after its own tail. |
+| `font-face-composite.js` | That several `@font-face` rules declaring the same family with the same style descriptors are one composite face and not a stack where the last rule wins, which is what CSS Fonts 4 §5.2 and §4.5.1 say: both members are kept with their own sources, faces split by `unicode-range` are all kept, an outright duplicate rule is emitted once, and a source repeated inside one rule is listed once, at the position of its later declaration. |
 
 ## The tools
 
-Not tests — they print, they do not assert, and CI does not run them.
+Not tests — they print, they do not assert, and CI does not run them. The runner skips
+them by name, in the `NOT_SUITES` list of [`test/run.js`](../run.js). Everything else in
+this directory IS run, so a new file is either a suite or a line in that list.
 
 | Script | Use |
 |---|---|

package/test/sfz-harness/pages-archive.js

@@ -4,9 +4,11 @@
 //
 // Three of its rules are worth stating, because they look arbitrary in the code:
 //
-//   - the first page is stored at the ROOT and the others under pages/N/. The root page is what a
-//     reader opens, so it cannot be moved into a folder without changing every relative URL the
-//     capture already resolved.
+//   - the first page is stored at the ROOT and the others under pages/N/, unless
+//     createRootDirectory asks for a folder for the first page too. A page's resources travel with
+//     it, so either layout resolves; what the root buys is a reader who unzips the archive and
+//     opens index.html without being told where to look, and what it costs is that the first page
+//     shares the root with the archive's own files.
 //   - a duplicate entry becomes a SYMLINK rather than being dropped. The router resolves it from
 //     the alias map in the manifest and never reads it, but a plain unzip has to produce complete
 //     page folders, and only a symlink gives both.
@@ -46,6 +48,37 @@ const pages = [
 		(manifest.pages[0].originalUrls || []).join(" "), "https://example.com/docs/");
 }
 
+// createRootDirectory gives the first page a folder of its own. Without it the first page is
+// written at the root, mixed in with the archive's own files, which is the reason the router needs
+// a special case at all: belongsToPage() has to read "everything not under pages/ and not named
+// sfz-*" as the first page. With every page under pages/N/ that rule is a plain prefix match.
+{
+	const entries = await readArchive(await createPagesArchive(pages, packagerOptions({ createRootDirectory: true, tocPage: true })));
+	const manifest = JSON.parse(await readEntry(entries, "sfz-pages.json"));
+	const toc = await readEntry(entries, "sfz-toc.html");
+	check("the first page is stored in a folder of its own when a root directory is asked for",
+		entries.has("pages/1/index.html"), true);
+	check("and the first page is no longer at the root", entries.has("index.html"), false);
+	check("the manifest names the folder of the first page too",
+		manifest.pages.map(page => page.path).join(" "), "pages/1/ pages/2/");
+	check("the table of contents links to the first page in its folder",
+		toc.includes("href=\"pages/1/index.html\""), true);
+	// the archive's own files stay at the root whatever the option says: the router finds them by
+	// exact name, and an archive whose sfz-pages.json moved stops being read as multi-page at all
+	check("the archive's own files are the only thing left at the root",
+		[...entries.keys()].filter(filename => !filename.includes("/")).sort().join(" "),
+		"sfz-pages.json sfz-toc.html");
+}
+
+// deduplication writes the link target relative to the folder the repeated entry sits in. With the
+// first page at the root that walk never has a common prefix to drop; with both pages in folders it
+// has to climb out of one and back into the other, which nothing exercised before
+{
+	const entries = await readArchive(await createPagesArchive(pages, packagerOptions({ createRootDirectory: true, dedupPages: true })));
+	check("a repeated entry points across folders at the one that was kept",
+		await readEntry(entries, "pages/2/styles.css"), "../1/styles.css");
+}
+
 // the router reads these two out of the manifest, and "auto" is the absence of a choice rather
 // than a value: writing it would pin the default of the day into every archive
 {

package/test/sfz-harness/pages-router.js

@@ -20,6 +20,7 @@ import * as zip from "../../vendor/zip/zip.js";
 const ARCHIVE_URL = "https://example.com/archive.html";
 
 let failed = false;
+let openedEntries;
 
 const pages = [
 	await makePage(1, { url: "https://example.com/docs/intro.html", title: "Intro" }),
@@ -50,6 +51,28 @@ const withoutTOC = await createPagesArchive(pages, packagerOptions());
 	check("a hash that is not a route opens the first page", content, "page at \"\"");
 }
 
+// createRootDirectory moves the first page into pages/1/, so the landing rule has to come from the
+// manifest rather than from the root. belongsToPage() also leaves its special case behind: while
+// the first page is at the root it can only be described as "everything not under pages/ and not
+// named sfz-*", and a page in a folder is selected by prefix like any other. The entries handed to
+// extract are the assertion, because a landing path alone would still read right if that selection
+// silently picked up the archive's own files
+{
+	const rooted = await createPagesArchive(pages, packagerOptions({ createRootDirectory: true }));
+	const content = await open(rooted);
+	check("an archive with a root directory opens on the first page in its folder", content, "page at \"pages/1/\"");
+	check("and the router hands it only the entries of that folder",
+		openedEntries.join(" "), "pages/1/index.html pages/1/manifest.json pages/1/styles.css");
+}
+
+{
+	const rooted = await createPagesArchive(pages, packagerOptions({ createRootDirectory: true, tocPage: true }));
+	check("an archive with a root directory still opens on its table of contents",
+		(await open(rooted)).includes("<h1>Table of contents</h1>"), true);
+	check("and a route still names a page in it",
+		await open(rooted, "#sfz/pages/1/"), "page at \"pages/1/\"");
+}
+
 console.log(failed ? "\nsome checks FAILED" : "\nall checks passed");
 Deno.exit(failed ? 1 : 0);
 
@@ -60,7 +83,10 @@ async function open(bytes, hash = "") {
 	let displayed;
 	installEnvironment(hash);
 	await router(new Blob([bytes]), {
-		extract: (content, { pagePath }) => ({ docContent: "page at " + JSON.stringify(pagePath) }),
+		extract: (content, { entries, pagePath }) => {
+			openedEntries = entries.map(entry => entry.filename).sort();
+			return { docContent: "page at " + JSON.stringify(pagePath) };
+		},
 		display: (document, docContent) => displayed = docContent
 	});
 	return displayed;

package/test/sfz-harness/relocation-cost.js

@@ -0,0 +1,94 @@
+// §5.2 of doc/singlefile-archive.md quantifies what relocating the extra-data element costs. The
+// figures it carried until 2026-09-12 came from two live captures and one fixture, and two of the
+// three did not reconstruct: the paragraph subtracted the 17 bytes of terminator and end tags from
+// the reservation without subtracting the element, which the appended placement also carries, so
+// it over-counted by the whole element. This pins the corrected arithmetic. The cost is the
+// reservation margin alone, it is positive on every rung whenever an element exists, and the only
+// way to make relocation save bytes is to have no element to relocate.
+import { makePageData, makeOptions, runProcess, freezeDate } from "./common.js";
+
+const DECODER = new TextDecoder("windows-1252");
+const OPEN_TAG = "<sfz-extra-data>";
+const CLOSE_TAG = "</sfz-extra-data>";
+const END_TAGS_LENGTH = "</body></html>".length;
+
+let failed = false;
+
+function check(label, actual, expected) {
+	const ok = actual === expected;
+	console.log(`${ok ? "PASS" : "FAIL"} ${label}: ${actual}${ok ? "" : " (expected " + expected + ")"}`);
+	failed ||= !ok;
+}
+
+function reservationSize(length) {
+	return Math.ceil(length * 1.01) + 32;
+}
+
+function inspect(bytes) {
+	const text = DECODER.decode(bytes);
+	const open = text.indexOf(OPEN_TAG);
+	const firstHeader = text.indexOf("PK\x03\x04");
+	return {
+		total: bytes.length,
+		element: open == -1 ? 0 : text.indexOf(CLOSE_TAG, open) + CLOSE_TAG.length - open,
+		relocated: open != -1 && open < firstHeader
+	};
+}
+
+async function build(seed, targetLength, overrides) {
+	const restoreDate = freezeDate();
+	const appended = inspect((await runProcess(makePageData(seed, targetLength), makeOptions(overrides))).bytes);
+	const relocated = inspect((await runProcess(makePageData(seed, targetLength), makeOptions({ ...overrides, preventAppendedData: true }))).bytes);
+	restoreDate();
+	return { appended, relocated, cost: relocated.total - appended.total };
+}
+
+// the element changes length between the two passes once the reservation is large enough to move
+// the central-directory offsets it encodes, and then the reservation comes from the first pass
+// while the element written into it comes from the second. These fixtures stay below that, which
+// is what lets the identity be asserted exactly rather than within a tolerance.
+for (const [label, seed, targetLength, closeTagLength] of [
+	["comment rung", 1, 64 * 1024, "-->".length],
+	["comment rung, larger", 2, 147 * 1024, "-->".length]
+]) {
+	const { appended, relocated, cost } = await build(seed, targetLength, {});
+	check(`${label}: the element keeps its length`, relocated.element, appended.element);
+	check(`${label}: relocates`, relocated.relocated, true);
+	check(`${label}: cost`, cost,
+		reservationSize(appended.element) - appended.element - closeTagLength - END_TAGS_LENGTH);
+	check(`${label}: cost is positive`, cost > 0, true);
+}
+
+// the rung sets the constant, because it is the closing tag the relocated placement stops emitting
+for (const [label, closeTag] of [
+	["script rung", "</script>"],
+	["svg CDATA rung", "]]></svg>"],
+	["plaintext rung", "</plaintext>"]
+]) {
+	const startTag = { "</script>": "<script type=sfz-data>", "]]></svg>": "<svg><![CDATA[", "</plaintext>": "<plaintext>" }[closeTag];
+	const { appended, cost } = await build(3, 64 * 1024, { extractDataFromPageTags: [startTag, closeTag] });
+	check(`${label}: cost`, cost,
+		reservationSize(appended.element) - appended.element - closeTag.length - END_TAGS_LENGTH);
+	check(`${label}: cost is positive`, cost > 0, true);
+}
+
+// with no element there is nothing to reserve, so the appended run is dropped and nothing replaces
+// it. This is the only case in which suppressing the run makes the file smaller.
+{
+	const { appended, cost } = await build(4, 64 * 1024, { extractDataFromPage: false });
+	check("extraction disabled: no element", appended.element, 0);
+	check("extraction disabled: cost", cost, -("-->".length + END_TAGS_LENGTH));
+}
+
+// the budget triggers relocation once the element no longer fits beside the terminator and the end
+// tags, so the boundary is exactly maxAppendedDataLength - 3 - 14
+{
+	const { appended } = await build(5, 64 * 1024, {});
+	const fits = appended.element + "-->".length + END_TAGS_LENGTH;
+	const atBoundary = await build(5, 64 * 1024, { maxAppendedDataLength: fits });
+	const belowBoundary = await build(5, 64 * 1024, { maxAppendedDataLength: fits - 1 });
+	check("an element that exactly fits the budget stays appended", atBoundary.appended.relocated, false);
+	check("one byte less of budget relocates it", belowBoundary.appended.relocated, true);
+}
+
+Deno.exit(failed ? 1 : 0);