demobites 1.37.0 → 1.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "demobites",
-  "version": "1.37.0",
+  "version": "1.39.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/record.mjs

@@ -599,11 +599,13 @@ async function visibleTarget(selector, minY = 0, timeout = 15000) {
     // third and re-scan — instead of failing the whole take. Bounded so a
     // genuinely-unreachable target still ends the loop. This is the camera
     // following the subject, not a camera-path change.
+    // THE SCROLL LAW (founder's take of 2026-10-18 jumped instead of scrolling): the correction GLIDES, never
+    // jumps — the same eased scroll a `scroll` step gets, ~800 ms, toward the target at 40% of the viewport.
+    // scrollIntoViewIfNeeded + an instant scrollBy was a cut in the middle of a take.
     if (offVerticalEl && scrollCorrections < 3) {
       scrollCorrections++;
-      await offVerticalEl.scrollIntoViewIfNeeded({ timeout: 2000 }).catch(() => {});
-      await page.evaluate(() => window.scrollBy(0, -Math.round(window.innerHeight * 0.28))).catch(() => {});
-      await page.waitForTimeout(450);
+      await glideIntoView(offVerticalEl, 800);
+      await page.waitForTimeout(300);
       continue;
     }
     await page.waitForTimeout(500);
@@ -764,6 +766,36 @@ async function glide(x, y) {
   await page.mouse.move(x, y).catch(() => {});
 }
 
+/** Ease the page (or the target's own scrolling panel) so the element lands at 40% of the viewport. The same
+ *  easing as smoothScroll, so a camera correction looks exactly like an authored scroll step. */
+async function glideIntoView(el, ms = 800) {
+  await el.evaluate((node, m) => new Promise((res) => {
+    const scrolls = (n) => {
+      if (!n || n === document.body || n === document.documentElement) return false;
+      const cs = getComputedStyle(n);
+      return /(auto|scroll|overlay)/.test(cs.overflowY) && n.scrollHeight > n.clientHeight + 40;
+    };
+    let panel = null;
+    for (let p = node.parentElement; p; p = p.parentElement) { if (scrolls(p)) { panel = p; break; } }
+    const r = node.getBoundingClientRect();
+    const h = panel ? panel.clientHeight : window.innerHeight;
+    const topInView = panel ? r.top - panel.getBoundingClientRect().top : r.top;
+    const d = Math.round(topInView - h * 0.4);
+    if (Math.abs(d) < 2) return res();
+    const y0 = panel ? panel.scrollTop : window.scrollY;
+    const t0 = performance.now();
+    const done = setTimeout(res, m + 500); // never hang the take on a tab that stops painting
+    const step = (now) => {
+      const e = Math.min(1, (now - t0) / m);
+      const ease = e < 0.5 ? 2 * e * e : 1 - Math.pow(-2 * e + 2, 2) / 2;
+      if (panel) panel.scrollTo(0, y0 + d * ease);
+      else window.scrollTo(0, y0 + d * ease);
+      if (e < 1) requestAnimationFrame(step); else { clearTimeout(done); res(); }
+    };
+    requestAnimationFrame(step);
+  }), ms).catch(() => {});
+}
+
 async function smoothScroll(dy, ms = 1400, within = null) {
   // `within` (2026-08-28, UC-studio lesson): full-viewport apps scroll INNER
   // panels, not the window — window.scrollTo is a no-op there. When set, it

package/skill/scripts/plan.mjs

@@ -148,14 +148,58 @@ const explore = (from, lookingFor, depth) => {
   for (const sc of res.screens.slice(0, 3)) if (sc.shot && fs.existsSync(sc.shot)) content.push({ type: "image", source: { type: "base64", media_type: "image/jpeg", data: fs.readFileSync(sc.shot).toString("base64") } });
   return content;
 };
+// THE SCROLL LAW (founder's take of 2026-10-18 jumped instead of scrolling): the dry run reports where every
+// click/hover/type target sat in the viewport (probe.mjs, the RESULT line). The geometry is kept with the camera
+// steps it was measured on; when the planner hands in that same storyboard, a scroll step is placed before every
+// target that sat below the fold (bottom > viewport − 120) or above it (top < 0), dy = top − 40% of the viewport,
+// 900 ms, so the camera glides there instead of the correction jumping it into frame.
+const FOLD_MARGIN = 120;
+const FOLD_AT = 0.4;
+let lastProbe = null; // { key, geometry: { steps: [...] } }
+const cameraKey = (sb) => (sb?.steps || []).map((s) => [s.action, s.url || "", s.selector || "", typeof s.dy === "number" ? s.dy : ""].join("|")).join("\n");
 const probe = (sb) => {
   if (!sb || !Array.isArray(sb.steps)) return "storyboard with steps[] required";
   const file = path.join(dir, "probe.json");
   fs.writeFileSync(file, JSON.stringify(sb, null, 2) + "\n");
   const r = run("probe.mjs", [file]);
-  const out = `${r.stdout || ""}${r.stderr ? `\n${r.stderr}` : ""}`.trim();
+  const all = (r.stdout || "").split("\n");
+  const last = all.filter((l) => l.startsWith("RESULT ")).pop();
+  let geometry = null; try { geometry = JSON.parse(last.slice(7)); } catch { /* an older probe, or it died */ }
+  lastProbe = geometry ? { key: cameraKey(sb), geometry } : null;
+  const text = all.filter((l) => !l.startsWith("RESULT ")).join("\n");
+  let out = `${text}${r.stderr ? `\n${r.stderr}` : ""}`.trim();
+  const below = foldScrolls(sb, geometry, true);
+  if (below.length) out += `\n\nBelow the fold: ${below.map((b) => `step ${b.step} (${b.selector}, top ${b.top} of ${b.viewport})`).join("; ")}. When you hand in this storyboard unchanged, a scroll step (dy ${below.map((b) => b.dy).join(", ")}, 900 ms) is placed before each of them for you; or add your own and probe again.`;
   return out.length > 12000 ? out.slice(0, 12000) + "\n… (cut)" : out || "(no report)";
 };
+/** The scroll steps the geometry asks for. dryRun = true only lists them; otherwise they are spliced into sb.steps. */
+const foldScrolls = (sb, geometry, dryRun = false) => {
+  const found = [];
+  if (!geometry || !Array.isArray(geometry.steps) || !Array.isArray(sb?.steps)) return found;
+  const byStep = new Map(geometry.steps.map((g) => [g.step, g]));
+  const steps = sb.steps;
+  let offset = 0; // what the inserted scrolls have already moved the page by, on the same screen
+  let lastUrl = null;
+  const outSteps = [];
+  for (const [i, s] of steps.entries()) {
+    const g = byStep.get(i + 1);
+    if (s.action === "goto") { offset = 0; lastUrl = null; }
+    if (g) {
+      if (lastUrl !== null && g.url !== lastUrl) offset = 0; // the probe navigated between the two targets
+      lastUrl = g.url;
+      const top = g.top - offset, bottom = g.bottom - offset;
+      if (bottom > g.viewport - FOLD_MARGIN || top < 0) {
+        const dy = Math.round(top - g.viewport * FOLD_AT);
+        found.push({ step: i + 1, selector: g.selector, top: g.top, viewport: g.viewport, dy });
+        if (!dryRun) outSteps.push({ action: "scroll", dy, ms: 900, frame: "wide", label: `bring ${String(g.selector).slice(0, 50)} into view`, inserted: "fold" });
+        offset += dy;
+      }
+    }
+    outSteps.push(s);
+  }
+  if (!dryRun && found.length) sb.steps = outSteps;
+  return found;
+};
 const ACTIONS = new Set(["goto", "settle", "scroll", "click", "hover", "type", "expect"]);
 const validate = (sb) => {
   if (!sb || typeof sb !== "object") return "storyboard required";
@@ -169,11 +213,11 @@ const validate = (sb) => {
     if (s.action === "scroll" && typeof s.dy !== "number") return `${at}: scroll needs numeric dy`;
     if (s.frame !== undefined && s.frame !== "close" && s.frame !== "wide") return `${at}: frame must be close or wide`;
   }
-  if (sb.steps.length > 14) return "more than 14 steps; 6 to 10 is the law";
+  if (sb.steps.length > 14) return "more than 14 steps; 5 to 8 is the law";
   // THE CAMERA'S CLOCK (founder 2026-10-15): the take may not run past 45 s. The estimate is the
   // camera's own (clock.mjs); the model gets the number and the cure.
   const est = estimateTake(sb.steps);
-  if (est > 45) return `the camera would run this take about ${Math.round(est)} s; the law is 30 to 45. Cut words (6 to 11 a line) or steps (5 to 8 narrated); never pad, never add.`;
+  if (est > 45) return `the camera would run this take about ${Math.round(est)} s; the law is 30 to 45. Cut words or steps: one line per idea, 3 to 6 narrated lines, no floor on a line, silence on the clicks; never pad, never add.`;
   return null;
 };
 
@@ -304,13 +348,18 @@ const plan = async () => {
           if (capped()) out = CAP_TEXT();
           else {
             probes += 1; if (!firstProbeAt) firstProbeAt = Date.now();
-            say(`Dry run of the storyboard, ${(input.storyboard?.steps || []).length} steps… (${probes} of ${CAP_PROBES})`);
+            say(`Walking the storyboard, ${(input.storyboard?.steps || []).length} steps…`);
             out = probe(input.storyboard);
             if (capped()) out += `\n\n${CAP_TEXT()}`;
           }
         }
         else if (u.name === "submit_storyboard") {
           say("Handing in the storyboard…");
+          // The fold scrolls go in before the clock is read, so the estimate is the take the camera will run.
+          if (lastProbe && input.storyboard && lastProbe.key === cameraKey(input.storyboard)) {
+            const added = foldScrolls(input.storyboard, lastProbe.geometry);
+            if (added.length) console.log(`  Scroll steps placed before ${added.map((a) => `step ${a.step}`).join(", ")} (below the fold in the dry run).`);
+          }
           const bad = validate(input.storyboard);
           if (bad) out = `Not accepted: ${bad}`;
           else { storyboard = input.storyboard; creates = typeof input.creates === "string" ? input.creates : ""; if (typeof input.unsure === "string" && input.unsure.trim()) storyboard.unsure = input.unsure.trim().slice(0, 240); out = "Accepted."; }

package/skill/scripts/probe.mjs

@@ -8,6 +8,13 @@
 // report lists the visible controls on that page so the planner can pick the
 // real one, and the run stops there.
 //
+// THE SCROLL LAW (founder's take of 2026-10-18 jumped instead of scrolling):
+// every target reports its geometry back, the element's top and bottom in the
+// viewport at the moment of the probe and the viewport's height, so the
+// planner (plan.mjs) knows which targets sit below the fold and puts a scroll
+// step before each of them. The last line of stdout is machine-readable:
+//   RESULT { passed, viewport, steps: [{ step, action, selector, top, bottom, viewport, url }] }
+//
 //   node scripts/probe.mjs <storyboard.json>
 import fs from "node:fs";
 import path from "node:path";
@@ -33,6 +40,9 @@ const ms = (v, d) => (typeof v !== "number" ? d : v < 60 ? v * 1000 : v);
 const lines = [];
 const out = (t) => { lines.push(t); console.log(t); };
 let failed = false;
+const VIEWPORT = launchOpts.viewport.height;
+const FOLD_MARGIN = 120;
+const geometry = [];
 
 const visible = async (selector, minY) => {
   const loc = page.locator(selector);
@@ -42,12 +52,20 @@ const visible = async (selector, minY) => {
     for (let i = 0; i < Math.min(n, 12); i++) {
       const el = loc.nth(i);
       const box = await el.boundingBox().catch(() => null);
-      if (box && box.width > 0 && box.height > 0 && box.y >= (minY || 0)) return el;
+      if (box && box.width > 0 && box.height > 0 && box.y >= (minY || 0)) return { el, box };
     }
     await page.waitForTimeout(250);
   }
   return null;
 };
+/** Where the target sat when the probe reached it: top and bottom in the viewport, and the viewport's height. */
+const place = (n, s, box) => {
+  const top = Math.round(box.y), bottom = Math.round(box.y + box.height);
+  const g = { step: n, action: s.action, selector: s.selector, top, bottom, viewport: VIEWPORT, url: page.url() };
+  geometry.push(g);
+  const where = bottom > VIEWPORT - FOLD_MARGIN ? " — BELOW THE FOLD: a scroll step goes before it" : top < 0 ? " — ABOVE THE VIEWPORT: a scroll step goes before it" : "";
+  return ` (top ${top}, bottom ${bottom} of ${VIEWPORT})${where}`;
+};
 const controls = async () => page.evaluate(() => {
   const vis = (el) => { const r = el.getBoundingClientRect(); const cs = getComputedStyle(el); return r.width > 0 && r.height > 0 && cs.visibility !== "hidden" && cs.display !== "none"; };
   const clean = (t) => (t || "").replace(/\s+/g, " ").trim();
@@ -86,7 +104,9 @@ for (const [i, s] of steps.entries()) {
       await page.waitForTimeout(600);
       out(`step ${n} scroll ${s.dy}: ok`);
     } else if (s.action === "click" || s.action === "hover" || s.action === "expect" || s.action === "type") {
-      const el = await visible(s.selector, s.minY);
+      const hit = await visible(s.selector, s.minY);
+      const el = hit?.el ?? null;
+      const geo = hit ? place(n, s, hit.box) : "";
       if (!el) {
         out(`step ${n} ${s.action} ${JSON.stringify(s.selector)}: NOT FOUND on ${page.url()}`);
         out(`  visible controls here:\n    ${(await controls()).join("\n    ")}`);
@@ -101,17 +121,17 @@ for (const [i, s] of steps.entries()) {
         if (s.waitLoad) await page.waitForLoadState("load").catch(() => {});
         let revealed = "";
         if (typeof s.reveals === "string" && s.reveals) revealed = (await visible(s.reveals, 0)) ? `, reveals ${JSON.stringify(s.reveals)} seen` : `, reveals ${JSON.stringify(s.reveals)} NOT SEEN`;
-        out(`step ${n} click ${JSON.stringify(s.selector)}: ok${revealed} — now at ${page.url()}`);
+        out(`step ${n} click ${JSON.stringify(s.selector)}: ok${geo}${revealed} — now at ${page.url()}`);
       } else if (s.action === "type") {
         if (s.clear) await el.fill("");
         await el.click({ timeout: 8000 }).catch(() => {});
         await el.type(String(s.text), { delay: 10 });
         if (s.enter) { await page.keyboard.press("Enter"); await page.waitForTimeout(Math.min(ms(s.after, 1500), 4000)); }
-        out(`step ${n} type into ${JSON.stringify(s.selector)}: ok — now at ${page.url()}`);
+        out(`step ${n} type into ${JSON.stringify(s.selector)}: ok${geo} — now at ${page.url()}`);
       } else {
         await el.hover().catch(() => {});
         await page.waitForTimeout(400);
-        out(`step ${n} ${s.action === "click" ? "pointed at" : s.action} ${JSON.stringify(s.selector)}: ok`);
+        out(`step ${n} ${s.action === "click" ? "pointed at" : s.action} ${JSON.stringify(s.selector)}: ok${geo}`);
       }
     } else {
       out(`step ${n}: unknown action ${JSON.stringify(s.action)}`);
@@ -126,5 +146,6 @@ for (const [i, s] of steps.entries()) {
   }
 }
 out(failed ? "PROBE FAILED: fix the steps above and probe again." : `PROBE PASSED: ${steps.length} steps resolved.`);
+console.log("RESULT " + JSON.stringify({ passed: !failed, viewport: VIEWPORT, steps: geometry }));
 await ctx.close();
 process.exit(failed ? 1 : 0);

package/skill/scripts/stage-wait.mjs

@@ -22,6 +22,7 @@
 // this take; a no-op everywhere else (the terminal flow, the cloud sandbox
 // copy that may not ship listen-event.mjs).
 const postEvent = await import("./listen-event.mjs").then((m) => m.postEvent).catch(() => async () => null);
+const listening = await import("./listen-event.mjs").then((m) => m.listening).catch(() => false);
 /** Where the person watches their takes: the Demos grid. `dashboardUrl` from
  * the server wins (relative or absolute), else <base>/demos. */
 export function gridUrl(base, dashboardUrl) {
@@ -151,6 +152,16 @@ export async function waitForDecision({ base, apiKey, stagingId, pageUrl, delive
     if (last.zooms === 0) console.error("WARNING: no camera shots landed.");
   }
   if (finalStudioUrl) console.log(`Studio: ${finalStudioUrl}`);
+  // THE STILLS, DRAWN HERE BEFORE "READY" (2026-10-18): the demo's intro and backdrop, by the studio's own code in
+  // this recorder's Chrome, remembered by the app so the export draws nothing. Bounded; a miss costs nothing.
+  if (listening) {
+    try {
+      const { spawnSync } = await import("node:child_process");
+      const here = (await import("node:path")).dirname((await import("node:url")).fileURLToPath(import.meta.url));
+      const r = spawnSync(process.execPath, [(await import("node:path")).join(here, "stills.mjs"), String(approvedBiteId)], { cwd: process.cwd(), encoding: "utf8", env: process.env, timeout: 60000 });
+      for (const l of (r.stdout || "").trim().split("\n").filter(Boolean)) console.log(`  ${l}`);
+    } catch (e) { console.log(`  stills: skipped (${String(e?.message ?? e).split("\n")[0]})`); }
+  }
   await postEvent("ready", { biteId: approvedBiteId, studioUrl: finalStudioUrl ?? null });
   return { exitCode: 0, status: "completed", biteId: approvedBiteId, studioUrl: finalStudioUrl };
 }

package/skill/scripts/stills.mjs

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// THE STILLS ARE DRAWN HERE (founder 2026-10-18: "at that point you have a browser… load fabric… create the two
+// images"). After the demo is built and before this recorder says "ready", its own Chrome opens the app's internal
+// still page — the studio's own render code, the design's fonts from the web — for the intro and the backdrop,
+// and hands the PNGs to the app, which remembers them for the export. Seconds here; a 30-second sandbox saved there.
+// Never fatal: on any miss the export draws them itself as before.
+// usage: node stills.mjs <biteId>     (base and key from <cwd>/.recorder/config.json)
+import fs from "node:fs";
+import path from "node:path";
+const biteId = Number(process.argv[2] || 0);
+if (!biteId) { console.error("usage: stills.mjs <biteId>"); process.exit(2); }
+const cfg = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), ".recorder", "config.json"), "utf8"));
+const base = (process.env.RECORDER_BASE || cfg.base || "https://app.demobites.com").replace(/\/+$/, "");
+const headers = { Authorization: `Bearer ${cfg.api_key}`, "Content-Type": "application/json" };
+const t0 = Date.now();
+const plan = await fetch(`${base}/api/recorder/stills?bite_id=${biteId}`, { headers, signal: AbortSignal.timeout(15000) }).then((r) => (r.ok ? r.json() : null)).catch(() => null);
+if (!plan?.stills?.length) { console.log("stills: nothing to draw here"); process.exit(0); }
+const { chromium } = await import("playwright");
+const browser = await chromium.launch({ channel: "chrome", headless: true }).catch(async () => chromium.launch({ headless: true }));
+const out = {};
+try {
+  const ctx = await browser.newContext({ viewport: { width: 1920, height: 1080 } });
+  for (const still of plan.stills) {
+    const page = await ctx.newPage();
+    try {
+      const res = await page.goto(still.url, { waitUntil: "domcontentloaded", timeout: 20000 });
+      if (!res || res.status() !== 200) throw new Error(`the still page answered ${res ? res.status() : "nothing"}`);
+      await page.waitForFunction("window.__FABRIC_STILL__ !== undefined", undefined, { timeout: 25000 });
+      const r = await page.evaluate("window.__FABRIC_STILL__");
+      if (!r?.ok || typeof r.dataUrl !== "string" || !r.dataUrl.startsWith("data:image/png;base64,")) throw new Error(r?.error || "no PNG from the still page");
+      out[still.kind] = r.dataUrl.slice("data:image/png;base64,".length);
+      console.log(`stills: ${still.kind} drawn (${Math.round(out[still.kind].length * 0.75 / 1024)} KB)`);
+    } catch (e) { console.log(`stills: ${still.kind} skipped (${String(e?.message ?? e).split("\n")[0]})`); }
+    finally { await page.close().catch(() => {}); }
+  }
+} finally { await browser.close().catch(() => {}); }
+if (!Object.keys(out).length) process.exit(0);
+const put = await fetch(`${base}/api/recorder/stills`, { method: "PUT", headers, body: JSON.stringify({ bite_id: biteId, hash: plan.hash, stills: out }), signal: AbortSignal.timeout(30000) }).then((r) => r.json().catch(() => ({ ok: r.ok }))).catch((e) => ({ error: String(e?.message ?? e) }));
+console.log(`stills: ${put?.ok ? `remembered for the export (${Object.keys(out).join(", ")})` : `not kept (${put?.error ?? "?"})`} in ${((Date.now() - t0) / 1000).toFixed(1)} s`);