afterimage-cli 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.1
+
+- **`init` keeps Next.js's long cache on the live app.** For a project that depends on `next`, `vercel.json` gets a header rule and a new `netlify.toml` a `[[headers]]` block that serve `/_next/static/` with `public, max-age=31536000, immutable`. The host settings Afterimage needs for Next.js turn off each host's own Next.js handling, which set that header, and real deploys of 0.1.0 showed those files served with `max-age=0`. Run `npx afterimage init` again to add it to a project set up with 0.1.0; for an existing `netlify.toml` it prints the lines to add.
+- **`afterimage dev` passes over a port Windows refuses.** Windows reserves port ranges for Hyper-V, WSL and Docker and refuses them with a permission error, which stopped `dev` instead of moving it to the next port, as a taken port does.
+
+## 0.1.0
+
+The first release.
+
+- **`afterimage init`** detects a plain HTML folder, Vite, Next.js with `output: 'export'`, Astro, and SvelteKit with `@sveltejs/adapter-static`. It writes `afterimage.config.json`, the `afterimage:save`, `afterimage:dev` and `afterimage:build` scripts, the `.gitattributes` and `.gitignore` lines, and host config for Vercel and Netlify. It stops and says what to change for a Next.js, Astro or SvelteKit project that has no static build, asks for the prototype's folder when it can't tell, takes `--source` and `--build`, copies the agent instructions with `--agent claude|cursor`, and never asks with `--no-input`.
+- **`afterimage save "Name" [--note "..."]`** builds the prototype and saves it as the next version, fingerprinted and byte for byte as built, plus the one script tag a save adds to each HTML page. An unchanged prototype saves nothing. One save runs at a time, and a failed save leaves the history as it was. It prints what each version adds and the history's total, and says so once the history passes 100 MB.
+- **`afterimage dev [--port N]`** serves the viewer over the saved history on localhost and picks up each new save.
+- **`afterimage build`** writes one static site with the app at the root and the history at `/afterimage/`, after checking every saved version against its fingerprint.
+- **The viewer** steps through versions, highlights what changed, and compares any two in Wipe or Side by side, on desktop and phone. Every view has its own link.
+- **A frame runtime** that lets built apps load inside a version, with their own files and routes, while the live app at the root loads as its own build makes it.
+- **Generated names** from Svelte, Astro, Vite CSS modules, Next.js CSS modules built with Turbopack and React 19.3 `useId` are ignored when matching, so two builds of an unchanged page show no changes. Names from Emotion, Vue, the Svelte 4 hydration marker and React 18 and 19.1 `useId` are recognised by their shape, not yet checked against a real build. `data-afterimage-id` pins a match by hand.
+- **Agent support:** a setup prompt and example prompts in `docs/agents.md`, a skill for Claude Code, and the same instructions as a Cursor rule.
+- **Examples:** Northwind (plain HTML), Vite with React, Next.js static export, Astro and SvelteKit, each with a saved history.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Lima
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Afterimage
+
+A version history for prototypes, deployed with the prototype itself.
+
+Afterimage keeps every version of your prototype you save and serves them all from one link, at `/afterimage/` on the site you already deploy. Step through the versions, see what changed between them, and compare any two. Share the link, and anyone can see how the prototype got here without a walkthrough.
+
+[Getting started](docs/getting-started.md) · [Commands](docs/commands.md) · [Deploying](docs/deploying.md) · [Agents](docs/agents.md) · [Matching](docs/matching.md) · [Limits](docs/limits.md)
+
+## Install
+
+Afterimage needs Node 22 or later. From your prototype's project root:
+
+```bash
+npm install -D afterimage-cli
+npx afterimage init
+```
+
+A plain HTML folder with no `package.json` needs `npm init -y` first.
+
+`init` works out what your prototype is: a plain HTML folder, a Vite app, a Next.js static export, an Astro site, or SvelteKit with `@sveltejs/adapter-static`. It writes `afterimage.config.json`, three scripts in `package.json`, lines in `.gitattributes` and `.gitignore`, and host config for Vercel and Netlify, then lists every file it changed. When it can't tell which folder holds the prototype, it asks. You can also tell it:
+
+```bash
+npx afterimage init --source dist --build "npm run build"
+```
+
+## Setup prompt
+
+Working with Claude Code, Cursor or another coding agent? Paste the setup prompt from [docs/agents.md](docs/agents.md) instead. It installs Afterimage and runs `init` with `--agent claude` or `--agent cursor`, which copies Afterimage's instructions into the project, where your agent reads them. It also passes `--no-input`, so init never waits on a question. Then it saves a first version and gives you the viewer's link. After that, "save a version called Remember me" works in plain words.
+
+## Usage
+
+Save a version whenever the prototype is worth keeping:
+
+```bash
+npx afterimage save "First version"
+npx afterimage save "Remember me" --note "Keeps people signed in for 30 days."
+```
+
+A save runs your build first when the prototype has one, then stores the result as the next version: v1, v2, v3. If nothing changed since the last version, nothing is saved.
+
+Open the history while you work:
+
+```bash
+npx afterimage dev
+```
+
+It prints the viewer's address, `http://localhost:4321/afterimage/` unless that port is busy. Your app keeps running on its own dev server. In the viewer, `[` and `]` step through versions, `H` highlights what changed, `C` compares two versions, and `?` lists every shortcut.
+
+Commit `afterimage/` with the rest of the project, along with `afterimage.config.json`, `package.json` and your lockfile, `.gitattributes`, and `vercel.json` or `netlify.toml`. `afterimage/` holds every saved version, and a fresh checkout can't get back a version that isn't in git. `.gitattributes` stops git from changing a saved version's line endings, which would break its fingerprint on another machine.
+
+## Deploying
+
+```bash
+npx afterimage build
+```
+
+This writes `.afterimage/site/`: your app at the root, as its own build makes it, and the history at `/afterimage/`. Serve it from the root of a domain, on any static host that meets [the requirements](docs/deploying.md#other-static-hosts).
+
+On Vercel and Netlify you don't run it yourself. The `vercel.json` and `netlify.toml` that `init` wrote tell the host to run the same build, so a push deploys both. Every preview deployment carries the live prototype and the versions saved on its branch. [docs/deploying.md](docs/deploying.md) covers each host, other static hosts and what init changes for them.
+
+## Limits
+
+- Static output only. Apps that render pages on a server aren't supported: Next.js without `output: 'export'`, Astro with an adapter but without `output: 'static'`, SvelteKit without `@sveltejs/adapter-static`.
+- The site has to be served from the root of its domain, since the history is always at `/afterimage/`. A site under a sub-path, such as a GitHub Pages project site, doesn't work.
+- Versions load through a service worker, so the history needs https, or localhost while you work. Without one, plain HTML with relative paths still shows, but a built app inside the viewer can show up unstyled or on its own not-found page.
+- Every saved version is public. Each one deploys with your site, and there is no command to take one back, so save only what you'd show.
+- A version keeps every file of the prototype except source maps and hidden files (names starting with `.`). The live app at the root keeps every file its build wrote.
+- An old version's code runs on your live site's address, so it can read and change the cookies and storage your live app uses.
+- A few ways of leaving a page inside a version open the live app instead, such as reloading the frame from the browser's menu or a link that opens a new tab.
+- The viewer has been tested in Chrome only so far. Firefox and Safari haven't been tested yet.
+
+[docs/limits.md](docs/limits.md) has the full list.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests and how the examples are made.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/agents/cursor/afterimage.mdc

@@ -0,0 +1,85 @@
+---
+description: Saves, names, compares and deploys versions of this prototype in its Afterimage history (afterimage-cli). Use when the user asks to save or name a version of the prototype, add a note to one, see what changed between versions, open the version history, or get the history ready to deploy. Not for git commits, branches or package versions.
+alwaysApply: false
+---
+
+# Afterimage
+
+Afterimage keeps a version history of this prototype. Each save builds the prototype and stores the built page as the next version (v1, v2, v3 and so on) in `afterimage/`. The viewer shows any saved version, and what changed between two of them. A version is the built page, kept to compare against and to share. It is not a backup of the source: the source belongs in git. Run every command from the project root, where `afterimage.config.json` is.
+
+## Commands
+
+### Save a version
+
+```bash
+npx afterimage save "Remember me" --note "Keeps people signed in for 30 days."
+```
+
+- It runs the prototype's build first when `afterimage.config.json` has one, then saves the result.
+- The name goes in quotes, up to 120 characters. `--note` is optional and can be repeated, one note each, up to 500 characters.
+- Keep names and notes to plain text. A `"`, `$` or backtick inside them breaks the shell's quoting, so leave those out or escape them for the shell you are in.
+- On success it prints `Saved v4 "Remember me".` and the version's size. Tell the user the id it printed. If it says the history is over 100 MB, pass that line on too.
+- `Nothing changed since v3 "Passkeys". Nothing was saved.` means the prototype is the same as the last saved version. Tell the user and stop there.
+
+### Open the history
+
+```bash
+npx afterimage dev
+```
+
+- It keeps running until it is stopped. Start it as a background process, not a command you wait for.
+- It prints `Afterimage is running at http://localhost:4321/afterimage/`. The port starts at 4321 and moves to the next free one when 4321 is busy, so give the user the URL it printed.
+- If dev is already running from earlier, use the URL it printed then. When a save finishes, it rebuilds the history it serves and prints `Updated: N versions.` If that rebuild fails, it prints `Could not update the history` and keeps serving the last good copy.
+- It serves the saved versions only. The app keeps running on its own dev server.
+- It checks the history when it starts. With no saved versions it stops with `Save a first version with: afterimage save "Name"`.
+
+### Build the deployable site
+
+```bash
+npx afterimage build
+```
+
+- It runs the prototype's build, then writes `.afterimage/site/`: the app at the root and the history at `/afterimage/`. That folder is git-ignored.
+- With no saved versions it stops with `Save a first version with: afterimage save "Name"`.
+- The host runs the same build when it deploys: `vercel.json` and `netlify.toml` run `npm run afterimage:build` and serve `.afterimage/site`.
+
+### Set up
+
+```bash
+npx afterimage init --agent claude --no-input
+```
+
+- It writes `afterimage.config.json`, the `afterimage:save`, `afterimage:dev` and `afterimage:build` scripts in `package.json`, lines in `.gitattributes` and `.gitignore`, `vercel.json` and `netlify.toml`. Running it again is safe.
+- `--agent claude` copies these instructions as a Claude Code skill to `.claude/skills/afterimage/`. `--agent cursor` copies them as a Cursor rule to `.cursor/rules/afterimage.mdc`. Pass the one for the agent you are.
+- `--no-input` makes sure it never waits on a question. Where it would have asked, it stops with a message or prints a note instead.
+- If its message contains `no static build`, the project has no static build to save: Next.js without `output: 'export'`, Astro with an adapter but without `output: 'static'`, or SvelteKit without `@sveltejs/adapter-static`. Tell the user what has to change, and stop. Don't pass `--source` to get around it. Once the user has made the change, run init again.
+- Otherwise, if it stops with `Say where the prototype is`, it can't tell which folder holds the prototype. Ask the user which folder it is. Never guess. Then run init again with the same flags plus `--source <folder>`, and add `--build "<command>"` when a build command writes that folder.
+- Anything it prints after the list of files, such as a note about an existing `vercel.json`, is for the user. Pass it on.
+
+## Links into the viewer
+
+Add these to the URL dev printed:
+
+- `?version=v3` opens one version.
+- `?version=v4&mode=compare&base=v2` compares v4 with the older v2.
+- `&hl=1` highlights what changed.
+
+With dev on its default port, a comparison is `http://localhost:4321/afterimage/?version=v4&mode=compare&base=v2`.
+
+`afterimage/versions.json` lists the versions newest first, so the first `id` in it is the latest. An id that isn't in the history opens the latest version instead, so check an id is listed before you link to it.
+
+## What people ask, and what to run
+
+- **"Save a version called Remember me with a note that it keeps people signed in for 30 days."** Run `npx afterimage save "Remember me" --note "Keeps people signed in for 30 days."` and tell the user the id it printed.
+- **"What changed since v2?"** Read `afterimage/versions.json`. If v2 is the latest version, tell the user nothing has changed since v2, because it is the newest version, and don't open a comparison. If v2 isn't listed, say so. Otherwise make sure dev is running and give the user the URL dev printed with `?version=<latest>&mode=compare&base=v2` added. The viewer shows the changes, so don't write a text diff. It compares saved versions: if the prototype has changed since the last save, say that those changes aren't in the comparison.
+- **"Get the version history ready to deploy."** Run `npx afterimage build`. If the project isn't a git repository, tell the user the history has to be committed to the repository the site deploys from, and stop. Otherwise run `git status --short -- afterimage afterimage.config.json package.json package-lock.json pnpm-lock.yaml yarn.lock bun.lock bun.lockb .gitattributes vercel.json netlify.toml` and tell the user which of those aren't committed yet, since the host only sees what is in git. The rest of the project is the user's business. Tell them the site is in `.afterimage/site/` and the history will be at `/afterimage/` on the deployed site. Don't commit, push or deploy unless the user asks.
+- **"Show me the version history."** Start dev and give the user the URL it printed.
+
+## Rules
+
+- **Never edit, move or delete anything in `afterimage/versions/`.** Every version is fingerprinted when it is saved. Once a saved version's files change, save and build stop and dev won't start. If one of them says a version has changed since it was saved, tell the user. Restoring it from git is their call.
+- **Commit `afterimage/` with the project, and never add it to `.gitignore`.** The saved versions live only there, and a fresh checkout can't recover a version that isn't in git.
+- **Save before risky changes.** Before a large or hard-to-undo change to the prototype, offer to save the current state first, so there is a version to compare the change against.
+- **Only save what you'd publish.** Every saved version is deployed with the history, so never save secrets, private data or a broken state. A save keeps every file in the prototype folder, whatever its type, and leaves out only source maps, hidden files (names starting with `.`) and the paths in the config's `exclude`.
+- **An unchanged prototype saves nothing.** `Nothing was saved` is the answer, not an error. Don't retry it.
+- **One save at a time.** Don't start a save while another is running, and don't edit the prototype during one. A save that finds another one running stops with `Another save is active`. Wait for the first to finish. A save that was killed is cleared by the next save once its process has ended, so if the message stays while no save is running, tell the user, who can delete `afterimage/.afterimage-save.lock`.

package/agents/skill/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: afterimage
+description: Saves, names, compares and deploys versions of this prototype in its Afterimage history (afterimage-cli). Use when the user asks to save or name a version of the prototype, add a note to one, see what changed between versions, open the version history, or get the history ready to deploy. Not for git commits, branches or package versions.
+---
+
+# Afterimage
+
+Afterimage keeps a version history of this prototype. Each save builds the prototype and stores the built page as the next version (v1, v2, v3 and so on) in `afterimage/`. The viewer shows any saved version, and what changed between two of them. A version is the built page, kept to compare against and to share. It is not a backup of the source: the source belongs in git. Run every command from the project root, where `afterimage.config.json` is.
+
+## Commands
+
+### Save a version
+
+```bash
+npx afterimage save "Remember me" --note "Keeps people signed in for 30 days."
+```
+
+- It runs the prototype's build first when `afterimage.config.json` has one, then saves the result.
+- The name goes in quotes, up to 120 characters. `--note` is optional and can be repeated, one note each, up to 500 characters.
+- Keep names and notes to plain text. A `"`, `$` or backtick inside them breaks the shell's quoting, so leave those out or escape them for the shell you are in.
+- On success it prints `Saved v4 "Remember me".` and the version's size. Tell the user the id it printed. If it says the history is over 100 MB, pass that line on too.
+- `Nothing changed since v3 "Passkeys". Nothing was saved.` means the prototype is the same as the last saved version. Tell the user and stop there.
+
+### Open the history
+
+```bash
+npx afterimage dev
+```
+
+- It keeps running until it is stopped. Start it as a background process, not a command you wait for.
+- It prints `Afterimage is running at http://localhost:4321/afterimage/`. The port starts at 4321 and moves to the next free one when 4321 is busy, so give the user the URL it printed.
+- If dev is already running from earlier, use the URL it printed then. When a save finishes, it rebuilds the history it serves and prints `Updated: N versions.` If that rebuild fails, it prints `Could not update the history` and keeps serving the last good copy.
+- It serves the saved versions only. The app keeps running on its own dev server.
+- It checks the history when it starts. With no saved versions it stops with `Save a first version with: afterimage save "Name"`.
+
+### Build the deployable site
+
+```bash
+npx afterimage build
+```
+
+- It runs the prototype's build, then writes `.afterimage/site/`: the app at the root and the history at `/afterimage/`. That folder is git-ignored.
+- With no saved versions it stops with `Save a first version with: afterimage save "Name"`.
+- The host runs the same build when it deploys: `vercel.json` and `netlify.toml` run `npm run afterimage:build` and serve `.afterimage/site`.
+
+### Set up
+
+```bash
+npx afterimage init --agent claude --no-input
+```
+
+- It writes `afterimage.config.json`, the `afterimage:save`, `afterimage:dev` and `afterimage:build` scripts in `package.json`, lines in `.gitattributes` and `.gitignore`, `vercel.json` and `netlify.toml`. Running it again is safe.
+- `--agent claude` copies these instructions as a Claude Code skill to `.claude/skills/afterimage/`. `--agent cursor` copies them as a Cursor rule to `.cursor/rules/afterimage.mdc`. Pass the one for the agent you are.
+- `--no-input` makes sure it never waits on a question. Where it would have asked, it stops with a message or prints a note instead.
+- If its message contains `no static build`, the project has no static build to save: Next.js without `output: 'export'`, Astro with an adapter but without `output: 'static'`, or SvelteKit without `@sveltejs/adapter-static`. Tell the user what has to change, and stop. Don't pass `--source` to get around it. Once the user has made the change, run init again.
+- Otherwise, if it stops with `Say where the prototype is`, it can't tell which folder holds the prototype. Ask the user which folder it is. Never guess. Then run init again with the same flags plus `--source <folder>`, and add `--build "<command>"` when a build command writes that folder.
+- Anything it prints after the list of files, such as a note about an existing `vercel.json`, is for the user. Pass it on.
+
+## Links into the viewer
+
+Add these to the URL dev printed:
+
+- `?version=v3` opens one version.
+- `?version=v4&mode=compare&base=v2` compares v4 with the older v2.
+- `&hl=1` highlights what changed.
+
+With dev on its default port, a comparison is `http://localhost:4321/afterimage/?version=v4&mode=compare&base=v2`.
+
+`afterimage/versions.json` lists the versions newest first, so the first `id` in it is the latest. An id that isn't in the history opens the latest version instead, so check an id is listed before you link to it.
+
+## What people ask, and what to run
+
+- **"Save a version called Remember me with a note that it keeps people signed in for 30 days."** Run `npx afterimage save "Remember me" --note "Keeps people signed in for 30 days."` and tell the user the id it printed.
+- **"What changed since v2?"** Read `afterimage/versions.json`. If v2 is the latest version, tell the user nothing has changed since v2, because it is the newest version, and don't open a comparison. If v2 isn't listed, say so. Otherwise make sure dev is running and give the user the URL dev printed with `?version=<latest>&mode=compare&base=v2` added. The viewer shows the changes, so don't write a text diff. It compares saved versions: if the prototype has changed since the last save, say that those changes aren't in the comparison.
+- **"Get the version history ready to deploy."** Run `npx afterimage build`. If the project isn't a git repository, tell the user the history has to be committed to the repository the site deploys from, and stop. Otherwise run `git status --short -- afterimage afterimage.config.json package.json package-lock.json pnpm-lock.yaml yarn.lock bun.lock bun.lockb .gitattributes vercel.json netlify.toml` and tell the user which of those aren't committed yet, since the host only sees what is in git. The rest of the project is the user's business. Tell them the site is in `.afterimage/site/` and the history will be at `/afterimage/` on the deployed site. Don't commit, push or deploy unless the user asks.
+- **"Show me the version history."** Start dev and give the user the URL it printed.
+
+## Rules
+
+- **Never edit, move or delete anything in `afterimage/versions/`.** Every version is fingerprinted when it is saved. Once a saved version's files change, save and build stop and dev won't start. If one of them says a version has changed since it was saved, tell the user. Restoring it from git is their call.
+- **Commit `afterimage/` with the project, and never add it to `.gitignore`.** The saved versions live only there, and a fresh checkout can't recover a version that isn't in git.
+- **Save before risky changes.** Before a large or hard-to-undo change to the prototype, offer to save the current state first, so there is a version to compare the change against.
+- **Only save what you'd publish.** Every saved version is deployed with the history, so never save secrets, private data or a broken state. A save keeps every file in the prototype folder, whatever its type, and leaves out only source maps, hidden files (names starting with `.`) and the paths in the config's `exclude`.
+- **An unchanged prototype saves nothing.** `Nothing was saved` is the answer, not an error. Don't retry it.
+- **One save at a time.** Don't start a save while another is running, and don't edit the prototype during one. A save that finds another one running stops with `Another save is active`. Wait for the first to finish. A save that was killed is cleared by the next save once its process has ended, so if the message stays while no save is running, tell the user, who can delete `afterimage/.afterimage-save.lock`.

package/bin/afterimage.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli/main.js';
+
+process.exitCode = await main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout, stderr: process.stderr });

package/package.json

@@ -1,6 +1,61 @@
-{
-  "name": "afterimage-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "afterimage-cli",
+  "version": "0.1.1",
+  "description": "A version history for prototypes, deployed with the prototype itself.",
+  "license": "MIT",
+  "keywords": [
+    "version-history",
+    "prototype",
+    "prototyping",
+    "design",
+    "viewer",
+    "compare",
+    "diff",
+    "static-site",
+    "vercel",
+    "netlify"
+  ],
+  "homepage": "https://github.com/uxlucas/Afterimage#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uxlucas/Afterimage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uxlucas/Afterimage/issues"
+  },
+  "type": "module",
+  "bin": {
+    "afterimage": "bin/afterimage.mjs"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "bin",
+    "src/cli",
+    "src/engine/manifest.js",
+    "src/runtime",
+    "viewer-dist",
+    "agents",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build:viewer": "node scripts/build-viewer.mjs",
+    "install:examples": "node scripts/install-examples.mjs",
+    "pretest:e2e": "npm run build:viewer && npm run install:examples",
+    "prepack": "npm run build:viewer",
+    "test": "node --test \"tests/*.test.mjs\"",
+    "test:e2e": "node --test --test-concurrency=1 \"tests/e2e/*.test.mjs\"",
+    "try:package": "node scripts/try-package.mjs"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "6.1.2",
+    "motion": "14.9.0",
+    "playwright-core": "1.64.1",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "vite": "8.3.5"
+  }
+}

package/src/cli/commands/build.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { readConfig } from '../config.js';
+import { assembleSite } from '../site.js';
+
+export const usage = 'afterimage build';
+export const summary = 'Build the prototype and write the deployable site with the history at /afterimage/.';
+// What both "afterimage build --help" and "afterimage help build" print.
+export const help = `Usage: ${usage}\n\n${summary}\n`;
+// Read by the docs tests, which check every flag the agent files name.
+export const options = { help: { type: 'boolean', short: 'h' } };
+
+// Not every static host can serve the history (a sub-path, no https, 403 for a missing file), so the message says where
+// the requirements are. tests/docs.test.mjs checks the heading exists.
+export const hostDocs = 'https://github.com/uxlucas/Afterimage/blob/main/docs/deploying.md#other-static-hosts';
+
+export async function run(args, { cwd, stdout, stderr, buildStdio, viewerDir, runtimeDir }) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args, options });
+  } catch (error) {
+    if (!error.code?.startsWith('ERR_PARSE_ARGS')) throw error;
+    stderr.write(`${error.message}\nUsage: ${usage}\n`);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(help);
+    return 0;
+  }
+
+  const config = await readConfig(cwd);
+  const { versions, warnings } = await assembleSite({ projectDir: path.resolve(cwd), config, viewerDir, runtimeDir, buildStdio });
+  for (const warning of warnings) stderr.write(`${warning}\n`);
+  stdout.write(`Built ${config.out} with ${versions} ${versions === 1 ? 'version' : 'versions'}. The history is at /afterimage/.\nServe it from the root of a domain, on a static host that does what ${hostDocs} lists.\n`);
+  return 0;
+}

package/src/cli/commands/dev.js

@@ -0,0 +1,195 @@
+import fs from 'node:fs';
+import http from 'node:http';
+import net from 'node:net';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { readConfig } from '../config.js';
+import { assembleSite } from '../site.js';
+import { fileFor, requestPath, sendFile } from '../static-files.js';
+
+export const usage = 'afterimage dev [--port N]';
+export const summary = 'Serve the saved history at /afterimage/ while your app runs on its own dev server.';
+// What both "afterimage dev --help" and "afterimage help dev" print.
+export const help = `Usage: ${usage}\n\n${summary}\n\n  --port N  the port to start from, 4321 by default; a busy one moves to the next free port\n`;
+// Read by the docs tests, which check every flag the agent files name.
+export const options = { port: { type: 'string' }, help: { type: 'boolean', short: 'h' } };
+
+const defaultPort = 4321;
+const portAttempts = 20;
+// Its own folder, never config.out, so dev and a running build can never share a staging folder.
+const devOut = '.afterimage/dev';
+const servedPath = '/afterimage/';
+
+const count = versions => `${versions} ${versions === 1 ? 'version' : 'versions'}`;
+
+// Windows lets a bind on 127.0.0.1 succeed even while another server holds 0.0.0.0, :: or ::1 on the same port (Astro's
+// default is 4321 too), so ask whether anything answers on either loopback address before binding. A refused connect or
+// a missing address (no IPv6) means nothing is there; a connect that hangs is treated as taken.
+const answers = (port, host) => new Promise(resolve => {
+  const socket = net.connect({ port, host });
+  const done = taken => { socket.destroy(); resolve(taken); };
+  socket.setTimeout(300, () => done(true));
+  socket.once('connect', () => done(true));
+  socket.once('error', () => done(false));
+});
+const isTaken = async port => (await Promise.all(['127.0.0.1', '::1'].map(host => answers(port, host)))).some(Boolean);
+
+// Listens on the first free port from `start`. Port 0 asks the system for any free one.
+async function listen(server, start) {
+  for (let port = start; port < start + (start === 0 ? 1 : portAttempts) && port <= 65535; port++) {
+    if (port !== 0 && await isTaken(port)) continue;
+    try {
+      await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        // Loopback only: the history is for this machine.
+        server.listen(port, '127.0.0.1', () => {
+          server.off('error', reject);
+          resolve();
+        });
+      });
+      return server.address().port;
+    } catch (error) {
+      // EACCES: Windows refuses ports in the ranges Hyper-V, WSL or Docker reserve, which nothing answers on beforehand.
+      if (error.code !== 'EADDRINUSE' && error.code !== 'EACCES') throw error;
+    }
+  }
+  throw new Error(`No free port from ${start} to ${start + portAttempts - 1}. Pass one with --port.`);
+}
+
+// Assembles the viewer and the saved history (not the app) into .afterimage/dev, serves it, and re-assembles when
+// versions.json changes. A failed refresh goes to onError and the last good site keeps serving.
+// Returns { url, versions, warnings, close }: warnings are from the first assemble, and close stops the server and
+// the watcher and waits for a refresh in flight.
+export async function startDev({ projectDir, config, port = defaultPort, viewerDir, runtimeDir, debounceMs = 150, onUpdate = () => {}, onError = () => {} }) {
+  const devConfig = { ...config, out: devOut };
+  const assemble = () => assembleSite({ projectDir, config: devConfig, viewerDir, runtimeDir, includeApp: false });
+  const first = await assemble();
+  const root = first.outDir;
+
+  const server = http.createServer(async (req, res) => {
+    const pathname = requestPath(req.url);
+    if (pathname === null) { res.writeHead(400).end(); return; }
+    if (pathname === '/' || pathname === servedPath.slice(0, -1)) { res.writeHead(302, { Location: servedPath }).end(); return; }
+    const file = fileFor(root, pathname);
+    if (!file) { res.writeHead(403).end(); return; }
+    await sendFile(res, file);
+  });
+  const boundPort = await listen(server, port);
+
+  let closed = false;
+  const stopServer = () => new Promise(resolve => {
+    server.close(resolve);
+    // A browser's keep-alive connection would otherwise hold the server open.
+    server.closeAllConnections();
+  });
+  let timer = null;
+  let refreshing = null;
+  let again = false;
+  // One refresh at a time. A change that lands during one asks for another straight after it.
+  const refresh = () => {
+    if (refreshing) { again = true; return refreshing; }
+    refreshing = (async () => {
+      try {
+        do {
+          again = false;
+          try {
+            const result = await assemble();
+            if (!closed) onUpdate(result);
+          } catch (error) {
+            if (!closed) onError(error);
+          }
+        } while (again && !closed);
+      } finally {
+        refreshing = null;
+      }
+    })();
+    return refreshing;
+  };
+
+  // A save publishes versions.json last, so it is the one file whose change means "the history is complete".
+  let watcher;
+  try {
+    watcher = fs.watch(path.resolve(projectDir, config.history), (event, name) => {
+      if (closed || (name && String(name) !== 'versions.json')) return;
+      clearTimeout(timer);
+      timer = setTimeout(refresh, debounceMs);
+    });
+  } catch (error) {
+    // The server is already listening; do not leave its port held.
+    await stopServer();
+    throw error;
+  }
+  watcher.on('error', error => { if (!closed) onError(error); });
+
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    clearTimeout(timer);
+    watcher.close();
+    await stopServer();
+    await refreshing;
+  };
+
+  return { url: `http://localhost:${boundPort}${servedPath}`, versions: first.versions, warnings: first.warnings, close };
+}
+
+// Resolves on Ctrl-C (or a terminate), or when a caller's signal aborts, which is how tests stop it.
+function untilStopped(signal) {
+  return new Promise(resolve => {
+    if (signal) {
+      if (signal.aborted) resolve();
+      else signal.addEventListener('abort', resolve, { once: true });
+      return;
+    }
+    const stop = () => {
+      process.off('SIGINT', stop);
+      process.off('SIGTERM', stop);
+      resolve();
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+  });
+}
+
+export async function run(args, { cwd, stdout, stderr, viewerDir, runtimeDir, signal }) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args, options });
+  } catch (error) {
+    if (!error.code?.startsWith('ERR_PARSE_ARGS')) throw error;
+    stderr.write(`${error.message}\nUsage: ${usage}\n`);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(help);
+    return 0;
+  }
+  let port = defaultPort;
+  if (parsed.values.port !== undefined) {
+    port = Number(parsed.values.port);
+    if (!/^\d+$/.test(parsed.values.port) || port < 1 || port > 65535) {
+      stderr.write(`--port needs a number from 1 to 65535.\nUsage: ${usage}\n`);
+      return 2;
+    }
+  }
+
+  const config = await readConfig(cwd);
+  const dev = await startDev({
+    projectDir: path.resolve(cwd),
+    config,
+    port,
+    viewerDir,
+    runtimeDir,
+    onUpdate: ({ versions, warnings }) => {
+      for (const warning of warnings) stderr.write(`${warning}\n`);
+      stdout.write(`Updated: ${count(versions)}.\n`);
+    },
+    onError: error => stderr.write(`Could not update the history: ${error.message}\nStill serving the last good copy.\n`)
+  });
+  for (const warning of dev.warnings) stderr.write(`${warning}\n`);
+  stdout.write(`Afterimage is running at ${dev.url}\n`);
+  stdout.write('Your app keeps running on its own dev server; this only serves the history.\n');
+  await untilStopped(signal);
+  await dev.close();
+  return 0;
+}