@qwertybit/pr-preview 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.1.5] — 2026-07-07
+
+### Changed
+
+- **New demo animation** — refreshed the README/npm demo with a designed
+  walkthrough of the full flow: a Claude Code prompt kicks off the run, the app is
+  driven automatically in a real Chrome window (add to cart → checkout, recording a
+  before/after), and out come `before.mp4` + `after.mp4`. Also available as an MP4.
+
+## [0.1.4] — 2026-07-07
+
+### Fixed
+
+- **The cursor is visible again** — the synthetic pointer is now anchored to the
+  viewport origin, so it no longer drifts off-frame (and out of the cropped clip)
+  when the app centers its layout with flexbox/grid. It's also larger, with an
+  always-on highlight halo, so it reads clearly once the clip is downscaled — and a
+  regression test now asserts it renders and moves across captured frames.
+- **Motion smoothing actually applies now** — corrected the ffmpeg `minterpolate`
+  scene-change-detection argument. The previous value was an invalid token, so the
+  interpolation command failed on every clip and silently fell back to a
+  non-interpolated, choppy encode. MP4s now interpolate as intended, and the
+  fallback logs a warning instead of failing quietly.
+
+### Changed
+
+- **Snappier motion** — cursor glides, scrolling, and settle pauses are quicker now
+  that the capture runs at ~60fps during motion; the slow pacing was only needed for
+  the old low, variable capture rate.
+
+### Added
+
+- **Smoother recordings** — agent-driven clips now read as fluid video instead of
+  a slideshow. Three changes: (1) the CDP screencast is capped to ~the CSS window
+  size so Chrome stops JPEG-encoding full Retina-resolution frames, raising the
+  delivered frame rate; (2) the agent animates motion in-page — the synthetic
+  cursor glides (distance-scaled), scroll eases, and text types character-by-
+  character; (3) a new `gif.interpolate` option (`"blend"` default / `"mci"` /
+  `"off"`) synthesises intermediate MP4 frames from the real captured frames up to
+  `gif.smoothFps` (default 60), so a low, variable capture rate still plays smooth.
+  `"blend"` never warps text/geometry; `"mci"` is sharper with a slight warp risk
+  on fast-scrolling dense pages.
+
+- **Claude Code integration via MCP** — a new `pr-preview mcp` command starts a
+  Model Context Protocol server (stdio) so an agent can record a journey from a
+  plain-English prompt. Claude reads the app's accessibility tree and drives it
+  with real clicks/typing, so the existing engine captures a real live clip — it
+  is agent-driven, not synthesized. Tools: `start_recording`, `snapshot`, `act`,
+  `next_pass`, `finish_recording`, `open_pr`, `cancel_recording`.
+- **Agent before/after** — `start_recording({ mode: "before-after" })` records the
+  same journey on the PR base branch (in a git worktree) and on your branch,
+  producing `before.*` and `after.*`, all driven by the agent.
+- **`open_pr` tool** — commits the clip into `pr-preview/`, pushes the branch, and
+  opens a pull request with the preview embedded (an inline GIF plus a link to the
+  full MP4). Requires the GitHub CLI (`gh`) authenticated.
+- **`detect_localhost` tool + "never guess the URL"** — probes common dev-server
+  ports and reports which local apps are running (with page titles). When no URL
+  is given, the agent uses it to ask which running app to record, or to ask for a
+  local/staging/production URL — it never guesses.
+- **`/record` slash command** — `init` installs a Claude Code skill at
+  `.claude/skills/record/SKILL.md`, so you can record any flow in one line:
+  `/record localhost:3000 add a book, then checkout`. It drives the recording
+  through the MCP tools (agent mode). Non-destructive: skipped if it already exists.
+- **`init` now writes `.mcp.json`** (merging into an existing file) so Claude Code
+  discovers the server automatically, plus the `/record` skill above.
+- **`init` prompts before overwriting** — when a `pr-preview` config, MCP server
+  entry, or `/record` skill already exists, it asks `Overwrite it? (y/N)` instead
+  of silently skipping. In a non-interactive shell (CI) it defaults to keeping the
+  existing file.
+
+### Notes
+
+- Agent before/after needs a managed dev server (omit `url`); already-running
+  apps (`--url`) remain single-clip in agent mode. Manual `pr-preview run` is
+  unchanged and still supports the full `--url` before/after flow.
+
 ## [0.1.0] — 2026-06-08
 
 Initial release.
@@ -30,4 +108,7 @@ Initial release.
   CSP `frame-ancestors`) are stripped.
 - CLI: `pr-preview init`, `pr-preview record`, `pr-preview run`.
 
+[Unreleased]: https://github.com/QwertyBit-Ventures/pr-preview/compare/v0.1.5...HEAD
+[0.1.5]: https://github.com/QwertyBit-Ventures/pr-preview/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/QwertyBit-Ventures/pr-preview/compare/v0.1.0...v0.1.4
 [0.1.0]: https://github.com/QwertyBit-Ventures/pr-preview/releases/tag/v0.1.0

package/README.md

@@ -16,7 +16,11 @@
 </p>
 
 <p align="center">
-  <img src="https://cdn.jsdelivr.net/npm/@qwertybit/pr-preview/assets/demo.gif" alt="PR Preview demo — recording a UI journey and producing a before/after video" width="720" />
+  <img src="https://cdn.jsdelivr.net/npm/@qwertybit/pr-preview/assets/demo.gif" alt="PR Preview demo — a Claude Code prompt drives the app in Chrome and produces before/after videos" width="720" />
+</p>
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/npm/@qwertybit/pr-preview/assets/demo.mp4">▶ Watch in higher quality (MP4)</a>
 </p>
 
 **PR Preview** opens your app in a controlled Chrome window and records the journey you perform —
@@ -38,33 +42,35 @@ about a minute.
 
 ---
 
-## ✨ Features
+## Features
 
-- 🎬 **Record by demonstration** — just use your app. Clicks, typing, scrolling and navigation are
+- **Record by demonstration** — just use your app. Clicks, typing, scrolling and navigation are
   captured as an editable outline; no selectors or scripts to hand-write.
-- 🎥 **Live capture, zero drift** — the clip is your real recording, not a replay, so it never
+- **Live capture, zero drift** — the clip is your real recording, not a replay, so it never
   desyncs on stateful apps. A synthetic cursor makes every move easy to follow.
-- 🌳 **True before/after** — the base branch runs in an isolated git **worktree**; your working
+- **True before/after** — the base branch runs in an isolated git **worktree**; your working
   tree is never touched. Or point it at an app you already run with `--url`.
-- 🎞️ **Tiny, sharp MP4s** — H.264, near-Full-HD, a few hundred KB. GitHub renders them inline in a
+- **Tiny, sharp MP4s** — H.264, near-Full-HD, a few hundred KB. GitHub renders them inline in a
   PR. High-quality GIF fallback when ffmpeg isn't installed.
-- 🔒 **Runs entirely on your machine** — nothing is uploaded. Your source and app data never leave
+- **Runs entirely on your machine** — nothing is uploaded. Your source and app data never leave
   your computer.
-- 🏷️ **Self-describing clips** — each is captioned with its branch and a timestamp.
-- 🤖 **Agent-friendly** — config-driven and flag-free, so you can kick it off from Claude Code or CI.
+- **Self-describing clips** — each is captioned with its branch and a timestamp.
+- **Drive it from Claude Code** — a built-in MCP server lets Claude record a journey for you from
+  a plain-English prompt: it opens Chrome, performs the flow step by step, and can even open the PR.
+  Agent-driven, but still a real capture of your real app — never synthesized. Manual mode still works.
 
-## 🚀 Install
+## Install
 
 ```bash
 npm i -D @qwertybit/pr-preview
 npx playwright install chromium   # one-time browser download
-npx pr-preview init               # scaffolds pr-preview.config.js
+npx pr-preview init               # scaffolds pr-preview.config.js + .mcp.json (Claude Code)
 ```
 
 > **ffmpeg** (optional, recommended) gives you MP4 output. macOS: `brew install ffmpeg` ·
 > Debian/Ubuntu: `apt install ffmpeg`. Without it, PR Preview produces a high-quality GIF instead.
 
-## ⚡ Quick start
+## Quick start
 
 On your PR branch:
 
@@ -85,7 +91,7 @@ Both clips land in `.pr-preview/output/`. Drag them into your PR description —
 Just need one clip (a demo, a bug repro)? `npx pr-preview run --single` records a single standalone
 video, no comparison.
 
-## 🧠 How it works
+## How it works
 
 A run is a short wizard shown in the harness sidebar:
 
@@ -103,7 +109,7 @@ Record    Capture   Record    Capture   Generate
   keep a session you set up by hand (e.g. a manual login) — only shown when there's state to reset.
 - **Refresh button** in the frame corner reloads the app whenever you need a clean slate.
 
-## 📦 Output
+## Output
 
 | `format` | Result | Needs ffmpeg |
 | --- | --- | --- |
@@ -113,7 +119,7 @@ Record    Capture   Record    Capture   Generate
 
 MP4 is recommended: full color, far smaller than GIF, and GitHub embeds it inline.
 
-## ⚙️ Configuration
+## Configuration
 
 Everything lives in `pr-preview.config.js` (or `.ts` / `.json`), so a project is set up once and
 runs with **no flags**:
@@ -161,13 +167,14 @@ export default {
 | `permissions` | allow-all | Browser permissions to grant (Playwright names). Unlisted ones stay denied — no native prompt blocks the run. |
 | `geolocation` | — | Fixed `{ latitude, longitude }` so location apps render identical results in both clips. |
 
-## 🖥️ CLI
+## CLI
 
 | Command | What it does |
 | --- | --- |
-| `pr-preview init` | Scaffold `pr-preview.config.js` and a `.gitignore` entry. |
+| `pr-preview init` | Scaffold `pr-preview.config.js`, a `.gitignore` entry, `.mcp.json`, and the `/record` Claude Code skill. |
 | `pr-preview record` | Record a journey on the current branch only (`-o <file>`). |
 | `pr-preview run` | The full before/after flow. |
+| `pr-preview mcp` | Run the MCP server (stdio) so Claude Code can drive a recording. |
 
 `run` flags: `-b, --base <ref>` (override base) · `--keep-worktree` (reuse the base worktree) ·
 `-u, --url <url>` (use your own running app) · `-s, --single` (one standalone clip, no comparison).
@@ -185,14 +192,68 @@ npx pr-preview run --url http://localhost:3000
 It records BEFORE on your running app, then **pauses** — you switch branches, restart on the same
 URL, and click **Continue** — then it records AFTER. No worktree, no managed dev server.
 
-## 🤖 Use it from Claude Code
+## Use it from Claude Code
+
+PR Preview ships an **MCP server** so Claude Code can record a journey for you — you describe the
+flow in plain English and Claude drives your real app in Chrome, records it, and (optionally) opens
+the PR. It's agent-driven, but still a real capture of your real app; nothing is synthesized.
+
+**Setup** — `npx pr-preview init` writes a `.mcp.json` that registers the server:
+
+```json
+{ "mcpServers": { "pr-preview": { "command": "npx", "args": ["pr-preview", "mcp"] } } }
+```
+
+Open the project in Claude Code (it auto-discovers `.mcp.json`) and just ask:
+
+> **You:** Record my add-to-cart flow — add 3 books to the cart, then go to checkout. Then open the PR.
+>
+> **Claude:** *opens Chrome, performs each step live, renders `before.mp4` + `after.mp4`, and opens
+> the pull request with the clip embedded.*
+
+**The tools Claude uses:**
+
+| Tool | What it does |
+| --- | --- |
+| `start_recording` | Open the app + start recording. `mode: "single"` (one clip) or `"before-after"`. Omit `url` to start your dev server; pass one to record an app you already run. |
+| `snapshot` | Read the page as an accessibility tree with `[ref=eN]` handles. |
+| `act` | Perform one action: `click` / `fill` / `press` / `hover` / `navigate` / `scroll` / `wait`. |
+| `next_pass` | *(before-after)* finish the BEFORE clip, switch to your branch, start AFTER. |
+| `finish_recording` | Stop, encode, and return the clip path(s). |
+| `open_pr` | Commit the clip, push the branch, and open a PR with the preview embedded. |
+| `detect_localhost` | Probe common dev-server ports and report which local apps are running (with their page titles). |
+| `cancel_recording` | Abort and close the browser without producing a clip. |
+
+Claude targets elements by their accessible name (no selectors or scripts), so it works on any app.
+
+**No URL? Claude asks — it never guesses.** If you don't name a URL, Claude runs `detect_localhost`
+first: if apps are running it asks which one to record; if none are, it asks for a local, staging, or
+production URL. That way it always records the app you meant.
+
+**The `/record` slash command.** `init` also installs a Claude Code skill at
+`.claude/skills/record/SKILL.md`, so you can record any flow in one line:
+
+```
+/record localhost:3000 add a book to the cart, then checkout
+```
+
+The skill drives the recording through the MCP tools above (agent mode), resolving the URL the same
+way. It's non-destructive — `init` skips it if the file already exists.
+
+**Before/after in agent mode** needs a managed dev server (omit `url`) and for you to be on a PR
+branch: Claude records the journey on the base branch (in a git worktree), then redoes the *same*
+journey on your branch. `--url` / already-running apps stay single-clip in agent mode, since an
+external app can't be branch-swapped without you.
+
+**About `open_pr`:** GitHub only plays inline video from its own attachment CDN (no public API), so
+the open-source path embeds an animated **GIF** (rendered inline) and links the full MP4. It creates
+a commit on your branch and pushes it, and needs the [GitHub CLI](https://cli.github.com) (`gh`)
+authenticated. One-click *hosted video in the PR body* is part of PR Preview for Teams.
 
-Because every setting lives in the config, a run takes no flags — so an AI agent can kick it off.
-Ask Claude Code for a preview and it runs `npx pr-preview run`; a Chrome window opens, **you click
-through the ~30-second journey**, and the agent picks up the finished `before.mp4` / `after.mp4` to
-drop into your PR. The agent triggers and finalizes; you demonstrate the journey.
+**Prefer to record by hand?** Manual mode is unchanged: `npx pr-preview run` opens Chrome for you to
+click through yourself. Both modes produce the same clips — the only difference is whose hands drive.
 
-## 🔐 Privacy
+## Privacy
 
 PR Preview runs locally — it opens your app in a Chrome window, records, and writes video files to
 your project. Nothing is uploaded. The clip is a real screen recording, so avoid typing real
@@ -216,25 +277,25 @@ PR Preview drives a real app inside a controlled browser, so a few things are ou
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and PRs welcome — and a ⭐ helps a lot.
+See [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and PRs welcome — and a star helps a lot.
 
 ## License & what's free
 
 The **CLI is open source under the [MIT license](./LICENSE)** — free to use, including commercially.
 This is an open-core project:
 
-- ✅ **This CLI** — recording and before/after clip generation. MIT, free forever. Clips carry a
+- **This CLI** — recording and before/after clip generation. MIT, free forever. Clips carry a
   small `pr-preview.com` watermark.
-- 🔒 **PR Preview for Teams** ([pr-preview.com](https://pr-preview.com)) — the hosted service:
+- **PR Preview for Teams** ([pr-preview.com](https://pr-preview.com)) — the hosted service:
   clip hosting, a synced review player, team reviewers & comments, sharing, and watermark-free
   clips. A separate, proprietary commercial offering — *coming soon*.
-- ™️ The **"PR Preview" name and logo** are trademarks of SC QWERTYBIT SRL; the MIT license covers
+- The **"PR Preview" name and logo** are trademarks of SC QWERTYBIT SRL; the MIT license covers
   the code, not the brand.
 
 ---
 
 <p align="center">
-  <a href="https://pr-preview.com"><strong>🎬 pr-preview.com</strong></a><br/>
+  <a href="https://pr-preview.com"><strong>pr-preview.com</strong></a><br/>
   <sub>See it in action, and <a href="https://pr-preview.com/#teams">join the early-access list for PR&nbsp;Preview for Teams</a> —<br/>
   hosted clips, team reviews &amp; sharing, coming soon.</sub>
 </p>