@widgex/wgx 0.0.0-stage → 0.4.2

package/python/xactor/man/driving.md

@@ -0,0 +1,168 @@
+# Doing things on a page
+<!-- also: l1, verbs, actions, page-verbs, transitions, drain, click, double_click, type_text, clear_and_type, press, focus, hover, scroll_to, select, navigate, here, wait_for, wait_stable, digest, evaluate, dom_click, dom_fill, upload, get_state, snapshot, screenshot, extract_secret, set_hfactor -->
+<!-- group: Working on a website -->
+
+`use_widget` and `drive` get you onto a page. This is everything you then *do*
+on it.
+
+**The verbs are right here, on `api`.** There is nothing to wrap them in:
+
+```python
+r = await api.use_widget("sentry_tokens")
+print(r["state"], r["transitions"])          # where you landed, and the way out
+
+await api.transition("create_token")
+await api.transition("configure", token_name="ci-deploy")
+```
+
+`api.here()` is the current `PageState` if you want to look before you leap —
+`describe()` lists what each transition does. `api.transition(name, **params)`
+is `(await api.here()).execute(name, **params)`, which is the same thing the
+bare `registry` in scope will give you:
+
+```python
+state = await registry.here(api)
+print(state.describe())
+```
+
+That is the whole shape of a browser task. `registry`, `PageState`,
+`Observation`, `Transition` and `Step` are bound in this shell alongside `api`,
+so a widget's state machine is something you call directly.
+
+This used to be untrue, and a lot of writing still assumes it. The browser ran
+in a second Python process, and reaching it meant shipping source text across
+with `api.browser_exec(session_id, "...")`. That process is gone. If you find
+yourself building a string of Python to run somewhere else, you are working
+from the old model — `browser_exec` now means *another session's* browser and
+nothing else.
+
+## Load a chain; do not stand in it
+
+Actions queue as you write them, in order. Awaiting each one is allowed and
+hands back that action's own record — but it is not required, and one
+`api.drain()` at the end collects the lot:
+
+```python
+api.click(api.find(role="button", like="create token"))
+api.type_text(api.find(role="textbox", right_of="Name"), "ci-deploy")
+api.click(await api.one(role="button", text_exact="Create", under='dialog"Create Token"'))
+report = await api.drain()
+```
+
+The rule, and it is the one thing worth remembering here: **anything that
+answers a question is awaited; anything that acts on the page is not.**
+`api.find` builds a description and runs nothing, so it needs no `await`.
+`api.one` and `api.search` go and look, so they do — passing an un-awaited
+`api.one(...)` hands the action a coroutine instead of an element.
+
+One report comes back for the whole chain: every action with its `outcome`, plus
+`ok` and `failed` counts. An action that cannot resolve its target comes back
+`ambiguous` or `not_found` **with the candidates that tied**, which is what you
+narrow on.
+
+Do not assume a failure halts what follows. A chain of three where the middle
+action is `ambiguous` still runs the third — measured, not inferred. If a later
+step only makes sense once an earlier one worked, await that one:
+
+```python
+first = await api.click(api.find(role="button", like="create token"))
+if not first["ok"]:
+    print("could not open it:", first.get("candidates"))
+else:
+    api.clear_and_type('dialog"Create Token"/textbox"Name"', "ci-deploy")
+    print(await api.drain())
+```
+
+## The verbs
+
+**Locating**: `find` (a deferred search), `search` (run it now, ranked
+candidates), `one` (exactly one or the candidates that tied), `outline` (the
+shape of the page), `snapshot` (the interactive tree, filtered), `digest`.
+
+**Acting**: `click`, `double_click`, `type_text`, `clear_and_type`, `select`,
+`press`, `focus`, `scroll_to`, `hover`, `navigate`, `drain`.
+
+`double_click` is `click` with a count — the two presses land back-to-back at
+one point, so the page sees `dblclick` rather than two clicks. You need it only
+where single and double click on the same element mean different things. If
+there is a button for what the double click does, prefer the button: it is what
+a keyboard user has to press anyway, and it is addressable by name.
+
+**Waiting**: `wait_for`, `wait_stable`. Rarely needed — an action already waits
+for its own target.
+
+**Files**: `upload(target, paths)` attaches files from disk to an
+`<input type=file>` (the input, or the button/drop zone around it) — script
+cannot, so this is the only way. Absolute path or a list of them.
+
+**Other**: `dom_click`, `dom_fill` (for a page that never paints), `evaluate`,
+`screenshot`, `extract_secret`, `get_state`, `set_hfactor` (humanisation
+speed — **higher is faster**; it divides the delays, so 6 is six times quicker
+than 1).
+
+## When you do not know what is there
+
+```python
+print(await api.outline())                       # the shape, cheapest
+hits = await api.search(role="button", like="create")
+for h in hits:
+    print(h.score, h.path, h.text)
+```
+
+Anchor on what is visible when structure is not enough. This is the alternative
+to a screenshot, and it costs nothing:
+
+```python
+api.find(role="textbox", right_of="Name")
+api.find(role="button", in_row='row"prod-key"')
+```
+
+## find or search?
+
+They look alike and are not interchangeable. Neither is legacy.
+
+| | |
+|---|---|
+| `api.find(**kw) -> FindSpec` | **Describes** a search. Runs nothing, costs no round trip, and is resolved by Layer 0 *at the moment the action fires*. |
+| `await api.search(**kw) -> list[Ref]` | **Runs** it now and hands back the ranked candidates, each with its score. |
+| `await api.one(**kw) -> Ref` | Runs it now and insists on exactly one, raising with whatever tied. |
+
+The difference that matters is *when they resolve*. `find` is what lets a chain
+click a button inside a dialog that does not exist yet:
+
+```python
+api.click(api.find(role="button", like="create token"))   # opens the dialog
+api.click(api.find(role="button", text_exact="Create",    # resolved after it opens
+                   under='dialog"Create Token"'))
+```
+
+Had the second line been a `search`, it would have run against the page as it
+was *before* the first click, found nothing, and there would be nothing to act
+on. So: **`find` to act, `search` to look.** Use `search` while you are working
+out what is on a page, and paste the paths it prints into your widget.
+
+## Getting it wrong
+
+**Wrapping it in `browser_exec`.** The commonest mistake, because most examples
+written before the shells merged do exactly that. `api.click(...)` works here.
+Building a string of Python to send somewhere costs a round trip, loses the
+traceback, and is only correct when the browser belongs to another session.
+
+**Bare verbs.** `click(...)` is a `NameError` — every verb is `api.click(...)`.
+
+**Awaiting the wrong half.** Locating is awaited, acting is not. An un-awaited
+`api.one(...)` passes a coroutine where an element belongs.
+
+**Calling `registry.here()` without `api`.** It needs the api object to take its
+snapshot: `await registry.here(api)`.
+
+**Assuming `here()` found something.** It falls back to `UNKNOWN_STATE` when no
+url_pattern matched. Check `state.name` before you execute a transition on it.
+
+**Writing selectors when a transition exists.** `state.describe()` lists the
+transitions the widget author tested. Yours is not tested.
+
+## See also
+
+`use_widget`, `drive`, `widget-model`, `finding`, `writing-a-widget`,
+`browser_exec`

package/python/xactor/man/edit_file.md

@@ -0,0 +1,112 @@
+# api.edit_file(path, old_string, new_string, replace_all=False, new_tab=False) -> str
+<!-- group: Coding -->
+
+Replace exact text in a file. Gated. **Reports failure by returning a string.**
+
+The single most important thing on this page: `edit_file` does **not raise** when
+the edit does not apply. It returns a string beginning `Error:` and leaves the
+file untouched. Code that ignores the return value cannot tell a successful edit
+from one that never happened.
+
+## Options
+
+- **`path`** — absolute, or relative to the shell's cwd (`api.cd` moves it).
+- **`old_string`** — the exact text to find. Byte-for-byte: whitespace,
+  indentation and line endings all count. It is a literal, not a regex.
+- **`new_string`** — what replaces it. May be `""` to delete.
+- **`replace_all`** — `False` (default) replaces the first occurrence and
+  *refuses* if there is more than one. `True` replaces every occurrence.
+- **`new_tab`** — accepted and ignored. See `write_file`.
+
+The file is read as UTF-8 and written back with `\n` line endings.
+
+## Returns
+
+A string, always. There are four of them:
+
+| Return | Meaning |
+|---|---|
+| `Replaced 1 occurrence(s) in <path>` | The edit landed. |
+| `Replaced N occurrence(s) in <path>` | `replace_all=True`, N sites changed. |
+| `Error: old_string not found in <path>` | Nothing changed. |
+| `Error: old_string found N times in <path>. Use replace_all=True or provide more context to make it unique.` | Nothing changed. |
+
+Only a genuinely broken file operation raises — a missing file is
+`FileNotFoundError`, an undecodable one `UnicodeDecodeError`. Permission being
+declined raises `PermissionError`.
+
+## Examples
+
+Check the result. Every time:
+
+```python
+r = await api.edit_file("src/app.py", "DEBUG = True", "DEBUG = False")
+if r.startswith("Error:"):
+    return f"edit did not apply: {r}"
+return r
+```
+
+Several edits in one exec, stopping at the first that fails:
+
+```python
+edits = [
+    ("timeout = 30", "timeout = 120"),
+    ("retries = 1", "retries = 3"),
+]
+done = []
+for old, new in edits:
+    r = await api.edit_file("src/config.py", old, new)
+    if r.startswith("Error:"):
+        return {"applied": done, "failed_on": old, "why": r}
+    done.append(old)
+return {"applied": done}
+```
+
+Renaming a symbol everywhere in one file:
+
+```python
+return await api.edit_file(
+    "src/util.py", "getCwd", "getCurrentWorkingDirectory", replace_all=True,
+)
+```
+
+## Getting it wrong
+
+**Ignoring the return value.**
+
+```python
+# Wrong — this reports success whatever happened.
+await api.edit_file("a.py", "foo", "bar")
+return "done"
+
+# Right.
+r = await api.edit_file("a.py", "foo", "bar")
+return r          # or branch on r.startswith("Error:")
+```
+
+**Pasting `old_string` out of `api.read_file` output.** `read_file` returns
+`f"{n:>6}\t{line}"` — six columns of line number and a tab in front of every
+line, and trailing whitespace stripped off the end. That text can never match
+the file. Read the file to *find* the edit, then write `old_string` as the file
+actually contains it. See `man('read_file')`.
+
+**Reaching for `replace_all=True` to get past the "found N times" error.** That
+error is telling you the anchor is ambiguous, and `replace_all` changes all N
+sites rather than the one you meant. If you want one, widen `old_string` with a
+line above or below until it is unique. Use `replace_all` only when changing
+every occurrence is the actual intent.
+
+**Chaining edits whose anchors overlap.** Each call re-reads the file, so a
+second edit whose `old_string` covers text the first one rewrote silently
+returns `Error: old_string not found`. Order the edits so they do not overlap,
+or write the whole file with `api.write_file`.
+
+**Using it to create a file.** `edit_file` requires the file to exist and
+raises `FileNotFoundError` otherwise. `api.write_file` creates, including any
+missing parent directories.
+
+## See also
+
+`write_file`, `read_file`, `permissions`, `xylon` (edits are journalled, so
+they appear in `xylon_get_diff` and can be reverted — `api.bash` changes are
+not)

package/python/xactor/man/finding.md

@@ -0,0 +1,194 @@
+# Finding things on a page
+<!-- also: find, one, search, outline, refs, uid, path -->
+<!-- group: Working on a website -->
+
+You know what you want. The page is graphical. This is the bridge.
+
+The hard part of driving a website is not clicking — it is *locating*. So
+locating and acting are separate verbs, and the engine will rank candidates for
+you but will never pick between close ones on your behalf. That decision needs
+what you know and it does not have.
+
+## Naming an element
+
+A **uid** — short, content-derived, `e7f3a1` — or a **path**:
+
+```
+main/table/row"prod-key"/button"Delete"
+dialog"Create Token"/button"Create"
+form#login/textbox"Username"
+```
+
+Both resolve — **as the thing you hand to an action**, not as an argument to
+the search verbs:
+
+```python
+await api.click("e7f3a1")                      # a uid, straight to the action
+await api.instruct("Click Save.", target="e7f3a1")
+await api.one(role="tab", like="Providers")    # keyword spec, never a string
+```
+
+`find` and `one` take a **keyword spec** and nothing positional, so
+`api.one('tab"Providers"')` raises *"takes 1 positional argument but 2 were
+given"* — an error that says what you did and not what to do instead. If you
+already have a uid or a path you do not need `one` at all: pass it to the action.
+
+A path runs through the page's *structure*, not its DOM: wrapper
+`div`s are invisible, so a framework inserting one changes nothing. Landmarks,
+tables and their rows, lists and their items, dialogs, and interactive controls
+are what make up a segment.
+
+Nothing is written into the page. A reference is a **description**, re-derived
+from the live DOM every time it is used — so a stale one matches nothing, or
+matches several, and both are errors you see. It can never quietly resolve to
+the wrong element.
+
+> **A uid is a memory. A path is an assertion.**
+> A uid identifies something you observed. A path is a claim about the page as it
+> is right now. `main/dialog"Confirm"/button"Yes"` *should* resolve against
+> whatever dialog is open when you use it.
+
+## The four verbs
+
+### `api.find(**kw) -> FindSpec`
+
+Describes a search **without running it**. Put it inside an action:
+
+```python
+api.click(api.find(role="button", like="create token"))
+```
+
+Every verb is a method on `api`; there are no bare functions in this scope.
+`find` needs no `await` because it runs nothing — it is a description, and
+Layer 0 resolves it when the action fires.
+
+This is the form to reach for by default. It costs nothing to build, and it
+resolves against the page as it will be *when the click happens* — which is how
+you write a chain that opens a dialog and then clicks a button inside it, in one
+pass, before the dialog exists.
+
+### `await api.search(**kw) -> list[Ref]`
+
+Runs it now and hands back the ranked candidates. **Zero results is an ordinary
+answer**, not an error — "I cannot find it" is the normal case here, and it is
+information.
+
+```python
+for r in await api.search(role="button", like="create"):
+    print(r.score, r.path, r.text)
+# 0.90 main/button"Create Token"  'Create Token'
+# 0.90 main/button"Create Team"   'Create Team'
+```
+
+Two things scoring the same is the page telling you the description was not
+specific enough.
+
+### `await api.one(**kw) -> Ref`
+
+Insists on exactly one, and raises with the candidates when it cannot get it.
+The exception body **is** the refinement hint.
+
+### `await api.outline(under=None, depth=2) -> dict`
+
+Roles and names, no geometry. The cheapest way to orient on a page you have
+never seen. Read this before reaching for a screenshot.
+
+## Narrowing
+
+| | |
+|---|---|
+| `role=` | An ARIA role, or a list. `button`, `link`, `textbox`, `row`, `dialog`. Same words the paths use. |
+| `like=` | Approximate text. **Ranked**, not filtered. |
+| `text_exact=` | Exact, after normalisation. |
+| `under=` | Restrict to a subtree. The cheapest and most effective narrowing there is. |
+| `attr=` | `{"data-testid": "row-delete"}` |
+| `state=` | `{"enabled": True}` |
+| `in_view=` | Default `True`. Off-screen matches are excluded **and counted**. |
+| `margin=` | How decisive the ranking must be. Below. |
+
+## Anchoring on what you can see
+
+The reason locating is hard is that the UI is graphical. These let a visual
+intuition become a structural query, with no picture involved:
+
+```python
+api.find(role="textbox", right_of="Name")          # the field beside a label
+api.find(role="button",  in_row='row"prod-key"')   # the one in that table row
+api.find(role="button",  below='heading"Danger"')
+api.find(role="link",    near='text"Billing"')
+```
+
+`near`, `above`, `below`, `left_of`, `right_of`, `in_row`, `in_section`.
+
+The anchor may be a ref, a path, **or just the visible text of a label**. That
+last form matters: a bare `<span>Name</span>` is not interactive, so it is not
+itself addressable — but it is exactly what a person would point at.
+
+## The margin
+
+Layer 0 ranks. Whether the winner is clear enough to act on is yours to set:
+
+```python
+api.click(api.find(role="button", like="create token"))          # default 0.15
+api.click(api.find(role="button", like="create", margin=0))      # take the top
+api.click(api.find(role="button", like="create", margin=1.0))    # sole match only
+```
+
+- **`0`** — always take the top rank. You are certain; you do not want a gate.
+- **`0.15`** (default) — act when the winner is clear, hand back the tie when it
+  is not.
+- **`1.0`** — act only when nothing else matched at all.
+
+When the gate does not open, the action reports `ambiguous` and the report
+carries the candidates. That is not a failure to route around; it is the page
+telling you which two things your description could not separate.
+
+Scores are a fixed ladder, so you can predict them: exact `1.00`, prefix `0.90`,
+word-boundary substring `0.80`, substring `0.70`, token overlap `0.30–0.60`,
+fuzzy below that. Disabled costs ×0.85, off-screen ×0.95.
+
+## Modals are handled for you
+
+While an `aria-modal` dialog is open, everything behind it is **inert and
+excluded**. That is not a heuristic — the browser genuinely will not deliver a
+click out there. So `find(role="button", like="Create")` with a dialog open
+returns one result, not two. Pass `include_inert=True` to see past it.
+
+## What you are not being shown
+
+Every result carries `omitted`:
+
+```python
+{"offscreen": 12, "inert": 3, "nonInteractive": 40, "overLimit": 0}
+```
+
+Silent filtering is how an agent gets stuck looking for something that was there
+all along. If the thing you want is missing, check this before concluding the
+page does not have it — then widen with `in_view=False` or `include_inert=True`.
+
+## Getting it wrong
+
+**Taking `search()[0]` without looking at the scores.** If the top two are level,
+you have just guessed. That is what `margin` exists to stop.
+
+**Awaiting `find()`.** It is a description, not a call. `search()` is the one
+that runs.
+
+**Hand-writing a path from a screenshot.** Paths match the *computed accessible
+name*, which is not always the visible text. Get paths from `search()`.
+`outline()`'s `seg` is only the last segment (`button"Settings"`), not a path:
+pass its `uid` instead.
+
+**Using `xh_3`.** That scheme is gone. It was a page-resident counter that
+dangled silently whenever a framework re-rendered.
+
+**Screenshotting to find something.** An image cannot be searched, and looking at
+one costs a round trip through you. Spatial predicates cost one round trip
+through the page.
+
+**Holding a uid across a navigation.** It will be refused. Paths survive; uids
+are scoped to the document you observed them in.
+
+## See also
+
+`driving`, `widget-model`, `browser-driver`, `drive`, `browser_screenshot`

package/python/xactor/man/fork_agent.md

@@ -0,0 +1,45 @@
+# api.fork_agent(board, session=None) / api.move_agent(board, session=None) -> dict
+<!-- also: move_agent, slots, slot -->
+
+<!-- group: Sessions -->
+
+Put an agent of your task to work on another board, **in the same task**.
+
+A channel is one repository or one drive folder. Work that reaches a second
+one happens in the task's **slot** on that board: a working copy of that
+board's own source, on the task's branch name. A slot is not a new task. It
+shares, with the task's other slots:
+
+- its status and lane, its phases and steps, its title and asks;
+- who may act on it, and the folders approved for it;
+- folder access: an agent in any slot reads and writes every slot's working
+  copy on this machine without being asked.
+
+The task is listed on every board it has a slot on. The slot is made the first
+time it is needed.
+
+```python
+await api.fork_agent("billing")                 # a copy of you, working in #billing
+await api.move_agent("#billing", "session3")    # session3 carries on from #billing
+```
+
+- **fork** starts a new agent there with the conversation so far.
+- **move** does the same and then closes the agent where it was, with a
+  `moved-to` line in its transcript. An agent moving *itself* is closed once
+  its current turn ends; another agent in the middle of a turn is refused.
+
+Both ask the person first. Both also need authority over the task (its
+assignee, its owner, or a manager) and a live board of this project bound to a
+repository or drive folder; a board with no source of its own (`#just me`)
+cannot hold a slot. The refusal says which is missing.
+
+In `wgx` both work the same, with two exceptions that the IDE still handles:
+a project manager moving somebody else's task, and a first slot on a board
+bound to a drive folder, which needs the IDE's folder picker.
+
+`session` is a session id, or a transcript name in your task (`session3`).
+Left out, it is you.
+
+## Returns
+
+`{ "session": <new agent's session id>, "task": "project/repo/issue" of the slot, "mode": "fork" | "move" }`

package/python/xactor/man/glob.md

@@ -0,0 +1,83 @@
+# api.glob(pattern, path=None, include_ignored=False) -> list[str]
+<!-- group: Coding -->
+
+Find files by name pattern. Sorted, capped at 500. Not gated.
+
+## Options
+
+- **`pattern`** — a glob. `*` matches within one path segment, `**`
+  matches across segments, `?` one character, `[abc]` a set.
+- **`path`** — directory to search from. Absolute, or relative to the shell's
+  cwd. Defaults to the cwd.
+- **`include_ignored`** — walk the pruned directories too.
+
+## What it does not walk
+
+The same list `grep` skips — `node_modules`, `.git`, `out`, `dist`, `build`
+and their neighbours, by directory name at any depth. See `PRUNED_DIRS` in
+`stdlib_api.py`, and `grep`'s manual for why it is not only about speed.
+
+The pattern is relative to `path`, never absolute. `api.glob("/etc/*")` does
+not do what it looks like — pass the directory as `path` instead.
+
+## Returns
+
+A sorted `list[str]` of **absolute** paths, **truncated to the first 500**.
+Directories are included, not just files. No matches gives `[]`.
+
+The 500 cap is silent: a list of exactly 500 means you probably have more.
+Narrow the pattern rather than assuming that is all of them.
+
+## Examples
+
+```python
+return await api.glob("**/*.test.ts")
+```
+
+Scoped to a subtree:
+
+```python
+return await api.glob("*.py", path="widgex-ide/extension/python/xactor")
+```
+
+Existence check that does not raise:
+
+```python
+if not await api.glob("package.json"):
+    return "not a node project"
+```
+
+Recent files first, when you care about what changed lately — `glob` sorts by
+name, so ask the shell instead:
+
+```python
+r = await api.bash("git ls-files -m")
+return r["stdout"].splitlines()
+```
+
+## Getting it wrong
+
+**Expecting `*` to cross directories.** `src/*.ts` finds only the files
+directly in `src`. `src/**/*.ts` walks the tree.
+
+**Expecting the results filtered to files.** Directories match too. Filter with
+`api.ls` on the parent, or check by pattern.
+
+**Hitting the cap without noticing.** `len(hits) == 500` is a warning sign, not
+a count.
+
+**Using it to search file *contents*.** That is `api.grep`. `glob` only ever
+looks at names.
+
+**Assuming it respects `.gitignore`.** It does not. It skips a fixed list of
+generated directory names, which covers the usual suspects and is not the same
+thing: anything else your `.gitignore` names still matches. Use
+`api.bash("git ls-files ...")` when you want the tracked set exactly.
+
+**Assuming the prune list is never wrong for your project.** It is by name, so
+a project whose real source lives in `build/` loses it. Pass
+`include_ignored=True` there.
+
+## See also
+
+`grep`, `ls`, `read_file`, `bash`