FORM_ACTIONS.md

Select, check, and press actions

These browser actions are first-class Core nodes. They use the same model.Locator contract as click/fill, participate in normal timeout, retry/failure routing and hooks, and never persist runtime coordinates.

Select

choose_country:
  type: select
  with:
    locator: {engine: js, role: combobox, name: Country, exact: true}
    values: [CN]
    mode: value

• locator and a non-empty values array are required. An exact template may supply the array at runtime.
• mode is value (default) or label. Matches are exact; labels are whitespace-normalized.
• Up to 100 unique matches are accepted. More than one value requires a native <select multiple>.
• Core re-locates a native <select>, rejects disabled/wrong/missing options, applies the selection through the current page CDP session, dispatches one bubbling input and change pair only when state changes, then re-locates and returns the actual selected option values.

Check

accept_terms:
  type: check
  with:
    locator: {engine: js, role: checkbox, name: Accept terms, exact: true}
    checked: true

checked is a required strict boolean (or an exact runtime template resolving to boolean). Core reads the current state first. If it already matches, the node succeeds with changed: false and does not click or emit a duplicate change. Otherwise it reuses the humanized CDP click policy, re-reads state, and fails if the target did not reach the requested value. Native checkbox/radio and explicit aria-checked checkbox/radio/switch contracts are recognized; radios cannot be unchecked through this action.

The output contains element, checked, and changed.

Press

submit_search:
  type: press
  with:
    locator: {engine: js, role: textbox, name: Search, exact: true}
    keys: [Control, a]
    repeat: 1

locator and keys are required. keys describes one chord: exactly one named action/navigation key or printable ASCII character plus any unique Alt, Control, Meta, and Shift modifiers. Named keys include Enter, Tab, Escape, Backspace, Delete, Insert, arrows, Home/End, PageUp/PageDown, Space, and F1–F12. Use fill for arbitrary or secret text. repeat defaults to 1 and is bounded to 1–100.

Core re-locates and focuses the element in the page, then sends paired CDP Input.dispatchKeyEvent events to that Chrome target only. Each repetition sends modifier keydowns in declaration order, main keydown/main keyup, then modifier keyups in reverse order. It has no host-global keyboard implementation or fallback. Repeat delays obey the run context; cancellation stops future events and best-effort main/modifier keyups prevent a partially dispatched chord from contaminating later actions.

Recording

The injected recorder captures native select changes as select, checkbox or radio changes as check, and command/navigation keydown events as press. Printable typing remains a coalesced fill; password characters are never recorded as press events. Consecutive identical press events become repeat. A click immediately followed by a fill/select/check event for the same locator is folded during workflow generation so replay does not perform the same user operation twice. Generated nodes retain locators and never store coordinates.

Recorder binding input is a trust boundary. JSON decode failures, payloads over 64 KiB, unknown action types, invalid action URLs, and the 10,000-event limit produce a payload-free recorder.Rejection. Embedders can consume live rejections through Recorder.OnRejected and inspect cumulative per-reason snapshots through Recorder.Rejections(). Stable reasons are invalid_json, payload_too_large, unknown_type, invalid_url, and event_limit. Rejections contain only reason, cumulative count, and timestamp—never the raw payload, decoded value, URL, locator, or secret.

The Studio control plane adds invalid_action when a decoded event fails the canonical node contract (for example, a check event without a boolean state). It exposes all rejected events as payload-free SSE diagnostics and review warnings; they never enter the executable draft.