retake-demos 0.2.1 → 0.3.0

package/dist/cli.js

@@ -29,6 +29,7 @@ import { acquireLock, captureHash, record, releaseLock } from "./record.js";
 import { check, render } from "./render.js";
 import { presetNames } from "./presets.js";
 import { PKG_ROOT, VERSION, entry } from "./paths.js";
+import { SECRET_NAME, writeEnvFile } from "./env.js";
 // The manifest may reference ${VARS}; load .env before any command reads one.
 // (`describe` and the UI used to do this individually, so a plain `run` from
 // the terminal silently saw empty values — which is how a whole take can fail
@@ -316,6 +317,108 @@ program
     say(`Keep ${o.ui} open while it works — the plan, the run and the video appear there.`);
     say("Retake will not start your app from outside its own window unless you add RETAKE_ALLOW_START=1 above.");
 });
+/** Read one line from stdin. On a terminal, `hide` switches to raw mode so the
+    characters are not echoed; on a pipe, lines are simply consumed in order. */
+let stdinBuf = "";
+function promptLine(label, hide) {
+    process.stdout.write(label);
+    const tty = !!process.stdin.isTTY;
+    const raw = hide && tty;
+    if (raw)
+        process.stdin.setRawMode(true);
+    process.stdin.resume();
+    return new Promise((resolve) => {
+        const finish = (line) => {
+            process.stdin.off("data", onData);
+            if (raw)
+                process.stdin.setRawMode(false);
+            process.stdin.pause();
+            if (raw)
+                process.stdout.write("\n");
+            resolve(line.trim());
+        };
+        const take = () => {
+            const i = stdinBuf.search(/\r|\n/);
+            if (i < 0)
+                return false;
+            const line = stdinBuf.slice(0, i);
+            stdinBuf = stdinBuf.slice(i + 1).replace(/^\n/, "");
+            finish(line);
+            return true;
+        };
+        const onData = (d) => {
+            const sIn = d.toString();
+            if (raw) {
+                for (const ch of sIn) {
+                    if (ch === "\u0003") {
+                        process.stdout.write("\n");
+                        process.exit(130);
+                    }
+                    if (ch === "\u007f" || ch === "\b") {
+                        stdinBuf = stdinBuf.slice(0, -1);
+                        continue;
+                    }
+                    stdinBuf += ch;
+                }
+            }
+            else
+                stdinBuf += sIn;
+            take();
+        };
+        if (take())
+            return;
+        process.stdin.on("data", onData);
+    });
+}
+program
+    .command("secret")
+    .description("put a demo account into this workspace's .env without opening the file — typed here, hidden, kept on this machine only")
+    .argument("<names...>", "variable names, e.g. APP_USER APP_PASSWORD APP_TOTP_SECRET")
+    .action(async (names) => {
+    const bad = names.filter((n) => !SECRET_NAME.test(n));
+    if (bad.length)
+        throw new Error(`names look like APP_PASSWORD — not: ${bad.join(", ")}`);
+    say(`Stays on this computer: written to ${path.join(process.cwd(), ".env")} (readable by you only), never sent anywhere, never shown to an agent. Use a demo account.`);
+    const values = {};
+    for (const n of names) {
+        const v = await promptLine(`${n}${/PASS|SECRET|TOKEN|KEY|PIN|OTP/.test(n) ? " (hidden)" : ""}: `, /PASS|SECRET|TOKEN|KEY|PIN|OTP/.test(n));
+        if (v)
+            values[n] = v;
+    }
+    const set = writeEnvFile(process.cwd(), values);
+    if (!set.length) {
+        say("nothing saved");
+        return;
+    }
+    say(`✓ ${set.join(", ")} saved to ${path.join(process.cwd(), ".env")} (mode 600). A manifest references them as \${NAME} with secret: true — the values never go on camera.`);
+});
+program
+    .command("signin")
+    .description("sign in by hand once — 2FA, SSO, captcha, anything — and keep the session for every later take")
+    .argument("<manifest>", "the demo whose auth.storageState should be saved")
+    .action(async (file) => {
+    const { manifest, dir } = loadManifest(file);
+    if (!manifest.auth?.storageState)
+        throw new Error(`${file} has no auth.storageState — add:\n  auth:\n    storageState: .auth/${manifest.name}.json\n    maxAgeHours: 24`);
+    const { resolve, expandEnv } = await import("./manifest.js");
+    const { chromium } = await import("playwright");
+    const q = resolve(manifest);
+    const statePath = path.resolve(dir, expandEnv(manifest.auth.storageState));
+    const browser = await chromium.launch({ headless: false });
+    const context = await browser.newContext({ viewport: q.viewport });
+    const page = await context.newPage();
+    await page.goto(manifest.url, { waitUntil: "domcontentloaded" }).catch(() => { });
+    say(`A browser is open at ${manifest.url}.`);
+    say(`Sign in there — codes, SSO, captcha, whatever it asks. When you can see the signed-in app, come back here and press Enter.`);
+    say(`(Nothing is recorded. Only the session is kept, in ${path.relative(process.cwd(), statePath)}, good for ${manifest.auth.maxAgeHours}h.)`);
+    await new Promise((ok) => { process.stdin.resume(); process.stdin.once("data", () => ok()); });
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    await context.storageState({ path: statePath });
+    fs.chmodSync(statePath, 0o600);
+    await browser.close();
+    say(`✓ session saved → ${path.relative(process.cwd(), statePath)}. Takes of ${manifest.name} now start signed in; run this again when it goes stale.`);
+    process.exit(0);
+});
 program
     .command("dry")
     .description("run the manifest with no camera and report what would fail")
@@ -384,12 +487,15 @@ program
     .description("list quality presets")
     .action(async () => {
     const { PRESETS } = await import("./presets.js");
-    say(`${"preset".padEnd(16)} ${"video".padEnd(11)} ${"page".padEnd(11)} fps  layout`);
+    const { bandHeightFor } = await import("./captions.js");
+    say(`${"preset".padEnd(16)} ${"video".padEnd(12)} ${"page".padEnd(11)} fps  layout`);
     for (const p of Object.values(PRESETS)) {
-        const video = p.layout === "card" ? `${p.width}×${p.height}` : `${p.width}×${p.height + (p.layout === "band" ? p.bandHeight : 0)}`;
-        say(`${p.name.padEnd(16)} ${video.padEnd(11)} ${String(p.width + "×" + p.height).padEnd(11)} ${String(p.fps).padEnd(4)} ${p.layout.padEnd(5)} — ${p.description}`);
+        const q = { captions: { fontSize: p.captionFontSize }, layout: p.layout, bandHeight: p.bandHeight, bandFit: p.bandFit, height: p.height };
+        const one = bandHeightFor(q, p.width, ["one line"]), two = bandHeightFor(q, p.width, ["a caption long enough to wrap ".repeat(6)]);
+        const video = p.layout === "card" ? `${p.width}×${p.height}` : p.layout !== "band" ? `${p.width}×${p.height}` : one === two ? `${p.width}×${p.height + one}` : `${p.width}×${p.height + one}–${p.height + two}`;
+        say(`${p.name.padEnd(16)} ${video.padEnd(12)} ${String(p.width + "×" + p.height).padEnd(11)} ${String(p.fps).padEnd(4)} ${p.layout.padEnd(5)} — ${p.description}`);
     }
-    say(`\nvideo = page + caption band. A manifest's \`viewport\` replaces the page size (the video follows it).`);
+    say(`\nvideo = page + caption band. On landscape presets the band fits the captions (one line, or two); square and vertical keep a fixed band so the canvas stays exact. A manifest's \`viewport\` replaces the page size (the video follows it). \`captions: false\` → no band.`);
 });
 program
     .command("validate")
@@ -400,10 +506,12 @@ program
     const q = resolve(manifest);
     // The video is the page area plus the caption band, so say the real number
     // here rather than letting it surprise someone after a two-minute take.
+    const { bandHeightFor } = await import("./captions.js");
     const outW = q.layout === "card" ? q.width : q.viewport.width;
-    const outH = (q.layout === "card" ? q.height : q.viewport.height) + (q.layout === "band" ? q.bandHeight : 0);
+    const band = bandHeightFor(q, outW, manifest.steps.flatMap((s) => (s.action === "scene" && s.caption ? [s.caption] : [])), q.viewport.height);
+    const outH = (q.layout === "card" ? q.height : q.viewport.height) + (q.layout === "band" ? band : 0);
     say(`ok: ${manifest.name} · ${manifest.steps.length} steps · ${manifest.steps.filter((s) => s.action === "scene").length} scenes`);
-    say(`   ${q.name} · video ${outW}×${outH}${q.layout === "band" ? ` (page ${q.viewport.width}×${q.viewport.height} + ${q.bandHeight}px caption band)` : ""} @ ${q.fps}fps${q.gif ? ` · gif ${q.gif.width}px` : ""}`);
+    say(`   ${q.name} · video ${outW}×${outH}${q.layout === "band" ? (band ? ` (page ${q.viewport.width}×${q.viewport.height} + ${band}px caption band${q.bandFit === "text" ? ", sized to the captions" : ""})` : " (captions off, no band)") : ""} @ ${q.fps}fps${q.gif ? ` · gif ${q.gif.width}px` : ""}`);
     for (const w of warnings(manifest))
         say(`⚠ ${w}`);
 });

package/dist/describe.js

@@ -25,16 +25,34 @@ import YAML from "yaml";
 import { Manifest } from "./manifest.js";
 import { digest } from "./digest.js";
 export function loadDotenv(root, files = [".env"]) {
+    // One parser for every reader of .env (see env.ts), so a password written
+    // by the window or `retake secret` is typed back exactly as entered.
     for (const name of files) {
-        const f = path.join(root, name);
-        if (!fs.existsSync(f))
+        for (const [k, v] of Object.entries(parseEnvText(root, name)))
+            if (process.env[k] === undefined)
+                process.env[k] = v;
+    }
+}
+function parseEnvText(root, name) {
+    const f = path.join(root, name);
+    if (!fs.existsSync(f))
+        return {};
+    const out = {};
+    for (const raw of fs.readFileSync(f, "utf8").split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(raw);
+        if (!m)
             continue;
-        for (const line of fs.readFileSync(f, "utf8").split("\n")) {
-            const m = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
-            if (m && process.env[m[1]] === undefined)
-                process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+        const v = m[2].trim();
+        if (v.startsWith('"') && v.endsWith('"')) {
+            try {
+                out[m[1]] = JSON.parse(v);
+                continue;
+            }
+            catch { /* literal */ }
         }
+        out[m[1]] = v.replace(/^(["'])(.*)\1$/, "$2");
     }
+    return out;
 }
 function cliPath(bin) {
     const home = os.homedir();
@@ -293,9 +311,10 @@ export async function proposeEdits(input) {
 // --- drafting ---------------------------------------------------------------
 const SCHEMA_DOC = `
 Manifest YAML fields:
-  name (kebab-case), title, url, preset: post-landscape, waitForSelector (selector present when page is ready),
-  camera: auto, setup: [steps run before recording], steps: [...], outputs: {mp4: true, gif: true, thumbnail: {scene: <label>}}
+  name (kebab-case), title, url, mode: demo, preset: post-landscape, waitForSelector (selector present when page is ready),
+  camera: static, setup: [steps run before recording], steps: [...], outputs: {mp4: true, gif: true, thumbnail: {scene: <label>}}
   Do NOT set viewport, cursor, chrome, background, fps, crf or captions — the preset handles quality.
+  Always set mode: demo — this is a demo, so nothing goes in the frame but the product. Never emit intro or outro cards, music, callouts or voiceover: those belong to mode: launch, which only a person can ask for.
 Steps (each may have pauseAfter ms, waitFor selector, timeout ms):
   {action: scene, label, caption, camera?: static | {focus: selector, zoom: 1.25}}   a named beat; caption is burned in until the next scene (under 60 chars). Set camera: static on every scene unless the thing being shown is genuinely too small to read at full frame — a calm, still demo reads as more real than a zooming one. If the person asked for zooms (or stillness), that wins.
   {action: wait, ms}
@@ -307,7 +326,7 @@ Steps (each may have pauseAfter ms, waitFor selector, timeout ms):
   {action: keyboard, key}
   {action: waitFor, selector, timeout: 30000}      wait for something to appear (use after actions that trigger async work)
   {action: evaluate, script}
-Rules: never invent field names or add "?" to keys; 15–35 seconds total; 3–6 scenes; open with a scene; every click uses a selector from the scouted list verbatim (selectors ending in \">> nth=N\" are already disambiguated — keep them exactly); after any action that loads or computes something, waitFor an element that only appears as a result (never one that is already on the page) — if you cannot know it from the scout, use {action: wait, ms: 3000} instead; end with a wait of ~2000ms on the payoff; do not use zoom steps — scenes carry the camera.
+Rules: never invent field names or add "?" to keys; write mode: demo; no cards, music, callouts or voiceover; 15–35 seconds total; 3–6 scenes; open with a scene; every click uses a selector from the scouted list verbatim (selectors ending in \">> nth=N\" are already disambiguated — keep them exactly); after any action that loads or computes something, waitFor an element that only appears as a result (never one that is already on the page) — if you cannot know it from the scout, use {action: wait, ms: 3000} instead; end with a wait of ~2000ms on the payoff; do not use zoom steps — scenes carry the camera; write a caption ONLY where it says something the screen cannot (never narrate a visible click), and hold the payoff in ONE frame rather than moving between tabs or views to show its parts separately.
 `;
 /** The person's standing taste — demos/style.md, written once, read by every
     draft. "No zooms, cursor visible, captions plain" should not need repeating. */

package/dist/dryrun.js

@@ -160,6 +160,9 @@ export async function dryRun(m, manifestDir, log, opts = {}) {
                     case "wait":
                         await page.waitForTimeout(isSetup ? step.ms : Math.min(step.ms, 400));
                         break;
+                    case "callout":
+                        await point(step.selector ?? step.at);
+                        break;
                     default: break; // scene, screenshot, zoom, download: nothing to verify
                 }
             if (step.pauseAfter)

package/dist/env.js

@@ -0,0 +1,76 @@
+/**
+ * The workspace `.env` — where an app's demo-account credentials live.
+ *
+ * Three things write it: the person (by hand, or `retake secret NAME`), the
+ * window (when an agent asks for a secret by name), and Settings. None of
+ * them ever hands a value to a model: the agent learns that `APP_PASSWORD`
+ * is *set*, and references it as `${APP_PASSWORD}` with `secret: true`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
+/** Parse KEY=value lines (quotes stripped, comments and blanks ignored). */
+export function readEnvFile(root) {
+    const file = path.join(root, ".env");
+    if (!fs.existsSync(file))
+        return {};
+    const out = {};
+    for (const raw of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+        const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(raw);
+        if (!m)
+            continue;
+        const v = m[2].trim();
+        // Double-quoted values are JSON strings (that is how writeEnvFile writes
+        // anything awkward); single-quoted are literal; bare is bare.
+        if (v.startsWith('"') && v.endsWith('"')) {
+            try {
+                out[m[1]] = JSON.parse(v);
+                continue;
+            }
+            catch { /* fall through */ }
+        }
+        out[m[1]] = v.replace(/^(["'])(.*)\1$/, "$2");
+    }
+    return out;
+}
+/** Set (or, with "", remove) keys in .env, leaving every other line alone.
+    Returns the keys actually written. Also updates process.env so the
+    calling process sees the new values without a restart. */
+export function writeEnvFile(root, set) {
+    const file = path.join(root, ".env");
+    const lines = fs.existsSync(file) ? fs.readFileSync(file, "utf8").split("\n") : [];
+    const written = [];
+    for (const [k, v] of Object.entries(set)) {
+        if (v === undefined)
+            continue;
+        const i = lines.findIndex((l) => l.startsWith(k + "="));
+        // Quote when the value has anything a shell-ish parser would trip on.
+        const line = `${k}=${/[\s#"']/.test(v) ? JSON.stringify(v) : v}`;
+        if (v === "") {
+            if (i >= 0)
+                lines.splice(i, 1);
+            delete process.env[k];
+        }
+        else {
+            if (i >= 0)
+                lines[i] = line;
+            else
+                lines.push(line);
+            process.env[k] = v;
+        }
+        written.push(k);
+    }
+    fs.writeFileSync(file, lines.filter((l, i, a) => l !== "" || i < a.length - 1).join("\n").replace(/\n*$/, "\n"), { mode: 0o600 });
+    // `mode` above only applies to a new file; an existing .env keeps whatever
+    // it had. Credentials went in, so: owner-only, every time.
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch { /* windows */ }
+    return written;
+}
+/** Which of these names are not set (missing or blank) in .env + the environment. */
+export function missingSecrets(root, names) {
+    const file = readEnvFile(root);
+    return names.filter((n) => !(process.env[n]?.trim() || file[n]?.trim()));
+}

package/dist/manifest.js

@@ -8,6 +8,7 @@
  *   - `outputs`  which artifacts to produce and how
  */
 import fs from "node:fs";
+import { createHmac } from "node:crypto";
 import path from "node:path";
 import YAML from "yaml";
 import { z } from "zod";
@@ -110,6 +111,16 @@ export const Step = z.discriminatedUnion("action", [
         json: z.unknown().optional(),
         from: z.string().optional(),
     }),
+    /** Point at something while the take holds: an animated ring and an optional
+        label, drawn at render time from the box recorded here. Sparingly — one
+        per scene at most; the captions carry the story. */
+    Base.extend({
+        action: z.literal("callout"),
+        selector: Selector.optional(),
+        at: Point.optional(),
+        label: z.string().max(60).optional(),
+        ms: z.number().positive().max(8000).default(2200),
+    }),
     /** A named beat. Timestamps go into the proof log; `caption` gets burned into
         the video from this moment until the next scene (or `holdMs`). */
     Base.extend({
@@ -124,7 +135,7 @@ export const Step = z.discriminatedUnion("action", [
             .optional(),
     }),
 ]).superRefine((st, ctx) => {
-    if ((st.action === "click" || st.action === "hover") && !st.selector && !st.at) {
+    if ((st.action === "click" || st.action === "hover" || st.action === "callout") && !st.selector && !st.at) {
         ctx.addIssue({ code: "custom", message: `${st.action} needs either a selector or an \`at\` point` });
     }
 });
@@ -177,7 +188,60 @@ const ManifestShape = z.object({
     /** band (default): the site fills the frame, caption strip below · card: the recording framed on a soft canvas · overlay-*: caption over the video · none */
     layout: z.enum(["band", "card", "overlay-bottom", "overlay-top", "none"]).optional(),
     /** auto: each scene zooms toward the last element the demo touched · static: no camera moves. */
-    camera: z.union([z.literal("auto"), z.literal("static"), z.object({ zoom: z.number().min(1).max(3) })]).default("auto"),
+    /** Compress at render what nobody watches. A waitFor/navigate that made
+        the viewer sit through N seconds is shown as ~keepSeconds (real start,
+        then a fast-forward); a long typing run keeps its start and its finish
+        at real speed and accelerates the middle (every keystroke is a
+        round-trip, so a real sentence costs ~5s of video). The author's own
+        `wait` steps are pacing and are never touched. Off by default. */
+    compressIdle: z.union([z.boolean(), z.object({ keepSeconds: z.number().min(0.8).max(5).default(1.5) })]).default(false),
+    /** What this take is FOR, and it changes what is allowed to be in it.
+        `demo` (the default) proves an interaction: direct, legible, minimally
+        framed — a title card or music in a demo is noise. `launch` presents
+        the product, so cards, music, emphasis and a branded ending are
+        legitimate, and each one still has to earn the second it costs.
+        Retake never upgrades a demo to a launch on its own. */
+    mode: z.enum(["demo", "launch"]).default("demo"),
+    /** How typed text lands. `natural` is the per-step default (~80ms a key);
+        `brisk` is the launch rhythm — fast keys (~22ms), the pauses carrying
+        the meaning instead. A step's own `delay` always wins. */
+    typing: z.enum(["natural", "brisk"]).default("natural"),
+    /** The captions, read aloud (edge-tts). Each scene's caption is synthesized
+        and placed at the scene's start; music ducks under it. The captions are
+        the script — there is nothing separate to write. */
+    voiceover: z
+        .union([
+        z.boolean(),
+        z.object({
+            voice: z.string().default("en-US-JennyNeural"),
+            gainDb: z.number().min(-20).max(10).default(0),
+            /** One continuous script, synthesized as a single performance and
+                laid under the whole video — the only shape that keeps prosody.
+                Without it, narration is per-scene fragments: prosody resets at
+                every line and the read/wait rhythm follows scene boundaries
+                instead of speech. Fragments are refused unless `fragments: true`
+                says you know. */
+            script: z.string().optional(),
+            fragments: z.boolean().default(false),
+            /** A person has heard this voice and this script and approved them.
+                Synthesis succeeding is not approval. */
+            approved: z.boolean().default(false),
+        }),
+    ])
+        .default(false),
+    /** A music bed under the whole video, mixed at render time: looped or
+        trimmed to fit, faded out over the last moments. The person supplies the
+        file (CC0/licensed — it ships inside their video); Retake bundles none. */
+    music: z.union([z.string(), z.object({ file: z.string(), gainDb: z.number().min(-40).max(6).default(-14), fadeOutMs: z.number().positive().max(8000).default(1800) })]).optional(),
+    /** Title cards, rendered at render time (change them, re-render in seconds).
+        The intro's settled frame is also written as cover.png — the poster. */
+    intro: z.object({ title: z.string().max(60), subtitle: z.string().max(90).optional(), ms: z.number().positive().max(6000).default(2400) }).optional(),
+    outro: z.object({ title: z.string().max(60), subtitle: z.string().max(90).optional(), ms: z.number().positive().max(6000).default(2000) }).optional(),
+    /** Still by default. A zoom is something a person asks for after seeing a
+        take, never something that happens to them: a calm demo reads as real
+        and can never crop the wrong thing. `auto` eases toward the last thing
+        touched; a scene can override either way. */
+    camera: z.union([z.literal("auto"), z.literal("static"), z.object({ zoom: z.number().min(1).max(3) })]).default("static"),
     /** Seconds cut from the head/tail of the finished video. Render-only: change
         it and re-render, no re-recording. */
     trim: z.object({ head: z.number().nonnegative().default(0), tail: z.number().nonnegative().default(0) }).prefault({}),
@@ -203,10 +267,9 @@ const ManifestShape = z.object({
     waitForSelector: Selector.optional(),
     speed: z.number().positive().default(1),
     /** Cursor overlay (testreel). false → none; {style: touch} → tap dot. Size is preset-scaled unless set. */
-    /** cursor.idleHide: fade the cursor out when idle (testreel default). Each
-        idle gap adds a nested if() to the ffmpeg alpha expression, and ffmpeg's
-        parser has a depth limit — long demos blow past it. Retake turns it off
-        automatically above 60 steps; set it explicitly either way. */
+    /** cursor.idleHide: fade the cursor out when idle (testreel default). Long
+        demos used to lose it (nested-if depth in ffmpeg); the flat cursor
+        expressions lifted that, so it is simply on unless you say otherwise. */
     cursor: z.union([z.boolean(), z.object({ style: z.enum(["default", "pointer", "text", "touch"]).optional(), size: z.number().optional(), idleHideMs: z.number().optional(), idleHide: z.boolean().optional() })]).default(true),
     seed: z.array(Seed).default([]),
     /** What a failed step does to the take. "stop" (default): the camera stops
@@ -249,6 +312,20 @@ const ManifestShape = z.object({
         .prefault({}),
 });
 export const Manifest = ManifestShape.superRefine((m, ctx) => {
+    // A synthetic voice is a claim on the person's taste. Retake will not put
+    // one in a deliverable until they have heard it and said yes — and will
+    // not read the captions as fragments at all, because that is the defect,
+    // not the voice: prosody resets every line and the rhythm follows scene
+    // boundaries instead of speech.
+    if (m.voiceover) {
+        const vo = m.voiceover === true ? { approved: false, script: undefined, fragments: false } : m.voiceover;
+        if (!vo.approved) {
+            ctx.addIssue({ code: "custom", path: ["voiceover"], message: "voiceover is not approved. Synthesize it, LISTEN to it with the person, and only then set `approved: true`. Successful synthesis is not approval; a silent cut beats an unapproved synthetic voice." });
+        }
+        if (!vo.script && !vo.fragments) {
+            ctx.addIssue({ code: "custom", path: ["voiceover"], message: "voiceover needs `script:` — one continuous script, synthesized as a single performance. Reading the captions line by line resets prosody at every scene and paces the speech off scene boundaries. Set `fragments: true` only if you have heard the fragmented read and want it." });
+        }
+    }
     [...m.steps, ...m.setup].forEach((st, i) => {
         if ((st.action === "click" || st.action === "hover") && !st.selector && !st.at) {
             ctx.addIssue({ code: "custom", path: ["steps", i], message: `${st.action} needs either a selector or an \`at\` point` });
@@ -294,11 +371,25 @@ export function loadManifest(file) {
         }).join("\n");
         throw new Error(`Invalid manifest ${file}:\n${issues}`);
     }
-    return { manifest: parsed.data, file: abs, dir: path.dirname(abs) };
+    const dir = path.dirname(abs);
+    // A fixture page can live next to its manifest: `url: file://./page.html`
+    // resolves against the manifest's folder, so a cloned repo's demos work.
+    const m = parsed.data;
+    const rel = /^file:\/\/(\.{1,2}\/.*)$/.exec(m.url);
+    if (rel)
+        m.url = "file://" + path.resolve(dir, rel[1]);
+    return { manifest: m, file: abs, dir };
 }
 /** Things worth saying out loud before a run. Not errors — the run proceeds. */
 export function warnings(m) {
     const w = [];
+    // A demo proves an interaction; a launch presents the product. Launch
+    // furniture in a demo is noise the viewer has to look past.
+    if (m.mode === "demo") {
+        const launchy = [m.intro && "intro card", m.outro && "outro card", m.music && "music", m.steps.some((s) => s.action === "callout") && "callouts"].filter(Boolean);
+        if (launchy.length)
+            w.push(`this is \`mode: demo\` but carries ${launchy.join(", ")} — a demo proves the interaction and wants nothing else in the frame. Set \`mode: launch\` if it is a launch video, or drop them.`);
+    }
     // Secrets typed during recorded steps end up in the video. In `setup` they do
     // not: setup runs before the camera and is trimmed off the front.
     const onCamera = m.steps.filter((s) => s.secret).length;
@@ -312,8 +403,8 @@ export function warnings(m) {
     if (m.auth && !m.auth.setup.length && !m.setup.length)
         w.push("`auth.storageState` is set but there are no sign-in steps under `auth.setup` — there is nothing to save a session from.");
     const moves = m.steps.filter((st) => ["click", "type", "fill", "hover", "scroll", "upload"].includes(st.action)).length;
-    if (m.cursor !== false && moves > 45)
-        w.push(`~${moves} cursor moves — the cursor overlay (testreel/ffmpeg) cannot exceed ~45 in one take and will be MISSING from the video. Split the demo into shorter ones, or set \`cursor: false\`.`);
+    if (m.cursor !== false && moves > 180)
+        w.push(`~${moves} cursor moves — past ~180 in one take the cursor filter no longer fits in one ffmpeg argument and the overlay will be MISSING. Split the demo into chapters, or set \`cursor: false\`.`);
     m.steps.forEach((st, i) => {
         if (st.action !== "scene")
             return;
@@ -328,13 +419,33 @@ export function warnings(m) {
 }
 /** `${VAR}` substitution against process.env, like testreel. */
 export function expandEnv(s) {
-    return s.replace(/\$\{([A-Z0-9_]+)\}/g, (_, k) => {
+    return s.replace(/\$\{(TOTP:)?([A-Z0-9_]+)\}/g, (_, fn, k) => {
         const v = process.env[k];
-        if (v === undefined)
-            throw new Error(`manifest references \${${k}} but it is not set`);
-        return v;
+        // `APP_USER=` with nothing after it is the template, not a value — a blank
+        // login that "succeeds" is worse than a loud stop.
+        if (v === undefined || v.trim() === "")
+            throw new Error(`manifest references \${${k}} but it is not set — add it to .env (a demo account, never a real one)`);
+        // ${TOTP:APP_TOTP_SECRET}: the six-digit code for right now, from an
+        // authenticator enrolment secret. Computed at fill time, so it is valid.
+        return fn ? totp(v) : v;
     });
 }
+/** RFC 6238 TOTP (SHA-1, 6 digits, 30s) from a base32 secret — what every
+    authenticator app enrols with. */
+export function totp(base32Secret, nowMs = Date.now()) {
+    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+    const clean = base32Secret.toUpperCase().replace(/[^A-Z2-7]/g, "");
+    let bits = "";
+    for (const c of clean)
+        bits += alphabet.indexOf(c).toString(2).padStart(5, "0");
+    const key = Buffer.from((bits.match(/.{8}/g) ?? []).map((b) => parseInt(b, 2)));
+    const counter = Buffer.alloc(8);
+    counter.writeBigUInt64BE(BigInt(Math.floor(nowMs / 30000)));
+    const h = createHmac("sha1", key).update(counter).digest();
+    const off = h[h.length - 1] & 0xf;
+    const code = ((h[off] & 0x7f) << 24 | h[off + 1] << 16 | h[off + 2] << 8 | h[off + 3]) % 1_000_000;
+    return String(code).padStart(6, "0");
+}
 export function resolve(m) {
     const p = PRESETS[m.preset] ?? PRESETS[DEFAULT_PRESET];
     const viewport = { width: m.viewport?.width ?? p.width, height: m.viewport?.height ?? p.height };

package/dist/operator/run.js

@@ -44,6 +44,10 @@ export function brief(input) {
         "6. When it is good, run with preview=false once for the real quality, then done with one sentence.",
         "",
         "Rules:",
+        "- Every manifest carries `mode:`. `demo` is the default and covers almost everything — it proves how the thing works and keeps everything but the product out of the frame. `mode: launch` is only for a video that presents the product in public (a launch, a post, an ad); it is the one mode where title cards, music, a callout and a branded ending belong, and it must end with THEIR product, never Retake. Decide from the audience, not the subject: a client walkthrough is a demo. Never upgrade a demo to a launch on your own.",
+        "- A caption earns its place only by saying what the screen cannot. Do not narrate a visible click. Hold the payoff in ONE frame instead of touring its parts.",
+        "- `check: pass` proves the file is sound, not that the demo is good. Use `look` on the payoff and judge it as a viewer before `done`.",
+        "- Never add voiceover. It needs a continuous script and a person who has heard it.",
         "- Never type real passwords into a manifest; use ${ENV_VAR} and secret: true, and tell the person which variable to set.",
         "- Never invent selectors; use what scout/read_project returned.",
         "- Never accept a static manifest for an interactive request. It must perform the requested actions after setup, not merely describe them with scenes and waits.",