single-file-core 1.5.109 → 1.5.111

package/doc/singlefile-archive.md

@@ -314,9 +314,9 @@ default wrapper is an HTML comment, and the HTML standard defines exactly which
 character sequences terminate one (`-->`, and the recovery form `--!>`); the writer
 MUST select a wrapper only after checking the bytes it must hide against that
 wrapper's patterns (the exact rules differ between the ZIP region and the PDF and
-PNG payloads, §5.1), so hiding relies on normative parsing behavior. One
-case weakens the wrapper itself: when no wrapper fits a PDF or PNG payload the
-payload is emitted bare (§5.1). Some binary content always sits *outside* a
+PNG payloads, §5.1), so hiding relies on normative parsing behavior. When no
+wrapper fits a PDF or PNG payload, the face is dropped rather than emitted bare
+(§5.1). Some binary content always sits *outside* a
 wrapper: in the PNG variants, the signature, IHDR and chunk framing bytes that
 precede the root element start tag decode to a short run of text that HTML error recovery
 places in the (hidden) body. The backstop for all these cases is the prologue: it
@@ -678,7 +678,8 @@ this ladder, in order:
 | 5 | `<noembed>` | raw text | `</noembed` + delimiter |
 | 6 | `<iframe>` | raw text | `</iframe` + delimiter |
 | 7 | `<xmp>` | raw text | `</xmp` + delimiter |
-| 8 | `<plaintext>` | everything to end of file | nothing — the element cannot be closed |
+| 8 | `<svg><![CDATA[` … `]]></svg>` | CDATA section | `]]>` |
+| 9 | `<plaintext>` | everything to end of file | nothing — the element cannot be closed |
 
 The terminators are written lower case above, but HTML matches end tag names ASCII
 case-insensitively: `</XMP>` and `</Script ` close their elements just as `</xmp>` and
@@ -711,6 +712,31 @@ or stops reading `<xmp>`, changes only which archives end up in a local search i
 every rung still hides its content from the HTML parser, and a writer whose ladder is
 ordered differently produces files that are just as correct.
 
+The CDATA rung sits where it does for the same reason, and it is the only rung whose
+placement understates it. A CDATA section is a CDATA section only in foreign content,
+which is what the `<svg>` element is there for — in HTML content `<![CDATA[` is a
+bogus comment, and the payload would be markup. Given the `<svg>`, the construct is the
+strongest on the ladder: `]]>` is the whole of its terminator, and it is a sequence real
+payloads carry far less often than `-->` or `</script>`. That matters most for the one
+thing the ladder cannot otherwise avoid — an archive nested inside another as a face
+carries the terminator of every rung it climbed, so each rung is spent once and only
+once (§5.1, ladder depth). A writer MUST place the identifier on the `<svg>` element and
+not on the markup declaration, which takes no attributes: `<svg id=sfz-data><![CDATA[`.
+
+Two properties of the CDATA section state are worth stating because a writer is tempted
+to guard against both and needs neither. Sections do not nest, so a `<![CDATA[` inside
+the payload is text like any other — the start-pattern test on this rung is the same
+conservatism the raw-text rungs get, not a necessity. And trailing brackets are safe: a
+payload ending `]]` against the writer's `]]>` produces `]]]]>`, and the tokenizer's
+CDATA section end state emits the payload's own two brackets before closing, so the
+recovered bytes are exact.
+
+Verified in Blink, Gecko and WebKit, and against html5lib: a universal-mode archive on
+this rung recovers from the parsed document byte for byte, with the checksum of §4.5
+matching, indistinguishably from the same archive on the comment rung. The same probe
+covered a payload holding every byte value, every rung's patterns, and the near-misses
+`]]x>`, `] ]>`, `]>` and `]]`, in both the prologue position and mid-document.
+
 Two things about the ladder *are* required. Whatever order a writer gives the seven
 closable rungs, it MUST apply the selection test below to every rung it considers, and
 MUST keep `<plaintext>` available as the rung of last resort: §6.2's termination
@@ -730,14 +756,15 @@ what differs is how far the ladder goes:
 - **The ZIP region** rejects a rung whose *end* pattern the payload contains, and also
   a rung whose *start* pattern it contains. A rung's start pattern is the tag's opening
   delimiter and name, without attributes: `<!--` for the comment, then `<script`,
-  `<style`, `<noframes`, `<noembed`, `<iframe`, `<xmp` for the elements.
+  `<style`, `<noframes`, `<noembed`, `<iframe`, `<xmp` for the elements, and
+  `<![CDATA[` for the CDATA rung.
 
   `<plaintext>` is exempt from **both** tests. It has no terminator to occur and no
   tokenizer states to escape into — a `<plaintext` inside a `<plaintext>` is inert
   text like everything else — so no payload can defeat it. §6.2's termination argument
   rests on that exemption.
 
-  The other seven are all tested, and a writer MUST test all seven rather than the one
+  The other eight are all tested, and a writer MUST test all eight rather than the one
   that needs it. The `<script>` rung needs it
   to be correct at all, because script data has escape states no other rung has: `<!--`
   in script data enters *script data escaped*, and a `<script` after that enters *script
@@ -746,7 +773,8 @@ what differs is how far the ladder goes:
   and the wrapper then swallows its own end tag, the extra-data element and the rest of
   the document. On the other six the start test is genuine conservatism: a nested `<!--`
   is a parse error inside a comment but does not close it, and the raw-text rungs hold a
-  flat run of characters with no states at all. The rule is uniform deliberately: the
+  flat run of characters with no states at all, while CDATA sections do not nest. The
+  rule is uniform deliberately: the
   exemption would save one pattern match per rung on bytes already in memory, at the
   cost of a special case an implementer has to remember correctly about the single rung
   where forgetting it destroys the document. An earlier draft offered exactly that
@@ -758,8 +786,12 @@ what differs is how far the ladder goes:
   the rest of the document, title, bootstrap and extra-data element included — but the
   `<plaintext>` rung is excluded from their ladder: those payloads sit in the middle
   of the file, so a wrapper that can never close is not an option. When no rung fits,
-  the payload is written bare, with no wrapper at all; it then reaches the parser as
-  text, and the blank-page backstop of §4.1 keeps it invisible.
+  the writer MUST omit the face and emit the archive without it. It MUST NOT write the
+  payload bare. Bare renders acceptably — the blank-page backstop of §4.1 keeps it
+  invisible — but the payload's markup joins the document, and a payload that is itself
+  a SingleFile archive then contributes an `sfz-data` node ahead of the file's own. A
+  reader looking for one node finds two, takes the first, and returns an archive that
+  passes every check it has (§7.4). A face is a convenience; the archive is not.
 
 The comment rung has one restriction more than a terminator. HTML forbids comment text
 that *starts* with `>` or `->`, and the tokenizer enforces it: it closes the comment
@@ -767,9 +799,14 @@ right there, spilling the payload into the parser. What starts the comment diffe
 payload — the ZIP region begins with the identifier, the PDF face with a local file
 header or `%PDF-` — but the PNG face begins with the CRC of the chunk carrying the
 start tag, four bytes that are only settled once the tag is chosen, and one in 256 of
-them is `>`. A writer using a comment there MUST compute that checksum and take the
-next rung when it opens with `>` or `->`; the next rung is an element, which has no
-such restriction, so the test cannot cascade. HTML also forbids comment text ending
+them is `>`. A writer using a comment there MUST compute that checksum and leave the
+comment rung when it opens with `>` or `->`. It MUST leave it by *resuming the rung
+search* below it, not by taking the rung that follows: the checksum says only that the
+comment is unusable, and which rung is usable remains the payload's to say. The test
+itself cannot cascade — only the comment rung carries the restriction, and every rung
+below it is an element — but the payload's terminators still apply, and a payload
+holding `</script>` sends a writer that stepped rather than searched onto the one rung
+it is guaranteed to close. HTML also forbids comment text ending
 with `<!-`, which the terminator check covers by testing that pattern anchored at the
 payload's end.
 
@@ -785,6 +822,18 @@ Verified on a build forced onto this rung with a screenshot embedded: the file e
 `49 45 4e 44 ae 42 60 82`, decodes as a PNG, and its archive extracts from the parsed
 page. The termination argument of §6.2 therefore holds for the faced variants too.
 
+The ladder has a depth, and nesting reaches it. An archive used as the PDF or PNG
+payload of another one carries the terminator of every rung its own faces climbed
+through, and `-->`, `</script>` and `</style>` besides, which every prologue emits.
+Each level of nesting therefore burns exactly one rung, and the eight a face may use
+run out at the sixth: the reference writer selects `<!--`, then `<noframes>`,
+`<noembed>`, `<iframe>`, `<xmp>`, the CDATA rung, and then has nothing left. No ladder
+of fixed length avoids this; adding a rung moves the limit by one level, which is the
+limit of what the CDATA rung buys here — its value is that real payloads rarely hold
+`]]>`, not that it makes nesting unbounded. That is why the paragraph
+above states a MUST rather than a quality-of-implementation preference — exhaustion is
+reachable by construction, not only by a payload built to provoke it.
+
 The check MUST be made against the payload's final bytes, for every payload the
 writer hides and in every variant that hides one. Every rejection restarts the build
 (§6): the wrapper choice changes the bytes preceding the archive, so the archive must
@@ -909,8 +958,8 @@ inverse mapping the extractor applies is, for the declared charset:
 3. **U+FFFD → 0x00.** No byte decodes to U+FFFD under a qualifying encoding (§2.1), so
    the replacement character can only have come from a NUL byte. This holds because
    the payload is inside a wrapper: in every tokenizer state the ladder of §5.1
-   produces — comment, raw text, script data, plaintext — the parser replaces NUL with
-   U+FFFD.
+   produces — comment, raw text, script data, CDATA section, plaintext — the parser
+   replaces NUL with U+FFFD.
 4. **Newlines from the payload.** The parser normalizes CR and CR LF to LF, so the
    original byte sequence is unrecoverable from the text alone; each newline consumes
    the next 2-bit code (0 = LF, 1 = CR, 2 = CR LF).
@@ -1236,6 +1285,7 @@ only if it affects the bytes the page is built from:
 | A `tEXt` chunk CRC does not match, or a chunk holds bytes PNG does not permit (§4.4) | Irrelevant to extraction; a reader of the archive MAY ignore both |
 | `page.pdf` is present but its data does not begin with `%PDF-` | Not an error. The entry is data like any other |
 | `index.html` is present without `manifest.json` | **MUST** still extract (§7.1) |
+| More than one node carries the `sfz-data` identifier | **MUST NOT** extract either silently. A conforming writer emits one (§5.1), so a second is a payload that escaped its wrapper — most often a nested archive written by a writer that emitted a face bare. Both candidates extract cleanly and check out, and the checksums say nothing about which one the file was built around |
 | The recovered region (universal mode) disagrees with the same bytes read directly, in the EOCD's two comment-length bytes only | Expected, not an error. A recovered region always declares a zero-length comment (§4.5), so it differs here from any archive written in the declared form (§4.2). Compare the two only up to those bytes |
 | The recovered region (universal mode) disagrees with the same bytes read directly, anywhere else | The file is not well-formed, whichever side is at fault, and a reader that has both MUST NOT silently merge them or pick per entry. Prefer the direct read — it is the writer's own output, where the recovered region is a reconstruction of it — and surface the disagreement rather than displaying either as intact |
 
@@ -1432,6 +1482,9 @@ predicts.
 | August 2026 | Core 1.5.108: the recovery payload stops two bytes short of the End Of Central Directory record, excluding its comment-length field (§1.3), which lets universal-mode archives declare their appended data as the archive comment — a writer option, for `java.util.zip` and the readers that reject undeclared trailing bytes (§4.2) |
 | August 2026 | Core 1.5.108: the PDF and PNG faces test a wrapper rung's start pattern as well as its end pattern, closing the same script-data escape hole the ZIP region was already guarded against — a face payload holding `<!--` and then `<script` took the `<script type=sfz-data>` rung and swallowed the rest of the document (§5.1) |
 | August 2026 | Core 1.5.108: the retry loop discards a relocation reservation at most once per build, so a payload sitting on the appended-data boundary cannot oscillate between the two placements forever (§6.2) |
+| August 2026 | Core 1.5.110: a PDF or PNG face whose payload names every rung is dropped instead of written bare (§5.1). Found by nesting an archive inside itself as both faces: the fifth level exhausts the ladder, and readers then extracted the fourth level's archive — checksums intact, no way to tell (§7.4) |
+| August 2026 | Core 1.5.110: a PNG face leaving the comment rung on its checksum resumes the rung search instead of taking the next rung untested (§5.1). Taking it put a payload holding `</script>` on the script rung, where its own bytes closed the wrapper 93 bytes in and left the image data, the chunk framing and the whole ZIP region to the parser |
+| August 2026 | Core 1.5.110: `<svg><![CDATA[` joins the ladder above `<plaintext>` (§5.1) — the one rung whose terminator, `]]>`, real payloads rarely carry. It gives a payload naming every element rung somewhere to go that does not cost the appended-data placement, and moves the self-nesting limit from the fifth level to the sixth |
 
 This document was itself revised in August 2026, against core 1.5.108, after several
 independent reviews. One of them was a reader built from this specification alone, with

package/modules/css-fonts-minifier.js

@@ -41,7 +41,11 @@ const REGEXP_COMMA = /\s*,\s*/;
 const REGEXP_DASH = /-/;
 const REGEXP_QUESTION_MARK = /\?/g;
 const REGEXP_STARTS_U_PLUS = /^U\+/i;
+const REGEXP_CUSTOM_PROPERTY = /var\((--[^),]*)\)/g;
 const VALID_FONT_STYLES = [/^normal$/, /^italic$/, /^oblique$/, /^oblique\s+/];
+// a family name kept when the "font" shorthand cannot be read: it resolves to nothing, so it
+// survives the substitution below and marks the fonts as undetermined instead of unused
+const UNRESOLVED_CUSTOM_PROPERTY_FAMILY = "var(--)";
 
 export {
 	process
@@ -268,23 +272,36 @@ function getFontFamilyNames(declarations, options) {
 	}
 	const font = declarations.children.filter(node => node.property == "font").tail;
 	if (font && font.data && font.data.value) {
+		const fontValue = cssTree.generate(font.data.value);
 		try {
 			let value = font.data.value;
-			let fontFamilyName = cssTree.generate(value);
-			const matchedVar = fontFamilyName.match(/^var\((--.*)\)$/);
-			if (matchedVar && matchedVar[1]) {
-				value = cssTree.parse(globalThis.getComputedStyle(options.doc.body).getPropertyValue(matchedVar[1]), { context: "value" });
+			const resolvedFontValue = resolveCustomProperties(fontValue, options);
+			if (resolvedFontValue != fontValue) {
+				value = cssTree.parse(resolvedFontValue, { context: "value" });
 			}
 			const parsedFont = fontPropertyParser.parse(value);
 			parsedFont.family.forEach(familyName => fontFamilyNames.push(helper.normalizeFontFamily(familyName)));
 			// eslint-disable-next-line no-unused-vars
 		} catch (error) {
-			// ignored				
+			// the shorthand is unreadable, and dropping it here would count the fonts it names as
+			// unused: a custom property left in it means the families cannot be determined at all
+			if (fontValue.includes("var(")) {
+				fontFamilyNames.push(UNRESOLVED_CUSTOM_PROPERTY_FAMILY);
+			}
 		}
 	}
 	return fontFamilyNames;
 }
 
+function resolveCustomProperties(value, options) {
+	if (globalThis.getComputedStyle && options.doc) {
+		const computedStyle = globalThis.getComputedStyle(options.doc.body);
+		return value.replace(REGEXP_CUSTOM_PROPERTY, (property, name) => computedStyle.getPropertyValue(name) || property);
+	} else {
+		return value;
+	}
+}
+
 function parseFamilyNames(fontFamilyNameTokenData, fontFamilyNames) {
 	let nextToken = fontFamilyNameTokenData.children.head;
 	while (nextToken) {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "single-file-core",
-  "version": "1.5.109",
+  "version": "1.5.111",
   "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",
+    "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",
     "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

@@ -83,6 +83,11 @@ async function createPagesArchive(pages, options) {
 		selfExtractingArchive: options.selfExtractingArchive,
 		extractDataFromPage: options.extractDataFromPage,
 		preventAppendedData: options.preventAppendedData,
+		declareAppendedData: options.declareAppendedData,
+		// the faces belong to the archive and are supplied by the caller: one rendered from a
+		// single page would misrepresent every other page, so nothing is generated here
+		embeddedPdf: options.embeddedPdf,
+		embeddedImage: options.embeddedImage,
 		includeBOM: options.includeBOM,
 		insertMetaCSP: options.insertMetaCSP,
 		insertCanonicalLink: options.insertCanonicalLink,

package/processors/compression/compression.js

@@ -53,6 +53,11 @@ const SCRIPT_PATH = "/lib/single-file-zip.min.js";
 // they drop a comment: macOS Spotlight indexes the content of every other rung, and textutil
 // also reads the last two. Neither is applied nor executed, the type is neither CSS nor
 // JavaScript. <plaintext> stays last, it is the only rung that cannot be closed
+// the CDATA section sits second to last, and it is the one rung a payload is unlikely to hold
+// the terminator of: every other rung ends on a sequence that real documents carry, which is
+// also why each level of self-nesting burns one. It is low in the ladder only because text
+// extractors read its content; nothing about the parse is weaker. A CDATA section is only a
+// CDATA section in foreign content, hence the <svg> element around it
 const EXTRA_DATA_TAGS = [
 	["<script type=sfz-data>", "</script>"],
 	["<style type=sfz-data>", "</style>"],
@@ -60,6 +65,7 @@ const EXTRA_DATA_TAGS = [
 	["<noembed>", "</noembed>"],
 	["<iframe>", "</iframe>"],
 	["<xmp>", "</xmp>"],
+	["<svg><![CDATA[", "]]></svg>"],
 	["<plaintext>", "</plaintext>"]
 ];
 const EMBEDDED_DATA_TAGS = [
@@ -76,6 +82,11 @@ const EXTRA_DATA_REGEXPS = [
 	[/<noembed/i, /<\/noembed[\t\n\f\r />]/i],
 	[/<iframe/i, /<\/iframe[\t\n\f\r />]/i],
 	[/<xmp/i, /<\/xmp[\t\n\f\r />]/i],
+	// a CDATA section ends on "]]>" and nothing else, so the terminator is the whole test; the
+	// start pattern is the same conservatism the raw text rungs get, since a nested "<![CDATA["
+	// is text like any other. Trailing brackets are safe: a payload ending "]]" against the
+	// writer's "]]>" gives "]]]]>", and the tokenizer emits the payload's own two before closing
+	[/<!\[CDATA\[/i, /\]\]>/],
 	[/<plaintext/i, /<\/plaintext[\t\n\f\r />]/i]
 ];
 // a comment must also not end with "<!-", the last of the restrictions HTML puts on comment
@@ -102,6 +113,7 @@ const MAX_APPENDED_DATA_LENGTH = 65535;
 const PDF_ENTRY_FILENAME = "page.pdf";
 const PDF_HEADER_MAX_OFFSET = 1024;
 const MINIMAL_DOCTYPE = "<!DOCTYPE html>";
+const UNHIDDEN_FACE_WARNING_MESSAGE = "SingleFile: the archive was written without a face, its data names every wrapper tag:";
 const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
 const CENTRAL_FILE_HEADER_SIGNATURE = 0x02014b50;
 const END_OF_CENTRAL_DIR_SIGNATURE = 0x06054b50;
@@ -110,9 +122,34 @@ const ZIP64_END_OF_CENTRAL_DIR_LOCATOR_SIGNATURE = 0x07064b50;
 
 const browser = globalThis.browser;
 
+// the options process() accepts from its caller. single-file.js builds its argument from this
+// list instead of a literal, because an option added here and forgotten there is undefined at
+// every call site and the feature silently does nothing: that is how declareAppendedData and
+// includeBOM both shipped inert. Options the module sets on itself between passes, and options
+// the packager supplies, are deliberately absent
+const PROCESS_OPTION_NAMES = [
+	"createRootDirectory",
+	"declareAppendedData",
+	"disableCompression",
+	"embeddedImage",
+	"embeddedPdf",
+	"extractDataFromPage",
+	"includeBOM",
+	"insertCanonicalLink",
+	"insertMetaCSP",
+	"insertMetaNoIndex",
+	"insertTextBody",
+	"password",
+	"preventAppendedData",
+	"selfExtractingArchive",
+	"url",
+	"zipScript"
+];
+
 export {
 	process,
-	createArchive
+	createArchive,
+	PROCESS_OPTION_NAMES
 };
 
 async function process(pageData, options, lastModDate = new Date()) {
@@ -136,32 +173,29 @@ async function createArchive(pageData, options, script, writeEntries, lastModDat
 	let extraDataOffset, extraData, embeddedImageDataOffset, endTag, pdfEntry;
 	if (options.embeddedImage) {
 		options.embeddedImage = new Uint8Array(options.embeddedImage);
-		const embeddedImageData = options.embeddedImage.slice(PNG_SIGNATURE_LENGTH + PNG_IHDR_LENGTH, options.embeddedImage.length - PNG_IEND_LENGTH);
+	}
+	// the whole chunk is built before the first byte of the image is written, because building it
+	// is what settles the rung, and the search can end with no rung at all: the image is then left
+	// out altogether rather than written unwrapped
+	let imageChunk;
+	if (options.embeddedImage && options.selfExtractingArchive) {
+		imageChunk = getImageHTMLChunk(pageData, options, lastModDate);
+		if (!imageChunk) {
+			dropUnhiddenFace(options, "embeddedImage");
+		}
+	}
+	if (options.embeddedImage) {
+		const embeddedImageData = getEmbeddedImageData(options.embeddedImage);
 		await writeData(zipDataWriter.writable, options.embeddedImage.slice(0, PNG_SIGNATURE_LENGTH + PNG_IHDR_LENGTH));
 		if (options.selfExtractingArchive) {
-			const embeddedImageText = TEXT_DECODER.decode(embeddedImageData);
-			let tagIndex = findEmbeddedDataTagIndex(embeddedImageText);
-			let startTag, startHTMLData, htmlData, htmlDataCRC, abruptComment;
-			do {
-				[startTag, endTag] = tagIndex == -1 ? ["", ""] : EMBEDDED_DATA_TAGS[tagIndex];
-				startHTMLData = getStartHTMLArray(pageData, options, lastModDate, startTag);
-				htmlData = new Uint8Array([...getLength(startHTMLData.htmlArray.length + 4), ...[0x74, 0x45, 0x58, 0x74, 0x50, 0x4e, 0x47, 0], ...startHTMLData.htmlArray]);
-				htmlDataCRC = getCRC32(htmlData, 4);
-				// what follows the start tag is this chunk's CRC, four bytes only known once the
-				// tag is chosen: a comment they open with ">" or "->" is closed by the parser
-				// there and then, leaving the image data to be read as markup
-				abruptComment = tagIndex == 0 && (htmlDataCRC[0] == 0x3e || (htmlDataCRC[0] == 0x2d && htmlDataCRC[1] == 0x3e));
-				if (abruptComment) {
-					tagIndex++;
-				}
-			} while (abruptComment);
-			if (startHTMLData.pdfEntry) {
-				pdfEntry = startHTMLData.pdfEntry;
+			endTag = imageChunk.endTag;
+			if (imageChunk.startHTMLData.pdfEntry) {
+				pdfEntry = imageChunk.startHTMLData.pdfEntry;
 				// the htmlArray starts after the 4-byte length and the 8-byte type of the tEXt chunk
 				pdfEntry.offset += zipDataWriter.offset + 12;
 			}
-			await writeData(zipDataWriter.writable, htmlData);
-			await writeData(zipDataWriter.writable, htmlDataCRC);
+			await writeData(zipDataWriter.writable, imageChunk.htmlData);
+			await writeData(zipDataWriter.writable, imageChunk.htmlDataCRC);
 		} else if (options.embeddedPdf) {
 			const data = new Uint8Array([...getLength(options.embeddedPdf.length + 4), ...[0x74, 0x45, 0x58, 0x74, 0x50, 0x44, 0x46, 0], ...new Uint8Array(options.embeddedPdf)]);
 			await writeData(zipDataWriter.writable, data);
@@ -517,9 +551,13 @@ async function prependHTMLData(pageData, zipDataWriter, script, options, lastMod
 // the extractor finds the zip data by identifier instead of by its position in the tree: an
 // element carries it as an attribute, a comment as the first characters of its data
 function getDataStartTag([startTag]) {
-	return startTag == "<!--" ?
-		startTag + DATA_IDENTIFIER :
-		startTag.slice(0, -1) + " id=" + DATA_IDENTIFIER + ">";
+	if (startTag == "<!--") {
+		return startTag + DATA_IDENTIFIER;
+	}
+	// the attribute belongs to the element that opens the wrapper, which is not always the whole
+	// start tag: the CDATA rung opens with an <svg> and then a markup declaration that takes none
+	const tagEnd = startTag.indexOf(">");
+	return startTag.slice(0, tagEnd) + " id=" + DATA_IDENTIFIER + startTag.slice(tagEnd);
 }
 
 function getStartHTMLArray(pageData, options, lastModDate, startTag = "") {
@@ -543,24 +581,30 @@ function getStartHTMLArray(pageData, options, lastModDate, startTag = "") {
 		const localHeader = pdfEntry ? pdfEntry.localHeader : new Uint8Array(0);
 		const embeddedPdfText = TEXT_DECODER.decode(localHeader) + TEXT_DECODER.decode(embeddedPdf);
 		const pdfTagIndex = findEmbeddedDataTagIndex(embeddedPdfText);
-		const [pdfStartTag, pdfEndTag] = pdfTagIndex == -1 ? ["", ""] : EMBEDDED_DATA_TAGS[pdfTagIndex];
-		let htmlArray1 = new TextEncoder().encode(html + pdfStartTag);
-		if (htmlArray1.length + localHeader.length > PDF_HEADER_MAX_OFFSET) {
-			// PDF readers only scan the start of the file for the %PDF- header, and the page
-			// doctype is copied verbatim: it is the one part of the prefix with no bound, so a
-			// long one is replaced rather than pushing the header out of the scan window
-			htmlArray1 = new TextEncoder().encode(bom + MINIMAL_DOCTYPE + documentStart + pdfStartTag);
-		}
-		const htmlArray2 = new TextEncoder().encode(pdfEndTag + comment + htmlHeadData + startTag);
-		htmlArray = new Uint8Array(htmlArray1.length + localHeader.length + embeddedPdf.length + htmlArray2.length);
-		htmlArray.set(htmlArray1);
-		htmlArray.set(localHeader, htmlArray1.length);
-		htmlArray.set(embeddedPdf, htmlArray1.length + localHeader.length);
-		htmlArray.set(htmlArray2, htmlArray1.length + localHeader.length + embeddedPdf.length);
-		if (pdfEntry) {
-			pdfEntry.offset = htmlArray1.length;
+		if (pdfTagIndex == -1) {
+			dropUnhiddenFace(options, "embeddedPdf");
+			pdfEntry = undefined;
+		} else {
+			const [pdfStartTag, pdfEndTag] = EMBEDDED_DATA_TAGS[pdfTagIndex];
+			let htmlArray1 = new TextEncoder().encode(html + pdfStartTag);
+			if (htmlArray1.length + localHeader.length > PDF_HEADER_MAX_OFFSET) {
+				// PDF readers only scan the start of the file for the %PDF- header, and the page
+				// doctype is copied verbatim: it is the one part of the prefix with no bound, so a
+				// long one is replaced rather than pushing the header out of the scan window
+				htmlArray1 = new TextEncoder().encode(bom + MINIMAL_DOCTYPE + documentStart + pdfStartTag);
+			}
+			const htmlArray2 = new TextEncoder().encode(pdfEndTag + comment + htmlHeadData + startTag);
+			htmlArray = new Uint8Array(htmlArray1.length + localHeader.length + embeddedPdf.length + htmlArray2.length);
+			htmlArray.set(htmlArray1);
+			htmlArray.set(localHeader, htmlArray1.length);
+			htmlArray.set(embeddedPdf, htmlArray1.length + localHeader.length);
+			htmlArray.set(htmlArray2, htmlArray1.length + localHeader.length + embeddedPdf.length);
+			if (pdfEntry) {
+				pdfEntry.offset = htmlArray1.length;
+			}
 		}
-	} else {
+	}
+	if (!options.embeddedPdf) {
 		htmlArray = new TextEncoder().encode(html + comment + htmlHeadData + startTag);
 	}
 	return { htmlArray, pdfEntry };
@@ -624,8 +668,45 @@ function findExtraDataTags(textContent, pageData, options, script, writeEntries,
 // a rung is rejected on its end pattern, which terminates the wrapper, and on its start
 // pattern: script data has escape states the raw text rungs do not have, where "<!--"
 // followed by "<script" leaves "</script>" unable to close the element at all
-function findEmbeddedDataTagIndex(text) {
-	return EMBEDDED_DATA_REGEXPS.slice(0, -1).findIndex(([startRegExp, endRegExp]) => !text.match(startRegExp) && !text.match(endRegExp));
+function findEmbeddedDataTagIndex(text, fromIndex = 0) {
+	const tagIndex = EMBEDDED_DATA_REGEXPS.slice(fromIndex, -1).findIndex(([startRegExp, endRegExp]) => !text.match(startRegExp) && !text.match(endRegExp));
+	return tagIndex == -1 ? -1 : tagIndex + fromIndex;
+}
+
+// a face exists only while a rung can hide it. When the payload names every rung, the older
+// fallback emitted it unwrapped, on the grounds that the page still rendered: but the payload's
+// markup then joins the document, and a payload that is itself an archive contributes an
+// sfz-data node ahead of this file's own. A reader takes that one and extracts it, checksum and
+// all, with nothing to say the archive it returned is not the archive the file was built around.
+// Dropping the face costs a picture; keeping it costs the archive
+// what follows the start tag is the checksum of the chunk carrying it, four bytes only known once
+// the tag is chosen: a comment they open with ">" or "->" is closed by the parser there and then,
+// leaving the image data to be read as markup. Stepping past the comment rung means searching from
+// the next one, not taking it — a rung qualifies on the payload, and the payload had no say in
+// which rung the checksum sent the writer to
+function getImageHTMLChunk(pageData, options, lastModDate) {
+	const embeddedImageText = TEXT_DECODER.decode(getEmbeddedImageData(options.embeddedImage));
+	let tagIndex = findEmbeddedDataTagIndex(embeddedImageText);
+	while (tagIndex != -1) {
+		const [startTag, endTag] = EMBEDDED_DATA_TAGS[tagIndex];
+		const startHTMLData = getStartHTMLArray(pageData, options, lastModDate, startTag);
+		const htmlData = new Uint8Array([...getLength(startHTMLData.htmlArray.length + 4), ...[0x74, 0x45, 0x58, 0x74, 0x50, 0x4e, 0x47, 0], ...startHTMLData.htmlArray]);
+		const htmlDataCRC = getCRC32(htmlData, 4);
+		if (tagIndex == 0 && (htmlDataCRC[0] == 0x3e || (htmlDataCRC[0] == 0x2d && htmlDataCRC[1] == 0x3e))) {
+			tagIndex = findEmbeddedDataTagIndex(embeddedImageText, tagIndex + 1);
+		} else {
+			return { endTag, startHTMLData, htmlData, htmlDataCRC };
+		}
+	}
+}
+
+function getEmbeddedImageData(embeddedImage) {
+	return embeddedImage.slice(PNG_SIGNATURE_LENGTH + PNG_IHDR_LENGTH, embeddedImage.length - PNG_IEND_LENGTH);
+}
+
+function dropUnhiddenFace(options, name) {
+	delete options[name];
+	console.warn(UNHIDDEN_FACE_WARNING_MESSAGE, name); // eslint-disable-line no-console
 }
 
 async function writeData(writable, array) {
@@ -669,7 +750,7 @@ async function addPageResources(zipWriter, pageData, options, prefixName, url) {
 	]);
 }
 
-async function addFile(zipWriter, prefixName, data, disableCompresson) {
+async function addFile(zipWriter, prefixName, data, disableCompression) {
 	const dataReader = typeof data.content == "string" ? new TextReader(data.content) : new BlobReader(new Blob([new Uint8Array(data.content)]));
 	const options = { password: data.password, bufferedWrite: true };
 	if (!data.password) {
@@ -677,7 +758,7 @@ async function addFile(zipWriter, prefixName, data, disableCompresson) {
 		// password the resource URLs would be readable while the same map in manifest.json is not
 		options.comment = data.url && data.url.startsWith("data:") ? "data:" : data.url;
 	}
-	if (NO_COMPRESSION_EXTENSIONS.includes(data.extension) || disableCompresson) {
+	if (NO_COMPRESSION_EXTENSIONS.includes(data.extension) || disableCompression) {
 		options.level = 0;
 	}
 	await zipWriter.add(prefixName + data.name, dataReader, options);

package/single-file.js

@@ -111,23 +111,11 @@ async function getPageData(options = {}, initOptions, doc, win) {
 	}
 	const pageData = await processor.getPageData();
 	if (options.compressContent) {
-		const blob = await processors.compression.process(pageData, {
-			insertTextBody: options.insertTextBody,
-			url: options.url,
-			createRootDirectory: options.createRootDirectory,
-			selfExtractingArchive: options.selfExtractingArchive,
-			disableCompression: options.disableCompression,
-			extractDataFromPage: options.extractDataFromPage,
-			preventAppendedData: options.preventAppendedData,
-			declareAppendedData: options.declareAppendedData,
-			insertCanonicalLink: options.insertCanonicalLink,
-			insertMetaNoIndex: options.insertMetaNoIndex,
-			insertMetaCSP: options.insertMetaCSP,
-			password: options.password,
-			zipScript: options.zipScript,
-			embeddedImage: options.embeddedImage,
-			embeddedPdf: options.embeddedPdf
-		});
+		const compressionOptions = {};
+		for (const optionName of processors.compression.PROCESS_OPTION_NAMES) {
+			compressionOptions[optionName] = options[optionName];
+		}
+		const blob = await processors.compression.process(pageData, compressionOptions);
 		delete pageData.resources;
 		let arrayBuffer;
 		if (globalThis.FileReader) {

package/test/sfz-harness/README.md

@@ -26,6 +26,7 @@ any check failed.
 | `format-rules.js` | The rules of the format: charset round trip, the wrapper-tag ladder and its selection tests, the identifier, appended-data placement and declaration, password scope, the PDF and PNG faces. |
 | `stored-trigger.js` | That a stored (uncompressed) entry whose bytes contain a rung's pattern moves the writer to the right rung. |
 | `check-determinism.js` | That the same inputs produce the same bytes, and that the levers which should change the output do. |
+| `option-wiring.js` | That every option `compression.js` reads is either declared as a caller option or classified as internal, and that `single-file.js` still builds its argument from that declaration. Guards the layer the other three suites sit below. |
 
 ## The tools
 

package/test/sfz-harness/format-rules.js

@@ -166,7 +166,7 @@ function countIdentifiers(text) {
 	// the last rung is exempt from both tests: it has no terminator and no tokenizer
 	// states, so a payload naming every rung still fits inside it
 	const content = new Uint8Array(4096).fill(0x21);
-	content.set(new TextEncoder().encode("<!--<script<style<noframes<noembed<iframe<xmp<plaintext"), 128);
+	content.set(new TextEncoder().encode("<!--<script<style<noframes<noembed<iframe<xmp<![CDATA[<plaintext"), 128);
 	const options = makeOptions();
 	const pageData = makePageData(19, 4 * 1024);
 	pageData.resources.images.push({ name: "images/all-starts.png", extension: ".png", content });
@@ -176,6 +176,33 @@ function countIdentifiers(text) {
 	check("the last rung still carries the identifier", decodeText(bytes).includes("<plaintext id=sfz-data>PK"), true);
 }
 
+// the CDATA rung is the last one that can be closed, so it is what stands between a payload
+// naming every element rung and <plaintext>, whose selection costs the appended-data placement.
+// Its identifier goes on the svg, not on the markup declaration, which takes no attributes
+{
+	const content = new Uint8Array(4096).fill(0x21);
+	content.set(new TextEncoder().encode("<!--<script<style<noframes<noembed<iframe<xmp"), 128);
+	const options = makeOptions();
+	const pageData = makePageData(24, 4 * 1024);
+	pageData.resources.images.push({ name: "images/no-cdata.png", extension: ".png", content });
+	const { bytes } = await runProcess(pageData, options);
+	check("a payload naming every element rung stops at the cdata rung", options.extractDataFromPageTags[0], "<svg><![CDATA[");
+	check("the cdata rung identifies the svg, not the declaration", decodeText(bytes).includes("<svg id=sfz-data><![CDATA[PK"), true);
+	check("the cdata rung leaves the appended data placement alone", options.preventAppendedData !== true, true);
+}
+
+// the terminator is the whole test for this rung, so a payload holding it must step past
+{
+	const content = new Uint8Array(4096).fill(0x21);
+	content.set(new TextEncoder().encode("<!--<script<style<noframes<noembed<iframe<xmp]]>"), 128);
+	const options = makeOptions();
+	const pageData = makePageData(25, 4 * 1024);
+	pageData.resources.images.push({ name: "images/cdata-end.png", extension: ".png", content });
+	const { bytes } = await runProcess(pageData, options);
+	check("a payload holding \"]]>\" defeats the cdata rung", options.extractDataFromPageTags[0], "<plaintext>");
+	check("the rung below takes it", decodeText(bytes).includes("<plaintext id=sfz-data>PK"), true);
+}
+
 // script data has escape states the raw text rungs do not: "<!--" then "<script" in a
 // payload leaves "</script>" unable to close the element, so a face carrying both must
 // step past the script rung even though it holds no closer at all
@@ -202,6 +229,42 @@ const DOUBLE_ESCAPE = "--> <!-- <script ";
 	check("the png face takes no script rung", decodeText(bytes).includes("<script type=sfz-data>"), false);
 }
 
+// a face is hidden by the same ladder as the zip data, minus the rung that cannot be closed:
+// a payload naming all seven of the rest leaves nowhere to put it. Writing it unwrapped was the
+// older behaviour, and it is the dangerous one, because the payload's own markup then joins the
+// document. These payloads carry the identifier the way a nested archive does: a reader looking
+// for one node finds two, takes the first, and extracts an archive that checksums
+const ALL_FACE_RUNGS = "<!--sfz-data<script<style<noframes<noembed<iframe<xmp<![CDATA[";
+
+{
+	const embeddedPdf = new TextEncoder().encode("%PDF-1.4\n1 0 obj\n<< /X (" + ALL_FACE_RUNGS + ") >>\nendobj\ntrailer\n<<>>\n%%EOF\n");
+	const options = makeOptions({ embeddedPdf });
+	const pageData = makePageData(22, 4 * 1024);
+	const { bytes } = await runProcess(pageData, options);
+	const text = decodeText(bytes);
+	check("an unhidable pdf face is dropped", text.includes("%PDF-"), false);
+	check("the dropped pdf face leaves one identifier", countIdentifiers(text), 1);
+	const zipReader = new ZipReader(new BlobReader(new Blob([bytes])));
+	const entries = await zipReader.getEntries();
+	await zipReader.close();
+	check("the archive survives the dropped pdf face", entries.length > 0, true);
+	check("no page.pdf entry is left behind", entries.some(entry => entry.filename.endsWith("page.pdf")), false);
+}
+
+{
+	const embeddedImage = new Uint8Array(8 + 25 + 512 + 12);
+	embeddedImage.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+	embeddedImage.fill(0x41, 33, 33 + 512);
+	embeddedImage.set(new TextEncoder().encode(ALL_FACE_RUNGS), 100);
+	const options = makeOptions({ embeddedImage });
+	const pageData = makePageData(23, 4 * 1024);
+	const { bytes } = await runProcess(pageData, options);
+	const text = decodeText(bytes);
+	check("an unhidable png face is dropped", bytes[0], 0x3c);
+	check("the dropped png face leaves one identifier", countIdentifiers(text), 1);
+	check("the page keeps its doctype without the png face", text.startsWith("<!DOCTYPE html>"), true);
+}
+
 // every rung pattern is matched case-insensitively, because the HTML tokenizer closes an
 // element on any case of its end tag. Dropping that would pick a rung the payload itself
 // terminates, and no other test in this file would notice
@@ -245,6 +308,29 @@ for (const seed of [147, 148, 616]) {
 	check("no wrapper comment is closed abruptly, seed " + seed, /<!--(>|->)/.test(decodeText(bytes)), false);
 }
 
+// leaving the comment rung is a search, not an increment. The checksum decides only that the
+// comment is unusable; which rung is usable is still the payload's to say, and these payloads
+// terminate the rung immediately below. Taking it on trust put the image data, the chunk framing
+// and the whole ZIP region outside the wrapper, 19KB of it, read by the parser as markup
+for (const seed of [148, 616]) {
+	const embeddedImage = randomPng(seed);
+	embeddedImage.set(new TextEncoder().encode("</script>"), 100);
+	const options = makeOptions({ embeddedImage });
+	const pageData = makePageData(seed, 2 * 1024);
+	const { bytes } = await runProcess(pageData, options);
+	const text = decodeText(bytes);
+	check("the step off the comment rung skips what the payload terminates, seed " + seed, text.includes("<script type=sfz-data>"), false);
+	check("the step off the comment rung lands on a rung that qualifies, seed " + seed, text.includes("<style type=sfz-data>"), true);
+}
+
+// the control for the pair above: the same seeds, the same step, a payload that leaves the rung
+// below usable — the writer must still take it rather than skip past it
+{
+	const options = makeOptions({ embeddedImage: randomPng(148) });
+	const { bytes } = await runProcess(makePageData(148, 2 * 1024), options);
+	check("the step off the comment rung takes a usable rung", decodeText(bytes).includes("<script type=sfz-data>"), true);
+}
+
 function readAppendedData(bytes) {
 	const view = new DataView(bytes.buffer, bytes.byteOffset);
 	for (let index = bytes.length - 22; index >= 0; index--) {

package/test/sfz-harness/option-wiring.js

@@ -0,0 +1,63 @@
+// The compression processor is reached through a whitelist in single-file.js. An option this
+// module reads but the whitelist omits is undefined at every call site, so the feature works on
+// the multi-page path (which calls createArchive directly) and silently does nothing on every
+// single-page capture. That is how --declare-appended-data and --include-BOM both shipped inert,
+// and no test caught either: the other suites call compression.process() directly, one layer
+// below the wiring they would have to see.
+import { PROCESS_OPTION_NAMES } from "../../processors/compression/compression.js";
+
+// names matched by the source scan that are NOT caller options. Keeping them listed here rather
+// than filtering them out silently is the point of this test: a new name must be classified as
+// one thing or the other before the suite goes green again
+const INTERNAL_OPTION_NAMES = [
+	// state the module sets on itself between build passes
+	"extraData",
+	"extraDataSize",
+	"extraDataSizeDropped",
+	"extractDataFromPageTags",
+	"preventEmbeddedPdfEntry",
+	// supplied by compression-packager.js, which calls createArchive directly
+	"embeddedScreenshotImage",
+	"multiPageArchive",
+	// read for the root directory name, but no caller has ever passed it
+	"tabId",
+	// a different `options` object: the per-entry zip options built inside addFile()
+	"comment",
+	"level"
+];
+
+let failed = false;
+
+function check(label, actual, expected) {
+	const ok = actual === expected;
+	console.log(`${ok ? "PASS" : "FAIL"} ${label}: ${actual}${ok ? "" : " (expected " + expected + ")"}`);
+	failed ||= !ok;
+}
+
+const compressionSource = await Deno.readTextFile(new URL("../../processors/compression/compression.js", import.meta.url));
+const singleFileSource = await Deno.readTextFile(new URL("../../single-file.js", import.meta.url));
+const readNames = [...new Set([...compressionSource.matchAll(/options\.([A-Za-z0-9_]+)/g)].map(match => match[1]))].sort();
+
+const unclassified = readNames.filter(name => !PROCESS_OPTION_NAMES.includes(name) && !INTERNAL_OPTION_NAMES.includes(name));
+check("every option compression.js reads is classified", unclassified.join(", "), "");
+
+const unread = PROCESS_OPTION_NAMES.filter(name => !readNames.includes(name));
+check("no declared caller option is dead", unread.join(", "), "");
+
+const misclassified = INTERNAL_OPTION_NAMES.filter(name => PROCESS_OPTION_NAMES.includes(name));
+check("no option is both a caller option and internal", misclassified.join(", "), "");
+
+check("the declared list is sorted", PROCESS_OPTION_NAMES.join(), [...PROCESS_OPTION_NAMES].sort().join());
+
+// the guard is only worth anything while single-file.js builds its argument from the list; a
+// literal object there would drift again, which is exactly the bug this file exists to prevent
+check("single-file.js builds its argument from the list", singleFileSource.includes("PROCESS_OPTION_NAMES"), true);
+check("single-file.js keeps no literal option whitelist", /insertTextBody:\s*options\.insertTextBody/.test(singleFileSource), false);
+
+check("includeBOM reaches the compressed path", PROCESS_OPTION_NAMES.includes("includeBOM"), true);
+
+if (failed) {
+	console.log("FAILED");
+	Deno.exit(1);
+}
+console.log("OK");

package/test/sfz-harness/stored-trigger.js

@@ -2,7 +2,7 @@ import { makePageData, makeOptions, runProcess, mulberry32 } from "./common.js";
 
 function storedResource(name, literals) {
 	const rand = mulberry32(0xbeef);
-	const bytes = new Uint8Array(4096).map(() => (rand() * 256) | 0);
+	const bytes = new Uint8Array(Math.max(4096, 256 + literals.length * 512)).map(() => (rand() * 256) | 0);
 	const encoder = new TextEncoder();
 	let offset = 256;
 	for (const literal of literals) {
@@ -33,7 +33,7 @@ function check(label, actual, expected) {
 	const options = makeOptions();
 	const pageData = makePageData(2, 64 * 1024);
 	pageData.resources.images.push(storedResource("photo.jpg",
-		["-->", "</noscript>", "</noframes>", "</noembed>", "</script>", "</style>", "</iframe>", "</xmp>"]));
+		["-->", "</noscript>", "</noframes>", "</noembed>", "</script>", "</style>", "</iframe>", "</xmp>", "]]>"]));
 	const result = await runProcess(pageData, options);
 	check("all closers exhaust to", result.fallbackTag, "<plaintext>");
 	check("all closers keep extraction", result.extractionDisabled, false);