@reticlehq/server 2.14.0 → 3.2.0

package/docs/tools-act-sequence.mdx

@@ -1,153 +0,0 @@
----
-title: reticle_act_sequence
-description: Run several actions in order in one round trip. Fill, fill, submit. Instead of paying a full turn for each step.
-icon: layer-group
----
-
-`reticle_act_sequence` runs several actions in order in a single round trip. Reach for it whenever a journey needs more than one step, such as fill, fill, submit, and then prove the outcome once with [`reticle_act_and_wait`](/tools-act-and-wait), because a sequence itself produces no verdict.
-
-A login is three actions. Driving it one call at a time costs three round trips and three turns of context. `reticle_act_sequence` does it in one.
-
-This tool exists because of a measured problem: agents were driving forms one call at a time, over and over. Those repeats were not retries. The calls succeeded and got repeated, because the batching tool was not advertised and so nobody knew it was there.
-
-## Example
-
-```json
-{
-  "steps": [
-    { "ref": "e603", "action": "fill", "args": { "value": "admin@reticle.dev" } },
-    { "ref": "e604", "action": "fill", "args": { "value": "correct-horse-battery-staple" } },
-    { "ref": "e605", "action": "click" }
-  ]
-}
-```
-
-Steps may also name a `target` instead of a `ref`, the same locator [`reticle_act`](/tools-act) takes. The sequence resolves each one before dispatch, so a login does not need a query round trip per field:
-
-```json
-{
-  "steps": [
-    { "target": { "label": "Email" }, "action": "fill", "args": { "value": "admin@reticle.dev" } },
-    {
-      "target": { "label": "Password" },
-      "action": "fill",
-      "args": { "value": "correct-horse-battery-staple" }
-    },
-    { "target": { "testid": "login-submit" }, "action": "click" }
-  ]
-}
-```
-
-Real response. Each `effects[]` entry also carries `targetMatched`, `visible`, `enabled`, `defaultPrevented`, `occluded`, `occludedBy` and `scrolledIntoView`, and each `steps[]` entry also carries `dispatched`, `settled`, `settleReason`, `component`, `role` and `name`. Those are trimmed here for length:
-
-```json
-{
-  "since": 3915,
-  "dispatched": true,
-  "result": {
-    "ok": true,
-    "count": 3,
-    "effects": [
-      {
-        "dispatched": true,
-        "focusMoved": "null->e603",
-        "valueChanged": false,
-        "domMutatedWithin": 0
-      },
-      {
-        "dispatched": true,
-        "focusMoved": "e603->e604",
-        "valueChanged": true,
-        "domMutatedWithin": 9
-      },
-      {
-        "dispatched": true,
-        "focusMoved": "e604->null",
-        "domMutatedWithin": 15,
-        "appeared": "Signing in… | Invalid email or password | Sign in"
-      }
-    ],
-    "steps": [
-      {
-        "ref": "e603",
-        "action": "fill",
-        "testid": "login-email",
-        "source": { "file": "src/components/Login.tsx", "line": 48 }
-      },
-      {
-        "ref": "e604",
-        "action": "fill",
-        "testid": "login-password",
-        "source": { "file": "src/components/Login.tsx", "line": 59 }
-      },
-      {
-        "ref": "e605",
-        "action": "click",
-        "testid": "login-submit",
-        "source": { "file": "src/components/Login.tsx", "line": 81 }
-      }
-    ]
-  }
-}
-```
-
-## Read that response again
-
-`ok: true`. `count: 3`. Every step dispatched. And the login **failed**, look at `appeared`:
-
-```
-"appeared": "Signing in… | Invalid email or password | Sign in"
-```
-
-That password was wrong. The app rejected it. And this tool still reported `ok: true`, correctly, because `ok` means _the three actions were dispatched_, which they were.
-
-<Warning>
-  This is the whole reason `act` and `act_sequence` do not produce verdicts. `ok: true` is a
-  statement about the input, not about the outcome. Follow a sequence with
-  [`reticle_act_and_wait`](/tools-act-and-wait) on the final step, or with an
-  [`reticle_assert`](/tools-assert), or you have proved nothing.
-</Warning>
-
-The honest pattern is: batch the setup, prove the outcome.
-
-```json
-{
-  "steps": [
-    { "ref": "e603", "action": "fill", "args": { "value": "admin@reticle.dev" } },
-    { "ref": "e604", "action": "fill", "args": { "value": "correct-password" } }
-  ]
-}
-```
-
-then
-
-```json
-{ "ref": "e605", "action": "click", "until": { "kind": "signal", "name": "auth:granted" } }
-```
-
-which returns the verdict the sequence could not:
-
-```json
-{
-  "verified": "yes",
-  "verifiedReason": "proved",
-  "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" } }
-  },
-  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
-}
-```
-
-Two calls instead of four, and the last one returns a verdict. Note `grade: "signal"`, the strongest Reticle awards, because the app said so itself.
-
-## What each step reports
-
-Every step comes back with the same `effect` fields as [`reticle_act`](/tools-act): `valueChanged`, `focusMoved`, `domMutatedWithin`, `occluded`. Plus its `testid`, `component` and `source`. When a sequence goes wrong, that per-step detail tells you which step, and which line of which file.
-
-<Note>
-  Steps run in order and do not stop on a soft failure, because "the field rejected the value" is
-  not an exception. It's a result you need to see. Read `effects[]` rather than assuming `ok: true`
-  means all three did what you wanted.
-</Note>

package/docs/tools-act.mdx

@@ -1,95 +0,0 @@
----
-title: reticle_act
-description: Perform an action without checking the result. Useful for setup steps, and dangerous as a final step, because ok means dispatched, not worked.
-icon: hand-pointer
----
-
-`reticle_act` clicks, fills, types, selects, drags. It does exactly one thing and makes exactly one promise: the event was dispatched.
-
-<Warning>
-  `reticle_act` **proves nothing**. If the action is supposed to cause something, use
-  [`reticle_act_and_wait`](/tools-act-and-wait) and get the verdict in the same call. A drive that
-  ends on `reticle_act` has no result.
-</Warning>
-
-## Example
-
-```json
-{ "ref": "e104", "action": "fill", "args": { "value": "reticle" } }
-```
-
-Real response:
-
-```json
-{
-  "since": 27544,
-  "inputMode": "synthetic",
-  "inputModeReason": "not-a-pointer-action",
-  "dispatched": true,
-  "settled": true,
-  "settleReason": null,
-  "result": {
-    "ok": true,
-    "ref": "e104",
-    "action": "fill",
-    "dispatched": true,
-    "settled": true,
-    "settleReason": null,
-    "testid": "login-password",
-    "component": "Login",
-    "role": "textbox",
-    "name": "Password",
-    "effect": {
-      "focusMoved": "null->e104",
-      "valueChanged": true,
-      "domMutatedWithin": 9
-    },
-    "source": { "file": "src/components/Login.tsx", "line": 59, "column": 8 }
-  }
-}
-```
-
-<Note>
-  The `effect` block only lists what is worth knowing. Fields sitting at their uninformative default
-  are **omitted**, so a clean action collapses to its consequence. An absent `dispatched`,
-  `targetMatched`, `visible` or `enabled` means `true`; an absent `occluded`, `scrolledIntoView`,
-  `valueChanged` or `defaultPrevented` means `false`; an absent `focusMoved` or `occludedBy` means
-  `null`. Do not read a missing field as a failure.
-</Note>
-
-## Actions
-
-`click` · `dblclick` · `hover` · `focus` · `blur` · `fill` · `type` · `clear` · `select` · `check` · `uncheck` · `submit` · `press` · `upload` · `scrollIntoView` · `drag` · `webmcp`
-
-| Action           | Arguments                                                       |
-| ---------------- | --------------------------------------------------------------- |
-| `fill`, `select` | `{ value }`                                                     |
-| `type`, `press`  | `{ text }`. For `press`, the key _name_, e.g. `Escape` or `Tab` |
-| `drag`           | `{ toRef }`. The ref to drop onto                               |
-| `upload`         | file arguments                                                  |
-
-## Reading the effect block
-
-This is where `act` earns its place even though it proves nothing.
-
-- **`valueChanged: true`**. The field actually took the value. `false` on a `fill` usually means the input is controlled and rejected it, or it's readonly.
-- **`focusMoved: "null->e104"`**, focus went where you expected.
-- **`domMutatedWithin: 9`**, something re-rendered within 9ms. A `fill` that mutates nothing often means no handler is attached.
-- **`defaultPrevented`**. A handler called `preventDefault()`, which is why your form didn't submit.
-- **`occluded` / `occludedBy`**. The click landed on something else. This is the answer to at least half of all "the button doesn't work" reports.
-
-## `settled: false` is not a failure
-
-`settled: true` with `settleReason: null`, as above, means a real frame flushed before Reticle stopped watching. `settled: false` with `settleReason: "timeout"` means the page was still busy. On a `fill` that's normal and uninteresting. On a click you expected to complete something, it's a hint that you wanted `act_and_wait` with an explicit `until`. A settle timeout never fails the tool.
-
-## `inputMode` tells you how real the input was
-
-`synthetic` means Reticle dispatched events programmatically. `real` means native CDP input, available under `reticle drive`. Synthetic input is fine for the overwhelming majority of apps; a few drag-and-drop and pointer-gesture libraries only respond to the real thing.
-
-`inputModeReason` explains any choice Reticle made on your behalf, so it is never silent. `not-a-pointer-action` above means a `fill` has no pointer path to take, not that real input was unavailable. Clicks default to the occlusion-honest synthetic path even when CDP is configured; pass `args.native: true` to force a trusted native click for file pickers and clipboard access.
-
-<Warning>
-  When the tab is backgrounded, synthetic timers and pointer gestures can silently no-op. Every
-  response carries a `warning` when the tab is throttled. Pass `refuseWhenThrottled: true` to make
-  Reticle throw instead of pretending it acted.
-</Warning>

package/docs/tools-assert.mdx

@@ -1,129 +0,0 @@
----
-title: reticle_assert
-description: Evaluate a predicate against what the app actually did, and get a verdict. Including a clear explanation when it fails.
-icon: gavel
----
-
-`reticle_assert` evaluates a predicate against what the app actually did and returns a verdict: `verified` plus `pass`, evidence when it holds, and `expected` versus `observed` when it does not. Reach for it when you want a verdict on something you did not just cause, or on several actions at once.
-
-It is the second of the two tools that produce a verdict, the other being [`reticle_act_and_wait`](/tools-act-and-wait). It takes the same predicate grammar and evaluates it against what already happened.
-
-## A real failure
-
-Failures are more instructive than passes, so here is one. I asserted a route change to `/` on a page that was already at `/`:
-
-```json
-{ "predicate": { "kind": "route", "pathname": "/" } }
-```
-
-```json
-{
-  "verified": "no",
-  "verifiedReason": "assertion_failed",
-  "because": "the declared consequence did not hold",
-  "pass": false,
-  "failureReason": "no route change observed",
-  "observed": "no route change in the window",
-  "expected": "a route change to /",
-  "assertion": "route.changed",
-  "source": "src/components/Login.tsx:81",
-  "buffer": {
-    "held": 536,
-    "dropped": 11,
-    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
-  }
-}
-```
-
-<Note>
-  The route predicate's field is `pathname`. `path` is accepted as an alias and rewritten, but
-  `pathname` is what the published schema declares, so it is the one to write.
-</Note>
-
-<Warning>
-  Read `assertion: "route.changed"` carefully. The `route` predicate asserts that the route
-  **changed**, not that it currently equals a value. Asserting the route you are already on will
-  always fail. This catches people out, and the response says so in `expected` rather than leaving
-  you to work it out.
-</Warning>
-
-Note also `expected` and `observed` side by side. A verdict that says only "failed" makes you go digging; this one tells you what it wanted, what it saw, and where in your source the relevant element lives.
-
-## A failure that names the real value
-
-The same shape on a store read, which is the strongest kind of failure you can get, because it quotes the app's own data back at you:
-
-```json
-{
-  "predicate": { "kind": "state", "store": "app", "path": "deployments.0.status", "equals": "live" }
-}
-```
-
-```json
-{
-  "verified": "no",
-  "verifiedReason": "assertion_failed",
-  "because": "the declared consequence did not hold",
-  "pass": false,
-  "failureReason": "state 'deployments.0.status' is \"queued\", expected \"live\"",
-  "observed": "deployments.0.status = \"queued\"",
-  "expected": "deployments.0.status = \"live\"",
-  "assertion": "state.equals",
-  "evidence": { "store": "app", "path": "deployments.0.status", "value": "queued" },
-  "source": "src/components/Login.tsx:81"
-}
-```
-
-## A pass can still come with a warning
-
-A presence-only predicate passes and tells you not to trust it much:
-
-```json
-{
-  "verified": "yes",
-  "pass": true,
-  "evidence": [
-    {
-      "ref": "e606",
-      "role": "alert",
-      "name": "Invalid email or password",
-      "visible": true,
-      "source": "src/components/Login.tsx:72",
-      "states": ["present", "visible", "enabled"]
-    }
-  ],
-  "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."
-}
-```
-
-## Arguments
-
-| Argument                 | What it does                                                      |
-| ------------------------ | ----------------------------------------------------------------- |
-| `predicate` (or `until`) | `{ kind, ...fields }`. See the [predicate reference](/predicates) |
-| `timeout_ms`             | If above zero, wait this long before failing. Default `0`         |
-| `since`                  | Cursor from a prior act. Scope to events after that action        |
-
-## Scope it with `since`
-
-By default an assertion already counts only events since your last act, so a signal buffered before the action cannot fake a pass. Pass `since` when you want to set that window explicitly: to scope to one particular earlier action, or to widen it deliberately across several.
-
-```json
-{ "predicate": { "kind": "net", "method": "POST" }, "since": 44395 }
-```
-
-The cursor comes from the preceding `reticle_act` response. Use it whenever you are asserting something an action was supposed to cause.
-
-## When to use assert over act_and_wait
-
-Use [`reticle_act_and_wait`](/tools-act-and-wait) when you are performing the action. Use `reticle_assert` when:
-
-- you are checking a precondition before acting;
-- the state was reached by several actions and you want one verdict over the lot;
-- you want to assert something extra about an action you already ran, using its `since` cursor.
-
-<Note>
-  `verified: "unknown"` means Reticle could not tell. It is not a pass, and it is not a failure, it
-  is a statement that the evidence was insufficient. Report it as unknown rather than rounding it in
-  either direction.
-</Note>

package/docs/tools-console.mdx

@@ -1,63 +0,0 @@
----
-title: reticle_console
-description: The console log, filtered by level, and an empty result that tells you it is a real reading rather than a missing one.
-icon: terminal
----
-
-`reticle_console` returns the app's console log, filtered by level, and tells you whether an empty result is a real reading or a missing one. Reach for it as the fast triage read after something goes wrong, and assert `{ "kind": "console", "absent": true }` when you want a clean console to be part of the pass.
-
-```json
-{ "limit": 3 }
-```
-
-Real response from a page with a clean console:
-
-```json
-{
-  "logs": [],
-  "buffer": {
-    "held": 535,
-    "dropped": 10,
-    "note": "event buffer evicted older events (age/size cap): a negative result here may be a false negative; the evidence may have expired. Grade sooner or widen the buffer."
-  },
-  "observed": true,
-  "note": "no console lines; the observation ran and found none, which is a result, not a missing reading",
-  "cost": { "bytes": 338, "tokens": 85 }
-}
-```
-
-## The empty result is the interesting one
-
-An empty array is ambiguous in almost every tool that returns one. Did nothing happen, or did the observation not run? Reticle answers both:
-
-- **`observed: true`** with that `note`. The observation ran and genuinely found nothing. You may treat a clean console as a fact.
-- **`buffer.dropped: 10`**, older events were evicted. If you are asking about something from a while ago, the honest answer is "not in what I still have", not "it didn't happen".
-
-Read both fields together. `observed: true` with a non-zero `dropped` count means _recently_ clean, which is usually what you wanted but is not the same as _always_ clean.
-
-## Arguments
-
-| Argument          | What it does                                         |
-| ----------------- | ---------------------------------------------------- |
-| `level`           | `log` · `warn` · `error` · `info`                    |
-| `limit`           | Most recent N. Older matches are dropped and counted |
-| `actionId`        | Only lines attributed to one action                  |
-| `since` / `until` | Cursors from a prior act                             |
-
-## The check worth making by default
-
-Plenty of features "work" while quietly throwing. Assert the clean console as part of the action rather than checking afterwards:
-
-```json
-{ "ref": "e605", "action": "click", "until": { "kind": "console", "absent": true } }
-```
-
-That fails if the click succeeds _and_ logs an error, which is exactly the case a human reviewer tends to wave through.
-
-<Tip>
-  `level: "error"` is the fast triage read. If it comes back empty with `observed: true`, stop
-  looking at the console and go look at [`reticle_network`](/tools-network) or
-  [`reticle_state`](/tools-state) instead. That is a real capture from this fixture:
-  `{"logs":[],"observed":true,"cost":{"bytes":337,"tokens":85}}`, eighty-five tokens to rule out a
-  whole class of bug.
-</Tip>

package/docs/tools-inspect.mdx

@@ -1,88 +0,0 @@
----
-title: reticle_inspect
-description: Everything about one element. Accessibility properties, geometry, computed styles, design tokens, React component stack, and the exact source file and line.
-icon: crosshairs
----
-
-`reticle_query` finds elements. `reticle_inspect` tells you everything about one of them. It is the tool that turns a finding into an edit, because it ends with a file and a line number.
-
-## Example
-
-```json
-{ "ref": "e120" }
-```
-
-Real response:
-
-```json
-{
-  "ref": "e120",
-  "role": "button",
-  "name": "Compose",
-  "visible": true,
-  "source": "src/components/Sidebar.tsx:41",
-  "tag": "button",
-  "occluded": false,
-  "states": ["present", "visible", "enabled"],
-  "box": { "x": 14, "y": 212.75, "width": 219, "height": 38 },
-  "styles": {
-    "color": "rgb(147, 152, 168)",
-    "backgroundColor": "rgba(0, 0, 0, 0)",
-    "opacity": "1",
-    "cursor": "pointer",
-    "display": "flex",
-    "visibility": "visible"
-  },
-  "scroll": { "scrollTop": 0, "scrollHeight": 36, "clientHeight": 36, "overflowY": "visible" },
-  "theme": {
-    "colorToken": "--muted",
-    "backgroundToken": null,
-    "offTheme": false,
-    "tokenCount": 18,
-    "themeScope": null,
-    "colorTokens": ["--muted"],
-    "backgroundTokens": []
-  },
-  "component": {
-    "componentStack": ["Sidebar", "App", "QueryClientProvider"],
-    "source": { "file": "src/components/Sidebar.tsx", "line": 41, "column": 8 }
-  }
-}
-```
-
-## What each block is for
-
-**`component`** is the payoff. The stack `["Sidebar", "App", "QueryClientProvider"]` tells your agent where this element lives in the tree, and `source` tells it which file to open. This needs `@reticlehq/react`; without it you still get everything else.
-
-**`theme`** catches a bug class most tools cannot see. `colorToken: "--muted"` means this colour came from your design system. `offTheme: false` means nothing here is a hardcoded hex that slipped past review. An agent that pastes `color: #939AA8` instead of using the token produces a change that looks identical and quietly forks your design system. This field is how that gets caught.
-
-Read `colorTokens` rather than `colorToken` when it matters. Design systems routinely give several tokens the same value, and the singular field is `null` whenever more than one matches, because naming an arbitrary winner is worse than admitting the palette cannot tell them apart. `themeScope` says which theme the reading was taken under, so two inspects either side of a theme toggle are comparable instead of quietly contradictory. It is `null`, as above, when the element sits under no scoped theme at all.
-
-**`scroll`** reports the element's own scroll box. `scrollHeight` above `clientHeight` means there is content below the fold inside this element, which is a different problem from the page being scrolled wrong.
-
-**`occluded`** is the difference between "visible" and "actually clickable". An element can be present, visible and enabled while sitting under a modal overlay. `states` will look perfect; `occluded: true` is the honest answer.
-
-**`box`** is geometry in CSS pixels. Useful for layout assertions and for working out whether something is off-screen rather than hidden.
-
-## When to reach for it
-
-<CardGroup cols={2}>
-  <Card title="A click did nothing" icon="hand-pointer">
-    Check `occluded` and `states` before assuming the handler is broken. Very often the handler is
-    fine and something is sitting on top of it.
-  </Card>
-  <Card title="You need to edit the code" icon="file-pen">
-    `component.source` is the file and line. This is the fastest path from symptom to diff.
-  </Card>
-  <Card title="A style looks wrong" icon="palette">
-    `theme.offTheme` tells you whether the value came from your tokens or from somebody's clipboard.
-  </Card>
-  <Card title="Layout is suspicious" icon="ruler">
-    `box` gives you real geometry, no screenshot and no vision model required.
-  </Card>
-</CardGroup>
-
-<Note>
-  `inspect` returns one element in detail. If you find yourself inspecting six things in a row, you
-  probably want [`reticle_query`](/tools-query) with `attrs` instead, one call, six answers.
-</Note>

package/docs/tools-navigate.mdx

@@ -1,107 +0,0 @@
----
-title: reticle_navigate
-description: Move the connected tab to a URL or reload it, and understand why ok does not mean the page arrived.
-icon: compass
----
-
-`reticle_navigate` moves the connected browser tab to a URL, or reloads it in place with `{ "reload": true }`. Reach for it for a genuine document load: a deep link, a hard refresh, or the first visit. Clicking a link inside a single-page app is a route change, not a navigation, and does not need this tool.
-
-```json
-{ "url": "/deployments" }
-```
-
-Real response, with the throttled-tab `session` and `warning` fields trimmed off:
-
-```json
-{
-  "ok": true,
-  "url": "http://localhost:4310/deployments",
-  "confirmed": false,
-  "waitedMs": 5000,
-  "note": "ok means the navigation was DISPATCHED, not that the page arrived. The SDK is torn down by the navigation itself, so nothing here can see the new document, and no session reconnected at the new URL within 5000ms. A slow app may still be on its way (an SPA reattaching under HMR can take 30-60s): navigate again with a larger timeout_ms, or call reticle_sessions to confirm a session reconnected before acting; if none appears, the page did not load or is not instrumented."
-}
-```
-
-## `confirmed: true` when the page comes back in time
-
-The daemon waits up to `timeout_ms` (default 5000) for the SDK to re-announce itself. When it does, you are told so and can act immediately without a `reticle_sessions` round trip. This is a real reload response:
-
-```json
-{
-  "ok": true,
-  "confirmed": true,
-  "note": "the page came back and re-announced itself under the same session id, so this session is live again. Anything captured before the reload is gone with the old document."
-}
-```
-
-Read the second sentence, which is the one that costs people a turn. `confirmed: true` restores the session, not the evidence: every event, network call and console line captured before the reload went with the old document.
-
-## `confirmed: false` is the honest part
-
-A full navigation destroys the document the SDK was living in. Reticle cannot report on the new page from inside the old one, because the old one no longer exists. So it tells you what it actually knows: the navigation was dispatched.
-
-Most tools would return `ok: true` and let you assume arrival. When the page then fails to load, or loads without instrumentation, you get a confusing cascade of "element not found" errors several calls later, with nothing pointing at the real cause.
-
-`waitedMs` says which of two things you are looking at. Reticle stopped waiting at the budget it had, or the page never came back. The first is fixed by asking for more: a single-page app reattaching under HMR has been measured at 30–60s, which no default should wait for on every call, but which the caller who knows the app can grant.
-
-```json
-{ "url": "/deployments", "timeout_ms": 45000 }
-```
-
-## The pattern after navigating
-
-```json
-{ "url": "/deployments" }
-```
-
-then confirm a session reconnected:
-
-```json
-{}
-```
-
-with [`reticle_sessions`](/tools-sessions), and only then snapshot. If no session appears at the new URL, the page did not load or is not instrumented. And you know that immediately rather than three calls later.
-
-<Warning>
-  **Refs do not survive a navigation.** A new document means new refs. Across one afternoon on the
-  same fixture, the same "Sign in" button was `e105`, then `e305`, then `e3`. Re-snapshot; never
-  carry refs across. Reticle refuses a stale ref rather than clicking whatever now occupies the
-  slot, so the failure is loud, but it still costs you a turn.
-</Warning>
-
-## Arguments
-
-| Argument | What it does |
-| --- | --- |
-| `url` | Where to go. Relative paths work |
-| `reload` | Reload in place instead of navigating |
-| `hard` | With `reload`, bypass the cache |
-| `timeout_ms` | How long to wait for the page to come back before `confirmed: false`. Default 5000; 0 looks once |
-
-## Client-side routing is different
-
-In a single-page app, clicking a link usually changes the route without destroying the document. That is a route change, not a navigation. Refs survive, and you can assert it directly:
-
-```json
-{ "ref": "e618", "action": "click", "until": { "kind": "route", "pathname": "/deployments" } }
-```
-
-That is a verified call. Its verdict quotes the transition itself:
-
-```json
-{
-  "verified": "yes",
-  "verdict": {
-    "pass": true,
-    "evidence": {
-      "from": "http://localhost:4310/",
-      "to": "http://localhost:4310/deployments",
-      "pathname": "/deployments",
-      "search": "",
-      "hash": ""
-    }
-  }
-}
-```
-
-Use `reticle_navigate` for a genuine document load. A deep link, a hard reload, or the first visit.