@reticlehq/server 2.7.0 → 2.8.0

package/docs/tools-wait-for.mdx

@@ -0,0 +1,66 @@
+---
+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` 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", "value": "Invalid email or password" },
+  "timeout_ms": 3000
+}
+```
+
+Real response:
+
+```json
+{
+  "pass": true,
+  "evidence": [
+    {
+      "ref": "e104",
+      "role": "alert",
+      "name": "Invalid email or password",
+      "visible": false,
+      "source": "src/components/Login.tsx:72",
+      "states": ["present", "hidden", "enabled"]
+    }
+  ]
+}
+```
+
+The evidence is the element itself, with the file and line that rendered it.
+
+<Note>
+  Look at `visible: false` and `states: ["present", "hidden", "enabled"]`. The alert exists in the
+  DOM and is not visible. `wait_for` on a `text` predicate matches presence, if you need it on
+  screen, that is a different question, and [`reticle_inspect`](/tools-inspect) answers it.
+</Note>
+
+## 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 grammar](/tools-act-and-wait) |
+| `timeout_ms` | Maximum wait |
+| `since` | Cursor from a prior act, to scope the wait |
+
+## 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": "e103", "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 matters. The expectation is recorded _before_ the action rather than chosen after it.
+
+Save `wait_for` for consequences you did not cause.

package/docs/troubleshooting.mdx

@@ -0,0 +1,193 @@
+---
+title: Troubleshooting: it worked on my tab
+sidebarTitle: Troubleshooting
+description: Nothing connected, the click did nothing, the verdict says unknown. The failures people actually hit, and the diagnostic for each.
+icon: stethoscope
+---
+
+Most of these were hit while writing these docs. The diagnostics quoted are real output.
+
+## Start here
+
+```bash
+npx @reticlehq/server doctor
+```
+
+```
+reticle doctor
+  node         v22.14.0
+  chromium     ✓ installed
+  daemon       ✓ running on :4400 (pid 24735, v2.8.0)
+  sessions     ✓ 1 page connected
+  bridge port  4400  (your app must dial THIS port, not your dev-server port)
+  daemon log   /Users/you/.reticle/daemon-4400.log
+  tracing      RETICLE_TRACE=1 on the daemon for per-stage timings in that log
+```
+
+One command, the whole setup. If this is clean and things still fail, the problem is in the app rather than the wiring.
+
+The `sessions` line is the one to read first. Zero connected pages is a failing check, not a footnote, because it is the state a setup most often stalls in: everything installed, the daemon up, and nothing having dialled in. When it is zero, `doctor` prints the same diagnosis described below underneath the checklist, so you do not have to call a tool to see it.
+
+## "No browser session connected"
+
+By far the most common. Reticle's own diagnostic is unusually good here. It tells you whether the wiring was ever correct:
+
+```json
+{
+  "sessionCount": 0,
+  "why": "no browser session connected, but one WAS connected to this daemon earlier, so the wiring is correct. The tab was closed, navigated away, or hard-reloaded. Ask the human to reopen the app (or run `reticle open`), or reload the tab. You do not have to wait for the human: reticle_lease {action:\"acquire\", url} opens a browser Reticle drives itself."
+}
+```
+
+Read the `why`. "One WAS connected earlier" means stop debugging your config, just reopen the tab.
+
+If nothing ever connected:
+
+- Is the app running, and open in a browser?
+- Is `reticle.connect()` actually executing? Check the dev guard is true.
+- **Port mismatch.** This is the big one.
+
+### The port mismatch
+
+Your app dials a port; the daemon listens on one. When they disagree, the app runs perfectly and silently never connects. The browser console says so:
+
+```
+[Reticle] could not reach the bridge at ws://localhost:4460/reticle after 3 attempts.
+Is the Reticle daemon running on that port? If your app runs in a container/devcontainer/WSL,
+the daemon is on a different host, so set the WS URL explicitly
+(Vite: VITE_RETICLE_WS_URL, or reticle.connect({ url })). Still retrying…
+```
+
+That message names the exact port it tried. Compare it with `bridge port` from `doctor` and set the one that is wrong:
+
+```bash
+VITE_RETICLE_WS_URL=ws://localhost:4400/reticle pnpm dev
+```
+
+<Warning>
+  The bridge port is **not** your dev-server port. A dev server on 4312 and a daemon on 4400 is
+  normal and correct.
+</Warning>
+
+## The click did nothing
+
+Check whether the tab is throttled. Every response tells you:
+
+```json
+"warning": "tab throttled; timer/rAF/pointer gestures may silently no-op; refocus before driving"
+```
+
+A backgrounded browser tab has its timers suppressed. Synthetic pointer gestures and timers can silently no-op, so an action reports success and nothing happens.
+
+Three fixes, in order of preference:
+
+1. **Drive a lease**. A context Reticle owns, never backgrounded:
+
+   ```json
+   { "tool": "reticle_lease", "args": { "action": "acquire", "url": "http://localhost:4312/" } }
+   ```
+
+   Release it when you finish: `{ "action": "release", "sessionId": "lease-…" }`.
+
+2. **Focus the tab.**
+3. **Fail loudly** instead of pretending. Pass `refuseWhenThrottled: true` to your action.
+
+If the tab is fine, check `occluded` on the element. A click that lands on a modal overlay is the other half of "the button doesn't work":
+
+```json
+{ "occluded": true, "occludedBy": "div.modal-backdrop" }
+```
+
+## "ref no longer resolves to an element"
+
+```
+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.
+Reticle refuses here rather than clicking whatever now occupies that slot.
+```
+
+This is Reticle protecting you, not failing. Re-query for a fresh ref.
+
+Better: use `reticle_act_and_wait { until }` for actions that change the page, so the next ref is taken after things settle.
+
+<Warning>
+  Refs never survive a full navigation. A new document means new refs, the same button was `e5`
+  before a navigation and `e103` after.
+</Warning>
+
+## The verdict says `unknown`
+
+`verified: "unknown"` means Reticle drove the app and could not tell. It is **not** a pass.
+
+The usual cause is a throttled tab: throttling suppresses the quiescence detection used to decide the page has settled, so even a successful action can come back unsettled. Drive a lease and try again.
+
+If it persists on an unthrottled context, that is worth reporting. Reticle's own response says so:
+
+```json
+"feedback_invite": "Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An unknown verdict is our defect, not yours"
+```
+
+## A negative result you are not sure about
+
+Before concluding "no request fired", read the buffer note:
+
+```json
+"buffer": { "held": 15, "dropped": 529, "note": "…a negative result here may be a false negative; the evidence may have expired…" }
+```
+
+"Nothing found" and "I no longer have what you asked about" are different answers. Grade sooner, or widen the buffer.
+
+## The agent cannot find an element
+
+- `reticle_snapshot { mode: "interactive" }` shows everything actionable.
+- Add a `data-testid` for a stable handle.
+- Narrow with `scope`. A CSS selector or a ref.
+
+## Assertions are flaky on async UIs
+
+- Use `timeout_ms` on `assert` and `wait_for`.
+- Pass the `since` cursor from `reticle_act` so only post-action events count. Without it, an assertion can pass on an event from two clicks ago.
+
+## `reticle_state` returns nothing
+
+`storeNames` empty means no store was registered. `reticle_state` reads what your app registered in `src/reticle-dev.ts`.
+
+<Warning>
+Pass the **store**, not `() => store.getState()`. The getter form is read-only and silently produces
+empty `stateDiffs`. Which reads as "nothing changed" and means "I was never watching".
+</Warning>
+
+## Source file is not resolving on React 19
+
+React 19 dropped `_debugSource`. Wire up `@reticlehq/babel-plugin`. Or just use `@reticlehq/vite-plugin` or `@reticlehq/next`, which both include it. Without it you get component identity but no `file:line`.
+
+## `ERESOLVE` installing next to a prerelease
+
+`@reticlehq/next` declares `peer next >=13` and `@reticlehq/react` declares `peer react >=18`. On a Next canary or React RC, npm refuses. See [the prerelease notes](/getting-started#installing-alongside-a-nextjs-or-react-prerelease).
+
+## Restarting things
+
+```bash
+npx @reticlehq/server stop     # clean daemon shutdown, no pkill needed
+npx @reticlehq/server status   # confirm it came back
+```
+
+<Warning>
+  Do not kill port 4400 with `lsof -ti tcp:4400 | xargs kill -9`. That matches the MCP proxy as well
+  as the daemon and takes your agent's connection down with it. Use `reticle stop`, or at minimum
+  `lsof -sTCP:LISTEN`.
+</Warning>
+
+## Sessions piling up
+
+Stale sessions pointing at dev servers you restarted an hour ago look completely plausible in a list, and one of them will get picked.
+
+```json
+{ "action": "end" }
+```
+
+`reticle_session { action: "end" }` when you are done, `{ action: "yield" }` when pausing. Both revive on your next action.
+
+<Card title="Still stuck?" icon="comments" href="/tools-session-and-feedback">
+  `reticle feedback --agent` works even when nothing is installed and the daemon will not start.
+</Card>