@reticlehq/browser 2.7.0 → 2.9.0

package/dist/dom/source.js

@@ -46,6 +46,22 @@ export function sourceFor(el, adapterSource) {
         return { file: adapterSource.file, line: adapterSource.line };
     return sourceFromDom(el);
 }
+/**
+ * Does ANY element in this document carry a source stamp?
+ *
+ * The difference between "this element has no stamp" and "the stamping loader is not running at
+ * all" — two answers that look identical from a single missing `source` field, and that call for
+ * completely different next actions. The first is ordinary: not every element sits under a stamped
+ * host. The second means "fix at file:line", the single most-cited reason to reach for Reticle over
+ * a generic DOM tool, is silently unavailable for the whole session — and it has been discovered by
+ * reading the adapter's source rather than from anything Reticle said.
+ *
+ * One `querySelector`, which stops at the first hit, so this is cheap enough to answer on a
+ * single-element path like inspect. It is only consulted when a source is already missing.
+ */
+export function documentHasSourceStamps(doc) {
+    return doc.querySelector(`[${SOURCE_ATTR}]`) !== null;
+}
 /**
  * `file:line` — the form an agent can act on directly.
  *

package/dist/dom/theme.d.ts

@@ -1,25 +1,48 @@
 /**
  * Design-token (theme) awareness — the in-source answer to "is this color on-theme?". A DOM/a11y
  * tool sees a color rendered; it does not know the app's INTENDED palette. Reticle reads the design
- * tokens the app declares as `:root` CSS custom properties and reports, per element, whether its
- * color/background maps to a token or is an off-palette hardcoded value. That is a theme-compliance
- * signal no outside-the-page tool has without re-deriving the palette itself.
+ * tokens the app declares as CSS custom properties, resolves them AS THE PAGE CURRENTLY RENDERS
+ * THEM, and reports, per element, which tokens its color/background map to or whether the value is
+ * an off-palette hardcoded one. That is a theme-compliance signal no outside-the-page tool has
+ * without re-deriving the palette itself.
  *
  * Conservative by design: only a SET, opaque color with no matching token is flagged off-theme, and
- * the matched token name is returned when there is one — so the agent can judge, not just trust a flag.
+ * every matching token name is returned — so the agent can judge, not just trust a flag.
+ *
+ * Two defects made this field untrustworthy in BOTH directions before it was rewritten:
+ *   - the reverse map was color → ONE name, first writer wins, so a button styled with a brand token
+ *     was told its background was a focus-border token because the two resolve to the same hex. The
+ *     name is the part an agent reasons about, and it was arbitrary among the candidates.
+ *   - the palette was built from the RAW `:root` declaration text and cached for the page lifetime,
+ *     on the reasoning that a theme rarely changes at runtime. A human toggling the theme between
+ *     two inspect calls left every lookup keyed on the previous theme's colors, so a `<summary>` that
+ *     had just been changed to a text token reported a surface token. The reporter read that as their
+ *     edit not applying and went hunting for a theme-scope bug that did not exist.
+ * Hence: no cache, values resolved through `getComputedStyle` so the active theme wins, and the
+ * scope that was active at capture time reported alongside, so two results minutes apart are
+ * comparable at all.
  */
 interface ThemeReport {
-    /** Matched design-token name for the text color, or null when the color is off-palette. */
+    /**
+     * The ONE design token matching the text color, or null. Null both when nothing matches and when
+     * several tokens share the color: the previous behaviour picked an arbitrary winner and the caller
+     * could not tell, which is the whole defect. Read `colorTokens` for the full answer; this field
+     * stays for callers that only ever wanted the unambiguous case.
+     */
     colorToken: string | null;
-    /** Matched design-token name for the background color, or null. */
+    /** Every design token whose resolved value is the text color. Empty when the color is off-palette. */
+    colorTokens: string[];
+    /** The one design token matching the background color, or null (same abstain-on-tie rule). */
     backgroundToken: string | null;
-    /** True when a set, opaque color uses no design token — a theme violation worth surfacing. */
+    /** Every design token whose resolved value is the background color. */
+    backgroundTokens: string[];
+    /** True when a set, opaque color matches NO design token — a theme violation worth surfacing. */
     offTheme: boolean;
-    /** How many color tokens the app declared (0 ⇒ no palette found, so offTheme is never asserted). */
+    /** How many color tokens resolved under the active theme (0 ⇒ offTheme is never asserted). */
     tokenCount: number;
+    /** Theme scope active at capture time, e.g. `.dark`, so two results taken apart are comparable. */
+    themeScope: string | null;
 }
 /** Report an element's theme compliance from its computed style. */
 export declare function themeReport(cs: CSSStyleDeclaration): ThemeReport;
-/** Drop the cached palette (call if the app swaps themes at runtime). */
-export declare function resetThemeCache(): void;
 export {};

package/dist/dom/theme.js

@@ -1,33 +1,32 @@
 /**
  * Design-token (theme) awareness — the in-source answer to "is this color on-theme?". A DOM/a11y
  * tool sees a color rendered; it does not know the app's INTENDED palette. Reticle reads the design
- * tokens the app declares as `:root` CSS custom properties and reports, per element, whether its
- * color/background maps to a token or is an off-palette hardcoded value. That is a theme-compliance
- * signal no outside-the-page tool has without re-deriving the palette itself.
+ * tokens the app declares as CSS custom properties, resolves them AS THE PAGE CURRENTLY RENDERS
+ * THEM, and reports, per element, which tokens its color/background map to or whether the value is
+ * an off-palette hardcoded one. That is a theme-compliance signal no outside-the-page tool has
+ * without re-deriving the palette itself.
  *
  * Conservative by design: only a SET, opaque color with no matching token is flagged off-theme, and
- * the matched token name is returned when there is one — so the agent can judge, not just trust a flag.
+ * every matching token name is returned — so the agent can judge, not just trust a flag.
+ *
+ * Two defects made this field untrustworthy in BOTH directions before it was rewritten:
+ *   - the reverse map was color → ONE name, first writer wins, so a button styled with a brand token
+ *     was told its background was a focus-border token because the two resolve to the same hex. The
+ *     name is the part an agent reasons about, and it was arbitrary among the candidates.
+ *   - the palette was built from the RAW `:root` declaration text and cached for the page lifetime,
+ *     on the reasoning that a theme rarely changes at runtime. A human toggling the theme between
+ *     two inspect calls left every lookup keyed on the previous theme's colors, so a `<summary>` that
+ *     had just been changed to a text token reported a surface token. The reporter read that as their
+ *     edit not applying and went hunting for a theme-scope bug that did not exist.
+ * Hence: no cache, values resolved through `getComputedStyle` so the active theme wins, and the
+ * scope that was active at capture time reported alongside, so two results minutes apart are
+ * comparable at all.
  */
-let cached = null;
-/** Resolve any CSS color string to canonical computed `rgb...)`/`rgba...)`, or null if not a color. */
-function toRgb(value) {
-    if (0 === value.length)
-        return null;
-    const probe = document.createElement('span');
-    probe.style.color = '';
-    probe.style.color = value; // invalid colors leave it empty (the setter rejects them)
-    if ('' === probe.style.color)
-        return null;
-    probe.style.position = 'absolute';
-    probe.style.pointerEvents = 'none';
-    document.body.appendChild(probe);
-    const rgb = getComputedStyle(probe).color;
-    probe.remove();
-    return rgb;
-}
-/** Collect `--token: value` declarations from every:root/html rule across the app's stylesheets. */
-function collectTokens() {
-    const out = {};
+/** Attribute an app flips to switch themes, reported as part of the scope so results are comparable. */
+const THEME_ATTRIBUTE = 'data-theme';
+/** Collect every custom-property NAME the app declares, in any rule. */
+function tokenNames() {
+    const names = new Set();
     for (const sheet of Array.from(document.styleSheets)) {
         let rules = null;
         try {
@@ -41,49 +40,109 @@ function collectTokens() {
         for (const rule of Array.from(rules)) {
             if (!(rule instanceof CSSStyleRule))
                 continue;
-            if (!/(^|,)\s*(:root|html)\b/.test(rule.selectorText))
-                continue;
+            // Deliberately NOT filtered to `:root`/`html`: a theme block is usually `.dark` or
+            // `[data-theme="dark"]`, and an app that declares its palette only there had no palette at all
+            // under the old filter. Names are cheap; a name that is not in scope resolves to nothing below
+            // and is dropped, so widening collection cannot invent a token.
             for (const prop of Array.from(rule.style)) {
                 if (prop.startsWith('--'))
-                    out[prop] = rule.style.getPropertyValue(prop).trim();
+                    names.add(prop);
             }
         }
     }
-    return out;
+    return names;
 }
-/** The app's palette (color tokens → rgb), built once and cached (theme rarely changes at runtime). */
+/**
+ * The palette as the page renders it right now: canonical `rgb(...)` → every token with that color.
+ *
+ * Resolved against `document.body` rather than the raw declaration text, because custom properties
+ * inherit: this picks up a theme scoped to `<html>` or to `<body>`, and picks up the value the
+ * ACTIVE theme block won with rather than whichever block the stylesheet happened to list first.
+ */
 function palette() {
-    if (cached !== null)
-        return cached;
     const byColor = new Map();
-    for (const [name, value] of Object.entries(collectTokens())) {
-        const rgb = toRgb(value);
-        if (rgb !== null && !byColor.has(rgb))
-            byColor.set(rgb, name);
+    const root = document.body ?? document.documentElement;
+    if (null === root)
+        return byColor;
+    const rootStyle = getComputedStyle(root);
+    // One shared probe for the whole build. There is no cache any more, so this runs per inspect, and
+    // a span per token would be a few hundred appends on a real design system.
+    const probe = document.createElement('span');
+    probe.style.position = 'absolute';
+    probe.style.pointerEvents = 'none';
+    document.body.appendChild(probe);
+    try {
+        for (const name of tokenNames()) {
+            const rgb = toRgb(probe, rootStyle.getPropertyValue(name).trim());
+            if (null === rgb)
+                continue;
+            const named = byColor.get(rgb);
+            if (named === undefined)
+                byColor.set(rgb, [name]);
+            else
+                named.push(name);
+        }
+    }
+    finally {
+        probe.remove();
     }
-    cached = { byColor };
-    return cached;
+    // Sorted so the reported order is a property of the app's tokens, not of stylesheet iteration
+    // order — the same collision must read the same way on two consecutive inspects.
+    for (const named of byColor.values())
+        named.sort();
+    return byColor;
+}
+/** Resolve any CSS color string to canonical computed `rgb...)`/`rgba...)`, or null if not a color. */
+function toRgb(probe, value) {
+    if (0 === value.length)
+        return null;
+    probe.style.color = '';
+    probe.style.color = value; // invalid colors leave it empty (the setter rejects them)
+    if ('' === probe.style.color)
+        return null;
+    return getComputedStyle(probe).color;
 }
 /** True for a color that carries no visual weight (fully transparent) — never flagged off-theme. */
 function isTransparent(rgb) {
     return 'rgba(0, 0, 0, 0)' === rgb || 'transparent' === rgb;
 }
+/**
+ * The theme scope in force at capture time, as a selector-shaped string (`.dark[data-theme="dark"]`),
+ * or null when the root carries no theme marker at all.
+ */
+function themeScope() {
+    const el = document.documentElement;
+    if (null === el)
+        return null;
+    const classes = Array.from(el.classList)
+        .map((c) => `.${c}`)
+        .join('');
+    const attr = el.getAttribute(THEME_ATTRIBUTE);
+    const scope = `${classes}${null === attr ? '' : `[${THEME_ATTRIBUTE}="${attr}"]`}`;
+    return 0 === scope.length ? null : scope;
+}
+/** The unambiguous match, or null when the palette cannot tell the candidates apart. */
+function sole(names) {
+    return 1 === names.length ? (names[0] ?? null) : null;
+}
 /** Report an element's theme compliance from its computed style. */
 export function themeReport(cs) {
-    const p = palette();
-    const colorToken = p.byColor.get(cs.color) ?? null;
-    const backgroundToken = p.byColor.get(cs.backgroundColor) ?? null;
-    const colorOff = !isTransparent(cs.color) && null === colorToken;
-    const bgOff = !isTransparent(cs.backgroundColor) && null === backgroundToken;
+    const byColor = palette();
+    const colorTokens = byColor.get(cs.color) ?? [];
+    const backgroundTokens = byColor.get(cs.backgroundColor) ?? [];
+    const colorOff = !isTransparent(cs.color) && 0 === colorTokens.length;
+    const bgOff = !isTransparent(cs.backgroundColor) && 0 === backgroundTokens.length;
+    let tokenCount = 0;
+    for (const named of byColor.values())
+        tokenCount += named.length;
     return {
-        colorToken,
-        backgroundToken,
+        colorToken: sole(colorTokens),
+        colorTokens,
+        backgroundToken: sole(backgroundTokens),
+        backgroundTokens,
         // Only meaningful when a palette exists; an app with no tokens can't violate one.
-        offTheme: p.byColor.size > 0 && (colorOff || bgOff),
-        tokenCount: p.byColor.size,
+        offTheme: tokenCount > 0 && (colorOff || bgOff),
+        tokenCount,
+        themeScope: themeScope(),
     };
 }
-/** Drop the cached palette (call if the app swaps themes at runtime). */
-export function resetThemeCache() {
-    cached = null;
-}

package/dist/observers/console.js

@@ -1,5 +1,6 @@
 import { EventType, TRANSPORT_LIMITS } from '@reticlehq/core';
 import { safeStringify } from '../security/serialization.js';
+import { requireCapturedMethod } from '../util/captured-method.js';
 const METHOD_EVENT = {
     log: EventType.CONSOLE_LOG,
     warn: EventType.CONSOLE_WARN,
@@ -41,8 +42,10 @@ export function installConsole(emit) {
     const originals = new Map();
     const patched = new Map();
     for (const method of methods) {
-        // Store the true original for teardown identity; call through a bound copy.
-        const original = console[method];
+        // Store the true original for teardown identity; call through a bound copy. Read as a stored
+        // VALUE rather than a method reference — see capturedMethod for why that distinction is the
+        // honest way to say "I am detaching this deliberately and putting it back".
+        const original = requireCapturedMethod(console, method);
         originals.set(method, original);
         const callOriginal = original.bind(console);
         const wrapper = (...args) => {

package/dist/observers/install-all.js

@@ -18,7 +18,7 @@ import { installFocus } from './focus.js';
 import { installBlindSpots } from './blind-spots.js';
 import { installDownload } from './download.js';
 import { installNetwork } from './network.js';
-import { installIpc, ipcNetOverrides } from './ipc.js';
+import { installIpc, ipcNetOverrides, isReticleOwnIpc } from './ipc.js';
 import { installPerf } from './perf.js';
 import { installRoute } from './route.js';
 import { installConsole } from './console.js';
@@ -43,6 +43,9 @@ export function installAllObservers(emit, options) {
         guard(emit, SdkSite.NETWORK_OBSERVER, () => installNetwork(emit, {
             captureBodies: options.captureBodies,
             reinterpret: ipcNetOverrides,
+            // The SDK's own Tauri screenshot is a fetch like any other — skip it, or the observer
+            // reports its own captures as the app's writes.
+            ignore: isReticleOwnIpc,
         })),
         // Desktop backends are reached over IPC, not HTTP — inert on a plain web page.
         guard(emit, SdkSite.IPC_OBSERVER, () => installIpc(emit, { captureBodies: options.captureBodies })),

package/dist/observers/ipc.d.ts

@@ -5,6 +5,22 @@ import type { Emit, Teardown } from './types.js';
  * already holds, so IPC knowledge stays in this file.
  */
 export declare function ipcNetOverrides(url: string, header: (name: string) => string | null): Record<string, unknown> | undefined;
+/**
+ * Is this fetch Reticle's OWN desktop call rather than the app's?
+ *
+ * Tauri has no preload stage, so `reticle_screenshot` reaches the shell the only way it can: an
+ * `invoke` — and an invoke IS a fetch to the `ipc://` protocol, straight through the patch the
+ * network observer installed. So the observer recorded its own screenshots as app IPC calls, and
+ * because `IPC` counts as a mutating method, three concurrent captures inside one action window came
+ * back to the agent as `duplicate-request`: "the same write fired 3 times", against an app that had
+ * never made the call. Accusing a correct app of a double submit is the most damaging thing a
+ * verification tool can do, and here the tool was the one submitting.
+ *
+ * Electron never had this problem — its preload captures through the UNPATCHED invoke for exactly
+ * this reason — and the bridge's own WebSocket is skipped on the same principle (`isBridgeSocket`).
+ * The capture command is the SDK's whole Tauri-side surface, so matching it is the whole rule.
+ */
+export declare function isReticleOwnIpc(url: string): boolean;
 /**
  * Subscribe to the Electron preload shim, if this app installed it. Inert on Tauri (whose calls the
  * network observer handles) and on a plain web page.

package/dist/observers/ipc.js

@@ -1,4 +1,4 @@
-import { BlindSpotKind, EventType, IPC_URL_SCHEME, IpcStatus, NetInitiator, RETICLE_IPC_GLOBAL, } from '@reticlehq/core';
+import { BlindSpotKind, EventType, IPC_URL_SCHEME, IpcStatus, NetInitiator, RETICLE_IPC_GLOBAL, RETICLE_TAURI_CAPTURE_COMMAND, } from '@reticlehq/core';
 import { observeSafely } from './types.js';
 /**
  * How Tauri v2 reports a command's verdict. The transport answers HTTP 200 whether the Rust command
@@ -48,6 +48,24 @@ export function ipcNetOverrides(url, header) {
         statusText: ok ? IPC_STATUS_TEXT.OK : IPC_STATUS_TEXT.ERROR,
     };
 }
+/**
+ * Is this fetch Reticle's OWN desktop call rather than the app's?
+ *
+ * Tauri has no preload stage, so `reticle_screenshot` reaches the shell the only way it can: an
+ * `invoke` — and an invoke IS a fetch to the `ipc://` protocol, straight through the patch the
+ * network observer installed. So the observer recorded its own screenshots as app IPC calls, and
+ * because `IPC` counts as a mutating method, three concurrent captures inside one action window came
+ * back to the agent as `duplicate-request`: "the same write fired 3 times", against an app that had
+ * never made the call. Accusing a correct app of a double submit is the most damaging thing a
+ * verification tool can do, and here the tool was the one submitting.
+ *
+ * Electron never had this problem — its preload captures through the UNPATCHED invoke for exactly
+ * this reason — and the bridge's own WebSocket is skipped on the same principle (`isBridgeSocket`).
+ * The capture command is the SDK's whole Tauri-side surface, so matching it is the whole rule.
+ */
+export function isReticleOwnIpc(url) {
+    return TAURI_IPC_URL.exec(url)?.[1] === RETICLE_TAURI_CAPTURE_COMMAND;
+}
 /**
  * Is this page an Electron renderer? Read off the user agent, which Electron stamps and which is
  * available whether or not the preload ran — the whole point is to recognise a renderer that has

package/dist/observers/network.d.ts

@@ -16,6 +16,14 @@ interface NetworkOptions {
     captureBodies?: boolean;
     /** Optional hook that reinterprets a completed request — see NetResponseReinterpreter. */
     reinterpret?: NetResponseReinterpreter;
+    /**
+     * Requests Reticle itself makes, which must never reach the app's evidence.
+     *
+     * Same seam and same reason as `reinterpret`: this observer knows nothing about desktop IPC, and
+     * the SDK's own Tauri screenshot travels as an ordinary fetch through this very patch. Passed in
+     * rather than imported, so the knowledge stays in the IPC observer.
+     */
+    ignore?: (url: string) => boolean;
 }
 /** Pure: the first real app-code frame in a stack string, capped. Exported for unit testing. */
 export declare function firstAppFrame(stack: string | undefined): string | undefined;

package/dist/observers/network.js

@@ -3,6 +3,7 @@ import { captureMethod } from '../patching/capture-method.js';
 import { isCapturableType, projectBody, withBodyDeadline } from './network-body.js';
 import { redactUrl } 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 };
@@ -60,6 +61,22 @@ function projectRequestBody(body, captureBodies) {
     const { body: out, truncated } = projectBody(text, contentType);
     return truncated ? { requestBody: out, requestBodyTruncated: true } : { requestBody: out };
 }
+/**
+ * Did this response succeed? A REDIRECT DID.
+ *
+ * The one rule both transports must share. `Response.ok` is true only for 200-299, so reading it
+ * straight through stamped every 3xx as a failed request, while the XHR path computed the same field
+ * itself and called the identical status a success. Downstream, `ok` is authoritative when present —
+ * so a POST-redirect-GET login, the first flow anyone verifies in an app with auth, produced a
+ * `ui-advanced-request-failed` contradiction citing its own success path, and the agent had to
+ * overrule the verdict by hand. A verdict that gets manually overruled is not deciding anything.
+ *
+ * 3xx is normal successful navigation. An opaque (no-cors) response reports status 0 and is correctly
+ * excluded here, exactly as `Response.ok` excluded it.
+ */
+function statusIsOk(status) {
+    return status >= 200 && status < 400;
+}
 /**
  * Response metadata that needs no body capture: HTTP status text, content-type, and byte size (from
  * content-length when the server sent it). Lets an agent tell an HTML error page served as 200 from
@@ -195,7 +212,7 @@ export function installNetwork(emit, opts = {}) {
     const reinterpret = opts.reinterpret;
     // Keep the true original for teardown identity, plus a window-bound copy to invoke
     // (fetch throws "Illegal invocation" if called with the wrong `this`).
-    const origFetch = window.fetch;
+    const origFetch = requireCapturedMethod(window, 'fetch');
     const callFetch = origFetch.bind(window);
     // Declare it if we are not the first to wrap fetch.
     //
@@ -218,10 +235,15 @@ export function installNetwork(emit, opts = {}) {
     let seq = 0;
     const nextId = () => `n${++seq}`;
     window.fetch = async (input, init) => {
+        const rawUrl = urlOf(input);
+        // Reticle's own call: pass it straight through, observed by nobody. Emitting even the PENDING
+        // half would be wrong twice over — it lands in the agent's network evidence, and `settle` would
+        // wait on the SDK's own screenshot as if the app had a request in flight.
+        if (true === opts.ignore?.(rawUrl))
+            return callFetch(input, init);
         const id = nextId();
         const start = performance.now();
         const method = methodOf(input, init);
-        const rawUrl = urlOf(input);
         const url = redactUrl(rawUrl);
         const initiatorStack = initiatorFrame();
         const initiatorFields = initiatorStack === undefined ? {} : { initiatorStack };
@@ -240,7 +262,7 @@ export function installNetwork(emit, opts = {}) {
                     method,
                     url,
                     status: res.status,
-                    ok: res.ok,
+                    ok: statusIsOk(res.status),
                     durationMs: Math.round(headersAt - start),
                     initiator: 'fetch',
                     ...initiatorFields,
@@ -320,8 +342,9 @@ export function installNetwork(emit, opts = {}) {
         }
     };
     // Remember it, so a later install recognises our own wrapper instead of reporting the app.
-    OURS.add(window.fetch);
-    const patchedFetch = window.fetch;
+    // Our own wrapper, read the same way — it is a value we stored a line ago, not a method call.
+    const patchedFetch = requireCapturedMethod(window, 'fetch');
+    OURS.add(patchedFetch);
     const meta = new WeakMap();
     const proto = XMLHttpRequest.prototype;
     const origOpen = captureMethod(proto, 'open');
@@ -382,7 +405,7 @@ export function installNetwork(emit, opts = {}) {
                         method: cur.method,
                         url: cur.url,
                         status: this.status,
-                        ok: this.status >= 200 && this.status < 400,
+                        ok: statusIsOk(this.status),
                         durationMs: Math.round(performance.now() - cur.start),
                         initiator: 'xhr',
                         ...(cur.initiatorStack === undefined ? {} : { initiatorStack: cur.initiatorStack }),

package/dist/observers/state.js

@@ -1,4 +1,4 @@
-import { EventType, REDACTED_VALUE } from '@reticlehq/core';
+import { BlindSpotKind, EventType, REDACTED_VALUE } from '@reticlehq/core';
 import { subscribableStores, onStoreRegistered, } from '../registry/stores.js';
 import { isSensitiveKey, sanitizeForTransport } from '../security/serialization.js';
 function isRecord(value) {
@@ -68,9 +68,28 @@ export function installStoreState(emit) {
     // Stores already registered...
     for (const entry of subscribableStores())
         watch(entry);
+    /**
+     * Declare an unwatched state channel — and clear it the moment one is watched.
+     *
+     * With nothing subscribed, every act reports `stateDiffs: []`, which reads as "the app changed no
+     * state" when the truth is "nobody was looking". Emitted as a BLIND_SPOT so it travels the path
+     * that already exists for everything the layer cannot see: bounding, never impeaching, so no
+     * verdict turns UNKNOWN over it.
+     */
+    if (0 === active.size) {
+        emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.UNWATCHED_STATE, count: 1 });
+    }
     //...and any registered LATER. The SDK installs observers during connect, but apps call
     // registerStore after that, so without this the common case subscribes to nothing.
-    const offRegistered = onStoreRegistered(watch);
+    const offRegistered = onStoreRegistered((entry) => {
+        const wasDark = 0 === active.size;
+        watch(entry);
+        // The channel just lit up. A blind spot that is never withdrawn is a permanent lie, and this one
+        // is withdrawn in the ordinary case: apps register their stores AFTER connect() installs us.
+        if (wasDark && active.size > 0) {
+            emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.UNWATCHED_STATE, count: 0 });
+        }
+    });
     return () => {
         offRegistered();
         for (const unsubscribe of active.values()) {

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

@@ -1,19 +1,36 @@
+/**
+ * The artwork constants are annotated `: string` deliberately.
+ *
+ * Without the annotation TypeScript infers a literal type, and every one of these SVG and HTML
+ * strings is copied verbatim into the emitted `.d.ts` as its own type. That duplicated the artwork
+ * into the published package twice over: this file's declarations alone were 16KB of a 900KB
+ * budget, carrying type information nobody can use - no caller cares about the literal type of a
+ * `<path d=...>`.
+ */
 /**
  * Brand marks, inlined. The SDK is bundled into someone else's page: it cannot read
  * `assets/logo/*.svg` from disk at runtime and must never fetch from our own domain, so the two
  * artwork files live here as strings (same precedent as SEND_ICON in presenter-controls.ts).
- * Both are minified — editor metadata, clip paths, masks and sub-0.01 precision stripped — and paint
+ * Both are minified - editor metadata, clip paths, masks and sub-0.01 precision stripped - and paint
  * with `currentColor` so the mark tracks --reticle-fg instead of hardcoding the export's #FAFAFA.
  */
-/** Accessible name of the HUD — the wordmark is artwork, this is what a screen reader reads. */
+/** Accessible name of the HUD - the wordmark is artwork, this is what a screen reader reads. */
 export declare const BRAND_NAME = "Reticle";
-/** Mark alone (shown when the HUD is collapsed to a pill). */
-export declare const MARK_SVG = "<svg class=\"reticle-mark\" viewBox=\"0 0 96 94\" fill=\"currentColor\" aria-hidden=\"true\"><path d=\"M92.82 92.16C93.07 93.4 91.77 94.4 90.63 93.83C89.62 93.33 88.62 92.82 87.63 92.3C71.14 83.78 54.79 72.27 39.61 57.96C39.09 57.49 38.57 56.98 38.06 56.49C22.45 41.52 9.78 25.14 .33 8.52C0.29 8.45 .25 8.38 .2 8.31C-0.44 7.2 .51 5.84 1.79 6.05L24.07 9.71C43.06 12.83 60.63 11.75 75.55 6.53L93.95 .09C95.15-0.33 96.31 .78 95.93 1.98L90.1 20.49C85.37 35.48 84.9 52.97 88.69 71.73L92.83 92.16H92.82Z\"/><path d=\"M58.72 89.23L6.15 92.8C5.24 92.86 4.48 92.13 4.51 91.22L6.56 30.39C6.61 28.91 8.51 28.36 9.35 29.57C16.23 39.43 24.98 52.35 33.01 61.26C41.05 70.17 50.6 78.72 59.62 86.56C60.65 87.45 60.08 89.13 58.72 89.23Z\"/></svg>";
-/** Mark + "reticle" lettering (shown when the HUD is expanded). */
-export declare const WORDMARK_SVG = "<svg class=\"reticle-wordmark\" viewBox=\"0 0 347 96\" fill=\"currentColor\" aria-hidden=\"true\"><g transform=\"translate(1 1)\"><path d=\"M92.82 92.16C93.07 93.4 91.77 94.4 90.63 93.83C89.62 93.33 88.62 92.82 87.63 92.3C71.14 83.78 54.79 72.27 39.61 57.96C39.09 57.49 38.57 56.98 38.06 56.49C22.45 41.52 9.78 25.14 .33 8.52C0.29 8.45 .25 8.38 .2 8.31C-0.44 7.2 .51 5.84 1.79 6.05L24.07 9.71C43.06 12.83 60.63 11.75 75.55 6.53L93.95 .09C95.15-0.33 96.31 .78 95.93 1.98L90.1 20.49C85.37 35.48 84.9 52.97 88.69 71.73L92.83 92.16H92.82Z\"/><path d=\"M58.72 89.23L6.15 92.8C5.24 92.86 4.48 92.13 4.51 91.22L6.56 30.39C6.61 28.91 8.51 28.36 9.35 29.57C16.23 39.43 24.98 52.35 33.01 61.26C41.05 70.17 50.6 78.72 59.62 86.56C60.65 87.45 60.08 89.13 58.72 89.23Z\"/></g><path d=\"M116.43 78V27.09H136.51C140.35 27.09 143.64 27.78 146.35 29.15C149.09 30.51 151.17 32.44 152.59 34.95C154.04 37.43 154.76 40.36 154.76 43.72C154.76 47.1 154.03 50.01 152.57 52.45C151.11 54.87 149 56.72 146.23 58.01C143.48 59.31 140.15 59.95 136.24 59.95H122.79V51.3H134.5C136.55 51.3 138.26 51.02 139.62 50.46C140.98 49.89 141.99 49.05 142.65 47.92C143.33 46.8 143.67 45.39 143.67 43.72C143.67 42.03 143.33 40.61 142.65 39.45C141.99 38.29 140.97 37.41 139.59 36.81C138.23 36.2 136.52 35.89 134.45 35.89H127.19V78H116.43ZM143.92 54.83L156.57 78H144.69L132.31 54.83H143.92ZM178.95 78.75C175.02 78.75 171.64 77.95 168.81 76.36C165.99 74.75 163.82 72.48 162.29 69.55C160.77 66.6 160.01 63.11 160.01 59.08C160.01 55.16 160.77 51.71 162.29 48.74C163.82 45.78 165.97 43.46 168.73 41.81C171.52 40.15 174.78 39.32 178.53 39.32C181.05 39.32 183.39 39.73 185.56 40.54C187.75 41.33 189.65 42.54 191.28 44.14C192.92 45.75 194.2 47.77 195.11 50.21C196.02 52.63 196.47 55.46 196.47 58.71V61.62H164.23V55.06H186.51C186.51 53.53 186.17 52.18 185.51 51C184.85 49.83 183.93 48.91 182.75 48.25C181.59 47.57 180.24 47.23 178.7 47.23C177.09 47.23 175.67 47.6 174.43 48.34C173.2 49.07 172.24 50.06 171.54 51.3C170.85 52.53 170.49 53.9 170.47 55.4V61.64C170.47 63.53 170.82 65.17 171.52 66.54C172.23 67.92 173.23 68.98 174.52 69.72C175.82 70.47 177.35 70.84 179.12 70.84C180.3 70.84 181.38 70.68 182.35 70.34C183.33 70.01 184.17 69.52 184.87 68.85C185.56 68.19 186.09 67.38 186.46 66.42L196.25 67.06C195.75 69.42 194.73 71.47 193.19 73.23C191.67 74.97 189.7 76.33 187.28 77.3C184.87 78.27 182.1 78.75 178.95 78.75ZM223.69 39.82V47.77H200.7V39.82H223.69ZM205.92 30.67H216.51V66.27C216.51 67.24 216.66 68.01 216.96 68.55C217.26 69.08 217.67 69.46 218.2 69.67C218.75 69.89 219.38 70 220.09 70C220.59 70 221.08 69.95 221.58 69.87C222.08 69.77 222.46 69.7 222.72 69.65L224.39 77.53C223.86 77.69 223.11 77.88 222.15 78.1C221.19 78.33 220.02 78.47 218.65 78.52C216.1 78.62 213.86 78.28 211.94 77.5C210.03 76.72 208.55 75.51 207.49 73.87C206.43 72.23 205.9 70.16 205.92 67.66V30.67ZM230.59 78V39.82H241.18V78H230.59ZM235.91 34.9C234.34 34.9 232.99 34.37 231.86 33.33C230.75 32.27 230.19 31 230.19 29.53C230.19 28.07 230.75 26.82 231.86 25.77C232.99 24.71 234.34 24.18 235.91 24.18C237.49 24.18 238.83 24.71 239.94 25.77C241.07 26.82 241.63 28.07 241.63 29.53C241.63 31 241.07 32.27 239.94 33.33C238.83 34.37 237.49 34.9 235.91 34.9ZM266.92 78.75C263 78.75 259.64 77.92 256.82 76.26C254.02 74.59 251.87 72.27 250.36 69.3C248.87 66.33 248.12 62.92 248.12 59.06C248.12 55.15 248.88 51.72 250.38 48.77C251.91 45.8 254.07 43.49 256.87 41.83C259.67 40.16 263 39.32 266.87 39.32C270.2 39.32 273.11 39.93 275.62 41.14C278.12 42.35 280.1 44.04 281.56 46.23C283.01 48.42 283.82 50.99 283.97 53.94H273.97C273.69 52.03 272.95 50.5 271.74 49.34C270.54 48.16 268.98 47.57 267.04 47.57C265.4 47.57 263.96 48.02 262.74 48.92C261.53 49.79 260.58 51.08 259.9 52.77C259.23 54.46 258.89 56.51 258.89 58.91C258.89 61.35 259.22 63.42 259.88 65.12C260.56 66.83 261.51 68.13 262.74 69.03C263.96 69.92 265.4 70.37 267.04 70.37C268.25 70.37 269.33 70.12 270.3 69.62C271.27 69.13 272.08 68.4 272.71 67.46C273.35 66.5 273.78 65.35 273.97 64.01H283.97C283.8 66.92 283.01 69.49 281.58 71.71C280.17 73.92 278.23 75.64 275.74 76.88C273.25 78.12 270.31 78.75 266.92 78.75ZM301.34 27.09V78H290.75V27.09H301.34ZM327.22 78.75C323.29 78.75 319.91 77.95 317.08 76.36C314.26 74.75 312.09 72.48 310.57 69.55C309.04 66.6 308.28 63.11 308.28 59.08C308.28 55.16 309.04 51.71 310.57 48.74C312.09 45.78 314.24 43.46 317 41.81C319.79 40.15 323.05 39.32 326.8 39.32C329.32 39.32 331.66 39.73 333.83 40.54C336.02 41.33 337.93 42.54 339.55 44.14C341.19 45.75 342.47 47.77 343.38 50.21C344.29 52.63 344.75 55.46 344.75 58.71V61.62H312.5V55.06H334.78C334.78 53.53 334.45 52.18 333.78 51C333.12 49.83 332.2 48.91 331.02 48.25C329.86 47.57 328.51 47.23 326.97 47.23C325.36 47.23 323.94 47.6 322.7 48.34C321.47 49.07 320.51 50.06 319.81 51.3C319.12 52.53 318.76 53.9 318.74 55.4V61.64C318.74 63.53 319.09 65.17 319.79 66.54C320.5 67.92 321.5 68.98 322.8 69.72C324.09 70.47 325.62 70.84 327.39 70.84C328.57 70.84 329.65 70.68 330.63 70.34C331.6 70.01 332.44 69.52 333.14 68.85C333.83 68.19 334.36 67.38 334.73 66.42L344.52 67.06C344.02 69.42 343.01 71.47 341.46 73.23C339.94 74.97 337.97 76.33 335.55 77.3C333.15 78.27 330.37 78.75 327.22 78.75Z\"/></svg>";
+/** Mark alone (shown in the FAB and compact toolbar). */
+export declare const MARK_SVG: string;
+/** FAB-sized mark for the collapsed circular control. */
+export declare const FAB_MARK_SVG: string;
+/** Mark + "reticle" lettering (legacy wordmark artwork). */
+export declare const WORDMARK_SVG: string;
+/** Compact text label beside the mark in the expanded toolbar. */
+export declare const BRAND_MINI_CLASS = "reticle-brand-mini";
+/** Toolbar brand: mark + Reticle word (always shown together when expanded). */
+export declare const TOOLBAR_BRAND_HTML: string;
 /**
  * Header brand block. Both marks are always in the DOM and CSS picks one off the collapsed
  * attribute, so there is no JS state to keep in sync. The artwork is decorative (aria-hidden);
  * the visually-hidden name is what keeps the HUD identifiable to a screen reader in BOTH states.
  */
-export declare const BRAND_HTML = "<span class=\"reticle-brand\"><svg class=\"reticle-mark\" viewBox=\"0 0 96 94\" fill=\"currentColor\" aria-hidden=\"true\"><path d=\"M92.82 92.16C93.07 93.4 91.77 94.4 90.63 93.83C89.62 93.33 88.62 92.82 87.63 92.3C71.14 83.78 54.79 72.27 39.61 57.96C39.09 57.49 38.57 56.98 38.06 56.49C22.45 41.52 9.78 25.14 .33 8.52C0.29 8.45 .25 8.38 .2 8.31C-0.44 7.2 .51 5.84 1.79 6.05L24.07 9.71C43.06 12.83 60.63 11.75 75.55 6.53L93.95 .09C95.15-0.33 96.31 .78 95.93 1.98L90.1 20.49C85.37 35.48 84.9 52.97 88.69 71.73L92.83 92.16H92.82Z\"/><path d=\"M58.72 89.23L6.15 92.8C5.24 92.86 4.48 92.13 4.51 91.22L6.56 30.39C6.61 28.91 8.51 28.36 9.35 29.57C16.23 39.43 24.98 52.35 33.01 61.26C41.05 70.17 50.6 78.72 59.62 86.56C60.65 87.45 60.08 89.13 58.72 89.23Z\"/></svg><svg class=\"reticle-wordmark\" viewBox=\"0 0 347 96\" fill=\"currentColor\" aria-hidden=\"true\"><g transform=\"translate(1 1)\"><path d=\"M92.82 92.16C93.07 93.4 91.77 94.4 90.63 93.83C89.62 93.33 88.62 92.82 87.63 92.3C71.14 83.78 54.79 72.27 39.61 57.96C39.09 57.49 38.57 56.98 38.06 56.49C22.45 41.52 9.78 25.14 .33 8.52C0.29 8.45 .25 8.38 .2 8.31C-0.44 7.2 .51 5.84 1.79 6.05L24.07 9.71C43.06 12.83 60.63 11.75 75.55 6.53L93.95 .09C95.15-0.33 96.31 .78 95.93 1.98L90.1 20.49C85.37 35.48 84.9 52.97 88.69 71.73L92.83 92.16H92.82Z\"/><path d=\"M58.72 89.23L6.15 92.8C5.24 92.86 4.48 92.13 4.51 91.22L6.56 30.39C6.61 28.91 8.51 28.36 9.35 29.57C16.23 39.43 24.98 52.35 33.01 61.26C41.05 70.17 50.6 78.72 59.62 86.56C60.65 87.45 60.08 89.13 58.72 89.23Z\"/></g><path d=\"M116.43 78V27.09H136.51C140.35 27.09 143.64 27.78 146.35 29.15C149.09 30.51 151.17 32.44 152.59 34.95C154.04 37.43 154.76 40.36 154.76 43.72C154.76 47.1 154.03 50.01 152.57 52.45C151.11 54.87 149 56.72 146.23 58.01C143.48 59.31 140.15 59.95 136.24 59.95H122.79V51.3H134.5C136.55 51.3 138.26 51.02 139.62 50.46C140.98 49.89 141.99 49.05 142.65 47.92C143.33 46.8 143.67 45.39 143.67 43.72C143.67 42.03 143.33 40.61 142.65 39.45C141.99 38.29 140.97 37.41 139.59 36.81C138.23 36.2 136.52 35.89 134.45 35.89H127.19V78H116.43ZM143.92 54.83L156.57 78H144.69L132.31 54.83H143.92ZM178.95 78.75C175.02 78.75 171.64 77.95 168.81 76.36C165.99 74.75 163.82 72.48 162.29 69.55C160.77 66.6 160.01 63.11 160.01 59.08C160.01 55.16 160.77 51.71 162.29 48.74C163.82 45.78 165.97 43.46 168.73 41.81C171.52 40.15 174.78 39.32 178.53 39.32C181.05 39.32 183.39 39.73 185.56 40.54C187.75 41.33 189.65 42.54 191.28 44.14C192.92 45.75 194.2 47.77 195.11 50.21C196.02 52.63 196.47 55.46 196.47 58.71V61.62H164.23V55.06H186.51C186.51 53.53 186.17 52.18 185.51 51C184.85 49.83 183.93 48.91 182.75 48.25C181.59 47.57 180.24 47.23 178.7 47.23C177.09 47.23 175.67 47.6 174.43 48.34C173.2 49.07 172.24 50.06 171.54 51.3C170.85 52.53 170.49 53.9 170.47 55.4V61.64C170.47 63.53 170.82 65.17 171.52 66.54C172.23 67.92 173.23 68.98 174.52 69.72C175.82 70.47 177.35 70.84 179.12 70.84C180.3 70.84 181.38 70.68 182.35 70.34C183.33 70.01 184.17 69.52 184.87 68.85C185.56 68.19 186.09 67.38 186.46 66.42L196.25 67.06C195.75 69.42 194.73 71.47 193.19 73.23C191.67 74.97 189.7 76.33 187.28 77.3C184.87 78.27 182.1 78.75 178.95 78.75ZM223.69 39.82V47.77H200.7V39.82H223.69ZM205.92 30.67H216.51V66.27C216.51 67.24 216.66 68.01 216.96 68.55C217.26 69.08 217.67 69.46 218.2 69.67C218.75 69.89 219.38 70 220.09 70C220.59 70 221.08 69.95 221.58 69.87C222.08 69.77 222.46 69.7 222.72 69.65L224.39 77.53C223.86 77.69 223.11 77.88 222.15 78.1C221.19 78.33 220.02 78.47 218.65 78.52C216.1 78.62 213.86 78.28 211.94 77.5C210.03 76.72 208.55 75.51 207.49 73.87C206.43 72.23 205.9 70.16 205.92 67.66V30.67ZM230.59 78V39.82H241.18V78H230.59ZM235.91 34.9C234.34 34.9 232.99 34.37 231.86 33.33C230.75 32.27 230.19 31 230.19 29.53C230.19 28.07 230.75 26.82 231.86 25.77C232.99 24.71 234.34 24.18 235.91 24.18C237.49 24.18 238.83 24.71 239.94 25.77C241.07 26.82 241.63 28.07 241.63 29.53C241.63 31 241.07 32.27 239.94 33.33C238.83 34.37 237.49 34.9 235.91 34.9ZM266.92 78.75C263 78.75 259.64 77.92 256.82 76.26C254.02 74.59 251.87 72.27 250.36 69.3C248.87 66.33 248.12 62.92 248.12 59.06C248.12 55.15 248.88 51.72 250.38 48.77C251.91 45.8 254.07 43.49 256.87 41.83C259.67 40.16 263 39.32 266.87 39.32C270.2 39.32 273.11 39.93 275.62 41.14C278.12 42.35 280.1 44.04 281.56 46.23C283.01 48.42 283.82 50.99 283.97 53.94H273.97C273.69 52.03 272.95 50.5 271.74 49.34C270.54 48.16 268.98 47.57 267.04 47.57C265.4 47.57 263.96 48.02 262.74 48.92C261.53 49.79 260.58 51.08 259.9 52.77C259.23 54.46 258.89 56.51 258.89 58.91C258.89 61.35 259.22 63.42 259.88 65.12C260.56 66.83 261.51 68.13 262.74 69.03C263.96 69.92 265.4 70.37 267.04 70.37C268.25 70.37 269.33 70.12 270.3 69.62C271.27 69.13 272.08 68.4 272.71 67.46C273.35 66.5 273.78 65.35 273.97 64.01H283.97C283.8 66.92 283.01 69.49 281.58 71.71C280.17 73.92 278.23 75.64 275.74 76.88C273.25 78.12 270.31 78.75 266.92 78.75ZM301.34 27.09V78H290.75V27.09H301.34ZM327.22 78.75C323.29 78.75 319.91 77.95 317.08 76.36C314.26 74.75 312.09 72.48 310.57 69.55C309.04 66.6 308.28 63.11 308.28 59.08C308.28 55.16 309.04 51.71 310.57 48.74C312.09 45.78 314.24 43.46 317 41.81C319.79 40.15 323.05 39.32 326.8 39.32C329.32 39.32 331.66 39.73 333.83 40.54C336.02 41.33 337.93 42.54 339.55 44.14C341.19 45.75 342.47 47.77 343.38 50.21C344.29 52.63 344.75 55.46 344.75 58.71V61.62H312.5V55.06H334.78C334.78 53.53 334.45 52.18 333.78 51C333.12 49.83 332.2 48.91 331.02 48.25C329.86 47.57 328.51 47.23 326.97 47.23C325.36 47.23 323.94 47.6 322.7 48.34C321.47 49.07 320.51 50.06 319.81 51.3C319.12 52.53 318.76 53.9 318.74 55.4V61.64C318.74 63.53 319.09 65.17 319.79 66.54C320.5 67.92 321.5 68.98 322.8 69.72C324.09 70.47 325.62 70.84 327.39 70.84C328.57 70.84 329.65 70.68 330.63 70.34C331.6 70.01 332.44 69.52 333.14 68.85C333.83 68.19 334.36 67.38 334.73 66.42L344.52 67.06C344.02 69.42 343.01 71.47 341.46 73.23C339.94 74.97 337.97 76.33 335.55 77.3C333.15 78.27 330.37 78.75 327.22 78.75Z\"/></svg><span class=\"reticle-brand-sr\">Reticle</span></span>";
+export declare const BRAND_HTML: string;
+/** Collapsed FAB control - Reticle mark only. */
+export declare const FAB_TOGGLE_HTML: string;