@reticlehq/browser 2.13.1 → 2.14.0

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

@@ -1,28 +1,19 @@
 import { PresenterReport } from './presenter-report.js';
 import { type SettingsHost } from './presenter-settings.js';
-export interface HudShellCallbacks {
+interface HudShellCallbacks {
     onChatOpen?: () => void;
     onChatClose?: () => void;
     onExpand?: () => void;
-    /** The user pressed the annotate toggle. `on` is the state they asked for. */
     onAnnotateToggle?: (on: boolean) => void;
     onCollapse?: () => void;
     settings?: SettingsHost;
 }
-/**
- * Morphing HUD shell: circular FAB ↔ icon toolbar, plus the agent chat panel above.
- * Expand enters annotation mode; the page stays clickable except for captured annotate clicks.
- */
 export declare class HudShell {
     #private;
     constructor(callbacks?: HudShellCallbacks);
-    /** Markup for the dock wrapper (chat panel + morphing HUD shell). */
     static dockHtml(actStripHtml: string, bannerHtml: string, logAttr: string, flowsHtml: string, footHtml: string): string;
-    /** The impact report, so the presenter can feed it and the chat can open it. */
     get report(): PresenterReport;
-    /** Does the user currently want to annotate? */
     isAnnotateOn(): boolean;
-    /** Set the toggle and reflect it on the button, without firing the callback. */
     setAnnotateOn(on: boolean): void;
     mount(root: HTMLElement): void;
     teardown(): void;
@@ -33,14 +24,7 @@ export declare class HudShell {
     openChat(): void;
     closeChat(): void;
     toggleChat(): void;
-    /**
-     * The chat, asked for by a PERSON - so it takes the slot from the report.
-     *
-     * `openChat` is also called by `expand`, which the agent triggers at session start; routing that
-     * through here closed the impact report every time the agent touched the app, which is precisely
-     * when you are reading it.
-     */
     showChat(): void;
-    /** Pulse the FAB when new activity arrives while collapsed. */
     pulseFab(active: boolean): void;
 }
+export {};

package/dist/presenter/presenter-shell.js

@@ -12,16 +12,10 @@ const DRAG_HANDLE_CLASS = 'reticle-toolbar-drag';
 const TRANSITION_LOCK_MS = 120;
 const ANNOTATE_LABEL = 'Annotate';
 const CHAT_MIN_LABEL = 'Minimise chat';
-/** The minimised chat capsule's label - it reopens the panel. */
 const CHAT_PILL_LABEL = 'Open agent chat';
-/** The toolbar entry to the impact report. */
 const REPORT_LABEL = 'Impact';
 const SETTINGS_LABEL = 'Settings';
 const EXIT_LABEL = 'Exit';
-/**
- * Morphing HUD shell: circular FAB ↔ icon toolbar, plus the agent chat panel above.
- * Expand enters annotation mode; the page stays clickable except for captured annotate clicks.
- */
 export class HudShell {
     #root;
     #dock;
@@ -35,32 +29,11 @@ export class HudShell {
     #transitionLock = false;
     #suppressFabClick = false;
     #annotateBtn;
-    /**
-     * Whether the USER wants to annotate. Distinct from whether annotation is currently possible,
-     * which also needs a live session and an expanded HUD — this is the half the user controls, and
-     * conflating the two is why there was no way to keep the HUD open without annotating.
-     *
-     * OFF until asked for. It began as `true` to preserve the old behaviour where expanding the HUD
-     * silently entered annotate mode, and that is exactly what made the toolbar icon look permanently
-     * lit: the toolbar is only visible while expanded, so an intent that defaults to on is on every
-     * time you can see it. Annotate mode also captures clicks, so defaulting it on means a click lands
-     * as a mark before anyone asked for one. It is a mode now, and modes are entered deliberately.
-     */
     #annotateOn = false;
     #toggleSync;
-    /**
-     * One signal for every listener this shell registers, so teardown cannot drift from mount.
-     *
-     * The click handlers below are anonymous closures over `this`: there is no reference to hand to
-     * `removeEventListener`, so before this they were never removed at all. Mounting twice onto the
-     * same root therefore stacked a second set, and every handler kept the shell reachable for as
-     * long as its element lived.
-     */
     #listeners;
     #report = new PresenterReport({
         onBeforeOpen: () => {
-            // One panel at a time in the slot above the toolbar. The chat, the settings and the report
-            // all anchor there, so opening one over another stacks two glass cards and reads as a bug.
             this.#settings.close();
             this.closeChat();
         },
@@ -71,22 +44,19 @@ export class HudShell {
         this.#settings = new PresenterSettingsPanel({
             ...callbacks.settings,
             onBeforeOpen: () => {
-                // Settings takes the slot from BOTH neighbours. Closing only the chat left the report
-                // sitting behind the settings card - two glass panels stacked in one anchor.
                 this.closeChat();
                 this.#report.close();
                 callbacks.settings?.onBeforeOpen?.();
             },
         });
     }
-    /** Markup for the dock wrapper (chat panel + morphing HUD shell). */
     static dockHtml(actStripHtml, bannerHtml, logAttr, flowsHtml, footHtml) {
         const annotate = hiToggleIconHtml(PresenterIcon.ANNOTATE, PRESENTER_ICON_SIZE.TOOLBAR);
         const chart = hiToggleIconHtml(PresenterIcon.CHART, PRESENTER_ICON_SIZE.TOOLBAR);
         const gear = hiToggleIconHtml(PresenterIcon.GEAR, PRESENTER_ICON_SIZE.TOOLBAR);
         const exit = hiIconHtml(PresenterIcon.REMOVE, PRESENTER_ICON_SIZE.TOOLBAR);
         return `<div ${DOCK_ATTR}>
-      <div ${CHAT_PANEL_ATTR} class="reticle-chat-panel ${HUD_SURFACE_CLASS}" role="dialog" aria-label="Reticle agent chat" aria-hidden="true">
+      <div ${CHAT_PANEL_ATTR} class="reticle-chat-panel ${HUD_SURFACE_CLASS}" role="region" aria-label="Reticle session" aria-hidden="true">
         <div class="reticle-chat-head">
           <span class="reticle-chat-brand">${MARK_SVG}<span class="reticle-chat-brandname">${BRAND_NAME}</span></span>
         </div>
@@ -134,11 +104,9 @@ export class HudShell {
       </div>
     </div>`;
     }
-    /** The impact report, so the presenter can feed it and the chat can open it. */
     get report() {
         return this.#report;
     }
-    /** Light exactly the toolbar buttons whose panels are open. */
     #syncToolbarToggles() {
         const root = this.#root;
         if (root === undefined)
@@ -152,11 +120,9 @@ export class HudShell {
         lit(SETTINGS_BTN_ATTR, '1' === root.getAttribute(SETTINGS_ATTR));
         lit(REPORT_BTN_ATTR, '1' === root.getAttribute(REPORT_ATTR));
     }
-    /** Does the user currently want to annotate? */
     isAnnotateOn() {
         return this.#annotateOn;
     }
-    /** Set the toggle and reflect it on the button, without firing the callback. */
     setAnnotateOn(on) {
         this.#annotateOn = on;
         this.#annotateBtn?.setAttribute('aria-pressed', on ? 'true' : 'false');
@@ -200,10 +166,6 @@ export class HudShell {
         root.removeAttribute(CHAT_ATTR);
         this.#settings.mount(root);
         this.#report.mount(root);
-        // The toolbar's lit state FOLLOWS the panels, rather than being set by whoever was clicked.
-        // Set at click time, a button stayed lit after its panel was closed by the panel that replaced
-        // it - two icons active, one panel open. The observer is the only place that can be right for
-        // every path: the toolbar, Escape, click-outside, and one panel closing another.
         this.#toggleSync = new MutationObserver(() => this.#syncToolbarToggles());
         this.#toggleSync.observe(root, {
             attributes: true,
@@ -249,13 +211,8 @@ export class HudShell {
         document.addEventListener('keydown', this.#onKeyDown, { signal });
     }
     teardown() {
-        // One call for all nine registrations. It cannot fall out of step with mount() the way a list
-        // of removeEventListener calls can, which is the whole point.
         this.#listeners?.abort();
         this.#listeners = undefined;
-        // NOT covered by the signal: a MutationObserver takes no `signal` option. This disconnect was
-        // missing entirely, so the observer kept `root` — and through it the shell — alive after
-        // teardown, and a re-mount left the previous one still firing.
         this.#toggleSync?.disconnect();
         this.#toggleSync = undefined;
         this.#dragTeardown?.();
@@ -286,12 +243,6 @@ export class HudShell {
         if (this.#fab !== undefined)
             this.#fab.setAttribute('aria-expanded', 'true');
         this.#callbacks.onExpand?.();
-        // The chat IS the HUD's content: expanding to a toolbar with nothing above it made the agent's
-        // log something you had to know to go looking for. Unconditional on purpose — the way to a bare
-        // toolbar is the chat's own minimise button, not a preference. `Auto-open chat` is a different
-        // question (should it appear with no click at all, at session start) and stays separate, because
-        // wiring expand to it made session start expand the HUD and the FAB never appeared.
-        // `openChat` re-enters `expand` only when collapsed, and MIN_ATTR is already cleared above.
         this.openChat();
         if (this.#dock !== undefined)
             scheduleSyncDockLayout(this.#dock, this.#root);
@@ -316,8 +267,6 @@ export class HudShell {
         if (this.isChatOpen())
             return;
         this.#root.setAttribute(CHAT_ATTR, '1');
-        // The panel had no layout while it was closed, so its feed could not follow the newest row.
-        // Now that it does, put it there before it is looked at.
         const log = this.#root.querySelector('[data-reticle-log]');
         if (log !== null)
             settleLogAtLatest(log);
@@ -327,10 +276,6 @@ export class HudShell {
         this.#callbacks.onChatOpen?.();
         if (this.#dock !== undefined)
             scheduleSyncDockLayout(this.#dock, this.#root);
-        const input = this.#root.querySelector('[data-reticle-input]');
-        if (input !== null && !input.disabled) {
-            requestAnimationFrame(() => input.focus());
-        }
     }
     closeChat() {
         if (this.#root === undefined || !this.isChatOpen())
@@ -349,18 +294,10 @@ export class HudShell {
         else
             this.showChat();
     }
-    /**
-     * The chat, asked for by a PERSON - so it takes the slot from the report.
-     *
-     * `openChat` is also called by `expand`, which the agent triggers at session start; routing that
-     * through here closed the impact report every time the agent touched the app, which is precisely
-     * when you are reading it.
-     */
     showChat() {
         this.#report.close();
         this.openChat();
     }
-    /** Pulse the FAB when new activity arrives while collapsed. */
     pulseFab(active) {
         this.#fab?.setAttribute('data-pulse', active ? '1' : '0');
     }
@@ -370,15 +307,6 @@ export class HudShell {
             this.#transitionLock = false;
         }, TRANSITION_LOCK_MS);
     }
-    /**
-     * A click on the page dismisses the SETTINGS popover - and nothing else.
-     *
-     * The chat used to close here too, which was wrong from three directions: Reticle's own clicks
-     * land on the page (synthetic in-page, or a genuine OS event when it drives through CDP), a click
-     * in annotate mode is placing a mark, and a person clicking around their app while watching the
-     * log is not asking for the log to go away. The chat has three deliberate ways out - its minimise
-     * button, the toolbar toggle, and Escape - and that is all it needs.
-     */
     #onDocPointerDown = (e) => {
         if (this.#root === undefined || this.#dock === undefined)
             return;

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

@@ -1,11 +1,2 @@
-/**
- * All presenter overlay CSS - glow border, synthetic cursor/ring/ripple, and the floating HUD shell.
- * Split across shell-styles + controls + log modules so each file stays under the size cap.
- */
-/**
- * The presenter overlay's stacking layer. Exported because the annotator has to sit ABOVE it: the
- * overlay holds the page blocker, and anything below this number is covered by that shield - which
- * is what buried the annotate composer and made its Cancel/Add buttons unclickable.
- */
 export declare const Z_OVERLAY = 2147483600;
 export declare const PRESENTER_CSS: string;

package/dist/presenter/presenter-styles.js

@@ -4,15 +4,6 @@ import { SHELL_CSS } from './presenter-shell-styles.js';
 import { SETTINGS_CSS } from './presenter-settings-styles.js';
 import { HUD_CHROME_CSS, HUD_LOG_WELL_CSS } from './presenter-hud-chrome.js';
 import { REPORT_CSS } from './presenter-report-styles.js';
-/**
- * All presenter overlay CSS - glow border, synthetic cursor/ring/ripple, and the floating HUD shell.
- * Split across shell-styles + controls + log modules so each file stays under the size cap.
- */
-/**
- * The presenter overlay's stacking layer. Exported because the annotator has to sit ABOVE it: the
- * overlay holds the page blocker, and anything below this number is covered by that shield - which
- * is what buried the annotate composer and made its Cancel/Add buttons unclickable.
- */
 export const Z_OVERLAY = 2147483600;
 export const PRESENTER_CSS = `
 [data-reticle-overlay]{position:fixed;inset:0;pointer-events:none;z-index:${String(Z_OVERLAY)};}

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

@@ -1,16 +1,11 @@
 import { type LogResult } from './presenter-log.js';
-/**
- * Paint the live verdict tally into a YouTube-style segmented pill (pass | fail).
- */
 export declare function renderTally(el: HTMLElement | undefined, runLog: {
     result?: LogResult;
 }[], prev: TallyCounts): TallyCounts;
-/** Running verdict counts the header tally shows - the testing score the human watches grow. */
 export interface TallyCounts {
     passes: number;
     fails: number;
 }
-/** Count pass/fail verdicts across the run log. Pure - no DOM, unit-testable. */
 export declare function countVerdicts(runLog: {
     result?: LogResult;
 }[]): TallyCounts;

package/dist/presenter/presenter-tally.js

@@ -1,8 +1,5 @@
 import { LOG_RESULT } from './presenter-log.js';
 import { PresenterIcon, PRESENTER_ICON_SIZE, hiIcon } from './presenter-icons.js';
-/**
- * Paint the live verdict tally into a YouTube-style segmented pill (pass | fail).
- */
 export function renderTally(el, runLog, prev) {
     const next = countVerdicts(runLog);
     if (el === undefined)
@@ -48,7 +45,6 @@ export function renderTally(el, runLog, prev) {
     el.append(pass, sep, fail);
     return next;
 }
-/** Count pass/fail verdicts across the run log. Pure - no DOM, unit-testable. */
 export function countVerdicts(runLog) {
     let passes = 0;
     let fails = 0;

package/dist/presenter/presenter-test-helpers.d.ts

@@ -1,9 +1,7 @@
-/** Shared fixtures for the presenter test suites (presenter.test.ts + presenter-lifecycle.test.ts). */
 export declare const FAST_IDLE_MS = 20;
 export declare const FAST_FADE_MS = 5;
 export declare const flush: () => Promise<void>;
 export declare const wait: (ms: number) => Promise<void>;
-/** Poll a predicate until true or timeout - robust to real-timer lateness under load (no flake). */
 export declare const until: (pred: () => boolean, ms?: number) => Promise<boolean>;
 export declare const dataOn: () => string | null;
 export declare const dataBusy: () => string | null;

package/dist/presenter/presenter-test-helpers.js

@@ -1,9 +1,7 @@
-/** Shared fixtures for the presenter test suites (presenter.test.ts + presenter-lifecycle.test.ts). */
 export const FAST_IDLE_MS = 20;
 export const FAST_FADE_MS = 5;
 export const flush = () => new Promise((r) => setTimeout(r, 0));
 export const wait = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Poll a predicate until true or timeout - robust to real-timer lateness under load (no flake). */
 export const until = async (pred, ms = 1000) => {
     const t0 = Date.now();
     while (!pred()) {

package/dist/presenter/presenter-verbs.js

@@ -1,10 +1,3 @@
-// Present-tense verb for an action label in the presenter HUD (cursor status + act-log row).
-// Presenter-only UI copy - never a wire string. Shared by presenter.ts (cursor) and reticle.ts
-// (act-log row) so the two stay in lockstep.
-//
-// The CASES are wire values though, and they are core's ActionType. Spelled as free strings here,
-// a rename in core left this switch silently falling through to `default` - which returns the raw
-// action name, so the HUD degrades to "webmcp Save" instead of a verb and nothing fails.
 import { ActionType } from '@reticlehq/core';
 export function actionVerb(action) {
     switch (action) {

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

@@ -1,15 +1,11 @@
-/** Read the Vite-injected repo root, when present. */
 export declare function readWorkspaceRoot(): string | undefined;
-/** Last path segment for compact display (Codex/Cursor-style chip). */
 export declare function workspaceFolderLabel(root: string): string;
-/** Project id from the URL lease stamp, when present. */
 export declare function readProjectIdFromUrl(): string | undefined;
 export declare function workspaceSummary(): {
     folder: string;
     root?: string;
     projectId?: string;
 };
-/** Workspace chip + detail menu - sits above the composer row. */
 export declare function workspaceRowHtml(): string;
 export declare function paintWorkspace(root: HTMLElement): void;
 export declare function mountWorkspaceSelector(root: HTMLElement): () => void;

package/dist/presenter/presenter-workspace.js

@@ -11,19 +11,16 @@ const PROJECT_LABEL = 'Project';
 const COPY_PATH_LABEL = 'Copy path';
 const COPIED_PATH_LABEL = 'Copied';
 const WORKSPACE_FALLBACK = 'This page';
-/** Read the Vite-injected repo root, when present. */
 export function readWorkspaceRoot() {
     const value = globalThis[RETICLE_ROOT_GLOBAL];
     return 'string' === typeof value && value.length > 0 ? value : undefined;
 }
-/** Last path segment for compact display (Codex/Cursor-style chip). */
 export function workspaceFolderLabel(root) {
     const normalized = root.replace(/\\/g, '/').replace(/\/+$/, '');
     const parts = normalized.split('/').filter((part) => part.length > 0);
     const last = parts[parts.length - 1];
     return last !== undefined && last.length > 0 ? last : WORKSPACE_FALLBACK;
 }
-/** Project id from the URL lease stamp, when present. */
 export function readProjectIdFromUrl() {
     if ('undefined' === typeof window)
         return undefined;
@@ -43,7 +40,6 @@ export function workspaceSummary() {
         out.projectId = projectId;
     return out;
 }
-/** Workspace chip + detail menu - sits above the composer row. */
 export function workspaceRowHtml() {
     const folderIcon = hiIconHtml(PresenterIcon.LAYOUT, PRESENTER_ICON_SIZE.HELP);
     const caret = hiIconHtml(PresenterIcon.CARET_DOWN, PRESENTER_ICON_SIZE.HELP);
@@ -54,7 +50,7 @@ export function workspaceRowHtml() {
       <span class="reticle-workspace-name" ${WORKSPACE_NAME_ATTR}>${WORKSPACE_FALLBACK}</span>
       <span class="reticle-workspace-caret" aria-hidden="true">${caret}</span>
     </button>
-    <div class="reticle-workspace-menu" ${WORKSPACE_MENU_ATTR} role="dialog" aria-label="${WORKSPACE_LABEL}" aria-hidden="true" hidden>
+    <div class="reticle-workspace-menu" ${WORKSPACE_MENU_ATTR} role="region" aria-label="${WORKSPACE_LABEL}" aria-hidden="true" hidden>
       <div class="reticle-workspace-menu-head">
         <div class="reticle-workspace-menu-title">${WORKSPACE_LABEL}</div>
         <button type="button" class="reticle-workspace-copy" ${WORKSPACE_COPY_ATTR} title="${COPY_PATH_LABEL}" aria-label="${COPY_PATH_LABEL}">${copyIcon}</button>
@@ -67,9 +63,6 @@ export function workspaceRowHtml() {
 }
 export function paintWorkspace(root) {
     const summary = workspaceSummary();
-    // Nothing to say - no injected repo root, no leased project id - so the chip says nothing. It
-    // used to render its fallback, "This page", which names no workspace and is exactly as true of
-    // every page. The chip earns its slot only when it can tell you WHICH checkout is being driven.
     const wrap = root.querySelector('.reticle-workspace-wrap');
     if (wrap instanceof HTMLElement) {
         const known = summary.root !== undefined || summary.projectId !== undefined;

package/dist/presenter/presenter.d.ts

@@ -12,93 +12,33 @@ export type { ControlIntent, ControlHandler } from './presenter-controls.js';
 export declare class Presenter {
     #private;
     constructor(options?: PresenterOptions);
-    /** Setter so reticle.ts can wire the control callback after construction. */
     setControlHandler(handler: ControlHandler): void;
-    /** Current live-control session state mirrored onto the panel (data-reticle-state). */
     get state(): SessionState;
-    /** Whether a run is currently being presented (false before the agent's first activity / after end). */
     get sessionActive(): boolean;
-    /** Drive the panel's live-control visual state (server-push / agent path; never emits). */
     setState(state: SessionState, text?: string, tone?: PresenterTone): void;
-    /** 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(): void;
     handlePush(command: {
         name: string;
         args: Record<string, unknown>;
     }): void;
-    /** Current cap on accumulated log rows. */
     get logMax(): number;
     set logMax(n: number);
     mount(): void;
-    /** Wire annotation chrome; expanding the HUD enters annotate mode. */
     bindAnnotator(annotator: Annotator): void;
     destroy(): void;
-    /**
-     * 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(): 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.
-     */
     sessionEnd(): void;
-    /**
-     * 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(): void;
-    /** Re-arm the quiet-window idle check (kept for reticle.ts's finally block). */
     scheduleIdle(): void;
-    /** Test/diagnostic accessor for the current glow phase. */
     glowPhase(): import("./presenter-config.js").GlowPhase;
-    /** Current intent (reading vs acting), exposed for tests + the watcher. */
     get mode(): PresenterMode;
-    /**
-     * 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: PresenterMode): void;
     status(text: string): void;
-    /** Agent-tunable idle-end window (reticle_session). Floored so it can't be set uselessly small. */
     setIdleEndMs(ms: number): void;
-    /**
-     * 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(): PresenterRunState | Record<string, unknown>;
-    /**
-     * 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: LogKind, text: string, result?: LogResult): LogHandle | undefined;
-    /** Back-compat: narration appends to the live log (append-only, never overwrites). */
     narrate(text: string, level?: string): LogHandle | undefined;
-    /**
-     * 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: boolean): void;
-    /** Fly the cursor to an element, play the action's effect, then pace for the human. */
     beforeAct(refId: string, action: string, label: string): Promise<void>;
 }