@reticlehq/browser 2.12.0 → 2.13.0

package/dist/actions/actions.js

@@ -142,8 +142,8 @@ function dangerousActionContext(el) {
         form?.getAttribute('action') ?? '',
     ].join(' ');
 }
-function requiresDangerousConfirmation(text) {
-    return isDangerousActionText(text);
+function requiresDangerousConfirmation(text, role) {
+    return isDangerousActionText(text, role);
 }
 /**
  * Which key a `press` is asking for.
@@ -325,11 +325,11 @@ function assertActionAllowed(el, action, args) {
     // Same resolver as the dispatch below, so the destructive-action guard cannot classify a drag
     // by a target the dispatch will not use.
     const dragTarget = action === ActionType.DRAG ? refs.resolve(dragTargetRef(args)) : null;
-    const context = isHtmlElement(dragTarget)
-        ? `${dangerousActionContext(el)} ${dangerousActionContext(dragTarget)}`
-        : dangerousActionContext(el);
+    const sourceDangerous = requiresDangerousConfirmation(dangerousActionContext(el), getRole(el));
+    const targetDangerous = isHtmlElement(dragTarget) &&
+        requiresDangerousConfirmation(dangerousActionContext(dragTarget), getRole(dragTarget));
     if (canTrigger &&
-        requiresDangerousConfirmation(context) &&
+        (sourceDangerous || targetDangerous) &&
         args[DANGEROUS_ACTION_CONFIRM_ARG] !== true) {
         throw new Error(`potentially destructive action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
     }

package/dist/connect-options.d.ts

@@ -17,7 +17,11 @@ export interface ReticleConnectOptions {
      * agent scope to the right app even when its dev server boots on an unexpected port. Optional.
      */
     projectId?: string;
-    /** Browser/bridge pairing token. Required when either endpoint is non-localhost. */
+    /**
+     * Browser/bridge pairing token. Required whenever the daemon has one, which is the ordinary case:
+     * it auto-provisions `~/.reticle/pairing-token` on first start and then refuses a hello without it,
+     * including on localhost. Non-localhost additionally needs `allowNonLocalhost`.
+     */
     token?: string;
     /** Explicitly allow Reticle on a non-localhost page or bridge. Requires token. */
     allowNonLocalhost?: boolean;
@@ -35,6 +39,19 @@ export interface ReticleConnectOptions {
      * sensitive keys redacted, per-body capped). Off by default - bodies cost tokens and can carry PII.
      */
     captureNetworkBodies?: boolean;
+    /**
+     * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
+     *
+     * The presenter is hidden from every tool by design, for a good reason: an agent that can drive
+     * Reticle's own interface can fabricate its own impact report, and Reticle chrome in a snapshot is
+     * noise in every other app on earth.
+     *
+     * The cost of that rule is that a HUD change is the only kind of change Reticle cannot be used to
+     * check — the panel rendering it is invisible to everything that could look at it. This hatch
+     * exists for exactly that case: the app under test IS Reticle. It reports itself in the app's
+     * capabilities, so a verdict drawn with it open can never be mistaken for an ordinary one.
+     */
+    exposePresenter?: boolean;
     /**
      * The project root, so source paths report repo-relative instead of absolute.
      *

package/dist/dom/dom-ignore.d.ts

@@ -4,6 +4,15 @@
  * presenter, so omitting its selector here leaked annotation chrome into every snapshot.
  */
 export declare const RETICLE_OVERLAY: string;
+/**
+ * Make Reticle's own presenter visible to snapshots and queries. Contributors only.
+ *
+ * Deliberately a function rather than a field on the ignore set, so the one place that decides
+ * "is this ours" also decides "may it be seen", and no caller can half-apply it.
+ */
+export declare function setPresenterVisible(visible: boolean): void;
+/** Whether the hatch is open — reported in the app's capabilities so a verdict is never mistaken. */
+export declare function isPresenterVisible(): boolean;
 /** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export declare function setIgnoreSelectors(selectors: string[]): void;
 /** True if the element is part of Reticle's own presenter overlay. */

package/dist/dom/dom-ignore.js

@@ -7,6 +7,34 @@ export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[da
 /** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
+/**
+ * Whether Reticle's OWN UI is visible to snapshots and queries.
+ *
+ * Off, always, unless an app opts in — and the opt-in exists for exactly one situation: the app
+ * under test IS Reticle. A HUD change is otherwise the only kind of change Reticle cannot be used to
+ * check, because the panel that renders it is invisible to every tool that could look at it.
+ *
+ * It stays off by default because the reason for hiding it is sound: an agent that can drive
+ * Reticle's own interface can fabricate its own impact report, and a snapshot full of Reticle chrome
+ * is noise in every other app on earth. This is a hatch for contributors, not a setting.
+ *
+ * Third-party dev overlays stay ignored either way — they are somebody else's furniture and were
+ * never the thing being verified.
+ */
+let presenterVisible = false;
+/**
+ * Make Reticle's own presenter visible to snapshots and queries. Contributors only.
+ *
+ * Deliberately a function rather than a field on the ignore set, so the one place that decides
+ * "is this ours" also decides "may it be seen", and no caller can half-apply it.
+ */
+export function setPresenterVisible(visible) {
+    presenterVisible = visible;
+}
+/** Whether the hatch is open — reported in the app's capabilities so a verdict is never mistaken. */
+export function isPresenterVisible() {
+    return presenterVisible;
+}
 /** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export function setIgnoreSelectors(selectors) {
     extraIgnore = selectors.join(',');
@@ -35,8 +63,9 @@ export function isReticleUi(node) {
 }
 /** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export function isIgnored(el) {
-    const sel = extraIgnore.length > 0
-        ? `${RETICLE_OVERLAY},${DEV_OVERLAYS},${extraIgnore}`
-        : `${RETICLE_OVERLAY},${DEV_OVERLAYS}`;
+    // With the hatch open, Reticle's own overlay drops out of the ignore set — but the third-party
+    // dev overlays do not. They are somebody else's furniture and were never the thing being verified.
+    const ours = presenterVisible ? '' : RETICLE_OVERLAY;
+    const sel = [ours, DEV_OVERLAYS, extraIgnore].filter((part) => part.length > 0).join(',');
     return el.closest(sel) !== null;
 }

package/dist/dom/query.js

@@ -4,7 +4,7 @@ import { capturedRootOf } from './shadow-registry.js';
 import { getAccessibleName, getRole, describe, getStates, isInViewport, isVisible, } from './a11y.js';
 import { isIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
-import { getCapabilities } from '../registry/capabilities.js';
+import { declaredTestids } from '../registry/capabilities.js';
 import { identifyComponent } from '../registry/adapters.js';
 import { refs } from './refs.js';
 const TESTID_ATTR = 'data-testid';
@@ -504,6 +504,47 @@ function buildPresentRegions(query) {
     }
     return regions;
 }
+/**
+ * The tightest single element whose SUBTREE text carries `wanted`, when no element's OWN text does.
+ *
+ * `by: text` matches an element's direct text nodes (`directText`), so a label rendered across
+ * several child nodes — `v-html`, an inline `<span>` per word, a highlighted substring — exists on
+ * the page and matches nothing. The two channels disagree by construction: `act_and_wait` reports
+ * `appeared` by concatenating an added subtree, so the string an agent is most likely to copy into
+ * its next predicate is exactly the shape this query cannot find.
+ *
+ * That failure is indistinguishable from the element being absent, which is the expensive half: the
+ * agent reads "no element matched", concludes the app did not render, and reports a bug against
+ * correct code.
+ *
+ * Returns the DEEPEST container rather than the first, because every ancestor up to `<body>` also
+ * contains the string and naming `<body>` is not a locator. The deepest one is the tightest scope
+ * that still holds the whole string, which is the one worth pasting back.
+ */
+function splitTextOwner(container, wanted) {
+    let best;
+    let bestDepth = -1;
+    for (const el of elementsUnder(container)) {
+        if (isIgnored(el))
+            continue; // never point an agent at Reticle's own UI
+        if (!fuzzyVisibleText(el.textContent ?? '', wanted))
+            continue;
+        let depth = 0;
+        for (let parent = el.parentElement; parent !== null; parent = parent.parentElement)
+            depth++;
+        if (depth > bestDepth) {
+            best = el;
+            bestDepth = depth;
+        }
+    }
+    return best;
+}
+/** The text this query searched for, in either spelling, or undefined when it searched by something else. */
+function wantedTextOf(query) {
+    if (query.text !== undefined)
+        return query.text;
+    return QueryBy.TEXT === query.by ? query.value : undefined;
+}
 /** Diagnostic hint for a zero-match query: what testids ARE present in the searched scope. */
 function buildEmptyHint(query) {
     const container = resolveContainer(query.scope).container ?? document.body;
@@ -519,15 +560,26 @@ function buildEmptyHint(query) {
                 break;
         }
     }
-    const registered = getCapabilities().testids;
+    // DECLARED, not observed: see declaredTestids. Every present testid is also an observed one, so
+    // the merged list would make this flag true for any page that has a testid at all.
+    const registered = declaredTestids();
     const knownEmptyState = present.some((id) => registered.includes(id));
     const route = `${location.pathname}${location.search}`;
-    return {
+    const hint = {
         route,
         presentTestids: present,
         presentRegions: buildPresentRegions(query),
         knownEmptyState,
     };
+    // Only for a text search, and only when the string IS here — otherwise this is an ordinary miss
+    // and the extra clause would lengthen every failure to say nothing.
+    const wanted = wantedTextOf(query);
+    if (wanted !== undefined) {
+        const owner = splitTextOwner(container, wanted);
+        if (owner !== undefined)
+            hint.splitText = describe(owner);
+    }
+    return hint;
 }
 /**
  * Resolve a query to descriptors for the `query` MCP tool.

package/dist/dom/snapshot.d.ts

@@ -21,6 +21,14 @@ export interface SnapshotResult {
      * must not receive the entire page as if it were the modal.
      */
     scopeMissing?: boolean;
+    /**
+     * How many MEANINGFUL nodes the lean walk passed over, present only in a lean mode and only when
+     * non-zero. This is what stops an empty `interactive` tree reading as an empty page — the mode is
+     * a role filter, and a production app whose controls carry no roles yields nothing while being
+     * full of things to drive. It shipped untyped: the value was spread into the result and every
+     * consumer had to reach for it without a type, including the tool that builds the note from it.
+     */
+    leanSkipped?: number;
     /**
      * Refs of the subtree roots the walk never entered, present ONLY when `truncated`. This is the
      * cut's own frontier: re-snapshot each with `{ scope: ref, includeRoot: true }` and the union is

package/dist/dom/snapshot.js

@@ -3,7 +3,7 @@ import { capturedRootOf } from './shadow-registry.js';
 import { isFrame } from './realm.js';
 import { getAccessibleName, getRole, getStates, getValue, isVisible } from './a11y.js';
 import { refs } from './refs.js';
-import { isIgnored } from './dom-ignore.js';
+import { isIgnored, isReticleOverlay } from './dom-ignore.js';
 const INTERACTIVE = new Set([
     'button',
     'link',
@@ -87,8 +87,12 @@ function stateSuffix(el) {
 function formatLine(el, depth, role, name, layout) {
     const indent = '  '.repeat(depth);
     const value = getValue(el);
-    const namePart = name.length > 0 ? ` "${name}"` : '';
-    const refPart = INTERACTIVE.has(role) || name.length > 0 ? ` (ref=${refs.refFor(el)})` : '';
+    // A testid stands in for the accessible name when there is none. Including a role-less control and
+    // then printing it as a bare `- generic` is worse than leaving it out: it is visible and it cannot
+    // be addressed. This is the name its author gave it.
+    const label = name;
+    const namePart = label.length > 0 ? ` "${label}"` : '';
+    const refPart = INTERACTIVE.has(role) || label.length > 0 ? ` (ref=${refs.refFor(el)})` : '';
     const valuePart = value !== undefined && value.length > 0 ? ` [value="${value}"]` : '';
     const layoutPart = layout.length > 0 ? ` [${layout}]` : '';
     return `${indent}- ${role}${namePart}${refPart}${valuePart}${layoutPart}${stateSuffix(el)}`;
@@ -177,8 +181,51 @@ function visit(child, depth, ctx, inLive) {
     const text = !lean && 'generic' === role && 0 === name.length ? directText(child) : '';
     // Layout signature for grid/flex containers — makes CLS/layout regressions visible.
     const layout = lean ? '' : layoutSignature(style);
-    const meaningful = interactive || role !== 'generic' || name.length > 0 || text.length > 0 || layout.length > 0;
-    const include = lean ? interactive : meaningful;
+    // Actionable WITHOUT an interactive role, which is most of the real web.
+    //
+    // `interactive` is a role test, and a large share of production UI carries no roles at all.
+    // Measured on MarkText, a production Electron editor: `mode:"interactive"` returned an EMPTY tree
+    // where `mode:"full"` found 47 nodes, because its whole block picker is `<div>`s. An empty tree is
+    // indistinguishable from an empty page, and the tool description recommends this mode as the
+    // default — so the cheaper view told an agent there was nothing to drive.
+    //
+    // A `data-testid` ONLY. It is a handle its author put there to be driven, and it marks one element
+    // rather than a subtree.
+    //
+    // `cursor: pointer` was tried here as a second signal — it is how an app tells a HUMAN that a
+    // thing is clickable — and measured on MarkText it was a disaster: interactive went from 0 nodes
+    // and 72 tokens to 180 nodes and 870, against a FULL snapshot of 47 nodes and 424. The pointer
+    // cursor is inherited, so every wrapper div inside a clickable row matched, and the lean mode
+    // became twice the size of the complete one while adding nothing but nameless `- generic` lines.
+    // The mode's whole claim is that it is smaller; a signal that cannot tell a control from its
+    // ancestors cannot be used to decide what a control is.
+    // `data-testid` was tried here as a second signal, on the premise that it is a handle its author
+    // put there to be driven. Measured against our own instrumented bench app, the premise is false:
+    // the lean tree on its dashboard came to 16 nodes and 175 tokens, and EIGHT were display elements
+    // — kpi-deploys, kpi-success, kpi-p95, kpi-services, area-chart, activity-feed, brand. Half the
+    // "actionable" view was things nothing can act on, and the mode roughly doubled to carry them; the
+    // benchmark read it as a 4% verification-efficiency regression. A testid marks what a TEST cares
+    // about, which is a superset of what a driver can use.
+    //
+    // It did not even help the case it shipped for: MarkText's controls carry no testid. `leanSkipped`
+    // is what fixed that — an empty tree that says how many it passed over is no longer an empty page.
+    //
+    // `cursor: pointer` was tried too and was worse: interactive went from 0 nodes and 72 tokens to
+    // 180 and 870 against a FULL snapshot of 47/424, because the pointer cursor is inherited and every
+    // wrapper div inside a clickable row matched. A signal that cannot tell a control from its
+    // ancestors cannot decide what a control is.
+    const actionable = interactive;
+    // A testid still makes an element MEANINGFUL, so `full` keeps it and can name and address it. It
+    // just is not evidence that the element is ACTIONABLE, which is the only question lean mode asks.
+    const meaningful = actionable || role !== 'generic' || name.length > 0 || text.length > 0 || layout.length > 0;
+    const include = lean ? actionable : meaningful;
+    // Counted, not just skipped. An empty INTERACTIVE tree is indistinguishable from an empty page,
+    // and on a real app the difference is everything: MarkText's block picker is 20+ live controls
+    // that carry no role, no testid and no pointer cursor, so the lean view is empty while the app is
+    // full of things to drive. Knowing how many were passed over is what turns "" into "look again in
+    // full mode" — see the note the snapshot tool builds from this.
+    if (lean && !include && meaningful)
+        ctx.leanSkipped += 1;
     if (include) {
         ctx.nodes += 1;
         ctx.lines.push(text.length > 0 && 0 === name.length && 0 === layout.length
@@ -207,10 +254,22 @@ function walk(parent, depth, ctx, inLive = false) {
             visit(child, depth, ctx, inLive);
     }
 }
+/**
+ * The APP's open dialogs. Reticle's own panels are excluded, always.
+ *
+ * The HUD's chat and report panels carry `role="dialog"` because that is the correct role for what
+ * they are — but they are OUR surface, not the application's. Once the presenter became visible to
+ * the tool surface (so that Reticle can be used to check its own HUD), every snapshot of every page
+ * started reporting `visibleDialogs: ["Reticle agent chat"]`, telling the agent a modal was up when
+ * the app had none. An agent that believes a dialog is open dismisses it before doing anything else,
+ * which is a wasted action at best and a dismissed REAL dialog at worst.
+ */
 function collectDialogs(root) {
     const nodes = root.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     const names = [];
     for (const node of nodes) {
+        if (isReticleOverlay(node))
+            continue;
         if (isVisible(node))
             names.push(getAccessibleName(node) || '(unnamed dialog)');
     }
@@ -240,6 +299,11 @@ function overlayHidingPage(root) {
     const dialogs = document.body.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
     let modal;
     for (const d of dialogs) {
+        // Never OUR overlay. Reticle's HUD must not be able to explain the app's absence with itself:
+        // that turns "the page did not render" into "an overlay is covering it", which sends the reader
+        // to dismiss a panel that was never the problem.
+        if (isReticleOverlay(d))
+            continue;
         if (isVisible(d)) {
             modal = d;
             break;
@@ -286,6 +350,7 @@ export function buildSnapshot(options = {}) {
     const ctx = {
         lines: [],
         nodes: 0,
+        leanSkipped: 0,
         truncated: false,
         mode,
         maxNodes: options.maxNodes ?? 400,
@@ -302,6 +367,7 @@ export function buildSnapshot(options = {}) {
         status,
         nodes: ctx.nodes,
         truncated: ctx.truncated,
+        ...(ctx.leanSkipped > 0 ? { leanSkipped: ctx.leanSkipped } : {}),
         ...(ctx.unread.length > 0 ? { unread: ctx.unread } : {}),
         ...(ctx.unreadOverflow ? { unreadOverflow: true } : {}),
     };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { SESSION_AUTO } from '@reticlehq/core';
 export { setIgnoreSelectors } from './dom/dom-ignore.js';
 export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
 export type { ReticleAdapter, ComponentInfo, ComponentSource } from './registry/adapters.js';
-export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, } from './registry/stores.js';
+export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, sourceOwner, markAdapterSource, } from './registry/stores.js';
 export type { StoreGetter, StoreLike, StoreSubscribe } from './registry/stores.js';
 export { tanstackQueryStore, jotaiStore, xstateStore, valtioStore, mobxStore, recoilStore, svelteStore, piniaStore, pushStore, } from './registry/store-adapters.js';
 export type { QuerySnapshot, RecoilAtomSnapshot } from './registry/store-adapters.js';

package/dist/index.js

@@ -14,7 +14,11 @@ export { setIgnoreSelectors } from './dom/dom-ignore.js';
 // Adapter API (used by @reticlehq/react and other framework adapters).
 export { registerAdapter, identifyComponent, readComponentState, elementHasHoverHandlers, adapterNames, } from './registry/adapters.js';
 // Store registry: pull live framework/store state on demand.
-export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, } from './registry/stores.js';
+export { registerStore, unregisterStore, storeNames, readStores, readStoresWithTruncation, 
+// Which name a store SOURCE is registered under. The React adapter discovers stores from the fiber
+// tree and needs this to tell "the app already wired this exact store" from "this is another one" —
+// a question neither the name nor the read value can answer.
+sourceOwner, markAdapterSource, } from './registry/stores.js';
 // Adapters for state libraries that do not natively expose `{getState, subscribe}`. zustand and Redux
 // need none of these; TanStack Query is the one that matters most, because a stale-cache bug fires no
 // request and renders a plausible value, so the cache is the only witness.

package/dist/observers/animation.js

@@ -3,6 +3,8 @@ import { refs } from '../dom/refs.js';
 import { isReticleOverlay } from '../dom/dom-ignore.js';
 /** Observe CSS animations + transitions and emit anim.start / anim.end. */
 export function installAnimation(emit) {
+    const ac = new AbortController();
+    const { signal } = ac;
     const onStart = (event) => {
         const target = event.target;
         // Skip Reticle's own HUD keyframes (reticle-pulse/reticle-shimmer/…) so observe/record never
@@ -23,12 +25,8 @@ export function installAnimation(emit) {
             emit(EventType.ANIM_END, { name: event.propertyName, kind: 'transition' }, refs.refFor(target));
         }
     };
-    document.addEventListener('animationstart', onStart, true);
-    document.addEventListener('animationend', onEnd, true);
-    document.addEventListener('transitionend', onTransitionEnd, true);
-    return () => {
-        document.removeEventListener('animationstart', onStart, true);
-        document.removeEventListener('animationend', onEnd, true);
-        document.removeEventListener('transitionend', onTransitionEnd, true);
-    };
+    document.addEventListener('animationstart', onStart, { capture: true, signal });
+    document.addEventListener('animationend', onEnd, { capture: true, signal });
+    document.addEventListener('transitionend', onTransitionEnd, { capture: true, signal });
+    return () => ac.abort();
 }

package/dist/observers/focus.js

@@ -17,6 +17,8 @@ function toBody(el) {
  * FOCUS_CHANGE {to, from, toBody}. Reversible.
  */
 export function installFocus(emit) {
+    const ac = new AbortController();
+    const { signal } = ac;
     let last = null;
     const onFocusIn = (event) => {
         const to = event.target;
@@ -39,10 +41,7 @@ export function installFocus(emit) {
             toBody: true,
         });
     };
-    document.addEventListener('focusin', onFocusIn);
-    document.addEventListener('focusout', onFocusOut);
-    return () => {
-        document.removeEventListener('focusin', onFocusIn);
-        document.removeEventListener('focusout', onFocusOut);
-    };
+    document.addEventListener('focusin', onFocusIn, { signal });
+    document.addEventListener('focusout', onFocusOut, { signal });
+    return () => ac.abort();
 }

package/dist/observers/health.js

@@ -109,21 +109,18 @@ function snapshotHealth() {
  * tab blind. Uses a native (pre-bound) timer so a frozen app clock (reticle_clock) never stalls it.
  */
 export function installHealth(emit) {
+    const ac = new AbortController();
+    const { signal } = ac;
     const report = (reason) => {
         emit(EventType.PAGE_HEALTH, { ...snapshotHealth(), reason });
     };
-    const onVisibility = () => report(HealthReason.VISIBILITY);
-    const onFocus = () => report(HealthReason.FOCUS);
-    const onBlur = () => report(HealthReason.BLUR);
-    document.addEventListener('visibilitychange', onVisibility);
-    window.addEventListener('focus', onFocus);
-    window.addEventListener('blur', onBlur);
+    document.addEventListener('visibilitychange', () => report(HealthReason.VISIBILITY), { signal });
+    window.addEventListener('focus', () => report(HealthReason.FOCUS), { signal });
+    window.addEventListener('blur', () => report(HealthReason.BLUR), { signal });
     report(HealthReason.INITIAL); // baseline so the server knows state before the first change
     const stopHeartbeat = nativeSetInterval(() => report(HealthReason.HEARTBEAT), SESSION_HEALTH.HEARTBEAT_MS);
     return () => {
         stopHeartbeat();
-        document.removeEventListener('visibilitychange', onVisibility);
-        window.removeEventListener('focus', onFocus);
-        window.removeEventListener('blur', onBlur);
+        ac.abort();
     };
 }

package/dist/observers/network-redact.d.ts

@@ -5,3 +5,16 @@
  * The hash is preserved and the URL is returned byte-for-byte when nothing matched.
  */
 export declare function redactUrl(raw: string): string;
+/**
+ * Displayed URL plus, when redaction rewrote it, the raw request for graders.
+ *
+ * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
+ * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
+ * changed, so an ordinary request pays nothing.
+ */
+export declare function netUrlFields(raw: string): {
+    url: string;
+} | {
+    url: string;
+    urlRaw: string;
+};

package/dist/observers/network-redact.js

@@ -1,4 +1,4 @@
-import { REDACTED_VALUE } from '@reticlehq/core';
+import { REDACTED_VALUE, URL_RAW } from '@reticlehq/core';
 import { isSensitiveKey } from '../security/serialization.js';
 /** A path segment name that is typically followed by a single-use secret token in the NEXT segment. */
 const SENSITIVE_PATH_SEGMENT = /^(reset|verify|verification|confirm|activate|invite|magic|magiclink|token|key|oauth|unsubscribe|password)$/i;
@@ -67,3 +67,14 @@ export function redactUrl(raw) {
     const queryOut = -1 === queryStart ? '' : `?${newQuery}`;
     return `${segments.join('/')}${queryOut}${newHash}`;
 }
+/**
+ * Displayed URL plus, when redaction rewrote it, the raw request for graders.
+ *
+ * `url` is what the agent reads. `urlRaw` exists only so `urlContains` can still match a public
+ * path segment that the heuristic rewrote (`/auth/token/refresh-context`). Omitted when nothing
+ * changed, so an ordinary request pays nothing.
+ */
+export function netUrlFields(raw) {
+    const url = redactUrl(raw);
+    return url === raw ? { url } : { url, [URL_RAW]: raw };
+}

package/dist/observers/network.d.ts

@@ -1,6 +1,6 @@
 import type { Emit, Teardown } from './types.js';
-import { redactUrl } from './network-redact.js';
-export { redactUrl };
+import { redactUrl, netUrlFields } from './network-redact.js';
+export { redactUrl, netUrlFields };
 /** Config for the network observer. Body capture is OFF by default and dev-only opt-in. */
 /**
  * Reinterpret a completed request's fields from its response.

package/dist/observers/network.js

@@ -1,12 +1,12 @@
 import { BlindSpotKind, EventType, RETICLE_WS_PATH, StreamTransport, StreamDirection, } from '@reticlehq/core';
 import { captureMethod } from '../patching/capture-method.js';
 import { isCapturableType, projectBody, withBodyDeadline } from './network-body.js';
-import { redactUrl } from './network-redact.js';
+import { redactUrl, netUrlFields } from './network-redact.js';
 import { watchStreamedBody } from './network-stream.js';
 import { requireCapturedMethod } from '../util/captured-method.js';
 // Redaction moved to its own cohesive module (network.ts is at its line cap); re-exported so callers
 // and the existing test suite keep importing it from here.
-export { redactUrl };
+export { redactUrl, netUrlFields };
 /** The byte size of a binary frame (ArrayBuffer / Blob / typed-array view), or undefined if unknown. */
 function binaryFrameBytes(data) {
     if (data instanceof ArrayBuffer)
@@ -244,10 +244,17 @@ export function installNetwork(emit, opts = {}) {
         const id = nextId();
         const start = performance.now();
         const method = methodOf(input, init);
-        const url = redactUrl(rawUrl);
+        const urlFields = netUrlFields(rawUrl);
+        const url = urlFields.url;
         const initiatorStack = initiatorFrame();
         const initiatorFields = initiatorStack === undefined ? {} : { initiatorStack };
-        emit(EventType.NET_PENDING, { id, method, url, initiator: 'fetch', ...initiatorFields });
+        emit(EventType.NET_PENDING, {
+            id,
+            method,
+            ...urlFields,
+            initiator: 'fetch',
+            ...initiatorFields,
+        });
         try {
             const res = await callFetch(input, init);
             // The app's fetch resolves HERE — at headers — like a native fetch. durationMs is measured to
@@ -261,7 +268,7 @@ export function installNetwork(emit, opts = {}) {
                 emit(EventType.NET_REQUEST, {
                     id,
                     method,
-                    url,
+                    ...urlFields,
                     status: res.status,
                     ok: statusIsOk(res.status),
                     durationMs: Math.round(headersAt - start),
@@ -376,7 +383,7 @@ export function installNetwork(emit, opts = {}) {
             emit(EventType.NET_PENDING, {
                 id: m.id,
                 method: m.method,
-                url: m.url,
+                ...netUrlFields(m.rawUrl),
                 initiator: 'xhr',
                 ...initiatorFields,
             });
@@ -405,7 +412,7 @@ export function installNetwork(emit, opts = {}) {
                     emit(EventType.NET_REQUEST, {
                         id: cur.id,
                         method: cur.method,
-                        url: cur.url,
+                        ...netUrlFields(cur.rawUrl),
                         status: this.status,
                         ok: statusIsOk(this.status),
                         durationMs: Math.round(performance.now() - cur.start),
@@ -432,17 +439,17 @@ export function installNetwork(emit, opts = {}) {
         window.EventSource = class extends origEventSource {
             constructor(u, init) {
                 super(u, init);
-                const url = redactUrl(String(u));
+                const urlFields = netUrlFields(String(u));
                 emit(EventType.NET_STREAM, {
                     transport: StreamTransport.SSE,
                     direction: StreamDirection.OPEN,
-                    url,
+                    ...urlFields,
                 });
                 this.addEventListener('message', (ev) => {
                     emit(EventType.NET_STREAM, {
                         transport: StreamTransport.SSE,
                         direction: StreamDirection.IN,
-                        url,
+                        ...urlFields,
                         ...frameFields(ev.data, captureBodies),
                     });
                 });
@@ -459,17 +466,17 @@ export function installNetwork(emit, opts = {}) {
                 this.#isBridge = isBridgeSocket(String(u));
                 if (this.#isBridge)
                     return;
-                const url = redactUrl(String(u));
+                const urlFields = netUrlFields(String(u));
                 emit(EventType.NET_STREAM, {
                     transport: StreamTransport.WS,
                     direction: StreamDirection.OPEN,
-                    url,
+                    ...urlFields,
                 });
                 this.addEventListener('message', (ev) => {
                     emit(EventType.NET_STREAM, {
                         transport: StreamTransport.WS,
                         direction: StreamDirection.IN,
-                        url,
+                        ...urlFields,
                         ...frameFields(ev.data, captureBodies),
                     });
                 });
@@ -486,7 +493,7 @@ export function installNetwork(emit, opts = {}) {
                 emit(EventType.NET_STREAM, {
                     transport: StreamTransport.WS,
                     direction: StreamDirection.OUT,
-                    url: redactUrl(this.url),
+                    ...netUrlFields(this.url),
                     ...frameFields(data, captureBodies),
                 });
                 super.send(data);
@@ -504,7 +511,7 @@ export function installNetwork(emit, opts = {}) {
     if (navProto !== null && origBeacon !== undefined) {
         patchedBeacon = function (url, data) {
             const id = nextId();
-            const redacted = redactUrl(String(url));
+            const urlFields = netUrlFields(String(url));
             const initiatorStack = initiatorFrame();
             const sent = origBeacon.call(this, url, data);
             // sendBeacon returns whether the payload was QUEUED, not an HTTP result — the response never
@@ -513,7 +520,7 @@ export function installNetwork(emit, opts = {}) {
             emit(EventType.NET_REQUEST, {
                 id,
                 method: 'POST',
-                url: redacted,
+                ...urlFields,
                 status: 0,
                 ok: sent,
                 queued: sent,
@@ -558,7 +565,7 @@ export function installNetwork(emit, opts = {}) {
                     emit(EventType.NET_REQUEST, {
                         id: nextId(),
                         method: 'GET',
-                        url: redactUrl(rawUrl),
+                        ...netUrlFields(rawUrl),
                         durationMs: Math.round(entry.duration),
                         initiator: type,
                         ...(entry.transferSize > 0 ? { transferSize: entry.transferSize } : {}),