@reticlehq/server 3.3.0 → 3.5.0

package/docs/vs-screenshots.mdx

@@ -80,11 +80,11 @@ Those are real bugs and structural reads can miss them. Reticle has `reticle_scr
 
 The argument is not "screenshots are bad". It is that a screenshot cannot answer "did the code work", and that is the question an AI coding agent needs answered on every change.
 
-## The honest limits
+## What is measured, and what is not
 
-We have not proven that Reticle makes agents _fix_ more bugs. A controlled test did not show a fix-rate improvement; the benchmark was confounded and we are still working on measuring it properly.
+What is measured is detection: 10 of 10 injected regressions caught with zero false alarms, against 9 and 8 for the alternatives, and one false green against a Playwright script's 29 over an 88-bug registry.
 
-What is measured is detection: 10 of 10 injected regressions caught with zero false alarms, against 9 and 8 for the alternatives.
+What is not established is that Reticle makes agents _fix_ more bugs. A fix-loop test on a small fixture found the same fix rate with and without it; [Why Reticle](/why-reticle#what-the-fix-rate-test-measured) says what that test could and could not show.
 
 ## FAQ
 

package/docs/what-is-recorded.md

@@ -5,7 +5,7 @@ description: What Reticle keeps on your machine, what is redacted, and what it t
 
 Reticle drives your app and reads what it did. That means it holds real content from real pages, so this page says exactly what it keeps, where it keeps it, and what it takes to make any of it leave.
 
-If you read one line: **a verdict is entirely local and needs no account.** Nothing is sent anywhere until you run `reticle login` and `reticle link`. Without them there is nowhere for anything to go.
+If you read one line: **a verdict is entirely local and needs no account.** Nothing from your project is sent anywhere until you run `reticle login` and `reticle link`. Without them there is nowhere for it to go. (Anonymous usage counts, which carry nothing from your app, are separate and described in [Telemetry](telemetry.md).)
 
 ## On your machine
 
@@ -31,7 +31,7 @@ Network bodies are **not** captured by default. Page content that reaches a verd
 
 ## What leaves, only if you ask
 
-`reticle login` signs this machine in. `reticle link` binds one repo to one cloud project. Until both have happened, `reticle push` has nothing to talk to and the sync path is a no-op. The code calls this the no-phone-home default.
+`reticle login` signs this machine in. `reticle link` binds one repo to one cloud project. Until both have happened, or `RETICLE_API_KEY` is set in the environment, `reticle push` has nothing to talk to and the sync path is a no-op. The code calls this the no-phone-home default. A key in the environment is how CI syncs with no login and no link, and it goes to the hosted service unless `RETICLE_CLOUD_URL` names another host.
 
 Once linked, you choose what syncs:
 

package/docs/what-is-reticle.mdx

@@ -1,7 +1,7 @@
 ---
 title: What is Reticle?
 sidebarTitle: What is Reticle
-description: Reticle is a verification layer for AI coding agents. It runs a dev-only SDK inside your running web app so an agent can prove a change works, instead of guessing. What it is, what it is not, and what it needs.
+description: Reticle is a verification layer for AI coding agents. It runs a dev-only SDK inside your running web app so an agent can prove a change works, instead of guessing. What it is, where it fits beside other tools, and what it needs.
 icon: circle-question
 ---
 
@@ -12,37 +12,33 @@ It exists because an agent that writes code cannot otherwise tell whether that c
 ## How it works, in three parts
 
 1. **An SDK inside the app.** Dev-only, stripped from production builds, added by a build plugin. It instruments the DOM, network, routing, console, animations, and your state library.
-2. **A local bridge.** The SDK connects over a WebSocket to a daemon on your machine. The daemon never starts or manages your dev server. It attaches to the app that is running. If none is, the agent is the one told to start it, using your project's own dev script, in the background, and saying so.
-3. **An MCP server.** The daemon exposes the app to your agent as tools. `reticle_snapshot` to look, `reticle_act_and_wait` to act and prove in one call, `reticle_state` and `reticle_network` to observe, `reticle_assert` to check.
+2. **A local bridge.** The SDK connects over a WebSocket to a daemon on your machine, bound to `127.0.0.1`. The daemon never manages your dev server; it attaches to the app that is running. On first setup, `npx @reticlehq/server init` starts the dev server with your project's own dev script and opens the app.
+3. **An MCP server.** The daemon exposes the app to your agent as tools. `reticle_look` to look, `reticle_act_and_wait` to act and prove in one call, `reticle_observe` to read what the app did, `reticle_assert` to check.
 
-Everything stays on your machine. No application code, DOM, network traffic, or console output leaves it.
+Your app's data stays on your machine: no application code, DOM, network traffic, state or console output leaves it. Anonymous usage counts are sent by default and can be [turned off](/telemetry).
 
-## What Reticle is not
+## Where it fits
 
-This is the section most people need, because Reticle sits next to several familiar categories without being any of them.
+Reticle sits next to several familiar categories, and it works alongside each of them.
 
-**Not a browser automation framework.** Playwright, Cypress and Selenium drive a browser from the outside and are excellent at it. Reticle runs inside the page you already have open. If you want to script a browser, use Playwright. Reticle is what an agent uses to answer "did the thing I just changed actually work?"
+**Browser automation.** Playwright, Cypress and Selenium drive a browser from the outside. Reticle runs inside the page you already have open and answers "did the thing I just changed actually work?" Playwright remains the tool for sites you don't own and for a cross-browser matrix.
 
-**Not a replacement for your test suite.** Unit and integration tests still do their job. Reticle covers the layer they structurally cannot reach: behaviour that only exists when the whole application runs. Many teams use both, and Reticle is often the thing that catches a suite passing over a broken app.
+**Your test suite.** Unit and integration tests keep doing their job. Reticle covers the layer they cannot reach: behaviour that only exists when the whole application runs, which is often where a suite passes over a broken app.
 
-**Not a screenshot or visual regression tool.** It can take screenshots, but the point is that it does not need to. Verdicts come from predicates over real events, a request with a status, a state path, a signal your code fired, so they do not break when a button moves four pixels. If pixel-perfect visual diffing is your goal, a dedicated visual testing service fits better.
+**Visual testing.** Reticle can take screenshots, but its verdicts come from predicates over real events (a request with a status, a state path, a signal your code fired), so they do not break when a button moves four pixels. For pixel-level diffs, pair it with a visual testing tool.
 
-**Not a monitoring or observability product.** Reticle is a development-time tool aimed at localhost. It is not an APM, not error tracking, and it does not watch production.
+**Security, accessibility, performance and SEO.** Reticle checks how your running app behaves in each: access control by role, calls that must never fire, focus and keyboard behaviour, request counts and long tasks, titles, links and redirects. It pairs with a vulnerability scanner, a full WCAG audit tool such as axe, and an SEO crawler. [Use cases](/use-cases) has what each check covers.
 
-**Not an accessibility auditor.** `reticle_snapshot` addresses elements by role and name, which is not the same as auditing contrast, focus order, or screen reader behaviour. Use a dedicated accessibility tool for that.
+**Monitoring.** Reticle runs against environments you control (a dev server, a staging or preview deployment) and replays saved flows in CI. The SDK refuses to connect in a production build, so it complements an APM or error tracker rather than watching live traffic.
 
-**Not an AI model, and not an agent.** Reticle has no model of its own and makes no decisions. It gives an agent you already use a way to see the running app. Your agent, your model, your keys.
+**Your agent.** Reticle has no model of its own for the verify loop. It gives the agent you already use a way to see the running app. Your agent, your model, your keys. (`explore` can drive a journey for you with a model inside the daemon; see [Autodrive](/autodrive).)
 
-**Not a hosted service that receives your application data.** The daemon runs on your machine and the SDK runs in your browser. Anonymous product analytics are sent unless you opt out, and they never include your code or your application's data. See the [Telemetry Policy](https://www.reticle.sh/legal/telemetry).
-
-**Not a way to make a failing check pass.** A verdict of `unknown` means Reticle drove the app and could not tell. It is deliberately not rounded up to a pass, because a verification tool that flatters you is worse than none.
+**The verdict.** A verdict of `unknown` means Reticle drove the app and could not tell. It is deliberately not rounded up to a pass.
 
 ## What Reticle needs
 
-Honest constraints, so you can tell in a minute whether it fits:
-
-- **A web application you can run locally**, with its dev server. Reticle attaches; it does not start one.
-- **A build step it can hook**, or two lines added by hand. Vite, Next.js, Remix and Astro are proven by gates in the repository. The SDK is framework agnostic and usually connects elsewhere, with reduced source mapping.
+- **A web application you can run**, with a dev build. `init` starts its dev server for you.
+- **A build step it can hook**, or two lines added by hand. [Frameworks](/frameworks) lists what is proven for each.
 - **An agent that speaks MCP.** Claude Code, Cursor, Codex, Copilot, Windsurf, OpenCode and others.
 - **Node 20 or newer.**
 
@@ -59,5 +55,6 @@ Side by side with the tools people ask about most:
 ## Where to go next
 
 - [Quickstart](/quickstart) gets a real verdict out of your own app in about five minutes.
-- [Why Reticle](/why-reticle) is the argument, with the evidence and the cases where it loses.
+- [Why Reticle](/why-reticle) is the argument, with the evidence and what pairs well with it.
+- [Use cases](/use-cases) covers what people verify with it.
 - [For agents](/for-agents) is written for the agent rather than for you.

package/docs/why-reticle.mdx

@@ -63,37 +63,30 @@ Observing one real dashboard once, with no bug involved:
 That last column is the one that matters more than the token counts. The other tools can _describe_ what a page looks like. Only Reticle can check whether the thing the app itself considers success actually happened.
 
 <Card title="How every number was measured" icon="chart-column" href="/benchmarks">
-  The full method, the raw data, and the scenarios where Reticle comes second.
+  The full method, the raw data, and the scenarios where the tools tie.
 </Card>
 
-## Where Reticle loses
+On raw cost per glance, Chrome DevTools MCP is cheaper: 758 tokens against 815. It catches fewer bugs, which is why the efficiency column favours Reticle.
 
-A benchmark that only shows you the wins is an advertisement wearing a lab coat. Ours doesn't.
+## What the fix-rate test measured
 
-- **Sites you don't own.** Reticle needs a dev-only SDK inside the app. If you're driving a third party's website, use Playwright. That is what it's for, and it's excellent at it.
-- **Pixels.** Reticle reads the program, not the screen. If your bug is "the button is three pixels too far left", Reticle is the wrong instrument.
-- **Chrome DevTools MCP is cheaper per look.** 758 tokens against our 815. It catches fewer bugs, so the efficiency works out in our favour, but on raw cost per glance it wins.
+We ran a fix-loop ablation: agents fixed 8 bugs injected into a small fixture app, with Reticle and without it, on a strong model and on a weaker one. **It did not show a fix-rate improvement at either tier.** The strong model fixed 8 of 8 in both conditions and the weaker one 7 of 8 in both, and the Reticle arm made roughly five to six times the tool calls, because driving an app costs more than reading a few short files.
 
-## What we have not proven
+The test cannot settle the question in either direction, and the reasons are specific: the fixture is small enough to read whole, several injected bugs were labelled by a comment on the changed line, and "fixed" was checked by a string disappearing rather than by the app behaving. One case pointed each way. The weaker model without Reticle claimed a fix it never applied, and the live re-check caught that with Reticle; with Reticle, the same model over-edited a stylesheet the string check scored as a pass. The full log is in [`bench/fix-loop/results.md`](https://github.com/reticlehq/reticle/blob/main/bench/fix-loop/results.md).
 
-Being honest here costs us something, and we'd rather pay it than have you find out later.
+A separate, smaller measurement of the source pointer alone found the same fix rate with and without it (6 of 6) and fewer tool calls with it (12 against 22). The pointer removed the search; it did not make the agent more capable.
 
-We ran a controlled test of whether an agent equipped with Reticle _fixes_ more bugs than one without it. **It did not show a fix-rate improvement.** The benchmark was confounded in ways we can point at, and we don't consider the question settled. But we are not going to claim a number we didn't measure.
+That is what Reticle is designed to improve: not the agent, but the verdict it reports. A broken build reads as broken, a failure arrives with the evidence and the `file:line`, and "I couldn't tell" is reported as that. In the 88-bug head-to-head against a Playwright script, Reticle reported one false green where the script reported 29.
 
-What Reticle demonstrably does is catch failures that are invisible to the alternatives, and hand back the file and line to go fix. Whether that translates into a better fix rate is a separate question, and we're still working on measuring it properly.
+## When to use it
 
-## When you should use it
+You own the app, an agent edits it, and you want the agent to prove its work rather than assure you of it. It needs a dev build it can instrument, and React (and any framework whose build plugin stamps source) adds source pointers on top. [Use cases](/use-cases) covers what people check with it beyond change verification, from access control to accessibility.
 
-<CardGroup cols={2}>
-  <Card title="A good fit" icon="circle-check">
-    You own the app. An agent edits it. You want the agent to prove its work rather than assure you
-    of it. React gets you source pointers on top.
-  </Card>
-  <Card title="A bad fit" icon="circle-xmark">
-    You're testing a site you don't control, you need pixel-level visual regression, or your app has
-    no dev build to instrument.
-  </Card>
-</CardGroup>
+## Pairs well with
+
+- **Playwright** for driving sites you don't own and a cross-browser matrix. Reticle needs its dev-only SDK inside the app.
+- **A visual testing tool** for pixel-level regression. Reticle reads the program, not the screen, so "the button is three pixels too far left" is a job for pixels.
+- **axe** for full WCAG audits, and **a security scanner** for vulnerability discovery.
 
 ## The one-sentence version
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@reticlehq/server",
-  "version": "3.3.0",
-  "description": "Reticle bridge + MCP server. Hosts the browser WS endpoint and exposes MCP tools to the coding agent.",
+  "version": "3.5.0",
+  "description": "Reticle CLI, bridge and MCP server: a coding agent drives your running web app from the inside and gets a verdict with evidence, for change verification, access control, accessibility, performance and SEO checks.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,24 +19,24 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.30.1",
     "ws": "^8.21.3",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.0",
-    "@reticlehq/engine": "3.3.0",
-    "@reticlehq/browser": "3.3.0",
-    "@reticlehq/init": "3.3.0",
+    "@reticlehq/browser": "3.5.0",
+    "@reticlehq/engine": "3.5.0",
+    "@reticlehq/core": "3.5.0",
     "open-verification": "1.0.0",
-    "@reticlehq/core": "3.3.0"
+    "@reticlehq/init": "3.5.0"
   },
   "devDependencies": {
     "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.5.13",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.1"
   },
   "optionalDependencies": {
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.62.1",
+    "playwright": "^1.63.0",
     "pngjs": "^7.0.0"
   },
   "license": "FSL-1.1-ALv2",
@@ -60,6 +60,7 @@
     "mcp",
     "ai-agents",
     "testing",
+    "verification",
     "cli"
   ],
   "reticle": {

package/dist/judgement/capsule/minimize.d.ts

@@ -1,12 +0,0 @@
-/**
- * Bug-capsule minimization — first cut: prefix-trim. A recorded flow that fails is often mostly setup;
- * the capsule should be the SMALLEST flow that still reproduces the failure, so a regression flow stays
- * fast and legible. Prefix-trim drops leading steps while the failure persists — the cheap, deterministic
- * v1 (delta-debugging over arbitrary subsets is a later refinement). The `stillFails` predicate is
- * injected (a real replay), so this stays pure and unit-testable.
- */
-/**
- * Return the shortest trailing sub-flow that still fails, by removing leading steps one at a time while
- * `stillFails` holds. Never trims below one step. Deterministic given a deterministic predicate.
- */
-export declare function prefixTrim<T>(steps: readonly T[], stillFails: (candidate: readonly T[]) => Promise<boolean>): Promise<T[]>;

package/dist/judgement/capsule/minimize.js

@@ -1,22 +0,0 @@
-/**
- * Bug-capsule minimization — first cut: prefix-trim. A recorded flow that fails is often mostly setup;
- * the capsule should be the SMALLEST flow that still reproduces the failure, so a regression flow stays
- * fast and legible. Prefix-trim drops leading steps while the failure persists — the cheap, deterministic
- * v1 (delta-debugging over arbitrary subsets is a later refinement). The `stillFails` predicate is
- * injected (a real replay), so this stays pure and unit-testable.
- */
-/**
- * Return the shortest trailing sub-flow that still fails, by removing leading steps one at a time while
- * `stillFails` holds. Never trims below one step. Deterministic given a deterministic predicate.
- */
-export async function prefixTrim(steps, stillFails) {
-    let kept = [...steps];
-    while (kept.length > 1) {
-        const trimmed = kept.slice(1);
-        if (await stillFails(trimmed))
-            kept = trimmed;
-        else
-            break;
-    }
-    return kept;
-}

package/dist/judgement/phenomena/phenomena.d.ts

@@ -1,27 +0,0 @@
-import { PhenomenonType, type JournalAction, type ReticleEvent } from '@reticlehq/core';
-/**
- * A detected phenomenon — a named, evidence-backed anomaly over the journal. Deterministic matchers, no
- * scanning by the agent: the layer names the fault, the agent acts on the name. `pre-hydration-click`
- * lands once the hydration signal (a later item) exists; the three here need only journal data.
- */
-interface Finding {
-    phenomenon: PhenomenonType;
-    evidence: Record<string, unknown>;
-}
-/** A request that started (NET_PENDING) but never completed (no NET_REQUEST with the same id). */
-export declare function detectHungRequests(events: readonly ReticleEvent[]): Finding[];
-/** A 5xx response observed while the page was hidden — an error the user never sees. */
-export declare function detectHidden500(events: readonly ReticleEvent[]): Finding[];
-/** An act that dispatched but attributed no events — the app did nothing. */
-export declare function detectDeadClicks(actions: readonly JournalAction[]): Finding[];
-/**
- * A click that landed BEFORE React hydration attached handlers — a silent no-op. Detectable only in-app:
- * the hydration-complete signal's time vs the click action's dispatch. No signal ⇒ can't tell (not a
- * React app, or hydration never completed), so we don't guess.
- */
-export declare function detectPreHydrationClicks(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];
-/** A React error boundary that caught and swallowed — surfaced on the signal channel by the adapter. */
-export declare function detectSwallowedErrors(events: readonly ReticleEvent[]): Finding[];
-/** Run every journal-only matcher over a session's events + actions. */
-export declare function detectPhenomena(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];
-export {};

package/dist/judgement/phenomena/phenomena.js

@@ -1,101 +0,0 @@
-import { EventType, FlowStepTool, PhenomenonType, RETICLE_ERROR_BOUNDARY_SIGNAL, RETICLE_HYDRATION_SIGNAL, } from '@reticlehq/core';
-/** ACT tools that represent a user-style interaction (a "click"), for dead-click detection. */
-const CLICK_TOOLS = new Set([FlowStepTool.ACT, FlowStepTool.ACT_AND_WAIT]);
-/** A request that started (NET_PENDING) but never completed (no NET_REQUEST with the same id). */
-export function detectHungRequests(events) {
-    const completed = new Set();
-    for (const event of events) {
-        if (event.type === EventType.NET_REQUEST)
-            completed.add(event.data['id']);
-    }
-    const findings = [];
-    for (const event of events) {
-        if (event.type !== EventType.NET_PENDING)
-            continue;
-        if (completed.has(event.data['id']))
-            continue;
-        findings.push({
-            phenomenon: PhenomenonType.HUNG_REQUEST,
-            evidence: { id: event.data['id'], method: event.data['method'], url: event.data['url'] },
-        });
-    }
-    return findings;
-}
-/** A 5xx response observed while the page was hidden — an error the user never sees. */
-export function detectHidden500(events) {
-    const findings = [];
-    let hidden = false;
-    for (const event of events) {
-        if (event.type === EventType.PAGE_HEALTH) {
-            const h = event.data['hidden'];
-            if ('boolean' === typeof h)
-                hidden = h;
-            continue;
-        }
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const status = event.data['status'];
-        if (hidden && 'number' === typeof status && status >= 500) {
-            findings.push({
-                phenomenon: PhenomenonType.HIDDEN_500,
-                evidence: { url: event.data['url'], status, method: event.data['method'] },
-            });
-        }
-    }
-    return findings;
-}
-/** An act that dispatched but attributed no events — the app did nothing. */
-export function detectDeadClicks(actions) {
-    const findings = [];
-    for (const action of actions) {
-        if (!CLICK_TOOLS.has(action.tool))
-            continue;
-        if (action.seqRange !== undefined)
-            continue; // it caused something → not dead
-        findings.push({
-            phenomenon: PhenomenonType.DEAD_CLICK,
-            evidence: { actionId: action.actionId, tool: action.tool, args: action.args },
-        });
-    }
-    return findings;
-}
-/**
- * A click that landed BEFORE React hydration attached handlers — a silent no-op. Detectable only in-app:
- * the hydration-complete signal's time vs the click action's dispatch. No signal ⇒ can't tell (not a
- * React app, or hydration never completed), so we don't guess.
- */
-export function detectPreHydrationClicks(events, actions) {
-    const hydration = events.find((e) => e.type === EventType.SIGNAL && e.data['name'] === RETICLE_HYDRATION_SIGNAL);
-    if (hydration === undefined)
-        return [];
-    return actions
-        .filter((a) => CLICK_TOOLS.has(a.tool) && a.tRange.from < hydration.t)
-        .map((a) => ({
-        phenomenon: PhenomenonType.PRE_HYDRATION_CLICK,
-        evidence: { actionId: a.actionId, clickedAt: a.tRange.from, hydratedAt: hydration.t },
-    }));
-}
-/** A React error boundary that caught and swallowed — surfaced on the signal channel by the adapter. */
-export function detectSwallowedErrors(events) {
-    const findings = [];
-    for (const event of events) {
-        if (event.type === EventType.SIGNAL && event.data['name'] === RETICLE_ERROR_BOUNDARY_SIGNAL) {
-            const detail = event.data['data'];
-            findings.push({
-                phenomenon: PhenomenonType.SWALLOWED_ERROR,
-                evidence: 'object' === typeof detail && detail !== null ? detail : {},
-            });
-        }
-    }
-    return findings;
-}
-/** Run every journal-only matcher over a session's events + actions. */
-export function detectPhenomena(events, actions) {
-    return [
-        ...detectHungRequests(events),
-        ...detectHidden500(events),
-        ...detectDeadClicks(actions),
-        ...detectPreHydrationClicks(events, actions),
-        ...detectSwallowedErrors(events),
-    ];
-}

package/dist/language/flows/flow-report.d.ts

@@ -1,22 +0,0 @@
-import { type FlowFile, type FlowReplayResult } from '@reticlehq/core';
-/**
- * Render a HUMAN-facing confidence report for a replayed flow — the artifact a developer reads to
- * trust the test without re-running it. It answers the three confidence questions in one page:
- * WHY — the declared business intent (+ whether it is actually asserted).
- * WHAT — the journey: a mermaid flow diagram + a per-step page → action → consequence table.
- * PROOF — the verdict (pass/drift/fail), the observed evidence (signals/network), and the
- * measured cost (deterministic replay tokens vs an LLM re-drive).
- *
- * Pure: no IO, no clock. Markdown out (mermaid is the one place mermaid earns its tokens — a human
- * renders it). Token figures are passed in (measured by the caller), never faked.
- */
-interface FlowReportInput {
-    flow: FlowFile;
-    replay: FlowReplayResult;
-    /** Measured deterministic replay cost (o200k proxy), for the "PROOF / cost" line. Optional. */
-    replayTokens?: number;
-    /** Measured per-run LLM re-drive cost of a step-driving tool, for the ratio. Optional. */
-    competitorTokens?: number;
-}
-export declare function buildFlowReport(input: FlowReportInput): string;
-export {};

package/dist/language/flows/flow-report.js

@@ -1,106 +0,0 @@
-import { ReplayStatus, } from '@reticlehq/core';
-import { classifyFlowAssertions } from './flow-classify.js';
-import { SUCCESS_STEP_TOOL } from './flow-success.js';
-const VERDICT_GLYPH = {
-    [ReplayStatus.OK]: '✅ pass',
-    [ReplayStatus.DRIFT]: '⚠️ drift',
-    [ReplayStatus.ERROR]: '❌ fail',
-};
-/** A mermaid-safe node id (mermaid ids must be alnum/underscore). */
-function nodeId(index) {
-    return `s${index}`;
-}
-/** Escape a label for a mermaid `["..."]` node (quotes/newlines break the parser). */
-function mermaidLabel(text) {
-    return text.replace(/"/g, "'").replace(/\n/g, ' ').slice(0, 80);
-}
-/** A short action verb for a step row ("act" is the tool; the anchor carries the target). */
-function stepAction(step) {
-    return step.tool === SUCCESS_STEP_TOOL ? 'assert outcome' : step.anchor;
-}
-/** The mermaid flowchart of the journey: one node per step, page-labelled, consequence on the edge. */
-function mermaidDiagram(steps) {
-    const lines = ['```mermaid', 'flowchart TD'];
-    steps.forEach((step, i) => {
-        const page = step.page !== undefined ? `${step.page} — ` : '';
-        const glyph = step.ok ? '' : ' ✗';
-        lines.push(`  ${nodeId(i)}["${mermaidLabel(`${page}${stepAction(step)}${glyph}`)}"]`);
-        if (i > 0) {
-            const edge = steps[i - 1]?.consequence;
-            const label = edge !== undefined ? `|"${mermaidLabel(edge)}"|` : '';
-            lines.push(`  ${nodeId(i - 1)} -->${label} ${nodeId(i)}`);
-        }
-    });
-    lines.push('```');
-    return lines.join('\n');
-}
-/** The per-step journey table (page → action → consequence → result). */
-function journeyTable(steps) {
-    const rows = [
-        '| # | page | action | consequence | result |',
-        '|---|------|--------|-------------|--------|',
-    ];
-    for (const step of steps) {
-        const page = step.page ?? '—';
-        const consequence = step.consequence ?? '—';
-        const result = step.ok
-            ? 'ok'
-            : step.drift !== undefined
-                ? `drift (${step.drift.anchor})`
-                : 'fail';
-        rows.push(`| ${step.step} | ${page} | ${stepAction(step)} | ${consequence} | ${result} |`);
-    }
-    return rows.join('\n');
-}
-/** Distinct observed consequences across the journey — the evidence the verdict rests on. */
-function evidenceList(steps) {
-    const seen = new Set();
-    for (const step of steps) {
-        if (step.consequence !== undefined) {
-            for (const part of step.consequence.split(';'))
-                seen.add(part.trim());
-        }
-    }
-    if (0 === seen.size)
-        return '_No observable consequence captured._';
-    return [...seen].map((e) => `- ${e}`).join('\n');
-}
-export function buildFlowReport(input) {
-    const { flow, replay, replayTokens, competitorTokens } = input;
-    const grade = classifyFlowAssertions(flow);
-    const verdict = VERDICT_GLYPH[replay.status] ?? replay.status;
-    const intent = flow.intent ?? '_(no intent declared)_';
-    const intentLine = flow.intent !== undefined
-        ? grade.intentVerified
-            ? `**Intent:** ${flow.intent} — **verified** (an observable outcome is asserted).`
-            : `**Intent:** ${flow.intent} — ⚠️ declared but NOT asserted (add a consequence oracle).`
-        : `**Intent:** ${intent}`;
-    const out = [];
-    out.push(`# Flow report — \`${flow.name}\``);
-    out.push('');
-    out.push(intentLine);
-    out.push(`**Verdict:** ${verdict}  ·  **steps:** ${replay.steps.length}`);
-    if (replayTokens !== undefined) {
-        const ratio = competitorTokens !== undefined && replayTokens > 0
-            ? `  ·  **${Math.round(competitorTokens / replayTokens)}×** cheaper than an LLM re-drive`
-            : '';
-        out.push(`**Cost:** ${replayTokens} tokens (deterministic replay, no LLM)${ratio}`);
-    }
-    if (replay.decision !== undefined) {
-        out.push('');
-        out.push(`> **Next action:** ${replay.decision.nextAction}`);
-        if (replay.decision.whereInSource !== undefined) {
-            out.push(`> **Where:** \`${replay.decision.whereInSource}\``);
-        }
-    }
-    out.push('');
-    out.push('## Journey');
-    out.push(mermaidDiagram(replay.steps));
-    out.push('');
-    out.push(journeyTable(replay.steps));
-    out.push('');
-    out.push('## Evidence');
-    out.push(evidenceList(replay.steps));
-    out.push('');
-    return out.join('\n');
-}