single-file-core 1.5.89 → 1.5.91

package/.github/workflows/publish.yml

@@ -0,0 +1,88 @@
+# .github/workflows/publish.yml
+
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  # nothing else guarantees that the released commit was verified: the vendor workflow runs on push,
+  # so this waits for its run on that exact commit and refuses to publish unless it succeeded
+  check_vendor:
+    name: 'Check vendor rebuild'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      actions: read
+    steps:
+      # only used to resolve the tag to a commit, so it runs no code from the repository and keeps no
+      # git credentials behind
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.release.tag_name }}
+          persist-credentials: false
+      # the tag is typed in the release UI, so nothing ties it to the version that is about to be
+      # published: a mistyped tag, or a bump that was never pushed, publishes a version nobody asked for
+      - name: Verify the tag matches the declared version
+        env:
+          TAG_NAME: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(jq -r .version package.json)
+          if [ "$TAG_NAME" != "v$version" ]; then
+            echo "::error::release $TAG_NAME but package.json declares $version"
+            exit 1
+          fi
+      - name: Wait for the vendor rebuild check of the released commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          sha=$(git rev-parse HEAD)
+          echo "released commit: $sha"
+          missing=0
+          for attempt in $(seq 1 60); do
+            run=$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/vendor.yml/runs?head_sha=$sha&per_page=1" \
+              --jq 'if (.workflow_runs | length) == 0 then "none none none"
+                    else (.workflow_runs[0] | "\(.status) \(.conclusion) \(.html_url)") end')
+            run_status=$(echo "$run" | cut -d' ' -f1)
+            conclusion=$(echo "$run" | cut -d' ' -f2)
+            url=$(echo "$run" | cut -d' ' -f3)
+            if [ "$run_status" = "none" ]; then
+              missing=$((missing + 1))
+              if [ "$missing" -ge 10 ]; then
+                echo "::error::no vendor run for $sha, run the vendor workflow on this commit and publish again"
+                exit 1
+              fi
+              echo "no vendor run found yet for $sha"
+            else
+              echo "vendor run: status=$run_status conclusion=$conclusion $url"
+              if [ "$run_status" = "completed" ]; then
+                if [ "$conclusion" = "success" ]; then
+                  exit 0
+                fi
+                echo "::error::the vendor rebuild concluded $conclusion for $sha, see $url"
+                exit 1
+              fi
+            fi
+            sleep 30
+          done
+          echo "::error::timed out waiting for the vendor rebuild of $sha"
+          exit 1
+
+  publish_npm:
+    needs: check_vendor
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.release.tag_name }}
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24'
+          registry-url: 'https://registry.npmjs.org'
+      - run: npm publish

package/.github/workflows/vendor.yml

@@ -0,0 +1,25 @@
+# .github/workflows/vendor.yml
+
+name: Vendor
+
+# tag pushes are excluded: creating a release would otherwise re-run the check already done on the branch
+on:
+  push:
+    branches: ['**']
+  pull_request:
+
+jobs:
+  rebuild:
+    name: 'Rebuild vendor/zip'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24'
+      - run: npm ci
+        working-directory: zip-build
+      - run: npm run build
+        working-directory: zip-build
+      # the checked-in files in vendor/zip must be exactly what the sources in zip-build produce
+      - run: git diff --exit-code vendor/zip

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "single-file-core",
-  "version": "1.5.89",
+  "version": "1.5.91",
   "description": "SingleFile Core",
   "author": "Gildas Lormeau",
   "license": "AGPL-3.0-or-later",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "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",
@@ -18,4 +22,4 @@
   "devDependencies": {
     "eslint": "^9.39.1"
   }
-}
+}

package/processors/compression/compression-router.js

@@ -27,8 +27,13 @@ export {
 
 async function router(content, { extract, display }) {
 	const PAGES_PREFIX = "pages/";
+	const RESERVED_PREFIX = "sfz-";
 	const PAGES_FILENAME = "sfz-pages.json";
+	const TOC_FILENAME = "sfz-toc.html";
 	const ROUTE_PREFIX = "#sfz/";
+	// "?" cannot start a zip entry path written by the packager, so reserved
+	// routes never collide with page paths
+	const TOC_ROUTE = "?toc";
 	const TARGET_ATTRIBUTE = "data-sfz-target";
 	const TARGET_PSEUDO_CLASS = /:target(?![\w-])/g;
 	const VISITED_ATTRIBUTE = "data-sfz-visited";
@@ -41,7 +46,7 @@ async function router(content, { extract, display }) {
 	const UNARCHIVED_TITLE = "Not saved in this archive";
 	const UNARCHIVED_PROTOCOLS = ["http:", "https:"];
 	const PREFETCH_DELAY = 100;
-	const { zip, document, location, history, CSS, setTimeout, clearTimeout } = globalThis;
+	const { zip, document, location, history, CSS, URL, setTimeout, clearTimeout } = globalThis;
 	const cache = new Map();
 	const urlToPath = new Map();
 	const scrollStates = new Map();
@@ -62,6 +67,7 @@ async function router(content, { extract, display }) {
 		throw new Error("Pages data not found");
 	}
 	const manifest = JSON.parse(await pagesEntry.getData(new zip.TextWriter()));
+	const tocEntry = entries.find(entry => entry.filename == TOC_FILENAME);
 	const { pages } = manifest;
 	const aliases = new Map(Object.entries(manifest.aliases || {}));
 	pages.forEach(page => {
@@ -97,6 +103,11 @@ async function router(content, { extract, display }) {
 		const node = findAnchor(event.target);
 		if (node && node.href) {
 			const fragment = getFragment(node.href);
+			// rewritten TOC links are already hash routes, default navigation
+			// triggers hashchange and modified clicks open the deep link natively
+			if (fragment && fragment.startsWith(ROUTE_PREFIX) && stripFragment(node.href) == stripFragment(location.href)) {
+				return;
+			}
 			let path = urlToPath.get(stripFragment(node.href));
 			if (path === undefined && fragment && stripFragment(node.href) == stripFragment(location.href)) {
 				path = currentPath;
@@ -127,7 +138,7 @@ async function router(content, { extract, display }) {
 		const continuityScrolls = captureElementScrolls();
 		const entryId = getEntryId();
 		const { routed, path, fragment } = parseRoute();
-		const willRender = routed && path != currentPath && Boolean(pages.find(page => page.path == path));
+		const willRender = routed && path != currentPath && isRenderablePath(path);
 		// the whole render and scroll sequence runs inside the view transition
 		// so that the crossfade ends on the final scroll position
 		if (willRender && document.startViewTransition && !prefersReducedMotion()) {
@@ -177,13 +188,16 @@ async function router(content, { extract, display }) {
 		if (!routed && !initial) {
 			return false;
 		}
-		if (path == currentPath || !pages.find(page => page.path == path)) {
+		if (path == currentPath || !isRenderablePath(path)) {
 			return false;
 		}
 		const docContent = await getPageContent(path);
 		currentPath = path;
 		await display(document, docContent, { inPlace: true });
 		attachListeners();
+		if (path == TOC_ROUTE) {
+			rewriteTocLinks();
+		}
 		visitedPaths.add(path);
 		markVisitedLinks();
 		if (manifest.markUnarchivedLinks) {
@@ -205,14 +219,24 @@ async function router(content, { extract, display }) {
 		let path = pages[0].path;
 		let fragment;
 		if (routed && hash) {
-			const route = hash.substring(ROUTE_PREFIX.length);
-			const indexFragment = route.indexOf("#");
-			path = decodeURIComponent(indexFragment == -1 ? route : route.substring(0, indexFragment));
-			fragment = indexFragment == -1 ? undefined : route.substring(indexFragment);
+			({ path, fragment } = parseRouteHash(hash));
 		}
 		return { routed, path, fragment };
 	}
 
+	function parseRouteHash(hash) {
+		const route = hash.substring(ROUTE_PREFIX.length);
+		const indexFragment = route.indexOf("#");
+		return {
+			path: decodeURIComponent(indexFragment == -1 ? route : route.substring(0, indexFragment)),
+			fragment: indexFragment == -1 ? undefined : route.substring(indexFragment)
+		};
+	}
+
+	function isRenderablePath(path) {
+		return path == TOC_ROUTE ? Boolean(tocEntry) : Boolean(pages.find(page => page.path == path));
+	}
+
 	// the cache stores promises so that a click during a hover prefetch awaits
 	// the extraction in flight instead of starting a second one
 	function getPageContent(path) {
@@ -225,6 +249,9 @@ async function router(content, { extract, display }) {
 	}
 
 	async function extractPageContent(path) {
+		if (path == TOC_ROUTE) {
+			return tocEntry.getData(new zip.TextWriter());
+		}
 		const pageEntries = entries
 			.filter(entry => belongsToPage(entry.filename, path) && !aliases.has(entry.filename))
 			.concat(getAliasEntries(path));
@@ -252,14 +279,37 @@ async function router(content, { extract, display }) {
 
 	function belongsToPage(filename, path) {
 		return path == "" ?
-			!filename.startsWith(PAGES_PREFIX) && filename != PAGES_FILENAME :
+			!filename.startsWith(PAGES_PREFIX) && !filename.startsWith(RESERVED_PREFIX) :
 			filename.startsWith(path);
 	}
 
+	// the stored TOC links relative page paths so that it works once unzipped,
+	// in the archive they are rewritten to hash routes: unrewritten links would
+	// resolve against the archive URL and get stamped as unarchived
+	function rewriteTocLinks() {
+		const pathsByUrl = new Map();
+		pages.forEach(page => pathsByUrl.set(new URL(page.path + "index.html", stripFragment(location.href)).href, page.path));
+		document.querySelectorAll("a[href]").forEach(anchorElement => {
+			const fragment = getFragment(anchorElement.href);
+			const path = pathsByUrl.get(stripFragment(anchorElement.href));
+			if (path !== undefined) {
+				anchorElement.setAttribute("href", ROUTE_PREFIX + path + (fragment || ""));
+			}
+		});
+	}
+
+	function getLinkPath(href) {
+		const fragment = getFragment(href);
+		if (fragment && fragment.startsWith(ROUTE_PREFIX) && stripFragment(href) == stripFragment(location.href)) {
+			return parseRouteHash(fragment).path;
+		}
+		return urlToPath.get(stripFragment(href));
+	}
+
 	function prefetchOnHover(event) {
 		const node = findAnchor(event.target);
 		if (node && node.href) {
-			const path = urlToPath.get(stripFragment(node.href));
+			const path = getLinkPath(node.href);
 			if (path !== undefined && path != currentPath && !cache.has(path)) {
 				clearTimeout(prefetchTimeout);
 				prefetchTimeout = setTimeout(() => getPageContent(path).catch(() => { }), PREFETCH_DELAY);
@@ -380,7 +430,7 @@ async function router(content, { extract, display }) {
 			getPseudoRules(VISITED_PSEUDO_CLASS, VISITED_ATTRIBUTE);
 		document.head.appendChild(styleElement);
 		document.querySelectorAll("a[href]").forEach(anchorElement => {
-			const path = urlToPath.get(stripFragment(anchorElement.href));
+			const path = getLinkPath(anchorElement.href);
 			if (path !== undefined && visitedPaths.has(path)) {
 				anchorElement.setAttribute(VISITED_ATTRIBUTE, "");
 			}

package/processors/compression/compression.js

@@ -112,7 +112,6 @@ async function process(pageData, options, lastModDate = new Date()) {
 async function createArchive(pageData, options, script, writeEntries, lastModDate = new Date()) {
 	const zipDataWriter = new Uint8ArrayWriter();
 	zipDataWriter.init();
-	zipDataWriter.writable.size = 0;
 	let extraDataOffset, extraData, embeddedImageDataOffset, endTag;
 	if (options.embeddedImage) {
 		options.embeddedImage = new Uint8Array(options.embeddedImage);
@@ -145,10 +144,15 @@ async function createArchive(pageData, options, script, writeEntries, lastModDat
 	} else if (!options.embeddedImage && options.embeddedPdf) {
 		await writeData(zipDataWriter.writable, new Uint8Array(options.embeddedPdf));
 	}
-	const zipWriter = new ZipWriter(zipDataWriter, { bufferedWrite: true, keepOrder: true, lastModDate, useCompressionStream: true });
+	// a WritableWriter object is passed instead of the writer so that the ZipWriter
+	// never takes ownership of the stream: preventClose is only honored when the
+	// caller owns the writable, and the HTML suffix still gets written after it;
+	// its size property tells the ZipWriter the offset of the data written so far
 	const startOffset = zipDataWriter.offset;
+	const zipWriter = new ZipWriter({ writable: zipDataWriter.writable, size: startOffset }, { bufferedWrite: true, keepOrder: true, lastModDate, useCompressionStream: true });
 	await writeEntries(zipWriter);
-	const data = await zipWriter.close(null, { preventClose: true });
+	await zipWriter.close(undefined, { preventClose: true });
+	const data = zipDataWriter.getData();
 	if (options.selfExtractingArchive) {
 		const lfCodes = [];
 		let crc32 = -1;
@@ -418,7 +422,6 @@ function findExtraDataTags(textContent, pageData, options, script, writeEntries,
 async function writeData(writable, array) {
 	const streamWriter = writable.getWriter();
 	await streamWriter.ready;
-	writable.size += array.length;
 	await streamWriter.write(array);
 	streamWriter.releaseLock();
 }

package/zip-build/README.md

@@ -0,0 +1,56 @@
+# Rebuilding `vendor/zip`
+
+The three files in [`../vendor/zip`](../vendor/zip) are custom builds of
+[@zip.js/zip.js](https://www.npmjs.com/package/@zip.js/zip.js) with
+[fflate](https://www.npmjs.com/package/fflate) as `DecompressionStream`
+fallback:
+
+- `zip.min.js` — extraction bundle used by self-extracting pages
+  (`ZipReader`, `HttpRangeReader`, blob/text/data-URI readers and writers,
+  no web workers, fflate fallback for browsers without
+  `DecompressionStream`)
+- `zip.js` — creation bundle used when saving pages (full zip-core plus
+  `deflateRaw`/`inflateRaw`)
+- `z-worker.js` — web worker script for the creation bundle
+
+This directory rebuilds them byte-for-byte from their sources. All
+dependencies are pinned to exact versions by `package.json` and
+`package-lock.json`, and the build embeds no timestamps, so the output is
+reproducible on any platform with a recent Node.js version:
+
+```sh
+cd zip-build
+npm ci
+npm run build
+git diff --exit-code ../vendor/zip
+```
+
+An empty diff means the checked-in files match the sources exactly. The
+GitHub Actions workflow `.github/workflows/vendor.yml` runs the same steps
+on every push.
+
+## Files
+
+- `lib/zip.js`, `lib/zip-vendor.js`, `lib/zip-vendor-worker.js` — bundle
+  entry points; they import the zip.js sources from the pinned npm package
+- `lib/fflate.js` — vendored [fflate](https://github.com/101arrowz/fflate)
+  0.8.3 (MIT)
+- `lib/fflate-streams.js` — `CompressionStream`/`DecompressionStream`
+  adapter over fflate
+- `reserved-property-names.json` — property names protected from terser
+  property mangling; generated by `reserved-property-names.js` in the
+  [zip.js repository](https://github.com/gildas-lormeau/zip.js) at the
+  pinned version (the script is not part of the npm package)
+
+## Updating zip.js
+
+1. Bump `@zip.js/zip.js` in `package.json` and run `npm install`.
+2. Regenerate `reserved-property-names.json` from a checkout of the zip.js
+   repository at the matching tag, with its dev dependencies installed:
+
+   ```sh
+   node --input-type=module -e "import { getReservedPropertyNames } from './reserved-property-names.js'; console.log(JSON.stringify([...getReservedPropertyNames()], null, '\t'))" > path/to/single-file-core/zip-build/reserved-property-names.json
+   ```
+
+3. Run `npm run build` and commit the regenerated files in `../vendor/zip`
+   together with the changes in this directory.

package/zip-build/lib/fflate-streams.js

@@ -0,0 +1,47 @@
+/* global TransformStream */
+
+import { Deflate, Inflate } from "./fflate.js";
+
+const FORMAT_DEFLATE_RAW = "deflate-raw";
+
+class FflateStream extends TransformStream {
+	constructor(codec) {
+		super({
+			start(controller) {
+				codec.ondata = chunk => {
+					if (chunk.length) {
+						controller.enqueue(chunk);
+					}
+				};
+			},
+			transform(chunk) {
+				codec.push(chunk);
+			},
+			flush() {
+				codec.push(new Uint8Array(0), true);
+			}
+		});
+	}
+}
+
+class CompressionStreamFallback extends FflateStream {
+	constructor(format, { level } = {}) {
+		checkFormat(format);
+		super(new Deflate(level === undefined ? {} : { level }));
+	}
+}
+
+class DecompressionStreamFallback extends FflateStream {
+	constructor(format) {
+		checkFormat(format);
+		super(new Inflate());
+	}
+}
+
+function checkFormat(format) {
+	if (format != FORMAT_DEFLATE_RAW) {
+		throw new TypeError("Unsupported compression format: " + format);
+	}
+}
+
+export { CompressionStreamFallback, DecompressionStreamFallback };