@vosjs/cli 0.78.0 → 0.79.0

package/dist/shotList-EE3S5LVF.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'\nimport { pressSequence, splitChord } from '@vosjs/render-core/record'\n\n/** A key or a chord as a person reads it: `Mod` is ⌘ on a Mac, Ctrl elsewhere. */\nexport function sayChord(chord: string): string {\n  const { mods, key } = splitChord(chord)\n  const word = (k: string) =>\n    k === 'Mod' || k === 'ControlOrMeta'\n      ? '⌘/Ctrl'\n      : k === 'Control'\n        ? 'Ctrl'\n        : k === 'Meta'\n          ? '⌘'\n          : k === 'Alt'\n            ? 'Alt/Option'\n            : k === ' '\n              ? 'Space'\n              : k\n  return [...mods, key].map(word).join('+')\n}\n\n/** A viewport point as a person finds it: where it is, and the script's numbers. */\nfunction sayPoint(p: { x?: number; y?: number }): string {\n  const x = p.x ?? 0\n  const y = p.y ?? 0\n  return `the spot at ${Math.round(x)}, ${Math.round(y)} (${y < 360 ? 'upper' : 'lower'} ${x < 640 ? 'left' : 'right'})`\n}\n\n/** A list in words: `a`, `a then b`, `a, b then c`. */\nconst thenList = (xs: string[]): string =>\n  xs.length <= 1\n    ? (xs[0] ?? '')\n    : `${xs.slice(0, -1).join(', ')} then ${xs[xs.length - 1]}`\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 ${step.selector !== undefined ? sayStepTarget({ selector: step.selector, id: step.id }) : sayPoint(step)}`\n    case 'click': {\n      const verb =\n        step.count === 3\n          ? 'Triple-click'\n          : step.count === 2\n            ? 'Double-click'\n            : 'Click'\n      const button =\n        step.button === 'right'\n          ? ' with the right button'\n          : step.button === 'middle'\n            ? ' with the middle button'\n            : ''\n      const target =\n        step.selector !== undefined\n          ? sayStepTarget({ selector: step.selector, id: step.id })\n          : sayPoint(step)\n      const holding = step.modifiers?.length\n        ? `Hold ${step.modifiers.map(sayChord).join('+')} and ${verb.toLowerCase()}`\n        : verb\n      return `${named}${holding} ${target}${button}`\n    }\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 ${thenList(pressSequence(step).map(sayChord))}${step.selector ? ` in ${sayStepTarget(step as { selector: string; id?: string })}` : ''}`\n    case 'paste': {\n      const what =\n        step.text !== undefined\n          ? `\"${step.text.length > 60 ? `${step.text.slice(0, 57)}...` : step.text}\"`\n          : `the file ${step.file}`\n      return `${named}Copy ${what}, then paste it${step.selector ? ` into ${sayStepTarget({ selector: step.selector, id: step.id })}` : ''} (⌘/Ctrl+V)`\n    }\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      const holding = step.modifiers?.length\n        ? `Hold ${step.modifiers.map(sayChord).join('+')} and `\n        : ''\n      const verb = holding ? 'drag' : 'Drag'\n      if (step.path !== undefined)\n        return `${named}${holding}${holding ? 'draw' : 'Draw'} the stroke ${typeof step.path === 'string' ? `in ${step.path}` : `of ${step.path.length} points`}, in one press`\n      return `${named}${holding}${verb} ${step.selector ? sayStepTarget(step as { selector: string; id?: string }) : 'from the start point'} across`\n    }\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.78.0",
+  "version": "0.79.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",
@@ -53,10 +53,10 @@
     "playwright": "^1.49.0",
     "@vosjs/core": "^0.31.0",
     "@vosjs/editor": "^1.6.0",
+    "@vosjs/render-core": "^0.8.0",
+    "@vosjs/studio-core": "^0.44.0",
     "@vosjs/elements": "^0.12.1",
-    "@vosjs/render-core": "^0.7.0",
     "@vosjs/shared": "^0.7.0",
-    "@vosjs/studio-core": "^0.43.0",
     "@vosjs/timeline": "^0.5.0",
     "@vosjs/tween": "^0.8.3"
   },

package/schema/actions.schema.json

@@ -80,6 +80,12 @@
         }
       }
     },
+    "ready": {
+      "type": "string",
+      "enum": ["dom", "networkidle"],
+      "default": "dom",
+      "description": "When the first page counts as ready for step 1. dom: after load, once the page has made no DOM change for 800 ms, at most 8 s. networkidle: once the network has gone quiet, at most 45 s, which a page holding a socket open or an analytics beacon never does. The same mode opens a setup goto, the page after a setup, and an await's reload. `--ready` overrides. The done event's `ready` says how the first load settled ({ mode, ms, capped }); `navTimeout` is true only when networkidle was asked for and never came."
+    },
     "mask": {
       "type": "array",
       "description": "Hidden BEFORE the first frame is captured and kept hidden across navigations and re-renders: what a signed-in account shows that must not ship. The real value is never in a frame, never in the recording, never pushed. `vos record` reports what it still sees afterwards (meta.exposures), and a mask whose selector reached nothing fails --strict.",
@@ -104,6 +110,11 @@
         }
       }
     },
+    "settle": {
+      "type": "boolean",
+      "default": false,
+      "description": "every gesture step waits on the app after it (a step's own settle overrides): a canvas that falls behind under load finishes the last stroke before the next one starts"
+    },
     "steps": {
       "type": "array",
       "minItems": 1,
@@ -140,14 +151,24 @@
           },
           {
             "type": "object",
-            "required": ["do", "selector"],
+            "required": ["do"],
             "additionalProperties": false,
             "properties": {
               "do": {
                 "const": "hover"
               },
               "selector": {
-                "type": "string"
+                "type": "string",
+                "description": "the element whose centre the pointer goes to; or x and y instead"
+              },
+              "x": {
+                "type": "number",
+                "minimum": 0,
+                "description": "with y: a viewport point in CSS px, for a spot no selector names (a place on a canvas); takes no selector"
+              },
+              "y": {
+                "type": "number",
+                "minimum": 0
               },
               "ms": {
                 "type": "number",
@@ -155,6 +176,10 @@
                 "default": 700,
                 "description": "Dwell — parked cursor becomes a zoom signal."
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -170,11 +195,33 @@
                 "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"
               }
-            }
+            },
+            "oneOf": [
+              {
+                "required": ["selector"],
+                "not": {
+                  "anyOf": [
+                    {
+                      "required": ["x"]
+                    },
+                    {
+                      "required": ["y"]
+                    }
+                  ]
+                }
+              },
+              {
+                "required": ["x", "y"],
+                "not": {
+                  "required": ["selector"]
+                }
+              }
+            ],
+            "description": "Rest the pointer on an element's centre (selector) or on a viewport point (x, y); ms is the dwell, a zoom signal."
           },
           {
             "type": "object",
-            "required": ["do", "selector"],
+            "required": ["do"],
             "additionalProperties": false,
             "properties": {
               "do": {
@@ -186,7 +233,42 @@
                 "description": "the read after the press, ms (default 150), held from the page's last visual change: the recorder watches the screencast and pays the settle itself (a change within 400 ms says the page is answering, 250 ms of quiet says it settled, 1.2 s bounds a page that never stops), so the same ms reads the same on every run. Size it as a reading beat, about 1000 after a navigation and 600 after a control, never padded for a slow page."
               },
               "selector": {
-                "type": "string"
+                "type": "string",
+                "description": "the element whose centre the pointer goes to; or x and y instead"
+              },
+              "x": {
+                "type": "number",
+                "minimum": 0,
+                "description": "with y: a viewport point in CSS px, for a spot no selector names (a place on a canvas); takes no selector"
+              },
+              "y": {
+                "type": "number",
+                "minimum": 0
+              },
+              "count": {
+                "type": "integer",
+                "enum": [1, 2, 3],
+                "default": 1,
+                "description": "2 is a real double click, 3 a triple click: that many presses inside the platform's double-click interval, each carrying its click count; every press is a down and an up on the cursor track"
+              },
+              "button": {
+                "type": "string",
+                "enum": ["left", "right", "middle"],
+                "default": "left",
+                "description": "the button pressed: right opens a context menu"
+              },
+              "modifiers": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": {
+                  "type": "string",
+                  "enum": ["Alt", "Shift", "Meta", "Control", "Mod"]
+                },
+                "description": "held for the press (a Shift-click adds to the selection) and released after it, whatever happens; Mod is Meta on macOS, Control elsewhere"
+              },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
               },
               "id": {
                 "type": "string",
@@ -208,7 +290,28 @@
                 "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"
               }
-            }
+            },
+            "oneOf": [
+              {
+                "required": ["selector"],
+                "not": {
+                  "anyOf": [
+                    {
+                      "required": ["x"]
+                    },
+                    {
+                      "required": ["y"]
+                    }
+                  ]
+                }
+              },
+              {
+                "required": ["x", "y"],
+                "not": {
+                  "required": ["selector"]
+                }
+              }
+            ]
           },
           {
             "type": "object",
@@ -240,6 +343,10 @@
                 "default": true,
                 "description": "The recorder clicks the field before typing, and that click is what opens the typing zoom on it. false types into the field as it is already focused: for a keystroke that finishes earlier typing (a submitting Enter) rather than starting it, where a second click rings a click effect on empty space beside the text."
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -274,9 +381,9 @@
           },
           {
             "type": "object",
-            "required": ["do", "key"],
+            "required": ["do"],
             "additionalProperties": false,
-            "description": "One named key, recorded as a typing ping where the pointer is (or on selector when given, with no click): Escape closes what a click opened, Enter submits what was typed, Tab moves on, an arrow nudges. Never a character: words are typed with type.",
+            "description": "A key, a chord or a sequence, each recorded as a typing ping where the pointer is (or on selector when given, with no click), never as the key itself. key names one control key (Escape closes what a click opened, Enter submits what was typed); keys names a chord (\"Shift+D\", \"Mod+Z\", Mod being Meta on macOS and Control elsewhere), a plain key (\"r\", a tool's shortcut) or a sequence ([\"v\", \"Escape\"]), 150 ms apart. Words are typed with type.",
             "properties": {
               "do": {
                 "const": "press"
@@ -300,6 +407,24 @@
                   "Space"
                 ]
               },
+              "keys": {
+                "oneOf": [
+                  {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  {
+                    "type": "array",
+                    "minItems": 1,
+                    "maxItems": 50,
+                    "items": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  }
+                ],
+                "description": "a key name or chord (modifiers Shift, Control, Alt, Meta, Mod, ControlOrMeta joined with + before the key; a key is a single character, a named key like Escape or ArrowLeft, F1 to F24, or a code like KeyA or Digit1), or a list of them pressed in order"
+              },
               "selector": {
                 "type": "string",
                 "description": "the element the key is about: the ping and the step's rect are its, with no click"
@@ -309,6 +434,10 @@
                 "minimum": 0,
                 "description": "the read after the key, ms (default 150), held from the page's last visual change like a click's"
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -329,7 +458,15 @@
                 "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"
               }
-            }
+            },
+            "oneOf": [
+              {
+                "required": ["key"]
+              },
+              {
+                "required": ["keys"]
+              }
+            ]
           },
           {
             "type": "object",
@@ -347,6 +484,10 @@
               "dy": {
                 "type": "number"
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -380,6 +521,10 @@
                 "type": "number",
                 "minimum": 0
               },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
               "id": {
                 "type": "string",
                 "minLength": 1,
@@ -399,9 +544,9 @@
           },
           {
             "type": "object",
-            "required": ["do", "tx", "ty"],
+            "required": ["do"],
             "additionalProperties": false,
-            "description": "Press-move-release: drag an element, slide a range input, move a clip. Start = selector center when given, else (x, y); end = (tx, ty), eased over ms.",
+            "description": "Press-move-release: drag an element, slide a range input, move a clip. Start = selector center when given, else (x, y); end = (tx, ty), eased over ms. With path, the drag DRAWS: the press at the path's first point, a move at every later point in order (never dropped, so a page that answers slowly makes the stroke late, reported as meta.steps[].overrunMs, never a different stroke), the release at its last. modifiers are held from the press to the release.",
             "properties": {
               "do": {
                 "const": "drag"
@@ -425,10 +570,42 @@
                 "type": "number",
                 "minimum": 0
               },
+              "path": {
+                "oneOf": [
+                  {
+                    "type": "array",
+                    "minItems": 2,
+                    "maxItems": 20000,
+                    "items": {
+                      "$ref": "#/$defs/pathPoint"
+                    }
+                  },
+                  {
+                    "type": "string",
+                    "pattern": "^(?!\\.)(?!.*\\.\\.)[^/\\\\]+$",
+                    "description": "a JSON file beside the actions file (a plain name) holding the points, or { \"points\": [...] }"
+                  }
+                ],
+                "description": "viewport points to draw through, replayed by their own times (tMs from the first point) or, untimed, evenly over ms. A point that carries pressure draws the whole path with a pen (pointer events with that pressure); without, the mouse draws it. A path takes no selector, x, y, tx or ty"
+              },
+              "modifiers": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": {
+                  "type": "string",
+                  "enum": ["Alt", "Shift", "Meta", "Control", "Mod"]
+                },
+                "description": "held from the press to the release (Alt-drag to duplicate, Shift to constrain); Mod is Meta on macOS, Control elsewhere"
+              },
               "ms": {
                 "type": "number",
                 "minimum": 0,
-                "default": 700
+                "default": 700,
+                "description": "the travel of a straight drag, or of an untimed path (default 700)"
+              },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
               },
               "id": {
                 "type": "string",
@@ -445,7 +622,18 @@
                 "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"
               }
-            }
+            },
+            "oneOf": [
+              {
+                "required": ["tx", "ty"],
+                "not": {
+                  "required": ["path"]
+                }
+              },
+              {
+                "required": ["path"]
+              }
+            ]
           },
           {
             "type": "object",
@@ -623,9 +811,106 @@
                 "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": "Put words or a file on the clipboard and paste it the way a person's ⌘V does: the browser's own clipboard and a trusted paste chord, so the page gets a trusted keydown and paste event and navigator.clipboard.read() sees the item; when the browser refuses the item, a paste event dispatched in the page (untrusted, said in the log). Into selector (clicked first) or where the focus is. Recorded as a typing ping, never its contents. A hosted take refuses a paste.",
+            "oneOf": [
+              {
+                "required": ["text"]
+              },
+              {
+                "required": ["file"]
+              }
+            ],
+            "properties": {
+              "do": {
+                "const": "paste"
+              },
+              "selector": {
+                "type": "string",
+                "minLength": 1,
+                "description": "the element to paste into, clicked first"
+              },
+              "text": {
+                "type": "string",
+                "description": "the words to paste"
+              },
+              "file": {
+                "type": "string",
+                "pattern": "^(?!\\.)(?!.*\\.\\.)[^/\\\\]+\\.(png|jpe?g|webp|gif|svg|txt|md|html?|json|csv)$",
+                "description": "a file beside the actions file, by a plain name, at most 10 MB: an image (a picture other than PNG is pasted as PNG), an SVG (also as its markup), or text"
+              },
+              "ms": {
+                "type": "number",
+                "minimum": 0,
+                "description": "the read after the paste, ms (default 150), held from the page's last visual change like a click's"
+              },
+              "settle": {
+                "type": "boolean",
+                "description": "after the gesture, wait until the page has made no DOM change and painted no new frame for 300 ms (at most 4 s), so an app that fell behind catches up before the next step; meta.steps[].settleMs says how long it waited. Absent: the script's top-level settle"
+              },
+              "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"
+              }
+            }
           }
         ]
       }
     }
+  },
+  "$defs": {
+    "pathPoint": {
+      "oneOf": [
+        {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 4,
+          "items": {
+            "type": "number"
+          },
+          "description": "[x, y], [x, y, tMs] or [x, y, tMs, pressure]: every point timed or none"
+        },
+        {
+          "type": "object",
+          "required": ["x", "y"],
+          "additionalProperties": false,
+          "properties": {
+            "x": {
+              "type": "number",
+              "minimum": 0
+            },
+            "y": {
+              "type": "number",
+              "minimum": 0
+            },
+            "t": {
+              "type": "number",
+              "minimum": 0,
+              "description": "ms"
+            },
+            "pressure": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          }
+        }
+      ]
+    }
   }
 }

package/schema/doc.schema.json

@@ -1589,7 +1589,38 @@
           "gain": {
             "type": "number",
             "minimum": 0,
-            "maximum": 1
+            "maximum": 1,
+            "description": "linear gain; with a measured `normalize`, a trim on the target"
+          },
+          "normalize": {
+            "type": "number",
+            "minimum": -30,
+            "maximum": -6,
+            "description": "target integrated loudness, LUFS (e.g. -16). Applies only while `loudness.src` is this clip's `key`: the clip plays at 10^((normalize - loudness.lufs) / 20) × gain, which may exceed 1, capped so the file's sample peak stays under -1 dBFS and never lifted more than +24 dB. Unmeasured or measured for another key, it is ignored (vos validate warns: measure it with vos audio measure)"
+          },
+          "loudness": {
+            "type": "object",
+            "description": "what the file measures (BS.1770 integrated, K-weighted, gated, over the whole file), written by vos audio measure, vos score and vos join, never by hand",
+            "required": ["lufs", "peakDb", "at", "src"],
+            "properties": {
+              "lufs": {
+                "type": "number",
+                "description": "integrated loudness, LUFS"
+              },
+              "peakDb": {
+                "type": ["number", "null"],
+                "description": "sample peak, dBFS (not oversampled)"
+              },
+              "at": {
+                "type": "string",
+                "description": "when it was measured (ISO date)"
+              },
+              "src": {
+                "type": "string",
+                "description": "the key it was measured for"
+              }
+            },
+            "additionalProperties": false
           },
           "fadeIn": {
             "type": "number",
@@ -1609,6 +1640,11 @@
             "type": "boolean",
             "description": "duck under the mic while speech is detected"
           },
+          "source": {
+            "type": "string",
+            "enum": ["page"],
+            "description": "page: sound the recorded page itself played (a video or audio element heard during the take, meta.media), placed by the plan at the output time it was heard and keyed to the file fetched into page-sound/. A re-plan replaces only these; absent = a clip someone added"
+          },
           "media": {
             "type": "string",
             "description": "the media this belongs to: a `media[].id`; absent = the primary, `source`"

package/skills/VERSION

@@ -1 +1 @@
-0.24.0
+0.25.0

package/skills/launch-kit/SKILL.md

@@ -180,7 +180,10 @@ not re-run `validate` after a push unless the human asks.
 
 ## 6. Push the release
 
-Push the take labelled for the release:
+Set `still` in `doc.json` to the payoff first (OUTPUT seconds): the
+result the release is about, never the opening. Without one the cover is
+derived near the start, usually a zoom on a navigation control under the
+first caption. Then push the take labelled for the release:
 
 ```
 vos push take --folder <project-slug> --label "v2.1 launch" --note "<what shipped, one line>" \
@@ -224,6 +227,8 @@ by data. Never spread before the seed is signed off.
   anything records. Cost a full re-record once.
 - A template's own palette on a deliverable: resolve `BRAND.md` (or witness
   the site) before cutting, and put it beside the take.
+- A push with no `still`: the release's watch page and share card open on
+  a frame near the start, not on what shipped.
 - A cold open (`firstlast`): the first frame is the marketing page's
   headline with the product nowhere; trim to the story or let the entrance
   carry it.

package/skills/product-video/SKILL.md

@@ -201,6 +201,11 @@ Per-channel dimensions and byte budgets: `references/destinations.md`.
    serves the take into the studio — your doc.json edits arrive intact and
    every zoom span is draggable.
 
+6c. **Pushing it to vos.so** (`vos push take`)? Set `still` in `doc.json`
+   (OUTPUT seconds) to the payoff first, the result the video is about,
+   never the opening: without one the cover is derived near the start,
+   usually a zoom on a navigation control under the first caption.
+
 7. **Package for the destination**: `references/destinations.md`.
 
 ## Launch kit (one take → every cut of a release)
@@ -251,6 +256,8 @@ when the ask is a release, not one video.
   frame the text, and open the span after the click.
 - Routing the cursor through a hover-triggered menu between beats.
 - A first frame or a last frame that cannot stand alone as a poster.
+- A push with no `still`: the shelf, the watch page and the share card
+  show a frame near the start instead of the result.
 - A frozen opening: a static landing page records as freeze-then-bang;
   trim it or speed it, the story opens near the money shot.
 - A sign-in in `steps`: every step there is in the footage and a typed

package/skills/vos-authoring/SKILL.md

@@ -57,10 +57,15 @@ the first line of `~/.config/vos/credentials`. With one, push:
 
 ```bash
 vos push my-config.json --title "…" --desc "one line" \
-  --prompt "<the person's prompt, as they wrote it>" --wait
+  --prompt "<the person's prompt, as they wrote it>" --still <t> --wait
 # --wait stays until the cover has rendered, then prints the links
 ```
 
+**Set the cover at the payoff.** `--still <t>` (OUTPUT seconds) picks the
+frame the shelf, the thumbnail and the share card show: the result the
+film is about, never the opening. Without it the cover is an early frame,
+before anything has arrived; later pushes keep the one you set.
+
 **Show the prompt that made it.** Pass the person's prompt with `--prompt`
 on the push that creates the vos: the watch page shows it by default, so
 whoever watches sees what was asked. Use their words as they wrote them,
@@ -155,6 +160,8 @@ examples of every major type: `references/examples.md`.
 7. **NO `Date.now()` / `Math.random()`** in frame paths — determinism is the
    contract; derive everything from the timeline's time and `ctx.data`
 8. **NO `onFrame`** for new configs — put all per-frame logic in `onUpdate`
+9. **NO push without `--still`** at the payoff — the default cover is an
+   early frame, before the film has arrived
 
 ## Params and Looks (make it remixable)
 

package/skills/vos-create/SKILL.md

@@ -171,6 +171,11 @@ vos push <file>.json --title "…" --desc "one line" --tags a,b \
 
 `--prompt` shows the person's prompt on the watch page by default: their words as they wrote them, never yours, with no file path, key or email they did not mean to publish. Say it is shown, and that they can take it off from the watch page.
 
+Add `--still <t>` (OUTPUT seconds) on the first push, at the payoff: the
+frame the design is about, never the opening. Without it the cover is an
+early frame, before the composition has arrived; every later push keeps
+the one you set.
+
 Pass `--label` and `--note` on EVERY push, the first one included: a
 create stamps them on v1, and the history is the conversation the human
 reads. The push creates a PRIVATE vos on the key owner's shelf, filed