demobites 1.4.0 → 1.7.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Ask your coding agent to record your product. Edit the result. Download the MP4.**
 
-Your agent drives a real browser on your machine and records the flow you describe. Connect a free DemoBites account to turn the take into an editable video, with text-to-speech, zooms, captions, and MP4 export included.
+Your agent drives a real browser on your machine, records the flow you describe, and delivers the take into your free DemoBites account as an editable video, with text-to-speech, zooms, captions, and MP4 export included.
 
 **Sign in to your app locally. You do not hand DemoBites your app password or upload your recording browser profile.**
 
@@ -28,7 +28,7 @@ Before installing:
 
 - **Node.js 18 or newer** and npm.
 - **Google Chrome**, recommended. The recorder also supports Playwright's Chromium.
-- A **free DemoBites account** for the Studio workflow below.
+- A **free DemoBites account**. The recorder works only when this project is connected to it.
 
 Run these commands from your project directory:
 
@@ -61,7 +61,7 @@ For Cursor or Codex, make the [recorder instructions](skill/SKILL.md) available
 1. **Describe the flow.** Give your agent the app URL and what you want to demonstrate.
 2. **Approve the storyboard.** Review the steps and estimated length before filming. If your app needs a login, sign in yourself in the recorder's local browser window.
 3. **Let it record.** The agent checks the flow and films it. Recording normally runs in the background.
-4. **Review the raw take.** Open the review link printed in the terminal. Check the footage, then approve it to create a Bite, an editable video project.
+4. **Watch it arrive.** The take is delivered by itself and becomes a Bite, an editable video project. The terminal prints a link to your Demos grid in DemoBites, where the take's card shows it coming in. If your account is out of recording minutes, the take is kept and waits on the same grid until minutes are back.
 5. **Tweak and download.** In the Studio, change a sentence, generate its voice, adjust the zooms or timing, and export your MP4.
 
 The storyboard's narration is a starting point. DemoBites rewrites and fits it to the footage; you can edit the final wording in the Studio.
@@ -103,24 +103,18 @@ The recorder uses a separate, persistent Chrome profile at `.recorder/profile/`.
 | --- | --- |
 | Your app's browser session | Stays in the local recording profile; the standard local workflow does not upload that profile to DemoBites. |
 | DemoBites recorder key | Saved in `.recorder/config.json` and used to authenticate recorder requests to DemoBites. This is separate from your app login. |
-| Footage and recording metadata | Uploaded to DemoBites for review and processing, including the storyboard, narration intent, cursor events, and camera targets. |
+| Footage and recording metadata | Uploaded to DemoBites for processing, including the storyboard, narration intent, cursor events, and camera targets. |
 
 Recording happens locally. Studio processing and editing use DemoBites online. Anything visible or typed into the recorded flow can appear in the footage or recording metadata, so use suitable demo data. Your coding agent's own data handling still follows its provider and your settings.
 
 Keep `.recorder/` and take directories out of version control. To disconnect the recorder, run `npx demobite logout`.
 
-## Local output without a DemoBites account
-
-The repository also contains a [standalone recorder skill](recorder/SKILL.md) and local finishing scripts. These produce a local MP4; optional voiceover uses your own ElevenLabs key.
-
-This is an advanced, manual workflow. The default `npx demobite@latest` command installs the Studio-connected skill, not the standalone skill. The standalone finishing reference contains legacy instructions; use the standalone skill as the entry point rather than treating it as a second ending of the installed Studio skill.
-
 ## A few boundaries
 
 - The agentic recorder films **browser workflows**. It does not record native desktop apps or phone screens.
 - The Studio-connected skill is designed for short demos, usually **30–45 seconds**, with a **90-second maximum per Bite**. Split longer stories into separate videos.
 - Some sites block automated browsers. The workflow may need a human sign-in or verification step, and some sites may refuse recording.
-- Filming does not publish anything. You review the take before creating the Bite; public publishing is a separate action.
+- Filming does not publish anything. You approve the storyboard before anything is filmed; the delivered Bite stays in your workspace, and public publishing is a separate action.
 
 ## Optional: Retake and management
 
@@ -134,7 +128,15 @@ npx demobite retake <biteId> --note "Export moved to the header"
 
 **Workspace rules.** A workspace admin can write standing rules for the recorder in plain words in the DemoBites settings tab Agentic Recorder Rules, one per line: what to mask, which pages never to open, which words to use. The agent reads them at the start of every take and applies them under its own filming laws; `npx demobite rules` prints them. Every take records the rules version it was filmed under.
 
-**Batches of briefs.** When a pull request in DemoBites produces approved briefs, your agent claims them, films one take per brief after you approve each storyboard, and delivers each take. A delivered take becomes a Bite in DemoBites by itself; there is no second review click for these takes. Nothing is published or shared.
+**Batches of briefs.** When a pull request in DemoBites produces approved briefs, your agent claims them, films one take per brief after you approve each storyboard, and delivers each take. Like every take, a delivered take becomes a Bite in DemoBites by itself and shows up on your Demos grid. Nothing is published or shared.
+
+**Update Radar.** A workflow on the Update Radar page (a scan of your merged pull requests, sorted into topics, written into briefs) shows a short record code once its briefs are approved. Run the command from the project where the recorder is installed, in your terminal or in your coding agent:
+
+```bash
+npx demobite record <code>
+```
+
+It lists the batch and its briefs in order, saves them under `.recorder/radar/<code>/`, and tells your agent what to do next, in four steps: it walks every brief against your repository and your running app and posts the refined briefs back (the Radar page marks them "Refined on your machine"), asks you every open question once in one message, shows you all the refined storyboards together for one yes, then films them in the background, in parallel (two or three at a time, each in its own browser profile), delivering each take as it lands. A failed take never stops the others. The workflow page shows each demo arriving; publishing stays a separate step there.
 
 The package also includes a DemoBites management MCP for releases and centers:
 
@@ -153,7 +155,6 @@ The default installer also attempts to register that MCP with Claude Code when t
 | `launcher/` | CLI setup, connection commands, and MCP registration. |
 | `skill/` | Studio-connected recorder instructions, login, upload, and Retake. |
 | `scripts/` | Shared browser recording, trimming, and timing calibration. |
-| `recorder/` | Standalone skill and local video finishing tools. |
 
 The same package is published under three names, `demobite`, `agentic-recorder` and `demobites`, always at the same version; `npx agentic-recorder@latest` and `npx demobites@latest` do exactly what `npx demobite@latest` does. Run it again to update the installed skill. For publishing instructions, see [RELEASING.md](RELEASING.md).
 

package/launcher/index.mjs

@@ -5,6 +5,8 @@
 //   npx demobite@latest login      connect this machine to DemoBites
 //   npx demobite@latest mcp        register the DemoBites management MCP
 //   npx demobite@latest logout     disconnect (revokes the key server-side)
+//   npx demobite record <code>     UPDATE RADAR (1.6.0): list a workflow's approved briefs for the agent
+//                                  (1.7.0: the agent then refines, asks once, gets one yes, films in parallel)
 //
 // One front door (founder 2026-08-31): the user never chooses between the
 // recorder skill and the management MCP — bare `npx demobite` sets up both.
@@ -29,8 +31,74 @@ const arg = process.argv[2] ?? "";
 const ok = (m) => console.log(`  ✓ ${m}`);
 const warn = (m) => console.log(`  ! ${m}`);
 
+// The skill's home and the project's key. The key lives in <cwd>/.recorder/config.json
+// (login.mjs writes it there), so everything here is per-project.
+const skillsDir = path.join(os.homedir(), ".claude", "skills");
+const dest = path.join(skillsDir, "agentic-recorder");
+const readCfg = () => {
+  try { return JSON.parse(fs.readFileSync(path.join(process.cwd(), ".recorder", "config.json"), "utf8")); }
+  catch { return null; }
+};
+
 console.log(`\ndemobite v${pkg.version} — the DemoBites agentic recorder\n`);
 
+// ── 0. record <code> (UPDATE RADAR, 1.6.0) ─────────────────────────────────
+// The Update Radar page shows `npx demobite record <code>` next to a workflow
+// whose briefs are approved. The person runs it in the terminal or in the
+// coding agent where the recorder is installed. It runs NO setup: it checks
+// the skill is installed, respects the auth gate (a missing key prints the
+// login line and stops, nothing opens by itself), asks the server for the
+// batch behind the code, writes .recorder/radar/<code>/bundle.json, prints
+// the briefs in order and then the instruction for the agent. The text is
+// addressed to the agent, plain, and never contains the api key.
+if (arg === "record") {
+  const slug = String(process.argv[3] ?? "").trim().toLowerCase();
+  if (!slug || !/^[a-z0-9-]{1,32}$/.test(slug)) {
+    console.log("Usage: npx demobite record <code>\nThe code is the short one on the Update Radar page, like k3fx9q.");
+    process.exit(2);
+  }
+  const briefsScript = path.join(dest, "scripts", "briefs.mjs");
+  if (!fs.existsSync(path.join(dest, "SKILL.md")) || !fs.existsSync(briefsScript)) {
+    console.log("The agentic-recorder skill is not installed on this machine.\nRun `npx demobite` first (it installs the skill and the recorder), then run this command again.");
+    process.exit(1);
+  }
+  // An older installed skill does not know the record code. Refresh the
+  // skill's files from this package (the same copy bare `npx demobite`
+  // does; no npm install, so nothing slow happens here).
+  if (!fs.readFileSync(briefsScript, "utf8").includes("--slug") || !fs.existsSync(path.join(dest, "scripts", "batch.mjs"))) {
+    const copy = (from, to) => fs.copyFileSync(path.join(pkgRoot, from), path.join(dest, to));
+    fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+    copy("skill/SKILL.md", "SKILL.md");
+    for (const f of fs.readdirSync(path.join(pkgRoot, "skill/scripts"))) copy(`skill/scripts/${f}`, `scripts/${f}`);
+    for (const f of fs.readdirSync(path.join(pkgRoot, "scripts"))) copy(`scripts/${f}`, `scripts/${f}`);
+    ok(`Skill files refreshed to v${pkg.version} → ${dest}`);
+  }
+  const cfg = readCfg();
+  if (!cfg?.api_key) {
+    console.log("This project is not connected to DemoBites yet.\nRun `npx demobite login` (it prints a link to approve in your browser), then run this command again.");
+    process.exit(1);
+  }
+  const r = spawnSync("node", [briefsScript, "list", "--slug", slug], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+    env: { ...process.env, DEMOBITE_CLI: "1" },
+  });
+  if (r.status !== 0) process.exit(r.status ?? 1);
+  console.log(`
+Follow the agentic-recorder skill (${path.join(dest, "SKILL.md").replace(os.homedir(), "~")}, section "Record a batch by slug"), in four steps:
+  1. List: the batch above; the bundle is in .recorder/radar/${slug}/ (one draft per brief in briefs/).
+  2. Refactor + questions: walk EVERY brief against the repository and the running app before anything films;
+     post each refined brief back (\`node scripts/briefs.mjs refine ${slug} <briefId>\`); ask every open
+     question in ONE message, then write the storyboards to .recorder/radar/${slug}/storyboards/<briefId>.json.
+  3. One approval: show the refined storyboards together and ask one yes for the batch ("Film these N?").
+  4. Film in the background: \`node scripts/batch.mjs run ${slug}\` films them in parallel, each on its own
+     profile, and delivers each take as it lands; relay its progress lines.
+When the run ends, report per brief and end with the workflow page link printed above; the person watches
+the demos arrive there.
+`);
+  process.exit(0);
+}
+
 // ── 1. Environment checks ──────────────────────────────────────────────────
 const nodeMajor = Number(process.versions.node.split(".")[0]);
 if (nodeMajor >= 18) ok(`Node ${process.versions.node}`);
@@ -52,8 +120,6 @@ if (hasBin("claude")) ok("Claude Code (drives the recorder; MCP registers automa
 else warn("Claude Code not found — using Cursor or Codex? They drive the recorder too; MCP setup prints below");
 
 // ── 2. Install / update the skill ──────────────────────────────────────────
-const skillsDir = path.join(os.homedir(), ".claude", "skills");
-const dest = path.join(skillsDir, "agentic-recorder");
 fs.mkdirSync(dest, { recursive: true });
 fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
 const copy = (from, to) => fs.copyFileSync(path.join(pkgRoot, from), path.join(dest, to));
@@ -101,7 +167,10 @@ if (!haveChrome) {
 
 // ── 3. Subcommands ─────────────────────────────────────────────────────────
 if (arg === "login" || arg === "logout") {
-  const r = spawnSync("node", [path.join(dest, "scripts", "login.mjs"), ...(arg === "logout" ? ["--logout"] : [])], {
+  // `login <base>` forwards the base (dev, a preview) to login.mjs, which
+  // resolves it before config.base and the production default. Logout
+  // forwards nothing extra: the key's own home always wins there.
+  const r = spawnSync("node", [path.join(dest, "scripts", "login.mjs"), ...(arg === "logout" ? ["--logout"] : process.argv.slice(3))], {
     stdio: "inherit",
     cwd: process.cwd(),
   });
@@ -112,10 +181,6 @@ if (arg === "login" || arg === "logout") {
 // The key lives in <cwd>/.recorder/config.json (login.mjs writes it there),
 // so MCP registration is per-project too — `claude mcp add` default (local)
 // scope matches that exactly and keeps the key out of committable files.
-const readCfg = () => {
-  try { return JSON.parse(fs.readFileSync(path.join(process.cwd(), ".recorder", "config.json"), "utf8")); }
-  catch { return null; }
-};
 const registerMcp = (cfg, { quiet = false } = {}) => {
   const url = `${cfg.base ?? "https://app.demobites.com"}/api/mcp`;
   const header = `Authorization: Bearer ${cfg.api_key}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "demobites",
-  "version": "1.4.0",
+  "version": "1.7.0",
   "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
   "bin": {
     "demobites": "launcher/index.mjs"

package/scripts/calibrate.mjs

@@ -271,12 +271,22 @@ if (!anchored) {
   }
 }
 
+// A click pairs only with a change inside its CONSEQUENCE WINDOW. Bite 1115
+// (2026-09-27): a click that toggled one small button changed no whole frame,
+// so it was paired with the dialog that opened 5.4 s later; with two clicks
+// the median was that mis-pair and the take was vetoed although the beacon
+// had measured the clock to ~90 ms. A change later than CONSEQUENCE_S is not
+// this click's consequence: the click is unpaired and left out.
+const CONSEQUENCE_S = 1.5;
+// The median can veto a take only from MIN_LATENCY_SAMPLES pairs; fewer are a
+// warning, and a beacon- or anchor-measured clock is never vetoed by it.
+const MIN_LATENCY_SAMPLES = 3;
 const latencies = [];
 for (const c of clicks) {
   const pred = tb.a * c.wall + tb.b;
-  const after = scenes.filter((s) => s >= pred - 0.15);
+  const after = scenes.filter((s) => s >= pred - 0.15 && s <= pred + CONSEQUENCE_S);
   if (after.length === 0) {
-    console.log(`  ${c.label}: predicted ${pred.toFixed(2)}s, no visible change after it`);
+    console.log(`  ${c.label}: predicted ${pred.toFixed(2)}s, no visible change within ${CONSEQUENCE_S}s (unpaired)`);
     continue;
   }
   const nearest = after.reduce((a, b) => (Math.abs(a - pred) <= Math.abs(b - pred) ? a : b));
@@ -285,7 +295,11 @@ for (const c of clicks) {
 }
 const sorted = [...latencies].sort((a, b) => a - b);
 const median = sorted.length ? sorted[Math.floor(sorted.length / 2)] : 0;
-if (!anchored && (median < -0.15 || median > 0.9)) {
+const clockMeasured = anchored || beaconAnchored;
+if (!clockMeasured && sorted.length < MIN_LATENCY_SAMPLES && (median < -0.15 || median > 0.9)) {
+  console.log(`WARNING: median click latency ${median.toFixed(3)}s from only ${sorted.length} paired click(s) — too few to veto the take; the clock stays an estimate. Judge the take on feel.`);
+}
+if (!clockMeasured && sorted.length >= MIN_LATENCY_SAMPLES && (median < -0.15 || median > 0.9)) {
   console.error(
     `VERIFY FAILED: median click latency ${median.toFixed(3)}s is outside [-0.15, +0.9]. ` +
     "The stamped timebase looks wrong for this take. Do not upload — investigate record_from.",

package/scripts/record.mjs

@@ -65,6 +65,10 @@ for (const [i, s] of STORYBOARD.steps.entries()) {
   if ((s.action === "click" || s.action === "hover") && !s.selector) { console.error(`${at}: ${s.action} needs selector`); process.exit(2); }
   if (s.action === "type" && (!s.selector || typeof s.text !== "string")) { console.error(`${at}: type needs selector and text`); process.exit(2); }
   if (s.action === "expect" && !s.selector) { console.error(`${at}: expect needs selector`); process.exit(2); }
+  // FRAMING (founder ruling 2026-09-27): `frame` is the director's word on the
+  // step's camera — "close" (the auto subject box) or "wide" (the full frame,
+  // the camera at 1.0). Absent = auto. Anything else is a typo, not a wish.
+  if (s.frame !== undefined && s.frame !== "close" && s.frame !== "wide") { console.error(`${at}: frame must be "close" or "wide" (got ${JSON.stringify(s.frame)})`); process.exit(2); }
 }
 
 const DIR = path.resolve(outArg);
@@ -72,7 +76,7 @@ const DIR = path.resolve(outArg);
 // RE-TAKE (founder 2026-09-02): the storyboard IS the bite's DNA. Keep a verbatim
 // copy in the take dir so upload.mjs can stage it as the recording recipe —
 // selectors, urls, typed text, hideCss — the wire manifest alone cannot re-film.
-const ENGINE_VERSION = "1.0.9";
+const ENGINE_VERSION = "1.1.0";
 fs.mkdirSync(DIR, { recursive: true });
 // The copy is the RECIPE, not the transport: cdpWsUrl / storageStatePath are
 // per-take plumbing stamped by the cloud runner (a CDP url carries a session
@@ -125,7 +129,11 @@ const SUPERSAMPLE = 1;
 const VIEW = { width: DESIGN.width * SUPERSAMPLE, height: DESIGN.height * SUPERSAMPLE };
 // Persistent camera-browser profile: the human's signed-in sessions live here.
 // The auth checkpoint (SKILL.md) fills it; record only ever reads it.
-const profileDir = path.resolve(".recorder", "profile");
+// PARALLEL TAKES (1.7.0, founder ruling 2026-09-26): a batch films several
+// takes at once, each in its OWN profile directory seeded from this one, so
+// no two Chromes fight over one profile lock. batch.mjs passes the directory
+// in RECORDER_PROFILE; a single take never sets it and films on the profile.
+const profileDir = path.resolve(process.env.RECORDER_PROFILE || path.join(".recorder", "profile"));
 fs.mkdirSync(profileDir, { recursive: true });
 
 // LAW (the video is the metronome, founder 2026-08-08): shots are as long as
@@ -406,6 +414,46 @@ const pushShot = (box, tStart, tEnd, label, extra) => {
   });
 };
 
+// LAW (the camera obeys the script, founder 2026-09-27, bite 1117): a WIDE
+// shot is the full frame — the camera at 1.0 — and the server honours it as a
+// boundary: the previous close shot ENDS at its start, nothing tight is merged
+// into it or held over it. What Enter revealed, a settle after a navigation,
+// and any step the director framed `wide` are wide shots. Framing is OUR job,
+// decided from the narration we wrote; the customer never thinks about zooms.
+const FULL_FRAME = { x: 0, y: 0, width: VIEW.width, height: VIEW.height };
+const pushWide = (tStart, tEnd, label, extra) =>
+  pushShot(FULL_FRAME, tStart, tEnd, label ?? "wide", { ...(extra ?? {}), wide: true });
+// A wide shot pushed at the END of the step (after the narration hold), so it
+// spans the whole landing — the line "you land on the report" plays over it.
+let wideAfter = null; // { tStart, label, extra }
+const wantsWide = (step) => step.frame === "wide";
+const wantsClose = (step) => step.frame === "close";
+// The page as a signature, so a submit that swaps the page IN PLACE (a search
+// that re-renders a list, a client-side route change) counts as a landing
+// even when the URL held still: url, title, first heading, text mass.
+async function pageSignature() {
+  try {
+    return await page.evaluate(() => {
+      const h = [...document.querySelectorAll("h1, h2")].find((el) => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; });
+      return {
+        url: location.href,
+        title: document.title,
+        heading: h ? (h.textContent || "").trim().slice(0, 120) : "",
+        mass: (document.body?.innerText ?? "").trim().length,
+      };
+    });
+  } catch { return null; }
+}
+/** Did the page change substantially between two signatures? A new URL, a
+ *  new title or heading, or the text mass moving by more than a quarter. */
+const pageChanged = (a, b) => {
+  if (!a || !b) return false;
+  if (a.url !== b.url) return true;
+  if (a.title !== b.title || a.heading !== b.heading) return true;
+  const base = Math.max(200, a.mass);
+  return Math.abs(b.mass - a.mass) / base > 0.25;
+};
+
 // User-approved zoom (storyboard flow 2026-08-20, cloud planner + storyboard
 // page): a step may carry zoom {x,y,w,h} in PERCENT of the frame, adjusted by
 // the customer before filming. It overrides the auto shot box. zoom:null means
@@ -700,8 +748,13 @@ try {
 }
 
 let failure = null;
+// A navigation just happened (goto, a click that changed the URL, Enter that
+// changed the page) and no shot has framed the new page yet: the next bare
+// settle is the landing and is framed wide (founder 2026-09-27).
+let landingPending = false;
 try {
   for (const step of STORYBOARD.steps) {
+    wideAfter = null;
     const rec = {
       n: manifest.steps.length + 1,
       action: step.action,
@@ -791,23 +844,39 @@ try {
         openingBeatPending = true;
       }
       await page.evaluate(([a, b]) => window.__recSetCursor?.(a, b), [cx, cy]);
+      // The new page is a landing: the next bare settle frames it wide. A
+      // goto framed `wide` frames it from the paint itself.
+      landingPending = true;
+      if (wantsWide(step)) wideAfter = { tStart: rec.nav ? rec.nav.to : manifest.record_from, label: step.label ?? "open the page", extra: { n: rec.n } };
     } else if (step.action === "settle") {
       // A settle can still carry the camera: `focus` names what to look at.
+      // A settle framed `wide`, or a bare settle right after a navigation
+      // (the landing), is a full-frame shot for its whole span, narration
+      // hold included — "and you land on the report itself" plays wide.
       const settleMs = ms(step.ms, DEFAULT_SETTLE_MS);
       const shotStart = t();
-      await page.waitForTimeout(settleMs);
-      if (step.focus) {
-        const box = await visibleBox(step.focus, step.minY ?? 0, 4000);
-        pushShot(userShotBox(step, box), shotStart, t(), step.label, { n: rec.n });
-      } else if (step.zoom) {
-        pushShot(userShotBox(step, null), shotStart, t(), step.label, { n: rec.n });
+      const bare = !step.focus && !step.zoom;
+      if (wantsWide(step) || (bare && landingPending && !wantsClose(step))) {
+        wideAfter = { tStart: shotStart, label: step.label ?? "settle, wide", extra: { n: rec.n } };
+        await page.waitForTimeout(settleMs);
+      } else {
+        await page.waitForTimeout(settleMs);
+        if (step.focus) {
+          const box = await visibleBox(step.focus, step.minY ?? 0, 4000);
+          pushShot(userShotBox(step, box), shotStart, t(), step.label, { n: rec.n });
+        } else if (step.zoom) {
+          pushShot(userShotBox(step, null), shotStart, t(), step.label, { n: rec.n });
+        }
       }
+      landingPending = false;
     } else if (step.action === "scroll") {
       // scrollTo distances are ALSO zoomed-space under CSS zoom (measured:
       // scrollTo(0,600) moves 300 design px) — storyboards speak design px.
       const shotStart = t();
       await smoothScroll(step.dy * SUPERSAMPLE, ms(step.ms, 1400), step.within ?? null);
-      if (step.zoom) pushShot(userShotBox(step, null), shotStart, t(), step.label, { n: rec.n });
+      if (wantsWide(step)) wideAfter = { tStart: shotStart, label: step.label ?? "scroll, wide", extra: { n: rec.n } };
+      else if (step.zoom) pushShot(userShotBox(step, null), shotStart, t(), step.label, { n: rec.n });
+      landingPending = false;
     } else if (step.action === "click" || step.action === "hover") {
       const { box, el } = await visibleTarget(step.selector, step.minY ?? 0, step.action === "hover" ? 8000 : 15000);
       if (!box) {
@@ -867,6 +936,10 @@ try {
         },
       };
 
+      // The director's `frame: "wide"`: the whole step is one full-frame shot
+      // from arrival to the end of the beat; no subject box, no reveal shot.
+      const stepWide = wantsWide(step);
+      landingPending = false;
       if (step.action === "hover") {
         await page.waitForTimeout(ms(step.dwell, DEFAULT_HOVER_DWELL));
         // LAW (camera choreography, measured off the reference 2026-08-09):
@@ -876,13 +949,15 @@ try {
         // that, and the same ballistic motion read stiffer for it. The shot
         // begins just before ARRIVAL, so the previous frame holds still
         // while the cursor sweeps across it, then the camera reframes.
-        pushShot(userShotBox(step, step.focus ? await visibleBox(step.focus, 0, 3000) : box), Math.max(shotStart, arrivalT - 0.3), t(), step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
+        if (stepWide) wideAfter = { tStart: Math.max(shotStart, arrivalT - 0.3), label: step.label, extra: { n: rec.n } };
+        else pushShot(userShotBox(step, step.focus ? await visibleBox(step.focus, 0, 3000) : box), Math.max(shotStart, arrivalT - 0.3), t(), step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
       } else {
         await page.waitForTimeout(ms(step.dwell, DEFAULT_CLICK_DWELL));
         await page.evaluate(([a, b]) => window.__recPulse?.(a, b), [x, y]);
         await page.waitForTimeout(220);
         rec.click_at = t();
         const clickEventIndex = mouseEvents.length;
+        const urlBeforeClick = page.url();
         pushMouse("click", x, y, "left");
         await page.mouse.click(x, y);
         if (step.waitLoad) {
@@ -893,7 +968,8 @@ try {
         }
         // Shot one: the control — beginning near ARRIVAL (see the camera
         // choreography law above), never spanning the approach glide.
-        pushShot(userShotBox(step, box), Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
+        if (stepWide) wideAfter = { tStart: Math.max(shotStart, arrivalT - 0.3), label: step.label, extra: { n: rec.n } };
+        else pushShot(userShotBox(step, box), Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label, { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
         // LAW (press physics, founder 2026-08-09): a press has a down and an
         // up — but the up only exists if the clicked surface is still there.
         // A menu item or modal button that DESTROYS itself on click gets a
@@ -948,8 +1024,11 @@ try {
         await page.waitForTimeout(Math.max(0, afterMs - early));
         // Shot two: whatever the click opened. This is the shot that was
         // missing on 2026-08-08, when the camera stayed on the button while
-        // the dialog opened in the middle of the screen.
-        if (step.reveals !== false) {
+        // the dialog opened in the middle of the screen. A step framed wide
+        // already frames its result; a click that changed the URL leaves the
+        // landing to the settle that follows (framed wide there).
+        if (page.url() !== urlBeforeClick) landingPending = true;
+        if (step.reveals !== false && !stepWide) {
           const opened = await revealedBox(step);
           if (opened) {
             rec.revealed = {
@@ -957,6 +1036,7 @@ try {
               w: Math.round(opened.width / SUPERSAMPLE), h: Math.round(opened.height / SUPERSAMPLE),
             };
             pushShot(opened, rec.click_at + 0.35, t(), `${step.label ?? "click"}, result`, { n: rec.n, revealed: true });
+            landingPending = false;
           }
         }
       }
@@ -1006,6 +1086,10 @@ try {
       pushMouse("click", x, y, "left");
       await page.mouse.click(x, y);
       await page.waitForTimeout(380);
+      // The page as it was when the field was taken: a search that filters
+      // as you type has changed the page BEFORE Enter, and the reveal is
+      // still what this beat's typing and Enter produced.
+      const sigBefore = await pageSignature();
       if (step.clear) {
         await page.keyboard.press(process.platform === "darwin" ? "Meta+a" : "Control+a");
         await page.waitForTimeout(180);
@@ -1018,9 +1102,19 @@ try {
         await page.keyboard.type(ch);
         await page.waitForTimeout(34 + Math.random() * 70);
       }
+      const typeWide = wantsWide(step);
+      const glideWin = { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 };
+      landingPending = false;
       if (step.enter || step.submit) {
         // `enter` is the skill's spelling, `submit` the cloud planner's.
         await page.waitForTimeout(300);
+        // LAW (Enter ends the close shot, founder 2026-09-27, bite 1117): the
+        // field shot ends the moment BEFORE Enter — typing end plus the
+        // breath above — never after the navigation waits. What Enter
+        // reveals is framed on its own, below.
+        const enterAt = t();
+        rec.enter_at = enterAt;
+        if (!typeWide) pushShot(userShotBox(step, box), Math.max(shotStart, arrivalT - 0.3), enterAt, step.label ?? "type", { n: rec.n, glide: glideWin });
         const urlBefore = page.url();
         await page.keyboard.press("Enter");
         // A submit usually navigates: re-arm the presenter layer on the new
@@ -1033,9 +1127,38 @@ try {
           await applyHideCss();
           await page.evaluate(([a, b]) => window.__recSetCursor?.(a, b), [x, y]);
         }
+        // LAW (what Enter revealed is a WIDE shot): a new URL or a page that
+        // changed substantially is a landing — full frame from Enter + 0.35 s
+        // to the end of the beat. A step framed wide is already wide. An
+        // overlay that opened without the page changing (Enter opened a
+        // dialog) is a revealed close shot, as after a click. `reveals:
+        // false` keeps the camera where it is.
+        if (!typeWide && step.reveals !== false) {
+          await page.waitForTimeout(250);
+          const sigAfter = await pageSignature();
+          const navigated = page.url() !== urlBefore;
+          if (navigated || pageChanged(sigBefore, sigAfter)) {
+            rec.landed = { url: page.url(), navigated, heading: sigAfter?.heading ?? null };
+            wideAfter = { tStart: enterAt + 0.35, label: `${step.label ?? "type"}, result`, extra: { n: rec.n, revealed: true } };
+            process.stdout.write(`landing: step ${rec.n} Enter ${navigated ? "changed the URL" : "changed the page"} — framed wide\n`);
+          } else {
+            const opened = await revealedBox(step);
+            if (opened) {
+              rec.revealed = {
+                x: Math.round(opened.x / SUPERSAMPLE), y: Math.round(opened.y / SUPERSAMPLE),
+                w: Math.round(opened.width / SUPERSAMPLE), h: Math.round(opened.height / SUPERSAMPLE),
+              };
+              pushShot(opened, enterAt + 0.35, t() + 0.3, `${step.label ?? "type"}, result`, { n: rec.n, revealed: true });
+            }
+          }
+        }
+        if (typeWide) wideAfter = { tStart: Math.max(shotStart, arrivalT - 0.3), label: step.label ?? "type", extra: { n: rec.n } };
+      } else if (typeWide) {
+        wideAfter = { tStart: Math.max(shotStart, arrivalT - 0.3), label: step.label ?? "type", extra: { n: rec.n } };
+      } else {
+        // One shot: the field, from arrival through the typing.
+        pushShot(userShotBox(step, box), Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label ?? "type", { n: rec.n, glide: glideWin });
       }
-      // One shot: the field, from arrival through the typing.
-      pushShot(userShotBox(step, box), Math.max(shotStart, arrivalT - 0.3), t() + 0.3, step.label ?? "type", { n: rec.n, glide: { t_start: Math.round(shotStart * 100) / 100, t_end: Math.round(arrivalT * 100) / 100 } });
       currentCursor = await cursorUnderPoint();
       pushMouse("move", cx, cy);
       await page.waitForTimeout(ms(step.after, DEFAULT_CLICK_AFTER));
@@ -1053,6 +1176,12 @@ try {
       if (elapsed < need) await page.waitForTimeout(Math.round((need - elapsed) * 1000));
     }
     rec.t_end = t();
+    // The wide shot spans the whole beat, narration hold included.
+    if (wideAfter) {
+      pushWide(wideAfter.tStart, rec.t_end, wideAfter.label, wideAfter.extra);
+      rec.wide = true;
+      wideAfter = null;
+    }
     manifest.steps.push(rec);
   }
   // Closing beat so the last action breathes before the cut ends.