@reticlehq/browser 2.13.1 → 2.14.0

package/dist/presenter/presenter.js

@@ -16,13 +16,8 @@ import { renderTally } from './presenter-tally.js';
 import { CONTROLS_BANNER_HTML, CONTROLS_FLOWS_HTML, CONTROLS_FOOT_HTML, ENDED_FADE_MS, ControlPanel, } from './presenter-controls.js';
 import { statusTheme, blockerHtml, getPresenterSettings, OutputDetail, syncPageBlocker, } from './presenter-settings.js';
 import { Annotator } from '../review/annotator.js';
-// Re-export the config surface so the public import path (`./presenter.js`) is unchanged.
 export { GlowPhase } from './presenter-config.js';
 export { LOG_KIND, LOG_RESULT } from './presenter-log.js';
-// Presenter / transparency layer: a human watches the agent work. Glowing border while
-// active, a synthetic cursor that flies to targets, click/hover/type effects, and a HUD that
-// shows the current action + the agent's narrated intent. All nodes carry data-reticle-* attrs
-// so they're excluded from snapshots/observers (see dom-ignore.ts).
 export class Presenter {
     #paceMs;
     #root;
@@ -32,12 +27,9 @@ export class Presenter {
     #hud;
     #actLine;
     #actStrip;
-    /** Label inside the minimised-chat capsule; mirrors the act strip. */
     #chatPillText;
-    /** Age of the last action, shown in the capsule's own slot. */
     #chatPillTime;
     #chip;
-    /** Live verdict tally (✓N ✗M) in the header - the running testing score the human watches. */
     #tally;
     #tallied = { passes: 0, fails: 0 };
     #mode = PresenterMode.IDLE;
@@ -45,25 +37,18 @@ export class Presenter {
     #heartbeatMs;
     #idleNoticeMs;
     #borderMode;
-    /** The glow / activity state machine (border shimmer + cursor visibility from activity timing). */
     #glowCtl;
-    /** Liveness: the most recent action text + a 1s ticker that ages it into an "idle · {dur}" clock. */
     #lastActionText = '';
     #heartbeatTimer;
-    /** Session lifecycle: idle-end window (tweakable), session id, start/end cursors, structured run log. */
     #idleEndMs;
     #sessionId;
     #startMs;
     #endMs;
     #runLog = [];
-    /** Tracks sessionStart/sessionEnd so both are idempotent (no strobe / no spurious off-write). */
     #sessionActive = false;
-    // v2: narration + action status accumulate in a persistent, timestamped, scrollable log.
     #logMax;
     #log;
-    /** now of the first row, the baseline for the +elapsed timestamps. */
     #logBaseMs;
-    // Live-control panel: the two-way control surface (Pause/Resume + End + message Send).
     #onControl;
     #panel;
     #shell;
@@ -110,26 +95,18 @@ export class Presenter {
             },
         });
     }
-    /** Setter so reticle.ts can wire the control callback after construction. */
     setControlHandler(handler) {
         this.#onControl = handler;
     }
-    /** Current live-control session state mirrored onto the panel (data-reticle-state). */
     get state() {
         return this.#panel.state;
     }
-    /** Whether a run is currently being presented (false before the agent's first activity / after end). */
     get sessionActive() {
         return this.#sessionActive;
     }
-    /** Drive the panel's live-control visual state (server-push / agent path; never emits). */
     setState(state, text, tone) {
         this.#panel.setState(state, text, tone);
     }
-    /** Apply a bridge→browser presenter push: PRESENTER (state echo) or FLOWS (replay list, the human's
-     * no-agent replay surface). Owns the wire parsing so the SDK dispatcher stays a thin router;
-     * setState-only so an echo can't re-emit. */
-    /** Re-scope the replay-flow chips to the current page (called by the SDK on route change). */
     refilterFlows() {
         this.#panel.refilterFlows();
     }
@@ -149,7 +126,6 @@ export class Presenter {
         if (isSessionState(state))
             this.setState(state, text, isPresenterTone(tone) ? tone : undefined);
     }
-    /** Current cap on accumulated log rows. */
     get logMax() {
         return this.#logMax;
     }
@@ -166,10 +142,6 @@ export class Presenter {
         document.head.appendChild(style);
         const root = document.createElement('div');
         root.setAttribute('data-reticle-overlay', '');
-        // 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()}
@@ -195,12 +167,10 @@ export class Presenter {
         this.#shell.mount(root);
         syncPageBlocker(root, getPresenterSettings(), false);
         this.#glowCtl.setElements(this.#glow, this.#cursor);
-        // The panel queries its refs, binds listeners, and paints the initial active state.
         this.#panel.mount(root, this.#glow);
         this.setMode(this.#mode);
         this.#renderTally();
     }
-    /** Wire annotation chrome; expanding the HUD enters annotate mode. */
     bindAnnotator(annotator) {
         this.#annotator = annotator;
         const root = this.#root;
@@ -220,12 +190,7 @@ export class Presenter {
         annotator.setAccent(statusTheme(getPresenterSettings().statusThemeId).active);
         this.#syncAnnotator();
     }
-    /** Annotate whenever the HUD is open and the person asked for it - agent or no agent. */
     #syncAnnotator() {
-        // Two things have to agree, and both are the user's: the HUD is open, and annotate is switched
-        // on. Session state used to be a third, so the mode was refused the moment the agent
-        // disconnected - which is precisely when someone opens the HUD to record what they just saw.
-        // The button still lit up, so the refusal was invisible: no outline, no composer, no reason.
         const live = !this.#shell.isCollapsed() && this.#shell.isAnnotateOn();
         this.#annotator?.toggle(live);
         if (this.#root !== undefined) {
@@ -246,19 +211,13 @@ export class Presenter {
         document.querySelectorAll('style[data-reticle-overlay]').forEach((s) => s.remove());
         this.#root = undefined;
     }
-    /**
-     * Session start: in 'session' border mode this fades the base border IN and keeps it on until
-     * sessionEnd. Idempotent, and a no-op when unmounted or in 'busy' border mode.
-     */
     sessionStart() {
-        // Returning agent activity after the session ended (idle or explicit) revives it as a fresh run.
         if (this.state === SessionState.ENDED) {
             this.#revive();
             return;
         }
         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;
@@ -271,43 +230,25 @@ 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]');
         dock?.setAttribute(DATA_ON, GLOW_ON);
         this.#hud?.setAttribute(DATA_ON, GLOW_ON);
-        // Base border persists in 'session' mode; 'busy' mode leaves it to the busy machine.
         if (this.#borderMode === BorderMode.SESSION)
             this.#glow?.setAttribute(DATA_ON, GLOW_ON);
     }
-    /** Revive after an ended session (new agent activity): clear the ended state + glow back on. */
     #revive() {
         this.#panel.setState(SessionState.ACTIVE);
         this.#endMs = undefined;
@@ -315,10 +256,6 @@ export class Presenter {
         this.#glowCtl.resetActivity(this.#now());
         this.#startHeartbeat();
     }
-    /**
-     * 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.
-     */
     sessionEnd() {
         if (!this.#sessionActive)
             return;
@@ -336,30 +273,18 @@ export class Presenter {
             this.#glow?.setAttribute(DATA_BUSY, BUSY_OFF);
         }
     }
-    /**
-     * Record agent activity. Idempotent while busy - only the first activity from idle/fading flips
-     * the glow on, so a burst never restarts the reticle-pulse animation (no strobe). Subsequent calls
-     * just refresh the last-activity timestamp and re-arm the idle check.
-     */
     markActivity() {
         this.#glowCtl.markActivity();
     }
-    /** Re-arm the quiet-window idle check (kept for reticle.ts's finally block). */
     scheduleIdle() {
         this.#glowCtl.scheduleIdle();
     }
-    /** Test/diagnostic accessor for the current glow phase. */
     glowPhase() {
         return this.#glowCtl.phase();
     }
-    /** Current intent (reading vs acting), exposed for tests + the watcher. */
     get mode() {
         return this.#mode;
     }
-    /**
-     * Set the presenter intent. READING shows a cyan scan + chip and hides the cursor; ACTING
-     * keeps the warm cursor/ripple + chip; IDLE clears the chip. Drives color via data-reticle-mode.
-     */
     setMode(mode) {
         this.#mode = mode;
         this.#root?.setAttribute('data-reticle-mode', mode);
@@ -381,7 +306,6 @@ export class Presenter {
                 this.#chip.appendChild(labelEl);
             }
         }
-        // READING has no real pointer to show (synthetic-hover pointer is native-only) - hide the cursor.
         if (mode === PresenterMode.READING)
             this.#cursor?.setAttribute(DATA_ON, GLOW_OFF);
     }
@@ -392,13 +316,6 @@ export class Presenter {
         this.#lastActionText = text;
         this.#paintActStrip(text, false);
     }
-    /**
-     * Sync act-strip text + the live/idle state.
-     *
-     * The liveness is mirrored onto the overlay root as well as the strip, because that is what the
-     * status COLOUR resolves against: the page glow, the collapsed FAB's halo and the minimised
-     * capsule all live outside the strip and still have to say whether the agent is working.
-     */
     #paintActStrip(text, idle) {
         if (this.#actLine !== undefined)
             this.#actLine.textContent = text;
@@ -407,9 +324,6 @@ export class Presenter {
             this.#actStrip.setAttribute('data-liveness', liveness);
         this.#root?.setAttribute(LIVENESS_ATTR, liveness);
         if (this.#chatPillText !== undefined) {
-            // The capsule reads "logo | what the agent did | how long ago | expand", so it takes the
-            // ACTION, never the composed "idle · 12s since last action" line the strip shows: the age
-            // lives in its own slot next to it.
             this.#chatPillText.textContent = idle
                 ? this.#lastActionText !== ''
                     ? this.#lastActionText
@@ -417,12 +331,6 @@ export class Presenter {
                 : text;
         }
     }
-    /**
-     * Liveness heartbeat (native 1s timer - never rAF, so it ticks in a foreground tab regardless of
-     * agent activity). Once the agent has been quiet for IDLE_NOTICE_MS, the act strip shows a LIVE,
-     * growing "◌ idle · {duration} since last action" - the signal that was missing when a stopped
-     * agent left the panel frozen and indistinguishable from one still thinking.
-     */
     #startHeartbeat() {
         if (this.#heartbeatTimer !== undefined)
             nativeClearTimeout(this.#heartbeatTimer);
@@ -436,20 +344,19 @@ export class Presenter {
         if (!this.#sessionActive || this.#actLine === undefined)
             return;
         if (this.state === SessionState.ENDED)
-            return; // already ended - leave the summary
+            return;
         const idleMs = this.#now() - this.#glowCtl.lastActivityMs();
         if (idleMs >= this.#idleEndMs) {
-            this.#endIdle(idleMs); // crossed the idle-end window → auto-end (glow off, panel kept)
+            this.#endIdle(idleMs);
             return;
         }
         if (idleMs < this.#idleNoticeMs)
-            return; // still active (or a brief think) - keep the action text
+            return;
         const since = this.#lastActionText !== '' ? ACT_STRIP.SINCE_LAST : '';
         this.#paintActStrip(`${ACT_STRIP.IDLE_PREFIX}${humanDuration(idleMs)}${since}`, true);
         if (this.#chatPillTime !== undefined)
             this.#chatPillTime.textContent = humanDuration(idleMs);
     }
-    /** Auto-end after the idle window: stamp the end, drive the panel to ENDED, stop the heartbeat. */
     #endIdle(idleMs) {
         this.#endMs = this.#now();
         this.#panel.setState(SessionState.ENDED, `idle ${humanDuration(idleMs)}`);
@@ -458,17 +365,11 @@ export class Presenter {
             this.#heartbeatTimer = undefined;
         }
     }
-    /** Agent-tunable idle-end window (reticle_session). Floored so it can't be set uselessly small. */
     setIdleEndMs(ms) {
         if (!Number.isFinite(ms))
             return;
         this.#idleEndMs = Math.max(IDLE_END_MIN_MS, Math.floor(ms));
     }
-    /**
-     * The exported "run state" for the Copy/Export buttons - everything the page holds about this
-     * run: session id, url, duration, capability surface, per-kind counts, and the full activity log.
-     * (The full network/console ring-buffer lives server-side; this is the in-page run summary.)
-     */
     runState() {
         const base = buildRunState({
             sessionId: this.#sessionId,
@@ -518,11 +419,6 @@ export class Presenter {
             syncPageBlocker(this.#root, settings, live);
         }
     }
-    /**
-     * Append an activity-log row. Accumulates (never overwrites): each call adds a timestamped row
-     * with a mode chip + text. Returns a handle to stamp the row's outcome glyph (✓/✗) later, or
-     * undefined when unmounted / when the text is empty after trimming.
-     */
     log(kind, text, result) {
         const ms = this.#now();
         this.#glowCtl.markActivity(ms);
@@ -532,7 +428,6 @@ export class Presenter {
         if (0 === trimmed.length)
             return undefined;
         this.#logBaseMs ??= ms;
-        // Structured run-log entry (mirrors the DOM row) for the exported run state, capped like the DOM.
         const entry = result !== undefined
             ? { at: ms - this.#logBaseMs, kind, text: trimmed, result }
             : { at: ms - this.#logBaseMs, kind, text: trimmed };
@@ -546,16 +441,14 @@ export class Presenter {
         if (this.#shell.isCollapsed())
             this.#shell.pulseFab(true);
         this.#renderTally();
-        // Wrap the handle so a later outcome stamp updates BOTH the DOM glyph and the run-log entry.
         return {
             result: (r) => {
                 handle.result(r);
                 entry.result = r;
-                this.#renderTally(); // a deferred ✓/✗ stamp bumps the header tally
+                this.#renderTally();
             },
         };
     }
-    /** Repaint the header verdict tally from the run log; the side that grew gets a one-shot pop. */
     #renderTally() {
         if (!getPresenterSettings().showTally) {
             this.#tally?.setAttribute('hidden', '');
@@ -563,7 +456,6 @@ export class Presenter {
         }
         this.#tallied = renderTally(this.#tally, this.#runLog, this.#tallied);
     }
-    /** Back-compat: narration appends to the live log (append-only, never overwrites). */
     narrate(text, level = 'info') {
         const line = 'info' === level ? text : `[${level}] ${text}`;
         return this.log(LOG_KIND.NARRATION, line);
@@ -575,11 +467,6 @@ export class Presenter {
             this.#log.firstElementChild?.remove();
         }
     }
-    /**
-     * Mirror the server's session.throttled state onto the HUD border. When throttled (tab
-     * backgrounded or stale), the border turns amber so the developer knows actions are no-oping -
-     * the same signal the agent already reads from result.session.throttled.
-     */
     setThrottled(throttled) {
         this.#root?.setAttribute(THROTTLED_ATTR, throttled ? '1' : '0');
         if (throttled && this.#actLine !== undefined) {
@@ -587,7 +474,6 @@ export class Presenter {
                 'Tab backgrounded - actions throttled. Bring tab to front or use `reticle drive`.';
         }
     }
-    /** Fly the cursor to an element, play the action's effect, then pace for the human. */
     async beforeAct(refId, action, label) {
         const el = refs.resolve(refId);
         this.status(`${actionVerb(action)} ${label}`);

package/dist/recorder/recorder-styles.d.ts

@@ -1,9 +1,3 @@
-/**
- * Inline style strings for the floating recorder toolbar. Browser-local UI
- * text (never crosses the wire), split out of recorder.ts to keep that file under the 500-line cap
- * (mirrors how presenter.ts extracts presenter-log.ts). All toolbar nodes also carry
- * data-reticle-overlay, so they are snapshot-excluded via dom-ignore.ts regardless of these styles.
- */
 export declare const TOOLBAR_CSS: string;
 export declare const BTN_CSS: string;
 export declare const NAME_CSS: string;

package/dist/recorder/recorder-styles.js

@@ -1,9 +1,3 @@
-/**
- * Inline style strings for the floating recorder toolbar. Browser-local UI
- * text (never crosses the wire), split out of recorder.ts to keep that file under the 500-line cap
- * (mirrors how presenter.ts extracts presenter-log.ts). All toolbar nodes also carry
- * data-reticle-overlay, so they are snapshot-excluded via dom-ignore.ts regardless of these styles.
- */
 export const TOOLBAR_CSS = [
     'position:fixed',
     'top:8px',

package/dist/recorder/recorder.d.ts

@@ -1,59 +1,25 @@
 import { AnnotationKind, EventType, RecorderPhase, type FlowAnchor, type FlowFile, type FlowStep } from '@reticlehq/core';
-/**
- * The human recorder. A floating toolbar (Record / Stop / Annotate) lets a
- * human click the golden path; capture-phase listeners map each real interaction to a SEMANTIC
- * anchor (testid → role+name → degraded placeholder, NEVER a volatile ref — invariant #1) and
- * append a FlowStep. Stop compiles a FlowFile in-page and emits ONE EventType.FLOW_RECORDED event
- * the server persists. Four structured annotation kinds compile into expect/dynamic/success.
- *
- * FIRST CUT scope: structured annotations only (the 4 AnnotationKind values via a menu + a signal
- * <select> drawn from registered capabilities). Explicitly FUTURE, not faked here:
- * - NL annotation → predicate compiler (CO-OWNED-FLOWS invariant #2 best-UX path).
- * - fixtures/preconditions (FlowFile.fixture stays a schema slot, never written).
- * - wait-for / ignore-region annotation kinds (only the 4 requested ship).
- */
-/** Browser-local UI text — never crosses the wire, mirrors presenter.ts CHIP_LABEL precedent. */
 export declare const RECORDER_EMPTY_MSG = "recorded 0 steps";
 interface RecorderDeps {
-    /** Emit a wire event (Reticle.#emit bound). */
     emit: (type: EventType, data: Record<string, unknown>) => void;
-    /** Injected clock for FlowFile.createdAt — never Date.now in pure logic (rule 7). */
     now: () => number;
-    /** Default flow name when the toolbar field is blank. */
     defaultName?: string;
 }
 export interface RecorderHandle {
     mount(): void;
     destroy(): void;
-    /** Test seam: current phase. */
     phase(): RecorderPhase;
-    /** Test seam: steps captured so far in the active span. */
     steps(): FlowStep[];
 }
-/** A structured annotation captured while recording (compiled into flow fields at Stop). */
 export interface Annotation {
     kind: AnnotationKind;
     anchor: FlowAnchor;
-    /** Required for ASSERT_SIGNAL / SUCCESS_STATE; the chosen capability signal name. */
     signal?: string;
 }
-/**
- * Pure: map a clicked/typed element → semantic FlowAnchor. testid wins; else role+accessible-name;
- * else the DEGRADED_ANCHOR_ROLE placeholder + degraded:true (never a ref — invariant #1).
- */
 export declare function anchorFor(el: Element): {
     anchor: FlowAnchor;
     degraded: boolean;
 };
-/**
- * Pure: assemble the in-page FlowFile from captured steps + annotations.
- * - ASSERT_SIGNAL → the most-recent step's expect.signal.
- * - ASSERT_VISIBLE → the most-recent step's expect.element (from the annotation anchor).
- * - MARK_DYNAMIC → push the anchor into flow.dynamic[].
- * - SUCCESS_STATE → flow.success = { signal }.
- * (FUTURE: per-step annotation targeting beyond the most-recent step.)
- */
 export declare function compileRecording(name: string, steps: FlowStep[], annotations: Annotation[], createdAt: number, startPath?: string): FlowFile;
-/** Install the floating recorder toolbar. Default off; gated by the host (reticle.ts recorder flag). */
 export declare function installRecorder(deps: RecorderDeps): RecorderHandle;
 export {};

package/dist/recorder/recorder.js

@@ -4,20 +4,6 @@ import { getAccessibleName, getRole, isSensitiveField } from '../dom/a11y.js';
 import { isReticleOverlay } from '../dom/dom-ignore.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { TOOLBAR_CSS, BTN_CSS, NAME_CSS, STATUS_CSS, MENU_CSS } from './recorder-styles.js';
-/**
- * The human recorder. A floating toolbar (Record / Stop / Annotate) lets a
- * human click the golden path; capture-phase listeners map each real interaction to a SEMANTIC
- * anchor (testid → role+name → degraded placeholder, NEVER a volatile ref — invariant #1) and
- * append a FlowStep. Stop compiles a FlowFile in-page and emits ONE EventType.FLOW_RECORDED event
- * the server persists. Four structured annotation kinds compile into expect/dynamic/success.
- *
- * FIRST CUT scope: structured annotations only (the 4 AnnotationKind values via a menu + a signal
- * <select> drawn from registered capabilities). Explicitly FUTURE, not faked here:
- * - NL annotation → predicate compiler (CO-OWNED-FLOWS invariant #2 best-UX path).
- * - fixtures/preconditions (FlowFile.fixture stays a schema slot, never written).
- * - wait-for / ignore-region annotation kinds (only the 4 requested ship).
- */
-/** Browser-local UI text — never crosses the wire, mirrors presenter.ts CHIP_LABEL precedent. */
 export const RECORDER_EMPTY_MSG = 'recorded 0 steps';
 const STATUS_RECORDING = 'recording…';
 const STATUS_IDLE = 'ready';
@@ -38,16 +24,11 @@ const ANNOTATION_LABEL = {
     [AnnotationKind.SUCCESS_STATE]: 'success state',
     [AnnotationKind.INTENT]: 'intent',
 };
-/** Annotation kinds whose compilation needs a signal name (from the capabilities <select>). */
 const NEEDS_SIGNAL = new Set([
     AnnotationKind.ASSERT_SIGNAL,
     AnnotationKind.SUCCESS_STATE,
 ]);
 const DEFAULT_NAME = 'recorded-flow';
-/**
- * Pure: map a clicked/typed element → semantic FlowAnchor. testid wins; else role+accessible-name;
- * else the DEGRADED_ANCHOR_ROLE placeholder + degraded:true (never a ref — invariant #1).
- */
 export function anchorFor(el) {
     const testid = el.getAttribute(TESTID_ATTR);
     if (testid !== null && testid.length > 0) {
@@ -59,7 +40,6 @@ export function anchorFor(el) {
         const anchor = name.length > 0 ? { kind: AnchorKind.ROLE, role, name } : { kind: AnchorKind.ROLE, role };
         return { anchor, degraded: false };
     }
-    // No resolvable testid/role/name — keep the step with a legible placeholder, never a ref.
     return { anchor: { kind: AnchorKind.ROLE, role: DEGRADED_ANCHOR_ROLE }, degraded: true };
 }
 function isTextbox(el) {
@@ -86,14 +66,6 @@ function buildStep(el, action, args) {
         step.degraded = true;
     return step;
 }
-/**
- * Pure: assemble the in-page FlowFile from captured steps + annotations.
- * - ASSERT_SIGNAL → the most-recent step's expect.signal.
- * - ASSERT_VISIBLE → the most-recent step's expect.element (from the annotation anchor).
- * - MARK_DYNAMIC → push the anchor into flow.dynamic[].
- * - SUCCESS_STATE → flow.success = { signal }.
- * (FUTURE: per-step annotation targeting beyond the most-recent step.)
- */
 export function compileRecording(name, steps, annotations, createdAt, startPath) {
     const out = steps.map((s) => ({ ...s }));
     const dynamic = [];
@@ -137,12 +109,10 @@ function anchorToElement(anchor) {
     }
     return {};
 }
-/** Live recorder instance: holds the capture buffer, toolbar DOM, and the phase machine. */
 class Recorder {
     #deps;
     #phase = RecorderPhase.IDLE;
     #steps = [];
-    /** The pathname the recording began on, so replay can navigate here before step 1. */
     #startPath;
     #annotations = [];
     #pendingFill;
@@ -150,7 +120,6 @@ class Recorder {
     #root;
     #statusEl;
     #menuEl;
-    /** The annotation being assembled in ANNOTATING phase. */
     #draft;
     constructor(deps) {
         this.#deps = deps;
@@ -183,7 +152,6 @@ class Recorder {
         this.#draft = undefined;
         this.#pendingFill = undefined;
     }
-    // ---- capture ----
     #installCapture() {
         const onClick = (ev) => this.#onClick(ev);
         const onInput = (ev) => this.#onInput(ev);
@@ -200,7 +168,6 @@ class Recorder {
             document.removeEventListener('submit', onSubmit, true);
         });
     }
-    /** True if the event should be ignored (toolbar self-click or non-element target). */
     #ignore(ev) {
         const target = ev.target;
         if (!(target instanceof Element))
@@ -219,9 +186,6 @@ class Recorder {
         }
         if (this.#phase !== RecorderPhase.RECORDING)
             return;
-        // Controls that emit `change` (checkbox, radio, select) are recorded by #onChange as their
-        // semantic step (CHECK/UNCHECK/SELECT). Recording a CLICK here too would replay any onChange
-        // side effect twice (analytics, dependent-field resets), so skip the duplicate.
         if ((target instanceof HTMLInputElement &&
             ('checkbox' === inputRole(target) || 'radio' === inputRole(target))) ||
             target instanceof HTMLSelectElement) {
@@ -236,7 +200,6 @@ class Recorder {
         const target = this.#ignore(ev);
         if (target === undefined || !isTextbox(target))
             return;
-        // Debounce per-keystroke input: keep the latest value, flush on change/blur/next-act.
         this.#pendingFill = { el: target, value: target.value };
     }
     #onChange(ev) {
@@ -279,12 +242,9 @@ class Recorder {
         if (pending === undefined)
             return;
         this.#pendingFill = undefined;
-        // Never persist a typed secret into a git-checked flow file: password/OTP/cc/sensitive-keyed
-        // fields record REDACTED_VALUE, the same redaction live snapshots apply (dom/a11y.ts getValue).
         const value = isSensitiveField(pending.el) ? REDACTED_VALUE : pending.value;
         this.#steps.push(buildStep(pending.el, ActionType.FILL, { value }));
     }
-    // ---- annotation ----
     #captureAnnotationTarget(target) {
         const draft = this.#draft;
         if (draft === undefined)
@@ -299,7 +259,6 @@ class Recorder {
         this.#setPhase(RecorderPhase.RECORDING);
         this.#closeMenu();
     }
-    /** Annotate-on-prior: confirm the most-recent step as the target (no extra click needed). */
     #confirmAnnotationOnPrior() {
         const draft = this.#draft;
         if (draft === undefined)
@@ -325,9 +284,7 @@ class Recorder {
         const value = select?.value ?? '';
         return value.length > 0 ? value : undefined;
     }
-    // ---- toolbar lifecycle actions ----
     #start() {
-        // A fresh span — no leakage from a previous Record→Stop cycle.
         this.#steps = [];
         this.#startPath = 'undefined' === typeof location ? undefined : location.pathname;
         this.#annotations = [];
@@ -355,7 +312,6 @@ class Recorder {
     #setPhase(phase) {
         this.#phase = phase;
     }
-    // ---- toolbar DOM (all nodes data-reticle-overlay → snapshot-excluded via dom-ignore.ts) ----
     #buildToolbar() {
         const root = document.createElement('div');
         root.setAttribute('data-reticle-overlay', '');
@@ -396,9 +352,6 @@ class Recorder {
             return;
         menu.textContent = '';
         for (const kind of Object.values(AnnotationKind)) {
-            // INTENT is free-text (the business goal), not a signal/testid pick — authored via
-            // reticle_annotate { kind:'intent', text }. The human toolbar's name field is signal/testid only,
-            // so intent is omitted from this menu rather than shipped as a control that can't capture text.
             if (kind === AnnotationKind.INTENT)
                 continue;
             const item = document.createElement('button');
@@ -426,7 +379,6 @@ class Recorder {
             }
             menu.appendChild(select);
         }
-        // "Confirm on prior step" path (annotate-on-prior); or the next click selects the target.
         const confirm = document.createElement('button');
         confirm.setAttribute('data-reticle-action', 'annotate-confirm');
         confirm.textContent = 'on prior step';
@@ -448,7 +400,6 @@ class Recorder {
         return value.length > 0 ? value : undefined;
     }
 }
-/** Install the floating recorder toolbar. Default off; gated by the host (reticle.ts recorder flag). */
 export function installRecorder(deps) {
     return new Recorder(deps);
 }

package/dist/registry/adapters.d.ts

@@ -1,4 +1,3 @@
-/** Framework adapter registry — enriches elements with component identity + source. */
 export interface ComponentSource {
     file: string;
     line: number;
@@ -11,20 +10,11 @@ export interface ComponentInfo {
 export interface ReticleAdapter {
     name: string;
     identify: (el: Element) => ComponentInfo | null;
-    /** Best-effort: read a component's hook state for a DOM element. */
     readState?: (el: Element) => unknown;
-    /** Best-effort: does the element declare framework enter/leave handlers synthetic hover may not fire? */
     hasHoverHandlers?: (el: Element) => boolean;
 }
-/** Called by @reticlehq/react (and future adapters) to register themselves. */
 export declare function registerAdapter(adapter: ReticleAdapter): void;
-/** First adapter that can identify the element wins. */
 export declare function identifyComponent(el: Element): ComponentInfo | null;
-/** First adapter that returns non-undefined component state for the element wins. */
 export declare function readComponentState(el: Element): unknown;
-/**
- * True if any installed adapter reports framework enter/leave hover handlers on the element.
- * No-op-safe: returns false when no adapter is installed or none implements the probe.
- */
 export declare function elementHasHoverHandlers(el: Element): boolean;
 export declare function adapterNames(): string[];