single-file-core 1.5.127 → 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/core/util.js

@@ -63,6 +63,8 @@ const CONTENT_TYPE_EXTENSIONS = {
 	"font/collection": ".ttc"
 };
 const CONTENT_TYPE_OCTET_STREAM = "application/octet-stream";
+const TRANSPORT_STREAM_SYNC_BYTE = 71;
+const TRANSPORT_STREAM_PACKET_SIZE = 188;
 const CONTENT_TYPES_HTML = ["text/html", "application/xhtml+xml"];
 const EXPECTED_TYPES_MEDIA = ["font", "image", "video", "audio"];
 
@@ -295,11 +297,11 @@ function getInstance(utilOptions) {
 		} catch (error) {
 			// ignored
 		}
-		if (!contentType || (contentType == CONTENT_TYPE_OCTET_STREAM && options.asBinary)) {
-			contentType = guessMIMEType(options.expectedType, buffer);
-			if (!contentType) {
-				contentType = options.contentType ? options.contentType : options.asBinary ? CONTENT_TYPE_OCTET_STREAM : "";
-			}
+		const guessedContentType = guessMIMEType(options.expectedType, buffer);
+		if (guessedContentType) {
+			contentType = guessedContentType;
+		} else if (!contentType || (contentType == CONTENT_TYPE_OCTET_STREAM && options.asBinary)) {
+			contentType = options.contentType ? options.contentType : options.asBinary ? CONTENT_TYPE_OCTET_STREAM : "";
 		}
 		if (!charset && options.charset) {
 			charset = options.charset;
@@ -403,6 +405,24 @@ function guessMIMEType(expectedType, buffer) {
 		if (compareBytes([255, 255, 255], [255, 216, 255])) {
 			return "image/jpeg";
 		}
+		if (compareBytes([0, 0, 0, 0, 255, 255, 255, 255, 255, 255, 255, 255], [0, 0, 0, 0, 102, 116, 121, 112, 97, 118, 105, 102]) ||
+			compareBytes([0, 0, 0, 0, 255, 255, 255, 255, 255, 255, 255, 255], [0, 0, 0, 0, 102, 116, 121, 112, 97, 118, 105, 115])) {
+			return "image/avif";
+		}
+		if (compareBytes([0, 0, 0, 0, 255, 255, 255, 255, 255, 255, 255, 255], [0, 0, 0, 0, 102, 116, 121, 112, 104, 101, 105, 99]) ||
+			compareBytes([0, 0, 0, 0, 255, 255, 255, 255, 255, 255, 255, 255], [0, 0, 0, 0, 102, 116, 121, 112, 104, 101, 105, 120]) ||
+			compareBytes([0, 0, 0, 0, 255, 255, 255, 255, 255, 255, 255, 255], [0, 0, 0, 0, 102, 116, 121, 112, 104, 101, 118, 99]) ||
+			compareBytes([0, 0, 0, 0, 255, 255, 255, 255, 255, 255, 255, 255], [0, 0, 0, 0, 102, 116, 121, 112, 104, 101, 118, 120])) {
+			return "image/heic";
+		}
+		if (compareBytes([255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255], [0, 0, 0, 12, 74, 88, 76, 32, 13, 10, 135, 10]) ||
+			compareBytes([255, 255], [255, 10])) {
+			return "image/jxl";
+		}
+		if (compareBytes([255, 255, 255, 255], [73, 73, 42, 0]) ||
+			compareBytes([255, 255, 255, 255], [77, 77, 0, 42])) {
+			return "image/tiff";
+		}
 	}
 	if (expectedType == "font") {
 		if (compareBytes([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255],
@@ -444,7 +464,7 @@ function guessMIMEType(expectedType, buffer) {
 		if (compareBytes([0, 0, 0, 0, 255, 255, 255, 255, 255, 255], [0, 0, 0, 0, 102, 116, 121, 112, 51, 103])) {
 			return "video/3gpp";
 		}
-		if (compareBytes([255], [71])) {
+		if (isTransportStream()) {
 			return "video/mp2t";
 		}
 	}
@@ -475,6 +495,14 @@ function guessMIMEType(expectedType, buffer) {
 		}
 	}
 
+	function isTransportStream() {
+		const value = new Uint8Array(buffer);
+		return value.length > TRANSPORT_STREAM_PACKET_SIZE * 2 &&
+			value[0] == TRANSPORT_STREAM_SYNC_BYTE &&
+			value[TRANSPORT_STREAM_PACKET_SIZE] == TRANSPORT_STREAM_SYNC_BYTE &&
+			value[TRANSPORT_STREAM_PACKET_SIZE * 2] == TRANSPORT_STREAM_SYNC_BYTE;
+	}
+
 	function compareBytes(mask, pattern) {
 		let patternMatch = true, index = 0;
 		if (buffer.byteLength >= pattern.length) {

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,26 +1,26 @@
 {
-  "name": "single-file-core",
-  "version": "1.5.127",
-  "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/filename-max-length.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",
-    "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",
-    "bump-commit": "git commit -m \"bump up version\" package.json package-lock.json"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/gildas-lormeau/single-file-core.git"
-  },
-  "bugs": {
-    "url": "https://github.com/gildas-lormeau/single-file-core/issues"
-  },
-  "homepage": "https://github.com/gildas-lormeau/single-file-core#readme",
-  "devDependencies": {
-    "@eslint/js": "^9.39.5",
-    "eslint": "^10.9.1"
-  }
+	"name": "single-file-core",
+	"version": "1.5.129",
+	"description": "SingleFile Core",
+	"author": "Gildas Lormeau",
+	"license": "AGPL-3.0-or-later",
+	"scripts": {
+		"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",
+		"bump-commit": "git commit -m \"bump up version\" package.json package-lock.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gildas-lormeau/single-file-core.git"
+	},
+	"bugs": {
+		"url": "https://github.com/gildas-lormeau/single-file-core/issues"
+	},
+	"homepage": "https://github.com/gildas-lormeau/single-file-core#readme",
+	"devDependencies": {
+		"@eslint/js": "^9.39.5",
+		"eslint": "^10.9.1"
+	}
 }

package/processors/compression/compression-packager.js

@@ -32,7 +32,8 @@ import {
 } from "./../../vendor/zip/zip.js";
 import {
 	createArchive,
-	escapeHTML
+	escapeHTML,
+	PROCESS_OPTION_NAMES
 } from "./compression.js";
 
 const browser = globalThis.browser;
@@ -46,6 +47,13 @@ const TOC_STYLE = "body{font-family:system-ui,sans-serif;margin:2em auto;max-wid
 	"summary{cursor:pointer;font-weight:bold;margin:.5em 0}" +
 	"details{padding-left:1em}ul{margin:.25em 0;padding-left:1.5em}" +
 	"@media(prefers-color-scheme:dark){body{background-color:#111;color:#eee}a{color:#8ab4f8}a:visited{color:#c58af9}}";
+const ARCHIVE_EXCLUDED_OPTION_NAMES = [
+	"createRootDirectory",
+	"disableCompression",
+	"insertTextBody",
+	"password",
+	"url"
+];
 const COMMENT_HEADER = "Page saved with SingleFile";
 const SYMLINK_UNIX_MODE = 0o120777;
 
@@ -59,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
@@ -80,23 +88,16 @@ async function createPagesArchive(pages, options) {
 	};
 	const archiveOptions = {
 		url: pages[0].url,
-		multiPageArchive: true,
-		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
+		multiPageArchive: true
 	};
+	PROCESS_OPTION_NAMES
+		.filter(name => !ARCHIVE_EXCLUDED_OPTION_NAMES.includes(name) && !(name in archiveOptions))
+		.forEach(name => archiveOptions[name] = options[name]);
 	const writtenEntries = options.dedupPages ? new Map() : undefined;
 	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;
@@ -162,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/processors/compression/compression-router.js

@@ -202,7 +202,7 @@ async function router(content, { extract, display }) {
 	function parseRoute() {
 		const hash = location.hash;
 		const routed = !hash || hash.startsWith(ROUTE_PREFIX);
-		let path = pages[0].path;
+		let path = routed && tocEntry ? TOC_ROUTE : pages[0].path;
 		let fragment;
 		if (routed && hash) {
 			({ path, fragment } = parseRouteHash(hash));

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
@@ -34,18 +41,24 @@ any check failed.
 | `css-property-filter.js` | That the declaration filter keeps a property css-tree's dictionary does not know (`stop-color`, `flood-opacity`, anything newer than the pinned build) and still drops a genuinely invalid value. |
 | `adopted-stylesheets-hook.js` | That the page-world hook answers the adopted-stylesheets request for a CLOSED shadow root, which its host does not expose. |
 | `inlined-functions.js` | That a function serialized into a self-extracting archive names nothing outside itself. An import survives bundling and still reads correctly, and the archive then throws a bare `ReferenceError` and renders nothing. |
-| `pages-archive.js` | That `createPagesArchive` packs several pages into one archive correctly: the first page at the root and the others in folders, the manifest, the symlink a deduplicated entry leaves behind, and the escaping of crawled titles in both tables of contents. |
+| `pages-archive.js` | That `createPagesArchive` packs several pages into one archive correctly: the first page at the root and the others in folders, the manifest, the symlink a deduplicated entry leaves behind, and the escaping of crawled titles in both tables of contents. Also that the options reaching the archive writer are derived from `PROCESS_OPTION_NAMES` rather than hand-listed — a hand copy dropped `maxAppendedDataLength` for months — and that `password` stays out of that derivation, since forwarding it would make the writer withhold the prologue's title as if the archive were encrypted while the table of contents and every entry comment still rode in that same cleartext prologue. |
+| `pages-router.js` | That the router opens a multi-page archive on the page a reader expects: the table of contents when the archive stores one, the first page when it does not, and the page a route in the hash names whatever else is stored. The router is inlined into the archive as source text and only ever ran inside a saved page, so nothing drove it before; the table of contents shipped stored, routable and unreachable. |
+| `content-type-sniffing.js` | That a magic-byte match beats the `Content-Type` header, and that the header survives when nothing matches. science.org serves its woff2 files as `text/plain`, which used to be trusted, so the fonts were embedded as `data:text/plain` and the SFZ writer deflated a file that is already Brotli-compressed. Two cases guard the rules themselves rather than the outcome: a video whose first byte is `G` must not be relabelled `video/mp2t`, and the generic `mif1` HEIF brand must identify nothing, because an AVIF can carry it and calling it HEIC would name a format no browser decodes. |
 | `entry-compression.js` | That an entry is deflated or stored on the content type the server sent, not on the extension alone — a module served as `text/javascript` from a `.ts` URL used to go in uncompressed — and that an unrecognized `application/octet-stream` still stays stored. |
 | `filename-max-length.js` | That `formatFilename` counts the ellipsis as well as the extension in the budget it truncates to, so a filename at `filenameMaxLength` stays at it, and that a limit shorter than the extension does not reach `Blob.slice` with a negative start. |
 | `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/content-type-sniffing.js

@@ -0,0 +1,83 @@
+// `core/util.js` used to trust any Content-Type the server sent and sniff the bytes only when the
+// header was missing or `application/octet-stream`. science.org serves its woff2 files as
+// `text/plain;charset=UTF-8` — 12 of them — and every one was embedded as `data:text/plain`, which
+// costs twice: a browser with no `format()` hint in the `@font-face` rule has nothing left to
+// identify the font by, and the SFZ writer deflates a file that is already Brotli-compressed
+// because it decides compression from the content type.
+//
+// The rule now: a magic-byte match wins over the header, and the header is kept only when nothing
+// matches. That raises the bar for the sniffer's own rules, which is why `video/mp2t` no longer
+// matches on a single `0x47` byte — as a last resort behind a missing header that was tolerable,
+// as an override of a correct header it would relabel any video whose first byte is `G`. It now
+// wants the sync byte at the 188-byte packet stride, and the case below is the regression guard.
+/* global Response */
+
+import "./dom-stub.js";
+// util.js pulls in the page-world hooks, which register a document listener as they are evaluated.
+// None of it is exercised here; the stubs exist so that importing util.js is possible at all
+globalThis.window = globalThis.window || {};
+globalThis.document = globalThis.document || {};
+globalThis.Document = globalThis.Document || class { };
+globalThis.MutationObserver = globalThis.MutationObserver || class {
+	observe() { }
+};
+const { getInstance } = await import("./../../core/util.js");
+
+const FONT_URL = "https://example.com/font";
+const WOFF2 = bytes([0x77, 0x4F, 0x46, 0x32], 64);
+const PNG = bytes([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A], 64);
+const AVIF = bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x61, 0x76, 0x69, 0x66], 64);
+const WEBP2 = bytes([0x77, 0x70, 0x32, 0x20], 64);
+const HEIF_MIF1 = bytes([0, 0, 0, 0x20, 0x66, 0x74, 0x79, 0x70, 0x6D, 0x69, 0x66, 0x31], 64);
+const NOT_A_TRANSPORT_STREAM = bytes([0x47, 0x53, 0x54, 0x00], 512);
+
+let failed = false;
+
+// [label, bytes, expectedType, the Content-Type the server sent, the type that must reach the data URI]
+const CASES = [
+	["a woff2 served as text/plain is embedded as font/woff2", WOFF2, "font", "text/plain;charset=UTF-8", "font/woff2"],
+	["a woff2 served as font/woff2 is unchanged", WOFF2, "font", "font/woff2", "font/woff2"],
+	["a woff2 served with no type at all is embedded as font/woff2", WOFF2, "font", undefined, "font/woff2"],
+	["a png served as text/plain is embedded as image/png", PNG, "image", "text/plain", "image/png"],
+	["an avif served as application/octet-stream is embedded as image/avif", AVIF, "image", "application/octet-stream", "image/avif"],
+	// "mif1" is the generic HEIF brand and an AVIF may carry it too, so it identifies nothing on
+	// its own: claiming HEIC here would relabel an AVIF as a format no browser decodes
+	["an ambiguous HEIF brand keeps the type the server sent", HEIF_MIF1, "image", "image/avif", "image/avif"],
+	// nothing matches these bytes, so the header is all there is and it has to survive
+	["a format the sniffer does not know keeps the type the server sent", WEBP2, "image", "image/webp2", "image/webp2"],
+	["a format the sniffer does not know and no type falls back to octet-stream", WEBP2, "image", undefined, "application/octet-stream"],
+	// the byte is 0x47, the packet stride is not, so this is not a transport stream
+	["a video starting with G is not relabelled as mp2t", NOT_A_TRANSPORT_STREAM, "video", "video/quicktime", "video/quicktime"]
+];
+
+for (const [label, data, expectedType, sentContentType, expectedContentType] of CASES) {
+	const { data: dataURI } = await fetchContent(data, expectedType, sentContentType);
+	check(label, readDataURIType(dataURI), expectedContentType);
+}
+
+console.log(failed ? "\nsome checks FAILED" : "\nall checks passed");
+Deno.exit(failed ? 1 : 0);
+
+function fetchContent(data, expectedType, contentType) {
+	const util = getInstance({
+		fetch: async () => new Response(data, { headers: contentType ? { "content-type": contentType } : {} })
+	});
+	return util.getContent(FONT_URL, { asBinary: true, inline: true, expectedType });
+}
+
+function readDataURIType(dataURI) {
+	const indexSeparator = dataURI.indexOf(";");
+	return dataURI.substring("data:".length, indexSeparator == -1 ? dataURI.indexOf(",") : indexSeparator);
+}
+
+function bytes(signature, length) {
+	const value = new Uint8Array(length);
+	value.set(signature);
+	return value;
+}
+
+function check(label, actual, expected) {
+	const ok = actual === expected;
+	console.log(`${ok ? "PASS" : "FAIL"} ${label}: ${actual}${ok ? "" : " (expected " + expected + ")"}`);
+	failed ||= !ok;
+}

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

@@ -4,16 +4,18 @@
 //
 // 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.
 //   - the titles written into the table of contents are CRAWLED, so they are attacker-controlled
 //     text going into an href attribute and into element content. Both escapers are checked here.
 import "./dom-stub.js";
-import { makePageData, makeOptions, runProcess } from "./common.js";
+import { makePageData, makeOptions, runProcess, freezeDate } from "./common.js";
 import { createPagesArchive } from "../../processors/compression/compression-packager.js";
 import { ZipReader, ZipWriter, BlobReader, TextReader, TextWriter, Uint8ArrayWriter } from "../../vendor/zip/zip.js";
 
@@ -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
 {
@@ -175,6 +208,33 @@ const pages = [
 		new TextDecoder("windows-1252").decode(await createPagesArchive(pages, packagerOptions())).includes("<nav><ul>"), false);
 }
 
+// the options handed to the archive writer are DERIVED from PROCESS_OPTION_NAMES, not hand-listed.
+// The hand copy carried eleven names and silently dropped maxAppendedDataLength, so
+// --max-appended-data-length did nothing on any multi-page save and nothing failed for months.
+// A one-byte budget has to reach the writer, where it is indistinguishable from refusing to append
+{
+	const unfreeze = freezeDate();
+	try {
+		const budgeted = await createPagesArchive(pages, packagerOptions({ maxAppendedDataLength: 1 }));
+		const prevented = await createPagesArchive(pages, packagerOptions({ preventAppendedData: true }));
+		const unbudgeted = await createPagesArchive(pages, packagerOptions());
+		check("a one-byte appended-data budget reaches the archive writer", equalData(budgeted, prevented), true);
+		check("and appending is what the writer does without one", equalData(unbudgeted, prevented), false);
+	} finally {
+		unfreeze();
+	}
+}
+
+// `password` is the one name the derivation must NOT forward. An encrypted multi-page archive
+// cannot be written yet, and forwarding the password would half-ship it: the writer would start
+// withholding the prologue's title as if the archive were encrypted, while the table of contents
+// and every entry comment — each one a resource URL — kept riding in that same cleartext prologue
+{
+	const prologue = new TextDecoder("windows-1252").decode(await createPagesArchive(pages, packagerOptions({ password: "secret" })));
+	check("a password is not forwarded to the archive writer",
+		prologue.includes("<title>Intro &#38; &#34;start&#34; &#60;b&#62;</title>"), true);
+}
+
 console.log(failed ? "\nsome checks FAILED" : "\nall checks passed");
 Deno.exit(failed ? 1 : 0);
 

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

@@ -0,0 +1,143 @@
+// The router picks the page a multi-page archive opens on. Nothing drove it until this file: the
+// function is inlined into the archive as source text, so it only ever ran inside a saved page,
+// and the suites around it checked what the packager WROTE rather than what a reader would see.
+// That is how the table of contents shipped unreachable. It was stored, the route existed, and
+// no link and no landing rule pointed at it, so --crawl-save-archive-toc looked like it did
+// nothing at all.
+//
+// The rule this file pins: an archive that stores a table of contents opens on it, and one that
+// does not opens on the first page. Two cases guard the edges of that rule. A route in the hash
+// names a page explicitly and has to win over the landing rule, or every deep link into an
+// archive would land on the table of contents instead. A hash that is NOT a route is a plain
+// fragment, and the only page it can mean is the first one, which is where the archive used to
+// land before the fragment was ever read.
+import "./dom-stub.js";
+import { makePageData, makeOptions, runProcess } from "./common.js";
+import { createPagesArchive } from "../../processors/compression/compression-packager.js";
+import { router } from "../../processors/compression/compression-router.js";
+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" }),
+	await makePage(2, { url: "https://example.com/docs/api/reference.html", title: "Reference" })
+];
+const withTOC = await createPagesArchive(pages, packagerOptions({ tocPage: true }));
+const withoutTOC = await createPagesArchive(pages, packagerOptions());
+
+{
+	const content = await open(withTOC);
+	check("an archive holding a table of contents opens on it", content.includes("<h1>Table of contents</h1>"), true);
+}
+
+{
+	const content = await open(withoutTOC);
+	check("an archive holding no table of contents opens on the first page", content, "page at \"\"");
+}
+
+{
+	const content = await open(withTOC, "#sfz/pages/2/");
+	check("a route in the hash names the page to open", content, "page at \"pages/2/\"");
+}
+
+// a bare fragment is what a hand-written link into the saved page looks like. The router scrolls
+// to it after rendering, and the table of contents is not the document it belongs to
+{
+	const content = await open(withTOC, "#introduction");
+	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);
+
+// the router reads its world out of globalThis and renders through the two functions it is given,
+// so a stub of each is enough to see the page it chose. Only what the first render touches is
+// stubbed here; navigation, scroll restoration and link marking read more of the DOM than this
+async function open(bytes, hash = "") {
+	let displayed;
+	installEnvironment(hash);
+	await router(new Blob([bytes]), {
+		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;
+}
+
+function installEnvironment(hash) {
+	// the router asks for web workers, which the archive serves from its own extension URL. There
+	// is no such URL here, so the request is answered with the synchronous codec instead
+	globalThis.zip = { ...zip, configure: options => zip.configure({ ...options, useWebWorkers: false }) };
+	globalThis.document = {
+		head: { appendChild() { } },
+		styleSheets: [],
+		createElement: () => ({ setAttribute() { }, remove() { } }),
+		querySelectorAll: () => [],
+		querySelector: () => null,
+		getElementById: () => null
+	};
+	globalThis.history = {
+		state: null,
+		scrollRestoration: "auto",
+		replaceState(state) {
+			this.state = state;
+		}
+	};
+	// Deno defines location as a getter that throws without --location, so it is replaced rather
+	// than assigned
+	Object.defineProperty(globalThis, "location", {
+		value: { href: ARCHIVE_URL + hash, hash },
+		configurable: true,
+		writable: true
+	});
+}
+
+async function makePage(seed, { url, title }) {
+	const pageData = makePageData(seed, 2 * 1024);
+	pageData.title = title;
+	const { bytes } = await runProcess(pageData, makeOptions({ url }));
+	return { url, title, getData: async () => bytes };
+}
+
+function packagerOptions(overrides = {}) {
+	return {
+		selfExtractingArchive: true,
+		extractDataFromPage: true,
+		zipScript: "/* zip script stub */",
+		...overrides
+	};
+}
+
+function check(label, actual, expected) {
+	const ok = actual === expected;
+	console.log(`${ok ? "PASS" : "FAIL"} ${label}: ${actual}${ok ? "" : " (expected " + expected + ")"}`);
+	failed ||= !ok;
+}

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);