retake-demos 0.14.0 → 0.14.1

package/dist/cli.js

@@ -33,6 +33,7 @@
  * installed from npm, dist/cli.js is the `retake` binary. Same file.
  */
 import { BROWSERS, chromiumPath, installChromium, launchChromium } from "./browser-home.js";
+import { bundledFfmpeg, recorderPatched } from "./self-repair.js";
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
@@ -807,11 +808,14 @@ program
     try {
         const require = createRequire(import.meta.url);
         const ff = require("ffmpeg-static");
-        fs.existsSync(ff) ? ok(`ffmpeg ${ff}`) : no("ffmpeg-static is missing its binary — reinstall retake-demos");
+        fs.existsSync(ff) ? ok(`ffmpeg ${ff}`) : say("· ffmpeg not downloaded yet — the first render fetches it (or run: retake install)");
     }
     catch {
         no("ffmpeg-static not found — reinstall retake-demos");
     }
+    const patched = recorderPatched();
+    if (patched === false)
+        no("Retake's recorder patch is not applied — run any retake command once and it applies itself");
     const which = (bin) => spawnSync("which", [bin], { encoding: "utf8" }).stdout.trim();
     say(which("gifski") ? `✓ gifski (better GIFs)` : `· gifski not installed — GIFs fall back to ffmpeg (brew install gifski)`);
     say(which("claude") ? `✓ claude CLI — \`retake install\` can register the tools` : `· claude CLI not found — paste the config from \`retake agent\` into your agent`);
@@ -831,18 +835,38 @@ program
     // 1. the workspace: demos/ and outputs/ live where the command was run
     initWorkspace(process.cwd(), say);
     // 2. the browser
+    if (bundledFfmpeg())
+        say("✓ ffmpeg present");
+    else
+        say("✗ could not get ffmpeg — install it once (brew install ffmpeg) and try again");
     if (chromiumPath())
         say("✓ chromium present");
     else if (!installChromium(say))
         say("✗ could not download Chromium — run `npx playwright install chromium` and try again");
     // 3. the tools, registered with Claude Code for every project
     const server = mcpServer(o.ui);
+    // Running install again (an upgrade, a new workspace) finds the tools
+    // already registered — replace that registration rather than calling it
+    // a failure, so it points at this install and this folder.
+    const add = () => execFileSync("claude", ["mcp", "add-json", "retake", JSON.stringify(server), "--scope", "user"], { stdio: "pipe", encoding: "utf8" });
     try {
-        execFileSync("claude", ["mcp", "add-json", "retake", JSON.stringify(server), "--scope", "user"], { stdio: "pipe" });
+        add();
         say("✓ Claude Code: retake tools registered (user scope)");
     }
-    catch {
-        say("✗ Claude Code CLI not found or refused — run `retake agent` and paste the config yourself");
+    catch (e) {
+        const why = String(e.stderr ?? e.message ?? "");
+        let fixed = false;
+        if (/already exists/i.test(why)) {
+            try {
+                execFileSync("claude", ["mcp", "remove", "retake", "--scope", "user"], { stdio: "pipe" });
+                add();
+                fixed = true;
+            }
+            catch { /* fall through */ }
+        }
+        say(fixed ? "✓ Claude Code: retake tools re-registered for this folder (user scope)"
+            : /ENOENT/.test(why) ? "✗ Claude Code CLI not found — run `retake agent` and paste the config yourself"
+                : `✗ Claude Code refused to register the tools${why.trim() ? ` (${why.trim().split("\n").pop()})` : ""} — run \`retake agent\` and paste the config yourself`);
     }
     // 4. the skill: when to reach for the tools, and in what order
     const skillSrc = path.join(PKG_ROOT, "skill", "SKILL.md");

package/dist/media-bin.js

@@ -1,7 +1,5 @@
-import fs from "node:fs";
 import { execFileSync } from "node:child_process";
-import { createRequire } from "node:module";
-const require = createRequire(import.meta.url);
+import { bundledFfmpeg } from "./self-repair.js";
 let cachedBin;
 /** Resolve the bundled media binary first, then fall back to PATH. */
 export function ffmpegBin() {
@@ -11,14 +9,15 @@ export function ffmpegBin() {
         execFileSync(process.env.FFMPEG_BIN, ["-version"], { stdio: "ignore" });
         return (cachedBin = process.env.FFMPEG_BIN);
     }
+    // The bundled copy — fetched now if npm skipped its install script.
+    const bundled = bundledFfmpeg();
+    if (bundled)
+        return (cachedBin = bundled);
     try {
-        const bundled = require("ffmpeg-static");
-        if (bundled && fs.existsSync(bundled))
-            return (cachedBin = bundled);
+        execFileSync("ffmpeg", ["-version"], { stdio: "ignore" });
     }
     catch {
-        // Fall through to the system binary.
+        throw new Error("Retake needs ffmpeg and could not get its own copy — install it once (`brew install ffmpeg` on a Mac), or reinstall with `npm install -g --allow-scripts=retake-demos,ffmpeg-static retake-demos`");
     }
-    execFileSync("ffmpeg", ["-version"], { stdio: "ignore" });
     return (cachedBin = "ffmpeg");
 }

package/dist/operator/tools.js

@@ -12,6 +12,7 @@
  * happening in plain sentences.
  */
 import "../browser-home.js";
+import "../self-repair.js";
 import { hasLogin, loginStoreName, readLogin, siteOf } from "../logins.js";
 import { sessionAgeHours, sessionPathFor } from "../signin.js";
 import fs from "node:fs";

package/dist/record.js

@@ -122,6 +122,22 @@ export function persistentCssScript(css) {
     }
   })();`;
 }
+/** Present in the DOM is not the same as on screen. A page whose stylesheet
+    or web font is still on its way has every element the manifest waits for
+    and paints nothing: an agent's demo of a public site opened on two seconds
+    of blank page, and every check passed. So before the camera's clock
+    starts, let the page finish loading what it draws with — bounded, because
+    a busy site may never be "done", and the manifest's own gate already
+    proved the app is there. */
+export async function untilPainted(page) {
+    await page.waitForLoadState("load", { timeout: 8000 }).catch(() => { });
+    await page.evaluate(() => Promise.race([
+        document.fonts?.ready,
+        new Promise((ok) => setTimeout(ok, 4000)),
+    ])).catch(() => { });
+    // Two frames: the first after fonts swap in, the second actually drawn.
+    await page.evaluate(() => new Promise((ok) => requestAnimationFrame(() => requestAnimationFrame(() => ok(null))))).catch(() => { });
+}
 /** The session a take should start from, and whether it is still good.
     Shared so `dry` starts signed in exactly when `run` would — a dry run
     against a logged-out app "proving" a manifest is a wasted take waiting
@@ -626,6 +642,13 @@ export async function record(m, opts) {
         // --- setup phase (still inside the video; trimmed later by `trimBefore`) ---
         // Document first; idle only if it comes quickly. Busy public sites never
         // go network-idle, and the manifest's waitForSelector is the real gate.
+        // The video starts at the first frame the tab paints. Left to itself that
+        // is somewhere between the empty tab and the site's first paint — on a
+        // real site, measured, up to 1.5s after the moment we took for it, which
+        // left blank white frames at the front and every cursor move, scene cut
+        // and caption that late. So paint the tab once, now, and take THAT as
+        // the start: measured within ~0.1s on local and public sites alike.
+        const paintedAt = await paintFirstFrame(page);
         await page.goto(expandEnv(m.url), { waitUntil: "domcontentloaded", timeout: 60000 });
         // The manifest's readiness selectors are authoritative. Busy public apps
         // may never become network-idle; paying a fixed 8s before every take made
@@ -649,10 +672,11 @@ export async function record(m, opts) {
             }
         }
         await gateOnApp(page, m, opts.outDir);
+        await untilPainted(page);
         // Playwright's video begins at the first *painted* frame, not at newPage().
         // On a dev server that can be seconds later; if testreel's cursor overlay is
         // told the wrong start it draws every cursor move that many seconds late.
-        const videoStartedAt = await firstPaintWallClock(page);
+        const videoStartedAt = paintedAt ?? await firstPaintWallClock(page);
         t0 = videoStartedAt;
         // Idle-hide fades are nested if()s in testreel's ffmpeg alpha expression;
         // past roughly sixty steps the nesting exceeds ffmpeg's parser and the
@@ -1542,6 +1566,18 @@ export function describe(step) {
             return `scene: ${step.label}`;
     }
 }
+/** Paint the empty tab and return the wall-clock ms of that paint — the
+    video's first frame. Null if the page would not paint (then the old
+    estimate stands). It happens during setup, so it is trimmed away. */
+export async function paintFirstFrame(page) {
+    try {
+        await page.setContent('<html style="background:#fff;height:100%"><body></body></html>');
+        return Math.round(await page.evaluate(() => new Promise((ok) => requestAnimationFrame(() => requestAnimationFrame(() => ok(performance.timeOrigin + performance.now()))))));
+    }
+    catch {
+        return null;
+    }
+}
 /** Wall-clock ms when the recorded page's document committed — empirically
     where Playwright's first video frame lands (falls back to now). */
 async function firstPaintWallClock(page) {

package/dist/self-repair.js

@@ -0,0 +1,64 @@
+/** What npm was supposed to do at install, done at start if it did not.
+
+    Two of Retake's parts arrive by install script: the patch that lets the
+    recorder draw the cursor right (scripts/patch-testreel.mjs, Retake's own
+    postinstall) and ffmpeg itself (ffmpeg-static downloads its binary at
+    install). npm has begun asking before it runs install scripts for global
+    packages, so a person can end up with neither — and a recorder that drops
+    the cursor, or a render that cannot start, for a reason they never saw.
+
+    Import this before anything that loads testreel: the patch has to be on
+    disk before the recorder is read. Both repairs are idempotent and cheap
+    when nothing is missing (a file read, a stat). */
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+const say = (l) => process.stderr.write(l + "\n");
+/** The marks the patch leaves. All present → patched. */
+const MARKS = ["/*retake:flat-cursor-v2*/", "/*retake:coordinate-scale*/"];
+export function recorderPatched() {
+    try {
+        const src = fs.readFileSync(path.join(path.dirname(require.resolve("testreel")), "index.js"), "utf8");
+        return MARKS.every((m) => src.includes(m));
+    }
+    catch {
+        return null;
+    }
+}
+function patchRecorder() {
+    if (recorderPatched() !== false)
+        return;
+    const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts", "patch-testreel.mjs");
+    if (!fs.existsSync(script))
+        return;
+    const r = spawnSync(process.execPath, [script], { encoding: "utf8" });
+    if (recorderPatched())
+        say("✓ applied Retake's recorder patch (npm skipped it at install)");
+    else
+        say(`· could not apply Retake's recorder patch — long demos may lose the cursor. ${r.stdout?.trim().split("\n").pop() ?? ""}`);
+}
+/** ffmpeg-static's binary, fetched now if its install script never ran.
+    Returns its path, or null when there is no bundled copy to be had. */
+export function bundledFfmpeg() {
+    let bin = null;
+    try {
+        bin = require("ffmpeg-static");
+    }
+    catch {
+        return null;
+    }
+    if (!bin)
+        return null;
+    if (fs.existsSync(bin))
+        return bin;
+    const installer = path.join(path.dirname(require.resolve("ffmpeg-static/package.json")), "install.js");
+    if (!fs.existsSync(installer))
+        return null;
+    say("… downloading ffmpeg (one time, ~45 MB — npm skipped it at install)");
+    spawnSync(process.execPath, [installer], { cwd: path.dirname(installer), stdio: ["ignore", "ignore", "inherit"] });
+    return fs.existsSync(bin) ? bin : null;
+}
+patchRecorder();

package/dist/setup.js

@@ -503,7 +503,10 @@ export async function readBrand(url, outBase, o = {}) {
         // school's site it was a cartoon character, not the TechBash wordmark.
         // A wordmark set in text is captured as a picture, background removed.
         const head = page.locator(HEADER_LOGO).first();
-        const box = await head.boundingBox().catch(() => null);
+        // No header logo is common, and boundingBox() on nothing waits out
+        // Playwright's 30 seconds — a first-run screen that sat on "Reading your
+        // site…" for half a minute. Ask whether it exists first.
+        const box = (await head.count().catch(() => 0)) ? await head.boundingBox({ timeout: 2000 }).catch(() => null) : null;
         if (box && box.width >= 40 && box.height >= 14 && box.height <= 140 && box.y < 200) {
             const inner = await head.evaluate(`(el) => { const i = el.querySelector('img[src$=".svg"], img'); const s = el.querySelector('svg'); return { img: i ? i.src : null, svg: s && !i ? s.outerHTML : null }; }`).catch(() => null);
             fs.mkdirSync(path.dirname(outBase), { recursive: true });

package/dist/ui/server.js

@@ -22,6 +22,7 @@
  *   GET  /out/:name/<file>          artifacts (mp4/gif/png/md)
  */
 import "../browser-home.js";
+import "../self-repair.js";
 import { hasLogin, loginStoreName, saveLogin, siteOf } from "../logins.js";
 import { openHandSignIn, sessionAgeHours, sessionPathFor } from "../signin.js";
 import http from "node:http";

package/dist/voice.js

@@ -30,6 +30,30 @@ function engine() {
         return { cmd: "python3", args: ["-m", "edge_tts"] };
     throw new Error("voiceover needs edge-tts — install it once with `pipx install edge-tts` (or `pip install edge-tts`), then re-render");
 }
+/** Run edge-tts, and when it fails say why in a sentence a person can act on —
+    not the whole command line with the script pasted into it. The usual
+    failure is Microsoft's service refusing an out-of-date edge-tts (a 403):
+    it worked yesterday, it stops today, and upgrading fixes it. */
+export function edgeFailure(stderr, cmd) {
+    const upgrade = cmd === "python3" ? "`pip install -U edge-tts`" : "`pipx upgrade edge-tts` (or `pip install -U edge-tts`)";
+    if (/\b403\b|WSServerHandshakeError/.test(stderr))
+        return `voiceover: Microsoft's voice service refused the request (403). That almost always means edge-tts is out of date — run ${upgrade}, then re-render. If it is already current, check that this computer's clock is right.`;
+    if (/getaddrinfo|ClientConnectorError|Cannot connect|Network is unreachable|TimeoutError/i.test(stderr))
+        return "voiceover: could not reach Microsoft's voice service — is the network up? (edge-tts is a network service)";
+    const last = stderr.trim().split("\n").filter(Boolean).pop() ?? "";
+    return `voiceover: edge-tts failed${last ? ` — ${last.slice(0, 200)}` : ""}`;
+}
+function runEdge(e, args, timeout) {
+    try {
+        execFileSync(e.cmd, [...e.args, ...args], { stdio: "pipe", timeout });
+    }
+    catch (err) {
+        const x = err;
+        if (x.code === "ETIMEDOUT" || x.signal === "SIGTERM")
+            throw new Error("voiceover: Microsoft's voice service did not answer in time — try again in a minute");
+        throw new Error(edgeFailure(String(x.stderr ?? ""), e.cmd));
+    }
+}
 export function synthesize(text, voice, out, ratePercent = 0) {
     const cached = voiceCachePath(text, voice, ratePercent);
     if (fs.existsSync(cached) && fs.statSync(cached).size >= 200) {
@@ -39,7 +63,7 @@ export function synthesize(text, voice, out, ratePercent = 0) {
     const e = engine();
     const temp = `${out}.tmp-${process.pid}`;
     try {
-        execFileSync(e.cmd, [...e.args, "--voice", voice, "--rate", `${ratePercent >= 0 ? "+" : ""}${ratePercent}%`, "--text", text, "--write-media", temp], { stdio: "pipe", timeout: 60_000 });
+        runEdge(e, ["--voice", voice, "--rate", `${ratePercent >= 0 ? "+" : ""}${ratePercent}%`, "--text", text, "--write-media", temp], 60_000);
         if (!fs.existsSync(temp) || fs.statSync(temp).size < 200)
             throw new Error(`voiceover: nothing came back for “${text.slice(0, 40)}…” — is the network up? (edge-tts is a network service)`);
         fs.mkdirSync(path.dirname(cached), { recursive: true });
@@ -87,7 +111,7 @@ export function synthesizeWithCues(text, voice, out, ratePercent = 0) {
     const e = engine();
     const temp = `${out}.tmp-${process.pid}`, srt = `${out}.srt`;
     try {
-        execFileSync(e.cmd, [...e.args, "--voice", voice, "--rate", `${ratePercent >= 0 ? "+" : ""}${ratePercent}%`, "--text", text, "--write-media", temp, "--write-subtitles", srt], { stdio: "pipe", timeout: 120_000 });
+        runEdge(e, ["--voice", voice, "--rate", `${ratePercent >= 0 ? "+" : ""}${ratePercent}%`, "--text", text, "--write-media", temp, "--write-subtitles", srt], 120_000);
         if (!fs.existsSync(temp) || fs.statSync(temp).size < 200)
             throw new Error("voiceover: nothing came back — is the network up? (edge-tts is a network service)");
         const cues = parseSrt(fs.readFileSync(srt, "utf8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "retake-demos",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Demo-as-code for coding agents: a YAML manifest in, a product walkthrough video out. Rerun the demo instead of re-recording it.",
   "keywords": [
     "demo",
@@ -57,12 +57,12 @@
     "site:test:browser": "node --test test/landing.test.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "commander": "^14.0.3",
-    "playwright": "^1.58.2",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "commander": "14.0.3",
+    "playwright": "1.62.1",
     "testreel": "0.2.0",
-    "yaml": "^2.8.3",
-    "zod": "^4.4.3"
+    "yaml": "2.9.0",
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@types/node": "^22",

package/site/releases.json

@@ -1,6 +1,19 @@
 {
   "_readme": "What's new, written for the person using Retake — not for whoever wrote it. Both the landing page and the Retake window read THIS file; there is no second copy. Rules for adding one: say what changed for them, name no files, no flags they will not type, no words like refactor or regression. If a line only makes sense to someone who has read the source, it does not belong here. Newest first. Add an entry on every release that changes what people see.",
   "releases": [
+    {
+      "version": "0.14.1",
+      "date": "2026-10-16",
+      "headline": "Videos of real websites open on the website, and installing just works",
+      "notes": [
+        "Recording a live website (not one on your own computer) used to start with a second or two of blank white, and the cursor, captions and scene cuts ran that much late. Retake now marks the true start of every recording, so the video opens on the page and everything lands on its moment.",
+        "Pasting your site now shows your colours in a few seconds. On sites without a logo in their header, Retake used to sit on “Reading your site…” for half a minute first.",
+        "Installing gets exactly the versions Retake was tested with, instead of whatever was newest that day.",
+        "If npm skips Retake's install steps — newer versions of npm ask before running them — Retake now finishes them itself the first time it runs: it fetches ffmpeg and applies its recorder fix.",
+        "Running the install command again (after an update, or in a new folder) now updates your agent's connection instead of reporting a failure.",
+        "When Microsoft's voice service refuses a voiceover, Retake now says what fixes it — usually updating the voice tool — instead of showing the whole command it ran."
+      ]
+    },
     {
       "version": "0.14.0",
       "date": "2026-10-14",