demobite 1.0.1 → 1.0.3

package/README.md

@@ -31,6 +31,53 @@ The agent storyboards the flow, films it in a real Chrome, and stages the take
 for your approval inside DemoBites. You approve in the product; the platform
 does the rest.
 
+## Manage DemoBites from your agent (MCP)
+
+Recording is half the story. The same package wires the **DemoBites management
+MCP** — a control plane your agent uses to run your Update Center and Demo
+Center. Your customers' agents read your centers; your agent runs them.
+
+```bash
+npx demobite mcp
+```
+
+Claude Code is registered automatically. Any other MCP client works over
+Streamable HTTP: point it at `https://app.demobites.com/api/mcp` with the
+`Authorization: Bearer <key>` header the command prints (in Cursor, add both
+under Settings → MCP). Then talk to your agent like a teammate:
+
+> "Create a release with my latest bites, add Spanish, and publish it."
+
+> "What's on our Demo Center? Swap the checkout bite for the onboarding one."
+
+### What it can do — 19 tools
+
+| Group | Tools |
+|---|---|
+| Connect | `get_started` · `connect_demobites` · `check_connection` · `get_recording_options` |
+| Read | `get_status` · `list_bites` · `list_releases` · `get_release` · `list_languages` |
+| Draft & edit | `create_release` · `update_release` · `assign_bites_to_release` · `update_center_settings` · `add_language` · `update_demo_center` |
+| Publish — with your approval | `publish_release` · `unpublish_release` · `remove_language` · `publish_demo_center` |
+
+The server describes itself: any client's `tools/list` returns every tool with
+its full input schema, straight from the running code.
+
+### You stay in charge
+
+Draft work executes directly, exactly like clicking around the product. But
+anything that touches a **public** page is two-phase: the tool returns a
+human-readable preview plus a single-use confirmation token, your agent shows
+you the preview, and only your go-ahead executes it. Tokens expire in ten
+minutes, are bound to the exact action and arguments, and every management
+call lands in an audit log.
+
+### Plans
+
+Connecting and reading are open. Managing requires the **Grow** plan.
+Recording works on every plan.
+
+Full guide: [Manage from your agent](https://www.demobites.com/docs/bites/manage-from-your-agent)
+
 ## What's in this repository
 
 | Directory | What it is |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "demobite",
-  "version": "1.0.1",
-  "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.3",
+  "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,9 @@ 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).
+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 +532,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
@@ -615,6 +643,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);
@@ -755,6 +784,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);
@@ -795,6 +825,16 @@ try {
       pushMouse("move", cx, cy);
       await page.waitForTimeout(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 need = estimateSpeech(rec.narration) + 0.5;
+      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
@@ -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) {