retake-demos 0.2.2 → 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({}),
@@ -248,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` });
@@ -305,6 +383,13 @@ export function loadManifest(file) {
 /** 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;
@@ -334,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.",

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}"`);