@reticlehq/browser 2.13.0 → 2.14.0

package/dist/reticle.js

@@ -7,7 +7,7 @@ import { Transport } from './transport/transport.js';
 import { unreachableMessage } from './transport/unreachable-message.js';
 import { adapterNames } from './registry/adapters.js';
 import { registerCapabilities, setCapabilitiesListener, hasCapabilities, } from './registry/capabilities.js';
-import { installAllObservers } from './observers/install-all.js';
+import { installAllObservers, runTeardowns } from './observers/install-all.js';
 import { installOverlay } from './presenter/overlay.js';
 import { Presenter, LOG_KIND, LOG_RESULT, } from './presenter/presenter.js';
 import { getPresenterSettings } from './presenter/presenter-settings.js';
@@ -17,18 +17,10 @@ import { resetClock } from './timers/clock.js';
 import { nativeWarn } from './timers/native-console.js';
 import { installRecorder } from './recorder/recorder.js';
 import { Annotator } from './review/annotator.js';
-/**
- * Runtime backstop for the dev-only SDK: block connecting when the build reports production, unless
- * explicitly overridden. Pure so it's testable; connect reads NODE_ENV safely (process may be absent
- * in a raw browser). This is defense-in-depth - the primary guard is the consumer gating the import
- * behind `import.meta.env.DEV` so the SDK is dead-code-eliminated from prod bundles entirely.
- */
 export function shouldBlockProduction(nodeEnv, allowInProduction) {
     return 'production' === nodeEnv && !allowInProduction;
 }
-export function connectionPolicy(pageHostname, bridgeUrl, allowNonLocalhost, token, 
-/** The page's protocol. Desktop webviews (file:, app:, tauri:) are local despite a non-loopback host. */
-pageProtocol = 'http:') {
+export function connectionPolicy(pageHostname, bridgeUrl, allowNonLocalhost, token, pageProtocol = 'http:') {
     let bridge;
     try {
         bridge = new URL(bridgeUrl);
@@ -63,19 +55,11 @@ pageProtocol = 'http:') {
     }
     return { allowed: true };
 }
-/** HUD summary when the SDK self-ends a session because the bridge (server/agent) became unreachable. */
 const BRIDGE_LOST_SUMMARY = 'Session ended - lost connection to Reticle (the agent is no longer running).';
-/**
- * Resolve the session label. An absent label or the `auto` sentinel yields a fresh per-tab id (via
- * the injected generator) so multi-tab / new-tab routes never collide; any other label is used
- * verbatim so tabs can intentionally share a session. `gen` is injected to keep this clock-free.
- */
 export function resolveSessionLabel(option, gen) {
     return option === undefined || option === SESSION_AUTO ? gen() : option;
 }
-// Re-exported from the protocol (the wire contract) so callers/tests can import it from the SDK too.
 export { RETICLE_URL_PARAM };
-/** Remove the `_reticle_reload` cache-buster a hard REFRESH left behind, via a native replaceState. */
 function stripReloadCacheBustParam() {
     try {
         const current = new URL(window.location.href);
@@ -85,13 +69,8 @@ function stripReloadCacheBustParam() {
         window.history.replaceState(window.history.state, '', current.toString());
     }
     catch {
-        /* best-effort URL hygiene - never block connect() on it */
     }
 }
-/**
- * Extract Reticle identity overrides from a `location.search` string. Pure (takes the string, not the
- * window) so it's testable without a DOM. Explicit connect options still win over these.
- */
 export function reticleParamsFromSearch(search) {
     const params = new URLSearchParams(search);
     const out = {};
@@ -103,12 +82,6 @@ export function reticleParamsFromSearch(search) {
         out.projectId = projectId;
     return out;
 }
-/**
- * Resolve the session + project identity for a connection: an explicit, non-`auto` option wins;
- * otherwise a launcher-stamped URL param is used; otherwise undefined (caller generates a per-tab id).
- * Crucially `auto` is treated like "unset" so an app that passes the auto sentinel still lets a pooled
- * launcher correlate the lease via __reticle_session. Pure for testability.
- */
 export function resolveConnectIdentity(options, search) {
     const url = reticleParamsFromSearch(search);
     const explicitSession = options.session !== undefined && options.session !== SESSION_AUTO ? options.session : undefined;
@@ -118,11 +91,6 @@ export function resolveConnectIdentity(options, search) {
         projectId: projectId !== undefined && projectId.length > 0 ? projectId : undefined,
     };
 }
-/**
- * Assemble an event envelope. Pure: `seq` (monotonic per session) and `t` (elapsed clock) are
- * injected, never read here - so it is unit-testable and honors the clock-injection rule. The
- * causing action's id is attributed server-side by the settle window, so it is not stamped here.
- */
 export function buildEvent(args) {
     return {
         t: args.t,
@@ -130,34 +98,17 @@ export function buildEvent(args) {
         type: args.type,
         sessionId: args.sessionId,
         ref: args.ref,
-        // Which document this was observed under, so the server can refuse evidence minted before a
-        // navigation replaced the page. Stamped HERE because it is the one place every event passes
-        // through: an observer added later would otherwise emit unstamped events, which read as
-        // "current" by design and would reintroduce the defect silently for one event type.
         documentId: args.documentId,
-        // Which round of source edits this was observed under. Stamped HERE for exactly the reason
-        // documentId is, and omitted while nothing has hot-updated: absence already reads as "current"
-        // downstream, so `NO_EDITS_OBSERVED` on the wire would be bytes spent saying "unknown".
         editEpoch: NO_EDITS_OBSERVED === args.editEpoch ? undefined : args.editEpoch,
         data: args.data,
     };
 }
-/**
- * The browser-side orchestrator. Wires observers -> events -> bridge, and bridge
- * commands -> handlers. Embedded in the host app (dev only).
- */
 export class Reticle {
     #transport;
     #registry = new Map();
     #teardowns = [];
     #connected = false;
     #session = 'default';
-    /**
-     * Minted once, here, because this class is constructed once per document: a full navigation tears
-     * down the JavaScript context and builds a new one, so the id dies with the document it names. An
-     * SPA route change does not reconstruct it, which is correct — same context, same in-flight
-     * requests, same evidence.
-     */
     #documentId = newDocumentId(Math.random);
     #start = 0;
     #overlay;
@@ -167,18 +118,16 @@ export class Reticle {
     #eventCount = 0;
     #token;
     #sdkVersion;
+    #captureBodies = false;
+    #sourceMapping = undefined;
     #projectId;
-    /** App-declared extra redaction keys, announced in hello so the driven path honours them too. */
     #redactKeys = [];
-    /** Act-row log handle for the in-flight act/act_sequence, so its outcome stamps the right row. */
     #actHandle;
     connect(options = {}) {
         if (this.#connected)
             return;
         if ('undefined' === typeof window || 'undefined' === typeof document)
             return;
-        // Dev-only backstop: refuse to activate in a production build (SSR healthcheck, prod bundle opened
-        // on localhost). `process` may not exist in a raw browser, so read NODE_ENV off globalThis.
         const proc = globalThis.process;
         const nodeEnv = proc?.env?.['NODE_ENV'];
         if (shouldBlockProduction(nodeEnv, true === options.allowInProduction)) {
@@ -186,9 +135,6 @@ export class Reticle {
                 'import.meta.env.DEV, or pass allowInProduction:true to override.');
             return;
         }
-        // A `hard` REFRESH left a cache-busting `_reticle_reload=<nonce>` in the address bar. Strip it now
-        // (before the route observer installs, so it emits no spurious ROUTE_CHANGE) - otherwise every hard
-        // reload permanently pollutes the URL the app and the agent see.
         stripReloadCacheBustParam();
         const url = options.url ?? bridgeWsUrl(RETICLE_DEFAULT_PORT);
         const policy = connectionPolicy(window.location.hostname, url, true === options.allowNonLocalhost, options.token, window.location.protocol);
@@ -196,24 +142,15 @@ export class Reticle {
             globalThis.console.warn(`[Reticle] ${policy.reason ?? 'connection blocked'}`);
             return;
         }
-        // Publish the project root for the adapters' source relativisation. Done HERE, in library code,
-        // so the app-side connect stays plain JavaScript - see ReticleConnectOptions.root.
         if (options.root !== undefined && options.root.length > 0) {
             globalThis[RETICLE_ROOT_GLOBAL] = options.root;
         }
-        // The build plugin defines this; a hand-wired connect can pass it explicitly. Either way an
-        // absent value means UNKNOWN, so the bridge never reports an unknown pair as in sync.
         const declaredVersion = options.sdkVersion ?? globalThis[RETICLE_SDK_VERSION_GLOBAL];
         this.#sdkVersion =
             'string' === typeof declaredVersion && declaredVersion.length > 0
                 ? declaredVersion
                 : undefined;
-        // A pooled/headless launcher can stamp identity via namespaced URL params; explicit (non-auto)
-        // options win, but the `auto` sentinel defers to the URL param so leases correlate.
         const identity = resolveConnectIdentity(options, window.location.search);
-        // Remembered per TAB, so a reload rejoins the same session instead of appearing as a new one and
-        // stranding the agent's handle - see session-continuity. An explicit id (connect option, or the
-        // lease's URL param) still wins.
         const explicitSession = resolveSessionLabel(identity.session, () => '');
         this.#session = rememberSessionLabel(explicitSession.length > 0 ? explicitSession : undefined, 'undefined' === typeof globalThis.sessionStorage ? undefined : globalThis.sessionStorage, () => 'function' === typeof globalThis.crypto?.randomUUID
             ? `s${globalThis.crypto.randomUUID()}`
@@ -221,9 +158,6 @@ export class Reticle {
         this.#token =
             options.token !== undefined && options.token.length > 0 ? options.token : undefined;
         this.#projectId = identity.projectId;
-        // Install the redaction rule BEFORE anything can emit. Every observer, the serializer and the
-        // snapshot path read it ambiently, so a policy set even one line after installAllObservers would
-        // leave the first events of the session redacted by a different rule than the rest.
         this.#applyRedaction(options.redact);
         this.#start = performance.now();
         this.#registry = createCommandRegistry();
@@ -231,42 +165,29 @@ export class Reticle {
             url,
             hello: () => this.#hello(),
             handleCommand: (command) => this.#handleCommand(command),
-            // Show the presenter HUD as soon as the agent bridge connects - the user immediately sees
-            // the glow border and narration panel, even before the first tool call lands.
             onConnected: () => this.#presenter?.sessionStart(),
-            // Liveness fallback: if the bridge stays unreachable (the agent killed the server process),
-            // no server-pushed end can arrive - so end the run we're presenting ourselves. A returning
-            // agent revives it via the normal sessionStart path on its next command.
             onConnectionLost: () => {
-                // Restore real timers. A frozen clock is driven by the agent through the bridge; once the
-                // bridge is gone nothing can ever advance it, so leaving it installed pins Date.now and
-                // queues every setTimeout into a scheduler that will never run. Concretely that kills every
-                // lodash debounce/throttle in the app (now - lastCall stays 0), so search boxes, autosave
-                // and resize handlers stop firing until a reload - with nothing on screen explaining why.
                 resetClock();
                 if (true === this.#presenter?.sessionActive) {
                     this.#presenter.setState(SessionState.ENDED, BRIDGE_LOST_SUMMARY);
                 }
             },
-            // First-connect never succeeded ⇒ this page's socket is not opening at this URL. Say what the
-            // page observed rather than guessing at the daemon, which it cannot see from in here.
             onUnreachable: ({ url: tried, attempts }) => {
                 nativeWarn(unreachableMessage(tried, attempts));
-                // And on screen, not only in a console nobody has open. An instrumented page with a dead
-                // bridge looked exactly like a page with no Reticle in it, so the user could not tell a
-                // daemon they forgot to start from an install that did not work.
                 this.#presenter?.showUnreachable(tried, attempts);
             },
         });
-        // Capabilities registered AFTER connect (which is when they are registered, by design) must
-        // reach the bridge, or an app that declared its whole testable surface reads as having none.
         setCapabilitiesListener(() => this.#transport?.reannounce());
-        // Contributors only, and reported in capabilities so a verdict drawn with it open is never
-        // mistaken for an ordinary one. See connect-options.ts.
         setPresenterVisible(true === options.exposePresenter);
         const emit = this.#emit;
+        this.#captureBodies = true === options.captureNetworkBodies;
+        this.#sourceMapping =
+            'boolean' === typeof options.sourceMapping ? options.sourceMapping : undefined;
         this.#teardowns = installAllObservers(emit, {
-            captureBodies: true === options.captureNetworkBodies,
+            captureBodies: this.#captureBodies,
+            ...(options.captureErrorBodies === undefined
+                ? {}
+                : { captureErrorBodies: options.captureErrorBodies }),
         });
         if (true === options.overlay) {
             this.#overlay = installOverlay();
@@ -288,21 +209,16 @@ export class Reticle {
             if (options.idleEndMs !== undefined)
                 presenterOptions.idleEndMs = options.idleEndMs;
             presenterOptions.sessionId = this.#session;
-            // The panel calls this when the human pauses/resumes/ends or sends a message. We emit a
-            // HUMAN_CONTROL event over the existing transport; #emit stamps `t` from the elapsed clock.
             presenterOptions.onControl = (intent) => this.#emit(EventType.HUMAN_CONTROL, intent.text !== undefined
                 ? { kind: intent.kind, text: intent.text }
                 : { kind: intent.kind });
             this.#presenter = new Presenter(presenterOptions);
-            // Mount the overlay. The session (glow + HUD) activates on bridge connect via onConnected,
-            // so the presenter is visible as soon as the agent is reachable - not just on first command.
             this.#presenter.mount();
         }
         if (true === options.recorder) {
             this.#recorder = installRecorder({ emit, now: () => Date.now() });
             this.#recorder.mount();
         }
-        // The page annotator rides with the presenter (the human surface) unless explicitly off.
         if (options.annotate ?? options.present !== false) {
             const presenter = this.#presenter;
             this.#annotator = new Annotator({
@@ -317,65 +233,45 @@ export class Reticle {
         this.#transport.connect();
         this.#connected = true;
     }
-    /** Whether the in-page SDK is connected to the bridge (read by createReticleEmitter, P5a). */
     get connected() {
         return this.#connected;
     }
-    /** Surface an arbitrary app-domain observation the DOM can't express. */
     signal(name, data = {}) {
         this.#emit(EventType.SIGNAL, { name, data });
     }
-    /** Report a framework/store state change the agent can observe and assert on. */
     state(name, value) {
         this.#emit(EventType.STATE_CHANGE, { name, value });
     }
-    /**
-     * Report an aggregated count of React commits (the @reticlehq/react render meter calls this on a
-     * throttle). Emits a single RENDER_COMMIT event per window so commit storms are observable without a
-     * per-render flood. Dev-only, like the whole SDK.
-     */
     renderCommit(commits) {
         if (commits > 0)
             this.#emit(EventType.RENDER_COMMIT, { commits });
     }
-    /** Advertise the app's testable surface so the agent learns it without reading source. */
     describe(input) {
-        registerCapabilities(input); // the registry notifies the transport - see setCapabilitiesListener
+        registerCapabilities(input);
     }
-    /** Live-control: end the session programmatically from the host app (drives the panel to ended). */
     endSession() {
         this.#presenter?.setState(SessionState.ENDED);
     }
-    /**
-     * Hand the SDK the page's hot-update channel, so a stale ref can say the code changed underneath it.
-     *
-     * `unknown` on purpose: the only caller that has one is the build integration, the shape it passes
-     * is Vite's `import.meta.hot`, and the SDK must not depend on Vite — it ships to Next, Electron,
-     * Tauri and plain pages. Anything that is not a subscribable channel is ignored, which is the
-     * normal case: with no channel the epoch stays at `NO_EDITS_OBSERVED`, meaning "no edits OBSERVED",
-     * never "no edits happened".
-     */
     observeHotUpdates(hot) {
         editEpoch.observe(hot);
     }
     disconnect() {
         if (!this.#connected)
             return;
-        for (const teardown of this.#teardowns)
-            teardown();
+        runTeardowns(this.#emit, this.#teardowns);
         this.#teardowns = [];
         this.#transport?.close();
         this.#transport = undefined;
         this.#overlay?.destroy();
         this.#overlay = undefined;
-        this.#presenter?.sessionEnd(); // fade the border out before tearing the overlay down
+        this.#presenter?.sessionEnd();
         this.#presenter?.destroy();
         this.#presenter = undefined;
         this.#recorder?.destroy();
         this.#recorder = undefined;
         this.#annotator?.destroy();
         this.#annotator = undefined;
-        resetClock(); // restore any frozen timers
+        resetClock();
         this.#connected = false;
     }
     #emit = (type, data, ref) => {
@@ -389,29 +285,16 @@ export class Reticle {
             data,
             ref,
         });
-        // Guarded because #emit runs INLINE IN THE APP'S CALL STACK: every monkey-patch calls it from
-        // inside the function it replaced. An exception here does not surface as an SDK error - it
-        // propagates out of history.pushState (crashing a router's navigate), out of localStorage.setItem
-        // after the write already succeeded, or out of console.log before the message reaches the console.
-        // A dev-only observability SDK must never be able to break the app it is observing.
         try {
             this.#transport?.sendEvent(event);
             this.#eventCount += 1;
             this.#overlay?.update({ connected: true, events: this.#eventCount });
-            // On a route change, re-scope the HUD's replay-flow chips to the page we're now on.
             if (type === EventType.ROUTE_CHANGE)
                 this.#presenter?.refilterFlows();
         }
         catch {
-            /* observation is best-effort; the host app's control flow is not */
         }
     };
-    /**
-     * Resolve the app's redaction config into the ambient policy, and remember the part of it that
-     * travels. A config of `undefined` is not "no policy" - it is the DEFAULT policy, installed
-     * explicitly so a second connect() in the same page (HMR, a re-mount) cannot inherit a rule the
-     * previous one set.
-     */
     #applyRedaction(config) {
         setActiveRedactionPolicy(buildRedactionPolicy(config, nativeWarn));
         this.#redactKeys = wireRedactionKeys(config);
@@ -427,31 +310,25 @@ export class Reticle {
             adapters: adapterNames(),
             ...(this.#token === undefined ? {} : { token: this.#token }),
             hasCapabilities: hasCapabilities(),
-            // Absent when no build plugin supplied one - "unknown", never "matching".
+            captureBodies: this.#captureBodies,
+            ...(this.#sourceMapping === undefined ? {} : { sourceMapping: this.#sourceMapping }),
             ...(this.#sdkVersion === undefined ? {} : { sdkVersion: this.#sdkVersion }),
-            // Always present: derived from THIS build's core, so it needs no build plugin to supply it.
-            // It is the half of the skew check that works on a hand-wired connect.
             contract: CONTRACT_FINGERPRINT,
             ...(0 === this.#redactKeys.length ? {} : { redactKeys: this.#redactKeys }),
         };
     }
     async #handleCommand(command) {
-        // NARRATE: the agent tells the human what it's about to do / decide (presenter HUD).
         if (command.name === ReticleCommand.NARRATE) {
-            this.#presenter?.sessionStart(); // first agent activity → reveal the glow + panel
+            this.#presenter?.sessionStart();
             this.#presenter?.narrate(str(command.args['text']), str(command.args['level'], 'info'));
             return { ok: true, result: { shown: this.#presenter !== undefined } };
         }
-        // SESSION_CONFIG: the agent tunes the session for the app (currently the idle-end window).
         if (command.name === ReticleCommand.SESSION_CONFIG) {
             const idleEndMs = command.args['idleEndMs'];
             if ('number' === typeof idleEndMs)
                 this.#presenter?.setIdleEndMs(idleEndMs);
             return { ok: true, result: { applied: this.#presenter !== undefined, idleEndMs } };
         }
-        // Bridge → browser presenter pushes (PRESENTER state echo / FLOWS replay list). The presenter owns
-        // the parsing; here we only report whether a panel was mounted to apply it. setState-only, so a
-        // PRESENTER echo of a HUMAN_CONTROL can't loop back into a re-emit.
         if (command.name === ReticleCommand.PRESENTER ||
             command.name === ReticleCommand.FLOWS ||
             command.name === ReticleCommand.IMPACT) {
@@ -462,7 +339,7 @@ export class Reticle {
         if (handler === undefined) {
             return { ok: false, error: `unknown command '${command.name}'` };
         }
-        this.#presenter?.sessionStart(); // first agent command → reveal the glow + panel
+        this.#presenter?.sessionStart();
         await this.#presentBefore(command);
         try {
             const result = await handler(command.args);
@@ -478,12 +355,11 @@ export class Reticle {
             this.#presenter?.scheduleIdle();
         }
     }
-    /** Drive the presenter (cursor/effects/status) before the real action runs. */
     async #presentBefore(command) {
         const p = this.#presenter;
         if (p === undefined)
             return;
-        p.setMode(modeForCommand(command.name)); // paint reading vs acting intent first
+        p.setMode(modeForCommand(command.name));
         this.#actHandle = undefined;
         if (command.name === ReticleCommand.ACT) {
             const ref = str(command.args['ref']);
@@ -497,7 +373,6 @@ export class Reticle {
                 const s = step;
                 const ref = str(s.ref);
                 const label = refLabel(ref);
-                // one log row per step; the last handle carries the sequence outcome glyph
                 this.#actHandle = p.log(LOG_KIND.ACT, `${actionVerb(str(s.action))} ${label}`);
                 await p.beforeAct(ref, str(s.action), label);
             }

package/dist/review/annotator-styles.js

@@ -1,17 +1,10 @@
 import { Z_OVERLAY } from '../presenter/presenter-styles.js';
-/** Markup + CSS for the in-page annotation HUD (markers, hover box, composer). */
 const MARK_ATTR = 'data-reticle-mark';
 const sel = (role) => `[${MARK_ATTR}="${role}"]`;
 export const MARK_PLACEHOLDER = 'What should change?';
 export const MARK_SUBMIT = 'Add';
 export const MARK_CANCEL = 'Cancel';
 export const MARK_PENDING_GLYPH = '+';
-/**
- * ABOVE the presenter overlay, because the overlay contains the page blocker annotate mode raises.
- * One below it, the shield painted over the composer: every click on Cancel or Add landed on the
- * blocker instead of the button, so the note could be neither saved nor dismissed. The root here is
- * pointer-events:none, so only the marks and the composer sit above the HUD - not a new shield.
- */
 const Z_MARK = Z_OVERLAY + 1;
 export const ANNOTATOR_CSS = `
 ${sel('root')}{position:fixed;inset:0;pointer-events:none;z-index:${String(Z_MARK)};}

package/dist/review/annotator.d.ts

@@ -1,19 +1,9 @@
 import { EventType } from '@reticlehq/core';
-/**
- * What the HUD is told about a mark the moment it is placed.
- *
- * The row used to get the note and the anchor's label - "generic: my feedback" - which names
- * neither the element nor which of several marks it is. The pin on the page is numbered, so the
- * row carries the same number, plus the source the anchor already resolved.
- */
-export interface MarkReport {
+interface MarkReport {
     note: string;
-    /** The anchor the agent will look the element up by, e.g. `[data-testid="deploy-submit"]`. */
     anchor: string;
     label: string;
-    /** 1-based, matching the number drawn in the pin. */
     index: number;
-    /** file:line, when the app is source-stamped. */
     source?: string;
 }
 export interface AnnotatorDeps {
@@ -34,9 +24,7 @@ export declare class Annotator {
     get active(): boolean;
     get markCount(): number;
     mount(): void;
-    /** Drive marker/highlight chrome from the HUD accent swatch. */
     setAccent(hex: string): void;
-    /** @deprecated HUD expand/collapse owns annotate mode; chrome buttons are hide/clear. */
     attachFlagButton(btn: HTMLElement): void;
     attachChrome(chrome: AnnotatorChrome): void;
     destroy(): void;
@@ -45,3 +33,4 @@ export declare class Annotator {
     syncAnchors(): void;
 }
 export declare function installAnnotator(deps: AnnotatorDeps): Annotator;
+export {};

package/dist/review/annotator.js

@@ -4,7 +4,6 @@ import { isReticleUi, isReticleOverlay } from '../dom/dom-ignore.js';
 import { resolveMarkAnchor } from './mark-anchor.js';
 import { nativeSetTimeout, nativeClearTimeout } from '../timers/native-timers.js';
 import { ANNOTATOR_CSS, ANNOTATOR_ROOT_HTML, MARK_CANCEL, MARK_PENDING_GLYPH, MARK_PLACEHOLDER, MARK_SUBMIT, } from './annotator-styles.js';
-/** The cursor must rest this long before the outline boxes the element under it - calm, not jumpy. */
 const HIGHLIGHT_REST_MS = 130;
 const SHAKE_MS = 250;
 const POP_W = 280;
@@ -85,12 +84,10 @@ export class Annotator {
         if (undefined !== this.#accent)
             this.setAccent(this.#accent);
     }
-    /** Drive marker/highlight chrome from the HUD accent swatch. */
     setAccent(hex) {
         this.#accent = hex;
         this.#root?.style.setProperty('--reticle-mark-accent', hex);
     }
-    /** @deprecated HUD expand/collapse owns annotate mode; chrome buttons are hide/clear. */
     attachFlagButton(btn) {
         this.attachChrome({ markersBtn: btn });
     }
@@ -211,18 +208,11 @@ export class Annotator {
     #handleClick(ev) {
         if (!this.#active)
             return;
-        // A click Reticle dispatched is the agent driving the app, not a person placing a mark. Without
-        // this, expanding the HUD silently disabled every `reticle_act` click while the action still
-        // reported success — a false green in our own UI. See synthetic-input.ts.
         if (isSyntheticInput())
             return;
         const raw = ev.target;
         if (!(raw instanceof Element))
             return;
-        // The page blocker is a full-viewport shield Reticle puts up WHILE annotating, so with it on
-        // every click lands on Reticle's own UI and was discarded as such — annotate mode looked
-        // completely dead, because the one thing standing between the user and the page is the thing
-        // annotate mode turns on. Resolve what is underneath instead of giving up on the click.
         const target = raw.hasAttribute(BLOCKER_ATTR_NAME)
             ? pageElementAt(ev.clientX, ev.clientY)
             : raw;
@@ -274,9 +264,6 @@ export class Annotator {
         if (this.#hi === undefined)
             return;
         const raw = ev.target;
-        // Same shield as in #handleClick: while annotating, a full-viewport blocker sits over the page,
-        // so EVERY mousemove reports it as the target. Resolving only there left the outline suppressed
-        // on every element - a crosshair with no indication of what it was on. See #handleClick.
         const target = raw instanceof Element && raw.hasAttribute(BLOCKER_ATTR_NAME)
             ? pageElementAt(ev.clientX, ev.clientY)
             : raw;
@@ -315,22 +302,11 @@ export class Annotator {
         this.#pendingKey = mark.anchor;
         this.#pendingTarget = mark.target;
         this.#hideHighlight();
-        // Where the element is NOW, not where it was when the mark was made. The popover is
-        // position:fixed, so it is placed in viewport coordinates, and the stored clientX/clientY are
-        // viewport coordinates from an earlier scroll position. Reopening a mark after scrolling put the
-        // note somewhere unrelated to the thing it annotates — further away the further you had scrolled.
         const at = this.#currentPoint(mark);
         this.#mountPopover(mark.label, at.x, at.y, mark.note);
         this.#dropPending(at.x, at.y);
         this.#paintSelection();
     }
-    /**
-     * The viewport point a mark's popover should open at.
-     *
-     * Prefers the element's live box, because that is what the note is ABOUT. Falls back to the stored
-     * coordinates only when the element is gone, where there is nothing better and the mark is already
-     * shown as stale.
-     */
     #currentPoint(mark) {
         const el = mark.target;
         if (el !== undefined && el.isConnected) {
@@ -471,7 +447,6 @@ export class Annotator {
         this.#dropPin(resolved, note, x, y);
         this.#report(note, resolved.anchor, resolved.label, this.#marks.length, sourceLabel(resolved));
     }
-    /** Hand the HUD everything it needs to name this mark in one row. */
     #report(note, anchor, label, index, source) {
         const mark = { note, anchor, label, index };
         if (source !== undefined)
@@ -560,12 +535,6 @@ export class Annotator {
         this.#repositionPopover();
         this.#paintSelection();
     }
-    /**
-     * Keep an OPEN popover attached to its element while the page scrolls.
-     *
-     * The pins were repositioned here and the popover was not, so scrolling with a note open slid the
-     * note off its target and left it floating over unrelated content.
-     */
     #repositionPopover() {
         const pop = this.#pop;
         const mark = this.#editing;
@@ -589,7 +558,6 @@ export class Annotator {
             this.#selBox.hidden = true;
     }
 }
-/** "file:line" for a resolved anchor, when the app carries source stamps. */
 function sourceLabel(resolved) {
     return resolved.source === undefined
         ? undefined
@@ -607,15 +575,7 @@ function isElementFixed(el) {
     const pos = getComputedStyle(el).position;
     return 'fixed' === pos || 'sticky' === pos;
 }
-/** The blocker Reticle raises over the page while annotating; see the click handler. */
 const BLOCKER_ATTR_NAME = 'data-reticle-blocker';
-/**
- * The topmost element of the HOST PAGE at a point, seeing past Reticle's own overlays.
- *
- * `elementsFromPoint` returns the whole stack topmost-first, so the page element is simply the first
- * entry that is not ours. Returns undefined where the API is unavailable (jsdom) or nothing but
- * Reticle UI is there, and the caller drops the click rather than guessing at a target.
- */
 function pageElementAt(x, y) {
     const from = document.elementsFromPoint.bind(document);
     if (from === undefined)

package/dist/review/mark-anchor.d.ts

@@ -1,10 +1,4 @@
 import { MarkAnchorStrategy } from '@reticlehq/core';
-/**
- * The element address carried by a human review mark: a re-resolvable anchor (auto-anchor's most
- * durable tier for this element), its durability strategy, a human-legible label, and — crucially —
- * the source file:line the agent should open. Source is reported INDEPENDENTLY of the anchor tier:
- * a role-anchored element still carries its babel-stamped source so the agent can jump to the code.
- */
 export interface MarkAnchor {
     anchor: string;
     strategy: MarkAnchorStrategy;
@@ -14,9 +8,4 @@ export interface MarkAnchor {
         line: number;
     };
 }
-/**
- * Resolve a clicked element into the address a human review mark carries. Reuses the same
- * auto-anchor machinery a recorded flow uses, so a mark pins to the element the way Reticle addresses
- * it everywhere else — and always reports the source file:line when one is available.
- */
 export declare function resolveMarkAnchor(el: Element): MarkAnchor;

package/dist/review/mark-anchor.js

@@ -3,26 +3,18 @@ import { AnchorStrategy, synthesizeAnchor } from '../dom/auto-anchor.js';
 import { getAccessibleName, getRole } from '../dom/a11y.js';
 import { identifyComponent } from '../registry/adapters.js';
 import { sourceFor } from '../dom/source.js';
-/** Attribute names — defined locally per the recorder/query convention (no shared free string). */
 const TESTID_ATTR = 'data-testid';
-/** AnchorStrategy and MarkAnchorStrategy share string values; map explicitly (no cross-cast). */
 const STRATEGY = {
     [AnchorStrategy.TESTID]: MarkAnchorStrategy.TESTID,
     [AnchorStrategy.COMPONENT]: MarkAnchorStrategy.COMPONENT,
     [AnchorStrategy.ROLE]: MarkAnchorStrategy.ROLE,
     [AnchorStrategy.POSITION]: MarkAnchorStrategy.POSITION,
 };
-/** A short, human-legible label for the element: `role "name"`, falling back to role / tag name. */
 function labelFor(el, role, name) {
     if (name.length > 0)
         return role.length > 0 ? `${role} "${name}"` : `"${name}"`;
     return role.length > 0 ? role : el.tagName.toLowerCase();
 }
-/**
- * Resolve a clicked element into the address a human review mark carries. Reuses the same
- * auto-anchor machinery a recorded flow uses, so a mark pins to the element the way Reticle addresses
- * it everywhere else — and always reports the source file:line when one is available.
- */
 export function resolveMarkAnchor(el) {
     const testid = el.getAttribute(TESTID_ATTR) ?? undefined;
     const info = identifyComponent(el);