afterimage-cli 0.0.0-stage → 0.1.1

package/src/cli/site.js

@@ -0,0 +1,171 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { sourceExcludes } from './config.js';
+import { readApp, verifyHistory } from './history.js';
+import { isLocked, retryLocked } from './retry.js';
+import { runBuild } from './run-build.js';
+
+// The package's own viewer and runtime, found from this file so they work from node_modules and from a checkout.
+export const packagedViewerDir = fileURLToPath(new URL('../../viewer-dist/', import.meta.url));
+export const packagedRuntimeDir = fileURLToPath(new URL('../runtime/', import.meta.url));
+
+const servedFolder = 'afterimage';
+const keep = { recursive: true, force: true, maxRetries: 3 };
+const escapePattern = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+// Windows and macOS ignore case by default, so two spellings of one folder must compare equal there.
+const fold = value => (process.platform === 'win32' || process.platform === 'darwin' ? value.toLowerCase() : value);
+
+// True when child is parent or lies under it. A folder named "..x" is inside; only ".." itself leaves.
+export function isSameOrInside(child, parent) {
+  const relative = path.relative(fold(parent), fold(child));
+  return !(relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative));
+}
+
+// Out is replaced wholesale, so it must not be, hold or sit inside anything that is not generated output.
+function checkOut({ outDir, projectDir, historyDir, sourceDir, includeApp }) {
+  const replaces = dir => { throw new Error(`"out" (${outDir}) would replace ${dir}. Point "out" at a folder of its own.`); };
+  if (isSameOrInside(projectDir, outDir)) replaces(projectDir);
+  if (isSameOrInside(historyDir, outDir)) replaces(historyDir);
+  if (isSameOrInside(outDir, historyDir)) throw new Error(`"out" (${outDir}) is inside the history folder, where saved versions live. Point "out" at a folder of its own.`);
+  if (!includeApp) return;
+  if (isSameOrInside(sourceDir, outDir)) replaces(sourceDir);
+  // With the prototype at the project root, config.js already leaves out of the app; anywhere else it would copy itself.
+  if (!isSameOrInside(projectDir, sourceDir) && isSameOrInside(outDir, sourceDir)) {
+    throw new Error(`"out" (${outDir}) is inside the source folder, so each build would copy the last one into itself. Point "out" outside ${sourceDir}.`);
+  }
+}
+
+// Leftovers of a build that crashed, matched by this file's own naming so nothing else is touched.
+async function removeStale(outDir) {
+  const pattern = new RegExp(`^${escapePattern(path.basename(outDir))}\\.tmp-[0-9a-f]{8}(\\.old)?$`);
+  try {
+    for (const name of await fs.readdir(path.dirname(outDir))) {
+      if (pattern.test(name)) await fs.rm(path.join(path.dirname(outDir), name), keep);
+    }
+  } catch { /* best effort */ }
+}
+
+const collision = () => new Error(`The app already has an ${servedFolder} file or folder, and Afterimage serves the history at /${servedFolder}/. Rename it or add it to exclude.`);
+
+// A top-level file called afterimage would stop readSnapshot with a less helpful message, so look for it first.
+async function checkCollision(sourceDir, excluded) {
+  let entries = [];
+  try {
+    entries = await fs.readdir(sourceDir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (entries.some(entry => !entry.isDirectory() && entry.name.toLowerCase() === servedFolder && !excluded.includes(entry.name))) throw collision();
+}
+
+// Builds the deployable site: the app at the root, the viewer and every saved version under /afterimage/.
+// With includeApp false (the dev server) only the afterimage/ folder is made. The old out stays in place until the
+// new one is complete, so a failure anywhere leaves the previous site untouched.
+// Returns warnings for the caller to print. fsOps lets tests make the swap fail; it is not part of the public signature.
+export async function assembleSite({ projectDir, config, viewerDir = packagedViewerDir, runtimeDir = packagedRuntimeDir, includeApp = true, buildStdio, fsOps = {} }) {
+  const ops = { rename: fs.rename, rm: fs.rm, ...fsOps };
+  const historyDir = path.resolve(projectDir, config.history);
+  const sourceDir = path.resolve(projectDir, config.source);
+  const outDir = path.resolve(projectDir, config.out);
+  const warnings = [];
+
+  const manifest = await verifyHistory(historyDir);
+  if (!manifest?.versions.length) throw new Error('Save a first version with: afterimage save "Name"');
+  try {
+    await fs.access(path.join(viewerDir, 'index.html'));
+  } catch {
+    throw new Error('The viewer is not built. Run "npm run build:viewer" first.');
+  }
+  // Without the runtime the viewer still loads, but every built app in it renders without its files, so a package
+  // that lost it must fail here rather than ship.
+  try {
+    await fs.access(runtimeDir);
+  } catch {
+    throw new Error(`The frame runtime is missing (${runtimeDir}). Reinstall afterimage-cli.`);
+  }
+  checkOut({ outDir, projectDir: path.resolve(projectDir), historyDir, sourceDir, includeApp });
+  // Asked twice: the user's build command can remove or create out, so the answer before it may be stale at the swap.
+  const outExists = async () => {
+    const found = await fs.lstat(outDir).catch(() => null);
+    if (found && !found.isDirectory()) throw new Error(`"out" (${outDir}) exists and is not a folder. Remove it or point "out" at another path.`);
+    return Boolean(found);
+  };
+  await outExists();
+  await removeStale(outDir);
+
+  let app;
+  if (includeApp) {
+    if (config.build) await runBuild(config.build, projectDir, { stdio: buildStdio, closing: 'Nothing was built.' });
+    const excluded = await sourceExcludes(projectDir, config);
+    await checkCollision(sourceDir, excluded);
+    // The app's output as its own build made it, not a save's selection: nothing Afterimage does may change the live root.
+    // Files no build wrote are the person's own folder, which can hold .env and editor settings like the project root.
+    app = await readApp(sourceDir, { exclude: excluded, plain: !config.build || sourceDir === path.resolve(projectDir) });
+    // Case-insensitive: on Windows and macOS Afterimage/ is the same folder.
+    if ([...app.keys()].some(name => name.split('/')[0].toLowerCase() === servedFolder)) throw collision();
+  }
+
+  await fs.mkdir(path.dirname(outDir), { recursive: true });
+  const staging = path.join(path.dirname(outDir), `${path.basename(outDir)}.tmp-${randomUUID().slice(0, 8)}`);
+  const previous = `${staging}.old`;
+  const rename = async (from, to) => {
+    try {
+      await retryLocked(() => ops.rename(from, to));
+    } catch (error) {
+      if (!isLocked(error)) throw error;
+      // The caller adds what became of the old site, which depends on how far the swap got.
+      throw Object.assign(new Error(`Could not replace ${config.out}: a file in it is in use. Close anything serving it (like afterimage dev or a static server) and run build again.`, { cause: error }), { locked: true });
+    }
+  };
+  try {
+    const served = path.join(staging, servedFolder);
+    await fs.mkdir(served, { recursive: true });
+    for (const [name, bytes] of app ?? []) {
+      const target = path.join(staging, name);
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, bytes);
+    }
+    await fs.cp(viewerDir, served, { recursive: true });
+    // Only what versions.json lists. The history folder also holds the save lock and stage folders.
+    await fs.copyFile(path.join(historyDir, 'versions.json'), path.join(served, 'versions.json'));
+    for (const { id } of manifest.versions) {
+      await fs.cp(path.join(historyDir, 'versions', id), path.join(served, 'versions', id), { recursive: true });
+    }
+    // map.js is for node (history.js injects with it); frame.js and sw.js carry their own copies of what they need,
+    // so the browser never loads it and it is not served.
+    await fs.cp(runtimeDir, served, { recursive: true, filter: source => path.relative(runtimeDir, source) !== 'map.js' });
+
+    // Windows cannot rename over an existing folder, so the old site steps aside first and comes back if the swap fails.
+    const existing = await outExists();
+    const unchanged = error => { if (error.locked) error.message += ' The previous site is unchanged.'; return error; };
+    if (existing) await rename(outDir, previous).catch(error => { throw unchanged(error); });
+    try {
+      await rename(staging, outDir);
+    } catch (error) {
+      if (existing) {
+        try {
+          await ops.rename(previous, outDir);
+        } catch {
+          // Keep the original error as the story; only add where the old site is.
+          throw new Error(`${error.message} The previous site could not be put back; it was left at ${previous}.`, { cause: error });
+        }
+      }
+      throw existing ? unchanged(error) : error;
+    }
+    // The new site is already live, so failing to clear the old one is a warning, not a failed build.
+    if (existing) {
+      try {
+        await ops.rm(previous, keep);
+      } catch (error) {
+        warnings.push(`Built, but could not remove the previous site at ${previous}: ${error.message}. It is safe to delete; the next build tries again.`);
+      }
+    }
+  } catch (error) {
+    await fs.rm(staging, keep).catch(() => {});
+    throw error;
+  }
+  return { outDir, versions: manifest.versions.length, warnings };
+}

package/src/cli/static-files.js

@@ -0,0 +1,46 @@
+// Serving files from a folder over local HTTP. Shared by afterimage dev and the end-to-end harness, so both guard paths the same way.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+// A save keeps any file, so this covers what prototypes commonly ship. Anything else is sent as application/octet-stream.
+export const TYPES = {
+  html: 'text/html; charset=utf-8', js: 'text/javascript', mjs: 'text/javascript', css: 'text/css', json: 'application/json',
+  webmanifest: 'application/manifest+json', xml: 'application/xml', pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown',
+  csv: 'text/csv', vtt: 'text/vtt', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+  webp: 'image/webp', avif: 'image/avif', ico: 'image/x-icon', woff: 'font/woff', woff2: 'font/woff2', ttf: 'font/ttf', otf: 'font/otf',
+  mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mp3: 'audio/mpeg', m4a: 'audio/mp4', wav: 'audio/wav', ogg: 'audio/ogg',
+  wasm: 'application/wasm', glb: 'model/gltf-binary', gltf: 'model/gltf+json', riv: 'application/octet-stream'
+};
+
+// The decoded path of a request URL, or null when it can't be decoded or holds a NUL byte (no file has one, and
+// the file system would throw on it).
+export function requestPath(url) {
+  try {
+    const decoded = decodeURIComponent(new URL(url, 'http://localhost').pathname);
+    return decoded.includes('\0') ? null : decoded;
+  } catch {
+    return null;
+  }
+}
+
+// The file under `root` that `relative` (a URL path starting with /) asks for, or null when it would leave
+// `root` or reach a hidden file or folder. Both slashes count as separators, since Windows accepts either.
+export function fileFor(root, relative) {
+  if (relative.split(/[\\/]/).some(part => part.startsWith('.'))) return null;
+  const file = path.resolve(root, '.' + relative + (relative.endsWith('/') ? 'index.html' : ''));
+  return file.startsWith(path.resolve(root) + path.sep) ? file : null;
+}
+
+// Sends `file` uncached, or a 404 when it isn't there.
+export async function sendFile(res, file) {
+  try {
+    const data = await fs.readFile(file);
+    res.setHeader('Content-Type', TYPES[path.extname(file).slice(1).toLowerCase()] || 'application/octet-stream');
+    res.setHeader('Cache-Control', 'no-store');
+    res.end(data);
+  } catch (error) {
+    if (!['ENOENT', 'EISDIR', 'ENOTDIR'].includes(error.code)) console.error(error);
+    res.statusCode = 404;
+    res.end('Not found');
+  }
+}

package/src/engine/manifest.js

@@ -0,0 +1,19 @@
+export function validateManifest(manifest) {
+  if (manifest?.schemaVersion !== 1 || !Array.isArray(manifest.versions) || !manifest.versions.length) {
+    throw new Error('Version history is missing or has an unsupported format.');
+  }
+  let previous = Infinity;
+  for (const version of manifest.versions) {
+    const number = Number(version?.id?.slice(1));
+    if (!/^v[1-9]\d*$/.test(version?.id) || !Number.isSafeInteger(number) || number >= previous ||
+        version.file !== `versions/${version.id}/index.html` || version.label !== `Version ${number}` ||
+        typeof version.name !== 'string' || !version.name.trim() ||
+        !Array.isArray(version.notes) || version.notes.some(note => typeof note !== 'string') ||
+        !/^[a-f0-9]{64}$/.test(version.sha256) ||
+        (version.savedAt !== null && (typeof version.savedAt !== 'string' || !Number.isFinite(Date.parse(version.savedAt))))) {
+      throw new Error('Version history contains an invalid entry.');
+    }
+    previous = number;
+  }
+  return manifest;
+}

package/src/runtime/frame.js

@@ -0,0 +1,84 @@
+// The frame runtime, served at /afterimage/frame.js. A save puts it first in every saved page's <head>, as
+// <script src="/afterimage/frame.js" data-afterimage-version="vN">, so it runs before any of the app's own scripts.
+// It is a classic script for that reason, and so it cannot import map.js; the one mapping it needs is inlined.
+// sw.js explains the approach and its limits.
+(() => {
+  const version = document.currentScript?.dataset.afterimageVersion;
+  const prefix = `/afterimage/versions/${version}`;
+  if (!version || !location.pathname.startsWith(`${prefix}/`)) return;
+  // The viewer reads this to tell which version a frame holds, since the URL below may no longer say.
+  window.__afterimageVersion = version;
+
+  // The app's own path at the root, so its router matches: .../vN/index.html -> /, .../vN/about/index.html -> /about/,
+  // .../vN/two.html -> /two.html. Relative URLs now resolve against it too; the worker maps the result back.
+  // Only a frame the worker controls is moved. Without one (no service workers on plain http, a host that won't serve
+  // sw.js) nothing would map root paths back, so the page keeps its own URL and its relative files still load from
+  // the version folder.
+  const mapped = Boolean(window.navigator?.serviceWorker?.controller);
+  const own = mapped ? location.pathname.slice(prefix.length).replace(/(^|\/)index\.html$/, '$1') : location.pathname;
+  // The file this document was loaded from, so the viewer can tell its own page from one reached by a hard link.
+  window.__afterimageFile = location.pathname;
+  if (mapped) history.replaceState(history.state, '', own + location.search + location.hash);
+
+  // The page the viewer compares: the frame's path as the app leaves it on its own. An app that redirects on load
+  // (replaceState to /home, / to /en) settles there. The person's first press or key inside the frame freezes it, so
+  // a route they open afterwards is not the page being compared. currententrychange follows the app's own
+  // same-document moves once they commit; load catches the rest, and is the only check without the Navigation API.
+  // Limits: without it, a move after load is missed; a redirect to another document (location.replace('/en')) loads
+  // another file, which the viewer does not compare; a press before the app has moved freezes the path early.
+  window.__afterimagePath = own + location.search;
+  let touched = false;
+  const follow = () => {
+    if (!touched) window.__afterimagePath = location.pathname + location.search;
+  };
+  const freeze = () => {
+    follow();
+    touched = true;
+  };
+  window.addEventListener('pointerdown', freeze, true);
+  window.addEventListener('keydown', freeze, true);
+  window.addEventListener('load', follow);
+  if (window.navigation) navigation.addEventListener('currententrychange', follow);
+
+  // Where a navigation to `href` belongs: same-origin paths outside /afterimage/ move into this version. Anything
+  // else (another origin, the viewer, a path already in a version) is left alone and gets null. So are blob:, data:
+  // and other non-http URLs: a blob: URL has this page's origin but no path to move, and would come back unchanged.
+  const inVersion = href => {
+    const url = new URL(href, location.href);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+    if (url.origin !== location.origin || url.pathname === '/afterimage' || url.pathname.startsWith('/afterimage/')) return null;
+    url.pathname = prefix + url.pathname;
+    return url.href;
+  };
+
+  // A page navigation to /about is outside the worker's scope, so it would load the live app. The Navigation API
+  // sees every one (links, location.assign and href, forms) and is the only way to catch location.assign, which
+  // cannot be patched. Same-document navigations (a router's pushState) are left alone, and so are traversals,
+  // downloads and POST forms, which cannot be re-sent elsewhere.
+  if (window.navigation) {
+    navigation.addEventListener('navigate', event => {
+      if (event.destination.sameDocument || !event.cancelable || event.navigationType === 'traverse' || event.downloadRequest !== null || event.formData) return;
+      const target = inVersion(event.destination.url);
+      // Redirecting to where it already goes would only start this handler again.
+      if (!target || target === event.destination.url) return;
+      event.preventDefault();
+      const redirect = navigation.navigate(target, { history: event.navigationType === 'push' ? 'auto' : 'replace' });
+      // Both reject when the redirect is cut short (the viewer moves the frame meanwhile); that is not the app's error.
+      redirect.committed.catch(() => {});
+      redirect.finished.catch(() => {});
+    });
+    return;
+  }
+
+  // Without the Navigation API only plain link clicks can be caught. This listens on window in the bubble phase, so
+  // it runs after the app's own handlers and leaves alone any click a router already took (defaultPrevented).
+  window.addEventListener('click', event => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const link = event.target instanceof Element ? event.target.closest('a[href]') : null;
+    if (!link || typeof link.href !== 'string' || (link.target && link.target !== '_self') || link.hasAttribute('download')) return;
+    const target = inVersion(link.href);
+    if (!target) return;
+    event.preventDefault();
+    location.assign(target);
+  });
+})();

package/src/runtime/map.js

@@ -0,0 +1,79 @@
+// Pure helpers for the frame runtime. history.js imports this module in node. sw.js is a classic worker, which cannot
+// import an ES module, so it carries its own copy of mapRequest, versionInPath and isServedPath; tests/runtime.test.mjs
+// runs one table against both copies so they cannot drift apart.
+
+const served = '/afterimage';
+const versionId = /^v[1-9]\d*$/;
+
+// The viewer, the runtime and the saved versions: everything Afterimage itself serves.
+export const isServedPath = pathname => pathname === served || pathname.startsWith(`${served}/`);
+
+// The version a document lives in, from its path: /afterimage/versions/v3/... -> 'v3'. Anything else -> null.
+export function versionInPath(pathname) {
+  const match = /^\/afterimage\/versions\/(v[1-9]\d*)\//.exec(pathname);
+  return match ? match[1] : null;
+}
+
+// Where a request from a version's document really lives. A built app asks for /assets/x.js as if it were at the
+// root; from v3 that is /afterimage/versions/v3/assets/x.js. Requests already under /afterimage/ (relative URLs,
+// the runtime itself) and requests from a client of no known version pass through unchanged. Takes a root path
+// or an absolute URL and returns the same kind. The caller checks the origin.
+export function mapRequest({ clientVersion, url }) {
+  if (typeof clientVersion !== 'string' || !versionId.test(clientVersion)) return url;
+  const absolute = /^[a-z][a-z\d+.-]*:/i.test(url);
+  const parsed = new URL(url, 'http://afterimage.invalid');
+  if (isServedPath(parsed.pathname)) return url;
+  parsed.pathname = `${served}/versions/${clientVersion}${parsed.pathname}`;
+  return absolute ? parsed.href : parsed.pathname + parsed.search + parsed.hash;
+}
+
+// The one tag a save adds to each page. A classic script, so it runs before anything else on the page.
+export const frameTag = id => `<script src="/afterimage/frame.js" data-afterimage-version="${id}"></script>`;
+// Anchored: only a tag at the insertion point counts as ours. The same text elsewhere (a string in a script) is content.
+const savedTag = /^<script src="\/afterimage\/frame\.js" data-afterimage-version="v[1-9]\d*"><\/script>/;
+
+// Everything that may sit before <head> in a page: a byte order mark (as a character, or as UTF-8 bytes read as
+// latin1, which is how a save reads them), white space, comments, <?...?> and the doctype.
+const bom = /^(?:\uFEFF|\xEF\xBB\xBF)/;
+const space = /^[\t\n\f\r ]+/;
+const prolog = /^(?:<!--[\s\S]*?-->|<\?[^>]*>|<!doctype[^>]*>)/i;
+// An open tag with any attributes, quoted values may hold ">". The lookahead keeps <header> from counting as <head>.
+const openTag = name => new RegExp(`^<${name}(?=[\\t\\n\\f\\r />])(?:[^>"']|"[^"]*"|'[^']*')*>`, 'i');
+const htmlTag = openTag('html');
+const headTag = openTag('head');
+const isDocument = /<!doctype[\t\n\f\r >]|<(?:html|head)(?=[\t\n\f\r />])/i;
+
+// Puts the frame tag first in <head>, inserting it and changing no other byte. Without a <head> tag it goes right
+// after <html ...>, else after the doctype and any comments, else at the start; the parser puts it in the head either
+// way. A page that already has the tag there (saved from a version's own files) only has its version id updated, so
+// a tag is never doubled and the same build always injects to the same bytes.
+// Only a page someone opens gets the tag, and a fragment a prototype fetches and inserts (htmx's hx-get, fetch and
+// innerHTML) is left as it is: a tag there would become its first child, and htmx would run it. A page is told apart by
+// a doctype, an <html> or a <head>, in any case. A version's entry page always gets it (page: true), since a hand-written
+// index.html may start straight at <h1>.
+export function injectFrameScript(html, id, { page = isDocument.test(html) } = {}) {
+  if (!page) return html;
+  let position = bom.exec(html)?.[0].length ?? 0;
+  let insertAt = position;
+  const skip = pattern => {
+    const match = pattern.exec(html.slice(position));
+    if (match) position += match[0].length;
+    return Boolean(match);
+  };
+  const skipProlog = () => {
+    for (;;) {
+      skip(space);
+      if (!skip(prolog)) return;
+      insertAt = position;
+    }
+  };
+  skipProlog();
+  if (skip(htmlTag)) {
+    insertAt = position;
+    skipProlog();
+  }
+  if (skip(headTag)) insertAt = position;
+  const rest = html.slice(insertAt);
+  const existing = savedTag.exec(rest);
+  return html.slice(0, insertAt) + frameTag(id) + (existing ? rest.slice(existing[0].length) : rest);
+}

package/src/runtime/sw.js

@@ -0,0 +1,218 @@
+// The frame runtime's service worker, served at /afterimage/sw.js with scope /afterimage/.
+//
+// Approach: each saved page carries frame.js (added at save time), which rewrites the frame's URL with replaceState
+// from /afterimage/versions/vN/<path> to /<path>, so the app's router sees its own paths. Built apps also ask for
+// root paths (/assets/x.js, /_next/...). This worker answers those from the version's folder. Nothing in it knows
+// any framework. The alternatives (a relative base set through the framework's config, rewriting paths at save
+// time) need per-framework work and miss URLs built at runtime, so they were not used.
+//
+// A classic worker, not a module one, so it runs wherever service workers do. It cannot import map.js (an ES module
+// that history.js uses in node), so the three helpers below are an inline copy; tests/runtime.test.mjs runs the same
+// table against both copies.
+//
+// Why this works:
+// - Scope. A navigation is routed by the destination URL's scope, so the frames (/afterimage/versions/vN/...) are
+//   controlled and the live app at / never is. If the app registers its own worker at scope /, the longer
+//   /afterimage/ scope still wins for the viewer and the frames, and ours never reaches the root.
+// - Subresources. A controlled document's requests come here whatever their URL, also after replaceState moved
+//   the document to /<path>. So a root path from a version maps into the version, and a request already under
+//   /afterimage/ (a relative URL resolved before the rewrite, the runtime itself) passes through.
+// - Response URL. A mapped answer is a new Response with no URL of its own, so the page treats it as coming from the
+//   path it asked for. Otherwise a module would get the version folder as its base URL, and a split chunk's
+//   "./index.js" would be a second copy of the entry module, run twice.
+// - Versions per client. The worker learns a frame's version from the navigation that creates it
+//   (resultingClientId on the request to /afterimage/versions/vN/...). It keeps that in memory and in the Cache API,
+//   keyed by client id, because the browser stops idle workers and a restarted one has no memory. Unknown clients
+//   (the viewer, anything that never navigated into a version) pass through.
+// - Navigations. A frame going to /about is out of scope, so this worker never sees it. frame.js catches those
+//   and sends them to /afterimage/versions/vN/about instead.
+// - Clean URLs. Static hosts answer /about from about.html (Netlify by default, Vercel with cleanUrls) or redirect it
+//   to /about/ when there is an about/index.html, and built apps rely on that: Next's static export writes about.html,
+//   links to /about and sends HEAD /about before it prefetches; Astro writes about/index.html and links to /about.
+//   Whatever serves the version folders may do neither (afterimage dev and plain file servers do not), so a 404 for
+//   a path in a version, page or subresource, is tried again here the same way: <path>.html answers in its place,
+//   and <path>/index.html turns it into a redirect to <path>/. The app sees the path it asked for, as on such a host.
+//   A path ending in / or in a file name with an extension (/x.js, /about.html, Next's /about.txt), and any answer
+//   other than 404, are left as the host gave them, so a missing asset costs no extra requests.
+// - Timing. The viewer waits until this worker is active before it creates frames, and install/activate take over
+//   at once (skipWaiting, clients.claim), so a frame's first request is already mapped.
+// - History. The viewer moves a frame to another version with location.replace, so its own version switches add no
+//   history entries for Back to land on.
+//
+// Known limits. Each of these reaches the live app at the root instead of the version:
+// - Reloading a frame from the browser's menu, and going back or forward to an entry of a document the frame has
+//   left: after a hard link, or after a router's pushState followed by a version switch. Those entries hold the
+//   rewritten /<path>, which is out of scope. A router's own back and forward inside one document work.
+// - Links that open elsewhere: target=_blank, _top and _parent (the navigation happens in another window, which
+//   frame.js does not run in), and download links (a download is not a navigation frame.js can redirect).
+// - POST forms, which cannot be re-sent to another URL.
+// - The app's own iframes: their navigations are their own, and an about:blank child is not controlled.
+// - Without the Navigation API (older Safari) frame.js sees only plain link clicks, not location.assign or forms.
+// - Requests made by a version's own Web Workers.
+// - Hosts that answer a missing file with 403 instead of 404 (S3 and similar object stores) get no clean-URL
+//   fallback: /about stays a 404 inside a version when only about.html exists (a miss, not the live app).
+// - Without service workers (http on a non-localhost address, a host that does not serve sw.js as JavaScript) the
+//   viewer still renders. frame.js then leaves each page at its own URL, so relative files load from the version,
+//   but root paths (/assets/x.js) reach the live app: a built app renders unstyled, and its router sees
+//   /afterimage/versions/vN/... instead of its own paths.
+// And one that comes with versions sharing the live app's origin: an old version's code runs there. It can register
+// a worker at scope / (its register('/sw.js') resolves against the root) and write cookies, localStorage and
+// IndexedDB that the live app then reads.
+
+const served = '/afterimage';
+const versionId = /^v[1-9]\d*$/;
+
+// ---- inline copy of map.js (keep in step; tests/runtime.test.mjs checks both) ----
+function isServedPath(pathname) {
+  return pathname === served || pathname.startsWith(`${served}/`);
+}
+
+function versionInPath(pathname) {
+  const match = /^\/afterimage\/versions\/(v[1-9]\d*)\//.exec(pathname);
+  return match ? match[1] : null;
+}
+
+function mapRequest({ clientVersion, url }) {
+  if (typeof clientVersion !== 'string' || !versionId.test(clientVersion)) return url;
+  const absolute = /^[a-z][a-z\d+.-]*:/i.test(url);
+  const parsed = new URL(url, 'http://afterimage.invalid');
+  if (isServedPath(parsed.pathname)) return url;
+  parsed.pathname = `${served}/versions/${clientVersion}${parsed.pathname}`;
+  return absolute ? parsed.href : parsed.pathname + parsed.search + parsed.hash;
+}
+// ---- end of the copy ----
+
+const store = 'afterimage-clients';
+const keyFor = clientId => new URL(`/afterimage/__clients/${encodeURIComponent(clientId)}`, self.location.href).href;
+// A frame being created is not in clients.matchAll() until its document is ready, and the viewer creates two at once.
+// So an entry is only dropped once its client has been listed and then is gone. Entries never listed (a navigation
+// that was abandoned) are kept, but only the newest few, so the store stays small without any timing.
+const unseenKept = 16;
+// clientId -> { id, seen }: the version, and whether the client has been listed yet.
+const versions = new Map();
+
+self.addEventListener('install', () => self.skipWaiting());
+self.addEventListener('activate', event => event.waitUntil(self.clients.claim()));
+
+async function read(response) {
+  try {
+    return response ? JSON.parse(await response.text()) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function remember(clientId, entry) {
+  const cache = await caches.open(store);
+  await cache.put(keyFor(clientId), new Response(JSON.stringify(entry)));
+  // Frames come and go as the viewer switches versions; drop what belongs to clients that are gone.
+  const alive = new Set((await self.clients.matchAll({ includeUncontrolled: true })).map(client => client.id));
+  const unseen = [];
+  for (const request of await cache.keys()) {
+    const known = decodeURIComponent(new URL(request.url).pathname.split('/').pop());
+    const value = await read(await cache.match(request));
+    if (!value) {
+      await cache.delete(request);
+    } else if (alive.has(known)) {
+      if (!value.seen) await cache.put(request, new Response(JSON.stringify({ ...value, seen: true })));
+      versions.set(known, { ...value, seen: true });
+    } else if (value.seen) {
+      await cache.delete(request);
+      versions.delete(known);
+    } else {
+      unseen.push([request, known]);
+    }
+  }
+  // keys() lists entries oldest first, so the end of the list is the newest.
+  for (const [request, known] of unseen.slice(0, -unseenKept)) {
+    await cache.delete(request);
+    versions.delete(known);
+  }
+}
+
+// Storage can be blocked or full; then the request is treated as one from an unknown client and passes through.
+async function recall(clientId) {
+  try {
+    const value = await read(await (await caches.open(store)).match(keyFor(clientId)));
+    if (value) versions.set(clientId, value);
+    return value?.id;
+  } catch {
+    return undefined;
+  }
+}
+
+// `request` sent to `url` instead. The init is spelled out: a Request passed as init would drop its body's streaming
+// mode. new Request refuses mode 'navigate'; for a page's own origin it amounts to 'same-origin'. Only GET and HEAD
+// get here.
+function like(request, url, method = request.method) {
+  const { headers, mode, credentials, cache, redirect, referrer, referrerPolicy, integrity, signal } = request;
+  return new Request(url, { method, headers, mode: mode === 'navigate' ? 'same-origin' : mode, credentials, cache, redirect, referrer, referrerPolicy, integrity, signal });
+}
+
+// The response with no URL of its own (see Response URL above). A request with redirect 'manual' gets an opaque
+// redirect (status 0), which a new Response cannot carry. It is passed back as it is: a redirect has no body or base
+// URL to keep, and the page follows it or not as it asked. redirect 'error' needs nothing: fetch rejects on a
+// redirect, as it would have without the worker.
+function plain(response) {
+  if (response.type === 'opaqueredirect' || response.status === 0) return response;
+  return new Response(response.body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+
+// A response that is not passed on. Its body would otherwise stay open until the browser collects it.
+const drop = response => response.body?.cancel().catch(() => {});
+
+// What the page gets for `found`, the host's answer for `inVersion` (the path in the version folder), with clean URLs
+// (see above): the host's answer or <path>.html, without a URL of their own, or a redirect. `asked` is the URL the
+// request was made with, which the redirect adds the slash to, so the page goes on to ask for the path it would on
+// such a host. The redirect goes back as Response.redirect made it, not through plain().
+async function withCleanUrls(request, inVersion, asked, found) {
+  const { pathname } = new URL(inVersion);
+  const name = pathname.slice(pathname.lastIndexOf('/') + 1);
+  if (found.status !== 404 || !name || /\.[^.]+$/.test(name)) return plain(found);
+  const at = suffix => {
+    const url = new URL(inVersion);
+    url.pathname += suffix;
+    return url.href;
+  };
+  const page = await fetch(like(request, at('.html')));
+  if (page.ok) {
+    drop(found);
+    return plain(page);
+  }
+  drop(page);
+  const index = await fetch(like(request, at('/index.html'), 'HEAD'));
+  drop(index);
+  if (!index.ok) return plain(found);
+  drop(found);
+  const slashed = new URL(asked);
+  slashed.pathname += '/';
+  return Response.redirect(slashed.href, 301);
+}
+
+async function answer(request, id) {
+  if (!id) return fetch(request);
+  const inVersion = mapRequest({ clientVersion: id, url: request.url });
+  return withCleanUrls(request, inVersion, request.url, await fetch(like(request, inVersion)));
+}
+
+self.addEventListener('fetch', event => {
+  const { request } = event;
+  const url = new URL(request.url);
+  if (url.origin !== self.location.origin) return;
+  if (request.mode === 'navigate') {
+    const id = versionInPath(url.pathname);
+    if (!id) return;
+    if (event.resultingClientId) {
+      const entry = { id, seen: false };
+      versions.set(event.resultingClientId, entry);
+      event.waitUntil(remember(event.resultingClientId, entry).catch(() => {}));
+    }
+    // Answered here only for the clean URLs; a page the host has comes back with its own status, headers and body.
+    event.respondWith(fetch(request).then(found => withCleanUrls(request, request.url, request.url, found)));
+    return;
+  }
+  // A static site has nothing that takes a POST, so other methods pass through with their bodies untouched.
+  if (!event.clientId || isServedPath(url.pathname) || (request.method !== 'GET' && request.method !== 'HEAD')) return;
+  const known = versions.get(event.clientId)?.id;
+  event.respondWith(known ? answer(request, known) : recall(event.clientId).then(id => answer(request, id)));
+});