@vosjs/cli 0.77.1 → 0.78.0

package/dist/index.d.ts

@@ -91,32 +91,12 @@ declare class BrowserUnavailableError extends Error {
  * `args` are extra Chromium switches (`--browser-arg` on the verbs that
  * record). Some product surfaces cannot be reached without one: a recorder
  * needs a fake capture device to get past a permission prompt, an extension
- * page needs the extension loaded. Passed through verbatim.
+ * page needs the extension loaded. Passed through verbatim. `headless:
+ * false` opens a window (`vos look --headed`).
  */
-declare function launchBrowser(args?: string[]): Promise<Browser>;
-
-/** Entry point — the delegation contract for @vosjs/cli: the host forwards
-    every non-engine verb here (`vos <verb>`). The exported `manifest` (index.ts)
-    tells the host which verbs exist and how to summarize them in help. */
-declare function run(argv: string[]): Promise<number>;
-
-/**
- * The verb manifest of the take pipeline and the vos.so verbs — what
- * `vos help` lists under the engine verbs. It kept the shape a separately
- * installed plugin once handed the host (name + host range), so a script
- * reading it keeps working.
- */
-interface PluginVerb {
-    name: string;
-    summary: string;
-}
-interface PluginManifest {
-    name: string;
-    /** Host versions this plugin speaks the run(argv) contract with. */
-    hostRange: string;
-    verbs: PluginVerb[];
-}
-declare const manifest: PluginManifest;
+declare function launchBrowser(args?: string[], launch?: {
+    headless?: boolean;
+}): Promise<Browser>;
 
 /** The name `record` writes its footage under — its encoder emits WebM. */
 declare const RECORDING_NAME = "recording.webm";
@@ -143,7 +123,7 @@ interface TakeData {
 /** Load a take directory; cursor+meta are required, doc/actions optional. */
 declare function loadTake(dir: string): Promise<TakeData>;
 
-type RecordOpts = Omit<RecordOpts$1, 'context' | 'env' | 'platform'> & {
+type RecordOpts = Omit<RecordOpts$1, 'context' | 'env' | 'platform' | 'outputs'> & {
     /**
      * A ready-made context to record IN, instead of one made from `browser`:
      * `--session <name>`, a persistent profile the person signed in to.
@@ -152,6 +132,29 @@ type RecordOpts = Omit<RecordOpts$1, 'context' | 'env' | 'platform'> & {
 };
 declare function recordTake(browser: Browser, url: string, actions: ActionsFile, paths: TakePaths, log: (msg: string) => void, opts?: RecordOpts): Promise<_vosjs_render_core_record.RecordResult>;
 
+/** Entry point — the delegation contract for @vosjs/cli: the host forwards
+    every non-engine verb here (`vos <verb>`). The exported `manifest` (index.ts)
+    tells the host which verbs exist and how to summarize them in help. */
+declare function run(argv: string[]): Promise<number>;
+
+/**
+ * The verb manifest of the take pipeline and the vos.so verbs — what
+ * `vos help` lists under the engine verbs. It kept the shape a separately
+ * installed plugin once handed the host (name + host range), so a script
+ * reading it keeps working.
+ */
+interface PluginVerb {
+    name: string;
+    summary: string;
+}
+interface PluginManifest {
+    name: string;
+    /** Host versions this plugin speaks the run(argv) contract with. */
+    hostRange: string;
+    verbs: PluginVerb[];
+}
+declare const manifest: PluginManifest;
+
 declare function encodeRecording(browser: Browser, takeDir: string, onProgress: (fraction: number) => void): Promise<{
     bytes: number;
 }>;

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   startTakeServer,
   validateActions,
   waitForPageDone
-} from "./chunk-IJZ3C435.js";
+} from "./chunk-INRUYQ6J.js";
 import {
   BrowserUnavailableError,
   configDuration,
@@ -23,13 +23,13 @@ import {
   previewPages,
   renderStill,
   renderVideo
-} from "./chunk-KDIRW72G.js";
+} from "./chunk-JYCW4EOA.js";
 import {
   RECORDING_NAME,
   loadTake,
   pullMedia,
   takePaths
-} from "./chunk-UY2N42P2.js";
+} from "./chunk-ZSJEISKL.js";
 import {
   apiError,
   apiJson,
@@ -42,7 +42,7 @@ import {
 import "./chunk-6XPFWQKP.js";
 import {
   manifest
-} from "./chunk-2KEQ3LKH.js";
+} from "./chunk-RUDDBHQ7.js";
 export {
   BrowserUnavailableError,
   RECORDING_NAME,

package/dist/manifest-6DJSPKVH.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import {
+  manifest
+} from "./chunk-RUDDBHQ7.js";
+export {
+  manifest
+};
+//# sourceMappingURL=manifest-6DJSPKVH.js.map

package/dist/{run-UNOXIGZ3.js → run-TIFM3ZHI.js}

@@ -3,20 +3,22 @@ import {
   HELP,
   MULTI_FLAGS,
   run,
+  strictFails,
   takeBackdrop,
   takeBrowserArgs,
   verbHelp
-} from "./chunk-IJZ3C435.js";
-import "./chunk-KDIRW72G.js";
-import "./chunk-UY2N42P2.js";
+} from "./chunk-INRUYQ6J.js";
+import "./chunk-JYCW4EOA.js";
+import "./chunk-ZSJEISKL.js";
 import "./chunk-B4U4URE3.js";
 import "./chunk-6XPFWQKP.js";
 export {
   HELP,
   MULTI_FLAGS,
   run,
+  strictFails,
   takeBackdrop,
   takeBrowserArgs,
   verbHelp
 };
-//# sourceMappingURL=run-UNOXIGZ3.js.map
+//# sourceMappingURL=run-TIFM3ZHI.js.map

package/dist/{shotList-MAQVLZBY.js → shotList-SCA234OS.js}

@@ -31,10 +31,28 @@ function sayStepTarget(step) {
   const byId = sayId(step.id);
   return byId ? `${byId} (${bySelector})` : bySelector;
 }
+function sayCondition(c) {
+  if (c.text !== void 0) return `"${c.text}" shows on the page`;
+  if (c.gone !== void 0) return `${sayTarget(c.gone)} is gone`;
+  const target = sayStepTarget({ selector: c.selector ?? "", id: c.id });
+  if (c.enabled === true) return `${target} is enabled`;
+  if (c.enabled === false) return `${target} is disabled`;
+  return `${target} is showing`;
+}
 function beatOf(step) {
+  const line = gestureBeat(step);
+  return line && step.guard ? `${line} (this spends something real: do it only if you mean to)` : line;
+}
+function gestureBeat(step) {
   const cap = step.caption;
   const named = cap ? `${cap}: ` : "";
   switch (step.do) {
+    case "expect":
+      return `${named}Check that ${sayCondition(step)}`;
+    case "await":
+      return `${named}Wait until ${sayCondition({ ...step.until, id: step.id })} (off camera: pause the recording meanwhile)`;
+    case "download":
+      return step.selector !== void 0 ? `${named}Download the file ${sayStepTarget({ selector: step.selector, id: step.id })} gives${step.as ? `, as ${step.as}` : ""}` : `${named}Download what ${sayTarget(step.src ?? "")} plays${step.as ? `, as ${step.as}` : ""}`;
     case "wait":
       return null;
     case "hover":
@@ -110,4 +128,4 @@ export {
   sayTarget,
   shotList
 };
-//# sourceMappingURL=shotList-MAQVLZBY.js.map
+//# sourceMappingURL=shotList-SCA234OS.js.map

package/dist/shotList-SCA234OS.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\n/** A page condition, for a person: what they should see before going on. */\nfunction sayCondition(c: {\n  selector?: string\n  text?: string\n  gone?: string\n  enabled?: boolean\n  id?: string\n}): string {\n  if (c.text !== undefined) return `\"${c.text}\" shows on the page`\n  if (c.gone !== undefined) return `${sayTarget(c.gone)} is gone`\n  const target = sayStepTarget({ selector: c.selector ?? '', id: c.id })\n  if (c.enabled === true) return `${target} is enabled`\n  if (c.enabled === false) return `${target} is disabled`\n  return `${target} is showing`\n}\n\nfunction beatOf(step: ActionStep): string | null {\n  const line = gestureBeat(step)\n  // A step that spends something real is marked where a person reads it.\n  return line && step.guard\n    ? `${line} (this spends something real: do it only if you mean to)`\n    : line\n}\n\nfunction gestureBeat(step: ActionStep): string | null {\n  const cap = step.caption\n  const named = cap ? `${cap}: ` : ''\n  switch (step.do) {\n    case 'expect':\n      return `${named}Check that ${sayCondition(step)}`\n    case 'await':\n      return `${named}Wait until ${sayCondition({ ...step.until, id: step.id })} (off camera: pause the recording meanwhile)`\n    case 'download':\n      return step.selector !== undefined\n        ? `${named}Download the file ${sayStepTarget({ selector: step.selector, id: step.id })} gives${step.as ? `, as ${step.as}` : ''}`\n        : `${named}Download what ${sayTarget(step.src ?? '')} plays${step.as ? `, as ${step.as}` : ''}`\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}${step.replace ? 'Replace what is in' : 'Type'}${step.replace ? ` ${sayStepTarget(step)} with \"${step.text}\"` : ` \"${step.text}\" into ${sayStepTarget(step)}`}${step.at === 'end' ? ', at the end' : step.at === 'start' ? ', at the start' : ''}`\n    case 'press':\n      return `${named}Press ${step.key}${step.selector ? ` in ${sayStepTarget(step as { selector: string; id?: string })}` : ''}`\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.77.1",
+  "version": "0.78.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, deliver a release's video cuts per destination spec, and sync with vos.so. One binary, every verb, MIT.",
   "type": "module",
   "license": "MIT",
@@ -51,12 +51,12 @@
     "acorn-walk": "^8.3.5",
     "mediabunny": "^1.55.7",
     "playwright": "^1.49.0",
+    "@vosjs/core": "^0.31.0",
     "@vosjs/editor": "^1.6.0",
     "@vosjs/elements": "^0.12.1",
-    "@vosjs/render-core": "^0.6.0",
-    "@vosjs/core": "^0.31.0",
+    "@vosjs/render-core": "^0.7.0",
     "@vosjs/shared": "^0.7.0",
-    "@vosjs/studio-core": "^0.42.3",
+    "@vosjs/studio-core": "^0.43.0",
     "@vosjs/timeline": "^0.5.0",
     "@vosjs/tween": "^0.8.3"
   },

package/schema/actions.schema.json

@@ -202,6 +202,11 @@
                 "type": "string",
                 "minLength": 1,
                 "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              },
+              "guard": {
+                "type": "string",
+                "enum": ["spend"],
+                "description": "the step costs something real (credits, a purchase, a message sent): `vos record --dry-run` hovers it and never presses it, and `vos record` presses it only with `--confirm <id>`, refusing before any capture otherwise. Needs an id. A hosted take refuses a guarded step"
               }
             }
           },
@@ -259,6 +264,11 @@
                 "type": "string",
                 "enum": ["end", "start"],
                 "description": "where the caret goes after the focusing click, before the first character: a click lands it where the pointer hit, and a code editor line is typed at its end"
+              },
+              "guard": {
+                "type": "string",
+                "enum": ["spend"],
+                "description": "the step costs something real (credits, a purchase, a message sent): `vos record --dry-run` hovers it and never presses it, and `vos record` presses it only with `--confirm <id>`, refusing before any capture otherwise. Needs an id. A hosted take refuses a guarded step"
               }
             }
           },
@@ -313,6 +323,11 @@
                 "type": "string",
                 "minLength": 1,
                 "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              },
+              "guard": {
+                "type": "string",
+                "enum": ["spend"],
+                "description": "the step costs something real (credits, a purchase, a message sent): `vos record --dry-run` hovers it and never presses it, and `vos record` presses it only with `--confirm <id>`, refusing before any capture otherwise. Needs an id. A hosted take refuses a guarded step"
               }
             }
           },
@@ -431,6 +446,183 @@
                 "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
               }
             }
+          },
+          {
+            "type": "object",
+            "required": ["do"],
+            "additionalProperties": false,
+            "description": "Check the page is as the flow expects, on camera, with no cursor move: exactly one of selector (visible; with enabled, enabled or disabled), text (some visible text contains it) or gone (no longer visible). A condition that never holds is a skip with its reason, which --strict turns into exit 2.",
+            "oneOf": [
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["text"]
+              },
+              {
+                "required": ["gone"]
+              }
+            ],
+            "properties": {
+              "do": {
+                "const": "expect"
+              },
+              "selector": {
+                "type": "string",
+                "minLength": 1
+              },
+              "text": {
+                "type": "string",
+                "minLength": 1
+              },
+              "gone": {
+                "type": "string",
+                "minLength": 1
+              },
+              "enabled": {
+                "type": "boolean",
+                "description": "with selector: wait for the element to be enabled (true) or disabled (false)"
+              },
+              "timeout": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 5,
+                "description": "seconds to wait for the condition"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional stable identity: doc.json anchors name a step by this id (else by index), so a step survives moving or gaining neighbours across script edits. Unique across steps when present."
+              },
+              "caption": {
+                "type": "string",
+                "maxLength": 80,
+                "description": "a beat's caption: vos deliver lands it as a lower-third at this step's moment on cuts that take words (feed cuts, the demo), never on a loop"
+              },
+              "read": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do", "until"],
+            "additionalProperties": false,
+            "description": "Wait OFF CAMERA for something slow (a render, a generated result): the capture stops, the condition is polled, and the capture resumes when it holds, so the footage has no gap and no frozen stretch. The cut lands in meta.skips[] ({ step, id, at, ms }) and becomes a segment boundary in the planned doc.json. A rehearsal waits for real and prints the time.",
+            "properties": {
+              "do": {
+                "const": "await"
+              },
+              "until": {
+                "type": "object",
+                "additionalProperties": false,
+                "minProperties": 1,
+                "maxProperties": 1,
+                "properties": {
+                  "selector": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "text": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "gone": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              },
+              "timeout": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 600,
+                "description": "the most seconds to wait"
+              },
+              "poll": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "default": 2,
+                "description": "seconds between looks"
+              },
+              "reload": {
+                "type": "boolean",
+                "default": false,
+                "description": "reload the page between looks"
+              },
+              "onTimeout": {
+                "type": "string",
+                "enum": ["fail", "continue"],
+                "default": "fail",
+                "description": "fail: the take stops there, exit 1; continue: the capture resumes and the skip records timedOut"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional stable identity: doc.json anchors name a step by this id (else by index), so a step survives moving or gaining neighbours across script edits. Unique across steps when present."
+              },
+              "caption": {
+                "type": "string",
+                "maxLength": 80,
+                "description": "a beat's caption: vos deliver lands it as a lower-third at this step's moment on cuts that take words (feed cuts, the demo), never on a loop"
+              },
+              "read": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": ["do"],
+            "additionalProperties": false,
+            "description": "Keep a file the page makes, in the take's outputs/: selector clicks a control and waits up to 30 s for the browser's download; src fetches the currentSrc of a video, audio or img element with the page's own cookies. Listed in meta.outputs[] ({ step, id, name, bytes, contentType }). A download that never arrives is a skip with its reason. A hosted take refuses a download.",
+            "oneOf": [
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["src"]
+              }
+            ],
+            "properties": {
+              "do": {
+                "const": "download"
+              },
+              "selector": {
+                "type": "string",
+                "minLength": 1
+              },
+              "src": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector (the same grammar as every other step) of a video, audio or img element"
+              },
+              "as": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^(?!\\.)(?!.*\\.\\.)[^/\\\\]+$",
+                "description": "the file name inside outputs/ (a plain name: no path separator, no \"..\"); absent, the name the page suggested"
+              },
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Optional stable identity: doc.json anchors name a step by this id (else by index), so a step survives moving or gaining neighbours across script edits. Unique across steps when present."
+              },
+              "caption": {
+                "type": "string",
+                "maxLength": 80,
+                "description": "a beat's caption: vos deliver lands it as a lower-third at this step's moment on cuts that take words (feed cuts, the demo), never on a loop"
+              },
+              "read": {
+                "type": "string",
+                "minLength": 1,
+                "description": "a selector whose words the recorder keeps once the step has settled (meta.steps[].text, trimmed, at most 2 KB): the take's own payload, which a layer quotes instead of a replay; on a click, what the click opened"
+              }
+            }
           }
         ]
       }

package/schema/doc.schema.json

@@ -957,14 +957,38 @@
           "start": {
             "type": "number",
             "minimum": 0,
-            "description": "OUTPUT seconds"
+            "description": "OUTPUT seconds. With an `anchor` it is the fallback, used when the anchor cannot resolve"
+          },
+          "anchor": {
+            "type": "object",
+            "required": ["step"],
+            "additionalProperties": false,
+            "description": "When the layer starts, as a recorder step: the lowering maps the step's moment (meta.steps, SOURCE seconds of its media) through the segments, speed spans and freezes exactly as a source-anchored span is mapped, and adds `offset`. A trim, a speed change or a re-record moves the layer with its step; `start` is the fallback when the step is missing, skipped or cut out (validate says which), and `duration` stays the layer's own. A text layer's {elapsed} fills with the anchored step's off-camera wait (the meta.skips entry naming the step, else its offCameraMs; a step that waited for nothing reads the nearest earlier wait on its media) as a rounded duration, like \"12 minutes\". Not the re-record `anchor` on spans, which the lowering never reads",
+            "properties": {
+              "step": {
+                "type": ["string", "integer"],
+                "description": "the step: its actions.json `id` (meta.steps[].id), else its index"
+              },
+              "media": {
+                "type": "string",
+                "description": "whose steps: a media[].id (absent = the primary)"
+              },
+              "at": {
+                "enum": ["start", "end"],
+                "description": "which edge of the step is its moment (default start)"
+              },
+              "offset": {
+                "type": "number",
+                "description": "OUTPUT seconds after the step's moment (negative = before; default 0)"
+              }
+            }
           },
           "duration": {
             "type": "number",
             "exclusiveMinimum": 0
           },
           "text": {
-            "description": "the words; \\n breaks lines. A string, or a list of RUNS when parts of it are set differently: each run is a piece of text and the fields in which it departs from the layer's style. Example: [{ \"text\": \"Ship \" }, { \"text\": \"faster\", \"weight\": 700, \"underline\": true }]. There is no markup in the words: an asterisk is an asterisk. A run may hold \\n, a style may start and end anywhere, and a word-by-word reveal keeps every word in its own style",
+            "description": "the words; \\n breaks lines. On an anchored layer, {elapsed} fills with the anchored step's off-camera wait. A string, or a list of RUNS when parts of it are set differently: each run is a piece of text and the fields in which it departs from the layer's style. Example: [{ \"text\": \"Ship \" }, { \"text\": \"faster\", \"weight\": 700, \"underline\": true }]. There is no markup in the words: an asterisk is an asterisk. A run may hold \\n, a style may start and end anywhere, and a word-by-word reveal keeps every word in its own style",
             "oneOf": [
               { "type": "string" },
               {

package/dist/chunk-2KEQ3LKH.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/plugin/manifest.ts"],"sourcesContent":["/**\n * The verb manifest of the take pipeline and the vos.so verbs — what\n * `vos help` lists under the engine verbs. It kept the shape a separately\n * installed plugin once handed the host (name + host range), so a script\n * reading it keeps working.\n */\nexport interface PluginVerb {\n  name: string\n  summary: string\n}\n\nexport interface PluginManifest {\n  name: string\n  /** Host versions this plugin speaks the run(argv) contract with. */\n  hostRange: string\n  verbs: PluginVerb[]\n}\n\nexport const manifest: PluginManifest = {\n  name: '@vosjs/cli',\n  hostRange: '>=0.9.0',\n  verbs: [\n    {\n      name: 'create',\n      summary: 'record + auto-plan + render, one command (--strict)',\n    },\n    {\n      name: 'record',\n      summary: 'drive actions.json into a take (screencast + cursor track)',\n    },\n    {\n      name: 'plan',\n      summary:\n        'plan zoom/cursor effects into doc.json (wand contract); --reuse re-times a previous cut onto a re-recording',\n    },\n    {\n      name: 'render',\n      summary: 'render a take directory (engine configs render in the host)',\n    },\n    {\n      name: 'frames',\n      summary:\n        'PNG stills at output times / zoom apexes / moments / exact sizes',\n    },\n    {\n      name: 'deliver',\n      summary:\n        'render a take to release video destinations (YouTube, X, Shorts/LinkedIn, GitHub) + verified kit.json',\n    },\n    {\n      name: 'digest',\n      summary:\n        'see a recording before cutting it: moments (clicks, typing, scrolls, idle, scenes) + footage frames + crops, in doc units',\n    },\n    { name: 'open', summary: 'serve the take into the vos.so studio' },\n    {\n      name: 'validate',\n      summary:\n        'lint actions.json, a take dir (doc.json semantics), or re-measure a kit.json against the channel specs',\n    },\n    {\n      name: 'actions',\n      summary:\n        'from-agent-browser: turn an agent-browser walk (steps.jsonl) into actions.json; what cannot follow is named',\n    },\n    {\n      name: 'ingest',\n      summary:\n        'a take from a recording someone else made, with its cursor track from a trace beside it (Playwright trace.zip, stamped records, CSV); without one nothing is planned',\n    },\n    {\n      name: 'port',\n      summary:\n        'bring a page, a HyperFrames or a Remotion piece: inventory (its words, colours, faces, media, scenes) then scaffold (a data-first program.mjs to translate the motion into)',\n    },\n    {\n      name: 'build',\n      summary:\n        'program.mjs (real functions) → config.json, refusing what cannot run on its own (module-scope reads, syntax the page cannot parse, non-JSON data)',\n    },\n    {\n      name: 'compare',\n      summary:\n        \"a program against the source's own render: per-frame SSIM and source | vos | difference sheets; exits 1 when any frame is under the threshold\",\n    },\n    {\n      name: 'brand',\n      summary:\n        \"write a product's BRAND.md, witnessed: /design.md, /llms.txt, then the page (palette, faces, marks, the avoid list)\",\n    },\n    {\n      name: 'fetch',\n      summary: 'download a hosted program: config.json + vos.json tracking',\n    },\n    {\n      name: 'push',\n      summary: 'push a config.json or take to vos.so (private; versioned)',\n    },\n    {\n      name: 'duplicate',\n      summary:\n        'a private sibling of your OWN vos (someone else\\u2019s is remixed: fetch + push --remix-of)',\n    },\n    {\n      name: 'pull',\n      summary:\n        'sync what changed on vos.so since your base (--media brings a take’s footage home)',\n    },\n    {\n      name: 'folder',\n      summary:\n        'list/create/pull folders, move voses and assets into them (pull = the context package on disk)',\n    },\n    {\n      name: 'asset',\n      summary:\n        'your files: push or import one, list them (assets ls), see storage (assets usage) and what uses a file (assets why)',\n    },\n    {\n      name: 'recipe',\n      summary:\n        'push a recipe .md into a folder, or replace one in place (prior body kept)',\n    },\n    {\n      name: 'login',\n      summary: 'sign in via the browser (or --key); stores a content key',\n    },\n    {\n      name: 'setup',\n      summary:\n        'ready this machine: the vos skills into your agent, a browser, one rules block, then doctor',\n    },\n    {\n      name: 'doctor',\n      summary:\n        'what is ready, in words: node, browser, ffmpeg, skills, a credential (never printed), the dev server',\n    },\n    {\n      name: 'whoami',\n      summary: 'the key’s name and the account it belongs to, never the key',\n    },\n    { name: 'logout', summary: 'remove ~/.config/vos/credentials' },\n  ],\n}\n"],"mappings":";;;AAkBO,IAAM,WAA2B;AAAA,EACtC,MAAM;AAAA,EACN,WAAW;AAAA,EACX,OAAO;AAAA,IACL;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA,EAAE,MAAM,QAAQ,SAAS,wCAAwC;AAAA,IACjE;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SACE;AAAA,IACJ;AAAA,IACA;AAAA,MACE,MAAM;AAAA,MACN,SAAS;AAAA,IACX;AAAA,IACA,EAAE,MAAM,UAAU,SAAS,mCAAmC;AAAA,EAChE;AACF;","names":[]}