@reticlehq/server 2.14.0 → 3.2.0

package/docs/tools-snapshot.mdx

@@ -1,129 +0,0 @@
----
-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
----
-
-`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

@@ -1,104 +0,0 @@
----
-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
----
-
-`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

@@ -1,85 +0,0 @@
----
-title: reticle_wait_for
-description: Block until a predicate holds. Or return immediately if it is already true in the recent buffer.
-icon: hourglass
----
-
-`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.