@reticlehq/server 2.7.0 → 2.8.0

package/docs/predicates.mdx

@@ -0,0 +1,179 @@
+---
+title: Predicate reference: the grammar of green
+sidebarTitle: Predicates
+description: The grammar for declaring what should be true. Every kind, every field, and which ones actually prove something.
+icon: filter
+---
+
+A predicate declares what should be true. It is the argument to `until` on [`reticle_act_and_wait`](/tools-act-and-wait), and to `predicate` on [`reticle_assert`](/tools-assert) and [`reticle_wait_for`](/tools-wait-for).
+
+Every predicate is `{ kind, ...fields }`.
+
+## Not all predicates prove the same thing
+
+Reticle grades them, and it will tell you when you have chosen a weak one. This is a real response from a `text` assertion:
+
+```json
+{
+  "verified": "yes",
+  "pass": true,
+  "advice": "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked."
+}
+```
+
+Take the advice. `element` and `text` are convenient and weak; `signal`, `state` and `net` are what make a green trustworthy.
+
+| Kind               | Grade     | Proves                                                 |
+| ------------------ | --------- | ------------------------------------------------------ |
+| `signal`           | strongest | The app declared success in its own words              |
+| `state`            | strong    | A registered store actually changed                    |
+| `net`              | strong    | A specific request fired, with a countable cardinality |
+| `route`            | medium    | Navigation happened                                    |
+| `console`          | medium    | Something logged, or nothing did                       |
+| `element` / `text` | weak      | Something rendered. A mock renders too                 |
+
+## The leaves
+
+### element
+
+```json
+{
+  "kind": "element",
+  "query": { "role": "dialog", "name": "Confirm" },
+  "state": "visible"
+}
+```
+
+`query` accepts `role`, `name`, `text`, `label`, `placeholder`, `testid`, `alt`, `scope`. `state` is one of `visible`, `hidden`, `enabled`, `disabled`, `checked`, `expanded`, `focused`, `present`.
+
+Add `"absent": true` to assert something is **gone**. The predicate for a removal, a dismissed toast, or a regression check.
+
+### text
+
+```json
+{ "kind": "text", "contains": "Saved successfully", "visible": true }
+```
+
+Both `contains` and `value` are accepted. `absent: true` asserts the text is not present.
+
+### net
+
+```json
+{ "kind": "net", "method": "POST", "urlContains": "/api/order", "status": 200 }
+```
+
+The one that catches the expensive bug:
+
+```json
+{ "kind": "net", "method": "POST", "urlContains": "/api/order", "count": 1 }
+```
+
+**Exactly one.** Double-submit fails at two, and nothing on screen would have told you.
+
+### route
+
+```json
+{ "kind": "route", "pathname": "/success" }
+```
+
+`contains` also works.
+
+<Warning>
+  `route` asserts the route **changed**. Asserting the route you are already on always fails, and
+  the response says so: `expected: "a route change to /"`, `assertion: "route.changed"`.
+</Warning>
+
+### console
+
+```json
+{ "kind": "console", "level": "error", "absent": true }
+```
+
+"The flow completed and logged nothing." Worth attaching to most actions. Plenty of features work while quietly throwing.
+
+### signal
+
+```json
+{ "kind": "signal", "name": "webhook:received", "dataMatches": { "provider": "stripe", "id": "*" } }
+```
+
+The app emitted a named signal via `reticle.signal()`. `dataMatches` is shallow JSON matching, and `*` means "present, any value".
+
+Nothing outranks this. A `200` proves the server was reachable; a rendered row proves React ran. A signal is the application itself saying the thing succeeded. See [instrumentation](/instrumentation) for how to emit them.
+
+### state
+
+```json
+{ "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
+```
+
+Walks a dot-path, with numeric array indices. `equals` takes a literal, or an operator pattern:
+
+| Operator                  | Meaning                       |
+| ------------------------- | ----------------------------- |
+| `$gte` `$lte` `$gt` `$lt` | numeric comparison            |
+| `$contains`               | substring or array membership |
+| `$length`                 | collection size               |
+
+Omit `equals` entirely to assert presence.
+
+`store` is optional. Leave it out and the path picks the store: if exactly one registered store exposes it, that one is read. Registering several is normal, so this is the common case rather than a shortcut. Name a store when two of them genuinely expose the same path, which is the only situation Reticle cannot resolve on its own. If no store exposes it, that is a failure rather than a question, and the miss names the stores it searched.
+
+This is the predicate that catches a UI-versus-store desync. A deploy that only _looks_ shipped. Deterministically, in one call, with no model involved. On a miss it names the real store value and the keys that were available, so a failure is legible rather than a blind "no".
+
+### animation
+
+```json
+{ "kind": "animation", "name": "dialog-in", "completed": true }
+```
+
+## Combinators
+
+```json
+{
+  "kind": "allOf",
+  "predicates": [
+    { "kind": "signal", "name": "auth:granted" },
+    { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
+    { "kind": "console", "level": "error", "absent": true }
+  ]
+}
+```
+
+```json
+{ "kind": "anyOf", "predicates": [ … ] }
+{ "kind": "not", "predicate": { … } }
+```
+
+<Warning>
+A combinator needs its own `kind`, and the children go in `predicates`. A bare
+`{ "allOf": [ … ] }` does not parse, and neither does `{ "kind": "allOf", "allOf": [ … ] }`.
+
+Reticle refuses the call rather than running half of it: _"Nothing ran, the predicate was not evaluated, so no verdict was produced."_ Better to be told than to get a green from an assertion that never executed.
+
+</Warning>
+
+`allOf` is the workhorse. "The signal fired **and** exactly one request went out **and** the console stayed clean" is a genuinely strong check, and it is one call.
+
+Each child reports its own evidence:
+
+```json
+"evidence": [
+  { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } },
+  { "matched": 1 },
+  { "absent": true }
+]
+```
+
+## Timing and scoping
+
+| Field | Where | What it does |
+| --- | --- | --- |
+| `timeout_ms` | `assert`, `wait_for`, `act_and_wait` | Wait up to N ms for it to become true |
+| `since` | `net` and `console` leaves, and the call itself | Only consider events after this cursor |
+
+The `since` cursor comes from a prior `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause. Without it, an assertion can pass on an event from two clicks ago.
+
+<Card title="Where predicates get used" icon="circle-check" href="/tools-act-and-wait">
+  Naming the consequence before the action is the whole point.
+</Card>

package/docs/quickstart.mdx

@@ -0,0 +1,211 @@
+---
+title: Quickstart: proof in five minutes
+sidebarTitle: Quickstart
+description: Install Reticle, connect your coding agent, and get a real verdict with evidence in about five minutes.
+icon: rocket
+---
+
+By the end of this page your agent will click a button in your app and prove what happened: the request that fired, the state that changed, and the file to open if it didn't.
+
+<Note>
+  Every response on this page is real output, captured against a running app while writing it.
+  Nothing here is illustrative.
+</Note>
+
+## Prerequisites
+
+- Node 20 or newer
+- A web app you can run locally, and its dev server
+- A coding agent that speaks MCP (Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code)
+
+## Step 1. Let your agent install it
+
+The fastest path is to hand the job to the agent that will use it. In your project directory:
+
+```bash
+npx @reticlehq/server init
+```
+
+This registers the MCP server, installs the SDK, wires it into your app's entry point, and writes the agent rule files. It is idempotent. Run it twice and the second run reports what was already done rather than doing it again.
+
+Prefer to install the skill and let the agent run setup itself? On Claude Code the plugin registers the MCP server and the skill in one step:
+
+```text
+/plugin marketplace add reticlehq/reticle
+/plugin install reticle@reticlehq
+```
+
+On Cursor, Codex, Copilot, Gemini and anything else the skills CLI supports:
+
+```bash
+npx skills add reticlehq/reticle
+```
+
+Then type `/reticle` and the agent runs the install from the skill.
+
+Useful flags, from `reticle init` itself:
+
+```
+reticle init  [--dry-run] [--port N] [--no-mcp] [--no-install] [--app <dir>]
+              --app picks WHICH app in a monorepo, when several are found
+              --no-mcp skips MORE than the server registration: also the agent rule files
+              (CLAUDE.md / AGENTS.md / .cursor) and the /reticle command, because all three
+              only make sense once the tools are reachable.
+```
+
+Start with `--dry-run` if you want to see the plan before anything is written.
+
+<Tip>
+  In a monorepo, `init` will find several apps and ask which one you mean. `--app packages/web`
+  skips the question.
+</Tip>
+
+Prefer to wire it yourself? See [Manual install](/install-manual). It is about ten lines, and worth reading once even if you let the agent do it, because it explains what the agent actually changed.
+
+## Step 2. Check the setup
+
+```bash
+npx @reticlehq/server doctor
+```
+
+`doctor` diagnoses the whole setup in one command: Chromium, the daemon, the port. If something is wrong this is the page you want before you start debugging your app instead.
+
+## Step 3. Start your app and open it
+
+Start your dev server as usual, then:
+
+```bash
+npx @reticlehq/server open
+```
+
+This reuses the tab you already have open, or opens one if you don't. The SDK connects to the local daemon over a WebSocket, and your agent can now see the app.
+
+<Warning>
+  If the browser console says it "could not reach the bridge", your app and the daemon disagree
+  about the port. Set it explicitly: `VITE_RETICLE_WS_URL=ws://localhost:4400/reticle` for Vite, or
+  `reticle.connect({url})`. This is the single most common setup problem, and the console message
+  tells you the exact port it tried.
+</Warning>
+
+## Step 4. Look at the page
+
+Ask your agent to take a snapshot. This is what came back from a real app:
+
+```json
+{
+  "tree": "- textbox \"Email\" (ref=e3) [value=\"admin@reticle.dev\"]\n- textbox \"Password\" (ref=e4) [value=\"[REDACTED]\"]\n- button \"Sign in\" (ref=e5)",
+  "nodes": 3,
+  "truncated": false,
+  "status": { "route": "/", "title": "Reticle · Mission Control" },
+  "cost": { "bytes": 243, "tokens": 61 }
+}
+```
+
+Three things to notice.
+
+The password is already `[REDACTED]`. Reticle redacts credential-shaped values before they leave the page, so your agent's context never holds your test password, let alone your real one.
+
+The whole snapshot cost **61 tokens**. This is `mode: "interactive"`, which returns only the controls. A full accessibility-tree dump of a comparable page runs to thousands. Reticle is built to ask narrow questions, because the answer gets re-sent to the model on every turn.
+
+Each control has a `ref` like `e5`. That's the handle for the next step, and it stays valid until the element leaves the DOM, so you don't re-snapshot between actions.
+
+## Step 5. Act, and prove it
+
+Here is the whole idea of Reticle in one call. Your agent names the expected consequence **before** it acts:
+
+```json
+{
+  "ref": "e5",
+  "action": "click",
+  "until": { "kind": "net", "method": "POST" }
+}
+```
+
+Stating the expectation up front is the difference between a check and a rationalisation. An agent that clicks first and then decides what counts as success will always find something that counts.
+
+The real response, trimmed for length:
+
+```json
+{
+  "verified": "yes",
+  "verifiedReason": "proved",
+  "because": "assertion held at presence grade over a clean capture with no channel disagreeing",
+  "effect": {
+    "ok": true,
+    "testid": "login-submit",
+    "component": "Login",
+    "name": "Sign in",
+    "effect": { "domMutatedWithin": 7, "appeared": "Signing in…" },
+    "source": { "file": "src/components/Login.tsx", "line": 81, "column": 8 }
+  },
+  "verdict": {
+    "pass": true,
+    "evidence": {
+      "method": "POST",
+      "url": "http://localhost:8787/api/login",
+      "status": 200,
+      "durationMs": 67,
+      "requestBody": "{\"email\":\"admin@reticle.dev\",\"password\":\"[REDACTED]\"}",
+      "responseBody": "{\"token\":\"[REDACTED]\",\"user\":{\"email\":\"admin@reticle.dev\"}}"
+    }
+  },
+  "summary": {
+    "net": { "total": 1, "errors": 0 },
+    "consoleErrors": 0,
+    "stateDiffs": [{ "path": "auth", "from": null, "to": "{\"email\":\"admin@reticle.dev\"}" }],
+    "signals": ["auth:granted"]
+  },
+  "honesty": {
+    "grade": "presence",
+    "coverage": { "pct": 100, "partial": false },
+    "integrity": { "clean": true, "issues": [] }
+  }
+}
+```
+
+![A real act_and_wait verdict, annotated. The verdict, the source pointer, the request evidence, the request count, the state diff, and the app's own signal](/images/verdict-annotated.png)
+
+Read what that actually proves:
+
+| Field | What it tells you |
+| --- | --- |
+| `verified: "yes"` | The named consequence happened. Not "the page looks different", the specific thing. |
+| `source.file` / `line` | The button lives at `src/components/Login.tsx:81`. If this had failed, your agent knows which file to open. |
+| `verdict.evidence` | The exact request: one `POST /api/login`, `200`, 67ms. Not a summary of it. The request. |
+| `stateDiffs` | Application state moved from `null` to a real user. A mock that returns 200 without changing state is caught right here. |
+| `signals` | The app's own `auth:granted` fired. This is the strongest signal available, because the app declared success itself. |
+| `net.total: 1` | Exactly one request. Double-submit bugs show up as `2`. |
+| `integrity.clean` | Nothing interfered with the capture, so the verdict is trustworthy. |
+
+## What "verified" can say
+
+<CardGroup cols={3}>
+  <Card title="yes" icon="circle-check">
+    The consequence you named actually happened, and the evidence is attached.
+  </Card>
+  <Card title="no" icon="circle-xmark">
+    It did not happen. This is a finding, with the source pointer to go fix it.
+  </Card>
+  <Card title="unknown" icon="circle-question">
+    Reticle drove the app and could not tell. **This is not a pass.** Report it as unknown.
+  </Card>
+</CardGroup>
+
+That third state is the one that matters. Most tools have two outcomes and quietly file "I couldn't tell" under "fine". A verification layer that cannot admit uncertainty is just a very confident random number generator.
+
+## Where to go next
+
+<CardGroup cols={2}>
+  <Card title="Instrument your app" icon="wrench" href="/instrumentation">
+    Emit signals like `auth:granted` so your verdicts get stronger than "the DOM changed".
+  </Card>
+  <Card title="Every tool" icon="list" href="/tools-overview">
+    The 18 tools your agent sees by default, and the 30 more it can reach on demand.
+  </Card>
+  <Card title="Run it in CI" icon="circle-check" href="/testing">
+    Turn this session into a suite that blocks a bad merge.
+  </Card>
+  <Card title="Why Reticle" icon="lightbulb" href="/why-reticle">
+    The false-green problem, and the measured case that this fixes it.
+  </Card>
+</CardGroup>

package/docs/recipes.mdx

@@ -0,0 +1,242 @@
+---
+title: Recipes: copy, paste, verify
+sidebarTitle: Recipes
+description: Worked examples for the situations you are actually in, with the real response each one returned.
+icon: book-open
+---
+
+Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app.
+
+## "Did the login actually work?"
+
+One call, three conditions. The signal fired, exactly one request went out, and nothing was logged.
+
+```json
+{
+  "ref": "e5",
+  "action": "click",
+  "until": {
+    "kind": "allOf",
+    "predicates": [
+      { "kind": "signal", "name": "auth:granted" },
+      { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
+      { "kind": "console", "level": "error", "absent": true }
+    ]
+  }
+}
+```
+
+```json
+{
+  "verified": "yes",
+  "because": "assertion held at signal grade over a clean capture with no channel disagreeing",
+  "verdict": {
+    "pass": true,
+    "evidence": [
+      { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } },
+      { "matched": 1 },
+      { "absent": true }
+    ]
+  },
+  "summary": {
+    "stateDiffs": [{ "path": "auth", "from": null, "to": "{…}" }],
+    "storageKeysChanged": ["reticle.bench.authToken", "reticle.bench.sessionId"]
+  },
+  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
+}
+```
+
+Each child predicate reports its own evidence, in order. `count: 1` is the part that catches double-submit, and it costs nothing to ask for.
+
+## "Did navigating actually change the view?"
+
+```json
+{ "ref": "e17", "action": "click", "until": { "kind": "signal", "name": "nav:changed" } }
+```
+
+```json
+{
+  "verified": "yes",
+  "verdict": {
+    "pass": true,
+    "evidence": { "name": "nav:changed", "data": { "view": "deployments" } }
+  },
+  "summary": {
+    "stateDiffs": [{ "path": "view", "from": "overview", "to": "deployments" }],
+    "route": "/deployments"
+  }
+}
+```
+
+The signal carries the destination in its payload, so one predicate proves both that navigation happened and that it went to the right place.
+
+## "Did the modal open?" and the lesson in getting it wrong
+
+Here is a real failure, kept because it teaches more than another pass.
+
+```json
+{
+  "ref": "e23",
+  "action": "click",
+  "until": {
+    "kind": "allOf",
+    "predicates": [
+      { "kind": "element", "query": { "role": "dialog" }, "state": "visible" },
+      { "kind": "console", "level": "error", "absent": true }
+    ]
+  }
+}
+```
+
+```json
+{
+  "verified": "no",
+  "verdict": {
+    "pass": false,
+    "evidence": [
+      {
+        "pass": false,
+        "expected": "an element matching {\"role\":\"dialog\"} in state 'visible'",
+        "observed": "no matching element on the page",
+        "evidence": { "presentTestids": ["deploy-table", "filter-search", "env-filter", "…"] }
+      },
+      { "pass": true, "evidence": { "absent": true } }
+    ]
+  },
+  "summary": {
+    "stateDiffs": [{ "path": "newDeployOpen", "from": false, "to": true }],
+    "signals": ["modal:opened"]
+  }
+}
+```
+
+Read the `summary`. The modal **did** open. `newDeployOpen` went `false → true` and the app fired `modal:opened`.
+
+The assertion was wrong, not the app. That modal is a `div` with no `role="dialog"`, so a role query could never match it. (Which is also an accessibility bug worth fixing, found for free.)
+
+The right predicate was sitting in the response the whole time:
+
+```json
+{ "until": { "kind": "signal", "name": "modal:opened" } }
+```
+
+<Tip>
+  When an assertion fails, read `summary.signals` and `summary.stateDiffs` before you assume the
+  feature is broken. They tell you what actually happened, and usually hand you the predicate you
+  should have written.
+</Tip>
+
+## "Nothing matched, and I do not know why"
+
+An empty `reticle_query` result tells you what _is_ there:
+
+```json
+{
+  "count": 0,
+  "elements": [],
+  "hint": {
+    "route": "/",
+    "knownEmptyState": true,
+    "presentTestids": ["nav-overview", "nav-deployments", "kpi-deploys", "…"]
+  }
+}
+```
+
+In this case the testid existed, on another route. The hint saved a snapshot and a guess.
+
+## "Is this button destructive?"
+
+Reticle refuses controls that look destructive, before acting:
+
+```json
+{
+  "error": "potentially destructive action blocked; retry with args.confirmDangerous=true",
+  "recovery": "Reticle blocked a potentially destructive control (delete, remove, revoke…) on purpose. If you mean it, retry the same action with args.confirmDangerous set to true. This is a deliberate refusal, not a defect: there is nothing to report."
+}
+```
+
+Confirm it explicitly when you mean it:
+
+```json
+{ "ref": "e23", "action": "click", "args": { "confirmDangerous": true }, "until": { … } }
+```
+
+<Note>
+  The matcher is conservative and will occasionally stop something harmless. A button labelled "New
+  deploy" trips it. That is the trade: a false stop costs you one argument, and a false start costs
+  you a deleted record.
+</Note>
+
+## "Did my change break anything else?"
+
+```json
+{ "tool": "reticle_verify_change", "args": { "since": "HEAD~1" } }
+```
+
+Give it the files you edited, or a git ref. It works out which saved flows cover them and replays only those.
+
+## "What is even testable in this app?"
+
+The best first call on an unfamiliar codebase:
+
+```json
+{ "tool": "reticle_capabilities" }
+```
+
+```json
+{
+  "testids": ["login-email", "login-submit", "new-deploy", "deploy-submit", "…"],
+  "signals": ["auth:granted", "auth:denied", "deploy:created", "modal:opened", "…"],
+  "stores": ["app"],
+  "flows": [
+    {
+      "name": "ship-a-deploy",
+      "steps": ["nav-deployments", "new-deploy", "deploy-name", "deploy-submit"]
+    }
+  ],
+  "source": "live"
+}
+```
+
+That is the app stating what it considers testable, which beats snapshotting the DOM and inferring it from element names.
+
+## "The error state has never been tested"
+
+Most error states have never run. Force one:
+
+```json
+{
+  "tool": "reticle_network_mock",
+  "args": { "mocks": [{ "urlContains": "/api/deploys", "status": 500 }] }
+}
+```
+
+Then drive the flow and assert the error UI appears. Pass `clear: true` to turn mocking off.
+
+<Warning>
+This one needs a **Reticle-driven browser**, because mocks are applied through CDP and the always-on
+SDK cannot do that. A pooled lease is **not** enough. Verified: `reticle_lease` still returns
+`{ "ok": false, "reason": "no-cdp-provider" }`.
+
+Your route is `RETICLE_CDP_URL` pointed at a Chrome started with `--remote-debugging-port`. The same applies to `reticle_screenshot`, `reticle_visual_diff` and `reticle_viewport`.
+
+</Warning>
+
+## "I want this to run on every PR"
+
+Record it once, replay it forever:
+
+```json
+{ "tool": "reticle_flow_verify" }
+```
+
+Replays every saved flow and returns one consolidated verdict.
+
+<CardGroup cols={2}>
+  <Card title="The predicate grammar" icon="filter" href="/predicates">
+    Every kind, every field, and which ones actually prove something.
+  </Card>
+  <Card title="Best practices" icon="star" href="/best-practices">
+    The habits behind these recipes, and the mistakes that produce a confident wrong pass.
+  </Card>
+</CardGroup>