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

```json
{
  "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](INTEGRATION.md) and [task template](../examples/browser-task.json).