Skill references

The detail the skill sends an agent to: acting on a page and reading one.

More: inspecting and sessions, Electron, setup and errors.

Acting

Element commands wait up to 5 s for the element (--timeout-ms <ms> for longer, or start --wait-ms <ms> once for a slow app). Besides a ref, --selector and --text, they take --role button --name "Save", --label "Email", --placeholder …, --testid … and --nth <i> (-1 = last). Frames are searched for you; when two frames hold a match, --frame "#billing" (the iframe’s CSS; "#outer >> #inner" for nested ones) looks only there.

What the tool handles for you

• New tabs: a target=_blank link or window.open opens a tab the session adopts and switches to; the response says "new_tabs":[1]. tab-select 0 goes back.
• Dialogs: alert, confirm and prompt are accepted and reported as "dialogs":[{type, message, accepted}]. Run dialog --dismiss first for “Cancel”.
• Navigation: a click that loads a page returns once it is ready; the next command never reads the old page. A page that never finishes loading is used as it is after about 5 s, with "loading": true: wait --text … for what you need.
• Moving and covered elements: a click waits for the element to stop moving and for what covers it (a toast, a sticky bar) to go. If it is still covered, the click fails and names the cover: close that first (a cookie banner needs its own click); click --force sends DOM events anyway. Styled checkboxes and radios are clicked through their label; a hidden input with no label fails at once and names what to click instead.
• Clicks that do nothing: if nothing changed after a click (DOM, focus, value, URL, request, dialog, tab; analytics don’t count), the response carries "no_effect". The page is often not wired up yet, or slow: wait for what the click should show, and click again only if it never comes. Don’t assume the click worked. A click that came before a page that just loaded wired the element up is sent again by navigera once it does ("clicked_again"): don’t click it again yourself.
• Iframes and shadow DOM: refs work in any iframe. --selector, --text and the locators also search iframes (cross-origin ones included) and open shadow roots when the page itself has no match. `–selector “#app >>> x-card

  button“names a path through shadow hosts (whatlocate` writes for an icon button in a web component).

• Files: upload ./doc.txt and screenshot shot.png take paths relative to your current directory.

Reading a page: ax

page "Checkout — Acme" http://shop.test/checkout
- banner:
  - link "Cart 2" [ref=9] url=/cart
- main:
  - heading "Checkout" [level=1]
  - textbox "Full name" [ref=21]
  - combobox "Country" [ref=22] value="Select…" options: "Canada", "Mexico", …
  - group "Shipping speed":
    - radio "Standard (5–8 days)" [ref=24]
    - radio "Express (1–2 days)" [checked, ref=25]
  - Iframe "Card payment":
    - document "Card details":
      - textbox "Card number" [ref=41]
  - button "Place order" [ref=30]

• [ref=N] marks what you can act on: pass the number to click/fill/ select/… (@12, e12 and ref=12 work too). A ref whose element the page drew again (same role, name and place) still works, and the result’s note names the new ref; after a navigation, or when the page changed more than that, the ref is stale: take a fresh ax.
• clickable [ref=N]: <text> is something the page made clickable without saying so (a row, a card, an icon): click it by ref like a button, before reaching for eval. One with no text shows its #id or .class and what the page marks it with (icon="fa-trash", data-tooltip="Archive", img="home.png").
• A cut text ends … (+N chars: get text <ref>): that command reads it all. A snapshot that cut anything says so on its second line. Before a reading or compliance judgment (terms, policies, contracts), read in full: text (the whole page as it reads), text --selector main, or ax --full-text.
• Nesting shows what belongs together (which “Add to cart” sits in which product). Iframes and open shadow DOM are included; links show their url=.
• Collapsed or hidden content (closed <details>, hover menus, inactive tabs) is not in the tree until you open it: click the toggle or hover the menu, then ax again.
• Big page: ax --selector "#results" or ax 57 (a ref), --limit <lines> (default 2000).
• An element on a long page by a word of its name: ax --grep "<word>" prints the lines that mention it under the containers they sit in, with refs to act on (--limit <lines>, 30 by default).
• One fact from a long page (a default, a price, a date): text --grep "<word or phrase>" prints the passages that mention it with the lines around them (--context <lines>, --limit <passages>), a few hundred bytes instead of the page. Several words match in any order when the phrase is nowhere.
• A list, one item a line: text --selector '#items' (quote a selector: an unquoted # starts a shell comment). Many items as data: one eval that returns JSON: navigera -s work eval "() => [...document.querySelectorAll('.item')].map(e => e.innerText)"

Made from skills/navigera/references/acting.md, skills/navigera/references/reading.md.