@vosjs/cli 0.43.0 → 0.45.0

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/cli.js

@@ -511,7 +511,7 @@ async function cmdCheck(argv) {
   return result.ok ? EXIT_OK : EXIT_ERROR;
 }
 async function delegate(argv, viaAlias = false) {
-  const { run } = await import("./run-ZYROWQ3T.js");
+  const { run } = await import("./run-3TY74GWE.js");
   if (viaAlias && argv[0]) {
     process.stderr.write(
       `note: "vos voila ${argv[0]}" is now "vos ${argv[0]}".
@@ -551,7 +551,7 @@ async function main() {
     const engine = HELP_ENGINE.split("\n").filter(
       (l) => l.startsWith(`  vos ${cmd} `)
     );
-    const { verbHelp } = await import("./run-ZYROWQ3T.js");
+    const { verbHelp } = await import("./run-3TY74GWE.js");
     const take = verbHelp(cmd);
     process.stdout.write(
       `${engine.join("\n")}
@@ -583,7 +583,7 @@ ${take.includes("no such verb") ? "" : take}`
 main().then(async (code) => {
   if (code === EXIT_OK) {
     const verb = process.argv[2] ?? "";
-    const { HELP } = await import("./run-ZYROWQ3T.js");
+    const { HELP } = await import("./run-3TY74GWE.js");
     const documented = [
       ...helpFlagsFor(HELP_ENGINE, verb),
       ...helpFlagsFor(HELP, verb)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Browser, Page } from 'playwright';
+import { Browser, BrowserContext, Page } from 'playwright';
 import { CursorTrack, RecordingMeta, ProjectDoc, CursorEvent, TemplateAnchor, Backdrop, LayoutParts, TranscriptSegment, Digest } from '@vosjs/studio-core';
 export { Digest } from '@vosjs/studio-core';
 
@@ -276,6 +276,12 @@ type ActionStep = ({
      * edits without breaking the cut anchored to it. Unique when present.
      */
     id?: string;
+    /**
+     * A beat's caption, two to eight words: `vos deliver` lands it as a
+     * lower-third at this step's moment on the cuts that take words, and
+     * `vos actions script` leads the beat with it.
+     */
+    caption?: string;
 };
 /** Structural validation with actionable messages. Returns [] when valid. */
 declare function validateActions(value: unknown): string[];
@@ -428,6 +434,12 @@ interface RecordOpts {
     onArrival?: (arrival: Arrival) => Promise<WallVerdict | null | void> | WallVerdict | null | void;
     /** Extra request headers on every request (`--header name=value`). */
     headers?: Record<string, string>;
+    /**
+     * A ready-made context to record IN, instead of one made from `browser`:
+     * `--session <name>`, a persistent profile the person signed in to. The
+     * recorder still sizes the viewport and closes it at the end.
+     */
+    context?: BrowserContext;
 }
 declare function recordTake(browser: Browser, url: string, actions: ActionsFile, paths: TakePaths, log: (msg: string) => void, opts?: RecordOpts): Promise<RecordResult>;
 

package/dist/index.js

@@ -30,13 +30,14 @@ import {
   validateActions,
   waitForPageDone,
   writeSyncState
-} from "./chunk-6PJPGBKH.js";
+} from "./chunk-JRRM7P5G.js";
 import {
   BrowserUnavailableError,
   configDuration,
   launchBrowser,
   loadVosConfig
 } from "./chunk-FACYY7VV.js";
+import "./chunk-RDQYYRWN.js";
 import {
   manifest
 } from "./chunk-EFI3WUQB.js";

package/dist/{run-ZYROWQ3T.js → run-3TY74GWE.js}

@@ -5,8 +5,9 @@ import {
   run,
   takeBrowserArgs,
   verbHelp
-} from "./chunk-6PJPGBKH.js";
+} from "./chunk-JRRM7P5G.js";
 import "./chunk-FACYY7VV.js";
+import "./chunk-RDQYYRWN.js";
 export {
   HELP,
   MULTI_FLAGS,
@@ -14,4 +15,4 @@ export {
   takeBrowserArgs,
   verbHelp
 };
-//# sourceMappingURL=run-ZYROWQ3T.js.map
+//# sourceMappingURL=run-3TY74GWE.js.map

package/dist/shotList-FYDHO5AI.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import {
+  askedMs
+} from "./chunk-RDQYYRWN.js";
+
+// src/plugin/shotList.ts
+function sayTarget(selector) {
+  const text = /^text=(['"]?)(.+?)\1$/.exec(selector);
+  if (text) return `"${text[2]}"`;
+  const has = /:has-text\((['"])(.+?)\1\)/.exec(selector);
+  if (has) return `"${has[2]}"`;
+  const role = /getByRole\(['"](\w+)['"],\s*\{\s*name:\s*(['"])(.+?)\2/.exec(
+    selector
+  );
+  if (role) return `the ${role[1]} "${role[3]}"`;
+  const label = /\[aria-label=(['"])(.+?)\1\]/.exec(selector);
+  if (label) return `"${label[2]}"`;
+  const ph = /\[placeholder=(['"])(.+?)\1\]/.exec(selector);
+  if (ph) return `the "${ph[2]}" field`;
+  return `\`${selector}\``;
+}
+var s1 = (ms) => `${Math.round(ms / 100) / 10}`.replace(/\.0$/, "");
+function sayId(id) {
+  if (!id || /^\d+$/.test(id) || id.length < 3) return null;
+  const words = id.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").toLowerCase().trim();
+  return words.length >= 3 ? words : null;
+}
+function sayStepTarget(step) {
+  const bySelector = sayTarget(step.selector);
+  if (!bySelector.startsWith("`")) return bySelector;
+  const byId = sayId(step.id);
+  return byId ? `${byId} (${bySelector})` : bySelector;
+}
+function beatOf(step) {
+  const cap = step.caption;
+  const named = cap ? `${cap}: ` : "";
+  switch (step.do) {
+    case "wait":
+      return null;
+    case "hover":
+      return `${named}Rest the pointer on ${sayStepTarget(step)}`;
+    case "click":
+      return `${named}Click ${sayStepTarget(step)}`;
+    case "type":
+      return `${named}Type "${step.text}" into ${sayStepTarget(step)}`;
+    case "scroll":
+      return `${named}Scroll ${step.dy < 0 ? "up" : "down"} ${step.dy < 0 ? "a little" : "a little"}`;
+    case "move":
+      return `${named}Move the pointer to the ${step.y < 360 ? "upper" : "lower"} ${step.x < 640 ? "left" : "right"}`;
+    case "drag":
+      return `${named}Drag ${step.selector ? sayStepTarget(step) : "from the start point"} across`;
+  }
+}
+function shotList(actions) {
+  const beats = [];
+  let pendingHold = 0;
+  let total = 0;
+  for (const step of actions.steps) {
+    total += askedMs(step);
+    if (step.do === "wait") {
+      if (beats.length) {
+        const last = beats[beats.length - 1];
+        last.holdS = (last.holdS ?? 0) + step.ms / 1e3;
+      } else pendingHold += step.ms;
+      continue;
+    }
+    const line = beatOf(step);
+    if (!line) continue;
+    const beat = { n: beats.length + 1, line };
+    if (step.do === "hover") beat.holdS = askedMs(step) / 1e3;
+    beats.push(beat);
+  }
+  void pendingHold;
+  return {
+    url: actions.url,
+    viewport: actions.viewport,
+    beats,
+    // gestures the recorder adds around each ask: about a second a beat
+    aboutS: Math.round((total + beats.length * 1e3) / 1e3),
+    setup: actions.setup?.length ?? 0
+  };
+}
+function formatShotList(list) {
+  const out = [];
+  out.push(
+    `Record this with the vosso extension in your own signed-in browser, about ${list.aboutS} seconds${list.viewport ? `, window about ${list.viewport.width}\xD7${list.viewport.height}` : ""}.`
+  );
+  if (list.url)
+    out.push(`Start on ${list.url}, signed in, with the page settled.`);
+  if (list.setup)
+    out.push(
+      `Before you press record: the script's ${list.setup} setup step${list.setup === 1 ? "" : "s"} (sign in, dismiss banners) are yours to do first; they are not part of the take.`
+    );
+  out.push("");
+  for (const b of list.beats) {
+    const hold = b.holdS && b.holdS >= 0.4 ? ` Hold ${s1(b.holdS * 1e3)} s.` : "";
+    out.push(`${b.n}. ${b.line}.${hold}`);
+  }
+  out.push("");
+  out.push(
+    "Move at a talking pace, let each screen settle before the next beat, and end on the finished state. Press the icon again to stop; the take opens in the studio and saves to your shelf."
+  );
+  return out.join("\n");
+}
+export {
+  formatShotList,
+  sayId,
+  sayTarget,
+  shotList
+};
+//# sourceMappingURL=shotList-FYDHO5AI.js.map

package/dist/shotList-FYDHO5AI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/plugin/shotList.ts"],"sourcesContent":["/**\n * The shot list: an `actions.json` said in words, for a person who will\n * record it by hand. The last rung of the session ladder is \"the human\n * records, the agent cuts\", and an agent that falls to it should hand over\n * more than an apology: the flow it worked out, as numbered beats with the\n * pace it wanted, so its knowledge survives the hop to a human. The take\n * comes back through the ordinary handoff and the agent cuts it.\n *\n * Pure: an ActionsFile in, lines out. Selectors are said as what they name\n * where the script says (an id, a caption, a text= locator), and as the\n * selector itself where it does not: a person reading `#filter-late` can\n * find it; a person reading nothing cannot.\n */\nimport type { ActionStep, ActionsFile } from './actions'\nimport { askedMs } from './pace'\n\nexport interface ShotBeat {\n  n: number\n  /** what to do, in words */\n  line: string\n  /** how long to hold after, in seconds, when the script asks for a hold */\n  holdS?: number\n}\n\nexport interface ShotList {\n  url?: string\n  viewport?: { width: number; height: number }\n  beats: ShotBeat[]\n  /** the take's asked length, from the script's own pacing */\n  aboutS: number\n  setup: number\n}\n\n/** A selector as a person reads it: the text it names, or the selector itself. */\nexport function sayTarget(selector: string): string {\n  const text = /^text=(['\"]?)(.+?)\\1$/.exec(selector)\n  if (text) return `\"${text[2]}\"`\n  const has = /:has-text\\((['\"])(.+?)\\1\\)/.exec(selector)\n  if (has) return `\"${has[2]}\"`\n  const role = /getByRole\\(['\"](\\w+)['\"],\\s*\\{\\s*name:\\s*(['\"])(.+?)\\2/.exec(\n    selector,\n  )\n  if (role) return `the ${role[1]} \"${role[3]}\"`\n  const label = /\\[aria-label=(['\"])(.+?)\\1\\]/.exec(selector)\n  if (label) return `\"${label[2]}\"`\n  const ph = /\\[placeholder=(['\"])(.+?)\\1\\]/.exec(selector)\n  if (ph) return `the \"${ph[2]}\" field`\n  return `\\`${selector}\\``\n}\n\nconst s1 = (ms: number) => `${Math.round(ms / 100) / 10}`.replace(/\\.0$/, '')\n\n/** A step's id, said as a name when it reads as one (`late`, `new-order`, `openBilling`). */\nexport function sayId(id: string | undefined): string | null {\n  if (!id || /^\\d+$/.test(id) || id.length < 3) return null\n  const words = id\n    .replace(/([a-z])([A-Z])/g, '$1 $2')\n    .replace(/[-_]+/g, ' ')\n    .toLowerCase()\n    .trim()\n  return words.length >= 3 ? words : null\n}\n\n/** What a step points at, for a person: the words the selector names, else the id's, else the selector. */\nfunction sayStepTarget(step: { selector: string; id?: string }): string {\n  const bySelector = sayTarget(step.selector)\n  if (!bySelector.startsWith('`')) return bySelector\n  const byId = sayId(step.id)\n  return byId ? `${byId} (${bySelector})` : bySelector\n}\n\nfunction beatOf(step: ActionStep): string | null {\n  const cap = step.caption\n  const named = cap ? `${cap}: ` : ''\n  switch (step.do) {\n    case 'wait':\n      return null\n    case 'hover':\n      return `${named}Rest the pointer on ${sayStepTarget(step)}`\n    case 'click':\n      return `${named}Click ${sayStepTarget(step)}`\n    case 'type':\n      return `${named}Type \"${step.text}\" into ${sayStepTarget(step)}`\n    case 'scroll':\n      return `${named}Scroll ${step.dy < 0 ? 'up' : 'down'} ${step.dy < 0 ? 'a little' : 'a little'}`\n    case 'move':\n      return `${named}Move the pointer to the ${step.y < 360 ? 'upper' : 'lower'} ${step.x < 640 ? 'left' : 'right'}`\n    case 'drag':\n      return `${named}Drag ${step.selector ? sayStepTarget(step as { selector: string; id?: string }) : 'from the start point'} across`\n  }\n}\n\nexport function shotList(actions: ActionsFile): ShotList {\n  const beats: ShotBeat[] = []\n  let pendingHold = 0\n  let total = 0\n  for (const step of actions.steps) {\n    total += askedMs(step)\n    if (step.do === 'wait') {\n      // A wait after a beat is that beat's hold; a leading wait is the\n      // settle before the first, which a person does without being told.\n      if (beats.length) {\n        const last = beats[beats.length - 1]\n        last.holdS = (last.holdS ?? 0) + step.ms / 1000\n      } else pendingHold += step.ms\n      continue\n    }\n    const line = beatOf(step)\n    if (!line) continue\n    const beat: ShotBeat = { n: beats.length + 1, line }\n    if (step.do === 'hover') beat.holdS = askedMs(step) / 1000\n    beats.push(beat)\n  }\n  void pendingHold\n  return {\n    url: actions.url,\n    viewport: actions.viewport,\n    beats,\n    // gestures the recorder adds around each ask: about a second a beat\n    aboutS: Math.round((total + beats.length * 1000) / 1000),\n    setup: actions.setup?.length ?? 0,\n  }\n}\n\n/** The list as the person reads it. */\nexport function formatShotList(list: ShotList): string {\n  const out: string[] = []\n  out.push(\n    `Record this with the vosso extension in your own signed-in browser, about ${list.aboutS} seconds${list.viewport ? `, window about ${list.viewport.width}×${list.viewport.height}` : ''}.`,\n  )\n  if (list.url)\n    out.push(`Start on ${list.url}, signed in, with the page settled.`)\n  if (list.setup)\n    out.push(\n      `Before you press record: the script's ${list.setup} setup step${list.setup === 1 ? '' : 's'} (sign in, dismiss banners) are yours to do first; they are not part of the take.`,\n    )\n  out.push('')\n  for (const b of list.beats) {\n    const hold =\n      b.holdS && b.holdS >= 0.4 ? ` Hold ${s1(b.holdS * 1000)} s.` : ''\n    out.push(`${b.n}. ${b.line}.${hold}`)\n  }\n  out.push('')\n  out.push(\n    'Move at a talking pace, let each screen settle before the next beat, and end on the finished state. Press the icon again to stop; the take opens in the studio and saves to your shelf.',\n  )\n  return out.join('\\n')\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vosjs/cli",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "The vos CLI: record the real product from a scripted browser flow, auto-zoom from the cursor track, cut as data in doc.json, render deterministic video and stills, deliver a release's media per destination spec, and sync with vos.so. One binary, every verb, MIT.",
   "type": "module",
   "license": "MIT",
@@ -54,8 +54,8 @@
     "@vosjs/render-core": "^0.2.8",
     "@vosjs/shared": "^0.4.1",
     "@vosjs/studio-core": "^0.29.0",
-    "@vosjs/timeline": "^0.4.1",
-    "@vosjs/tween": "^0.8.2"
+    "@vosjs/tween": "^0.8.2",
+    "@vosjs/timeline": "^0.4.1"
   },
   "devDependencies": {
     "@types/node": "^22",