actions.json
The flow recipe: steps, selectors, how pacing becomes the zoom plan, and how an agent-browser walk becomes one.
The flow recipe: steps, selectors, how pacing becomes the zoom plan, and how an agent-browser walk becomes one.
actions.json is the flow recipe: the script vos record drives the page
with. It is small on purpose; the craft is in the pacing.
{
"url": "https://target.example",
"viewport": { "width": 1280, "height": 720 },
"steps": [
{ "do": "wait", "ms": 800 },
{ "do": "hover", "selector": "a[href='/pricing']", "ms": 700 },
{ "do": "click", "selector": "#cta" },
{ "do": "type", "selector": "input[name=email]", "text": "demo@example.com" },
{ "do": "scroll", "dy": 400 },
{ "do": "move", "x": 640, "y": 320 }
]
}wait · hover · click · type · press · scroll · move · drag ·
paste (drag is press-move-release: slide a range input, drag a canvas element, move a
timeline clip; start is a selector center or x/y, end is tx/ty,
eased over ms).
type takes replace: true, which selects the field's value first so the
typing replaces it (a form that opens filled in), and at: "end" or
"start", which puts the caret there before the first character (a code
editor line typed at its end). press presses one named key (Escape,
Enter, Tab, Backspace, Delete, the arrows, Home, End,
PageUp, PageDown, Space), with no click: an Escape closes what a
click opened, an Enter submits what was typed.
A whiteboard, a design tool or a timeline takes more than a click.
press takes keys: a chord ("Shift+D", "Mod+Z", where Mod is Meta
on macOS and Control elsewhere), a plain key ("r", a tool's shortcut) or
a sequence (["v", "Escape"]). drag takes modifiers held for the whole
drag, and path: viewport points inline or in a file beside the script,
drawn with a pen when the points carry pressure. click takes count: 2
or 3, button: "right" or "middle" and modifiers, and click and
hover take a viewport point (x, y) instead of a selector. paste
pastes text or a file (an image, an SVG) the way a person's ⌘V does.
"settle": true, on a step or on the whole script, waits after a gesture
until the page has stopped changing, so a heavy canvas finishes one stroke
before the next. A hosted recording refuses a paste and a path read from a
file.
The take starts once the first page has stopped changing ("ready": "dom",
the default); "ready": "networkidle" waits for the network instead.
Three steps are not gestures. expect checks the page on camera with no
cursor move (selector, text, gone or js), and a condition that never
holds is a skip. js reads what an app keeps in script rather than in the
page: { "do": "expect", "js": "window.app.count()", "equals": 14 } holds
when the value equals 14, and a miss says what the app had. await takes
the same in until. await waits off camera for something slow, a render or a
deploy: the capture stops, until is polled up to timeout seconds (600),
and the footage runs straight from the moment before the wait to the moment
after. download keeps a file the page makes in the take's outputs/.
A click, press or type that costs something real (credits, a purchase,
a message sent) carries "guard": "spend" and an id. A rehearsal hovers
it and never presses it, and vos record presses it only with
--confirm <id>. A hosted recording refuses a guarded step and a download.
Any step may carry read: "<selector>": the recorder keeps that element's
words once the step has settled (meta.steps[].text; a field's value, or
on a click what the click opened), and every step keeps the page it left
(meta.steps[].url). A layer then quotes the take instead of a second run
of the flow.
A gesture step may carry "zoom": true, marking it as its beat's payoff:
vos plan --zooms per-beat keeps one zoom per captioned beat, on that
step. "zoom": false means never zoom there. A file the script pastes
travels with a pushed take, and vos fetch --media brings it back, so the
take records again from anywhere.
peers puts other people on the page, off camera: each peer is its own
browser and sign-in, driven by its own steps, each starting with or
after a step of the take. Only the take's page is filmed, so what a peer
does reaches the footage through the app's own sync. A hosted recording
refuses a js check and peers.
Prefer stable selectors: a[href='...'], ids, roles. Never nth-child
chains; they break on the first layout change.
vos validate actions.json checks a script without running anything.
The agent that verified a feature in agent-browser already walked the
product. vos actions from-agent-browser steps.jsonl turns that walk into
the script, so the take needs no second one.
agent-browser's --json result does not say what ran (scroll answers
{"scrolled":true}), so keep each command beside its result. A shell
function does it per call, and a whole path run as one
agent-browser batch … --json already has the shape:
ab() { agent-browser "$@" --json | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{const r=JSON.parse(s);process.stdout.write(JSON.stringify({command:process.argv.slice(1),...r})+"\n")})' -- "$@" >> steps.jsonl; }
ab open https://target.example; ab snapshot -i -u; ab click @e27; ab wait 800
vos actions from-agent-browser steps.jsonl --out actions.json
vos record --actions actions.json --out take --strictRefs (@e27) resolve through the last snapshot -i before them, to a
role and name selector (role=link[name="Docs"]); -u gives links their
href. CSS targets pass through. fill and type become type,
press Enter a newline into the last field, scroll and mouse move
their steps, set viewport the viewport, the first open the URL.
What the recorder cannot follow is named in the output, never dropped: a
shortcut key, a drag, a coordinate click, a second open, a step that
failed in the walk. Read the notes, write those steps by hand, then record.
The planner reads your dwells and your typing, so how you pace the flow is how the camera will move:
wait of at least 700ms, so hydration finishes and the first
frame is settled.type step earns a held frame on its field.
The click into the field opens the span, and the camera releases after the
last character. About 0.6s or more of typing qualifies, so pace delayMs
like a person (60 to 90ms), not a paste.ms on the step sets
it). A gesture runs by the clock, so a slow page costs samples, not
seconds, and a take runs as long as the script asks plus the gestures.
vos record ends with a pace line saying what the script asked, what the
gestures added and what the page cost.Footage resolution equals the viewport. If you want a 2K video, record at
2560x1440. Decide at record time; upscaling later is dishonest, and
vos validate warns when an export preset exceeds the footage.
Give load-bearing steps an id ({ "do": "click", "selector": "#cta", "id": "cta" }). The recorder writes down when each step ran, and a cut
anchored to a step id follows it through re-records even after the script
gains or loses neighbouring steps. See
Every release for the loop this enables.
Every field, generated from schema/actions.schema.json (what
vos validate enforces); step rows are grouped by verb, so steps[click].*
is the shape of a click step. A * marks a required field.
| field | type | description |
|---|---|---|
| url | string | Page to record (overridable with --url). |
| app | string | A desktop app to record in place of a page: its name or bundle id (overridable with --app; macOS). Selectors are then in the desktop dialect: a role, then what the element is called or its accessibility identifier, e.g. button[name='Save'], textfield[id='title'], toolbar > button[name*='Share'], button[name='Delete']:nth(1). vos look --app lists them. A desktop script takes no url, mask, setup, teardown, ready or peers, and its steps are wait, hover, click, type, press, scroll, move, drag and expect. |
| onSkip | "stop" | "continue" = "stop" | A DESKTOP script's answer to a step that missed (an element that never appeared, an expect that never held, a disabled control): stop ends the take there, continue goes on. Default stop, because the keys of the steps after a miss land wherever focus is, and an app cannot be thrown away as a page can. Not a page script's field. |
| viewport | object | |
| viewport.width* | integer 320.. = 1280 | |
| viewport.height* | integer 240.. = 720 | |
| setup | array | Run BEFORE the camera rolls, after the first navigation: a sign-in form, a cookie banner, an onboarding tour. Plain actions with no cursor, no frames, no pace and nothing in meta.steps; then the recorder opens `url` again and the take begins where the setup left it. A selector that never appears fails the take before anything is recorded (exit 2). A `type` step's text may be { "env": "NAME" }, read at run time and never logged or stored; a literal typed into a password field is refused, because actions.json is committed and pushed. |
| teardown | array | Run AFTER the take, off camera, with the same verbs and rules as setup: what the take created in the product (an API key, a project, an invite) removed again, so a rehearsal or a re-record leaves the account as it found it. The steps run once the screencast has stopped, on the take's own page and session, after a --dry-run rehearsal too, and also when the take stops early or throws after its first step ran. Nothing of them is captured or written to meta.steps. Bounded at 60 s in all. A step that fails stops the teardown and is reported (the --json done event's `teardown`), and never fails the take or changes its exit code. A { "env": "NAME" } the shell does not hold refuses the take before it begins. |
| ready | "dom" | "networkidle" = "dom" | 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 | array | 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. |
| mask[].selector* | string | |
| mask[].as | "blur" | "text" = "blur" | blur the element, or swap its words for `text`. A form control is always blurred: writing into an input would change what the app submits. `text` is for IDENTIFIERS (an email, a name, an account id), never for product copy or numbers. |
| mask[].text | string | shown instead, with as: "text" |
| settle | boolean = false | 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* | array | |
| steps[wait].do* | "wait" | |
| steps[wait].ms* | number 0.. | |
| steps[wait].id | string | 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. |
| steps[wait].caption | string | 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 |
| steps[wait].read | string | 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 |
| steps[wait].zoom | false | false: the wait is watched whole. The planner proposes nothing over it, whatever the pointer does meanwhile (a long task, a result arriving). true is refused: a wait shows nothing to zoom on |
| steps[hover].do* | "hover" | |
| steps[hover].selector | string | the element whose centre the pointer goes to; or x and y instead |
| steps[hover].x | number 0.. | with y: a viewport point in CSS px, for a spot no selector names (a place on a canvas); takes no selector |
| steps[hover].y | number 0.. | |
| steps[hover].ms | number 0.. = 700 | Dwell — parked cursor becomes a zoom signal. |
| steps[hover].settle | boolean | 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 |
| steps[hover].id | string | 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. |
| steps[hover].caption | string | 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 |
| steps[hover].zoom | boolean | the cut's camera on this step: true marks it as its beat's payoff (vos plan --zooms per-beat keeps the zoom on it and only it), false means never zoom here (the planner's proposal on it is rejected); the planner still decides level and focus |
| steps[hover].read | string | 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 |
| steps[click].do* | "click" | |
| steps[click].ms | number 0.. | 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. |
| steps[click].selector | string | the element whose centre the pointer goes to; or x and y instead |
| steps[click].x | number 0.. | with y: a viewport point in CSS px, for a spot no selector names (a place on a canvas); takes no selector |
| steps[click].y | number 0.. | |
| steps[click].count | 1 | 2 | 3 = 1 | 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 |
| steps[click].button | "left" | "right" | "middle" = "left" | the button pressed: right opens a context menu |
| steps[click].modifiers | "Alt" | "Shift" | "Meta" | "Control" | "Mod"[] | held for the press (a Shift-click adds to the selection) and released after it, whatever happens; Mod is Meta on macOS, Control elsewhere |
| steps[click].settle | boolean | 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 |
| steps[click].id | string | 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. |
| steps[click].caption | string | 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 |
| steps[click].zoom | boolean | the cut's camera on this step: true marks it as its beat's payoff (vos plan --zooms per-beat keeps the zoom on it and only it), false means never zoom here (the planner's proposal on it is rejected); the planner still decides level and focus |
| steps[click].read | string | 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 |
| steps[click].guard | "spend" | 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 |
| steps[type].do* | "type" | |
| steps[type].ms | number 0.. | the settle after the last character, ms (default 150) |
| steps[type].selector | string | |
| steps[type].text* | string | |
| steps[type].delayMs | number 0.. = 40 | |
| steps[type].focus | boolean = true | 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. |
| steps[type].settle | boolean | 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 |
| steps[type].id | string | 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. |
| steps[type].caption | string | 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 |
| steps[type].zoom | boolean | the cut's camera on this step: true marks it as its beat's payoff (vos plan --zooms per-beat keeps the zoom on it and only it), false means never zoom here (the planner's proposal on it is rejected); the planner still decides level and focus |
| steps[type].read | string | 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 |
| steps[type].replace | boolean = false | select the field's value before typing, so what is typed replaces it: a form that opens filled in, a search box holding the last query |
| steps[type].at | "end" | "start" | 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 |
| steps[type].guard | "spend" | 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 |
| steps[press].do* | "press" | |
| steps[press].key | "Escape" | "Enter" | "Tab" | "Backspace" | "Delete" | "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Home" | "End" | "PageUp" | "PageDown" | "Space" | |
| steps[press].keys | variant | 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 |
| steps[press].selector | string | the element the key is about: the ping and the step's rect are its, with no click |
| steps[press].ms | number 0.. | the read after the key, ms (default 150), held from the page's last visual change like a click's |
| steps[press].settle | boolean | 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 |
| steps[press].id | string | 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. |
| steps[press].caption | string | 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 |
| steps[press].zoom | boolean | the cut's camera on this step: true marks it as its beat's payoff (vos plan --zooms per-beat keeps the zoom on it and only it), false means never zoom here (the planner's proposal on it is rejected); the planner still decides level and focus |
| steps[press].read | string | 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 |
| steps[press].guard | "spend" | 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 |
| steps[scroll].do* | "scroll" | |
| steps[scroll].ms | number 0.. | the settle after the scroll lands, ms (default 200) |
| steps[scroll].dy* | number | |
| steps[scroll].settle | boolean | 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 |
| steps[scroll].id | string | 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. |
| steps[scroll].caption | string | 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 |
| steps[scroll].read | string | 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 |
| steps[move].do* | "move" | |
| steps[move].x* | number 0.. | |
| steps[move].y* | number 0.. | |
| steps[move].settle | boolean | 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 |
| steps[move].id | string | 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. |
| steps[move].caption | string | 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 |
| steps[move].read | string | 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 |
| steps[drag].do* | "drag" | |
| steps[drag].selector | string | |
| steps[drag].x | number 0.. | |
| steps[drag].y | number 0.. | |
| steps[drag].tx | number 0.. | |
| steps[drag].ty | number 0.. | |
| steps[drag].path | variant | 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 |
| steps[drag].modifiers | "Alt" | "Shift" | "Meta" | "Control" | "Mod"[] | held from the press to the release (Alt-drag to duplicate, Shift to constrain); Mod is Meta on macOS, Control elsewhere |
| steps[drag].ms | number 0.. = 700 | the travel of a straight drag, or of an untimed path (default 700) |
| steps[drag].settle | boolean | 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 |
| steps[drag].id | string | 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. |
| steps[drag].caption | string | 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 |
| steps[drag].zoom | boolean | the cut's camera on this step: true marks it as its beat's payoff (vos plan --zooms per-beat keeps the zoom on it and only it), false means never zoom here (the planner's proposal on it is rejected); the planner still decides level and focus |
| steps[drag].read | string | 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 |
| steps[expect].do* | "expect" | |
| steps[expect].selector | string | |
| steps[expect].text | string | |
| steps[expect].gone | string | |
| steps[expect].enabled | boolean | with selector: wait for the element to be enabled (true) or disabled (false) |
| steps[expect].js | string | a JavaScript expression evaluated in the page (a promise is awaited): the check holds when its value is truthy, or, with equals, when its value equals that one |
| steps[expect].equals | with js: the value the expression must answer, compared as JSON | |
| steps[expect].timeout | number = 5 | seconds to wait for the condition |
| steps[expect].id | string | 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. |
| steps[expect].caption | string | 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 |
| steps[expect].read | string | 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 |
| steps[expect].zoom | false | false: the wait is watched whole. The planner proposes nothing over it, whatever the pointer does meanwhile (a long task, a result arriving). true is refused: a wait shows nothing to zoom on |
| steps[await].do* | "await" | |
| steps[await].until* | object | |
| steps[await].until.selector | string | |
| steps[await].until.text | string | |
| steps[await].until.gone | string | |
| steps[await].until.js | string | a JavaScript expression evaluated in the page (a promise is awaited): holds when its value is truthy, or, with equals, when its value equals that one. A hosted take refuses it. |
| steps[await].until.equals | with js: the value the expression must answer, compared as JSON | |
| steps[await].timeout | number = 600 | the most seconds to wait |
| steps[await].poll | number = 2 | seconds between looks |
| steps[await].reload | boolean = false | reload the page between looks |
| steps[await].onTimeout | "fail" | "continue" = "fail" | fail: the take stops there, exit 1; continue: the capture resumes and the skip records timedOut |
| steps[await].id | string | 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. |
| steps[await].caption | string | 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 |
| steps[await].read | string | 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 |
| steps[download].do* | "download" | |
| steps[download].selector | string | |
| steps[download].src | string | a selector (the same grammar as every other step) of a video, audio or img element |
| steps[download].as | string | the file name inside outputs/ (a plain name: no path separator, no ".."); absent, the name the page suggested |
| steps[download].id | string | 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. |
| steps[download].caption | string | 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 |
| steps[download].read | string | 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 |
| steps[paste].do* | "paste" | |
| steps[paste].selector | string | the element to paste into, clicked first |
| steps[paste].text | string | the words to paste |
| steps[paste].file | string | 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 |
| steps[paste].ms | number 0.. | the read after the paste, ms (default 150), held from the page's last visual change like a click's |
| steps[paste].settle | boolean | 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 |
| steps[paste].id | string | 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. |
| steps[paste].caption | string | 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 |
| steps[paste].zoom | boolean | the cut's camera on this step: true marks it as its beat's payoff (vos plan --zooms per-beat keeps the zoom on it and only it), false means never zoom here (the planner's proposal on it is rejected); the planner still decides level and focus |
| steps[paste].read | string | 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 |
| peers | array | Other people on the page, OFF CAMERA: each a browser context of its own (its own storage state, so its own user, or signed out) on the same url, driven by its own steps. Only the take's page is filmed and only the take's steps make the cursor track; what a peer does reaches the footage through the app's own sync (its presence, its remote cursors, the shape it drew). A peer step starts with a take step (`with`, as it starts) or after one (`after`, as it ends), named by id, else right after the peer's previous step (the first, as the camera rolls). The take never waits on a peer: wait for what the peer's work shows with the take's own expect or await. A hosted take refuses peers. |
| peers[].id* | string | a short word lines and meta.peers name the peer by |
| peers[].url | string | the page the peer opens (http or https); absent, the take's url |
| peers[].viewport | object | |
| peers[].viewport.width* | number | |
| peers[].viewport.height* | number | |
| peers[].storageState | string | a Playwright storage state file (the second person's sign-in), by a path from the actions file's directory or an absolute one. Opened by the browser only: never copied into the take, never uploaded; a pushed script keeps its file name only. Absent, the peer is signed out. A peer that lands on a sign-in refuses the take. |
| peers[].steps* | array | The peer's steps: the take's own step shapes (see steps), for wait, move, hover, click, type, press, scroll, drag (path inline only) and expect, without guard, read, caption or settle, plus when each starts. Every step is bounded like a take step; a miss is a skip listed with the take's (peer set), which --strict fails on. |
| peers[].steps[].do* | "wait" | "move" | "hover" | "click" | "type" | "press" | "scroll" | "drag" | "expect" | |
| peers[].steps[].with | string | start as the take's step with this id starts: the two run together |
| peers[].steps[].after | string | start once the take's step with this id has ended |
| peers[].steps[].id | string |