afterimage-cli 0.1.0 → 0.2.0

package/src/cli/commands/init.js

@@ -35,7 +35,10 @@ const skillHint = [
   ...Object.entries(agents).map(([name, agent]) => `  npx afterimage init --agent ${name}   copies the ${agent.what} to ${agent.to}${agent.what === 'skill' ? '/' : ''}`)
 ].join('\n');
 
-const nextStep = 'Next: npx afterimage save "First version"';
+// The dev script starts Afterimage beside the app when init could set it; otherwise the app's own command goes after --.
+const nextStep = devReady => (devReady
+  ? 'Next: npm run dev, then use the Afterimage pill on your prototype to save versions and see them all.'
+  : 'Next: start your dev server through Afterimage with npx afterimage dev -- <your dev command>, then use the pill on your prototype to save versions and see them all.');
 
 async function isFolder(file) {
   try {
@@ -146,22 +149,39 @@ async function planConfig(cwd, flags, ctx) {
   };
 }
 
-async function planPackage(cwd) {
+// Read and checked before anything else, so a bad package.json stops init before any question.
+async function readPackage(cwd) {
   const file = path.join(cwd, 'package.json');
   const { bom, body: before } = await readJsonText(file);
   const manifest = before === null ? { private: true, scripts: {} } : parseJson(before, 'package.json');
   if (manifest.scripts !== undefined && (!manifest.scripts || typeof manifest.scripts !== 'object' || Array.isArray(manifest.scripts))) {
     throw new Error('package.json "scripts" must be an object.\nFix it, then run "afterimage init" again.');
   }
+  return { file, bom, before, manifest };
+}
+
+// The pill on the prototype needs afterimage dev running beside the app. So the project's own dev script starts it:
+// "vite" becomes "afterimage dev -- vite", which runs both and stops both. A plain folder with no dev script gets
+// "afterimage dev", which serves the folder itself. Run again, it changes nothing.
+const devWrap = 'afterimage dev';
+function devScript(existing, config) {
+  if (typeof existing.dev === 'string') return existing.dev.trim().startsWith(devWrap) ? null : `${devWrap} -- ${existing.dev}`;
+  return config.build ? null : devWrap;
+}
+
+function planPackage({ file, bom, before, manifest }, config) {
   const existing = manifest.scripts ?? {};
   const added = Object.keys(scripts).filter(name => !Object.hasOwn(existing, name));
   const notes = [];
   if (Object.hasOwn(existing, 'afterimage:build') && existing['afterimage:build'] !== scripts['afterimage:build']) {
     notes.push(`package.json already has "afterimage:build": "${existing['afterimage:build']}". The host config runs that script, so it should be "${scripts['afterimage:build']}".`);
   }
-  if (!added.length) return { change: null, notes, apply: null };
-  manifest.scripts = { ...existing, ...Object.fromEntries(added.map(name => [name, scripts[name]])) };
-  const what = `added ${plural(added.length, 'script')}`;
+  const dev = devScript(existing, config);
+  if (!added.length && !dev) return { change: null, notes, apply: null };
+  const wraps = dev && Object.hasOwn(existing, 'dev');
+  manifest.scripts = { ...existing, ...Object.fromEntries(added.map(name => [name, scripts[name]])), ...(dev ? { dev } : {}) };
+  const count = added.length + (dev && !wraps ? 1 : 0);
+  const what = [count ? `added ${plural(count, 'script')}` : null, wraps ? 'dev now starts Afterimage too' : null].filter(Boolean).join('; ');
   return {
     change: `${before === null ? 'Created' : 'Updated'} package.json (${what})`,
     notes,
@@ -169,6 +189,95 @@ async function planPackage(cwd) {
   };
 }
 
+// The overlay's one line. A plain page loads it from the history's own folder, which afterimage dev and the deployed
+// site both serve; a Vite page imports it from the package, since Vite's dev server serves no /afterimage/.
+const pillTag = '<script src="/afterimage/overlay.js" defer></script>';
+const pillImport = "<script type=\"module\">import 'afterimage-cli/overlay';</script>";
+const pillNotes = {
+  'next-static': "Add the Afterimage pill to your app: create app/afterimage.tsx with\n  'use client';\n  import 'afterimage-cli/overlay';\n  export default function Afterimage() { return null; }\nand put <Afterimage /> inside <body> in app/layout.tsx.",
+  astro: "Add the Afterimage pill to your app: put <script>import 'afterimage-cli/overlay';</script> in the layout every page uses.",
+  'sveltekit-static': "Add the Afterimage pill to your app: put import 'afterimage-cli/overlay'; in the <script> of src/routes/+layout.svelte.",
+  unknown: "Add the Afterimage pill to your app: import 'afterimage-cli/overlay' once in the code every page loads."
+};
+
+// Before the last </body>, or at the end of the file when it has none, on a line of its own. When </body> starts its
+// line, the new line takes the indent of the line above it, so it sits with the page's other scripts.
+function withLine(text, line) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const at = text.search(/<\/body>(?![\s\S]*<\/body>)/i);
+  if (at === -1) return `${text}${text === '' || text.endsWith('\n') ? '' : eol}${line}${eol}`;
+  const lineStart = text.lastIndexOf('\n', at - 1) + 1;
+  if (!/^[ \t]*$/.test(text.slice(lineStart, at))) return `${text.slice(0, at)}${eol}${line}${eol}${text.slice(at)}`;
+  const above = text.slice(0, lineStart).replace(/\r?\n$/, '').split(/\r?\n/).pop();
+  return `${text.slice(0, lineStart)}${above.match(/^[ \t]*/)[0]}${line}${eol}${text.slice(lineStart)}`;
+}
+
+// Every file under `dir` whose name passes `want`, never going into hidden folders, installed packages or `skip`
+// (absolute folders), which a real project's node_modules makes worth not reading at all.
+async function walk(dir, want, skip) {
+  const found = [];
+  for (const entry of await fs.readdir(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    if (entry.isDirectory()) {
+      if (!skip.includes(full)) found.push(...await walk(full, want, skip));
+    } else if (entry.isFile() && want(entry.name)) {
+      found.push(full);
+    }
+  }
+  return found;
+}
+
+// Every .html page in the prototype's folder, minus the history and Afterimage's own output.
+async function plainPages(cwd, config) {
+  const skip = [config.history, config.out].map(folder => path.resolve(cwd, folder));
+  const pages = await walk(path.resolve(cwd, config.source), name => /\.html?$/i.test(name), skip);
+  return pages.map(full => ({ full, name: path.relative(cwd, full).replace(/\\/g, '/') })).sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+// Whether the app's own code already loads the overlay, so init stops asking once the line is in. Only source files
+// are read: not installed packages, hidden folders, the history, or what a build wrote.
+const codeFile = /\.(m?[jt]sx?|svelte|astro|vue|html?)$/i;
+async function loadsPill(cwd, config) {
+  const skip = [config.history, config.out, config.source].filter(folder => folder !== '.').map(folder => path.resolve(cwd, folder));
+  for (const full of await walk(cwd, name => codeFile.test(name), skip)) {
+    const text = await readText(full);
+    if (text.includes('afterimage-cli/overlay') || text.includes('/afterimage/overlay.js')) return true;
+  }
+  return false;
+}
+
+async function planPill(cwd, config) {
+  let pages = [];
+  let line = pillTag;
+  const noteFor = async type => ({ change: null, notes: await loadsPill(cwd, config) ? [] : [pillNotes[type] ?? pillNotes.unknown], apply: null });
+  if (config.type === 'plain') {
+    pages = await plainPages(cwd, config);
+  } else if (config.type === 'vite') {
+    const index = path.join(cwd, 'index.html');
+    if (await readText(index) === null) return noteFor('unknown');
+    pages = [{ full: index, name: 'index.html' }];
+    line = pillImport;
+  } else {
+    return noteFor(config.type);
+  }
+  const writes = [];
+  for (const page of pages) {
+    const text = await readText(page.full);
+    if (text.includes('/afterimage/overlay.js') || text.includes('afterimage-cli/overlay')) continue;
+    writes.push({ ...page, text: withLine(text, line) });
+  }
+  if (!writes.length) return { change: null, notes: [], apply: null };
+  const names = writes.map(page => page.name);
+  return {
+    change: names.length === 1 ? `Added the Afterimage pill to ${names[0]}` : `Added the Afterimage pill to ${names.length} pages (${names.join(', ')})`,
+    notes: [],
+    apply: async () => {
+      for (const page of writes) await fs.writeFile(page.full, page.text);
+    }
+  };
+}
+
 // Adds each line that is not already there, in the file's own line ending.
 async function planLines(cwd, name, lines, isPresent) {
   const file = path.join(cwd, name);
@@ -274,11 +383,12 @@ export async function run(args, ctx) {
   // and detection (which reads package.json) still sees the project as it was.
   let plans;
   try {
-    const packagePlan = await planPackage(cwd);
+    const packageFile = await readPackage(cwd);
     const configPlan = await planConfig(cwd, flags, prompt);
     plans = [
       configPlan,
-      packagePlan,
+      planPackage(packageFile, configPlan.config),
+      await planPill(cwd, configPlan.config),
       await planLines(cwd, '.gitattributes', [`${configPlan.config.history}/** -text`], hasTextRule),
       // The save's lock and stage folders too, which a killed save can leave in the history folder.
       await planLines(cwd, '.gitignore', ['.afterimage/', `${configPlan.config.history}/.afterimage-*`, 'node_modules/'], hasIgnore),
@@ -302,6 +412,7 @@ export async function run(args, ctx) {
   if (notes.length) stdout.write(`${changes.length ? '\n' : ''}${notes.join('\n\n')}\n`);
   // With --agent the copy is in place, and a fresh one needs loading; without it, say how to add it.
   const agentLine = agent ? plans.at(-1).change && agents[agent].loads : skillHint;
-  stdout.write(`\n${agentLine ? `${agentLine}\n` : ''}${nextStep}\n`);
+  const dev = (await readPackage(cwd)).manifest.scripts?.dev;
+  stdout.write(`\n${agentLine ? `${agentLine}\n` : ''}${nextStep(typeof dev === 'string' && dev.trim().startsWith(devWrap))}\n`);
   return 0;
 }

package/src/cli/commands/save.js

@@ -31,11 +31,7 @@ export async function run(args, { cwd, stdout, stderr, buildStdio, largeHistory
   }
 
   const config = await readConfig(cwd);
-  if (config.build) await runBuild(config.build, cwd, { stdio: buildStdio });
-  const { version, unchanged, bytes, history } = await saveVersion(
-    { historyDir: path.resolve(cwd, config.history), sourceDir: path.resolve(cwd, config.source), exclude: await sourceExcludes(cwd, config) },
-    { name, notes: parsed.values.note ?? [] }
-  );
+  const { version, unchanged, bytes, history } = await saveProject({ projectDir: cwd, config, name, notes: parsed.values.note ?? [], buildStdio });
   if (unchanged) {
     stdout.write(`Nothing changed since ${version.id} "${version.name}". Nothing was saved.\n`);
     return 0;
@@ -49,7 +45,17 @@ export async function run(args, { cwd, stdout, stderr, buildStdio, largeHistory
   return 0;
 }
 
-export const sizeDocs = 'https://github.com/uxlucas/Afterimage/blob/main/docs/limits.md#history-size';
+// Builds the prototype when it has a build, then saves it as the next version. Shared by this command and the overlay's
+// Save button, which reaches it through afterimage dev.
+export async function saveProject({ projectDir, config, name, notes = [], buildStdio }) {
+  if (config.build) await runBuild(config.build, projectDir, { stdio: buildStdio });
+  return saveVersion(
+    { historyDir: path.resolve(projectDir, config.history), sourceDir: path.resolve(projectDir, config.source), exclude: await sourceExcludes(projectDir, config) },
+    { name, notes }
+  );
+}
+
+export const sizeDocs ='https://github.com/uxlucas/Afterimage/blob/main/docs/limits.md#history-size';
 
 // Decimal units, as macOS Finder and npm count them.
 export function formatSize(bytes) {

package/src/cli/hosts.js

@@ -21,7 +21,7 @@ export const cleanUrlRewrite = { source: '/:path((?!afterimage/|afterimage$).+)'
 // own builder takes over: @vercel/next finds .next/export-detail.json after the build and serves the export's folder (out/),
 // not outputDirectory, so /afterimage/ would not deploy. Vercel detects the framework from package.json, so this is keyed
 // on a dependency on next and not on the type init chose. It costs the live app the builder's _next/static caching and its
-// .html stripping, which the rewrite below brings back for the stripping. Other presets (Vite, Astro, SvelteKit) run in
+// .html stripping, which nextStaticCache and the rewrite below bring back. Other presets (Vite, Astro, SvelteKit) run in
 // @vercel/static-build, which uses outputDirectory ahead of the preset's own folder, and null would cost them their cache
 // headers or SPA fallback, so they are left as they are.
 // Source: https://github.com/vercel/vercel/blob/main/packages/next/src/index.ts
@@ -32,6 +32,15 @@ const hostSettings = (next) => (next ? { framework: null, buildCommand: hostBuil
 // is not caught and nothing loops.
 export const slashRedirect = { source: '/afterimage', destination: '/afterimage/' };
 
+// The long cache on a Next.js app's hashed files (/_next/static: content-hashed names, or the build id in the path), which
+// Vercel's Next.js builder and Netlify's Next.js runtime set and which framework: null and NETLIFY_NEXT_PLUGIN_SKIP give up.
+// Both hosts then serve them with max-age=0 (seen on real deploys, docs/checking-a-deploy.md). The source matches the live
+// app's paths only: a version's copies, under /afterimage/versions/vN/_next/static/, keep the host's default.
+const immutable = 'public, max-age=31536000, immutable';
+export const nextStaticCache = { source: '/_next/static/(.*)', headers: [{ key: 'Cache-Control', value: immutable }] };
+// Any rule of the project's own for those paths counts, whatever it sets.
+const isStaticCache = rule => typeof rule?.source === 'string' && rule.source.trim().startsWith('/_next/static/');
+
 // A rule counts as ours when it points at <path>.html and keeps /afterimage out, however the rest is spelled.
 const isCleanUrlRewrite = rule => typeof rule?.destination === 'string' && /^\/:\w+\*?\.html$/.test(rule.destination) && typeof rule.source === 'string' && rule.source.includes('afterimage');
 const fromAfterimage = rule => typeof rule?.source === 'string' && rule.source.trim().replace(/\/+$/, '') === slashRedirect.source;
@@ -75,7 +84,8 @@ export async function planVercel(cwd, { isTTY, ask }) {
   const file = path.join(cwd, 'vercel.json');
   const { bom, body: before } = await readJsonText(file);
   const settings = before === null ? {} : parseJson(before, 'vercel.json');
-  const wanted = hostSettings(await usesNext(cwd));
+  const next = await usesNext(cwd);
+  const wanted = hostSettings(next);
   const notes = [];
   if (await dependsOn(cwd, '@astrojs/vercel')) notes.push(astroVercelNote);
 
@@ -101,6 +111,7 @@ export async function planVercel(cwd, { isTTY, ask }) {
       lists.redirects = planList(settings, 'redirects', slashRedirect, isSlashRedirect, 'so /afterimage opens the viewer');
     }
   }
+  if (next) lists.headers = planList(settings, 'headers', nextStaticCache, isStaticCache, "for the long cache on the live app's /_next/static");
   const added = {};
   for (const [key, plan] of Object.entries(lists)) {
     if (plan.note) notes.push(plan.note);
@@ -116,14 +127,14 @@ export async function planVercel(cwd, { isTTY, ask }) {
     if (!agreed) {
       // Values to set, and entries to add to lists the project may already have: pasting must never replace its own rules.
       const lines = [`Left vercel.json as it is. To deploy the history with Afterimage, set:\n${JSON.stringify(wanted, null, 2).slice(2, -2)}`];
-      for (const [key, entry] of [['rewrites', cleanUrlRewrite], ['redirects', slashRedirect]]) {
+      for (const [key, entry] of [['rewrites', cleanUrlRewrite], ['redirects', slashRedirect], ['headers', nextStaticCache]]) {
         if (key in added) lines.push(`and add this to "${key}", keeping the rules already there:\n${JSON.stringify(entry, null, 2)}`);
       }
       return { change: null, notes: [lines.join('\n'), ...notes], apply: null };
     }
     set.unshift(...differs.filter(key => !set.includes(key)));
   }
-  const order = [...Object.keys(wanted), 'rewrites', 'redirects'];
+  const order = [...Object.keys(wanted), 'rewrites', 'redirects', 'headers'];
   const text = JSON.stringify({ ...settings, ...wanted, ...added }, null, 2);
   return {
     change: before === null ? 'Created vercel.json' : `Updated vercel.json (set ${order.filter(key => set.includes(key)).join(', ')})`,
@@ -151,24 +162,30 @@ const usesNext = cwd => dependsOn(cwd, 'next');
 // deploy. NETLIFY_NEXT_PLUGIN_SKIP makes it step aside. Read in opennextjs-netlify's source (src/index.ts,
 // src/build/content/static.ts), not tried on a real deploy. Netlify answers /about from about.html on its own.
 const skipRuntime = 'NETLIFY_NEXT_PLUGIN_SKIP';
+// nextStaticCache, for Netlify. Its paths match the live app's only, as on Vercel.
+const netlifyStaticCache = `[[headers]]\n  for = "/_next/static/*"\n  [headers.values]\n    Cache-Control = "${immutable}"\n`;
 
 export async function planNetlify(cwd) {
   const file = path.join(cwd, 'netlify.toml');
   const before = await readText(file);
   const next = await usesNext(cwd);
   if (before === null) {
-    const environment = next ? `\n[build.environment]\n  ${skipRuntime} = "true"\n` : '';
-    return { change: 'Created netlify.toml', notes: [], apply: writer(file, `[build]\n  command = "${hostBuild}"\n  publish = "${hostOutput}"\n${environment}`) };
+    const nextOnly = next ? `\n[build.environment]\n  ${skipRuntime} = "true"\n\n${netlifyStaticCache}` : '';
+    return { change: 'Created netlify.toml', notes: [], apply: writer(file, `[build]\n  command = "${hostBuild}"\n  publish = "${hostOutput}"\n${nextOnly}`) };
   }
   // TOML is not parsed or rewritten here: a hand edit is safer than a guessed merge.
   const hasCommand = new RegExp(`^\\s*command\\s*=\\s*["']${hostBuild}["']`, 'm').test(before);
   const hasPublish = new RegExp(`^\\s*publish\\s*=\\s*["']${hostOutput.replace('.', '\\.')}["']`, 'm').test(before);
   const hasSkip = new RegExp(`^\\s*${skipRuntime}\\s*=\\s*["']?(true|1)["']?\\s*$`, 'm').test(before);
+  // Any [[headers]] rule of the project's own for those paths counts, whatever it sets.
+  const hasCache = /^\s*for\s*=\s*["']\/_next\/static\//m.test(before);
   const wantsSkip = next && !hasSkip;
-  if (hasCommand && hasPublish && !wantsSkip) return { change: null, notes: [], apply: null };
+  const wantsCache = next && !hasCache;
+  if (hasCommand && hasPublish && !wantsSkip && !wantsCache) return { change: null, notes: [], apply: null };
   const lines = [];
   if (!hasCommand || !hasPublish) lines.push(`Under [build], set:\n  command = "${hostBuild}"\n  publish = "${hostOutput}"`);
   if (wantsSkip) lines.push(`Under [build.environment], set (so Netlify's Next.js runtime leaves the history in place instead of deploying out/):\n  ${skipRuntime} = "true"`);
+  if (wantsCache) lines.push(`To keep the long cache on the live app's /_next/static, which the runtime would have set, add:\n${netlifyStaticCache.trimEnd()}`);
   return {
     change: null,
     notes: [`netlify.toml already exists, so Afterimage left it alone. ${lines.join('\n')}`],

package/src/cli/site.js

@@ -65,7 +65,7 @@ async function checkCollision(sourceDir, excluded) {
 // 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 = {} }) {
+export async function assembleSite({ projectDir, config, viewerDir = packagedViewerDir, runtimeDir = packagedRuntimeDir, includeApp = true, allowEmpty = false, 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);
@@ -73,7 +73,8 @@ export async function assembleSite({ projectDir, config, viewerDir = packagedVie
   const warnings = [];
 
   const manifest = await verifyHistory(historyDir);
-  if (!manifest?.versions.length) throw new Error('Save a first version with: afterimage save "Name"');
+  // Dev may start before the first save, so the overlay can offer it; a deploy needs something to show.
+  if (!manifest?.versions.length && !allowEmpty) throw new Error('Save a first version with: afterimage save "Name"');
   try {
     await fs.access(path.join(viewerDir, 'index.html'));
   } catch {
@@ -130,8 +131,8 @@ export async function assembleSite({ projectDir, config, viewerDir = packagedVie
     }
     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) {
+    if (manifest) 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,
@@ -167,5 +168,5 @@ export async function assembleSite({ projectDir, config, viewerDir = packagedVie
     await fs.rm(staging, keep).catch(() => {});
     throw error;
   }
-  return { outDir, versions: manifest.versions.length, warnings };
+  return { outDir, versions: manifest?.versions.length ?? 0, warnings };
 }

package/src/runtime/overlay.js

@@ -0,0 +1,266 @@
+// The overlay: Afterimage's pill on the prototype itself, served at /afterimage/overlay.js and exported as
+// afterimage-cli/overlay. One line adds it to an app: a script tag in plain HTML, or an import in a bundled app.
+//
+// It finds the history on its own and draws nothing when there is none:
+// - on this machine, afterimage dev answers /afterimage/api/session, on the page's own origin (a plain prototype dev
+//   serves itself) or on ports 4321 to 4330 (beside the app's own dev server). There the pill can also save.
+// - on a built site, /afterimage/versions.json is next to the app, and the pill shows the history only.
+// How this copy was loaded says which, so a built site never asks for a helper, even served from this machine:
+// - a script tag dev served carries dev's stamp (window.__afterimageDev); any other script tag is a built site's copy.
+// - an import has no currentScript. Bundlers replace process.env.NODE_ENV, so a production build says it is one.
+// History opens the viewer as a layer over the page, in the same tab; the close button, Esc, or the viewer itself
+// (it posts afterimage:close when it is framed) close it again.
+//
+// It is plain JavaScript with no imports, so it runs as a classic script and as a module, and it does nothing where
+// there is no document (a server render of a bundled app). It draws in a shadow root, so the app's CSS can't reach it.
+// It stays out of saved versions, which are builds of the same app: frame.js marks those pages before any app code
+// runs, and any page in a frame is left alone too.
+(() => {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return;
+  if (window.__afterimageOverlay || window.__afterimageVersion) return;
+  try {
+    if (window.top !== window) return;
+  } catch {
+    return;
+  }
+  window.__afterimageOverlay = true;
+
+  const local = ['localhost', '127.0.0.1', '[::1]'].includes(location.hostname) || location.hostname.endsWith('.localhost');
+  const scriptTag = Boolean(document.currentScript);
+  const servedByDev = window.__afterimageDev === true;
+  let mode;
+  try {
+    // Written out in full so a bundler can replace it; with no bundler there is no process and this throws.
+    mode = process.env.NODE_ENV;
+  } catch { /* a script tag */ }
+  const inDev = local && (scriptTag ? servedByDev : mode !== 'production');
+  const helperPorts = Array.from({ length: 10 }, (_, i) => 4321 + i);
+
+  const getJson = async (url, timeout = 1500) => {
+    try {
+      const response = await fetch(url, { cache: 'no-store', signal: AbortSignal.timeout(timeout) });
+      return response.ok ? await response.json() : null;
+    } catch {
+      return null;
+    }
+  };
+  const session = async base => {
+    const body = await getJson(`${base}/afterimage/api/session`);
+    return body?.afterimage === 1 ? { base, ...body } : null;
+  };
+
+  // Where the history is, or null. On this machine a running afterimage dev comes first: some dev servers (Vite's)
+  // serve the project's own afterimage/versions.json at the same path a deployed site does, and that copy can't save.
+  // A host that answers every path with the app's own page fails the JSON checks.
+  async function find() {
+    if (inDev && servedByDev) {
+      const here = await session(location.origin);
+      if (here) return here;
+    } else if (inDev) {
+      // One port at a time from 4321, stopping at the first helper: usually that is the first ask, and a port held by
+      // some other server costs one quick refusal (which the browser logs) rather than ten at once.
+      for (const port of helperPorts) {
+        const found = await session(`http://${location.hostname}:${port}`);
+        if (found) return found;
+      }
+    }
+    const manifest = await getJson('/afterimage/versions.json');
+    if (Array.isArray(manifest?.versions) && manifest.versions.length) {
+      const latest = manifest.versions[0];
+      return { base: location.origin, versions: manifest.versions.length, latest: { id: latest.id, name: latest.name }, canSave: false };
+    }
+    return null;
+  }
+
+  const css = `
+    :host { all: initial; }
+    * { box-sizing: border-box; }
+    .dock { position: fixed; right: 16px; bottom: 16px; z-index: 2147483646; font: 13px/1 system-ui, -apple-system, 'Segoe UI', sans-serif;
+      -webkit-font-smoothing: antialiased; color: #ededed; }
+    .pill { display: flex; align-items: center; gap: 2px; padding: 5px; border-radius: 999px; background: #1b1b1b;
+      box-shadow: 0 0 0 1px #ffffff14, 0 1px 2px #0000004d, 0 10px 28px #00000040; user-select: none; -webkit-user-select: none; }
+    .mark { flex: none; width: 34px; height: 34px; display: grid; place-items: center; }
+    .label { padding: 0 8px 0 2px; color: #8e8e8e; white-space: nowrap; font-variant-numeric: tabular-nums; }
+    .label b { color: #ededed; font-weight: 500; }
+    .sep { flex: none; width: 1px; height: 18px; margin: 0 4px; background: #ffffff14; }
+    button { appearance: none; height: 34px; margin: 0; padding: 0 12px; border: 0; border-radius: 999px; background: transparent;
+      color: inherit; font: inherit; line-height: 1; white-space: nowrap; cursor: pointer; }
+    button:hover:not(:disabled) { background: #2a2a2a; }
+    button:disabled { color: #5c5c5c; cursor: default; }
+    button:focus-visible, input:focus-visible { outline: 2px solid #ededed8c; outline-offset: 1px; }
+    .primary { background: #ededed; color: #1b1b1b; }
+    .primary:hover:not(:disabled) { background: #ffffff; }
+    input { width: 180px; height: 34px; margin: 0 2px 0 0; padding: 0 12px; border: 0; border-radius: 999px; background: #2a2a2a;
+      color: #ededed; font: inherit; }
+    input::placeholder { color: #8e8e8e; }
+    .status { padding: 0 12px 0 2px; white-space: nowrap; }
+    .status.bad { color: #e0705f; white-space: normal; max-width: 320px; line-height: 1.35; padding: 6px 12px 6px 2px; }
+    .busy { display: inline-block; width: 6px; height: 6px; margin-right: 8px; border-radius: 50%; background: #e5a83b;
+      vertical-align: 1px; animation: pulse 1s ease-in-out infinite alternate; }
+    @keyframes pulse { from { opacity: 0.35; } to { opacity: 1; } }
+    .layer { position: fixed; inset: 0; z-index: 2147483647; background: #1b1b1b; opacity: 0; transition: opacity 160ms ease-out; }
+    .layer[data-shown] { opacity: 1; }
+    .layer iframe { display: block; width: 100%; height: 100%; border: 0; }
+    .close { position: absolute; top: 12px; right: 12px; width: 34px; padding: 0; display: grid; place-items: center; background: #1b1b1b;
+      box-shadow: 0 0 0 1px #ffffff14, 0 6px 16px #00000040; color: #ededed; }
+    .close:hover:not(:disabled) { background: #2a2a2a; }
+    .visually-hidden { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+    @media (prefers-reduced-motion: reduce) { .layer { transition: none; } .busy { animation: none; } }
+  `;
+  // The wipe mark from afterimage's own icon: the first version on the left, today's on the right.
+  const mark = '<svg width="18" height="18" viewBox="0 0 32 32" aria-hidden="true"><rect width="32" height="32" rx="7" fill="#ededed"/><path d="M7 0h9v32H7a7 7 0 0 1-7-7V7a7 7 0 0 1 7-7z" fill="#8e8e8e"/><rect x="15" y="5" width="2" height="22" rx="1" fill="#1b1b1b"/></svg>';
+  const cross = '<svg width="12" height="12" viewBox="0 0 12 12" aria-hidden="true"><path d="M2 2l8 8M10 2l-8 8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>';
+
+  const host = document.createElement('afterimage-overlay');
+  const root = host.attachShadow({ mode: 'open' });
+  const make = (tag, props = {}) => Object.assign(document.createElement(tag), props);
+
+  let state = null;
+  let view = 'idle';
+  let message = '';
+  let timer = 0;
+  let layer = null;
+  let returnFocus = null;
+
+  const dock = make('div', { className: 'dock' });
+  const pill = make('div', { className: 'pill' });
+  pill.setAttribute('role', 'toolbar');
+  pill.setAttribute('aria-label', 'Afterimage');
+  dock.append(pill);
+  const live = make('div', { className: 'visually-hidden' });
+  live.setAttribute('aria-live', 'polite');
+  root.append(make('style', { textContent: css }), dock, live);
+
+  const say = text => { live.textContent = text; };
+  const later = (next, ms) => {
+    clearTimeout(timer);
+    timer = setTimeout(next, ms);
+  };
+  const button = (text, onClick, extra = {}) => {
+    const element = make('button', { type: 'button', textContent: text, ...extra });
+    element.addEventListener('click', onClick);
+    return element;
+  };
+
+  function render() {
+    pill.replaceChildren();
+    pill.insertAdjacentHTML('beforeend', `<span class="mark">${mark}</span>`);
+    const versions = state.versions;
+
+    if (view === 'naming') {
+      const input = make('input', { type: 'text', maxLength: 120, placeholder: `Version ${versions + 1}`, ariaLabel: 'Version name' });
+      input.addEventListener('keydown', event => {
+        if (event.key === 'Enter') save(input.value);
+        if (event.key === 'Escape') { event.stopPropagation(); back(); }
+      });
+      pill.append(input, button('Save', () => save(input.value), { className: 'primary' }), button('Cancel', back));
+      input.focus();
+      return;
+    }
+    if (view === 'saving') {
+      pill.append(make('span', { className: 'status', innerHTML: `<span class="busy"></span>Saving v${versions + 1}…` }));
+      return;
+    }
+    if (view === 'saved' || view === 'failed') {
+      pill.append(make('span', { className: `status${view === 'failed' ? ' bad' : ''}`, textContent: message }));
+      return;
+    }
+
+    const label = make('span', { className: 'label' });
+    if (versions) label.innerHTML = `<b>${state.latest.id}</b> · ${versions} ${versions === 1 ? 'version' : 'versions'}`;
+    else label.textContent = 'No versions yet';
+    pill.append(label, make('span', { className: 'sep' }));
+    if (versions) pill.append(button('History', open));
+    if (state.canSave) pill.append(button(versions ? 'Save' : 'Save first version', () => { view = 'naming'; render(); }, versions ? {} : { className: 'primary' }));
+  }
+
+  function back() {
+    view = 'idle';
+    render();
+  }
+
+  async function save(name) {
+    view = 'saving';
+    render();
+    say('Saving. Afterimage builds the prototype first.');
+    let result;
+    try {
+      const response = await fetch(`${state.base}/afterimage/api/save`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name: name.trim() })
+      });
+      result = await response.json().catch(() => ({ error: `Afterimage answered ${response.status}.` }));
+      if (!response.ok) throw new Error(result.error ?? `Afterimage answered ${response.status}.`);
+    } catch (error) {
+      view = 'failed';
+      message = `Couldn't save. ${error.message === 'Failed to fetch' ? 'Is afterimage dev still running?' : error.message}`;
+      render();
+      say(message);
+      later(back, 6000);
+      return;
+    }
+    if (result.saved) state = { ...state, versions: Number(result.id.slice(1)), latest: { id: result.id, name: result.name } };
+    view = 'saved';
+    message = result.saved ? `Saved ${result.id} "${result.name}"` : `No changes since ${result.id}`;
+    render();
+    say(message);
+    later(back, 2400);
+  }
+
+  function open(event) {
+    if (layer) return;
+    returnFocus = event?.currentTarget ?? null;
+    layer = make('div', { className: 'layer' });
+    layer.setAttribute('role', 'dialog');
+    layer.setAttribute('aria-modal', 'true');
+    layer.setAttribute('aria-label', 'Version history');
+    const frame = make('iframe', { src: `${state.base}/afterimage/`, title: 'Version history' });
+    const closer = button('', close, { className: 'close', ariaLabel: 'Close history' });
+    closer.innerHTML = cross;
+    layer.append(frame, closer);
+    root.append(layer);
+    dock.hidden = true;
+    document.documentElement.style.setProperty('overflow', 'hidden');
+    requestAnimationFrame(() => layer?.setAttribute('data-shown', ''));
+    frame.addEventListener('load', () => frame.focus(), { once: true });
+    closer.focus();
+  }
+
+  function close() {
+    if (!layer) return;
+    layer.remove();
+    layer = null;
+    dock.hidden = false;
+    document.documentElement.style.removeProperty('overflow');
+    returnFocus?.focus?.();
+    // A save the agent made from the terminal meanwhile shows up in the count.
+    refresh();
+  }
+
+  window.addEventListener('keydown', event => {
+    if (event.key === 'Escape' && layer) close();
+  });
+  window.addEventListener('message', event => {
+    if (layer && event.origin === new URL(state.base).origin && event.data?.type === 'afterimage:close') close();
+  });
+
+  async function refresh() {
+    if (!state || view !== 'idle') return;
+    const next = state.canSave ? await session(state.base) : null;
+    if (next && (next.versions !== state.versions)) {
+      state = next;
+      render();
+    }
+  }
+  // Saves the agent makes from the terminal show up when the person comes back to the page.
+  document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'visible') refresh(); });
+
+  const mount = async () => {
+    state = await find();
+    if (!state) return;
+    render();
+    // On <html>, beside <body> rather than in it: frameworks that redraw the body (hydration, page swaps) leave it alone.
+    document.documentElement.append(host);
+  };
+  if (document.body) mount();
+  else document.addEventListener('DOMContentLoaded', mount, { once: true });
+})();