@reticlehq/browser 2.11.0 → 2.13.0

package/dist/presenter/presenter-settings.js

@@ -70,7 +70,15 @@ const DEFAULT_SETTINGS = {
     blockPageInteractions: true,
     showTally: false,
     showTimestamps: true,
-    autoOpenChat: false,
+    // ON by default: the chat IS the HUD's content, and shipping it off meant the default experience
+    // was a bare toolbar until somebody found the toggle. `expand()` has always opened the chat for
+    // the same reason; this is the other half — session start, with no click at all.
+    //
+    // Safe to default because `openChat()` expands a collapsed HUD, and session start is the one
+    // moment where that is what you want. A user who prefers the bare toolbar turns this off and it
+    // stays off: a stored `false` is honoured over the default, which is pinned in
+    // presenter-chat-default.test.ts so the product cannot change somebody's answer behind their back.
+    autoOpenChat: true,
     reduceMotion: false,
 };
 let activeSettings = loadPresenterSettings();
@@ -169,7 +177,7 @@ export function settingsPanelHtml() {
     const hideHelp = 'Hide the Reticle HUD until you reload the page';
     const tallyHelp = 'Show the pass/fail score pill in the toolbar';
     const timestampsHelp = 'Show relative timestamps on each activity-log row';
-    const autoChatHelp = 'Open the agent chat by itself when a session starts and when you expand the HUD. Off leaves the toolbar bare until you ask for the chat.';
+    const autoChatHelp = 'On by default. Opens the agent chat by itself when a session starts and when you expand the HUD. Off leaves the toolbar bare until you ask for the chat.';
     const motionHelp = 'Reduce HUD animations for accessibility';
     const glowHelp = 'Glow the page edges in the status colour while a session is live. Off keeps the HUD signals and leaves your app alone.';
     return `<div ${SETTINGS_PANEL_ATTR} class="reticle-settings ${HUD_SURFACE_CLASS}" role="dialog" aria-label="Reticle settings" aria-hidden="true">

package/dist/presenter/presenter-shell-styles.js

@@ -306,8 +306,19 @@ export const SHELL_CSS = `
   padding:2px 6px;border-radius:999px;white-space:nowrap;pointer-events:none;z-index:2;
   transition:opacity .12s ease;}
 [${OVERLAY}][${STATE}="paused"] [data-reticle-badge]{display:inline-flex;}
+/**
+ * The mode, ON the status row rather than under it.
+ *
+ * The action text beside it is flex:1, so this claims the right edge of the row and takes its space
+ * from the elided action text. Nothing above or below moves: the panel used to grow and shrink by
+ * the height of this pill on every single tool call, which is what made one status line look like a
+ * second UI appearing and leaving.
+ */
 [${DOCK_ATTR}] .reticle-chip{display:none;flex:none;align-items:center;gap:4px;font-size:8px;font-weight:600;letter-spacing:.06em;
-  padding:3px 7px;border-radius:999px;text-transform:uppercase;background:rgba(255,255,255,.06);}
+  height:16px;padding:0 7px;line-height:1;border-radius:999px;text-transform:uppercase;
+  background:rgba(255,255,255,.06);opacity:0;transition:opacity .12s ease;}
+[${DOCK_ATTR}] .reticle-chip[data-mode="reading"],
+[${DOCK_ATTR}] .reticle-chip[data-mode="acting"]{opacity:1;}
 [${DOCK_ATTR}] .reticle-chip[data-mode="reading"],
 [${DOCK_ATTR}] .reticle-chip[data-mode="acting"]{display:inline-flex;color:var(--reticle-fg);}
 [${DOCK_ATTR}] .reticle-tally[hidden]{display:none;}
@@ -344,6 +355,14 @@ export const SHELL_CSS = `
     0 0 8px color-mix(in srgb,var(--reticle-state) 45%,transparent);}
 [${CHAT_PANEL}] .reticle-act-strip[data-liveness="idle"] .reticle-act-dot{
   animation:reticle-idle-pulse 2.4s ease-in-out infinite;}
+/**
+ * Unreachable: present, and plainly not working.
+ *
+ * Muted rather than alarming. Nothing is broken in the user's app — Reticle simply has nobody to
+ * talk to — and a dev overlay that shouts about its own plumbing is one the user turns off.
+ */
+[${OVERLAY}][${STATE}="unreachable"]{--reticle-state:var(--reticle-faint);}
+[${OVERLAY}][${STATE}="unreachable"] [${CHAT_PANEL}] .reticle-act-dot{animation:none;}
 [${OVERLAY}][${STATE}="paused"] [${CHAT_PANEL}] .reticle-act-dot,
 [${OVERLAY}][${STATE}="ended"] [${CHAT_PANEL}] .reticle-act-dot{animation:none;}
 @keyframes reticle-idle-pulse{0%,100%{opacity:.45;transform:scale(.92)}50%{opacity:1;transform:scale(1)}}

package/dist/presenter/presenter-shell.d.ts

@@ -44,5 +44,3 @@ export declare class HudShell {
     /** Pulse the FAB when new activity arrives while collapsed. */
     pulseFab(active: boolean): void;
 }
-/** Whether the dock has been dragged off the default bottom-right position. */
-export declare function isDockDragged(dock: HTMLElement): boolean;

package/dist/presenter/presenter-shell.js

@@ -1,5 +1,5 @@
 import { PresenterReport, reportPanelHtml } from './presenter-report.js';
-import { CHAT_MIN_ATTR, CHAT_PILL_ATTR, REPORT_ATTR, REPORT_BTN_ATTR, ANNOTATE_BTN_ATTR, CHAT_ATTR, CHAT_TOGGLE_ATTR, CHAT_PANEL_ATTR, DOCK_ATTR, FAB_ATTR, MIN_ATTR, HUD_DRAGGED_ATTR, SETTINGS_ATTR, SETTINGS_BTN_ATTR, } from './presenter-config.js';
+import { CHAT_MIN_ATTR, CHAT_PILL_ATTR, REPORT_ATTR, REPORT_BTN_ATTR, ANNOTATE_BTN_ATTR, CHAT_ATTR, CHAT_TOGGLE_ATTR, CHAT_PANEL_ATTR, DOCK_ATTR, FAB_ATTR, MIN_ATTR, SETTINGS_ATTR, SETTINGS_BTN_ATTR, } from './presenter-config.js';
 import { BRAND_NAME, FAB_TOGGLE_HTML, MARK_SVG } from './presenter-brand.js';
 import { settleLogAtLatest } from './presenter-log.js';
 import { installHudDragHandles, installHudPositionGuards } from './presenter-drag.js';
@@ -93,7 +93,6 @@ export class HudShell {
         <button type="button" ${CHAT_MIN_ATTR} class="reticle-chat-min" title="${CHAT_MIN_LABEL}" aria-label="${CHAT_MIN_LABEL}">${hiIconHtml(PresenterIcon.CARET_DOWN, PRESENTER_ICON_SIZE.TOOLBAR)}</button>
         ${actStripHtml}
         <span class="reticle-tally" data-reticle-tally hidden></span>
-        <span class="reticle-chip" data-reticle-chip></span>
         ${bannerHtml}
         <div class="${HUD_LOG_WELL_CLASS}"><div ${logAttr}></div></div>
         ${flowsHtml}
@@ -420,7 +419,3 @@ export class HudShell {
         }
     };
 }
-/** Whether the dock has been dragged off the default bottom-right position. */
-export function isDockDragged(dock) {
-    return '1' === dock.getAttribute(HUD_DRAGGED_ATTR);
-}

package/dist/presenter/presenter.d.ts

@@ -41,6 +41,19 @@ export declare class Presenter {
      * sessionEnd. Idempotent, and a no-op when unmounted or in 'busy' border mode.
      */
     sessionStart(): void;
+    /**
+     * The bridge never answered: show that, rather than showing nothing.
+     *
+     * An instrumented page with a dead bridge used to be indistinguishable from a page with no
+     * Reticle in it — overlay mounted, dock off, nothing on screen. The user cannot tell "I forgot to
+     * start the daemon" from "the install did not work", and the commonest cause is the cheapest to
+     * say: the port. So the HUD appears, states the URL it tried, and marks itself unreachable so it
+     * is never mistaken for a live session.
+     *
+     * Not an error dialog and not modal: the page is the user's, and a dev overlay that shouts is one
+     * they turn off. It is the same capsule they would have had, saying the one thing it knows.
+     */
+    showUnreachable(url: string, attempts: number): void;
     /**
      * Session end: hides the log/HUD and (in 'session' mode) clears the base border. Idempotent; a
      * no-op without a prior sessionStart or when unmounted.

package/dist/presenter/presenter.js

@@ -1,12 +1,13 @@
 import { ActionType, ReticleCommand, PresenterMode, SessionState, isPresenterTone, isSessionState, } from '@reticlehq/core';
 import { refs } from '../dom/refs.js';
+import { unreachableStripText } from '../transport/unreachable-message.js';
 import { actionVerb } from './presenter-verbs.js';
 import { nativeSetTimeout, nativeClearTimeout, nativeNow } from '../timers/native-timers.js';
 import { LOG_KIND, CHIP_LABEL, DATA_RETICLE_LOG, clampLogMax, formatElapsed, humanDuration, appendLogRow, } from './presenter-log.js';
 import { PRESENTER_CSS } from './presenter-styles.js';
 import { HudShell } from './presenter-shell.js';
 import { parseImpactSnapshot } from './presenter-report-copy.js';
-import { BorderMode, DEFAULT_BORDER_MODE, DATA_BUSY, BUSY_OFF, effectivePaceMs, IDLE_AFTER_MS, HEARTBEAT_MS, IDLE_NOTICE_MS, IDLE_END_MS, IDLE_END_MIN_MS, ACT_STRIP, GLOW_FADE_MS, GLOW_ON, GLOW_OFF, DATA_ON, THROTTLED_ATTR, LIVENESS_ATTR, MARKERS_BTN_ATTR, CLEAR_MARKS_ATTR, MARK_COUNT_ATTR, } from './presenter-config.js';
+import { BorderMode, DEFAULT_BORDER_MODE, DATA_BUSY, BUSY_OFF, effectivePaceMs, IDLE_AFTER_MS, HEARTBEAT_MS, IDLE_NOTICE_MS, IDLE_END_MS, IDLE_END_MIN_MS, ACT_STRIP, STATE_ATTR, UNREACHABLE_STATE, GLOW_FADE_MS, GLOW_ON, GLOW_OFF, DATA_ON, THROTTLED_ATTR, LIVENESS_ATTR, MARKERS_BTN_ATTR, CLEAR_MARKS_ATTR, MARK_COUNT_ATTR, } from './presenter-config.js';
 import { buildRunState } from './presenter-run-state.js';
 import { moveCursor, ringAround, spawnRipple, pace } from './presenter-effects.js';
 import { GlowController } from './presenter-glow.js';
@@ -165,7 +166,11 @@ export class Presenter {
         document.head.appendChild(style);
         const root = document.createElement('div');
         root.setAttribute('data-reticle-overlay', '');
-        const actStrip = `<div class="reticle-act-strip" data-liveness="idle"><span class="reticle-act-dot" aria-hidden="true"></span><span class="reticle-act">${ACT_STRIP.READY}</span></div>`;
+        // The mode rides ON the status row, next to the dot and the elapsed time it already reports.
+        // It used to be a sibling BELOW the strip, hidden except while reading or acting — so every
+        // single tool call popped a block into the panel and took it away again, which reads as a
+        // second UI flashing in rather than as the one status line changing what it says.
+        const actStrip = `<div class="reticle-act-strip" data-liveness="idle"><span class="reticle-act-dot" aria-hidden="true"></span><span class="reticle-act">${ACT_STRIP.READY}</span><span class="reticle-chip" data-reticle-chip></span></div>`;
         root.innerHTML = `
       ${blockerHtml()}
       <div data-reticle-glow></div>
@@ -253,6 +258,9 @@ export class Presenter {
         }
         if (this.#sessionActive)
             return;
+        // A bridge that answered supersedes whatever the failed connect left on screen.
+        if (UNREACHABLE_STATE === this.#root?.getAttribute(STATE_ATTR))
+            this.#root.removeAttribute(STATE_ATTR);
         this.#sessionActive = true;
         this.#startMs ??= this.#now();
         this.#endMs = undefined;
@@ -263,6 +271,33 @@ export class Presenter {
             this.#shell.openChat();
         }
     }
+    /**
+     * The bridge never answered: show that, rather than showing nothing.
+     *
+     * An instrumented page with a dead bridge used to be indistinguishable from a page with no
+     * Reticle in it — overlay mounted, dock off, nothing on screen. The user cannot tell "I forgot to
+     * start the daemon" from "the install did not work", and the commonest cause is the cheapest to
+     * say: the port. So the HUD appears, states the URL it tried, and marks itself unreachable so it
+     * is never mistaken for a live session.
+     *
+     * Not an error dialog and not modal: the page is the user's, and a dev overlay that shouts is one
+     * they turn off. It is the same capsule they would have had, saying the one thing it knows.
+     */
+    showUnreachable(url, attempts) {
+        if (this.#sessionActive)
+            return;
+        this.#root?.setAttribute(STATE_ATTR, UNREACHABLE_STATE);
+        // Dock and HUD, but NOT the border glow: the glow means the agent is working, and nothing is.
+        const dock = this.#root?.querySelector('[data-reticle-dock]');
+        dock?.setAttribute(DATA_ON, GLOW_ON);
+        this.#hud?.setAttribute(DATA_ON, GLOW_ON);
+        this.#lastActionText = unreachableStripText(url, attempts);
+        this.#paintActStrip(this.#lastActionText, true);
+        // The message IS the reason this state exists, and a collapsed capsule hides it. Same setting
+        // a live session honours, so a user who wants the bare toolbar still gets one.
+        if (getPresenterSettings().autoOpenChat)
+            this.#shell.openChat();
+    }
     /** Turn the base border (session mode) + the HUD/log on - the visible "session is live" state. */
     #showSession() {
         const dock = this.#root?.querySelector('[data-reticle-dock]');

package/dist/registry/auto-testids.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The testids the page is actually showing, read from the live DOM.
+ *
+ * `registerCapabilities({ testids: [...] })` used to be the only source, and `init` filled it by
+ * grepping the source at install time. That list is a snapshot of the codebase on the day `init` ran:
+ * it goes stale on the next commit that renames an element, it is empty for every app whose testids
+ * arrive with a lazy route, and finishing it was homework handed to whoever ran the install.
+ *
+ * The attribute in the DOM is the same declaration, read fresh, so nothing has to be copied into a
+ * config file to be true. Reticle's own presenter markup is excluded — advertising our own controls
+ * as the app's testable surface would be the tool describing itself.
+ */
+/**
+ * Ceiling on the reported list.
+ *
+ * A virtualized 500-row grid stamps a testid per cell, and the capabilities payload rides in every
+ * announce — an uncapped read turns one long table into a permanently expensive message. The cap is
+ * on the REPORT, not on what can be driven: a testid past it is still findable by query.
+ */
+export declare const MAX_AUTO_TESTIDS = 200;
+export declare function domTestids(doc: Document): string[];

package/dist/registry/auto-testids.js

@@ -0,0 +1,48 @@
+/**
+ * The testids the page is actually showing, read from the live DOM.
+ *
+ * `registerCapabilities({ testids: [...] })` used to be the only source, and `init` filled it by
+ * grepping the source at install time. That list is a snapshot of the codebase on the day `init` ran:
+ * it goes stale on the next commit that renames an element, it is empty for every app whose testids
+ * arrive with a lazy route, and finishing it was homework handed to whoever ran the install.
+ *
+ * The attribute in the DOM is the same declaration, read fresh, so nothing has to be copied into a
+ * config file to be true. Reticle's own presenter markup is excluded — advertising our own controls
+ * as the app's testable surface would be the tool describing itself.
+ */
+const TESTID_ATTR = 'data-testid';
+const TESTID_SELECTOR = `[${TESTID_ATTR}]`;
+/**
+ * Ceiling on the reported list.
+ *
+ * A virtualized 500-row grid stamps a testid per cell, and the capabilities payload rides in every
+ * announce — an uncapped read turns one long table into a permanently expensive message. The cap is
+ * on the REPORT, not on what can be driven: a testid past it is still findable by query.
+ */
+export const MAX_AUTO_TESTIDS = 200;
+/** Reticle's own UI carries testids; they are not the host app's surface. */
+const RETICLE_OWN_PREFIX = 'reticle-';
+export function domTestids(doc) {
+    const out = [];
+    const seen = new Set();
+    let nodes;
+    try {
+        nodes = doc.querySelectorAll(TESTID_SELECTOR);
+    }
+    catch {
+        return out; // a document that cannot be queried (detached, hostile) simply advertises nothing
+    }
+    for (let i = 0; i < nodes.length && out.length < MAX_AUTO_TESTIDS; i += 1) {
+        const value = nodes[i]?.getAttribute(TESTID_ATTR);
+        if (null === value || undefined === value)
+            continue;
+        const trimmed = value.trim();
+        if (0 === trimmed.length || seen.has(trimmed))
+            continue;
+        if (trimmed.startsWith(RETICLE_OWN_PREFIX))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}

package/dist/registry/capabilities.d.ts

@@ -8,6 +8,15 @@ export interface Capabilities {
     signals: string[];
     stores: string[];
     flows: CapabilityFlow[];
+    /**
+     * True when Reticle's OWN presenter is visible to snapshots and queries.
+     *
+     * Present only when the hatch is open, and reported here rather than left implicit, because a
+     * verdict drawn against Reticle's own interface is not an ordinary verdict: an agent that can see
+     * the impact panel can also assert against it. Anybody reading a result should be able to tell
+     * which kind they are holding without going to look at a build config.
+     */
+    presenterExposed?: boolean;
 }
 /** What the host app passes to reticle.describe; all fields optional. */
 export interface CapabilitiesInput {
@@ -22,5 +31,23 @@ export declare function setCapabilitiesListener(cb: (() => void) | undefined): v
 export declare function registerCapabilities(input: CapabilitiesInput): void;
 /** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */
 export declare function getCapabilities(): Capabilities;
-/** Whether the app has advertised any capabilities (used in the HELLO flag). */
+/**
+ * Testids the app DECLARED, without the ones merely observed in the DOM.
+ *
+ * The difference carries meaning the merged list cannot. `knownEmptyState` asks "did the app NAME
+ * this element as part of its testable surface?", which is how a zero-match query against
+ * `cart-empty-region` is told apart from a broken selector. Every testid on the page is observed, so
+ * answering that over the merged list makes it true whenever the page has any testid at all — the
+ * same as not asking.
+ */
+export declare function declaredTestids(): string[];
+/**
+ * Whether the app has a testable surface at all (used in the HELLO flag).
+ *
+ * Answered over the OBSERVED surface as well as the declared one. It used to be answerable only by
+ * declaration, so an app with two hundred testids in its DOM and a live Redux store reported
+ * `hasCapabilities: false` until somebody typed those facts into a config file — and the agent
+ * reading that flag concluded, correctly by the flag and wrongly in fact, that there was nothing to
+ * drive.
+ */
 export declare function hasCapabilities(): boolean;

package/dist/registry/capabilities.js

@@ -1,4 +1,33 @@
 /** Self-describing capability registry — the testable surface the app advertises. */
+import { RETICLE_RENDERS_STORE } from '@reticlehq/core';
+import { isPresenterVisible } from '../dom/dom-ignore.js';
+import { domTestids } from './auto-testids.js';
+import { storeNames } from './stores.js';
+/**
+ * The two halves of the capability report the app no longer has to write down.
+ *
+ * `testids` and `stores` used to be *declarations* — strings copied into a generated file by `init`
+ * and then expected to stay true. Both are now read from the thing they describe: the testids from
+ * the DOM, the store names from the registry (which the React adapter fills by discovery). What the
+ * app declares is still merged in and still wins nothing away: `signals` and `flows` cannot be
+ * observed and remain the app's to state.
+ */
+function liveTestids() {
+    if ('undefined' === typeof document)
+        return [];
+    return domTestids(document);
+}
+/** Registered stores, minus the ones Reticle registered on the app's behalf. */
+function liveStores() {
+    return storeNames().filter((name) => RETICLE_RENDERS_STORE !== name);
+}
+function union(declared, observed) {
+    const out = [...declared];
+    for (const value of observed)
+        if (!out.includes(value))
+            out.push(value);
+    return out;
+}
 // Persist on a global so the registry survives HMR module re-evaluation (matches __reticleAdapters).
 const globalStore = globalThis;
 function empty() {
@@ -48,16 +77,39 @@ export function registerCapabilities(input) {
 /** Snapshot copy of the registered capabilities (defensive — never hand out the live arrays). */
 export function getCapabilities() {
     return {
-        testids: [...capabilities.testids],
+        testids: union(capabilities.testids, liveTestids()),
         signals: [...capabilities.signals],
-        stores: [...capabilities.stores],
+        stores: union(capabilities.stores, liveStores()),
         flows: capabilities.flows.map((f) => ({ name: f.name, steps: [...f.steps] })),
+        // Only when open — an absent field is the ordinary case and should not cost a line in every
+        // capabilities payload ever sent.
+        ...(isPresenterVisible() ? { presenterExposed: true } : {}),
     };
 }
-/** Whether the app has advertised any capabilities (used in the HELLO flag). */
+/**
+ * Testids the app DECLARED, without the ones merely observed in the DOM.
+ *
+ * The difference carries meaning the merged list cannot. `knownEmptyState` asks "did the app NAME
+ * this element as part of its testable surface?", which is how a zero-match query against
+ * `cart-empty-region` is told apart from a broken selector. Every testid on the page is observed, so
+ * answering that over the merged list makes it true whenever the page has any testid at all — the
+ * same as not asking.
+ */
+export function declaredTestids() {
+    return [...capabilities.testids];
+}
+/**
+ * Whether the app has a testable surface at all (used in the HELLO flag).
+ *
+ * Answered over the OBSERVED surface as well as the declared one. It used to be answerable only by
+ * declaration, so an app with two hundred testids in its DOM and a live Redux store reported
+ * `hasCapabilities: false` until somebody typed those facts into a config file — and the agent
+ * reading that flag concluded, correctly by the flag and wrongly in fact, that there was nothing to
+ * drive.
+ */
 export function hasCapabilities() {
-    return (capabilities.testids.length > 0 ||
-        capabilities.signals.length > 0 ||
-        capabilities.stores.length > 0 ||
-        capabilities.flows.length > 0);
+    return (capabilities.signals.length > 0 ||
+        capabilities.flows.length > 0 ||
+        union(capabilities.testids, liveTestids()).length > 0 ||
+        union(capabilities.stores, liveStores()).length > 0);
 }

package/dist/registry/store-adapters.d.ts

@@ -1,4 +1,4 @@
-import type { StoreLike, StoreSubscribe } from './stores.js';
+import { type StoreLike, type StoreSubscribe } from './stores.js';
 /**
  * Adapters that give non-`{getState, subscribe}` state libraries the shape `registerStore` wants.
  *

package/dist/registry/store-adapters.js

@@ -1,4 +1,5 @@
 import { nativeWarn } from '../timers/native-console.js';
+import { markAdapterSource } from './stores.js';
 /**
  * Expose a TanStack Query cache as a Reticle store, keyed by query key.
  *
@@ -16,7 +17,7 @@ export function tanstackQueryStore(client) {
     // effects, a provider remount, HMR — and an adapter holding the old cache would keep answering
     // from a store the app no longer reads, which is a stale-data bug inside the tool whose job is
     // catching stale data.
-    return {
+    const store = {
         getState: () => {
             const out = {};
             for (const query of client.getQueryCache().getAll()) {
@@ -34,6 +35,10 @@ export function tanstackQueryStore(client) {
         },
         subscribe: (listener) => client.getQueryCache().subscribe(listener),
     };
+    // Registering this adapter claims the CLIENT too, so fiber-tree discovery can tell that the app
+    // already wired this exact QueryClient and must not add a second entry for it.
+    markAdapterSource(store, client);
+    return store;
 }
 /**
  * Expose a chosen set of Jotai atoms as one Reticle store.

package/dist/registry/stores.d.ts

@@ -48,3 +48,7 @@ export declare function readStoresWithTruncation(only?: string): {
     stores: Record<string, unknown>;
     truncation?: Record<string, TruncationReport>;
 };
+/** Called by an adapter to record what it was built from. See `sourceOwner`. */
+export declare function markAdapterSource(store: object, source: object): void;
+/** The name this store source is registered under, or undefined if nothing has claimed it. */
+export declare function sourceOwner(value: unknown): string | undefined;

package/dist/registry/stores.js

@@ -34,6 +34,7 @@ function isStoreLike(source) {
  * leaves the store on pull-only reads: no change events, and an empty `stateDiffs` in every act summary.
  */
 export function registerStore(name, source, subscribe) {
+    claimSource(name, source);
     if (isStoreLike(source)) {
         const getter = () => source.getState();
         const sub = (listener) => source.subscribe(listener);
@@ -149,3 +150,37 @@ function warnSilentStoreOnce(name) {
         `changes are invisible: no STATE_CHANGE events, no state diffs in causal summaries, and a state ` +
         `predicate will never see it update. Pass the store object (or a subscribe callback) to fix.`);
 }
+/**
+ * Who owns a given store SOURCE — the object the app (or an adapter) was built from.
+ *
+ * Registration is keyed by name, which cannot answer "is this same store already readable?". The
+ * question matters because the React adapter discovers stores from the fiber tree, and an app that
+ * has already registered the very same store by hand must not get a second entry for it under a
+ * second name. Comparing the READ VALUE cannot answer it either: `tanstackQueryStore` builds a fresh
+ * snapshot object on every `getState`, so identity never matches. Measured on bench-app, which
+ * registers `queries` itself and got an auto-discovered `query` beside it — one cache, listed twice,
+ * in every state read.
+ *
+ * A WeakMap so nothing here keeps an app's store alive.
+ */
+const sourceOwners = new WeakMap();
+/** Adapter instance → the object it wraps, so registering an adapter also claims its source. */
+const adapterSources = new WeakMap();
+/** Called by an adapter to record what it was built from. See `sourceOwner`. */
+export function markAdapterSource(store, source) {
+    adapterSources.set(store, source);
+}
+function claimSource(name, source) {
+    if (null === source || ('object' !== typeof source && 'function' !== typeof source))
+        return;
+    sourceOwners.set(source, name);
+    const wrapped = adapterSources.get(source);
+    if (wrapped !== undefined)
+        sourceOwners.set(wrapped, name);
+}
+/** The name this store source is registered under, or undefined if nothing has claimed it. */
+export function sourceOwner(value) {
+    if (null === value || ('object' !== typeof value && 'function' !== typeof value))
+        return undefined;
+    return sourceOwners.get(value);
+}

package/dist/reticle.d.ts

@@ -55,6 +55,8 @@ export declare function buildEvent(args: {
     sessionId: string;
     data: Record<string, unknown>;
     ref?: string | undefined;
+    documentId?: string | undefined;
+    editEpoch?: number | undefined;
 }): ReticleEvent;
 /**
  * The browser-side orchestrator. Wires observers -> events -> bridge, and bridge
@@ -79,5 +81,15 @@ export declare class Reticle {
     describe(input: CapabilitiesInput): void;
     /** Live-control: end the session programmatically from the host app (drives the panel to ended). */
     endSession(): void;
+    /**
+     * Hand the SDK the page's hot-update channel, so a stale ref can say the code changed underneath it.
+     *
+     * `unknown` on purpose: the only caller that has one is the build integration, the shape it passes
+     * is Vite's `import.meta.hot`, and the SDK must not depend on Vite — it ships to Next, Electron,
+     * Tauri and plain pages. Anything that is not a subscribable channel is ignored, which is the
+     * normal case: with no channel the epoch stays at `NO_EDITS_OBSERVED`, meaning "no edits OBSERVED",
+     * never "no edits happened".
+     */
+    observeHotUpdates(hot: unknown): void;
     disconnect(): void;
 }

package/dist/reticle.js

@@ -1,5 +1,7 @@
-import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, TRANSPORT_LIMITS, buildRedactionPolicy, isLoopbackHostname, isLocalPage, setActiveRedactionPolicy, wireRedactionKeys, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
+import { setPresenterVisible } from './dom/dom-ignore.js';
+import { EventType, RETICLE_DEFAULT_PORT, RETICLE_PROTOCOL_VERSION, RETICLE_URL_PARAM, bridgeWsUrl, ReticleCommand, MessageKind, SESSION_AUTO, SessionState, TRANSPORT_LIMITS, buildRedactionPolicy, isLoopbackHostname, isLocalPage, setActiveRedactionPolicy, wireRedactionKeys, RETICLE_ROOT_GLOBAL, RETICLE_SDK_VERSION_GLOBAL, CONTRACT_FINGERPRINT, newDocumentId, NO_EDITS_OBSERVED, } from '@reticlehq/core';
 import { rememberSessionLabel } from './session-continuity.js';
+import { editEpoch } from './edit-epoch.js';
 import { createCommandRegistry, RELOAD_CACHE_BUST_PARAM, } from './commands/commands.js';
 import { Transport } from './transport/transport.js';
 import { unreachableMessage } from './transport/unreachable-message.js';
@@ -128,6 +130,15 @@ export function buildEvent(args) {
         type: args.type,
         sessionId: args.sessionId,
         ref: args.ref,
+        // Which document this was observed under, so the server can refuse evidence minted before a
+        // navigation replaced the page. Stamped HERE because it is the one place every event passes
+        // through: an observer added later would otherwise emit unstamped events, which read as
+        // "current" by design and would reintroduce the defect silently for one event type.
+        documentId: args.documentId,
+        // Which round of source edits this was observed under. Stamped HERE for exactly the reason
+        // documentId is, and omitted while nothing has hot-updated: absence already reads as "current"
+        // downstream, so `NO_EDITS_OBSERVED` on the wire would be bytes spent saying "unknown".
+        editEpoch: NO_EDITS_OBSERVED === args.editEpoch ? undefined : args.editEpoch,
         data: args.data,
     };
 }
@@ -141,6 +152,13 @@ export class Reticle {
     #teardowns = [];
     #connected = false;
     #session = 'default';
+    /**
+     * Minted once, here, because this class is constructed once per document: a full navigation tears
+     * down the JavaScript context and builds a new one, so the id dies with the document it names. An
+     * SPA route change does not reconstruct it, which is correct — same context, same in-flight
+     * requests, same evidence.
+     */
+    #documentId = newDocumentId(Math.random);
     #start = 0;
     #overlay;
     #presenter;
@@ -234,11 +252,18 @@ export class Reticle {
             // page observed rather than guessing at the daemon, which it cannot see from in here.
             onUnreachable: ({ url: tried, attempts }) => {
                 nativeWarn(unreachableMessage(tried, attempts));
+                // And on screen, not only in a console nobody has open. An instrumented page with a dead
+                // bridge looked exactly like a page with no Reticle in it, so the user could not tell a
+                // daemon they forgot to start from an install that did not work.
+                this.#presenter?.showUnreachable(tried, attempts);
             },
         });
         // Capabilities registered AFTER connect (which is when they are registered, by design) must
         // reach the bridge, or an app that declared its whole testable surface reads as having none.
         setCapabilitiesListener(() => this.#transport?.reannounce());
+        // Contributors only, and reported in capabilities so a verdict drawn with it open is never
+        // mistaken for an ordinary one. See connect-options.ts.
+        setPresenterVisible(true === options.exposePresenter);
         const emit = this.#emit;
         this.#teardowns = installAllObservers(emit, {
             captureBodies: true === options.captureNetworkBodies,
@@ -321,6 +346,18 @@ export class Reticle {
     endSession() {
         this.#presenter?.setState(SessionState.ENDED);
     }
+    /**
+     * Hand the SDK the page's hot-update channel, so a stale ref can say the code changed underneath it.
+     *
+     * `unknown` on purpose: the only caller that has one is the build integration, the shape it passes
+     * is Vite's `import.meta.hot`, and the SDK must not depend on Vite — it ships to Next, Electron,
+     * Tauri and plain pages. Anything that is not a subscribable channel is ignored, which is the
+     * normal case: with no channel the epoch stays at `NO_EDITS_OBSERVED`, meaning "no edits OBSERVED",
+     * never "no edits happened".
+     */
+    observeHotUpdates(hot) {
+        editEpoch.observe(hot);
+    }
     disconnect() {
         if (!this.#connected)
             return;
@@ -347,6 +384,8 @@ export class Reticle {
             t: Math.round(performance.now() - this.#start),
             type,
             sessionId: this.#session,
+            documentId: this.#documentId,
+            editEpoch: editEpoch.current,
             data,
             ref,
         });

package/dist/transport/unreachable-message.d.ts

@@ -10,3 +10,10 @@
  * diagnose the daemon, and lists the checks in the order that actually resolves the ambiguity.
  */
 export declare function unreachableMessage(url: string, attempts: number): string;
+/**
+ * The same fact, sized for the HUD's one-line status row.
+ *
+ * The console warning explains; this one only has room to name the URL, which is the answer in
+ * most cases anyway — a bridge on a port the page is not dialling.
+ */
+export declare function unreachableStripText(url: string, attempts: number): string;

package/dist/transport/unreachable-message.js

@@ -5,12 +5,13 @@
  * than a template inlined in a warn call. The rule it exists to hold: report what this page observed
  * and what it could not determine, never a cause. See unreachable-message.test.ts.
  */
+import { UNREACHABLE_NOTICE_PREFIX } from '@reticlehq/core';
 /**
  * The page tried, failed, and cannot see why. Names the address and the attempt count, refuses to
  * diagnose the daemon, and lists the checks in the order that actually resolves the ambiguity.
  */
 export function unreachableMessage(url, attempts) {
-    return (`[Reticle] this page could not open a websocket to ${url}. ${String(attempts)} attempts, all ` +
+    return (`${UNREACHABLE_NOTICE_PREFIX}${url}. ${String(attempts)} attempts, all ` +
         `failed. That is everything the page can see: from inside the browser it cannot tell a daemon ` +
         `that is not there from one it is not allowed to reach, so this is not evidence about the ` +
         `daemon. What answers it: run \`npx @reticlehq/server status\` to see whether one is listening ` +
@@ -18,3 +19,12 @@ export function unreachableMessage(url, attempts) {
         `different host, so set the URL explicitly (Vite: VITE_RETICLE_WS_URL, or ` +
         `reticle.connect({ url })). An https page cannot open a ws:// socket at all. Still retrying…`);
 }
+/**
+ * The same fact, sized for the HUD's one-line status row.
+ *
+ * The console warning explains; this one only has room to name the URL, which is the answer in
+ * most cases anyway — a bridge on a port the page is not dialling.
+ */
+export function unreachableStripText(url, attempts) {
+    return `no bridge at ${url} — ${String(attempts)} attempt${1 === attempts ? '' : 's'}`;
+}