@vosjs/cli 0.42.0 → 0.44.0

package/README.md

@@ -80,7 +80,7 @@ vos plan take --reuse                                   # re-time that cut onto
 
 | Verb     | Flags                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--allow-wall` `--keep-frames` `--storage-state <file>` `--browser-arg=<switch>`... `--max-duration <s>` `--background <slug\|url\|none>`                                                                                                                                                                                                                                                  |
+| `record` | `--actions <file>` (or positional) `--url` `--out take` `--strict` `--dry-run` `--allow-wall` `--keep-frames` `--storage-state <file>` `--header name=value`... `--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)                                                                                                                                                                                                                                          |
@@ -90,6 +90,21 @@ vos plan take --reuse                                   # re-time that cut onto
 
 **The wall check.** Once the first navigation settles, and before a frame is captured, `record`, `create` and `--dry-run` ask whether the recorder landed where it was sent. A take that met a sign-in instead is refused with exit 4 and a sentence (`asked for /dashboard, landed on /login: no session for app.acme.com`): the asked URL answered 401 or 403, the recorder was sent to an identity provider or a sign-in path, or the page is a sign-in form (one password field, or a one-time-code field) rendered in place. A redirect somewhere else with no sign-in in sight, which is what a site that shows strangers a public page looks like, is refused under `--strict` and in a rehearsal, and said as a warning otherwise. The check runs before a re-record clears anything, so a session that expired since the last take never costs the footage it failed to replace. The way past a wall is a session: `--storage-state <file>`, minted from the test auth the project already has wherever that exists. `--allow-wall` records the page anyway (a video OF a sign-in page is a legitimate take), and the take's `meta.wall` and its digest then say so.
 
+**`setup`: the steps that run before the camera rolls.** A sign-in form, a cookie banner, the "choose your editor" modal, an onboarding tour: things a take must get past and must not show. `actions.json` takes `setup: [...]` beside `steps`, with the verbs `goto`, `click`, `type`, `press`, `wait`. They run after the first navigation and before a frame is captured, as plain actions with no cursor, no frames, no pace and nothing in `meta.steps`; then the recorder opens `url` again and the take begins where the setup left it. A `type` step's `text` may be `{ "env": "DEMO_PASSWORD" }`, read from the shell at run time and never logged or stored (the log names the field, never the value; a literal typed into a password field is refused by `validate`, because `actions.json` is committed and pushed with the take). A selector that never appears fails the take before anything is recorded (exit 2), because a take that begins at a half-finished sign-in is the wall by another name; rehearse the setup with `--dry-run` like everything else. This is rung 2 of the session ladder made scriptable: a local or self-hosted instance with a seeded user, no state file needed.
+
+```json
+"setup": [
+  { "do": "goto", "url": "http://localhost:3000/login" },
+  { "do": "type", "selector": "#email", "text": "demo@acme.test" },
+  { "do": "type", "selector": "#password", "text": { "env": "DEMO_PASSWORD" } },
+  { "do": "press", "key": "Enter", "ms": 800 }
+]
+```
+
+**`vos actions script <actions.json>`: the flow as a shot list.** When no rung of the session ladder holds and a person has to record the take themselves (in their own signed-in browser, with the vosso extension), the agent hands over the flow it worked out rather than an apology: numbered beats in plain words with the holds the script asked for, the page to start on and about how long. A step's `caption` leads its beat, a `text=` or `:has-text()` selector is said as its words, and a step's `id` is said as a name (`new-order` reads as "new order"), so give steps ids and captions that a person could follow. `--json` carries the beats beside the text. The take comes back through the ordinary handoff, and the agent cuts it (`vos pull --media`, then the `vos-cut` skill).
+
+**`--header name=value`**, repeatable: a request header on every request the recording browser makes, the way past a preview deployment protected by a bypass header alone (`--header x-vercel-protection-bypass=$TOKEN`). The rehearsal's `Next:` line carries it.
+
 **What the frame shows.** Getting past a login puts the account's own data in the picture, and asking for a demo account does not hold that line: a person asked to sign in signs in as themselves. So the recorder looks. After the page opens and after every step it reads the text visible in the viewport and reports the KIND of thing it saw and where, never the string: an email address (one on `example.com` or a `.test`, `.example`, `.invalid` or `.localhost` domain is demo data and is not reported), something shaped like an API key or a JWT, a card number that passes the Luhn check, a masked card's visible tail. They land in `meta.exposures[]` (`step`, `kind`, `selector`, `rect`, `seen`), in the `record` and `create` done events, at the end of a rehearsal (before anything is recorded), as warnings in `vos validate <take>`, and in the digest's `take.exposures`. They warn; they do not fail a take, because a product may legitimately show addresses. The `selector` reaches that element and no other, so it can be pasted into a mask.
 
 **`mask`** in `actions.json` hides a selector BEFORE the first frame is captured and keeps it hidden across navigations and re-renders, so the real value is never in a frame, never in the recording, never pushed:

package/dist/chunk-RDQYYRWN.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+// src/plugin/pace.ts
+var POINTER_MS_PER_PX = 0.7;
+var POINTER_MIN_MS = 250;
+var POINTER_MAX_MS = 800;
+var MOTION_TICK_MS = 16;
+var SETTLE_MS = {
+  click: 150,
+  type: 150,
+  scroll: 200,
+  drag: 80
+};
+var PRESS_LEAD_MS = 80;
+var PRESS_HOLD_MS = 70;
+var SCROLL_SETTLE_MS = 120;
+var TRAILING_HOLD_MS = 400;
+function pointerTravelMs(dist) {
+  return Math.min(
+    POINTER_MAX_MS,
+    Math.max(POINTER_MIN_MS, Math.round(dist * POINTER_MS_PER_PX))
+  );
+}
+function settleMs(step) {
+  if (typeof step.ms === "number" && step.ms >= 0) return step.ms;
+  const d = step.do;
+  return SETTLE_MS[d] ?? 0;
+}
+var easeInOutCubic = (u) => u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2;
+async function clockMotion(dur, at, clock) {
+  const start = clock.now();
+  let samples = 0;
+  for (; ; ) {
+    const elapsed = clock.now() - start;
+    if (elapsed >= dur) break;
+    await at(easeInOutCubic(Math.min(1, elapsed / dur)));
+    samples++;
+    const next = start + Math.ceil((clock.now() - start) / MOTION_TICK_MS) * MOTION_TICK_MS;
+    const wait = Math.min(next, start + dur) - clock.now();
+    if (wait > 0) await clock.sleep(wait);
+  }
+  await at(1);
+  return samples + 1;
+}
+async function clockTyping(chars, delay, type, clock) {
+  const start = clock.now();
+  for (let i = 0; i < chars.length; i++) {
+    await type(chars[i], i);
+    const due = start + (i + 1) * delay;
+    const wait = due - clock.now();
+    if (wait > 0 && i < chars.length - 1) await clock.sleep(wait);
+  }
+}
+function askedMs(step) {
+  switch (step.do) {
+    case "wait":
+      return step.ms ?? 0;
+    case "hover":
+      return step.ms ?? 700;
+    case "drag":
+      return step.ms ?? 700;
+    case "type":
+      return (step.text?.length ?? 0) * (step.delayMs ?? 40);
+    default:
+      return 0;
+  }
+}
+function paceReport(steps) {
+  const askedMs2 = steps.reduce((a, s) => a + s.askedMs, 0);
+  const gestureMs = steps.reduce((a, s) => a + s.gestureMs, 0);
+  const wallMs = steps.reduce((a, s) => a + s.wallMs, 0);
+  const overheadMs = Math.max(0, wallMs - askedMs2 - gestureMs);
+  const slow = steps.filter((s) => s.wallMs > (s.askedMs + s.gestureMs) * 1.34 + 60).map((s) => ({
+    step: s.step,
+    do: s.do,
+    askedMs: s.askedMs,
+    wallMs: s.wallMs
+  }));
+  return {
+    askedMs: askedMs2,
+    gestureMs,
+    wallMs,
+    overheadMs,
+    overheadPct: wallMs > 0 ? Math.round(overheadMs / wallMs * 100) : 0,
+    slow
+  };
+}
+function paceLine(r) {
+  const s = (ms) => `${(ms / 1e3).toFixed(1)} s`;
+  const slow = r.slow.length ? `; slow: ${r.slow.map((x) => `#${x.step} ${x.do} ${s(x.wallMs)} for ${s(x.askedMs)} asked`).join(", ")}` : "";
+  return `pace: the script asked ${s(r.askedMs)}, the gestures added ${s(r.gestureMs)}, the take ran ${s(r.wallMs)} (${r.overheadPct} % overhead${slow})`;
+}
+
+export {
+  PRESS_LEAD_MS,
+  PRESS_HOLD_MS,
+  SCROLL_SETTLE_MS,
+  TRAILING_HOLD_MS,
+  pointerTravelMs,
+  settleMs,
+  clockMotion,
+  clockTyping,
+  askedMs,
+  paceReport,
+  paceLine
+};
+//# sourceMappingURL=chunk-RDQYYRWN.js.map

package/dist/chunk-RDQYYRWN.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin/pace.ts"],"sourcesContent":["/**\n * The recorder's pace — the pure parts.\n *\n * A take of a scripted flow should run as long as the script asks, plus the\n * gestures a person makes between the asks (the pointer's travel, the press,\n * the settle after it) and no more. Measured before this module (§4.5 of\n * the utility-clip retrospective), hovers ran 2× their ask, drags 4.8× and\n * a 25 s script recorded 42 s, for two reasons the numbers here answer:\n *\n *  - The motion loops counted STEPS (one per 16 ms of the asked duration)\n *    and awaited a `mouse.move` round trip per step, so a page that\n *    re-renders per move (a slider) stretched every gesture by the round\n *    trip. A gesture is now driven by the CLOCK: its position is a function\n *    of the elapsed time, and it ends when the asked duration has elapsed,\n *    however many samples the page allowed.\n *  - The settles after a gesture were fixed sleeps (500 ms after a click,\n *    250 after every selector lookup). A settle is DATA: `ms` on the step\n *    overrides a small default, and the script's own `wait` steps carry\n *    the intended pauses.\n */\n\n/** Pointer travel: ms per CSS px, floor and ceiling — a person's hand. */\nexport const POINTER_MS_PER_PX = 0.7\nexport const POINTER_MIN_MS = 250\nexport const POINTER_MAX_MS = 800\n/** The sample cadence a motion loop aims for. */\nexport const MOTION_TICK_MS = 16\n\n/** The settle after a gesture when the step names none, by verb. */\nexport const SETTLE_MS = {\n  click: 150,\n  type: 150,\n  scroll: 200,\n  drag: 80,\n} as const\n\n/** The press: the pause before the button goes down, and the hold. */\nexport const PRESS_LEAD_MS = 80\nexport const PRESS_HOLD_MS = 70\n/** The pause between a selector lookup that scrolled the page and the move. */\nexport const SCROLL_SETTLE_MS = 120\n/** The hold after the last step, so the take does not cut on a press. */\nexport const TRAILING_HOLD_MS = 400\n\n/** How long the pointer takes to travel `dist` CSS px. */\nexport function pointerTravelMs(dist: number): number {\n  return Math.min(\n    POINTER_MAX_MS,\n    Math.max(POINTER_MIN_MS, Math.round(dist * POINTER_MS_PER_PX)),\n  )\n}\n\n/** The settle after a step: its own `ms` when it names one, else the verb's. */\nexport function settleMs(step: { do: string; ms?: number }): number {\n  if (typeof step.ms === 'number' && step.ms >= 0) return step.ms\n  const d = step.do as keyof typeof SETTLE_MS\n  return SETTLE_MS[d] ?? 0\n}\n\nexport const easeInOutCubic = (u: number): number =>\n  u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2\n\n/**\n * Drive a motion by the clock: `at(u)` is called with the eased progress\n * for each sample, and the loop ends when `dur` ms have elapsed, with the\n * last call at u = 1 exactly. Between samples it sleeps to the next tick\n * only when the sample came back early; a slow sample (a page busy\n * re-rendering) is followed at once, so the gesture keeps its length and\n * loses samples, never the other way round.\n */\nexport async function clockMotion(\n  dur: number,\n  at: (u: number) => Promise<void>,\n  clock: { now: () => number; sleep: (ms: number) => Promise<void> },\n): Promise<number> {\n  const start = clock.now()\n  let samples = 0\n  for (;;) {\n    const elapsed = clock.now() - start\n    if (elapsed >= dur) break\n    await at(easeInOutCubic(Math.min(1, elapsed / dur)))\n    samples++\n    const next =\n      start + Math.ceil((clock.now() - start) / MOTION_TICK_MS) * MOTION_TICK_MS\n    const wait = Math.min(next, start + dur) - clock.now()\n    if (wait > 0) await clock.sleep(wait)\n  }\n  await at(1)\n  return samples + 1\n}\n\n/**\n * Typing paced by the clock: the i-th character is due at `start + i·delay`;\n * after each keystroke the loop sleeps to the next due time only if the\n * keystroke came back early. A slow field (an editor re-rendering per key)\n * types as fast as it can and says so in the pace report.\n */\nexport async function clockTyping(\n  chars: readonly string[],\n  delay: number,\n  type: (ch: string, index: number) => Promise<void>,\n  clock: { now: () => number; sleep: (ms: number) => Promise<void> },\n): Promise<void> {\n  const start = clock.now()\n  for (let i = 0; i < chars.length; i++) {\n    await type(chars[i], i)\n    const due = start + (i + 1) * delay\n    const wait = due - clock.now()\n    if (wait > 0 && i < chars.length - 1) await clock.sleep(wait)\n  }\n}\n\n/** One step's pace: what the script asked for it and what it took. */\nexport interface StepPace {\n  step: number\n  do: string\n  /** The script's own ask: a wait's ms, a hover's dwell, a drag's ms, typing's chars × delay; 0 for a click or a scroll. */\n  askedMs: number\n  /** The gesture the recorder adds by design: pointer travel, the press, the settle. */\n  gestureMs: number\n  wallMs: number\n}\n\nexport interface PaceReport {\n  askedMs: number\n  gestureMs: number\n  wallMs: number\n  /** Wall time neither asked nor a gesture: what the page and the round trips cost. */\n  overheadMs: number\n  overheadPct: number\n  /** The steps whose wall ran past their ask plus gesture by more than a third. */\n  slow: { step: number; do: string; askedMs: number; wallMs: number }[]\n}\n\n/** What a script asks of a step, in ms: the part of its wall time that is the author's. */\nexport function askedMs(step: {\n  do: string\n  ms?: number\n  text?: string\n  delayMs?: number\n}): number {\n  switch (step.do) {\n    case 'wait':\n      return step.ms ?? 0\n    case 'hover':\n      return step.ms ?? 700\n    case 'drag':\n      return step.ms ?? 700\n    case 'type':\n      return (step.text?.length ?? 0) * (step.delayMs ?? 40)\n    default:\n      return 0\n  }\n}\n\nexport function paceReport(steps: readonly StepPace[]): PaceReport {\n  const askedMs = steps.reduce((a, s) => a + s.askedMs, 0)\n  const gestureMs = steps.reduce((a, s) => a + s.gestureMs, 0)\n  const wallMs = steps.reduce((a, s) => a + s.wallMs, 0)\n  const overheadMs = Math.max(0, wallMs - askedMs - gestureMs)\n  const slow = steps\n    .filter((s) => s.wallMs > (s.askedMs + s.gestureMs) * 1.34 + 60)\n    .map((s) => ({\n      step: s.step,\n      do: s.do,\n      askedMs: s.askedMs,\n      wallMs: s.wallMs,\n    }))\n  return {\n    askedMs,\n    gestureMs,\n    wallMs,\n    overheadMs,\n    overheadPct: wallMs > 0 ? Math.round((overheadMs / wallMs) * 100) : 0,\n    slow,\n  }\n}\n\n/** The pace in one line for the log. */\nexport function paceLine(r: PaceReport): string {\n  const s = (ms: number) => `${(ms / 1000).toFixed(1)} s`\n  const slow = r.slow.length\n    ? `; slow: ${r.slow.map((x) => `#${x.step} ${x.do} ${s(x.wallMs)} for ${s(x.askedMs)} asked`).join(', ')}`\n    : ''\n  return `pace: the script asked ${s(r.askedMs)}, the gestures added ${s(r.gestureMs)}, the take ran ${s(r.wallMs)} (${r.overheadPct} % overhead${slow})`\n}\n"],"mappings":"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","names":["askedMs"]}

package/dist/{chunk-7RMULTDM.js → chunk-WCSAECM4.js}

@@ -6,6 +6,19 @@ import {
   noteGivenFlag,
   trackFlags
 } from "./chunk-FACYY7VV.js";
+import {
+  PRESS_HOLD_MS,
+  PRESS_LEAD_MS,
+  SCROLL_SETTLE_MS,
+  TRAILING_HOLD_MS,
+  askedMs,
+  clockMotion,
+  clockTyping,
+  paceLine,
+  paceReport,
+  pointerTravelMs,
+  settleMs
+} from "./chunk-RDQYYRWN.js";
 
 // src/plugin/run.ts
 import { mkdir as mkdir10, readFile as readFile15, rm as rm5 } from "fs/promises";
@@ -101,8 +114,137 @@ function createReporter(json) {
   };
 }
 
+// src/plugin/setup.ts
+var VERBS = /* @__PURE__ */ new Set(["wait", "click", "type", "press", "goto"]);
+function validateSetup(value) {
+  const errors = [];
+  if (!Array.isArray(value)) return ["setup must be an array of steps"];
+  value.forEach((raw, i) => {
+    const at2 = `setup[${i}]`;
+    if (typeof raw !== "object" || raw === null) {
+      errors.push(`${at2}: must be an object`);
+      return;
+    }
+    const s = raw;
+    if (typeof s.do !== "string" || !VERBS.has(s.do)) {
+      errors.push(`${at2}: "do" must be one of ${[...VERBS].join(", ")}`);
+      return;
+    }
+    if ((s.do === "click" || s.do === "type") && typeof s.selector !== "string")
+      errors.push(`${at2}: ${s.do} needs a selector`);
+    if (s.do === "wait" && typeof s.ms !== "number")
+      errors.push(`${at2}: wait needs ms`);
+    if (s.do === "press" && typeof s.key !== "string")
+      errors.push(`${at2}: press needs a key`);
+    if (s.do === "goto" && typeof s.url !== "string")
+      errors.push(`${at2}: goto needs a url`);
+    if (s.do === "type") {
+      const t = s.text;
+      const isEnv = typeof t === "object" && t !== null && typeof t.env === "string" && Object.keys(t).length === 1;
+      if (typeof t !== "string" && !isEnv)
+        errors.push(
+          `${at2}: type needs text, a string or { "env": "NAME" } read at run time`
+        );
+      if (typeof t === "string" && /passw|secret|token/i.test(String(s.selector)) && t.length > 0)
+        errors.push(
+          `${at2}: a literal value typed into ${String(s.selector)} would live in actions.json, which is committed and pushed. Use { "env": "NAME" }`
+        );
+    }
+  });
+  return errors;
+}
+function resolveSetupText(t, env = process.env) {
+  if (typeof t === "string") return { value: t, secret: false };
+  const v = env[t.env];
+  if (v === void 0 || v === "")
+    throw new SetupEnvError(
+      `setup: the environment variable ${t.env} is not set, and a type step reads it. Export it in the shell that runs vos record; it is never written to a file`
+    );
+  return { value: v, secret: true };
+}
+async function runSetup(page, steps, opts) {
+  const lines = [];
+  for (const [i, step] of steps.entries()) {
+    const settle = "ms" in step && typeof step.ms === "number" ? step.ms : 150;
+    try {
+      switch (step.do) {
+        case "wait":
+          await opts.sleep(step.ms);
+          lines.push(`setup #${i} wait ${step.ms}ms`);
+          break;
+        case "goto":
+          await page.goto(step.url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
+          });
+          lines.push(`setup #${i} goto ${step.url}`);
+          break;
+        case "press":
+          await page.keyboard.press(step.key);
+          await opts.sleep(settle);
+          lines.push(`setup #${i} press ${step.key}`);
+          break;
+        case "click": {
+          const loc = page.locator(step.selector).first();
+          await loc.waitFor({ state: "visible", timeout: 8e3 });
+          await loc.click();
+          await opts.sleep(settle);
+          lines.push(`setup #${i} click ${step.selector}`);
+          break;
+        }
+        case "type": {
+          const loc = page.locator(step.selector).first();
+          await loc.waitFor({ state: "visible", timeout: 8e3 });
+          const { value, secret } = resolveSetupText(step.text, opts.env);
+          await loc.fill(value);
+          await opts.sleep(settle);
+          lines.push(
+            `setup #${i} type ${secret ? `\${${step.text.env}}` : `${value.length} chars`} into ${step.selector}`
+          );
+          break;
+        }
+      }
+    } catch (e) {
+      if (e instanceof SetupEnvError) throw e;
+      return {
+        ran: i,
+        lines,
+        failed: {
+          step: i,
+          do: step.do,
+          ..."selector" in step ? { selector: step.selector } : {}
+        }
+      };
+    }
+  }
+  return { ran: steps.length, lines };
+}
+var SetupEnvError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SetupEnvError";
+  }
+};
+var SetupError = class extends Error {
+  constructor(failed2) {
+    super(
+      `setup #${failed2.step} ${failed2.do}${failed2.selector ? ` ${failed2.selector}` : ""}: the selector never appeared, so the take would begin at a half-finished setup. Nothing was recorded. Fix the setup step (rehearse with --dry-run), then record.`
+    );
+    this.failed = failed2;
+    this.name = "SetupError";
+  }
+  failed;
+};
+function parseHeaders(given) {
+  const out = {};
+  for (const h of given ?? []) {
+    const i = h.indexOf("=");
+    if (i <= 0) throw new Error(`--header wants name=value, got "${h}"`);
+    out[h.slice(0, i).trim()] = h.slice(i + 1);
+  }
+  return out;
+}
+
 // src/plugin/actions.ts
-var VERBS = /* @__PURE__ */ new Set([
+var VERBS2 = /* @__PURE__ */ new Set([
   "wait",
   "hover",
   "click",
@@ -129,6 +271,7 @@ function validateActions(value) {
       }
     }
   }
+  if (obj.setup !== void 0) errors.push(...validateSetup(obj.setup));
   if (obj.mask !== void 0) {
     if (!Array.isArray(obj.mask)) {
       errors.push("mask must be an array of { selector, as?, text? }");
@@ -159,8 +302,8 @@ function validateActions(value) {
       return;
     }
     const s = raw;
-    if (typeof s.do !== "string" || !VERBS.has(s.do)) {
-      errors.push(`${at2}: "do" must be one of ${[...VERBS].join(", ")}`);
+    if (typeof s.do !== "string" || !VERBS2.has(s.do)) {
+      errors.push(`${at2}: "do" must be one of ${[...VERBS2].join(", ")}`);
       return;
     }
     if (s.id !== void 0) {
@@ -6556,97 +6699,6 @@ function cappedLine(capSeconds) {
   return `stopped at ${formatDurationCap(capSeconds)} (--max-duration ${capSeconds}); the remaining steps did not run`;
 }
 
-// src/plugin/pace.ts
-var POINTER_MS_PER_PX = 0.7;
-var POINTER_MIN_MS = 250;
-var POINTER_MAX_MS = 800;
-var MOTION_TICK_MS = 16;
-var SETTLE_MS = {
-  click: 150,
-  type: 150,
-  scroll: 200,
-  drag: 80
-};
-var PRESS_LEAD_MS = 80;
-var PRESS_HOLD_MS = 70;
-var SCROLL_SETTLE_MS = 120;
-var TRAILING_HOLD_MS = 400;
-function pointerTravelMs(dist) {
-  return Math.min(
-    POINTER_MAX_MS,
-    Math.max(POINTER_MIN_MS, Math.round(dist * POINTER_MS_PER_PX))
-  );
-}
-function settleMs(step) {
-  if (typeof step.ms === "number" && step.ms >= 0) return step.ms;
-  const d = step.do;
-  return SETTLE_MS[d] ?? 0;
-}
-var easeInOutCubic = (u) => u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2;
-async function clockMotion(dur, at2, clock) {
-  const start = clock.now();
-  let samples = 0;
-  for (; ; ) {
-    const elapsed = clock.now() - start;
-    if (elapsed >= dur) break;
-    await at2(easeInOutCubic(Math.min(1, elapsed / dur)));
-    samples++;
-    const next = start + Math.ceil((clock.now() - start) / MOTION_TICK_MS) * MOTION_TICK_MS;
-    const wait2 = Math.min(next, start + dur) - clock.now();
-    if (wait2 > 0) await clock.sleep(wait2);
-  }
-  await at2(1);
-  return samples + 1;
-}
-async function clockTyping(chars, delay, type, clock) {
-  const start = clock.now();
-  for (let i = 0; i < chars.length; i++) {
-    await type(chars[i], i);
-    const due = start + (i + 1) * delay;
-    const wait2 = due - clock.now();
-    if (wait2 > 0 && i < chars.length - 1) await clock.sleep(wait2);
-  }
-}
-function askedMs(step) {
-  switch (step.do) {
-    case "wait":
-      return step.ms ?? 0;
-    case "hover":
-      return step.ms ?? 700;
-    case "drag":
-      return step.ms ?? 700;
-    case "type":
-      return (step.text?.length ?? 0) * (step.delayMs ?? 40);
-    default:
-      return 0;
-  }
-}
-function paceReport(steps) {
-  const askedMs2 = steps.reduce((a, s) => a + s.askedMs, 0);
-  const gestureMs = steps.reduce((a, s) => a + s.gestureMs, 0);
-  const wallMs = steps.reduce((a, s) => a + s.wallMs, 0);
-  const overheadMs = Math.max(0, wallMs - askedMs2 - gestureMs);
-  const slow = steps.filter((s) => s.wallMs > (s.askedMs + s.gestureMs) * 1.34 + 60).map((s) => ({
-    step: s.step,
-    do: s.do,
-    askedMs: s.askedMs,
-    wallMs: s.wallMs
-  }));
-  return {
-    askedMs: askedMs2,
-    gestureMs,
-    wallMs,
-    overheadMs,
-    overheadPct: wallMs > 0 ? Math.round(overheadMs / wallMs * 100) : 0,
-    slow
-  };
-}
-function paceLine(r) {
-  const s = (ms) => `${(ms / 1e3).toFixed(1)} s`;
-  const slow = r.slow.length ? `; slow: ${r.slow.map((x) => `#${x.step} ${x.do} ${s(x.wallMs)} for ${s(x.askedMs)} asked`).join(", ")}` : "";
-  return `pace: the script asked ${s(r.askedMs)}, the gestures added ${s(r.gestureMs)}, the take ran ${s(r.wallMs)} (${r.overheadPct} % overhead${slow})`;
-}
-
 // src/plugin/wall.ts
 var IDP_HOSTS = [
   "accounts.google.com",
@@ -6994,7 +7046,8 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   const context = await browser.newContext({
     viewport: { width: vw, height: vh },
     deviceScaleFactor: 1,
-    ...opts.storageState ? { storageState: opts.storageState } : {}
+    ...opts.storageState ? { storageState: opts.storageState } : {},
+    ...opts.headers && Object.keys(opts.headers).length ? { extraHTTPHeaders: opts.headers } : {}
   });
   const masks = actions.mask ?? [];
   if (masks.length) await context.addInitScript(maskInitScript(masks));
@@ -7009,12 +7062,26 @@ async function recordTake(browser, url, actions, paths, log, opts = {}) {
   });
   log(`goto ${url}`);
   let navTimeout = false;
-  const response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
+  let response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => {
     navTimeout = true;
     log("   (networkidle timeout \u2014 continuing)");
     return null;
   });
   await sleep(800);
+  const setup = actions.setup ?? [];
+  if (setup.length) {
+    log(`setup: ${setup.length} step(s), off camera`);
+    const result = await runSetup(page, setup, { sleep: realSleep });
+    for (const line of result.lines) log(`   ${line}`);
+    if (result.failed) {
+      await context.close().catch(() => {
+      });
+      throw new SetupError(result.failed);
+    }
+    log(`goto ${url} (after setup)`);
+    response = await page.goto(url, { waitUntil: "networkidle", timeout: 45e3 }).catch(() => null);
+    await sleep(800);
+  }
   let wall = null;
   if (opts.onArrival) {
     const seen = await page.evaluate(WALL_PROBE).catch(() => null);
@@ -10443,9 +10510,10 @@ function convertAgentBrowser(records, opts = {}) {
 async function cmdActions(argv) {
   const { positionals, flags } = parseArgs(argv, /* @__PURE__ */ new Set(["json"]));
   const [sub, input] = positionals;
+  if (sub === "script" && input) return cmdActionsScript(input, flags);
   if (sub !== "from-agent-browser" || !input) {
     throw new UsageError(
-      "vos actions from-agent-browser <steps.jsonl> [--out actions.json] [--url <url>] [--viewport WxH] [--json]"
+      "vos actions from-agent-browser <steps.jsonl> [--out actions.json] [--url <url>] [--viewport WxH] [--json]\n       vos actions script <actions.json> [--json]"
     );
   }
   const r = createReporter(flags.json === true);
@@ -10493,6 +10561,18 @@ function summary(result) {
     notes: result.notes
   };
 }
+async function cmdActionsScript(input, flags) {
+  const r = createReporter(flags.json === true);
+  const { readFile: readFile16 } = await import("fs/promises");
+  const { shotList, formatShotList } = await import("./shotList-FYDHO5AI.js");
+  const raw = JSON.parse(await readFile16(resolve8(input), "utf8"));
+  const errors = validateActions(raw);
+  if (errors.length) throw new UsageError(`${input}:
+  ${errors.join("\n  ")}`);
+  const list = shotList(raw);
+  r.done({ ...list, text: formatShotList(list) }, formatShotList(list));
+  return EXIT_OK;
+}
 
 // src/plugin/run.ts
 var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
@@ -10518,12 +10598,12 @@ var BOOLEAN_FLAGS5 = /* @__PURE__ */ new Set([
   "dry-run",
   "allow-wall"
 ]);
-var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg"]);
+var MULTI_FLAGS2 = /* @__PURE__ */ new Set(["set", "override", "browser-arg", "header"]);
 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] [--allow-wall] [--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] [--dry-run] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--browser-arg=<switch>]... [--background <slug|url|none>] [--json]
+  vos create --actions actions.json [--url <url>] [--out take] [out.webm] [--strict] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--header name=value]... [--browser-arg=<switch>]... [--background <slug|url|none>] [render flags] [--json]
+  vos record --actions actions.json [--url <url>] [--out take] [--strict] [--dry-run] [--allow-wall] [--keep-frames] [--max-duration <s>] [--storage-state <file>] [--header name=value]... [--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]
@@ -10535,6 +10615,8 @@ Take pipeline
   vos validate <actions.json|take|kit.json> [--picture] [--json]
   vos judge <kit.json> --against <MANIFEST.json> [--out dir] [--json]
   vos actions from-agent-browser <steps.jsonl> [--out actions.json] [--url <url>] [--viewport WxH] [--json]
+  vos actions script <actions.json> [--json]
+            the flow as numbered beats in words, for a person recording it by hand
 
 Platform (vos.so) \u2014 fetch, edit, push, pull, repeat
   vos login [--key <vos_sk_\u2026>] [--label <name>] [--no-browser]
@@ -10816,6 +10898,13 @@ function exposureNote(rec) {
 ${rec.exposures.map((e) => `    - ${exposureLine(e)}`).join("\n")}
   ${EXPOSURE_ADVICE}`;
 }
+function takeHeaders(multi) {
+  try {
+    return parseHeaders(multi.header);
+  } catch (e) {
+    throw new UsageError(e instanceof Error ? e.message : String(e));
+  }
+}
 function takeBrowserArgs(multi) {
   const given = multi["browser-arg"];
   return (given ?? []).filter(Boolean);
@@ -10886,6 +10975,7 @@ async function cmdRecord(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  const headers = takeHeaders(multi);
   if (flags["dry-run"] === true) {
     void flags.strict;
     void flags["keep-frames"];
@@ -10902,6 +10992,7 @@ async function cmdRecord(argv) {
         r.log,
         {
           storageState,
+          headers,
           dryRun: true,
           // A rehearsal is always strict, and it touches no directory.
           onArrival: wallGate(flags, r, { strict: true })
@@ -10917,6 +11008,7 @@ async function cmdRecord(argv) {
       const carried = [
         ...strFlag(flags, "storage-state") ? [`--storage-state ${strFlag(flags, "storage-state")}`] : [],
         ...browserArgs.map((a) => `--browser-arg=${a}`),
+        ...Object.entries(headers).map(([k, v]) => `--header ${k}=${v}`),
         ...flags["allow-wall"] === true ? ["--allow-wall"] : []
       ].join(" ");
       const nextOut = strFlag(flags, "out") ?? "take";
@@ -10958,6 +11050,7 @@ ${lines.join("\n")}
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
       storageState,
+      headers,
       onArrival: wallGate(flags, r, {
         strict: flags.strict === true,
         prepare
@@ -11038,6 +11131,7 @@ async function cmdCreate2(argv) {
   const maxDurationSeconds = await maxDuration(flags, r);
   const storageState = takeStorageState(flags);
   const browserArgs = takeBrowserArgs(multi);
+  const headers = takeHeaders(multi);
   const paths = takePaths(outDir);
   const prepare = async () => {
     if (existsSync15(join18(outDir, "meta.json"))) {
@@ -11056,6 +11150,7 @@ async function cmdCreate2(argv) {
     const rec = await recordTake(browser, url, actions, paths, r.log, {
       maxDurationSeconds,
       storageState,
+      headers,
       onArrival: wallGate(flags, r, {
         strict: flags.strict === true,
         prepare
@@ -12196,6 +12291,11 @@ async function run(argv) {
   } catch (e) {
     if (e instanceof UsageError) {
       process.stderr.write(`usage error: ${e.message}
+`);
+      return EXIT_USAGE;
+    }
+    if (e instanceof SetupError || e instanceof SetupEnvError) {
+      process.stderr.write(`${e.message}
 `);
       return EXIT_USAGE;
     }
@@ -12248,4 +12348,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-7RMULTDM.js.map
+//# sourceMappingURL=chunk-WCSAECM4.js.map