retake-demos 0.2.1 → 0.3.0

package/dist/operator/tools.js

@@ -27,6 +27,7 @@ import { scout, draftManifest, suggestIdeas, pickProvider, loadDotenv } from "..
 import { digest } from "../digest.js";
 import { startApp as reallyStartApp, listeningPorts as ports, waitForUrl as waitUrl } from "../appserver.js";
 import { applyEdits, receiptsFor } from "../edits.js";
+import { SECRET_NAME, missingSecrets, readEnvFile } from "../env.js";
 const ROOT = process.env.RETAKE_ROOT || process.cwd();
 const DEMOS = path.join(ROOT, "demos");
 const OUT = process.env.RETAKE_OUT ? path.resolve(process.env.RETAKE_OUT.replace(/^~/, os.homedir())) : path.join(ROOT, "outputs");
@@ -129,7 +130,63 @@ server.registerTool("start_app", {
     await tell(`Could not start it: ${r.why}`);
     return text(`FAILED: ${r.why}\nlog tail:\n${r.log.slice(-800)}`);
 });
-server.registerTool("ask", { description: "Ask the person ONE question and wait for the answer. Use only when genuinely blocked (which app, a credential name, a choice between two things). Keep it one sentence, with the evidence.", inputSchema: { question: z.string() }, annotations: RETAKE_WRITE }, async ({ question }) => {
+server.registerTool("secrets", {
+    description: [
+        "Get the person's demo-account credentials into place WITHOUT ever seeing them. Call this the moment a demo needs a login (read_project found sign-in fields, scout found a password field, or they said so): pass the variable NAMES you will use (APP_USER, APP_PASSWORD, and APP_TOTP_SECRET if the site asks for an authenticator code).",
+        "It returns at once with what to tell the person — ALWAYS relay it in full, with the link: assume they have never seen the Retake window and do not know it exists. They type the values into a form there (or into their terminal); the values go straight into the workspace .env; you only ever learn 'set'. When they say they are done, call this tool again with the same names.",
+        "Then the manifest references them as ${APP_USER} / ${APP_PASSWORD} with `secret: true`, inside auth.setup. Never ask for a password in chat, never put a literal credential in a manifest, never invent values. For logins a script cannot do (SMS code, SSO, captcha): `retake signin demos/<name>.yaml` — the person signs in once in a real window and Retake keeps the session.",
+    ].join(" "),
+    inputSchema: {
+        names: z.array(z.string().regex(SECRET_NAME, "UPPER_SNAKE names like APP_PASSWORD")).min(1).describe("the environment variable names the manifest will reference"),
+        why: z.string().describe("one sentence the person will read: what the login is for, e.g. 'The dashboard demo starts behind the admin sign-in.'"),
+    },
+    annotations: RETAKE_WRITE,
+}, async ({ names, why }) => {
+    const reload = () => { for (const [k, v] of Object.entries(readEnvFile(ROOT)))
+        if (v.trim())
+            process.env[k] = v; };
+    const how = `Reference them as ${names.map((n) => "${" + n + "}").join(", ")} with \`secret: true\` inside auth.setup${names.some((n) => /TOTP/.test(n)) ? ` (the authenticator one as ${"${TOTP:" + names.find((n) => /TOTP/.test(n)) + "}"} — Retake computes the current code)` : ""}. The values stay in .env; you never see them, and they are never on camera.`;
+    reload();
+    let missing = missingSecrets(ROOT, names);
+    if (!missing.length)
+        return text(`All set: ${names.join(", ")} are in the workspace .env. ${how} Continue.`);
+    const link = UI || "http://localhost:4310";
+    const list = missing.join(" and ");
+    // Is the window actually there? A dead URL must not leave the person
+    // staring at a link that does nothing.
+    const windowUp = UI ? await fetch(`${UI}/api/settings`).then((r) => r.ok).catch(() => false) : false;
+    if (windowUp) {
+        // One open form per set of names — calling again must not stack forms.
+        const pending = await fetch(`${UI}/api/secrets/pending`).then((r) => r.json()).catch(() => []);
+        let req = pending.find((r) => r.names.join() === missing.join());
+        if (req) {
+            // Second call: they said "done" (or we are checking). Give the form a
+            // short moment, then report — never sit here in silence.
+            const deadline = Date.now() + 20_000;
+            while (Date.now() < deadline) {
+                const st = await fetch(`${UI}/api/secrets/${req.id}`).then((x) => x.json()).catch(() => null);
+                if (st?.filled)
+                    break;
+                await new Promise((ok) => setTimeout(ok, 2000));
+            }
+            reload();
+            missing = missingSecrets(ROOT, names);
+            if (!missing.length)
+                return text(`Set: ${names.join(", ")} — saved to the workspace .env from the Retake window. ${how} Continue.`);
+            return text(`Not yet — ${missing.join(", ")} still empty. The form is still open in the Retake window. Tell them again, with the link: “Open ${link} — there is a form waiting for ${list}. Type the demo account's values, press Save to .env, and tell me when it's done.” Then call secrets again.`);
+        }
+        try {
+            const r = await fetch(`${UI}/api/secrets/request`, { method: "POST", body: JSON.stringify({ names: missing, why }) });
+            if (!r.ok)
+                throw new Error(String(r.status));
+            await tell(`Waiting for you: ${missing.join(", ")} — a form is open in the window.`);
+            return text(`A form is now open in the Retake window. Tell the person this, including the link: “Open ${link} in your browser — a form is waiting there for ${list}. Use a demo account for the app (the result is a video). What you type is saved to one local file on your computer and never sent to me or anywhere else. Press Save to .env, then tell me it's done.” When they say done, call secrets again with the same names.`);
+        }
+        catch { /* fall through to the terminal route */ }
+    }
+    return text(`The Retake window is not open. Tell the person this, exactly: “Retake needs a demo account for this app. Either run \`retake ui\` and open ${link} — I'll ask you there — or run \`retake secret ${missing.join(" ")}\` in your Retake workspace folder and type the values into the terminal (hidden, kept on your machine). If the sign-in needs a code from your phone, SSO or a captcha, run \`retake signin demos/<name>.yaml\` instead and log in once by hand. Tell me when it's done.” Then call secrets again with the same names.`);
+});
+server.registerTool("ask", { description: "Ask the person ONE question and wait for the answer. Use only when genuinely blocked (which app, a choice between two things). Keep it one sentence, with the evidence. NEVER for passwords or tokens — that is what `secrets` is for.", inputSchema: { question: z.string() }, annotations: RETAKE_WRITE }, async ({ question }) => {
     try {
         const a = await waitForHuman("question", question);
         return text(`They answered: ${a}`);
@@ -249,7 +306,7 @@ server.registerTool("read_manifest", { description: "The YAML of a demo.", input
         return text(`no demo "${name}"`);
     return text(fs.readFileSync(manifestPath(name), "utf8"));
 });
-server.registerTool("write_manifest", { description: "Create or replace a demo's YAML. It is validated; errors come back instead of being written. Prefer `edit` for small changes to an existing demo.", inputSchema: { name: z.string(), yaml: z.string() }, annotations: RETAKE_WRITE }, async ({ name, yaml }) => {
+server.registerTool("write_manifest", { description: "Create or replace a demo's YAML. It is validated; errors come back instead of being written. Prefer `edit` for small changes to an existing demo. ALWAYS set `mode:`. `mode: demo` (the default) proves how something works and keeps everything but the product out of the frame — a client walkthrough, a PR clip, a bug repro, a lesson, anything for someone who already wants to know how it works. `mode: launch` presents the product in public (a launch, a post, an ad, a landing page) and is the ONLY mode where intro/outro cards, music, callouts and a branded ending belong — and a launch cut ends with THEIR product, never with Retake. Decide from the AUDIENCE, not the subject, and never upgrade a demo to a launch yourself: if you are unsure, use demo and ask.", inputSchema: { name: z.string(), yaml: z.string() }, annotations: RETAKE_WRITE }, async ({ name, yaml }) => {
     LAST_DEMO = name;
     if (!safe(name))
         return text("name must be kebab-case");
@@ -269,7 +326,7 @@ server.registerTool("write_manifest", { description: "Create or replace a demo's
     await tell(`Wrote demos/${name}.yaml — ${r.data.steps.length} steps, ${r.data.steps.filter((s) => s.action === "scene").length} scenes`);
     return text(`written: demos/${name}.yaml (${r.data.steps.length} steps)`);
 });
-server.registerTool("draft", { description: "Let Retake draft a manifest from a sentence: scouts the URL (and reads the project if given) and writes demos/<name>.yaml. Then dry-run it.", inputSchema: { name: z.string(), url: z.string().url(), describe: z.string(), project: z.string().optional() }, annotations: RETAKE_WRITE }, async ({ name, url, describe, project }) => {
+server.registerTool("draft", { description: "Let Retake draft a manifest from a sentence: scouts the URL (and reads the project if given) and writes demos/<name>.yaml. Then dry-run it. Drafts are always `mode: demo` — nothing in the frame but the product. If this is a launch or a post, say so afterwards with edit (see write_manifest for what launch mode allows).", inputSchema: { name: z.string(), url: z.string().url(), describe: z.string(), project: z.string().optional() }, annotations: RETAKE_WRITE }, async ({ name, url, describe, project }) => {
     LAST_DEMO = name;
     if (!safe(name))
         return text("name must be kebab-case");
@@ -284,7 +341,7 @@ server.registerTool("draft", { description: "Let Retake draft a manifest from a
     await tell(`Drafted demos/${name}.yaml — ${m.steps.length} steps, ${m.steps.filter((s) => s.action === "scene").length} scenes`);
     return text(`drafted demos/${name}.yaml (${m.steps.length} steps). Next: dry.\n\n${d.yaml}`);
 });
-server.registerTool("edit", { description: "Make small structured changes to a demo without rewriting it: captions, camera, holds, trim, waits, selectors, text; delete_step; insert_step {after, step:{action,…}} to add one step; set_step {step, value:{action,…}} to replace one. Steps are validated. Keeps comments. Returns what changed and whether it needs re-recording. Prefer this over write_manifest — one verb costs a line, a rewrite costs the file.", inputSchema: { name: z.string(), edits: z.array(z.object({ op: z.string() }).passthrough()) }, annotations: RETAKE_WRITE }, async ({ name, edits }) => {
+server.registerTool("edit", { description: "Make small structured changes to a demo without rewriting it: captions, camera, holds, trim, waits, selectors, text; delete_step; insert_step {after, step:{action,…}} to add one step; set_step {step, value:{action,…}} to replace one. Steps are validated. Keeps comments. Returns what changed and whether it needs re-recording. Prefer this over write_manifest — one verb costs a line, a rewrite costs the file. Turning a demo into a launch cut is edits too: set mode: launch, then intro/outro cards, one callout at most, music (their file), compressIdle. Never do that unasked — a demo is the default and a client walkthrough is a demo.", inputSchema: { name: z.string(), edits: z.array(z.object({ op: z.string() }).passthrough()) }, annotations: RETAKE_WRITE }, async ({ name, edits }) => {
     LAST_DEMO = name;
     if (!safe(name) || !fs.existsSync(manifestPath(name)))
         return text(`no demo "${name}"`);
@@ -303,7 +360,7 @@ server.registerTool("dry", { description: "Run a demo with no camera: every sele
     await tell(r.ok ? `Checked: all ${manifest.steps.length} steps resolve` : `${r.failures} step(s) would fail`);
     return text(r.ok ? `ok: all ${manifest.steps.length} steps resolve` : r.lines.join("\n"));
 });
-server.registerTool("run", { description: "Record the demo and render it. Slow (the demo is performed in real time). preview=true for a fast low-cost render to check the story. Returns the receipts.", inputSchema: { name: z.string(), preview: z.boolean().default(true), until: z.string().optional().describe("record up to the end of this scene label, then stop — for iterating on one beat of a long demo") }, annotations: RETAKE_WRITE }, async ({ name, preview, until }) => {
+server.registerTool("run", { description: "Record the demo and render it. Slow (the demo is performed in real time). preview=true for a fast low-cost render to check the story. Returns the receipts. `check: pass` and healthy audio prove the FILE is sound, not that the demo is good — call `look` at the payoff scene and judge it: can a stranger state the promise from that frame, is the result legible at playback size, is any beat longer than what it tells you? If you cannot answer yes, fix the cut before calling done.", inputSchema: { name: z.string(), preview: z.boolean().default(true), until: z.string().optional().describe("record up to the end of this scene label, then stop — for iterating on one beat of a long demo") }, annotations: RETAKE_WRITE }, async ({ name, preview, until }) => {
     LAST_DEMO = name;
     if (!safe(name) || !fs.existsSync(manifestPath(name)))
         return text(`no demo "${name}"`);

package/dist/pace.js

@@ -0,0 +1,99 @@
+/**
+ * Idle compression: the app's dead time, shortened at render.
+ *
+ * The take's own timeline is the honest signal — a waitFor or navigate step
+ * records exactly how long the viewer sat looking at nothing changing. Each
+ * such stretch is shown as ~keepSeconds: the real start at 1×, then the rest
+ * fast-forwarded. The author's `wait` steps are pacing and are never touched;
+ * scene holds stay exactly as written.
+ *
+ * Implemented as a pre-pass: the source video is re-cut into a warped source
+ * and every clock in the take (timeline, trim, duration) is remapped through
+ * the same piecewise-linear warp, so captions, camera keys and stills land
+ * where they always did — the rest of the render pipeline never knows.
+ */
+import path from "node:path";
+/** The app made the viewer wait: show the start, fast-forward the rest. */
+const WAITING = new Set(["waitFor", "navigate"]);
+/** Only stretches meaningfully longer than what we would keep are worth a cut. */
+const SLACK = 0.6;
+/** Typing is not dead time — it is the person speaking — so it keeps its
+    start AND its finish at real speed and only accelerates the middle. Every
+    keystroke is a round-trip to the browser (~57ms whatever `delay` says), so
+    a real sentence costs five seconds nobody watches. */
+const TYPE_BUDGET = 2.4;
+const TYPE_HEAD = 0.8;
+const TYPE_TAIL = 0.7;
+/** Plan the warp: 1× everywhere except the tail of each long app-wait and the
+    middle of each long typing run. */
+export function planIdle(take, keepSeconds) {
+    const segs = [];
+    for (const e of take.timeline) {
+        if (!e.ok)
+            continue;
+        const dur = e.end - e.start;
+        if (WAITING.has(e.action)) {
+            if (dur < keepSeconds + SLACK)
+                continue;
+            // Head at real speed, tail fast-forwarded into the remaining budget.
+            const head = keepSeconds * 0.6;
+            const shownTail = keepSeconds * 0.4;
+            segs.push({ from: e.start + head, to: e.end, rate: (dur - head) / shownTail });
+        }
+        else if (e.action === "type" || e.action === "fill") {
+            if (dur < TYPE_BUDGET + SLACK)
+                continue;
+            const middle = dur - TYPE_HEAD - TYPE_TAIL;
+            const shownMiddle = Math.max(0.3, TYPE_BUDGET - TYPE_HEAD - TYPE_TAIL);
+            segs.push({ from: e.start + TYPE_HEAD, to: e.end - TYPE_TAIL, rate: middle / shownMiddle });
+        }
+    }
+    return segs.sort((a, b) => a.from - b.from);
+}
+/** Source time → warped time. */
+export function warpTime(segs, t) {
+    let out = t;
+    for (const s of segs) {
+        if (t <= s.from)
+            break;
+        const inSeg = Math.min(t, s.to) - s.from;
+        out -= inSeg - inSeg / s.rate;
+    }
+    return out;
+}
+/** The take with every clock remapped. */
+export function warpTake(take, segs) {
+    const w = (t) => warpTime(segs, t);
+    return {
+        ...take,
+        trimBefore: w(take.trimBefore),
+        duration: w(take.duration),
+        timeline: take.timeline.map((e) => ({ ...e, start: w(e.start), end: w(e.end) })),
+    };
+}
+/** ffmpeg args to cut the raw source into the warped source. */
+export function warpFilterArgs(src, segs, duration, out) {
+    // Alternating 1× and fast segments covering [0, duration].
+    const pieces = [];
+    let cur = 0;
+    for (const s of segs) {
+        if (s.from > cur)
+            pieces.push({ a: cur, b: s.from, rate: 1 });
+        pieces.push({ a: s.from, b: s.to, rate: s.rate });
+        cur = s.to;
+    }
+    if (cur < duration)
+        pieces.push({ a: cur, b: duration, rate: 1 });
+    const graph = pieces.map((p, i) => `[0:v]trim=start=${p.a.toFixed(3)}:end=${p.b.toFixed(3)},setpts=(PTS-STARTPTS)/${p.rate.toFixed(4)}[s${i}]`).join(";") +
+        ";" + pieces.map((_, i) => `[s${i}]`).join("") + `concat=n=${pieces.length}:v=1:a=0[out]`;
+    return ["-i", path.resolve(src), "-filter_complex", graph, "-map", "[out]", "-an", out];
+}
+/** Human line for the proof log. */
+export function describeIdle(take, segs) {
+    return segs.map((s) => {
+        const e = take.timeline.find((x) => x.start <= s.from && x.end >= s.to);
+        const real = e ? e.end - e.start : s.to - s.from;
+        const shown = real - (s.to - s.from) + (s.to - s.from) / s.rate;
+        return `${e ? e.summary.slice(0, 52) : "wait"}: ${real.toFixed(1)}s shown as ${shown.toFixed(1)}s`;
+    });
+}

package/dist/presets.js

@@ -8,7 +8,7 @@ export const PRESETS = {
         name: "draft",
         width: 960, height: 540, scale: 1, fps: 15, crf: 0,
         gif: false, layout: "band", cameraZoom: 1.2,
-        cursorSize: 36, captionFontSize: 24, bandHeight: 76,
+        cursorSize: 36, captionFontSize: 24, bandHeight: 76, bandFit: "text",
         encoder: "videotoolbox", master: false,
         description: "Fastest. Same layout as the final at a quarter of the pixels — for iterating, never for shipping.",
     },
@@ -16,7 +16,7 @@ export const PRESETS = {
         name: "preview-fast",
         width: 1920, height: 1080, scale: 2, fps: 24, crf: 0,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
         encoder: "videotoolbox", master: false,
         description: "Same framing as post, hardware-encoded MP4 only. For checking timing and framing fast.",
     },
@@ -24,7 +24,7 @@ export const PRESETS = {
         name: "proof-fast",
         width: 960, height: 720, scale: 1, fps: 24, crf: 24,
         gif: false, layout: "band", cameraZoom: 1.2,
-        cursorSize: 40, captionFontSize: 26, bandHeight: 84,
+        cursorSize: 40, captionFontSize: 26, bandHeight: 84, bandFit: "text",
         encoder: "videotoolbox", master: false,
         description: "Small, quick internal check.",
     },
@@ -32,7 +32,7 @@ export const PRESETS = {
         name: "post-landscape",
         width: 1920, height: 1080, scale: 2, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
         encoder: "x264", master: true,
         description: "1080p, 30fps, CRF 17. The general-purpose demo. GIF on request.",
     },
@@ -41,25 +41,25 @@ export const PRESETS = {
         /* The page area is the canvas minus the caption band, so the file really
            is 1080×1080 — a square preset that produced 1080×1210 got letterboxed
            by every feed. Landscape keeps its full-height page on purpose. */
-        width: 1080, height: 950, scale: 1.6, fps: 30, crf: 17,
+        width: 1080, height: 960, scale: 1.6, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 60, captionFontSize: 40, bandHeight: 130,
+        cursorSize: 60, captionFontSize: 36, bandHeight: 120, bandFit: "fill",
         encoder: "x264", master: true,
-        description: "A true 1080×1080 (page 1080×950 + caption band), feed-friendly.",
+        description: "A true 1080×1080 (page 1080×960 + a fixed 120px caption band), feed-friendly.",
     },
     "post-vertical": {
         name: "post-vertical",
-        width: 1080, height: 1750, scale: 2, fps: 30, crf: 17,
+        width: 1080, height: 1800, scale: 2, fps: 30, crf: 17,
         gif: false, layout: "band", cameraZoom: 1.3,
-        cursorSize: 60, captionFontSize: 44, bandHeight: 170,
+        cursorSize: 60, captionFontSize: 40, bandHeight: 120, bandFit: "fill",
         encoder: "x264", master: true,
-        description: "A true 1080×1920 (page 1080×1750 + caption band) for shorts/reels. Narrow-column apps suit it best.",
+        description: "A true 1080×1920 (page 1080×1800 + a fixed 120px caption band) for shorts/reels. Narrow-column apps suit it best.",
     },
     "docs-gif": {
         name: "docs-gif",
         width: 1440, height: 900, scale: 1.5, fps: 24, crf: 20,
         gif: { width: 900, fps: 15 }, layout: "band", cameraZoom: 1.2,
-        cursorSize: 48, captionFontSize: 32, bandHeight: 100,
+        cursorSize: 48, captionFontSize: 32, bandHeight: 100, bandFit: "text",
         encoder: "x264", master: false,
         description: "README/docs GIF, 900px wide.",
     },
@@ -67,7 +67,7 @@ export const PRESETS = {
         name: "master",
         width: 1920, height: 1080, scale: 2, fps: 30, crf: 12,
         gif: false, layout: "band", cameraZoom: 1.25,
-        cursorSize: 72, captionFontSize: 46, bandHeight: 150,
+        cursorSize: 72, captionFontSize: 46, bandHeight: 150, bandFit: "text",
         encoder: "x264", master: true,
         description: "Highest quality, slowest. Archive/source render.",
     },

package/dist/record.js

@@ -44,7 +44,11 @@ export function capSecondsFor(m) {
     return Math.min(3600, Math.max(240, Math.round(m.steps.length * 10 + waits)));
 }
 /** Roughly how many times the cursor will move on camera. */
-export const CURSOR_MOVE_LIMIT = 45;
+/** Cursor moves per take. testreel's nested-if overlay died at ~45 (ffmpeg's
+    parser stops at 98 levels); scripts/patch-testreel.mjs flattens those
+    expressions, so the ceiling is now the size of the filter graph as one
+    argv string — ~630 bytes a move against Linux's 128 KB per-argument cap. */
+export const CURSOR_MOVE_LIMIT = 180;
 export function cursorMoves(m) {
     return m.steps.filter((s) => ["click", "type", "fill", "hover", "scroll", "upload"].includes(s.action)).length;
 }
@@ -187,6 +191,10 @@ export async function record(m, opts) {
     const stateFresh = !!statePath && fs.existsSync(statePath) && (Date.now() - fs.statSync(statePath).mtimeMs) / 3.6e6 < (m.auth?.maxAgeHours ?? 72);
     if (statePath)
         log(stateFresh ? `auth: reusing session ${path.relative(process.cwd(), statePath)}` : `auth: no fresh session — running setup to sign in`);
+    // No session and nothing that could create one: stop here rather than record
+    // a logged-out take that passes every check.
+    if (statePath && !stateFresh && !(m.auth?.setup?.length))
+        throw new Error(`no fresh session at ${path.relative(process.cwd(), statePath)} and no auth.setup to sign in with — run \`retake signin ${path.relative(process.cwd(), path.join(opts.manifestDir, m.name + ".yaml"))}\` and log in once by hand, or add the sign-in steps under auth.setup`);
     const context = await browser.newContext({
         viewport: size,
         colorScheme: m.colorScheme,
@@ -293,10 +301,7 @@ export async function record(m, opts) {
         // past roughly sixty steps the nesting exceeds ffmpeg's parser and the
         // composite fails. Long demos get an always-visible cursor unless told
         // otherwise — the fade was never the point of the video.
-        const LONG = 60;
-        const cursorIdleHide = q.cursor === false ? undefined : q.cursor.idleHide ?? (m.steps.length <= LONG);
-        if (q.cursor !== false && q.cursor.idleHide === undefined && m.steps.length > LONG)
-            log(`cursor: ${m.steps.length} steps — idle-hide fades off (ffmpeg nesting limit); set cursor.idleHide to override`);
+        const cursorIdleHide = q.cursor === false ? undefined : q.cursor.idleHide;
         const rec = await recordPage(page, {
             outputDir: opts.outDir,
             name: m.name,
@@ -331,6 +336,10 @@ export async function record(m, opts) {
         if (statePath && !stateFresh && authOk) {
             fs.mkdirSync(path.dirname(statePath), { recursive: true });
             await context.storageState({ path: statePath });
+            try {
+                fs.chmodSync(statePath, 0o600);
+            }
+            catch { /* windows */ }
             log(`auth: saved session → ${path.relative(process.cwd(), statePath)}`);
         }
         else if (statePath && !stateFresh) {
@@ -343,7 +352,7 @@ export async function record(m, opts) {
         // overlay silently fails and the video ships with no cursor at all.
         const moves = cursorMoves(m);
         if (q.cursor !== false && moves > CURSOR_MOVE_LIMIT)
-            log(`cursor: ~${moves} cursor moves — testreel's overlay cannot exceed ~${CURSOR_MOVE_LIMIT}; the cursor may be MISSING from this video. Split the demo, or set cursor: false to be honest about it.`);
+            log(`cursor: ~${moves} cursor moves — past ~${CURSOR_MOVE_LIMIT} the cursor filter no longer fits in one ffmpeg argument and the overlay may be MISSING. Split the demo (a viewer wants chapters anyway), or set cursor: false to be honest about it.`);
         let pastUntil = false;
         for (const [i, step] of m.steps.entries()) {
             // --until <scene>: record that scene in full, stop at the next one.
@@ -365,6 +374,15 @@ export async function record(m, opts) {
                 end: 0,
                 ok: true,
             };
+            if (step.action === "callout") {
+                // Resolve the box now; the ring itself is drawn at render time.
+                const target = step.selector ?? step.at;
+                const c = await resolvePoint(page, target, step.timeout ?? 10_000);
+                const half = typeof target === "string" || !("x" in target)
+                    ? await page.locator((typeof target === "string" ? target : target.selector)).first().evaluate((el) => { const r = el.getBoundingClientRect(); return { w: r.width, h: r.height }; }).catch(() => ({ w: 48, h: 48 }))
+                    : { w: 48, h: 48 };
+                entry.callout = { box: { x: c.x - half.w / 2, y: c.y - half.h / 2, width: half.w, height: half.h }, label: step.label, ms: step.ms };
+            }
             if (step.action === "scene") {
                 entry.label = step.label;
                 entry.caption = step.caption;
@@ -430,7 +448,7 @@ export async function record(m, opts) {
             screenshots = result.screenshots;
             const joined = compositeLog.join("");
             if (/Error initializing filters|Missing '\)' or too many args/.test(joined)) {
-                const why = `cursor overlay failed in testreel's ffmpeg pass (expression too deep — ~${moves} moves, limit ~${CURSOR_MOVE_LIMIT}); the video has NO CURSOR. Split the demo or set cursor: false.`;
+                const why = `cursor overlay failed in testreel's ffmpeg pass (~${moves} moves; the filter is too large past ~${CURSOR_MOVE_LIMIT}); the video has NO CURSOR. Split the demo or set cursor: false.`;
                 partial = partial ? `${partial}; ${why}` : why;
                 ok = false;
                 log(`✗ ${why}`);
@@ -480,10 +498,18 @@ export async function record(m, opts) {
     // calibrated to within ~0.2s of the first video frame on a warm route). The
     // real file length is authoritative for the end.
     const trimBefore = sec(setupEnd - t0);
-    const duration = video ? videoDuration(video) : sec(endMs - t0);
+    // The recording keeps rolling while the browser is torn down, so the raw
+    // video always has a tail of nothing after the last step. The take ends
+    // where the demo ends (plus a breath), never where the recorder stopped —
+    // otherwise every video ships with dead seconds at the end.
+    const GRACE = 0.4;
+    const videoSec = video ? videoDuration(video) : sec(endMs - t0);
     const last = timeline.at(-1);
-    if (last && Math.abs(duration - last.end) > 3) {
-        log(`note: video is ${duration.toFixed(1)}s but the last step ended at ${last.end.toFixed(1)}s — check anchoring`);
+    const duration = last && videoSec > last.end + GRACE + 0.1 ? last.end + GRACE : videoSec;
+    if (last && duration < videoSec - 0.05)
+        log(`trim: ${(videoSec - duration).toFixed(1)}s of tail after the last step dropped`);
+    if (last && videoSec < last.end - 0.5) {
+        log(`note: video is ${videoSec.toFixed(1)}s but the last step ended at ${last.end.toFixed(1)}s — check anchoring`);
     }
     const finishedAt = new Date().toISOString();
     const take = {
@@ -614,7 +640,7 @@ async function runStep(rec, page, step, m, ctx) {
             await rec.click(step.selector, { timeout, zoom: step.zoom });
             break;
         case "type":
-            await rec.type(step.selector, expandEnv(step.text), { delay: step.delay ?? 70, clear: step.clear, timeout });
+            await rec.type(step.selector, expandEnv(step.text), { delay: step.delay ?? (m.typing === "brisk" ? 22 : 70), clear: step.clear, timeout });
             break;
         case "fill":
             await rec.fill(step.selector, expandEnv(step.text), { timeout });
@@ -694,6 +720,11 @@ async function runStep(rec, page, step, m, ctx) {
         case "stub":
             await ctx.stub({ url: step.url, method: step.method, status: step.status ?? 200, json: step.json, from: step.from, contentType: "application/json; charset=utf-8" });
             break;
+        case "callout":
+            // The box was resolved in the caller; on camera this is a hold while
+            // the (render-time) ring has the viewer's eye.
+            await page.waitForTimeout(step.ms / m.speed);
+            break;
         case "scene":
             // A marker only. Its timestamp is the point of the step.
             break;
@@ -742,6 +773,8 @@ export function describe(step) {
             return `evaluate (${step.script.length} chars)`;
         case "stub":
             return `stub ${step.method ? step.method + " " : ""}${step.url}`;
+        case "callout":
+            return `callout ${step.selector ?? pointName(step.at)}${step.label ? ` “${step.label}”` : ""}`;
         case "scene":
             return `scene: ${step.label}`;
     }