@vosjs/cli 0.38.0 → 0.39.0

package/README.md

@@ -60,6 +60,7 @@ A **take** is a directory: the recording of a scripted browser flow, its exact c
 
 ```bash
 vos create --actions actions.json out.webm --strict     # one shot: record, auto-plan, render
+vos record --actions actions.json --out take --dry-run  # rehearse the script first: which selectors resolve, their rects, in seconds
 vos record --actions actions.json --out take --strict   # drive the page, record it with an exact cursor track, plan the cut
 vos digest take                                         # SEE the recording before cutting: moments, frames, crops (an agent's eyes)
 # … edit take/doc.json (zoom spans, trims, speed, overlays) by hand or by agent …
@@ -79,7 +80,7 @@ vos plan take --reuse                                   # re-time that cut onto
 
 | Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                                                                                                                  |
+| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--keep-frames` `--storage-state <file>` `--browser-arg=<switch>`... `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                                 |
 | `create` | The `record` flags plus the render flags (`--width` `--height` `--fps` `--format` `--parallel` `--draft` `--frame` `--set`), no `--range`. With `--strict` an incomplete recording exits 2 before anything is rendered                                                                                                                                                                                                                                                    |
 | `plan`   | `--fresh` (discard the current plan) `--reuse` `--from <doc.json>` (defaults to `<take>/doc.prev.json`) `--style <doc.json\|take\|vosId>` `--with <doc.json\|take\|vosId>[@end\|@start\|@step:<id>\|@<seconds>]` (a template, repeatable) `--background` `--motion` (re-propose the motion) `--headline` `--kicker` `--launch` `--brand` `--music` `--entrance` `--transitions slide\|fade\|scale\|none` `--end-card on\|none\|<ref>` `--captions` `--clicks` `--release` |
 | `digest` | `--out <take>/digest` `--full 960` `--crop 640` (image long edges, the token budget) `--no-frames` `--transcript <file>` (Whisper-shaped segments merged as `said`) `--style <ref>` (report a reference document's style fields)                                                                                                                                                                                                                                          |
@@ -87,6 +88,8 @@ vos plan take --reuse                                   # re-time that cut onto
 | `render` | `--width` `--height` `--fps` `--format webm\|mp4` `--parallel N` (1..16 sessions) `--range a..b` (output seconds; keeps its audio) `--draft` `--frame <kind>` `--background` `--set …`; `out` defaults to `<take>/out.<format>`                                                                                                                                                                                                                                           |
 | `open`   | `--studio http://localhost:6060` `--print` (print the URL, do not launch a browser)                                                                                                                                                                                                                                                                                                                                                                                       |
 
+**Rehearse before you record.** `vos record … --dry-run` runs every step against the real page, in order, because a later selector usually exists only after an earlier click. Nothing is captured and nothing is written: the pointer lands instead of travelling, every pause is cut to a beat, and the take directory beside it keeps its footage, its cut and its script exactly as they were (a real re-record moves `doc.json` aside; a rehearsal does not). Selector lookups keep their whole timeout, so a miss here is a miss in the take. It prints each step with the rect it resolved, in capture px, which are the rects a pin or `vos callout --step` reads, and exits 2 on any miss or a first load that never settled. Add `--dry-run` to the exact command you were about to run; `--storage-state` and `--browser-arg=` apply to it too.
+
 **Digest first.** `vos digest <take>` is how an agent sees a recording without reading the video. It writes `digest/digest.json`: one moment per thing the cursor track says mattered (click clusters, typing sessions, scroll runs, dwells, idle gaps, head, tail, and frame-diff scene changes), each with source and output extents, a normalized `focus` and `rect` you can copy into a zoom span, per-second `activity`, and the planners' `proposed` span ids; plus one footage frame and a crop around the target per moment, and `sheet.png`, the contact sheet. Read the JSON, then the sheet, then a crop only where you must decide. `vos validate` then warns when a zoom does not contain what was clicked under it, and `vos frames --at-moments` renders the composed output at every moment so a still and its footage crop share an id.
 
 **Many media in one take (concat).** `doc.json` may carry `media: [{ id, videoKey, cursor, meta, … }]`, the take's OTHER recordings or uploads, each the `source` shape with an `id`; a segment on one (`{ in, out, media: "m1" }`) plays it, and a zoom, tilt, speed, freeze or cam-move span names the media its source seconds belong to (absent = the primary, `source`). The Video row shows the clips in order, a span is drawn where its media plays, `vos plan` proposes zoom and speed spans on every media from its own cursor track, `vos validate` measures each span against its own media's length, and `vos push` and `vos pull --media` carry every media through the recording door. A media wears its OWN card: `media[].frame` carries the card-owned fields (its placement and size as `inset`, the browser bar, the corner, the shadow, the border, the cover fit and its focus) over the take's frame while it plays; the bar names that media's recorded page, an upload with no page wears none, and the frame-wide fields (the aspect, the padding, the ground, the backdrop, the card's animation) stay the take's. Sound: the primary's tracks play at the primary's moments; another media's own audio is not spliced into the cut yet. **Many cards**: an image or video overlay may show a document media by reference (`key: "media:<id>"`, `media:` alone the primary; its cursor track and recorded page come with it) and wear a card (`frame`: `browserBar`, a `lean` `{rx, ry}` in degrees, `shadow`, `shadowContact`, `shadowColor`, `cursor`), drawn by the card painter on its own plane above the primary card with the media's cursor dot and click rings inside it; a layer without `frame` stays the flat picture. The primary card stays primary: the sequence, the camera and the cut are its.

package/dist/{chunk-LGRNHJ2U.js → chunk-RECQEBXN.js}

@@ -6629,7 +6629,8 @@ function paceLine(r) {
 }
 
 // src/plugin/recorder.ts
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var DRY_PAUSE_MS = 120;
 function jpegDims(buf) {
   let i = 2;
   while (i < buf.length - 9) {
@@ -6644,7 +6645,9 @@ function jpegDims(buf) {
   return null;
 }
 async function recordTake(browser, url, actions, paths, log, opts = {}) {
-  const maxSeconds = opts.maxDurationSeconds ?? Infinity;
+  const dry = opts.dryRun === true;
+  const sleep = dry ? (ms) => realSleep(Math.min(ms, DRY_PAUSE_MS)) : realSleep;
+  const maxSeconds = dry ? Infinity : opts.maxDurationSeconds ?? Infinity;
   const vw = actions.viewport?.width ?? 1280;
   const vh = actions.viewport?.height ?? 720;
   const context = await browser.newContext({
@@ -6667,22 +6670,24 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const frames = [];
   let frameIdx = 0;
   let t0 = 0;
-  cdp.on("Page.screencastFrame", (ev) => {
-    const tsMs = ev.metadata.timestamp ? ev.metadata.timestamp * 1e3 : Date.now();
-    const file = `frame-${String(frameIdx++).padStart(5, "0")}.jpg`;
-    writeFileSync2(join13(paths.framesDir, file), Buffer.from(ev.data, "base64"));
-    frames.push({ file, tMs: Math.max(0, Math.round(tsMs - t0)) });
-    cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {
+  if (!dry)
+    cdp.on("Page.screencastFrame", (ev) => {
+      const tsMs = ev.metadata.timestamp ? ev.metadata.timestamp * 1e3 : Date.now();
+      const file = `frame-${String(frameIdx++).padStart(5, "0")}.jpg`;
+      writeFileSync2(join13(paths.framesDir, file), Buffer.from(ev.data, "base64"));
+      frames.push({ file, tMs: Math.max(0, Math.round(tsMs - t0)) });
+      cdp.send("Page.screencastFrameAck", { sessionId: ev.sessionId }).catch(() => {
+      });
     });
-  });
   t0 = Date.now();
-  await cdp.send("Page.startScreencast", {
-    format: "jpeg",
-    quality: 90,
-    maxWidth: vw,
-    maxHeight: vh,
-    everyNthFrame: 1
-  });
+  if (!dry)
+    await cdp.send("Page.startScreencast", {
+      format: "jpeg",
+      quality: 90,
+      maxWidth: vw,
+      maxHeight: vh,
+      everyNthFrame: 1
+    });
   const events = [];
   const cur = { x: 48, y: 48 };
   const now = () => Date.now() - t0;
@@ -6694,7 +6699,7 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
     const dist = Math.hypot(tx - cur.x, ty - cur.y);
     const from = { ...cur };
     await clockMotion(
-      pointerTravelMs(dist),
+      dry ? 0 : pointerTravelMs(dist),
       async (u) => {
         cur.x = from.x + (tx - from.x) * u;
         cur.y = from.y + (ty - from.y) * u;
@@ -6969,12 +6974,14 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
       `   WARNING: ${freezePct}% of the take is visually frozen (${freezes.length} freezes, longest ${Math.max(...freezes.map((f) => f.ms))}ms) \u2014 keep motion in frame or trim these spans in doc.json`
     );
   }
-  await writeJson(paths.cursor, events);
-  await writeJson(paths.meta, meta, true);
-  await writeJson(paths.framesIndex, frames);
-  await writeJson(paths.actions, { ...actions, url }, true);
   const pace = paceReport(paces);
-  log(`   ${paceLine(pace)}`);
+  if (!dry) {
+    await writeJson(paths.cursor, events);
+    await writeJson(paths.meta, meta, true);
+    await writeJson(paths.framesIndex, frames);
+    await writeJson(paths.actions, { ...actions, url }, true);
+    log(`   ${paceLine(pace)}`);
+  }
   return {
     events,
     frames,
@@ -8345,12 +8352,12 @@ async function browserLogin(origin, r, opts) {
   r.log(`Sign in at ${verifyUrl}`);
   if (opts.openBrowser) void launchDefaultBrowser(verifyUrl);
   r.log("Waiting for approval\u2026 (Ctrl-C to cancel)");
-  const sleep2 = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
+  const sleep = opts.sleep ?? ((ms) => new Promise((res) => setTimeout(res, ms)));
   let intervalMs = baseIntervalMs;
   let failures = 0;
   let capNoted = false;
   while (Date.now() < expiresAt) {
-    await sleep2(intervalMs);
+    await sleep(intervalMs);
     let res;
     try {
       res = await apiJson(origin, "/api/cli/login/poll", {
@@ -10108,14 +10115,15 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "check",
   "motion",
   "leader",
-  "keep-frames"
+  "keep-frames",
+  "dry-run"
 ]);
 var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg"]);
 var HELP = `vos \u2014 record a browser flow, plan effects, render a product video; sync with vos.so
 
 Take pipeline
   vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
-  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
+  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
   vos plan <take> [--fresh] [--reuse [--from <doc.json>]] [--style <doc.json|vosId>] [--with <doc.json|vosId>[@end|@start|@step:<id>|@<s>]]... [--background <slug|url|none>] [--motion] [--headline "\u2026"] [--kicker "\u2026"] [--launch LAUNCH.md] [--brand BRAND.md] [--music <slug|mood|none>] [--entrance tilt-in|pull-out|rise|fade|slide|none] [--transitions slide|fade|scale|none] [--end-card on|none|<doc.json|vosId>] [--captions none] [--clicks none] [--still <t>] [--release v2.1] [--json]
   vos render <take> [out.webm] [--width] [--height] [--fps] [--format webm|mp4] [--parallel N] [--range a..b] [--draft] [--frame <kind>] [--background <url|slug>] [--set <path=value>]... [--json]
   vos frames <take> [--times 0,25%,50%,75%,100%] [--frame <t>] [--at-zooms] [--at-moments] [--at-still] [--size WxH] [--out dir] [--background <url|slug>] [--set <path=value>]... [--json]
@@ -10445,6 +10453,47 @@ async function cmdRecord(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  if (flags["dry-run"] === true) {
+    void flags.strict;
+    void flags["keep-frames"];
+    const browser2 = await launchBrowser(browserArgs);
+    try {
+      r.log("rehearsing (nothing is captured or written)\u2026");
+      r.event({ event: "phase", phase: "rehearse" });
+      const started = Date.now();
+      const rec = await recordTake(
+        browser2,
+        url,
+        actions,
+        takePaths(outDir),
+        r.log,
+        { storageState, dryRun: true }
+      );
+      const steps = rec.meta.steps ?? [];
+      const lines = steps.map((s) => {
+        const rect = s.rect ? `  rect ${s.rect.x},${s.rect.y} ${s.rect.w}\xD7${s.rect.h}` : "";
+        const what = s.selector ? ` ${s.selector}` : "";
+        return `  ${s.skipped ? "\u2717" : "\u2713"} #${s.step}${s.id ? ` (${s.id})` : ""} ${s.do}${what}${s.skipped ? "  NOT FOUND" : rect}${s.navigated ? "  \u2192 navigated" : ""}`;
+      });
+      const failed2 = rec.skipped.length > 0 || rec.navTimeout;
+      r.done(
+        {
+          dryRun: true,
+          ok: !failed2,
+          seconds: +((Date.now() - started) / 1e3).toFixed(1),
+          steps,
+          skipped: rec.skipped,
+          navTimeout: rec.navTimeout
+        },
+        `${failed2 ? "REHEARSAL FAILED" : "Rehearsal passed"}: ${steps.length - rec.skipped.length}/${steps.length} steps resolved in ${((Date.now() - started) / 1e3).toFixed(1)}s${rec.navTimeout ? " (the first load never reached networkidle)" : ""}
+${lines.join("\n")}
+  ${failed2 ? "Fix the script, rehearse again, then record." : `Rects are capture px (the step rects a pin or a callout reads). Next: vos record --actions ${actionsPath} --out ${outDir} --strict`}`
+      );
+      return failed2 ? EXIT_USAGE : EXIT_OK;
+    } finally {
+      await browser2.close();
+    }
+  }
   if (existsSync15(join18(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
@@ -11691,4 +11740,4 @@ export {
   takeBrowserArgs,
   run
 };
-//# sourceMappingURL=chunk-LGRNHJ2U.js.map
+//# sourceMappingURL=chunk-RECQEBXN.js.map