docs/ACTIONS.md

Browser action reference

The host supplies an explicit task contract: URL, allowed origins, selectors, labels, desired values, optional preconditions and success conditions. NanoJev-Web chooses an action ID. The executor re-observes the page before executing it and rejects stale observations, ambiguous targets and disallowed navigation.

Action	Executor behavior	Host-supplied data / boundary
fill	Replace an input or textarea value	selector, value; text, email, telephone, URL, number, date, time and datetime-local. Native temporal segments use keyboard input.
type	Focus, move to the end and type text	value; provide finalValue when appending to existing content.
clear	Empty the target input	Explicitly permitted target.
select	Select one native option	Option value.
multiselect	Select several native options	Array of option values.
check / uncheck	Set a checkbox state	Explicit desired boolean state.
radio	Click the assigned radio option	Correct option is supplied by the host.
click	Click an allowed element	Explicit purpose and expected postcondition when needed; supports switches through aria-checked.
open	Click a reveal control	Opens a supplied dropdown/dialog trigger; it does not invent a URL.
option	Click a custom dropdown option	Supplied option selector and postcondition.
hover	Hover over an element	Expected revealed state should be supplied.
dblclick	Double-click an element	Explicit target and postcondition.
drag	Drag a source to a destination	Source selector, destination selector and expected result.
focus	Focus an allowed control	Use a focused success condition.
press	Send a permitted keyboard key/chord	key; host controls focus. macOS Escape uses agent-browser's documented keyboard stream.
add / remove	Click an allowed add/remove control	Suitable for repeatable form rows with an explicit expected count/state. These are click aliases, not DOM modifications.
link	Click a link	Actual destination must remain in the task's allowedOrigins.
tab	Open an authorized URL or return to an owned parent tab	mode: "open" plus url, or mode: "return"; arbitrary tab discovery is not supported.
upload	Supply an explicitly authorized local file to a file input	value: one path or an array. The host is responsible for authorizing these files.
scroll	Scroll an offscreen target into view	Generated by the observer from an allowed control; it is not a task control operation.
WAIT	Wait for the page's visible busy state to clear	No browser action is invented.
DONE	Finish when the host's visible success condition is met	The host must separately verify saved data and business rules where required.
BLOCKED	Stop for host assistance	No forced click, bypass or automatic substitute model.

Frames: a control may specify a frame selector for a same-origin iframe. The executor enters it for the action and returns to the main frame. frame is context on a control, not a standalone action. Cross-origin frames are outside this release's observation contract.

Observations: snapshots, read-only DOM inspection, screenshots and audit reads belong to the host. They are not extra model actions. Candidate descriptions contain operation, purpose, current value-match state, assignment state, viewport visibility, enabled state and blocking state. Supplied values and selectors remain local.

Conditions: visible, absent, count, text, includes, attribute, property, value, focused, any and all express expected states. Satisfied assigned controls and non-executable offscreen actions are removed from the choice set; the corresponding scroll action can remain. Optional distractors remain available so incorrect selection can be measured.

Unsupported work: arbitrary JavaScript or shell execution, canvas/game control, CAPTCHA bypass, downloads, general file chooser exploration, cross-origin frame reading, autonomous workflow discovery and secret entry. Password fields stop the generic runner; PINs, OTPs and other secrets must stay with a dedicated host helper. Control allowlists do not grant permission for consequential real-world actions.

Minimal task

{
  "name": "contact-test",
  "url": "http://127.0.0.1:9000/contact",
  "allowedOrigins": ["http://127.0.0.1:9000"],
  "controls": [
    {"id":"name","op":"fill","selector":"#name","label":"Name","value":"Test Contact"},
    {"id":"agree","op":"check","selector":"#agree","label":"Use test data"},
    {"id":"save","op":"click","purpose":"submit","selector":"#save","label":"Save"}
  ],
  "success":{"selector":"#status","kind":"text","value":"Saved"}
}

Replace the example URL and selectors with your own authorized page. run.command records evidence in .local/runs/. Define persistence and business checks in your host application. See the integration guide and task template.