@reticlehq/server 2.14.0 → 3.2.0

package/docs/tools/query.mdx

@@ -0,0 +1,133 @@
+---
+title: reticle_query
+description: Find elements by Testing-Library semantics. Role, text, label, placeholder, testid, alt, or React component, including inside open shadow roots.
+icon: magnifying-glass
+---
+
+<Warning>
+  **reticle_query is not advertised.** The default surface is the merged nine, so an agent does not see
+  this name. Call **`reticle_look { action: "find" }`** instead. Everything below describes what that call does;
+  only the spelling changed. A call to the old name is answered with the new one, but an
+  `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
+</Warning>
+
+`reticle_query` answers "where is the thing I mean?" without dumping the whole page into your context window. It queries the way a testing library does. By role, label, text, testid. So your agent binds to meaning rather than to DOM structure that a refactor will move.
+
+## Example
+
+```json
+{ "by": "role", "value": "button", "limit": 6 }
+```
+
+Real response from a running app, with four of the six elements trimmed out for length:
+
+```json
+{
+  "count": 7,
+  "elements": [
+    {
+      "ref": "e118",
+      "role": "button",
+      "name": "Overview",
+      "visible": true,
+      "source": "src/components/Sidebar.tsx:41",
+      "states": ["present", "visible", "enabled"]
+    },
+    {
+      "ref": "e120",
+      "role": "button",
+      "name": "Compose",
+      "visible": true,
+      "source": "src/components/Sidebar.tsx:41",
+      "states": ["present", "visible", "enabled"]
+    }
+  ],
+  "total": 7,
+  "truncated": true,
+  "cost": { "bytes": 944, "tokens": 236 }
+}
+```
+
+Seven buttons, each with a `ref` to act on and a source file to open, for 236 tokens.
+
+## Arguments
+
+| Argument     | What it does                                                               |
+| ------------ | -------------------------------------------------------------------------- |
+| `by`         | `role` · `text` · `label` · `placeholder` · `testid` · `alt` · `component` |
+| `value`      | The query value for that strategy                                          |
+| `name`       | Accessible-name filter. Narrows a broad `role` query                       |
+| `scope`      | CSS selector or ref, to search inside a subtree                            |
+| `limit`      | Cap the descriptors returned. Cuts tokens hard on broad queries            |
+| `count_only` | Return just `{ count }`, around 30x smaller                                |
+| `attrs`      | Extra attributes per match, e.g. `['href']` to inventory links             |
+| `self`       | Return the `scope` element itself instead of searching inside it           |
+
+Every argument also has a predicate spelling, so `{ "role": "button" }` works as shorthand for `{ "by": "role", "value": "button" }`.
+
+## Use `count_only` when you only need a number
+
+"Are there still three rows?" does not require three row descriptors:
+
+```json
+{ "by": "testid", "value": "login-submit", "count_only": true }
+```
+
+```json
+{ "count": 1, "cost": { "bytes": 11, "tokens": 3 } }
+```
+
+Three tokens. Note that `total` is not emitted on this path, because `count` already is the total.
+
+## A zero-match result tells you what _is_ there
+
+```json
+{ "by": "testid", "value": "compose-prompt" }
+```
+
+```json
+{
+  "count": 0,
+  "elements": [],
+  "hint": {
+    "route": "/hostile",
+    "knownEmptyState": true,
+    "presentTestids": [
+      "brand",
+      "nav-overview",
+      "nav-deployments",
+      "nav-compose",
+      "nav-diagnostics",
+      "nav-hostile",
+      "session-pill",
+      "cmdk-open",
+      "sign-out",
+      "hostile-view",
+      "hostile-ticker",
+      "hostile-feed-count"
+    ],
+    "presentRegions": [
+      { "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] },
+      { "role": "banner", "childCount": 0, "sample": [] }
+    ]
+  },
+  "cost": { "bytes": 402, "tokens": 101 }
+}
+```
+
+The testid existed, on another route. `hint.route` says where you actually are, `presentTestids` says what is on this page instead, and `presentRegions` distinguishes an empty list from a missing one. All of it without paying for a snapshot.
+
+## Reading the response
+
+`ref` is the handle for every other tool: `act`, `inspect`, `state`. It stays valid until the element leaves the DOM, so you do not need to re-snapshot between actions on the same element.
+
+`source` appears when `@reticlehq/react` is installed. Note that both sidebar buttons above report `Sidebar.tsx:41`, and so do the three trimmed out of the example. That is the line where the component renders all five in a loop, which is exactly the line you want to edit.
+
+`truncated: true` with `total: 7` means `limit` cut the list, not that Reticle ran out of room. Neither field is emitted when nothing was cut, so their absence is itself the signal that you are looking at every match.
+
+`states` distinguishes `present` from `visible` from `enabled`. An element can be all three and still be covered by a modal. [`reticle_inspect`](/tools/inspect) reports `occluded` for that.
+
+<Tip>
+  Query by `testid` when you can. Role and text queries survive refactors well; testids survive
+  redesigns, translations, and the day someone rewrites your button labels for the marketing team.
+</Tip>

package/docs/tools/sessions.mdx

@@ -0,0 +1,101 @@
+---
+title: reticle_sessions
+description: List every connected browser tab, with the health fields that tell you whether it can actually be driven.
+icon: list-check
+---
+
+<Warning>
+  **reticle_sessions is not advertised.** The default surface is the merged nine, so an agent does not see
+  this name. Call **`reticle_session { action: "list" }`** instead. Everything below describes what that call does;
+  only the spelling changed. A call to the old name is answered with the new one, but an
+  `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
+</Warning>
+
+`reticle_sessions` lists every browser tab currently connected to the Reticle daemon, with the health fields that decide whether it can actually be driven. Reach for it first when a tool says no session is connected, and after every [`reticle_navigate`](/tools/navigate) that came back `confirmed: false`.
+
+```json
+{}
+```
+
+Real response from a healthy session:
+
+```json
+{
+  "sessions": [
+    {
+      "sessionId": "sba6117a6-24ec-494d-8c2c-e2958cff2e7f",
+      "url": "http://localhost:4310/",
+      "title": "Reticle · Mission Control",
+      "adapters": ["react"],
+      "hasCapabilities": true,
+      "hidden": false,
+      "lastSeenMs": 155,
+      "throttled": false,
+      "focused": true,
+      "attachment": { "connectedSinceMs": 18654, "outages": 0 },
+      "realInputAvailable": false,
+      "leased": false
+    }
+  ]
+}
+```
+
+A backgrounded tab adds a `recommendation` telling you what to do about it, and `attachment` grows a `lastOutage` once the connection has dropped at least once:
+
+```json
+{
+  "hidden": false,
+  "throttled": true,
+  "attachment": {
+    "connectedSinceMs": 1217047,
+    "outages": 3,
+    "lastOutage": { "startedMs": 1786818483776, "durationMs": 967 }
+  },
+  "recommendation": "tab hidden/throttled and may be un-focusable from here; refocus it, or run `reticle drive <url>` for a guaranteed scriptable context"
+}
+```
+
+## When nothing is connected
+
+An empty list is not silent. It comes back with a `why` that separates the two causes, and refuses to guess between them:
+
+```json
+{
+  "sessions": [],
+  "why": "no browser session connected. Two things to weigh, and neither of them is proof. (1) Nothing is listening on the ports Reticle scans, so the dev server may not be running. That scan is narrow though: a server on any other port is invisible to it, so if the app IS running, ask for its URL rather than assuming it is down, and open it with `reticle open <url>`. (2) There is no `.reticle.json` in the directory this daemon is running in. That is the file `reticle init` writes, so the app may carry no Reticle SDK."
+}
+```
+
+That string is trimmed. The full text also lists the exact ports it scanned and warns that in a monorepo the daemon often runs at the root while the app lives in a subdirectory, so you should check the app's own directory before re-running `init`.
+
+## The fields that decide whether driving will work
+
+| Field | Why it matters |
+| --- | --- |
+| `throttled` | The browser is deprioritising a background tab. Synthetic timers and pointer gestures may silently no-op |
+| `hidden` / `focused` | Why it's throttled, and what to do about it |
+| `hasCapabilities` | Whether the app registered testids, signals and stores. `false` means [`reticle_state`](/tools/state) has nothing to read |
+| `adapters` | `["react"]` means you get component names and source pointers |
+| `realInputAvailable` | `true` when native CDP input is available, under `reticle drive` |
+| `outages` | How often the connection has dropped. Non-zero is worth investigating |
+
+<Warning>
+  `throttled: true` is the most common cause of "the click did nothing". Focus the tab, or drive a
+  dedicated context. It is not your app being broken. It is the browser saving battery on a tab
+  nobody is looking at.
+</Warning>
+
+## Confirm after navigating
+
+[`reticle_navigate`](/tools/navigate) can only report that a navigation was dispatched. `sessions` is how you confirm one arrived: a session at the new URL means the page loaded **and** is instrumented. No session means one of those two is false, and you find out now rather than after three confusing failures.
+
+## Scoping
+
+You rarely need to pass `sessionId` to other tools. Reticle scopes to your project, prefers the active tab, and refuses rather than guesses when the choice is ambiguous. A refusal you can act on beats a silent pick of the wrong tab.
+
+Pass it explicitly when you genuinely mean one specific tab, such as when testing two apps at once.
+
+<Note>
+Sessions accumulate. A stale entry pointing at a dev server you have since restarted will sit there
+looking plausible. `reticle_session { action: "end" }` clears one out.
+</Note>

package/docs/tools/snapshot.mdx

@@ -0,0 +1,136 @@
+---
+title: reticle_snapshot
+description: A semantic accessibility snapshot of the page or a subtree, in three sizes. From the full tree down to a 25-token route check.
+icon: camera
+---
+
+<Warning>
+  **reticle_snapshot is not advertised.** The default surface is the merged nine, so an agent does not see
+  this name. Call **`reticle_look { action: "page" }`** instead. Everything below describes what that call does;
+  only the spelling changed. A call to the old name is answered with the new one, but an
+  `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
+</Warning>
+
+`reticle_snapshot` is how an agent gets its bearings. It returns the page as semantic structure, not pixels and not raw HTML, and it comes in three sizes so you can pay for only what you need.
+
+## Three modes, three prices
+
+| Mode          | Returns                               | Real cost on one page |
+| ------------- | ------------------------------------- | --------------------- |
+| `status`      | Route and title only                  | **25 tokens**         |
+| `interactive` | Only clickable and focusable elements | **65 tokens**         |
+| `full`        | Every element                         | Depends on the page   |
+
+### `status`. the cheapest possible check
+
+```json
+{ "mode": "status" }
+```
+
+```json
+{
+  "tree": "",
+  "nodes": 0,
+  "truncated": false,
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 98, "tokens": 25 }
+}
+```
+
+Ninety-eight bytes to answer "where am I?". Use it after a navigation instead of re-reading the page.
+
+### `interactive`. the default working view
+
+```json
+{ "mode": "interactive" }
+```
+
+```json
+{
+  "tree": "- textbox \"Email\" (ref=e303) [value=\"admin@reticle.dev\"]\n- textbox \"Password\" (ref=e304) [value=\"[REDACTED]\"]\n- button \"Sign in\" (ref=e305)",
+  "nodes": 3,
+  "truncated": false,
+  "status": { "route": "/deployments", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 260, "tokens": 65 }
+}
+```
+
+Everything you can act on, with a `ref` for each, for 65 tokens. Note the password arrives `[REDACTED]` without anyone configuring it.
+
+## Arguments
+
+| Argument | What it does                                                                 |
+| -------- | ---------------------------------------------------------------------------- |
+| `mode`   | `full` · `interactive` · `status`                                            |
+| `scope`  | CSS selector or ref, to snapshot one subtree                                 |
+| `diff`   | Return only what changed since your last snapshot of the same scope and mode |
+
+## `diff` is how you keep a long session cheap
+
+```json
+{ "mode": "interactive", "diff": true }
+```
+
+When nothing moved since your last look of the same scope and mode, that costs 20 tokens and says so:
+
+```json
+{
+  "mode": "unchanged",
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 79, "tokens": 20 }
+}
+```
+
+When something did move, you get only what changed. This is the same call after a login replaced the form with the app shell:
+
+```json
+{
+  "mode": "delta",
+  "delta": {
+    "added": [
+      "- button \"Overview\" (ref=e17)",
+      "- button \"Deployments40\" (ref=e18)",
+      "- button \"Compose\" (ref=e19)",
+      "- button \"Diagnostics\" (ref=e20)",
+      "- button \"Hostile\" (ref=e21)",
+      "- button \"Search or jump to…⌘K\" (ref=e22)",
+      "- button \"Sign out\" (ref=e23)"
+    ],
+    "removed": [
+      "- textbox \"Email\" (ref=e4) [value=\"admin@reticle.dev\"]",
+      "- textbox \"Password\" (ref=e5) [value=\"[REDACTED]\"]",
+      "- button \"Sign in\" (ref=e3)"
+    ],
+    "addedCount": 7,
+    "removedCount": 3
+  },
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 545, "tokens": 137 }
+}
+```
+
+A route change resets it: the next call after one returns a full snapshot rather than a delta against a page that no longer exists.
+
+<Tip>
+  Reach for [`reticle_query`](/tools/query) instead when you already know what you're looking for.
+  Snapshot is for orientation; query is for retrieval, and it's almost always cheaper.
+</Tip>
+
+## Refs change across documents
+
+Refs are stable while the element is in the DOM. A full navigation builds a new document, so refs are re-issued. Across the captures on this page the same "Sign in" button was `e105`, then `e305`, then `e3`, because each reload built a new document. Snapshot after navigating; don't reuse refs across one.
+
+Reticle refuses a stale ref rather than clicking whatever now occupies that slot:
+
+```json
+{
+  "error": "ref 'e303' no longer resolves to an element",
+  "recovery": "That ref is stale: refs are invalidated whenever the DOM re-renders, so any action that navigated, opened a modal, re-sorted a list or changed the page invalidates every ref taken before it. Call reticle_query again for a fresh ref and retry the action."
+}
+```
+
+<Note>
+  That `recovery` string is trimmed. The full text also recommends
+  [`reticle_act_and_wait`](/tools/act-and-wait) with `until`, so the next ref is taken after the
+  page settles.
+</Note>

package/docs/tools/state.mdx

@@ -0,0 +1,111 @@
+---
+title: reticle_state
+description: Read live framework state directly from the running app. What it believes, not just what it rendered, without the app broadcasting anything.
+icon: database
+---
+
+<Warning>
+  **reticle_state is not advertised.** The default surface is the merged nine, so an agent does not see
+  this name. Call **`reticle_look { action: "state" }`** instead. Everything below describes what that call does;
+  only the spelling changed. A call to the old name is answered with the new one, but an
+  `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
+</Warning>
+
+`reticle_state` reads live framework state straight out of the running app, without the app broadcasting anything. Reach for it when the DOM looks right and you want to know whether the application actually accepted the change, which is where false greens live.
+
+The DOM tells you what the app _drew_. `reticle_state` tells you what it _believes_. The gap between those two is where false greens live: a row appears in the table, the store never changed, and a reload makes the row vanish.
+
+## Example
+
+```json
+{ "depth": 2 }
+```
+
+Real response:
+
+```json
+{
+  "found": true,
+  "value": {
+    "stores": {
+      "__reticle_renders": "{…1 keys}",
+      "app": "{…30 keys}",
+      "queries": "{…0 keys}"
+    },
+    "storeNames": ["__reticle_renders", "app", "queries"]
+  },
+  "storeNames": ["__reticle_renders", "app", "queries"]
+}
+```
+
+`depth: 2` collapsed the contents to size markers: `{…30 keys}` rather than thirty keys of JSON. On a large store this is the difference between a cheap look and a very expensive one.
+
+## Arguments
+
+| Argument | What it does                                                 |
+| -------- | ------------------------------------------------------------ |
+| `store`  | A registered store name, e.g. `app`                          |
+| `path`   | Dot-path into a store, e.g. `cart.items.0.qty`               |
+| `depth`  | Collapse anything deeper than N levels to a size marker      |
+| `ref`    | Best-effort read of the nearest React component's hook state |
+
+Drill in once you know what you want:
+
+```json
+{ "store": "app", "path": "auth" }
+```
+
+```json
+{
+  "store": "app",
+  "path": "auth",
+  "found": true,
+  "value": { "email": "admin@reticle.dev" },
+  "storeNames": ["__reticle_renders", "app", "queries"]
+}
+```
+
+A wrong `path` comes back `{ "found": false, "availableKeys": [...] }` rather than an empty value, so a typo is diagnosable instead of looking like an empty store.
+
+<Warning>
+  `reticle_state` asks the page and waits. On a backgrounded tab the page may never answer, and you
+  get `"command 'state_read' timed out after 8000ms"` with a recovery note pointing at
+  [`reticle_sessions`](/tools/sessions). That is a fact about the tab, not a Reticle failure. Bring
+  it to the front, or drive your own browser.
+</Warning>
+
+## You have to register stores first
+
+`reticle_state` reads what your app registered in `src/reticle-dev.ts`. With nothing registered, `storeNames` comes back empty and this tool has nothing to say.
+
+```ts
+registerCapabilities({
+  stores: [{ name: 'app', store: appStore }],
+});
+```
+
+<Warning>
+Pass the **store**, not `() => store.getState()`. The store form wires `subscribe` too, so every
+mutation emits a state diff. The getter form is read-only and silently produces empty diffs, which
+looks like "nothing changed" and is really "I was never watching".
+</Warning>
+
+That distinction is the single most common instrumentation mistake, and its failure mode is a verdict that passes when it should not.
+
+## Why this is the strongest evidence you have
+
+A `POST` returning `200` proves the server was reachable. A row in the DOM proves React rendered something. Neither proves your application accepted the change.
+
+State does. When [`reticle_act_and_wait`](/quickstart) reports
+
+```json
+"stateDiffs": [
+  { "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}", "atMs": 44403 }
+]
+```
+
+that is the app itself saying the login took. A mock that returns `200` without touching state gets caught right there, and nowhere else.
+
+<Card title="Instrument your app" icon="wrench" href="/instrumentation">
+  Registering one store for your most important flow is the highest-value line you can write.
+</Card>

package/docs/tools/wait-for.mdx

@@ -0,0 +1,92 @@
+---
+title: reticle_wait_for
+description: Block until a predicate holds. Or return immediately if it is already true in the recent buffer.
+icon: hourglass
+---
+
+<Warning>
+  **reticle_wait_for is not advertised.** The default surface is the merged nine, so an agent does not see
+  this name. Call **`reticle_assert { action: "wait" }`** instead. Everything below describes what that call does;
+  only the spelling changed. A call to the old name is answered with the new one, but an
+  `allowedTools` allowlist or an MCP permission rule naming it refuses before Reticle is asked.
+</Warning>
+
+`reticle_wait_for` blocks until a predicate holds, or returns straight away if it is already satisfied in the recent event buffer. Reach for it when you are waiting on something you did not cause. It reads and waits; it does not produce a verdict, so finish with [`reticle_assert`](/tools/assert).
+
+It takes the same predicate grammar as [`reticle_act_and_wait`](/tools/act-and-wait), without the action. Use it when the thing you are waiting for was triggered by something other than your own click. A timer, a websocket push, a background refresh.
+
+## Example
+
+```json
+{
+  "predicate": { "kind": "text", "contains": "Invalid email or password" },
+  "timeout_ms": 3000
+}
+```
+
+Real response:
+
+```json
+{
+  "pass": true,
+  "evidence": [
+    {
+      "ref": "e606",
+      "role": "alert",
+      "name": "Invalid email or password",
+      "visible": true,
+      "source": "src/components/Login.tsx:72",
+      "states": ["present", "visible", "enabled"]
+    }
+  ]
+}
+```
+
+The evidence is the element itself, with the file and line that rendered it.
+
+<Note>
+  A `text` predicate matches **presence** by default, so an element that is in the DOM but hidden
+  satisfies it and comes back with `visible: false` and `states: ["present", "hidden", "enabled"]`.
+  If you need it on screen, say so: `{ "kind": "text", "contains": "…", "visible": true }`.
+</Note>
+
+The field is `contains`. `value` and `text` are accepted as aliases and rewritten to it, but `contains` is what the published schema declares.
+
+## It checks the buffer first
+
+`wait_for` does not always wait. If the predicate is already satisfied in the recent event buffer, it returns immediately. This means you can act, then wait, without racing. The event that happened while you were composing the second call is not lost.
+
+## Arguments
+
+| Argument                 | What it does                                                      |
+| ------------------------ | ----------------------------------------------------------------- |
+| `predicate` (or `until`) | `{ kind, ...fields }`, see the [predicate reference](/predicates) |
+| `timeout_ms`             | Maximum wait. Default 4000                                        |
+| `since`                  | Cursor from a prior act, to widen or narrow the window explicitly |
+
+By default the wait only counts events since your last act, so a signal that fired before the action cannot satisfy it. A miss returns a near-miss diagnosis rather than a bare `false`:
+
+```json
+{
+  "pass": false,
+  "failureReason": "no element matched {\"text\":\"Deployments\"}",
+  "observed": "no matching element on the page",
+  "expected": "an element matching {\"text\":\"Deployments\"}",
+  "assertion": "element.present",
+  "evidence": { "presentTestids": ["login-email", "login-password", "login-submit"] }
+}
+```
+
+`presentTestids` there is the answer to the real question. The text was missing because the app had logged out, not because the render was slow.
+
+## Prefer `act_and_wait` when you caused it
+
+If your own action is supposed to trigger the thing, put the predicate in the action:
+
+```json
+{ "ref": "e605", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
+```
+
+One call instead of two, no gap for an event to slip through, and, the part that actually matters, the expectation is recorded _before_ the action rather than chosen after it.
+
+Save `wait_for` for consequences you did not cause.