actions.json

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 }
  ]
}

The step verbs

wait · hover · click · type · scroll · move · drag (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).

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.

From an agent-browser walk

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 --strict

Refs (@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.

Pacing is the zoom plan

The planner reads your dwells and your typing, so how you pace the flow is how the camera will move:

• Open with a wait of at least 700ms, so hydration finishes and the first frame is settled.
• Hover the things that matter for 700 to 900ms; those dwells become the zooms.
• Typing is a zoom signal: a 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.
• Wait 1200 to 2000ms after navigations, and end with a settle wait; the last frame is the poster.
• Route the cursor away from hover-triggered menus (they open and blur the page behind their scrim); path through page content, not along the nav.
• The recorder adds only the gestures: the pointer's travel, the press, and a short settle after a click, a type or a scroll (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.

Record at the resolution you want

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.

Field reference

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.

Related

• Verbs for record --strict and the loop around it.
• doc.json for what the recording becomes.