@vosjs/cli 0.37.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.
@@ -167,7 +170,7 @@ Verified the flow in agent-browser already? `vos actions from-agent-browser step
 
 **Text overlays.** `doc.overlays`: screen-space clips above the card, outside the zoom, output-anchored. `{ "id": "t0", "kind": "text", "start": 1, "duration": 3, "text": "Ship it", "preset": "title", "transform": { "x": 0.5, "y": 0.82, "scale": 1, "rotation": 0 }, "enter": "rise", "exit": "fade" }`. Presets `title`, `caption`, `label`, overridable with `size` (12..200 design px) and `color`; `\n` breaks lines; a caption (a layer with no referent) is a lower third at `y` ≈ 0.82. Enter and exit: `rise`, `fade`, `none`. Fonts load at render start, fail-open to system stacks.
 
-**Callouts in the grammar.** `vos callout <take> note --step copy --kicker "index.css" --title "Every token you tuned, as CSS variables." --mark ring` writes a callout in the house grammar (three shapes a viewer learns once: `note`, a kicker, a title and a line; `tag`, one label on the accent; `code`, the payload block) from the product's REGISTER: `BRAND.md` beside the take (`bgA` the ground, `accent`, `fontBody`) or `--ground #hex --accent #hex --font "…" --body-px 14`. The card inverts the app's value in the product's hue (a light app gets a dark card, a dark app a light one), keeps the accent for the kicker, sets its title at 1.35× the app's body AS SEEN ON SCREEN at the layer's start (the camera's level is read from the document), lifts on a real shadow and a hairline, rises in and fades out, opens a beat after the step's press lands and closes before the next scroll or navigation, and is pinned to the step (`--side`, `--mark`, `--leader`, `--color` refine the pin). `--at <s> --seconds <n>` places one without a step; `--print` prints the clip instead of writing it. `vos validate <take> --picture` renders the footage under every html layer at its start and reports the ΔE between the card's ground and what it covers: under 8 is a problem (the card reads as one more panel), under 16 a warning. An unpinned html or media layer whose window holds a step with an element gets the pin named in a warning.
+**Callouts in the grammar.** `vos callout <take> note --step copy --kicker "index.css" --title "Every token you tuned, as CSS variables." --mark ring` writes a callout in the house grammar (three shapes a viewer learns once: `note`, a kicker, a title and a line; `tag`, one label on the accent; `code`, the payload block) from the product's REGISTER: `BRAND.md` beside the take (`bgA` the ground, `accent`, `fontBody`; a kit whose accent is RESERVED, a recorder's red that marks time and nothing else, names a `callout` role and the notes speak in that hue instead) or `--ground #hex --accent #hex --font "…"`. The card inverts the app's value in the product's hue (a light app gets a dark card, a dark app a light one), keeps the accent for the kicker, sets its title at 1.35× the app's body AS SEEN ON SCREEN at the layer's start (the camera's level is read from the document; `--body-px <n>` instead sets the body size on the DELIVERED frame and is never rescaled, which is the flag a rich capture needs, since a 2560-wide take on a padded frame sits near scale 0.6 and lands every default on the grammar's floor; the verb prints the three sizes and the scale it measured), lifts on a real shadow and a hairline, rises in and fades out, opens a beat after the step's press lands and closes before the next scroll or navigation, and is pinned to the step (`--side`, `--mark`, `--leader`, `--color` refine the pin; `--color` paints the mark and the leader, never the kicker, which is the accent). `--at <s> --seconds <n>` places one without a step; `--print` prints the clip instead of writing it. `vos validate <take> --picture` renders the footage under every html layer at its start and reports the ΔE between the card's ground and what it covers: under 8 is a problem (the card reads as one more panel), under 16 a warning. An unpinned html or media layer whose window holds a step with an element gets the pin named in a warning.
 
 **Pinned layers.** A layer ABOUT something on the page names it, and the lowering keeps the two together: `"pin": { "step": "copy", "side": "auto", "mark": "ring", "leader": true }` on any overlay kind places the layer a gap off one side of that step's element and carries it with the element as the camera moves (the layer keeps its screen size; only its place follows). One of `step` (a recorder step's `id`, else its index), `press` (SOURCE seconds; the nearest press names the element, for a human recording) or `rect` (video fractions) names the referent. `side` is `auto` (the first of right, left, below, above whose box fits inside the frame through the layer's life) or a side by name; `gap` is design px (24); `mark` is `ring` or `underline`, a standing highlight on the referent for the layer's life; `leader` draws a hairline from the layer to the referent; `color` is their ink. `transform.x/y` stay the fallback for a pin that cannot resolve, and `vos validate` says why (an unknown step, a step that touched nothing, a scroll inside the layer's window). A layer that cannot name its referent is a caption: place it in the margin, never over the app.
 

package/dist/{chunk-NHKHTIDR.js → chunk-FACYY7VV.js}

@@ -1,5 +1,91 @@
 #!/usr/bin/env node
 
+// src/flagUse.ts
+var given = /* @__PURE__ */ new Set();
+var used = /* @__PURE__ */ new Set();
+function trackFlags(bag) {
+  return new Proxy(bag, {
+    get(target, key, receiver) {
+      if (typeof key === "string") used.add(key);
+      return Reflect.get(target, key, receiver);
+    },
+    has(target, key) {
+      if (typeof key === "string") used.add(key);
+      return Reflect.has(target, key);
+    },
+    // hasOwnProperty.call(flags, name) lands here.
+    getOwnPropertyDescriptor(target, key) {
+      if (typeof key === "string") used.add(key);
+      return Reflect.getOwnPropertyDescriptor(target, key);
+    },
+    // A spread, Object.keys or JSON.stringify hands every flag onward; what
+    // happens to them after that cannot be seen, so they all count as read.
+    ownKeys(target) {
+      for (const key of Reflect.ownKeys(target))
+        if (typeof key === "string") used.add(key);
+      return Reflect.ownKeys(target);
+    }
+  });
+}
+function noteGivenFlag(name) {
+  given.add(name);
+}
+function unusedFlags() {
+  return [...given].filter((name) => !used.has(name) && name !== "help");
+}
+function helpFlagsFor(help, verb) {
+  const out = /* @__PURE__ */ new Set();
+  let inVerb = false;
+  for (const line of help.split("\n")) {
+    const head = /^\s{2}vos\s+(\S+)/.exec(line);
+    if (head) inVerb = head[1] === verb;
+    else if (!/^\s{3,}\S/.test(line)) inVerb = false;
+    if (!inVerb) continue;
+    for (const m of line.matchAll(/--([a-z][a-z0-9-]*)/g)) out.add(m[1]);
+  }
+  return [...out];
+}
+function editDistance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const keep = row[j];
+      row[j] = Math.min(
+        row[j] + 1,
+        row[j - 1] + 1,
+        prev + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+      prev = keep;
+    }
+  }
+  return row[b.length];
+}
+function nearestFlag(name, candidates) {
+  let best = null;
+  let bestScore = Infinity;
+  for (const c of candidates) {
+    if (c === name) continue;
+    const d = c.includes(name) || name.includes(c) ? 1 : editDistance(name, c);
+    if (d < bestScore) {
+      bestScore = d;
+      best = c;
+    }
+  }
+  return best !== null && bestScore <= Math.max(2, Math.floor(name.length / 3)) ? best : null;
+}
+function unusedFlagsMessage(verb, documented) {
+  const unused = unusedFlags();
+  if (!unused.length) return null;
+  const parts = unused.map((name) => {
+    const near = nearestFlag(name, documented);
+    return `--${name}${near ? ` (did you mean --${near}?)` : ""}`;
+  });
+  const list = documented.length ? ` It reads: ${documented.map((f) => `--${f}`).join(" ")}.` : "";
+  return `vos ${verb} RAN, and ignored ${parts.join(", ")}: ${unused.length > 1 ? "they are" : "it is"} not something this verb reads, so what it printed above was made without ${unused.length > 1 ? "them" : "it"}.${list}`;
+}
+
 // src/args.ts
 var UsageError = class extends Error {
 };
@@ -33,7 +119,8 @@ function parseArgs(argv, booleanFlags) {
     }
     positionals.push(arg);
   }
-  return { positionals, flags };
+  for (const name of Object.keys(flags)) noteGivenFlag(name);
+  return { positionals, flags: trackFlags(flags) };
 }
 function numFlag(flags, name, fallback) {
   const v = flags[name];
@@ -179,20 +266,21 @@ Fixes, in order of preference:
     );
   }
 };
-async function launchBrowser() {
+async function launchBrowser(args = []) {
+  const opts = args.length ? { args } : {};
   const explicit = process.env.VOS_BROWSER_PATH;
   if (explicit) {
-    return chromium.launch({ executablePath: explicit }).catch((e) => {
+    return chromium.launch({ ...opts, executablePath: explicit }).catch((e) => {
       throw new BrowserUnavailableError(
         `VOS_BROWSER_PATH failed: ${e.message}`
       );
     });
   }
   try {
-    return await chromium.launch({ channel: "chrome" });
+    return await chromium.launch({ ...opts, channel: "chrome" });
   } catch {
     try {
-      return await chromium.launch();
+      return await chromium.launch(opts);
     } catch (e) {
       throw new BrowserUnavailableError(
         e.message.split("\n")[0] ?? "unknown"
@@ -202,6 +290,10 @@ async function launchBrowser() {
 }
 
 export {
+  trackFlags,
+  noteGivenFlag,
+  helpFlagsFor,
+  unusedFlagsMessage,
   UsageError,
   parseArgs,
   numFlag,
@@ -213,4 +305,4 @@ export {
   BrowserUnavailableError,
   launchBrowser
 };
-//# sourceMappingURL=chunk-NHKHTIDR.js.map
+//# sourceMappingURL=chunk-FACYY7VV.js.map

package/dist/chunk-FACYY7VV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/flagUse.ts","../src/args.ts","../src/loadConfig.ts","../src/browser.ts"],"sourcesContent":["/**\n * Which of the flags a person gave did the verb actually READ?\n *\n * The parsers accept any `--name`, so a mistyped or misplaced flag used to be\n * swallowed: `vos frames <take> --at 3,5,8` wrote five evenly spread stills\n * and exited 0, because the flag is `--times` and nothing ever looked at\n * `at`. It looked like it worked.\n *\n * A declared list per verb would be the obvious guard and the wrong one here:\n * several verbs read their options through data (a name table, a helper three\n * calls down), so a list drifts, and the day it drifts it REFUSES a real flag\n * for every agent at once. Reading is the truth, so reading is what is\n * recorded: both parsers hand back their flags behind a proxy that notes each\n * name a verb asks for, and the CLI's one exit point compares that with what\n * was given. It cannot reject a flag a verb uses, by construction.\n *\n * The cost of being certain is that the verdict lands AFTER the verb ran, so\n * the message says so plainly: the command ran, without that flag.\n */\n\nconst given = new Set<string>()\nconst used = new Set<string>()\n\n/** A flag bag that remembers which names were asked for. */\nexport function trackFlags<T extends Record<string, unknown>>(bag: T): T {\n  return new Proxy(bag, {\n    get(target, key, receiver) {\n      if (typeof key === 'string') used.add(key)\n      return Reflect.get(target, key, receiver)\n    },\n    has(target, key) {\n      if (typeof key === 'string') used.add(key)\n      return Reflect.has(target, key)\n    },\n    // hasOwnProperty.call(flags, name) lands here.\n    getOwnPropertyDescriptor(target, key) {\n      if (typeof key === 'string') used.add(key)\n      return Reflect.getOwnPropertyDescriptor(target, key)\n    },\n    // A spread, Object.keys or JSON.stringify hands every flag onward; what\n    // happens to them after that cannot be seen, so they all count as read.\n    ownKeys(target) {\n      for (const key of Reflect.ownKeys(target))\n        if (typeof key === 'string') used.add(key)\n      return Reflect.ownKeys(target)\n    },\n  })\n}\n\nexport function noteGivenFlag(name: string): void {\n  given.add(name)\n}\n\n/** Flags that were given and never read, in the order they were given. */\nexport function unusedFlags(): string[] {\n  return [...given].filter((name) => !used.has(name) && name !== 'help')\n}\n\nexport function resetFlagUse(): void {\n  given.clear()\n  used.clear()\n}\n\n/**\n * The `--flags` a verb documents: its `vos <verb>` line in a help text plus\n * the indented lines that continue it.\n */\nexport function helpFlagsFor(help: string, verb: string): string[] {\n  const out = new Set<string>()\n  let inVerb = false\n  for (const line of help.split('\\n')) {\n    const head = /^\\s{2}vos\\s+(\\S+)/.exec(line)\n    if (head) inVerb = head[1] === verb\n    else if (!/^\\s{3,}\\S/.test(line)) inVerb = false\n    if (!inVerb) continue\n    for (const m of line.matchAll(/--([a-z][a-z0-9-]*)/g)) out.add(m[1])\n  }\n  return [...out]\n}\n\nfunction editDistance(a: string, b: string): number {\n  const row = Array.from({ length: b.length + 1 }, (_, i) => i)\n  for (let i = 1; i <= a.length; i++) {\n    let prev = row[0]\n    row[0] = i\n    for (let j = 1; j <= b.length; j++) {\n      const keep = row[j]\n      row[j] = Math.min(\n        row[j] + 1,\n        row[j - 1] + 1,\n        prev + (a[i - 1] === b[j - 1] ? 0 : 1),\n      )\n      prev = keep\n    }\n  }\n  return row[b.length]\n}\n\n/** The documented flag a mistyped one most likely meant, or null. */\nexport function nearestFlag(name: string, candidates: string[]): string | null {\n  let best: string | null = null\n  let bestScore = Infinity\n  for (const c of candidates) {\n    if (c === name) continue\n    // A candidate that contains the name (or the reverse) is as close as a\n    // one-letter slip: `--zooms` for `--at-zooms`, `--body` for `--body-px`.\n    const d = c.includes(name) || name.includes(c) ? 1 : editDistance(name, c)\n    if (d < bestScore) {\n      bestScore = d\n      best = c\n    }\n  }\n  return best !== null && bestScore <= Math.max(2, Math.floor(name.length / 3))\n    ? best\n    : null\n}\n\n/** The sentence for a run that ignored what it was given, or null when nothing was. */\nexport function unusedFlagsMessage(\n  verb: string,\n  documented: string[],\n): string | null {\n  const unused = unusedFlags()\n  if (!unused.length) return null\n  const parts = unused.map((name) => {\n    const near = nearestFlag(name, documented)\n    return `--${name}${near ? ` (did you mean --${near}?)` : ''}`\n  })\n  const list = documented.length\n    ? ` It reads: ${documented.map((f) => `--${f}`).join(' ')}.`\n    : ''\n  return `vos ${verb} RAN, and ignored ${parts.join(', ')}: ${unused.length > 1 ? 'they are' : 'it is'} not something this verb reads, so what it printed above was made without ${unused.length > 1 ? 'them' : 'it'}.${list}`\n}\n","/**\n * Minimal argv parser — positionals + `--flag value` / `--flag=value` /\n * boolean flags. Deliberately tiny: the CLI has a small, stable surface and\n * agents benefit from predictable, dependency-free parsing.\n */\nimport { noteGivenFlag, trackFlags } from './flagUse'\n\nexport interface ParsedArgs {\n  positionals: string[]\n  flags: Record<string, string | true>\n}\n\nexport class UsageError extends Error {}\n\nexport function parseArgs(\n  argv: string[],\n  booleanFlags: ReadonlySet<string>,\n): ParsedArgs {\n  const positionals: string[] = []\n  const flags: Record<string, string | true> = {}\n  for (let i = 0; i < argv.length; i++) {\n    const arg = argv[i]\n    if (arg === '--') {\n      positionals.push(...argv.slice(i + 1))\n      break\n    }\n    if (arg.startsWith('--')) {\n      const eq = arg.indexOf('=')\n      if (eq !== -1) {\n        flags[arg.slice(2, eq)] = arg.slice(eq + 1)\n        continue\n      }\n      const name = arg.slice(2)\n      if (booleanFlags.has(name)) {\n        flags[name] = true\n        continue\n      }\n      const next = argv[i + 1]\n      if (next === undefined || next.startsWith('--')) {\n        throw new UsageError(`--${name} expects a value`)\n      }\n      flags[name] = next\n      i++\n      continue\n    }\n    positionals.push(arg)\n  }\n  for (const name of Object.keys(flags)) noteGivenFlag(name)\n  return { positionals, flags: trackFlags(flags) }\n}\n\nexport function numFlag(\n  flags: ParsedArgs['flags'],\n  name: string,\n  fallback: number,\n): number {\n  const v = flags[name]\n  if (v === undefined) return fallback\n  const n = Number(v)\n  if (!Number.isFinite(n))\n    throw new UsageError(`--${name} expects a number, got \"${String(v)}\"`)\n  return n\n}\n","import { readFile } from 'node:fs/promises'\nimport { existsSync, readFileSync, statSync } from 'node:fs'\nimport { join } from 'node:path'\nimport {\n  CURRENT_CONFIG_VERSION,\n  migrateConfig,\n  vosConfigJsonSchema,\n} from '@vosjs/core'\nimport { UsageError } from './args'\n\nexport interface LoadedConfig {\n  config: Record<string, unknown>\n  warnings: string[]\n}\n\n/**\n * What a directory holds, by one deterministic sniff and never a flag:\n * a TAKE carries a recording document (`doc.json` with `source`); a PROGRAM\n * directory carries `config.json`, optionally beside a program document\n * (`doc.json` without `source`: the shared layers, the tween overlay, the\n * program's own length, with `program.config` omitted on disk). An unparsable\n * doc.json counts as a take so the take path reports the real error.\n */\nexport type DirectoryKind = 'take' | 'program' | 'none'\n\nexport function directoryKind(target: string): DirectoryKind {\n  try {\n    if (!statSync(target).isDirectory()) return 'none'\n  } catch {\n    return 'none'\n  }\n  const docPath = join(target, 'doc.json')\n  if (existsSync(docPath)) {\n    try {\n      const doc: unknown = JSON.parse(readFileSync(docPath, 'utf8'))\n      if (typeof doc === 'object' && doc !== null && 'source' in doc)\n        return 'take'\n    } catch {\n      return 'take'\n    }\n  }\n  return existsSync(join(target, 'config.json')) ? 'program' : 'none'\n}\n\n/**\n * A program directory's config: `config.json`, composed with the program\n * document beside it when there is one (the layers ride as the studio stack\n * entry, the tween overlay is baked into `createTimeline`), so a render of\n * the directory is a render of what the studio and vos.so play.\n */\nexport async function loadProgramDirectory(\n  dir: string,\n  warnings: string[],\n): Promise<unknown> {\n  const config: unknown = JSON.parse(\n    await readFile(join(dir, 'config.json'), 'utf8'),\n  )\n  const docPath = join(dir, 'doc.json')\n  if (!existsSync(docPath)) return config\n  const doc: unknown = JSON.parse(await readFile(docPath, 'utf8'))\n  if (typeof doc !== 'object' || doc === null || 'source' in doc) return config\n  if (typeof config !== 'object' || config === null) {\n    throw new UsageError(`${dir}/config.json does not contain a JSON object`)\n  }\n  const raw = doc as Record<string, unknown>\n  const program =\n    raw.program && typeof raw.program === 'object'\n      ? (raw.program as Record<string, unknown>)\n      : {}\n  const { lowerProgramDoc } = await import('@vosjs/studio-core')\n  const composed = lowerProgramDoc(\n    { ...raw, program: { ...program, config } } as never,\n    { bake: true },\n  ).config\n  warnings.push(\n    'composed config.json with doc.json (a program document: its layers and tween edits ride the render)',\n  )\n  return composed\n}\n\n/**\n * The text of a config source: an http(s) URL or a file. A directory that is\n * neither a take nor a program directory is refused in words, since the raw\n * read would report a bare EISDIR.\n */\nexport async function readSourceText(source: string): Promise<string> {\n  if (/^https?:\\/\\//.test(source)) {\n    const res = await fetch(source)\n    if (!res.ok) throw new Error(`fetch ${source} → ${res.status}`)\n    return await res.text()\n  }\n  let isDir = false\n  try {\n    isDir = statSync(source).isDirectory()\n  } catch {\n    /* a missing path reads below and reports itself */\n  }\n  if (isDir) {\n    throw new UsageError(\n      `${source} is a directory with no config.json and no doc.json — pass a config file, a URL, a program directory or a take`,\n    )\n  }\n  return await readFile(source, 'utf8')\n}\n\n/**\n * Load a VosConfigJson from a file path, an http(s) URL, or a program\n * directory (config.json, composed with a program document when one sits\n * beside it); unwrap API `{ config }` envelopes, migrate old versions, and\n * validate against the schema. A take directory is refused here in words:\n * takes render through the take pipeline (`vos render <take>`).\n */\nexport async function loadVosConfig(source: string): Promise<LoadedConfig> {\n  const warnings: string[] = []\n  let parsed: unknown\n  const kind = /^https?:\\/\\//.test(source) ? 'none' : directoryKind(source)\n  if (kind === 'take') {\n    throw new UsageError(\n      `${source} is a take (its doc.json is a recording document). Render it through the take pipeline: vos render ${source} [out]; vos frames ${source} for stills.`,\n    )\n  }\n  if (kind === 'program') {\n    parsed = await loadProgramDirectory(source, warnings)\n    return finish(source, parsed, warnings)\n  }\n  const raw = await readSourceText(source)\n\n  try {\n    parsed = JSON.parse(raw)\n  } catch (e) {\n    throw new UsageError(`${source} is not valid JSON: ${(e as Error).message}`)\n  }\n  return finish(source, parsed, warnings)\n}\n\nfunction finish(\n  source: string,\n  parsed: unknown,\n  warnings: string[],\n): LoadedConfig {\n  if (typeof parsed !== 'object' || parsed === null) {\n    throw new UsageError(`${source} does not contain a JSON object`)\n  }\n\n  // API endpoints wrap the config: { config: {...} }.\n  let obj = parsed as Record<string, unknown>\n  if (\n    typeof obj.config === 'object' &&\n    obj.config !== null &&\n    !('createTimeline' in obj)\n  ) {\n    obj = obj.config as Record<string, unknown>\n    warnings.push('unwrapped { config } envelope')\n  }\n\n  const version = obj.version\n  const migrated = migrateConfig(obj)\n  if (version === undefined) {\n    // Plays fine (the stamp happens above), but a storer refuses it.\n    warnings.push(\n      `config declares no \"version\". Add \"version\": ${CURRENT_CONFIG_VERSION} before pushing it.`,\n    )\n  } else if (version !== CURRENT_CONFIG_VERSION) {\n    warnings.push(\n      `migrated config v${String(version)} to v${CURRENT_CONFIG_VERSION}`,\n    )\n  }\n\n  const check = vosConfigJsonSchema.safeParse(migrated)\n  if (!check.success) {\n    const issues = check.error.issues\n      .slice(0, 5)\n      .map((i) => `  ${i.path.join('.') || '(root)'}: ${i.message}`)\n      .join('\\n')\n    throw new UsageError(`invalid vos config:\\n${issues}`)\n  }\n\n  return { config: migrated, warnings }\n}\n\n/** Best-effort duration from the config (seconds). */\nexport function configDuration(\n  config: Record<string, unknown>,\n): number | undefined {\n  const d = config.duration\n  return typeof d === 'number' && Number.isFinite(d) && d > 0 ? d : undefined\n}\n","import { chromium } from 'playwright'\nimport type { Browser } from 'playwright'\n\nexport class BrowserUnavailableError extends Error {\n  constructor(cause: string) {\n    super(\n      `Could not launch a Chromium-family browser (${cause}).\\n` +\n        `Fixes, in order of preference:\\n` +\n        `  1. Install Google Chrome (used automatically), or\\n` +\n        `  2. npx playwright install chromium, or\\n` +\n        `  3. Set VOS_BROWSER_PATH to a Chrome/Chromium executable.`,\n    )\n  }\n}\n\n/**\n * Launch headless Chromium: explicit VOS_BROWSER_PATH → system Chrome\n * (no download needed) → Playwright's bundled Chromium.\n *\n * `args` are extra Chromium switches (`--browser-arg` on the verbs that\n * record). Some product surfaces cannot be reached without one: a recorder\n * needs a fake capture device to get past a permission prompt, an extension\n * page needs the extension loaded. Passed through verbatim.\n */\nexport async function launchBrowser(args: string[] = []): Promise<Browser> {\n  const opts = args.length ? { args } : {}\n  const explicit = process.env.VOS_BROWSER_PATH\n  if (explicit) {\n    return chromium.launch({ ...opts, executablePath: explicit }).catch((e) => {\n      throw new BrowserUnavailableError(\n        `VOS_BROWSER_PATH failed: ${(e as Error).message}`,\n      )\n    })\n  }\n  try {\n    return await chromium.launch({ ...opts, channel: 'chrome' })\n  } catch {\n    try {\n      return await chromium.launch(opts)\n    } catch (e) {\n      throw new BrowserUnavailableError(\n        (e as Error).message.split('\\n')[0] ?? 'unknown',\n      )\n    }\n  }\n}\n"],"mappings":"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","names":[]}