retake-demos 0.2.0

package/.env.example

@@ -0,0 +1,19 @@
+# Retake — optional. Only `retake describe` and `retake ideas` use a model; validate/dry/run/render/check never do.
+# With a coding agent driving Retake over MCP you can leave all of this empty.
+# Pick explicitly with RETAKE_MODEL=claude-code|codex|groq|mistral|local; otherwise the first available is used.
+RETAKE_MODEL=claude-code
+
+# A. the CLIs you are already signed into on this machine — no keys needed
+#    claude-code: `claude` (Claude Code)      codex: `codex` (OpenAI Codex CLI)
+#    optional: RETAKE_CLAUDE_MODEL=  RETAKE_CODEX_MODEL=
+
+# A. hosted keys
+GROQ_API_KEY=
+RETAKE_GROQ_MODEL=openai/gpt-oss-120b
+MISTRAL_API_KEY=
+RETAKE_MISTRAL_MODEL=mistral-small-latest
+
+# B. local, OpenAI-compatible (Ollama: http://localhost:11434/v1 · LM Studio: http://localhost:1234/v1)
+RETAKE_LOCAL_URL=
+RETAKE_LOCAL_MODEL=llama3.1
+RETAKE_LOCAL_KEY=local

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gleb Bogachev
+
+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

@@ -0,0 +1,183 @@
+<p align="center"><img src="assets/hero.png" width="720" alt="Retake — rerun the demo, don't re-record it"></p>
+
+<p align="center">
+  <b>Rerun the demo. Don't re-record it.</b><br>
+  A product walkthrough as a small YAML file. Your coding agent writes it, Retake records it, you watch and ship it.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/retake-demos"><img src="https://img.shields.io/npm/v/retake-demos?color=111&label=retake-demos" alt="npm"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-111" alt="MIT"></a>
+  <a href="https://github.com/glebbogachev00/retake/actions/workflows/ci.yml"><img src="https://github.com/glebbogachev00/retake/actions/workflows/ci.yml/badge.svg" alt="ci"></a>
+</p>
+
+---
+
+Retake drives a real browser through a web app, records it, and hands back an MP4 with burned-in captions, a still for every scene, and a proof log of exactly what happened. The demo is a file, so when a button moves you change a selector instead of re-shooting — and when the app changes, you rerun the same file.
+
+It is built for the way people work now: **you ask your coding agent for a demo in one sentence**, the agent drafts the file, dry-runs every selector, records a preview, reads the proof log, fixes what failed, and records the real one. Claude Code, Codex, Cursor and anything else that speaks MCP get Retake's tools; `retake ui` is the window you watch it in.
+
+<p align="center"><img src="assets/ui.png" width="900" alt="The Retake window: your demos on the left, the video and its scenes in the middle"></p>
+
+## Install
+
+Needs Node 20+. ffmpeg ships with the package; Chromium is downloaded once.
+
+```bash
+npm install -g retake-demos
+mkdir my-demos && cd my-demos
+retake install
+```
+
+`retake install` makes the folder a workspace (`demos/`, `outputs/`, `.env`, the `.gitignore` lines), downloads Chromium, registers the tools with Claude Code and installs its *recording-product-demos* skill, and prints the config for Codex. Restart your agent afterwards — agents load tools at the start of a session.
+
+Prefer not to install globally? `npx retake-demos install` works the same. Don't use Claude Code? `retake agent` prints the MCP config for Codex, Cursor, or anything else.
+
+Then, in your agent:
+
+> Record a demo of my app at localhost:3000 showing a new user creating their first project.
+
+and in another terminal, `retake ui` → http://localhost:4310 to watch it happen. The agent reports its plan and progress there; the video, stills and receipts land there when it's done.
+
+`retake doctor` tells you if anything is missing.
+
+## What you get
+
+```
+outputs/<name>/
+  demo.mp4        the shareable — captions burned in
+  master.mp4      the CRF-14 keeper (post presets only)
+  stills/         one PNG per scene, mid-scene and at its last moment
+  thumbnail.png   the frame at a chosen scene
+  proof-log.md    result, shot list, every step's timing, pass/fail, what was on screen when it failed
+  take.json       the raw timeline the renderer reads
+```
+
+In the window: play it, switch speed (0.75× to 2×, re-rendered in seconds), download, show in Finder, open the file to edit. Demos group by the app they point at; archive what you're done with.
+
+## The loop
+
+Everything an agent does, you can do from the terminal:
+
+```bash
+retake validate demos/x.yaml   # schema + warnings, instant
+retake dry demos/x.yaml        # every selector and wait, no camera (~30s)
+retake run demos/x.yaml --preset draft   # first take, quarter-size, fast
+retake check outputs/x         # resolution, fps, duration, files: pass/fail
+retake run demos/x.yaml        # the real one
+retake render outputs/x        # captions/camera/speed changed? re-render, no browser
+```
+
+The expensive step comes last on purpose. `dry` catches most failures in seconds and prints the step, the error, and the text that was on screen; a failed `run` costs a minute and a confusing video. When a step fails during `run`, Retake stops, keeps what it has, and the proof log says which step and why — an agent fixes it from that text, never from watching the video.
+
+Exit codes: `0` good · `2` a step failed or the video is a raw fallback · `3` `dry`/`check` failed.
+
+## Demo-as-code
+
+```yaml
+name: first-project
+title: "Creating your first project"
+url: http://localhost:3000
+preset: post-landscape            # 1080p @ 30fps · `retake presets`
+viewport: { width: 1440, height: 1080 }
+scale: 1.8                        # page drawn at 1.8× so text stays crisp
+reducedMotion: true
+camera: auto                      # each scene eases toward the last thing touched
+
+seed: []                          # put the app in a known state first
+setup: []                         # runs before the camera; trimmed off the video
+
+steps:
+  - { action: scene, label: start, caption: "An empty workspace.", camera: static }
+  - { action: wait, ms: 1500 }
+  - { action: click, selector: "button:has-text('New project')", pauseAfter: 800 }
+  - { action: type, selector: "input[name=title]", text: "Q3 launch plan", delay: 40 }
+  - { action: click, selector: "button[type=submit]" }
+  - { action: waitFor, selector: ".project-header" }
+  - { action: scene, label: result, caption: "And it exists." }
+  - { action: wait, ms: 2500 }
+
+outputs:
+  thumbnail: { scene: result }
+```
+
+The full template is [`demos/example.yaml`](demos/example.yaml); `retake init` copies it into a new workspace.
+
+**Steps** — `click`, `type`, `fill`, `hover`, `drag`, `scroll`, `keyboard`, `navigate`, `wait`, `waitFor`, `evaluate`, `upload`, `download`, `screenshot`, `scene`. Every step takes `pauseAfter`, `waitFor`, `timeout`, `secret`. Targets are a selector, or a point — `{x, y}` or `{selector, dx, dy}` — for canvases and SVG editors. `${VAR}` expands from `.env` and fails loudly when unset.
+
+**Scenes** are the spine: `{ action: scene, label, caption }` at each beat. They take their timestamps from the actual run, so captions land on the frames they describe even when the app took 3 seconds this time and 11 the last.
+
+**Seeds** put the app in a known state before the camera: write a JSON file, run JS in the page, or run a shell command. **Setup** is the stuff that runs before recording and is trimmed off the front — logins live there. **`tempo`** speeds the finished video up or down at render time; **`lock`** names a shared resource so two demos that touch the same backend don't record over each other.
+
+## Quality
+
+Think in the publishing format, not the browser window.
+
+| Preset | Canvas | For |
+|---|---:|---|
+| `draft` | 960×540 @ 15fps | iterating — same layout as the finals at a quarter of the pixels, fastest |
+| `preview-fast` | 1920×1080 @ 24fps | checking timing and framing, hardware-encoded |
+| `post-landscape` *(default)* | 1920×1080 @ 30fps | the general-purpose demo, plus a CRF-14 master |
+| `post-square` | 1080×1080 @ 30fps | feeds |
+| `post-vertical` | 1080×1920 @ 30fps | shorts and reels |
+| `docs-gif` | 1440×900 @ 24fps | README and docs GIFs |
+| `master` | 1920×1080 @ 30fps | archive, CRF 12 |
+
+**Page scale** is what makes it crisp: the page lays out as if the viewport were smaller and every glyph is drawn at 2×, so 1080p text reads on a phone. **Camera** eases toward whatever the demo just touched, at render time, clamped so it can never crop the thing it points at — per scene: `camera: static` or `camera: { focus: ".result", zoom: 1.3 }`. Captions, camera, speed, trim, format and layout are all render-time: change them and `retake render` takes seconds, never touches the browser.
+
+## Signing in
+
+```yaml
+auth:
+  storageState: .auth/myapp.json   # session saved here, reused until stale
+  maxAgeHours: 8
+setup:
+  - { action: fill, selector: "#user", text: "${APP_USER}" }
+  - { action: fill, selector: "#password", text: "${APP_PASSWORD}", secret: true }
+  - { action: click, selector: "button[type=submit]" }
+```
+
+Secrets live in `.env`, never in a manifest. `secret: true` keeps a value out of the terminal, the window and the proof log — but not out of the video, which is why `validate` warns when a secret step is in `steps` rather than `setup`. A session is only saved when the sign-in actually succeeded. Use a demo account: the output is a video you may publish.
+
+Apps that keep their session in IndexedDB (Firebase) can't be restored from `storageState`; put the login in plain `setup` instead.
+
+## Limits worth knowing
+
+- **One page.** Retake records one tab. `keepInTab` (on by default) folds `window.open` and `target="_blank"` back into it, so popup logins and "preview" buttons stay on camera; flows that genuinely need a second window do not.
+- **~45 cursor moves per take.** The cursor overlay is one nested expression per move and ffmpeg's parser has a depth limit. `validate` warns, the recorder detects it, `check` fails. Split long stories into chapters of 30–45 seconds — the viewer agrees.
+- **`scale` uses CSS zoom**, which shifts the coordinate space some forms rely on for focus; if typing goes nowhere, `scale: 1`. (`deviceScaleFactor` is not the fix — Playwright's screencast never upscales.)
+- **macOS is where it's used daily.** `videotoolbox` hardware encoding falls back to libx264 elsewhere; Linux is untested beyond CI.
+
+## How it's built
+
+```
+src/
+  cli.ts          install · init · doctor · ui · run · dry · render · check · validate · describe · ideas
+  manifest.ts     zod schema, presets, warnings
+  record.ts       Playwright + testreel → take.json (seeds, auth, locks, stop-on-fail, drag)
+  dryrun.ts       every selector and wait, no camera
+  render.ts       ffmpeg: camera → layout → captions → demo/master, stills, check
+  edits.ts        structural edits agents make to a manifest (comments preserved)
+  operator/       the MCP server: 22 tools, from `scout` and `draft` to `run`, `look` and `done`
+  ui/             one http server, three pages, no framework, no build step
+skill/SKILL.md    what the agent is taught: order of operations, failures as text, when to stop
+demos/            manifests; outputs/ is where takes land
+```
+
+Recording and the cursor come from [testreel](https://github.com/greentfrapp/testreel); GIFs from [gifski](https://github.com/ImageOptim/gifski) when installed; ffmpeg from `ffmpeg-static`. Retake adds what the job needs on top: waiting on selectors, seeds, scenes with real timestamps, camera and captions at render time, presets, credentials, locks, structural edits, and the receipts.
+
+## Developing
+
+```bash
+git clone https://github.com/glebbogachev00/retake && cd retake
+npm install                      # also builds dist/
+npx playwright install chromium
+npm run retake -- run demos/todo-basics.yaml --preset draft   # a public app, no setup
+npm test && npm run typecheck
+```
+
+`npm run retake -- …` runs the TypeScript source; `retake …` is the built package — same code. See [CONTRIBUTING.md](CONTRIBUTING.md), [BACKLOG.md](BACKLOG.md), and [AGENTS.md](AGENTS.md) (what coding agents read when pointed at this folder). Found something off? The **Bug?** button in the window pre-fills an issue with the receipts.
+
+## License
+
+[MIT](LICENSE) — Gleb Bogachev.

package/assets/logo.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512" role="img" aria-label="Retake">
+  <!-- Retake: a play button built out of takes.
+       Five stacked bars — recorded runs — that together read as ▶.
+       The longest one is the take you keep. -->
+  <rect width="512" height="512" rx="112" fill="#1a1c1e"/>
+  <g fill="#eceee9">
+    <rect x="132" y="112" width="96"  height="46" rx="23" opacity="0.55"/>
+    <rect x="132" y="180" width="192" height="46" rx="23" opacity="0.8"/>
+    <rect x="132" y="248" width="288" height="46" rx="23" fill="#e8b04b"/>
+    <rect x="132" y="316" width="192" height="46" rx="23" opacity="0.8"/>
+    <rect x="132" y="384" width="96"  height="46" rx="23" opacity="0.55"/>
+  </g>
+</svg>

package/demos/example.yaml

@@ -0,0 +1,65 @@
+# A template. Copy it, point it at your app, replace the selectors.
+#
+#   retake validate demos/example.yaml     schema + warnings, instant
+#   retake dry demos/example.yaml          every selector and wait, no camera
+#   retake run demos/example.yaml          record + render → outputs/example/
+#
+# Or don't write it at all: once `retake install` has run, ask your coding
+# agent for "a demo of my app at localhost:3000 showing …" and it drafts,
+# dry-runs, records and checks this file for you. `retake ui` is the window
+# to watch it in.
+
+name: example
+title: "Example — the shape of a demo"
+url: http://localhost:3000
+
+preset: post-landscape        # 1080p @ 30fps · see `retake presets`
+viewport: { width: 1440, height: 1080 }   # match your app's natural shape
+scale: 1.8                    # page drawn at 1.8× so text stays crisp at 1080p
+reducedMotion: true           # calms infinite spinners and entrance animations
+camera: auto                  # each scene eases toward the last thing touched
+
+# Put the app in a known state before the camera rolls. Pick what fits:
+#   - { kind: file, path: /tmp/app/state.json, from: seeds/empty.json }
+#   - { kind: evaluate, script: "localStorage.clear()" }
+#   - { kind: command, run: "curl -X POST http://localhost:3000/api/test/reset" }
+seed: []
+
+# Runs before recording starts and is trimmed off the front of the video.
+# Sign-ins belong here — see the "Signing in" section of the README.
+setup: []
+
+steps:
+  - action: scene
+    label: start
+    caption: "The problem, before anything happens."
+    camera: static
+  - action: wait
+    ms: 1800
+
+  - action: click
+    selector: "button:has-text('Get started')"
+    pauseAfter: 900
+
+  - action: type
+    selector: "input[name=title]"
+    text: "A realistic thing a person would type"
+    delay: 40
+    pauseAfter: 600
+
+  - action: click
+    selector: "button[type=submit]"
+  - action: waitFor              # wait for the RESULT, never a fixed sleep
+    selector: ".result"
+    timeout: 30000
+
+  - action: scene
+    label: result
+    caption: "And the result, which is the whole point."
+  - action: wait
+    ms: 2600
+
+outputs:
+  mp4: true
+  gif: false                   # opt-in; gifski is used when installed
+  thumbnail: { scene: result }

package/dist/appserver.js

@@ -0,0 +1,316 @@
+/**
+ * Starting the person's app after an explicit Retake workflow requests it.
+ *
+ * Retake records web apps, so a dead port is a common dead end. The UI invokes
+ * this only after the person selects a project and asks Retake to scan or
+ * record it. External agents keep a separate opt-in gate in operator/tools.ts.
+ *
+ * The hard part is not spawning — it is knowing WHICH port. Next and Vite take
+ * the next free one and say so once, in their log. So we watch the log and the
+ * set of listening ports, and only report success when something answers.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import net from "node:net";
+import { spawn, execFileSync } from "node:child_process";
+/** Processes this server started, so it can stop them and not double-start. */
+const started = new Map();
+export const startedApps = () => [...started.entries()].map(([k, v]) => ({ key: k, ...v }));
+export function listeningPorts() {
+    try {
+        const out = execFileSync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"], { encoding: "utf8", timeout: 3000 });
+        const ports = new Set();
+        for (const line of out.split("\n")) {
+            const m = /:(\d{4,5})\s+\(LISTEN\)/.exec(line);
+            if (m)
+                ports.add(Number(m[1]));
+        }
+        return [...ports].filter((p) => p >= 1024 && p < 65535).sort((a, b) => a - b);
+    }
+    catch {
+        return [];
+    }
+}
+export async function answers(url, ms = 2500) {
+    try {
+        const r = await fetch(url, { signal: AbortSignal.timeout(ms) });
+        return r.status < 500;
+    }
+    catch {
+        return false;
+    }
+}
+/** Is something holding the port open? Cheap, and true long before a dev
+    server can actually answer — the two are minutes apart on a cold start. */
+export function portOpen(port, ms = 900) {
+    return new Promise((done) => {
+        const sock = net.connect({ port, host: "127.0.0.1" });
+        const end = (v) => { sock.destroy(); done(v); };
+        sock.setTimeout(ms);
+        sock.once("connect", () => end(true));
+        sock.once("timeout", () => end(false));
+        sock.once("error", () => end(false));
+    });
+}
+export async function waitForUrl(url, ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        if (await answers(url, 2000))
+            return true;
+        await new Promise((ok) => setTimeout(ok, 900));
+    }
+    return false;
+}
+/** Modern Next prints every useful fact on separate lines when the same
+    project is already running. Prefer the last live localhost URL: the first
+    one can be the short-lived port from the failed second launch. */
+function alreadyRunningHint(log, cwd) {
+    if (!/already running/i.test(log))
+        return null;
+    const urls = [...log.matchAll(/https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]):\d{2,5}/g)].map((m) => m[0]);
+    const dir = /^- Dir:\s+(.+)$/m.exec(log)?.[1]?.trim();
+    if (dir && path.resolve(dir) !== cwd)
+        return null;
+    const pid = Number(/^- PID:\s+(\d+)$/m.exec(log)?.[1] || 0) || undefined;
+    const url = [...new Set(urls)].at(-1);
+    return url ? { url, pid } : null;
+}
+/** The project's own way of starting itself. We do not invent commands. */
+export function startOffer(dir) {
+    const root = path.resolve(dir.replace(/^~/, os.homedir()));
+    const pkgFile = path.join(root, "package.json");
+    if (fs.existsSync(pkgFile)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
+            const scripts = pkg.scripts ?? {};
+            for (const name of ["dev", "start", "serve", "preview"]) {
+                if (scripts[name])
+                    return { command: `npm run ${name}`, script: scripts[name], dir: root };
+            }
+        }
+        catch { /* fall through */ }
+    }
+    // Vercel-style projects with no package.json (static + edge functions).
+    if (fs.existsSync(path.join(root, "vercel.json")) || fs.existsSync(path.join(root, "api"))) {
+        return { command: "vercel dev", script: "vercel dev", dir: root };
+    }
+    return null;
+}
+/** A port nothing is listening on, walking up from a sensible base. */
+async function freePort(from = 3200) {
+    const busy = new Set(listeningPorts());
+    for (let p = from; p < from + 60; p++)
+        if (!busy.has(p) && !(await portOpen(p, 300)))
+            return p;
+    return from + 61;
+}
+/** Say the same command again, but on a port of our choosing. Dev servers
+    disagree about flags and agree about $PORT, so we set both where we can. */
+function onPort(command, port) {
+    const flagged = /\b(next|vite|astro|nuxt|remix|ng|serve|http-server)\b/.test(command) && !/\bnpm run\b/.test(command)
+        ? `${command} --port ${port}`
+        : command;
+    return `PORT=${port} ${flagged}`;
+}
+function withWebpack(command) {
+    if (/\b--webpack\b/.test(command))
+        return command;
+    return /\bnpm run\b/.test(command) ? `${command} -- --webpack` : `${command} --webpack`;
+}
+/** A retried command is still the same app. Keep one map entry so a second
+    request reuses the process we moved instead of starting it again. */
+function startKey(cwd, command) {
+    let canonical = command;
+    if (/^PORT=\d+\s+/.test(canonical))
+        canonical = canonical.replace(/^PORT=\d+\s+/, "").replace(/\s+--port\s+\d+$/, "");
+    return `${cwd}::${canonical}`;
+}
+/** Start it and wait until something actually answers. Reports the real port. */
+export async function startApp(opts) {
+    const cwd = path.resolve(opts.dir.replace(/^~/, os.homedir()));
+    const key = startKey(cwd, opts.command);
+    const existing = started.get(key);
+    if (existing && existing.url && (await answers(existing.url)))
+        return { ok: true, url: existing.url, pid: existing.pid, log: "" };
+    // Do this before spawning. Otherwise an already-open expected port can win
+    // the readiness race and make us report somebody else's process as the app
+    // we just started, before our child has time to print EADDRINUSE.
+    if (opts.expectUrl && !opts.noRetry) {
+        const expected = Number(new URL(opts.expectUrl).port || 80);
+        if (await portOpen(expected, 300)) {
+            const next = await freePort();
+            opts.onProgress?.(`Port ${expected} is already in use — starting on ${next} instead.`);
+            return startApp({ ...opts, command: onPort(opts.command, next), expectUrl: `http://localhost:${next}`, noRetry: true });
+        }
+    }
+    const before = new Set(listeningPorts());
+    const logFile = path.join(os.tmpdir(), `retake-app-${Date.now()}.log`);
+    const out = fs.openSync(logFile, "a");
+    // A login shell so nvm/asdf/volta shims are on PATH, and its own process
+    // group so stopping it takes the whole tree with it.
+    const child = spawn("/bin/sh", ["-lc", opts.command], { cwd, env: process.env, stdio: ["ignore", out, out], detached: true });
+    child.unref();
+    started.set(key, { pid: child.pid ?? 0, logFile });
+    const tail = () => { try {
+        return fs.readFileSync(logFile, "utf8").split("\n").slice(-14).join("\n");
+    }
+    catch {
+        return "";
+    } };
+    const say = opts.onProgress ?? (() => { });
+    const handleExisting = async (log) => {
+        const hint = alreadyRunningHint(log, cwd);
+        if (!hint)
+            return null;
+        if (await answers(hint.url, 8000)) {
+            try {
+                process.kill(-(child.pid ?? 0), "SIGTERM");
+            }
+            catch { /* failed launch already ended */ }
+            say(`It is already running at ${hint.url} — using that.`);
+            started.set(key, { pid: 0, url: hint.url, logFile });
+            return { ok: true, url: hint.url, log };
+        }
+        if (!hint.pid || opts.restartedExisting)
+            return { ok: false, log, why: `the existing server at ${hint.url} is not responding` };
+        say(`The existing server at ${hint.url} is not responding — restarting it.`);
+        try {
+            process.kill(hint.pid, "SIGTERM");
+        }
+        catch {
+            return { ok: false, log, why: `the existing server at ${hint.url} could not be stopped` };
+        }
+        const port = Number(new URL(hint.url).port || 80);
+        for (let i = 0; i < 12 && (await portOpen(port, 400)); i++)
+            await new Promise((ok) => setTimeout(ok, 500));
+        if (await portOpen(port, 400)) {
+            say(`The stale server did not stop cleanly — force-stopping PID ${hint.pid}.`);
+            try {
+                process.kill(hint.pid, "SIGKILL");
+            }
+            catch { /* verify the port below */ }
+            for (let i = 0; i < 8 && (await portOpen(port, 300)); i++)
+                await new Promise((ok) => setTimeout(ok, 350));
+        }
+        if (await portOpen(port, 400))
+            return { ok: false, log, why: `the existing server at ${hint.url} did not stop` };
+        try {
+            process.kill(-(child.pid ?? 0), "SIGTERM");
+        }
+        catch { /* failed launch already ended */ }
+        const restarted = await startApp({ ...opts, expectUrl: hint.url, noRetry: true, restartedExisting: true });
+        if (restarted.ok && restarted.url)
+            started.set(key, { pid: restarted.pid ?? 0, url: restarted.url, logFile });
+        return restarted;
+    };
+    // Phase 1 — find the port. A dev server opens it within seconds and usually
+    // announces it in the log; it may not be able to answer for minutes yet.
+    const portUntil = Date.now() + 45_000;
+    let port = opts.expectUrl ? Number(new URL(opts.expectUrl).port || 80) : 0;
+    while (Date.now() < portUntil) {
+        const log = tail();
+        const existingResult = await handleExisting(log);
+        if (existingResult)
+            return existingResult;
+        if (child.exitCode !== null) {
+            if (/EADDRINUSE|address already in use|port \d+ is (?:already )?in use|another .* is already running/i.test(log) && !opts.noRetry) {
+                const p2 = await freePort();
+                say(`That port is taken — trying ${p2} instead.`);
+                return startApp({ ...opts, command: onPort(opts.command, p2), expectUrl: `http://localhost:${p2}`, noRetry: true, onProgress: opts.onProgress });
+            }
+            return { ok: false, log, why: `the command exited (${child.exitCode}) — see the log` };
+        }
+        if (port && (await portOpen(port)))
+            break;
+        const m = /https?:\/\/(?:localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0):(\d{2,5})/.exec(tail());
+        if (m && (await portOpen(Number(m[1])))) {
+            port = Number(m[1]);
+            break;
+        }
+        const fresh = listeningPorts().filter((p) => !before.has(p));
+        if (fresh.length) {
+            port = fresh[0];
+            break;
+        }
+        await new Promise((ok) => setTimeout(ok, 1000));
+    }
+    if (!port || !(await portOpen(port))) {
+        const log = tail();
+        // Two things a dev server says when it will not start, and both have a
+        // better answer than "failed". If it is already running, that is the app
+        // the person wanted — use it. If the port is simply taken, move over.
+        const existingResult = await handleExisting(log);
+        if (existingResult)
+            return existingResult;
+        const taken = /EADDRINUSE|address already in use|port \d+ is (?:already )?in use|another .* is already running/i.test(log);
+        if (taken && !opts.noRetry) {
+            const p2 = await freePort();
+            say(`Something already holds that port — trying ${p2} instead.`);
+            try {
+                process.kill(-(child.pid ?? 0), "SIGTERM");
+            }
+            catch { /* already gone */ }
+            return startApp({ ...opts, command: onPort(opts.command, p2), expectUrl: `http://localhost:${p2}`, noRetry: true, onProgress: opts.onProgress });
+        }
+        return { ok: false, log, why: "nothing opened a port within 45s — check the log" };
+    }
+    const url = `http://localhost:${port}`;
+    say(`Port ${port} is open — waiting for the first page to build…`);
+    // Phase 2 — be patient. A cold Next/Vite dev server compiles on the first
+    // request, and on a loaded machine that is minutes, not seconds. Failing at
+    // two seconds (as this used to) reports a working app as dead.
+    const answerUntil = Date.now() + (opts.seconds ?? 300) * 1000;
+    const answerStarted = Date.now();
+    while (Date.now() < answerUntil) {
+        const log = tail();
+        const existingResult = await handleExisting(log);
+        if (existingResult)
+            return existingResult;
+        if (child.exitCode !== null)
+            return { ok: false, log: tail(), why: `the command exited (${child.exitCode}) — see the log` };
+        if (await answers(url, 20_000)) {
+            started.set(key, { pid: child.pid ?? 0, url, logFile });
+            return { ok: true, url, pid: child.pid ?? undefined, log: tail() };
+        }
+        if (!opts.webpackFallback && Date.now() - answerStarted > 25_000 && /Next\.js[\s\S]*\(Turbopack\)/i.test(log)) {
+            say("The Turbopack server opened a port but did not serve the first page — retrying with webpack.");
+            try {
+                process.kill(-(child.pid ?? 0), "SIGTERM");
+            }
+            catch { /* verify below */ }
+            for (let i = 0; i < 12 && (await portOpen(port, 350)); i++)
+                await new Promise((ok) => setTimeout(ok, 450));
+            if (await portOpen(port, 350)) {
+                try {
+                    process.kill(-(child.pid ?? 0), "SIGKILL");
+                }
+                catch { /* retry reports a conflict if still alive */ }
+            }
+            const fallback = await startApp({ ...opts, command: onPort(withWebpack(opts.command), port), expectUrl: url, noRetry: true, webpackFallback: true });
+            if (fallback.ok && fallback.url)
+                started.set(key, { pid: fallback.pid ?? 0, url: fallback.url, logFile });
+            return fallback;
+        }
+        say("Still building…");
+    }
+    return { ok: false, log: tail(), why: `it opened ${url} but never finished building — check the log` };
+}
+export function stopApp(key) {
+    const s = started.get(key);
+    if (!s?.pid)
+        return false;
+    try {
+        process.kill(-s.pid, "SIGTERM");
+    }
+    catch {
+        try {
+            process.kill(s.pid, "SIGTERM");
+        }
+        catch {
+            return false;
+        }
+    }
+    started.delete(key);
+    return true;
+}