@reticlehq/browser 2.12.0 → 2.13.0

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.js

@@ -1,3 +1,4 @@
+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';
@@ -251,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,

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

@@ -19,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'}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@reticlehq/core": "2.12.0"
+    "@reticlehq/core": "2.13.0"
   },
   "devDependencies": {
     "@iconify-json/heroicons-outline": "^1.2.1",
@@ -21,11 +21,11 @@
     "@tanstack/query-core": "^5.101.4",
     "jotai": "^2.20.2",
     "jsdom": "^30.0.1",
-    "mobx": "^7.0.0",
+    "mobx": "^7.0.3",
     "pinia": "^4.0.3",
     "react": "^19.2.8",
     "recoil": "^0.7.7",
-    "svelte": "^5.56.8",
+    "svelte": "^5.56.10",
     "valtio": "^2.3.2",
     "vue": "^3.5.41",
     "xstate": "^5.32.5"