@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/browser_detach.md

@@ -0,0 +1,50 @@
+# api.browser_detach(target_session_id) -> dict
+<!-- group: Working on a website -->
+
+Give a borrowed browser back, waking whoever is waiting next.
+
+The other half of `browser_attach`. Until you call it, the owner and every other
+session waiting for that browser stays blocked.
+
+## Options
+
+- **`target_session_id`** — the session you borrowed from.
+
+## Returns
+
+```python
+{"status": "detached", "dispatcher_id": str, "held_ms": int}
+```
+
+Detaching something you were not holding is not an error — you get
+`{"status": "detached", "note": ...}`. Only the session that took the lease can
+release it; anyone else gets an error naming the real holder, so one session
+cannot cut another's work short.
+
+Your shell is pointed back at your own browser, if you have one.
+
+## Examples
+
+The shape to use every time:
+
+```python
+r = await api.browser_attach("session-42")
+if r.get("occupied"):
+    return r["error"]
+try:
+    await api.browser_exec(None, "print(await api.outline())")
+finally:
+    await api.browser_detach("session-42")
+```
+
+## Getting it wrong
+
+**Detaching on the happy path only.** An exception between attach and detach
+leaves the browser held with nobody able to take it. `finally` is the point.
+
+**Assuming a turn ending releases it.** It does not. The lease outlives your
+turn; only this call clears it.
+
+## See also
+
+`browser_attach`, `browser_exec`, `sessions`, `browser_plumbing`

package/python/xactor/man/browser_exec.md

@@ -0,0 +1,66 @@
+# api.browser_exec(session_id, code, timeout=None) -> dict
+<!-- group: Working on a website -->
+
+Run Python in **another session's** browser shell. Gated.
+
+Almost certainly not what you want. For your own browser there is nothing to
+wrap: the page verbs and the widget symbols are bound in this shell, so
+`api.click(...)` and `registry` work directly. See `driving`.
+
+```python
+# Your own browser — no browser_exec anywhere.
+await api.use_widget("sentry_tokens")
+state = await registry.here(api)
+state = await state.execute("create_token", token_name="ci-deploy")
+```
+
+This call was once the only way in, because the browser ran in a second Python
+process and its namespace was unreachable from here — `code` was shipped across
+as source text. That process is gone. What is left is the case the name now
+describes: reaching a browser that belongs to a session that is not yours.
+
+## Options
+
+- **`session_id`** — the session whose browser to use. Pass `None` for your
+  own, though if you are doing that you want `driving` instead.
+- **`code`** — Python. `await` is supported at the top level.
+- **`timeout`** — milliseconds. Default 60,000.
+
+## Borrowing someone else's browser
+
+`browser_attach` first, or the tabs are not yours to drive and the call is
+refused. Give it back when you are done, or whoever is queued behind you waits
+for the timeout:
+
+```python
+await api.browser_attach(target_session_id="session-12")
+try:
+    out = await api.browser_exec("session-12", """
+state = await registry.here(api)
+print(state.name)
+""")
+finally:
+    await api.browser_detach(target_session_id="session-12")
+```
+
+## The scope over there
+
+The same names this shell has: `api` with the page verbs on it, plus
+`registry`, `PageState`, `Observation`, `Transition`, `Step`, `asyncio` and
+`json`. `__import__`, `open`, `eval`, `exec`, `compile`, `input` and
+`breakpoint` are blocked, as they are here.
+
+## Getting it wrong
+
+**Using it for your own browser.** A round trip, a lost traceback and a string
+of Python you have to escape, to reach verbs that were already in scope.
+
+**Expecting values back other than through `print`.** What you get is the
+shell's output. Print what you need.
+
+**Skipping `browser_attach`.** Another session's tabs are owned. Reaching for
+them without attaching is refused rather than shared.
+
+## See also
+
+`driving`, `browser_attach`, `browser_detach`, `use_widget`, `widget-model`

package/python/xactor/man/browser_focus_tab.md

@@ -0,0 +1,47 @@
+# api.browser_focus_tab(tab_id) -> dict
+<!-- also: focus-tab, switch-tab -->
+<!-- group: Working on a website -->
+
+Drive a different tab of your session's window.
+
+Brings the tab to the front and repoints your browser shell at it. Whatever you
+were part-way through on the tab you left is still there when you come back — a
+half-filled form stays half-filled.
+
+## Options
+
+- **`tab_id`** — from `api.browser_tabs()`.
+
+## Returns
+
+```python
+{"status": "focused", "tab_id": str, "url": str}
+```
+
+`{"error": ...}` if the tab is not in your window, or if its page has gone.
+
+## Examples
+
+```python
+tabs = (await api.browser_tabs())["tabs"]
+target = next(t for t in tabs if "console" in t["url"])
+await api.browser_focus_tab(target["tab_id"])
+print((await api.browser_exec(None, "print(await api.outline())"))["output"])
+```
+
+## Getting it wrong
+
+**Focusing another session's tab.** You cannot; only your window's tabs are
+addressable. Use `api.browser_attach` to borrow another session's window.
+
+**Forgetting the state registry follows the page.** After focusing, run
+`registry.here(api)` again — the widget state that applied on the old tab says
+nothing about the new one.
+
+**Assuming focus is instant for the user.** It repoints your driver. The user's
+own view is theirs.
+
+## See also
+
+`browser_tabs`, `browser_open_tab`, `browser_close_tab`, `browser_exec`,
+`widget-model`

package/python/xactor/man/browser_hybrid.md

@@ -0,0 +1,47 @@
+# api.browser_hybrid / api.query — withdrawn
+<!-- also: hybrid_snapshot, query, query_one, hybrid -->
+<!-- group: Working on a website -->
+
+Both returned a flat list. Use `find`, `one`, `outline` or `snapshot`.
+
+## Why they went
+
+The list had no containment. Eight "Delete" buttons on eight table rows came
+back as eight identical entries, and nothing in the payload said which row each
+belonged to — so the only way to disambiguate was a screenshot, which is a round
+trip through the model for something the page already knew.
+
+Each node also carried five raw CSS strings (`color`, `bgColor`, `border`,
+`fontWeight`, `opacity`) that nothing read, at roughly forty tokens apiece. A
+console page cost 9 000–25 000 tokens to look at, and one rode along on *every*
+`browser_exec` result whether anyone wanted it or not.
+
+The ids were worse. `xh_3` was a counter stamped into the page as an attribute,
+so a framework re-render destroyed the node and the id silently dangled — or
+matched whatever was minted into that slot next.
+
+## What to use
+
+| Was | Now |
+|---|---|
+| `browser_hybrid(disp)` | `await api.outline()` for the shape, `await api.snapshot()` for the interactive tree |
+| `query(role=..., name=...)` | `await api.search(role=..., like=...)` — ranked, with scores |
+| `query_one(...)` | `await api.one(...)` — exactly one, or the candidates that tied |
+| holding an `xh_3` | a uid (`e7f3a1`) or a path (`main/table/row"prod-key"/button"Delete"`) |
+
+```python
+# was: hits = [n for n in snap["nodes"] if "Create token" in str(n)]
+hits = await api.search(role="button", like="create token")
+
+# was: impossible without a screenshot
+btn = await api.one(role="button", text_exact="Delete",
+                    under='main/table/row"prod-key"')
+```
+
+Calling either raises with this list rather than returning an `AttributeError`,
+because a missing method invites a guess and the guess is usually another name
+that is also missing.
+
+## See also
+
+`finding`, `browser_exec`, `widget-model`, `browser_snapshot`

package/python/xactor/man/browser_open.md

@@ -0,0 +1,50 @@
+# api.browser_open(...) — withdrawn
+<!-- group: Working on a website -->
+
+This call no longer opens anything. It raises, and names its replacements.
+
+```
+api.browser_open() is withdrawn — opening a browser at a bare URL says
+nothing about why.
+  api.widgets()                    what is already modelled
+  api.use_widget(name)             work through one of them
+  api.drive(url, why)              no widget exists for this site yet
+```
+
+It was kept as a refusal rather than deleted on purpose: an agent that calls a
+method which no longer exists gets an `AttributeError` and guesses, while this
+tells it what to call instead. It is deliberately **not** gated — it never opens
+anything, so there is nothing to approve.
+
+## Why it went
+
+A bare URL records the destination and nothing else. The user approving it
+learns where you are going, not what you are going to do there. `use_widget`
+names a written automation; `drive` demands a `why`. Both are things a person
+can consent to.
+
+## What to call
+
+```python
+found = await api.widgets(url)
+match = next((w for w in found if w["matches"]), None)
+if match:
+    return await api.use_widget(match["name"])
+return await api.drive(url, why="what you are there to do, in one line")
+```
+
+## Getting it wrong
+
+**Believing a stale tool description.** An older bundle may still advertise
+`api.browser_open`. The advertisement is wrong; the call is right. This page is
+the only thing that can tell you which is which.
+
+**Retrying it with different arguments.** It ignores all of them and raises
+regardless.
+
+**Reading the raise as a bug.** It is the intended behaviour. There is nothing
+to report.
+
+## See also
+
+`widgets`, `use_widget`, `drive`, `widget-model`

package/python/xactor/man/browser_open_tab.md

@@ -0,0 +1,58 @@
+# api.browser_open_tab(url, background=False) -> dict
+<!-- also: open-tab, new-tab -->
+<!-- group: Working on a website -->
+
+Open a new tab in your session's window and drive it.
+
+The new tab becomes the focused one, so `browser_exec` runs against it from
+then on. The tab you were on stays open and keeps its state — go back with
+`browser_focus_tab`.
+
+## Options
+
+- **`url`** — where to open. `http`, `https` or `file`.
+- **`background`** — open without taking the foreground. The tab is still
+  driven; it just does not steal the user's view. Useful when you are opening
+  several at once.
+
+## Returns
+
+```python
+{"status": "opened", "tab_id": str, "url": str, "shell_status": str}
+```
+
+Or `{"error": ...}` if the page opened but could not be attached to.
+
+## Examples
+
+Keep a reference page open beside the thing you are working on:
+
+```python
+work = (await api.browser_tabs())["focused_tab_id"]
+docs = await api.browser_open_tab("https://docs.example.com/api", background=True)
+# ... read the docs tab ...
+await api.browser_focus_tab(work)
+```
+
+Compare two accounts without losing either:
+
+```python
+a = await api.browser_open_tab("https://console.example.com/org/a")
+b = await api.browser_open_tab("https://console.example.com/org/b")
+```
+
+## Getting it wrong
+
+**Using it as navigation.** To move the *current* tab, navigate inside
+`browser_exec`. Opening a tab per page leaves a pile of them behind.
+
+**Not closing what you opened.** Tabs persist for the life of the session.
+Close the ones you are finished with.
+
+**Expecting the first browser to come from here.** `api.drive` and
+`api.use_widget` are the gated entry points that reach a site and are what the
+user approves. This adds a tab to a window you already have.
+
+## See also
+
+`browser_tabs`, `browser_focus_tab`, `browser_close_tab`, `drive`, `use_widget`

package/python/xactor/man/browser_plumbing.md

@@ -0,0 +1,107 @@
+# Browser plumbing — connect / disconnect / hfactor / load / flush / context
+<!-- also: browser_connect, browser_disconnect, browser_hfactor, browser_load, browser_flush, browser_context, browser -->
+<!-- group: Working on a website -->
+
+The six registry and lifecycle calls. None of them is gated; none is meaningful
+on its own, which is why they share a page.
+
+`use_widget` and `drive` do the connecting and loading for you. These are the
+manual controls for when that is not enough.
+
+## `browser_connect(session_id=None) -> dict`
+
+Attach to a browser CDP target on port 9222 and return a dispatcher. `session_id`
+is inferred from the shell when omitted.
+
+## `browser_disconnect(dispatcher_id) -> dict`
+
+Detach a dispatcher. Requires the dispatcher id — this one is not inferred.
+
+## `browser_hfactor(value) -> dict`
+
+The humanization speed factor. Every dispatcher delay becomes `seconds / value`,
+so **higher is faster**. Default `1.0`, clamped at a minimum of `0.01` seconds
+per delay. `2.0` halves the pauses; `0.5` doubles them.
+
+## `browser_load(name=None, code=None, session_id=None) -> dict`
+
+Load page states into the registry.
+
+- **`name`** — a widget, spelled as `api.widgets()` lists it. The ordinary case.
+- **`code`** — raw Python defining `PageState`s, for a site with no saved
+  widget.
+- Give **one** of them. Neither raises `give either name= ... or code=`; both
+  raises `give name= or code=, not both`.
+- `session_id` is inferred; there is no reason to name your own session.
+
+`use_widget` already loads. Call this directly only when you are assembling
+states by hand.
+
+## `browser_flush(session_id=None) -> dict`
+
+Clear every widget state from the registry. Use it when a stale machine is
+matching pages it should not.
+
+## `browser_context(session_id=None, widget_name=None) -> dict`
+
+What is currently loaded, and the current dispatcher. This is how you find a
+`dispatcher_id` for `browser_hybrid`, `browser_snapshot` or
+`browser_screenshot`.
+
+## Examples
+
+Finding the dispatcher for a capture:
+
+```python
+ctx = await api.browser_context()
+return await api.browser_hybrid(ctx["dispatcherId"])
+```
+
+Loading hand-written states for an unmodelled site:
+
+```python
+await api.drive("https://status.example.com", why="read the incident timeline")
+return await api.browser_load(code=open_states_source)
+```
+
+Speeding up a long scripted sequence:
+
+```python
+await api.browser_hfactor(3.0)      # three times faster
+```
+
+Clearing a registry that is matching the wrong pages:
+
+```python
+await api.browser_flush()
+return await api.use_widget("github")
+```
+
+## Getting it wrong
+
+**Reading `hfactor` backwards.** The commonest mistake with it, and it is worth
+saying twice: it divides the delay, it is not the delay. Higher is *faster* —
+`hfactor=6` finishes in a sixth of the time `hfactor=1` takes, and `0.5` takes
+twice as long. Reaching for a small number to speed a run up does the opposite,
+and reaching for a big one to be gentle on a flaky page makes it much flakier.
+
+**Calling `browser_load` when `use_widget` would do.** `use_widget` loads,
+navigates, and shows the user a named action. Loading by hand skips the
+approval story.
+
+**Passing `browser_load` both `name` and `code`, or neither.** Both raise, with
+the fix in the message.
+
+**Naming your own `session_id`.** It is inferred. Passing it is noise, and
+passing the wrong one is a bug.
+
+**Passing a session id where a dispatcher id is wanted.** `disconnect`,
+`hybrid`, `snapshot` want the dispatcher. `browser_context` has it.
+
+**Flushing mid-task.** Every loaded state goes, including the one you are
+standing in. `registry.here()` will then return `UNKNOWN_STATE`.
+
+## See also
+
+`widget-model`, `driving`, `use_widget`, `drive`, `browser_hybrid`,
+`widgets`

package/python/xactor/man/browser_screenshot.md

@@ -0,0 +1,56 @@
+# api.browser_screenshot(dispatcher_id=None, session_id=None, max_width=None) -> dict
+<!-- group: Working on a website -->
+
+Capture the page as an image you can look at. Gated.
+
+The image is **seen, not queryable**. That single fact decides when to use it:
+for layout, rendering, and confirming that something a human was asked to do
+actually happened — never for finding an element.
+
+## Options
+
+- **`dispatcher_id`** — the dispatcher to capture.
+- **`session_id`** — the session whose dispatcher to use, when you do not have
+  the dispatcher id. Give one or the other.
+- **`max_width`** — capture width in pixels. Default 900. Smaller is cheaper.
+
+## Returns
+
+```python
+{"$image": {...}}
+```
+
+Which arrives as an image, not text. At the default width it costs roughly 675
+tokens.
+
+## Examples
+
+Confirming a human-performed step:
+
+```python
+await api.request_user_action("Please complete the 2FA challenge in the browser.")
+return await api.browser_screenshot(session_id=session_id)
+```
+
+Checking a rendering problem, cheaply:
+
+```python
+return await api.browser_screenshot(dispatcher_id=did, max_width=600)
+```
+
+## Getting it wrong
+
+**Using it to locate something.** You cannot grep an image. `browser_hybrid`
+gives you structure, costs nothing to search, and does not prompt.
+
+**Taking one after every action.** ~675 tokens each, and none of them can be
+referred back to by anything but you looking again.
+
+**Taking one at full width by habit.** `max_width=600` is often enough and
+meaningfully cheaper.
+
+**Passing neither id.** It needs one of `dispatcher_id` or `session_id`.
+
+## See also
+
+`browser_hybrid`, `browser_snapshot`, `request_user_action`, `browser_plumbing`

package/python/xactor/man/browser_snapshot.md

@@ -0,0 +1,52 @@
+# api.browser_snapshot(dispatcher_id) -> dict
+<!-- group: Working on a website -->
+
+Full DOM snapshot: URL, **cookies**, accessibility tree. Gated.
+
+It requires permission for a specific reason — the snapshot includes the page's
+cookies, so it reads the session credentials for whatever site is open. That is
+why it prompts and `browser_hybrid` does not.
+
+Reach for it when you genuinely need the whole document. Most of the time you do
+not.
+
+## Options
+
+- **`dispatcher_id`** — the browser dispatcher to capture.
+
+## Returns
+
+A dict with the page URL, its cookies, and the accessibility tree. Large.
+
+## Examples
+
+When the accessibility tree is the actual question:
+
+```python
+snap = await api.browser_snapshot(dispatcher_id)
+return snap.get("url")
+```
+
+Preferring the cheaper call, which is almost always right:
+
+```python
+return await api.browser_hybrid(dispatcher_id)     # no cookies, no prompt
+```
+
+## Getting it wrong
+
+**Using it to find an element.** `browser_hybrid` returns searchable structure
+without reading credentials and without a prompt. This is the wrong reflex and
+the most common misuse.
+
+**Treating the prompt as bureaucracy.** The user is being asked whether you may
+read their logged-in session's cookies. Do not ask unless you need them.
+
+**Putting the result somewhere it persists.** It contains credentials. It
+belongs in the turn, not in a file.
+
+**Passing a session id.** It wants a *dispatcher* id.
+
+## See also
+
+`browser_hybrid`, `browser_screenshot`, `browser_plumbing`, `permissions`

package/python/xactor/man/browser_tabs.md

@@ -0,0 +1,67 @@
+# api.browser_tabs() -> dict
+<!-- also: tabs, window, browser-window, session-window, tab-ownership -->
+<!-- group: Working on a website -->
+
+The tabs in your session's browser window.
+
+Your session owns a **window** — a set of browser tabs. You can open new ones,
+close them, and move between them freely. No other session can reach any tab in
+your window, and you cannot reach theirs.
+
+## Why a window, and not just a tab
+
+Browsers used to be chosen rather than owned: every session attached to whatever
+tab the browser listed first. Two sessions running at once drove the same tab
+and navigated it out from under each other. Nothing errored — each one saw a
+plausible page and drew confident conclusions about a site it was not looking
+at. A session mapping Supabase decided the site was behind a login wall while
+actually reading another session's Netlify tab.
+
+Owning one tab each was not enough either: a session that opened a second tab
+left it looking unowned, and the next session took it. So the boundary is the
+whole window.
+
+## Returns
+
+```python
+{"tabs": [{"tab_id": str, "url": str, "focused": bool}],
+ "focused_tab_id": str | None}
+```
+
+`focused` marks the tab your `browser_exec` currently runs against. Tabs whose
+page has been closed by hand are dropped before you are answered, so the list
+is what actually exists.
+
+An empty list means you have no browser open yet — `api.drive` or
+`api.use_widget` is how you get the first one.
+
+## Examples
+
+```python
+for t in (await api.browser_tabs())["tabs"]:
+    print("*" if t["focused"] else " ", t["tab_id"][:8], t["url"])
+```
+
+Work two pages at once — the docs and the console:
+
+```python
+console = await api.browser_open_tab("https://dash.example.com/keys")
+docs    = await api.browser_open_tab("https://docs.example.com/api")
+await api.browser_focus_tab(console["tab_id"])
+```
+
+## Getting it wrong
+
+**Expecting to see another session's tabs.** You will not. That is the point.
+`api.browser_attach` borrows another session's window deliberately.
+
+**Holding a `tab_id` across a close.** Ids are not reused, and a closed tab is
+gone. Re-list rather than remembering.
+
+**Assuming the focused tab is what the user is looking at.** Focus here means
+which tab *you* drive. The user may be looking at anything.
+
+## See also
+
+`browser_open_tab`, `browser_focus_tab`, `browser_close_tab`, `browser_attach`,
+`drive`, `use_widget`, `browser_exec`