demobite 1.0.2 → 1.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "demobite",
-  "version": "1.0.2",
-  "description": "The DemoBites agentic recorder \u2014 you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
+  "version": "1.0.4",
+  "description": "The DemoBites agentic recorder — you prompt, it films a real browser, and DemoBites turns the take into an editable demo bite.",
   "bin": {
     "demobite": "launcher/index.mjs"
   },
@@ -35,4 +35,4 @@
   },
   "license": "MIT",
   "type": "module"
-}
+}

package/scripts/record.mjs

@@ -85,6 +85,19 @@ const DEFAULT_HOVER_DWELL = 3200;
 const DEFAULT_CLICK_DWELL = 700;
 const DEFAULT_CLICK_AFTER = 2000;
 const CLOSING_BEAT_MS = 2200;
+// LAW (hold your line, founder 2026-09-02): a beat is never shorter than its
+// own narration. Same estimate manifest.mjs uses (words / 2.6 s + 0.4 s).
+// Storyboard durations (`dwell`, `after`, settle `ms`, scroll `ms`) are
+// MILLISECONDS; an author who writes 3.4 means seconds. Anything under 60 is
+// read as seconds (a 59 ms dwell is never intended).
+// The video track starts up to ~2.5 s AFTER the wall clock (startup lead,
+// measured per take by calibrate.mjs). trim.mjs cuts by record_from, so the
+// opening beat loses that lead in the published file. The FIRST narrated beat
+// after the stamp carries this slack so its line always has its full beat.
+const STARTUP_LEAD_SLACK_S = 2.5;
+let openingBeatPending = false;
+const ms = (v, fallback) => (v == null ? fallback : v < 60 ? Math.round(v * 1000) : v);
+const estimateSpeech = (text) => String(text).trim().split(/\s+/).filter(Boolean).length / 2.6 + 0.4;
 
 const narrationOf = (s) => {
   if (s.narration == null) return null;
@@ -529,9 +542,34 @@ try {
     };
     process.stdout.write(`step ${rec.n} ${step.action} ${step.label ?? ""}\n`);
     if (step.action === "goto") {
+      const navIssuedAt = t();
       await page.goto(step.url, { waitUntil: "load" });
       await ensureCursor();
       await applyHideCss();
+      if (manifest.record_from !== undefined) {
+        // LAW (page transitions, founder 2026-09-02): a mid-take navigation
+        // must not show its loading blank. Wait for the new page to PAINT,
+        // then stamp the window so manifest.mjs cuts it out with a fade —
+        // the viewer sees page one, a fade, page two. No zoom or narration
+        // may live inside that window (manifest.mjs keeps them out).
+        await page.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => {});
+        const paintDeadline = Date.now() + 10000;
+        while (Date.now() < paintDeadline) {
+          const painted = await page.evaluate(() => {
+            const textMass = (document.body?.innerText ?? "").trim().length;
+            let visible = 0;
+            for (const el of document.querySelectorAll("div, section, main, button")) {
+              const r = el.getBoundingClientRect();
+              if (r.width > 40 && r.height > 20) { visible++; if (visible > 8) break; }
+            }
+            return textMass > 80 && visible > 8;
+          }).catch(() => false);
+          if (painted) break;
+          await page.waitForTimeout(200);
+        }
+        await page.waitForTimeout(350);
+        rec.nav = { from: navIssuedAt, to: t() };
+      }
       if (manifest.record_from === undefined) {
         // LAW (first-frame, founder 2026-08-08, HARDENED 2026-08-13 after a
         // take opened on a white page): the published cut opens on a FULLY
@@ -575,13 +613,14 @@ try {
         }
         await page.waitForTimeout(600);
         manifest.record_from = t();
+        openingBeatPending = true;
       }
       await page.evaluate(([a, b]) => window.__recSetCursor?.(a, b), [cx, cy]);
     } else if (step.action === "settle") {
       // A settle can still carry the camera: `focus` names what to look at.
-      const ms = step.ms ?? DEFAULT_SETTLE_MS;
+      const settleMs = ms(step.ms, DEFAULT_SETTLE_MS);
       const shotStart = t();
-      await page.waitForTimeout(ms);
+      await page.waitForTimeout(settleMs);
       if (step.focus) {
         const box = await visibleBox(step.focus, step.minY ?? 0, 4000);
         pushShot(box, shotStart, t(), step.label, { n: rec.n });
@@ -589,7 +628,7 @@ try {
     } 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.
-      await smoothScroll(step.dy * SUPERSAMPLE, step.ms ?? 1400, step.within ?? null);
+      await smoothScroll(step.dy * SUPERSAMPLE, ms(step.ms, 1400), step.within ?? null);
     } else if (step.action === "click" || step.action === "hover") {
       const { box, el } = await visibleTarget(step.selector, step.minY ?? 0);
       if (!box) throw new Error("no visible target for " + step.selector);
@@ -615,6 +654,7 @@ try {
       currentCursor = "arrow";
       await glide(x, y);
       const arrivalT = t();
+      rec.arrival = arrivalT; // narration anchors here (manifest.mjs) — so does the beat hold
       currentCursor = targetCursor;
       rec.cursor = currentCursor;
       pushMouse("move", x, y);
@@ -636,7 +676,7 @@ try {
       };
 
       if (step.action === "hover") {
-        await page.waitForTimeout(step.dwell ?? DEFAULT_HOVER_DWELL);
+        await page.waitForTimeout(ms(step.dwell, DEFAULT_HOVER_DWELL));
         // LAW (camera choreography, measured off the reference 2026-08-09):
         // the camera must NOT travel in lockstep with the cursor. When it
         // does, the cursor sits pinned near frame center while the page
@@ -646,7 +686,7 @@ try {
         // while the cursor sweeps across it, then the camera reframes.
         pushShot(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(step.dwell ?? DEFAULT_CLICK_DWELL);
+        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();
@@ -670,7 +710,7 @@ try {
         // pointer. The recorder does not guess: it ASKS the page whether the
         // element it just clicked is still connected, visible, and under the
         // point. The verdict rides the click event as press:'full'|'down'.
-        const afterMs = step.after ?? DEFAULT_CLICK_AFTER;
+        const afterMs = ms(step.after, DEFAULT_CLICK_AFTER);
         const early = Math.min(450, afterMs);
         await page.waitForTimeout(Math.min(200, early));
         // TIMING LAW (parity forensics 2026-08-09): this check must not eat
@@ -755,6 +795,7 @@ try {
       currentCursor = "arrow";
       await glide(x, y);
       const arrivalT = t();
+      rec.arrival = arrivalT; // narration anchors here (manifest.mjs) — so does the beat hold
       currentCursor = targetCursor;
       rec.cursor = currentCursor;
       pushMouse("move", x, y);
@@ -766,7 +807,7 @@ try {
           w: Math.round(box.width / SUPERSAMPLE), h: Math.round(box.height / SUPERSAMPLE),
         },
       };
-      await page.waitForTimeout(step.dwell ?? DEFAULT_CLICK_DWELL);
+      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();
@@ -793,7 +834,19 @@ try {
       pushShot(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(step.after ?? DEFAULT_CLICK_AFTER);
+      await page.waitForTimeout(ms(step.after, DEFAULT_CLICK_AFTER));
+    }
+    if (rec.narration && step.action !== "goto" && step.action !== "expect") {
+      // Hold the shot until the line would have finished, plus a breath — the
+      // ingestion refits words to video but cannot fit 5 s of speech in a 2 s
+      // beat (founder 2026-09-02: the last track ran past the end).
+      // Measured from ARRIVAL (where manifest.mjs anchors the line), not from
+      // the cursor's departure — the glide is not speaking time.
+      const narrText = typeof rec.narration === "string" ? rec.narration : rec.narration?.text ?? "";
+      let need = estimateSpeech(narrText) + 0.5;
+      if (openingBeatPending) { need += STARTUP_LEAD_SLACK_S; openingBeatPending = false; }
+      const elapsed = t() - (rec.arrival ?? rec.t_start);
+      if (elapsed < need) await page.waitForTimeout(Math.round((need - elapsed) * 1000));
     }
     rec.t_end = t();
     manifest.steps.push(rec);

package/skill/SKILL.md

@@ -90,7 +90,7 @@ Holding shots to cover estimated lines is what produced a 60 second take with th
 
 **Budgets, hold yourself to them:**
 
-- **30 to 45 seconds total.** Over 45 is a rewrite, not a trim.
+- **30 to 45 seconds total (35 to 45 when the story crosses pages).** Over 45 is a rewrite, not a trim; under 30 with two pages is rushing, see the linger law below.
 - **90 seconds is a HARD CAP, by product concept, and it is a limit, not a
   target.** A Bite over 90 seconds does not exist. Budget the beats BEFORE
   filming: if the human's scenario cannot honestly fit inside 90 seconds, do
@@ -103,6 +103,14 @@ Holding shots to cover estimated lines is what produced a 60 second take with th
 
 **LAW: a line must FIT its beat, and a beat that NAVIGATES away cannot hold two lines** (founder drift analysis, 2026-08-09). Each narration line plays while its own beat is on screen. If a beat is a click that navigates to a new page, everything you want said ABOUT the old page has to fit BEFORE that click — a ~14-word line is ~5s of speech, so one line per pre-navigation beat, not two stacked. Cramming the intro plus a second observation before a fast navigation is what makes the words drift a beat behind the picture (a list-page sentence finishing over the product page). If you need to say two things about a page, either say them AFTER you have landed on it, or give the source beat a longer `dwell` so the line finishes before the click. The ingestion fits words to the video, but it cannot make 8 seconds of speech fit into a 5 second window — that is authoring, and it is yours.
 
+**LAW: every take opens with a framing intro** (founder, 2026-09-02). The first narrated beat frames the story for someone who is NOT inside the product yet: "Let's look at what happens when a visitor searches your Update Center for something you have not published yet." Never open on a UI detail ("Search sits at the top right"). The viewer is not in the realm; bring them in first.
+
+**LAW: narrate the path, do not drive.** Before every navigation, scroll or drill-down, SAY where we are going and why, in the beat before it: "In the analytics for this Update Center, near the bottom, sits search intelligence." A viewer who only sees a cursor dive into a panel learns nothing about how to get there themselves.
+
+**LAW: linger.** A single-page story is 30 to 45 seconds; a story that crosses pages is 35 to 45 seconds, never 23. Every beat holds at least as long as its own line plus a breath (record.mjs now enforces this: a narrated beat waits until words / 2.6 s + 0.8 s have passed), and the last beat holds its whole line so no track ever runs past the end of the video. The ingestion refits words to video; it cannot fit five seconds of speech into a two-second beat.
+
+**LAW: page transitions are cut and faded, never watched.** When the story moves to another page, the viewer sees page one, a short fade, page two — never the loading blank. record.mjs stamps every mid-take `goto` and manifest.mjs cuts that window out with a fade (`cuts` in the wire manifest); the ingestion lays it on the bite as a timeline cut. No zoom and no narration live inside a cut (the studio forbids both), so put the line about the new page on the beat AFTER it has landed, and say goodbye to the old page BEFORE the goto.
+
 Storyboard schema:
 
 ```json
@@ -122,7 +130,7 @@ Storyboard schema:
 }
 ```
 
-Step fields: `action` is one of `goto | settle | scroll | click | hover`. `goto` needs `url`. `settle` takes `ms` and an optional `focus` selector. `scroll` needs `dy` and takes `ms`. `click`/`hover` need `selector` and take `minY` (minimum Y for the visible instance pick), `dwell`, `after`, `waitLoad`. Every step takes `label` and `narration`.
+Step fields: `action` is one of `goto | settle | scroll | click | hover | type | expect`. **Durations (`dwell`, `after`, settle `ms`, scroll `ms`) are milliseconds; a value under 60 is read as seconds** (write `"dwell": 3400` or `"dwell": 3.4`, never `"dwell": 3` meaning 3 ms). `goto` needs `url`. `settle` takes `ms` and an optional `focus` selector. `scroll` needs `dy` and takes `ms`. `click`/`hover` need `selector` and take `minY` (minimum Y for the visible instance pick), `dwell`, `after`, `waitLoad`. Every step takes `label` and `narration`.
 
 Two fields carry the whole advantage of this lane, so fill them in:
 
@@ -246,7 +254,8 @@ What the human approves on that page is the **picture and the coverage**, never
     click?: { x, y, t },                     // frame px + seconds
     narration?: { text, t, estimated_duration }
   }],
-  camera: [{ t_start, t_end, x, y, w, h, label }]   // focus rectangles, frame px
+  camera: [{ t_start, t_end, x, y, w, h, label }],  // focus rectangles, frame px
+  cuts?: [{ t_start, t_end, transition: 'fade'|'abrupt', n }]  // navigation loads, cut out of the bite
 }
 ```
 

package/skill/scripts/manifest.mjs

@@ -9,7 +9,8 @@
 //            on_screen?,                           // what the viewer sees
 //            click?:{x,y,t},                       // frame px + seconds
 //            narration?:{text,t,estimated_duration} }],
-//   camera:[{ t_start, t_end, x, y, w, h, label }] }  // focus rectangles
+//   camera:[{ t_start, t_end, x, y, w, h, label }],  // focus rectangles
+//   cuts?:[{ t_start, t_end, transition:'fade'|'abrupt', n }] }  // navigation loads cut out
 //
 // EVERY time is relative to the uploaded file: record_from is subtracted and
 // the result clamped at 0.
@@ -132,6 +133,24 @@ const steps = (man.steps ?? []).map((s) => {
   return out;
 });
 
+// ── LAW (page transitions, founder 2026-09-02): a mid-take navigation is CUT
+// out with a FADE — the viewer sees page one, a fade, page two, never the
+// loading blank. record.mjs stamps `nav {from,to}` on every goto after the
+// first; each becomes a cut on the uploaded timeline. No narration may start
+// inside a cut (pushed to the cut's end) and no camera shot may live in one
+// (clipped/split below) — the studio forbids zoom + TTS inside cuts anyway.
+const cuts = (man.steps ?? [])
+  .filter((s) => s.nav && Number.isFinite(s.nav.from) && Number.isFinite(s.nav.to))
+  .map((s) => ({ t_start: round2(norm(s.nav.from + 0.12)), t_end: round2(norm(s.nav.to)), transition: "fade", n: s.n }))
+  .filter((c) => c.t_end - c.t_start >= 0.3 && c.t_start >= 0 && c.t_end <= duration)
+  .sort((a, b) => a.t_start - b.t_start);
+const insideCut = (t) => cuts.find((c) => t > c.t_start && t < c.t_end);
+for (const st of steps) {
+  if (!st.narration) continue;
+  const c = insideCut(st.narration.t);
+  if (c) st.narration.t = round2(c.t_end + 0.1);
+}
+
 // ── LAW (breathing room, founder 2026-08-09): narration never speaks over
 // the first or last half second. A voice at t=0 startles; a voice cut by the
 // end reads broken. First line starts at >=0.5s; the last line ENDS at
@@ -281,6 +300,27 @@ const interactions = mouseEvents.length
     }
   : null;
 
+// Camera shots never overlap a cut: drop shots inside one, clip those that
+// straddle an edge, split those that contain one.
+if (cuts.length > 0) {
+  const clipped = [];
+  for (const sh of camera) {
+    let pieces = [{ ...sh }];
+    for (const c of cuts) {
+      const next = [];
+      for (const p of pieces) {
+        if (p.t_end <= c.t_start || p.t_start >= c.t_end) { next.push(p); continue; }
+        if (p.t_start < c.t_start) next.push({ ...p, t_end: round2(c.t_start) });
+        if (p.t_end > c.t_end) next.push({ ...p, t_start: round2(c.t_end) });
+      }
+      pieces = next;
+    }
+    for (const p of pieces) if (p.t_end - p.t_start >= 0.25) clipped.push(p);
+  }
+  camera.length = 0;
+  camera.push(...clipped.sort((a, b) => a.t_start - b.t_start));
+}
+
 const wire = {
   version: 2,
   app: man.app ?? "App",
@@ -289,13 +329,14 @@ const wire = {
   duration,
   steps,
   camera,
+  ...(cuts.length > 0 ? { cuts } : {}),
   ...(interactions ? { interactions } : {}),
 };
 const outPath = path.join(dir, "manifest.demobites.json");
 fs.writeFileSync(outPath, JSON.stringify(wire, null, 2));
 console.log(
   `manifest.demobites.json written (v2: ${steps.length} steps, ${camera.length} camera shots, ` +
-  `${mouseEvents.length} mouse events, ${duration}s)`,
+  `${mouseEvents.length} mouse events, ${cuts.length} cut${cuts.length === 1 ? "" : "s"}, ${duration}s)`,
 );
 
 if (wantSrt) {