afterimage-cli 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.2.0
+
+- **The pill.** Afterimage now sits on the prototype itself. Save keeps the current state as the next version, and History opens every version over the page, in the same tab; Esc or the close button returns to the prototype. On a deployed site the same pill shows everyone the versions, without Save. It draws in a shadow root, so the app's CSS can't reach it, and it stays out of saved versions.
+- **`init` adds the pill and wires `npm run dev`.** A plain HTML page gets one script tag, and a Vite app's `index.html` one import. For Next.js, Astro and SvelteKit it prints the one import to add. The `dev` script now starts Afterimage beside the app (`vite` becomes `afterimage dev -- vite`), and a plain HTML folder gets a `dev` script that serves it. Run `npx afterimage init` again on a project set up with 0.1.
+- **`afterimage dev -- <your dev command>`** runs the app's own dev server with Afterimage beside it and stops when it stops. With no dev command, a plain HTML prototype is served at `/`. dev now starts before the first save, answers the pill's save on this machine only, and keeps its served copy outside the project, so a dev server watching the project can't stop it updating after a save on Windows.
+- **The viewer closes itself when it is opened in the pill's layer**: Esc with nothing else open returns to the prototype.
+- **The agent instructions** cover "add Afterimage so I can track my versions" from start to finish, and tell the agent to answer in a line instead of handing back commands.
+
+## 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.

package/README.md

@@ -17,7 +17,7 @@ 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:
+`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 puts the Afterimage pill on your prototype and makes `npm run dev` start Afterimage beside your app. It also writes `afterimage.config.json`, lines in `.gitattributes` and `.gitignore`, and host config for Vercel and Netlify, then lists every file it changed. For Next.js, Astro and SvelteKit it prints the one import that adds the pill. 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"
@@ -25,26 +25,28 @@ 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.
+Working with Claude Code, Cursor or another coding agent? Paste the setup prompt from [docs/agents.md](docs/agents.md) instead. It starts with "Add Afterimage so I can track this prototype's versions." The agent installs Afterimage, puts the pill on your prototype, saves a first version and starts your dev server with Afterimage beside it. It also copies Afterimage's instructions into the project, so "save a version called Remember me" works in plain words later.
 
 ## Usage
 
-Save a version whenever the prototype is worth keeping:
+Run your prototype:
 
 ```bash
-npx afterimage save "First version"
-npx afterimage save "Remember me" --note "Keeps people signed in for 30 days."
+npm run dev
 ```
 
-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.
+The pill sits at the bottom right of the page. Save keeps the current state as the next version. History opens every version over the page, with what changed between any two, and Esc closes it. Once you deploy, the same pill on the live site shows everyone the versions, without Save.
 
-Open the history while you work:
+You can also save from the command line, or have your agent do it:
 
 ```bash
-npx afterimage dev
+npx afterimage save "First version"
+npx afterimage save "Remember me" --note "Keeps people signed in for 30 days."
 ```
 
-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.
+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.
+
+`npm run dev` also prints the history's own address, `http://localhost:4321/afterimage/` unless that port is busy. 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.
 

package/agents/cursor/afterimage.mdc

@@ -1,11 +1,25 @@
 ---
-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.
+description: Adds Afterimage (afterimage-cli) to this prototype and saves, names, compares and deploys versions in its history. Use when the user asks to add Afterimage or track versions, 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.
+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/`. A pill sits on the running prototype: Save keeps the current state as the next version, and History opens every version over the page, with what changed between any two. On the deployed site the same pill shows the history to everyone who opens it. 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.
+
+The user works on the prototype, not in a terminal. Do the steps yourself and reply in a line or two, with a link when there is one. Never hand the user a command to run.
+
+## Add Afterimage
+
+When the user asks to add Afterimage, or to track the prototype's versions, do all of this:
+
+1. If the project has no `package.json`, run `npm init -y`.
+2. Unless `package.json` already lists it, run `npm install --save-dev afterimage-cli`.
+3. Run `npx afterimage init --agent claude --no-input` if you are Claude Code, or `npx afterimage init --agent cursor --no-input` if you are Cursor. Handle what it prints as "Set up" below says.
+4. Init puts the pill on plain HTML pages and in a Vite app's `index.html` itself. For Next.js, Astro and SvelteKit it prints a note that starts with `Add the Afterimage pill to your app`. Make that change yourself, exactly as the note says.
+5. Unless `afterimage/versions.json` already lists a version, run `npx afterimage save "First version"`.
+6. Start `npm run dev` as a background process. If you started the project's dev server earlier in this session, stop that one first: this is the same server, with Afterimage beside it. Wait for the line that starts with `Afterimage is running at`.
+7. Tell the user where the prototype is running and that the pill at its bottom right saves a version and shows them all. The address is the app dev server's own (such as Vite's `Local:` line), or the one after `Your prototype is at` for plain HTML.
 
 ## Commands
 
@@ -15,23 +29,25 @@ Afterimage keeps a version history of this prototype. Each save builds the proto
 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.
+- It runs the prototype's build first when `afterimage.config.json` has one, then saves the result. The pill's Save button does the same.
 - 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.
+- On success it prints `Saved v4 "Remember me".` and the version's size. Tell the user the id in one line, such as "Saved v4, Remember me." 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.
+- While dev runs, a save made here shows up in the pill and the history on their own.
 
-### Open the history
+### Run the prototype with the pill
 
 ```bash
-npx afterimage dev
+npm run dev
 ```
 
+- Init makes the project's `dev` script start Afterimage beside the app: `vite` becomes `afterimage dev -- vite`, which runs both and stops both. A plain HTML folder with no dev script gets `afterimage dev`, which serves the folder itself.
+- If the `dev` script doesn't start with `afterimage dev`, run the app's own dev command through it instead, such as `npx afterimage dev -- next 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"`.
+- It prints `Afterimage is running at http://localhost:4321/afterimage/`, the history's own address. The port starts at 4321 and moves to the next free one when 4321 is busy, so use the URL it printed. With plain HTML it also prints `Your prototype is at` and the prototype's address.
+- If dev is already running from earlier, use the URLs 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 starts with no saved versions too. Then the pill offers to save the first one.
 
 ### Build the deployable site
 
@@ -42,6 +58,7 @@ 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`.
+- On the deployed site the pill shows the versions and opens the history. It has no Save there.
 
 ### Set up
 
@@ -49,16 +66,16 @@ npx afterimage build
 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.
+- It writes `afterimage.config.json`, the `afterimage:save`, `afterimage:dev` and `afterimage:build` scripts and a `dev` script that starts Afterimage beside the app in `package.json`, the pill's line in the prototype's pages, 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.
+- A note that starts with `Add the Afterimage pill to your app` is yours to do. Pass any other note it prints after the list of files, such as one about an existing `vercel.json`, on to the user.
 
 ## Links into the viewer
 
-Add these to the URL dev printed:
+Add these to the URL that follows `Afterimage is running at`:
 
 - `?version=v3` opens one version.
 - `?version=v4&mode=compare&base=v2` compares v4 with the older v2.
@@ -68,12 +85,13 @@ With dev on its default port, a comparison is `http://localhost:4321/afterimage/
 
 `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
+## What people ask, and what to do
 
-- **"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.
+- **"Add Afterimage so I can track my versions."** Do everything in "Add Afterimage" above, then tell the user the prototype's address and that the pill on it saves versions and shows them all.
+- **"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, in one line.
+- **"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 history's URL 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 history will be at `/afterimage/` on the deployed site, behind the same pill. Don't commit, push or deploy unless the user asks.
+- **"Show me the version history."** Make sure dev is running, then tell the user to press History on the pill, and give them the history's URL too.
 
 ## Rules
 

package/agents/skill/SKILL.md

@@ -1,11 +1,25 @@
 ---
 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.
+description: Adds Afterimage (afterimage-cli) to this prototype and saves, names, compares and deploys versions in its history. Use when the user asks to add Afterimage or track versions, 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.
+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/`. A pill sits on the running prototype: Save keeps the current state as the next version, and History opens every version over the page, with what changed between any two. On the deployed site the same pill shows the history to everyone who opens it. 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.
+
+The user works on the prototype, not in a terminal. Do the steps yourself and reply in a line or two, with a link when there is one. Never hand the user a command to run.
+
+## Add Afterimage
+
+When the user asks to add Afterimage, or to track the prototype's versions, do all of this:
+
+1. If the project has no `package.json`, run `npm init -y`.
+2. Unless `package.json` already lists it, run `npm install --save-dev afterimage-cli`.
+3. Run `npx afterimage init --agent claude --no-input` if you are Claude Code, or `npx afterimage init --agent cursor --no-input` if you are Cursor. Handle what it prints as "Set up" below says.
+4. Init puts the pill on plain HTML pages and in a Vite app's `index.html` itself. For Next.js, Astro and SvelteKit it prints a note that starts with `Add the Afterimage pill to your app`. Make that change yourself, exactly as the note says.
+5. Unless `afterimage/versions.json` already lists a version, run `npx afterimage save "First version"`.
+6. Start `npm run dev` as a background process. If you started the project's dev server earlier in this session, stop that one first: this is the same server, with Afterimage beside it. Wait for the line that starts with `Afterimage is running at`.
+7. Tell the user where the prototype is running and that the pill at its bottom right saves a version and shows them all. The address is the app dev server's own (such as Vite's `Local:` line), or the one after `Your prototype is at` for plain HTML.
 
 ## Commands
 
@@ -15,23 +29,25 @@ Afterimage keeps a version history of this prototype. Each save builds the proto
 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.
+- It runs the prototype's build first when `afterimage.config.json` has one, then saves the result. The pill's Save button does the same.
 - 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.
+- On success it prints `Saved v4 "Remember me".` and the version's size. Tell the user the id in one line, such as "Saved v4, Remember me." 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.
+- While dev runs, a save made here shows up in the pill and the history on their own.
 
-### Open the history
+### Run the prototype with the pill
 
 ```bash
-npx afterimage dev
+npm run dev
 ```
 
+- Init makes the project's `dev` script start Afterimage beside the app: `vite` becomes `afterimage dev -- vite`, which runs both and stops both. A plain HTML folder with no dev script gets `afterimage dev`, which serves the folder itself.
+- If the `dev` script doesn't start with `afterimage dev`, run the app's own dev command through it instead, such as `npx afterimage dev -- next 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"`.
+- It prints `Afterimage is running at http://localhost:4321/afterimage/`, the history's own address. The port starts at 4321 and moves to the next free one when 4321 is busy, so use the URL it printed. With plain HTML it also prints `Your prototype is at` and the prototype's address.
+- If dev is already running from earlier, use the URLs 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 starts with no saved versions too. Then the pill offers to save the first one.
 
 ### Build the deployable site
 
@@ -42,6 +58,7 @@ 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`.
+- On the deployed site the pill shows the versions and opens the history. It has no Save there.
 
 ### Set up
 
@@ -49,16 +66,16 @@ npx afterimage build
 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.
+- It writes `afterimage.config.json`, the `afterimage:save`, `afterimage:dev` and `afterimage:build` scripts and a `dev` script that starts Afterimage beside the app in `package.json`, the pill's line in the prototype's pages, 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.
+- A note that starts with `Add the Afterimage pill to your app` is yours to do. Pass any other note it prints after the list of files, such as one about an existing `vercel.json`, on to the user.
 
 ## Links into the viewer
 
-Add these to the URL dev printed:
+Add these to the URL that follows `Afterimage is running at`:
 
 - `?version=v3` opens one version.
 - `?version=v4&mode=compare&base=v2` compares v4 with the older v2.
@@ -68,12 +85,13 @@ With dev on its default port, a comparison is `http://localhost:4321/afterimage/
 
 `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
+## What people ask, and what to do
 
-- **"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.
+- **"Add Afterimage so I can track my versions."** Do everything in "Add Afterimage" above, then tell the user the prototype's address and that the pill on it saves versions and shows them all.
+- **"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, in one line.
+- **"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 history's URL 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 history will be at `/afterimage/` on the deployed site, behind the same pill. Don't commit, push or deploy unless the user asks.
+- **"Show me the version history."** Make sure dev is running, then tell the user to press History on the pill, and give them the history's URL too.
 
 ## Rules
 

package/package.json

@@ -1,61 +1,65 @@
-{
-  "name": "afterimage-cli",
-  "version": "0.1.0",
-  "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"
-  }
-}
+{
+  "name": "afterimage-cli",
+  "version": "0.2.0",
+  "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"
+  },
+  "exports": {
+    "./overlay": "./src/runtime/overlay.js",
+    "./package.json": "./package.json"
+  },
+  "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"
+  }
+}