@reticlehq/browser 2.12.0 → 2.13.1

package/dist/observers/scroll.js

@@ -5,6 +5,8 @@ const THROTTLE_MS = 100;
 const REVEAL_SELECTOR = '[data-reticle-reveal], [data-reveal], section';
 /** Observe scroll position + reveal-on-scroll for modern scroll-reactive UIs. */
 export function installScroll(emit) {
+    const ac = new AbortController();
+    const { signal } = ac;
     let lastEmit = 0;
     let lastY = 0;
     let trailingTimer;
@@ -39,7 +41,7 @@ export function installScroll(emit) {
             }, THROTTLE_MS - elapsed);
         }
     };
-    window.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('scroll', onScroll, { passive: true, signal });
     let io;
     if ('function' === typeof IntersectionObserver) {
         io = new IntersectionObserver((entries) => {
@@ -60,7 +62,7 @@ export function installScroll(emit) {
             observer.observe(el);
     }
     return () => {
-        window.removeEventListener('scroll', onScroll);
+        ac.abort();
         if (trailingTimer !== undefined)
             nativeClearTimeout(trailingTimer);
         io?.disconnect();

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

@@ -104,6 +104,15 @@ export declare const GLOW_FADE_MS = 250;
 export declare const GLOW_ON = "1";
 export declare const GLOW_OFF = "0";
 export declare const DATA_ON = "data-on";
+/** The overlay root's state attribute, which the shell styles resolve colour against. */
+export declare const STATE_ATTR = "data-reticle-state";
+/**
+ * Not a SessionState: there is no session. It is the absence of one, said out loud.
+ *
+ * Kept off `SessionState` deliberately — that enum crosses the wire, and this state exists only
+ * because nothing crossed the wire.
+ */
+export declare const UNREACHABLE_STATE = "unreachable";
 /** Overlay-root attribute toggled when the HUD is collapsed to the FAB. */
 export declare const MIN_ATTR = "data-reticle-min";
 /** Overlay-root attribute toggled when the agent chat panel is open. */
@@ -174,7 +183,7 @@ export declare const LOG_TIMESTAMPS_ATTR = "data-reticle-log-ts";
 /** When 1, HUD motion is reduced for accessibility. */
 export declare const REDUCE_MOTION_ATTR = "data-reticle-reduce-motion";
 /** Docs opened from the settings footer. */
-export declare const MCP_DOCS_URL = "https://github.com/reticlehq/reticle/blob/main/docs/getting-started.md";
+export declare const MCP_DOCS_URL: string;
 /** HUD has been dragged off the default dock - positioned with explicit left/top. */
 export declare const HUD_DRAGGED_ATTR = "data-dragged";
 /** CSS custom properties written when the HUD is dragged. */
@@ -185,5 +194,5 @@ export declare const HUD_DRAG_THRESHOLD_PX = 4;
 /** Minimum gap between a dragged HUD and the viewport edge. */
 export declare const HUD_DOCK_MARGIN_PX = 8;
 /** Interactive nodes inside the drag handle that must not start a drag (not the FAB itself). */
-export declare const HUD_DRAG_IGNORE_SEL = "[data-reticle-pause], [data-reticle-annotate-btn], [data-reticle-markers-btn], [data-reticle-clear-marks], [data-reticle-end], [data-reticle-min-btn], [data-reticle-settings-btn], [data-reticle-settings-panel], [data-reticle-report-btn], [data-reticle-report-panel], [data-reticle-chat-panel], [data-reticle-chat-toggle], [data-reticle-workspace-btn], [data-reticle-workspace-menu], [data-reticle-copy], [data-reticle-export], [data-reticle-send], input, textarea, select, a, .reticle-head-ctl, [data-reticle-tally], .reticle-maxhint";
+export declare const HUD_DRAG_IGNORE_SEL: string;
 export declare const THROTTLED_ATTR = "data-reticle-throttled";

package/dist/presenter/presenter-config.js

@@ -72,6 +72,15 @@ export const GLOW_FADE_MS = 250;
 export const GLOW_ON = '1';
 export const GLOW_OFF = '0';
 export const DATA_ON = 'data-on';
+/** The overlay root's state attribute, which the shell styles resolve colour against. */
+export const STATE_ATTR = 'data-reticle-state';
+/**
+ * Not a SessionState: there is no session. It is the absence of one, said out loud.
+ *
+ * Kept off `SessionState` deliberately — that enum crosses the wire, and this state exists only
+ * because nothing crossed the wire.
+ */
+export const UNREACHABLE_STATE = 'unreachable';
 /** Overlay-root attribute toggled when the HUD is collapsed to the FAB. */
 export const MIN_ATTR = 'data-reticle-min';
 /** Overlay-root attribute toggled when the agent chat panel is open. */

package/dist/presenter/presenter-hud-chrome.d.ts

@@ -14,4 +14,4 @@ export declare const HUD_LOG_WELL_CLASS = "reticle-hud-log-well";
  * the panel read as a container rather than as one card. It also grew and shrank with its content,
  * so the panel resized on every row; the height is fixed now and the feed scrolls inside it.
  */
-export declare const HUD_LOG_WELL_CSS = "\n.reticle-hud-log-well{\n  /* A settled height, but still allowed to shrink: pinned with flex:none it pushed the composer\n     off the bottom of the panel the moment the rest of the content grew. */\n  /* A flex column, so the feed inside actually FILLS the height: as a plain block the log was only\n     as tall as its rows, which left the empty-state line floating near the top of an otherwise\n     empty panel instead of centred in it. */\n  position:relative;display:flex;flex-direction:column;\n  flex:1 1 auto;height:210px;min-height:96px;max-height:210px;overflow:hidden;\n  contain:layout style paint;\n  margin:0 6px;border-radius:12px;background:transparent;}\n.reticle-hud-log-well > *{position:relative;z-index:1;}";
+export declare const HUD_LOG_WELL_CSS: string;

package/dist/presenter/presenter-report-copy.d.ts

@@ -32,7 +32,19 @@ export declare const REPORT_TEXT: {
     readonly TITLE: "Impact";
     readonly PROJECT: "This project";
     readonly GLOBAL: "Everything on this machine";
-    readonly HERO_DEFECTS: "defects caught before you saw them";
+    /**
+     * What `counts.failed` actually is: a verdict whose declared consequence did not hold.
+     *
+     * It used to read "defects caught before you saw them", which overclaims in the one direction a
+     * verification tool must never overclaim. A failed verdict is not proof of a defect in the app —
+     * it is equally the shape of an assertion that was wrong. Measured in the field: an agent
+     * asserted a clean console on an app with ordinary dev-mode logging, the verdict went red, and
+     * the panel reported a defect nobody had found.
+     *
+     * The honest word is what Reticle DID: it refused to pass them. That is true of the assertion
+     * error and the real bug alike, and it still reads as the tool having done its job.
+     */
+    readonly HERO_DEFECTS: "checks Reticle refused to pass";
     readonly VERDICTS: "Verdicts";
     readonly PASSED: "passed";
     readonly FAILED: "failed";
@@ -48,6 +60,23 @@ export declare const REPORT_TEXT: {
     readonly SAVED_MINUTES: "Time saved";
     readonly ESTIMATE_TAG: "estimate";
     readonly CHART: "Verdicts, last 30 days";
+    readonly DEFECTS: "What broke";
+    readonly DEFECTS_MORE: "Manage all of them on the dashboard";
+    /**
+     * What an UNLINKED user is told, and the only place the product tells them.
+     *
+     * The dashboard link renders only when `dashboardUrl` exists, which means only once a repo is
+     * already linked — so the person most likely to want one, watching this record climb on their own
+     * machine, was never told it existed. The single mention anywhere else is a daemon log line.
+     *
+     * Stated as a FACT about where the record lives, not as a pitch. It sits at the foot of a panel
+     * somebody opened on purpose, so it informs rather than interrupts, and it appears only once
+     * there is a verdict worth keeping — an offer to preserve nothing is just an advert.
+     */
+    readonly LOCAL_ONLY: "This record stops at this machine.";
+    readonly LOCAL_ONLY_ACTION: "reticle login";
+    readonly LOCAL_ONLY_TAIL: "keeps it, and lets a team see it.";
+    readonly DEFECTS_NONE: "Nothing has failed a declared consequence yet.";
     readonly EMPTY: "Nothing recorded yet. Drive the app once and this fills in.";
     readonly SHARE: "Share";
     readonly COPY: "Copy";

package/dist/presenter/presenter-report-copy.js

@@ -32,7 +32,19 @@ export const REPORT_TEXT = {
     TITLE: 'Impact',
     PROJECT: 'This project',
     GLOBAL: 'Everything on this machine',
-    HERO_DEFECTS: 'defects caught before you saw them',
+    /**
+     * What `counts.failed` actually is: a verdict whose declared consequence did not hold.
+     *
+     * It used to read "defects caught before you saw them", which overclaims in the one direction a
+     * verification tool must never overclaim. A failed verdict is not proof of a defect in the app —
+     * it is equally the shape of an assertion that was wrong. Measured in the field: an agent
+     * asserted a clean console on an app with ordinary dev-mode logging, the verdict went red, and
+     * the panel reported a defect nobody had found.
+     *
+     * The honest word is what Reticle DID: it refused to pass them. That is true of the assertion
+     * error and the real bug alike, and it still reads as the tool having done its job.
+     */
+    HERO_DEFECTS: 'checks Reticle refused to pass',
     VERDICTS: 'Verdicts',
     PASSED: 'passed',
     FAILED: 'failed',
@@ -48,6 +60,23 @@ export const REPORT_TEXT = {
     SAVED_MINUTES: 'Time saved',
     ESTIMATE_TAG: 'estimate',
     CHART: 'Verdicts, last 30 days',
+    DEFECTS: 'What broke',
+    DEFECTS_MORE: 'Manage all of them on the dashboard',
+    /**
+     * What an UNLINKED user is told, and the only place the product tells them.
+     *
+     * The dashboard link renders only when `dashboardUrl` exists, which means only once a repo is
+     * already linked — so the person most likely to want one, watching this record climb on their own
+     * machine, was never told it existed. The single mention anywhere else is a daemon log line.
+     *
+     * Stated as a FACT about where the record lives, not as a pitch. It sits at the foot of a panel
+     * somebody opened on purpose, so it informs rather than interrupts, and it appears only once
+     * there is a verdict worth keeping — an offer to preserve nothing is just an advert.
+     */
+    LOCAL_ONLY: 'This record stops at this machine.',
+    LOCAL_ONLY_ACTION: 'reticle login',
+    LOCAL_ONLY_TAIL: 'keeps it, and lets a team see it.',
+    DEFECTS_NONE: 'Nothing has failed a declared consequence yet.',
     EMPTY: 'Nothing recorded yet. Drive the app once and this fills in.',
     SHARE: 'Share',
     COPY: 'Copy',
@@ -88,7 +117,7 @@ export function buildShareText(scope, projectName) {
     const where = projectName !== undefined && projectName.length > 0 ? ` on ${projectName}` : '';
     const lines = [
         `My agent verified its own work ${String(c.verdicts)} times${where}.`,
-        `${String(c.failed)} defects caught before I looked at any of them.`,
+        `${String(c.failed)} checks it refused to pass before I looked at any of them.`,
     ];
     if (c.unknown > 0) {
         lines.push(`${String(c.unknown)} came back "unknown" - it drove the app and could not tell. That is the number I watch.`);

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

@@ -73,6 +73,30 @@ export const REPORT_CSS = `
 [${REPORT_PANEL_ATTR}] .reticle-report-basis{
   display:block;margin-top:2px;color:var(--reticle-c-active);opacity:.8;
   font-size:8.5px;letter-spacing:.06em;text-transform:uppercase;cursor:help;}
+[${REPORT_PANEL_ATTR}] .reticle-report-defects-wrap{margin-top:14px;}
+[${REPORT_PANEL_ATTR}] .reticle-report-defects{
+  display:flex;flex-direction:column;gap:6px;margin:0;padding:0;list-style:none;}
+/* A left rule rather than a card per row: ten cards in a 320px panel is a wall, and the rule keeps
+   the list scannable as a list — which is what a person is doing when they open this. */
+[${REPORT_PANEL_ATTR}] .reticle-report-defect{
+  display:flex;flex-direction:column;gap:1px;padding:4px 0 4px 8px;
+  border-left:2px solid color-mix(in srgb,#f87171 70%,transparent);}
+[${REPORT_PANEL_ATTR}] .reticle-report-defect-title{
+  font-size:11px;line-height:1.35;overflow-wrap:anywhere;}
+[${REPORT_PANEL_ATTR}] .reticle-report-defect-detail{
+  color:var(--reticle-faint);font-size:10px;line-height:1.35;overflow-wrap:anywhere;}
+[${REPORT_PANEL_ATTR}] .reticle-report-defect-source{
+  color:var(--reticle-faint);font-size:9.5px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;
+  overflow-wrap:anywhere;}
+[${REPORT_PANEL_ATTR}] .reticle-report-defects-more{
+  display:inline-block;margin-top:8px;font-size:10px;color:var(--reticle-c-active);
+  text-decoration:none;}
+[${REPORT_PANEL_ATTR}] .reticle-report-defects-more:hover{text-decoration:underline;}
+[${REPORT_PANEL_ATTR}] .reticle-report-local-only{
+  margin:14px 0 0;padding-top:10px;border-top:1px solid var(--reticle-line);
+  color:var(--reticle-faint);font-size:10px;line-height:1.45;}
+[${REPORT_PANEL_ATTR}] .reticle-report-local-only code{
+  font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--reticle-c-active);}
 [${REPORT_PANEL_ATTR}] .reticle-report-chart-wrap{margin-top:12px;}
 [${REPORT_PANEL_ATTR}] .reticle-report-section{
   display:block;margin-bottom:6px;color:var(--reticle-faint);font-size:9.5px;

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

@@ -1,6 +1,6 @@
-import type { ImpactScope, ImpactSnapshot } from '@reticlehq/core';
+import { type ImpactScope, type ImpactSnapshot } from '@reticlehq/core';
 export declare function reportPanelHtml(): string;
-export declare function reportBodyHtml(scope: ImpactScope): string;
+export declare function reportBodyHtml(scope: ImpactScope, dashboardUrl?: string): string;
 export interface ReportHost {
     /** Opened from the toolbar and from the chat, so the shell decides what else must close. */
     onBeforeOpen?: () => void;

package/dist/presenter/presenter-report.js

@@ -1,3 +1,4 @@
+import { IMPACT_DEFECT_LIMIT } from '@reticlehq/core';
 import { PresenterIcon, PRESENTER_ICON_SIZE, hiIconHtml } from './presenter-icons.js';
 import { HUD_SURFACE_CLASS } from './presenter-hud-chrome.js';
 import { REPORT_PANEL_ATTR, REPORT_ATTR, REPORT_CLOSE_ATTR } from './presenter-config.js';
@@ -67,7 +68,80 @@ function chart(scope) {
         .join('');
     return `<div class="reticle-report-chart-wrap"><span class="reticle-report-section">${REPORT_TEXT.CHART}</span><div class="reticle-report-chart">${bars}</div></div>`;
 }
-export function reportBodyHtml(scope) {
+/**
+ * Escape text that came from the app under test.
+ *
+ * A defect title is an element's accessible name or a verdict's failure reason — both of which are
+ * ultimately the CONTENT of somebody else's page, and this panel builds its DOM from an HTML string.
+ * Everything else the report renders is a number or a date; this is the first app-derived text to
+ * reach it, so the escaping arrives with it.
+ */
+function esc(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * The short list of what is currently broken.
+ *
+ * The hero number already says HOW MANY defects Reticle caught; this says WHICH ONES, which is the
+ * difference between a statistic and something a person can act on. Deliberately short: a panel in
+ * the corner of somebody's app is not a triage queue, and the link at the bottom is where the queue
+ * lives. When the project is not linked to a workspace there is no link and no nagging — the free
+ * tool is complete on its own.
+ */
+/**
+ * Whether a dashboard link is safe to render as a clickable href.
+ *
+ * The url arrives from `.reticle/cloud.json` — a file in somebody's repository, which means it is
+ * INPUT. Escaping the quotes stops it breaking out of the attribute but does nothing about the
+ * SCHEME, so `javascript:...` produced a link that ran code inside the developer's own application,
+ * from a panel Reticle injected there. Only the two schemes a dashboard can actually live on are
+ * allowed; anything else renders no link at all, which is the same state as an unlinked project and
+ * therefore already a supported one.
+ */
+function isSafeDashboardUrl(raw) {
+    try {
+        const scheme = new URL(raw).protocol;
+        return 'https:' === scheme || 'http:' === scheme;
+    }
+    catch {
+        // Not a url at all. A relative path cannot address a dashboard on another origin, so there is
+        // nothing to render and nothing lost by refusing it.
+        return false;
+    }
+}
+function defects(scope, dashboardUrl) {
+    /*
+     * Defaulted here as well as in the schema. Zod's default applies when a record is PARSED, and the
+     * snapshot reaching this panel is pushed straight from the daemon rather than round-tripped
+     * through the schema — so a record written by an older build arrives with no `defects` field at
+     * all and used to throw, taking the whole report down with it.
+     */
+    const list = (scope.defects ?? []).slice(0, IMPACT_DEFECT_LIMIT);
+    if (0 === list.length)
+        return '';
+    const rows = list
+        .map((d) => {
+        const detail = d.detail === undefined
+            ? ''
+            : `<span class="reticle-report-defect-detail">${esc(d.detail)}</span>`;
+        const source = d.source === undefined
+            ? ''
+            : `<span class="reticle-report-defect-source">${esc(d.source)}</span>`;
+        return `<li class="reticle-report-defect"><span class="reticle-report-defect-title">${esc(d.title)}</span>${detail}${source}</li>`;
+    })
+        .join('');
+    // Only claim there are more when there actually are — `counts.failed` is every defect ever, and
+    // this list is the recent tail of it.
+    const more = dashboardUrl === undefined || !isSafeDashboardUrl(dashboardUrl)
+        ? ''
+        : `<a class="reticle-report-defects-more" href="${esc(dashboardUrl)}" target="_blank" rel="noreferrer noopener">${REPORT_TEXT.DEFECTS_MORE}${scope.counts.failed > list.length ? ` (${String(scope.counts.failed)})` : ''}</a>`;
+    return `<div class="reticle-report-defects-wrap"><span class="reticle-report-section">${REPORT_TEXT.DEFECTS}</span><ul class="reticle-report-defects">${rows}</ul>${more}</div>`;
+}
+export function reportBodyHtml(scope, dashboardUrl) {
     const c = scope.counts;
     if (0 === c.calls)
         return `<p class="reticle-report-empty">${REPORT_TEXT.EMPTY}</p>`;
@@ -90,7 +164,25 @@ export function reportBodyHtml(scope) {
         card(compactNumber(scope.savings.tokens.value), REPORT_TEXT.SAVED_TOKENS, scope.savings.tokens.basis),
         card(compactDuration(scope.savings.minutes.value * 60_000), REPORT_TEXT.SAVED_MINUTES, scope.savings.minutes.basis),
     ].join('');
-    return `${streak}${hero}${verdicts}<div class="reticle-report-grid">${cards}</div>${chart(scope)}`;
+    return `${streak}${hero}${verdicts}<div class="reticle-report-grid">${cards}</div>${defects(scope, dashboardUrl)}${chart(scope)}${localOnly(scope, dashboardUrl)}`;
+}
+/**
+ * The one line an UNLINKED user is shown about the dashboard.
+ *
+ * Absent `dashboardUrl` IS the unlinked signal — it is only ever set from a repo's cloud.json — so
+ * this needs no new plumbing and cannot be wrong about the state it describes.
+ *
+ * Gated on a VERDICT, not on tool calls. Somebody who has driven the app but proved nothing has not
+ * yet received the thing this offers to preserve, and offering to keep nothing is an advert. Past
+ * that bar it is a fact about where their record lives, at the foot of a panel they opened on
+ * purpose — which is why it does not need to be dismissible.
+ */
+function localOnly(scope, dashboardUrl) {
+    if (dashboardUrl !== undefined)
+        return '';
+    if (scope.counts.verdicts <= 0)
+        return '';
+    return `<p class="reticle-report-local-only">${REPORT_TEXT.LOCAL_ONLY} <code>${REPORT_TEXT.LOCAL_ONLY_ACTION}</code> ${REPORT_TEXT.LOCAL_ONLY_TAIL}</p>`;
 }
 /** The report panel controller: scope toggle, live repaint, share + referral actions. */
 export class PresenterReport {
@@ -194,7 +286,7 @@ export class PresenterReport {
         this.#body.innerHTML =
             scope === undefined
                 ? `<p class="reticle-report-empty">${REPORT_TEXT.EMPTY}</p>`
-                : reportBodyHtml(scope);
+                : reportBodyHtml(scope, this.#snapshot?.dashboardUrl);
     }
     #openShare(url) {
         window.open(url, '_blank', 'noopener,noreferrer');

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

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;