@reticlehq/browser 2.13.1 → 3.1.0

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

@@ -0,0 +1,99 @@
+import { HUD_DROP_SHADOW, HUD_SURFACE_PAINT } from './chrome/presenter-hud-chrome.js';
+const AVATAR = 20;
+const AVATAR_LG = 28;
+export const ACCOUNT_CSS = `
+/* The control establishes its own stacking context, and a high one.
+   Its menu is absolutely positioned inside a panel whose other children (the log well, the act strip)
+   are themselves positioned with their own z-index, so a z-index on the MENU alone was being compared
+   inside the wrong context and lost to a sibling with a lower number. Raising it here, on the thing
+   that contains the menu, is what actually puts the menu above them. 9 clears the workspace menu's 8,
+   which is the highest in-panel chrome. */
+/* The header row has to out-stack the log well, or nothing inside it can.
+   .reticle-chat-head is position:relative with z-index:2, so it IS a stacking context and the number
+   below is scoped inside it -- while the log well is a SIBLING, also at z-index:2, and later in DOM
+   order. Equal z, later sibling wins, so the well painted over the whole header and took the open
+   menu with it. The menu measured correctly and was invisible, which is the shape of bug that reads
+   as "the dropdown does not work". Raising the header is what lets its children escape; the two only
+   overlap while a menu is open, so nothing else moves. */
+.reticle-chat-head{z-index:3;}
+.reticle-account{position:relative;z-index:9;display:inline-flex;align-items:center;gap:6px;flex:none;}
+.reticle-account-avatar{
+  display:inline-flex;align-items:center;justify-content:center;
+  width:${String(AVATAR)}px;height:${String(AVATAR)}px;border-radius:999px;
+  font-size:9px;font-weight:600;letter-spacing:.02em;
+  background:rgba(255,255,255,.12);color:rgba(255,255,255,.92);user-select:none;}
+.reticle-account-avatar--lg{
+  width:${String(AVATAR_LG)}px;height:${String(AVATAR_LG)}px;font-size:11px;}
+
+/* The trigger is the avatar plus a hit area, never a second visual element: an avatar that looks
+   like a button reads as an action, and this one opens a menu about a state. */
+.reticle-account-trigger{
+  display:inline-flex;align-items:center;justify-content:center;
+  padding:0;border:none;background:transparent;cursor:pointer;line-height:0;border-radius:999px;
+  transition:box-shadow .12s,opacity .12s;}
+.reticle-account-trigger:hover{opacity:.85;}
+.reticle-account-trigger:focus-visible{outline:none;box-shadow:0 0 0 2px rgba(255,255,255,.35);}
+.reticle-account-trigger[aria-expanded="true"]{box-shadow:0 0 0 2px rgba(255,255,255,.28);}
+
+.reticle-account-signin{
+  border:none;border-radius:6px;padding:2px 9px;cursor:pointer;font:inherit;font-size:10.5px;
+  background:rgba(255,255,255,.06);color:rgba(255,255,255,.75);transition:background .12s,color .12s;}
+.reticle-account-signin:hover{background:rgba(255,255,255,.12);color:#fff;}
+
+/* Anchored to the control and opening DOWNWARD.
+   Not upward, which is what it looked like it wanted: all three surfaces mount this near the TOP of
+   a panel whose own overflow is hidden for its rounded corners, so a menu opening upward is laid
+   out correctly and then clipped away entirely -- present to the probe, invisible to the eye. Panels
+   grow downward and have the height, so down is the direction that stays inside the box. */
+.reticle-account-menu{
+  position:absolute;right:0;top:calc(100% + 8px);z-index:6;
+  min-width:212px;max-width:280px;padding:10px;box-sizing:border-box;
+  display:flex;flex-direction:column;gap:8px;
+  border-radius:10px;
+  /* The HUD's own surface tokens, not a colour invented here. A menu with its own near-black is a
+     second design language in the same panel, and a translucent one lets the panel's empty-state text
+     read straight through the rows -- which is what the first version did. */
+  ${HUD_SURFACE_PAINT}
+  box-shadow:inset 0 1px 0 rgba(255,255,255,.09),${HUD_DROP_SHADOW};
+  font-size:11px;color:rgba(255,255,255,.78);text-align:left;}
+.reticle-account-menu[hidden]{display:none;}
+
+.reticle-account-head{display:flex;align-items:center;gap:8px;min-width:0;}
+.reticle-account-who{display:flex;flex-direction:column;min-width:0;gap:1px;}
+.reticle-account-org{
+  font-size:11.5px;font-weight:600;color:rgba(255,255,255,.95);
+  overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.reticle-account-email{
+  font-size:10.5px;color:rgba(255,255,255,.55);
+  overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+
+.reticle-account-rows{
+  display:flex;flex-direction:column;gap:4px;
+  padding-top:8px;border-top:1px solid rgba(255,255,255,.08);}
+.reticle-account-row{display:flex;align-items:baseline;justify-content:space-between;gap:10px;}
+.reticle-account-k{color:rgba(255,255,255,.5);flex:none;}
+.reticle-account-v{
+  color:rgba(255,255,255,.88);min-width:0;
+  overflow:hidden;text-overflow:ellipsis;white-space:nowrap;
+  font-variant-numeric:tabular-nums;}
+
+.reticle-account-actions{
+  display:flex;flex-direction:column;gap:2px;
+  padding-top:8px;border-top:1px solid rgba(255,255,255,.08);}
+.reticle-account-action{
+  display:flex;align-items:center;gap:6px;width:100%;box-sizing:border-box;
+  padding:5px 6px;border:none;border-radius:6px;cursor:pointer;
+  font:inherit;font-size:11px;text-align:left;text-decoration:none;
+  background:transparent;color:rgba(255,255,255,.8);transition:background .12s,color .12s;}
+.reticle-account-action:hover{background:rgba(255,255,255,.08);color:#fff;}
+.reticle-account-action:focus-visible{outline:none;background:rgba(255,255,255,.1);color:#fff;}
+/* The unlinked hint is a sentence, not a verb: it wraps rather than truncating, because a clipped
+   instruction is worse than a tall menu. */
+.reticle-account-action--hint{
+  color:rgba(255,255,255,.5);font-size:10.5px;line-height:1.35;white-space:normal;cursor:pointer;}
+
+.reticle-account-dashboard{
+  display:inline-flex;align-items:center;justify-content:center;
+  border:none;background:transparent;color:rgba(255,255,255,.6);cursor:pointer;line-height:0;padding:2px;}
+.reticle-account-dashboard:hover{color:#fff;}
+`;

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

@@ -0,0 +1,40 @@
+import type { AccountState } from '@reticlehq/core';
+export declare const ACCOUNT_ROOT_ATTR = "data-reticle-account";
+export declare const ACCOUNT_SIGNIN_ATTR = "data-reticle-account-signin";
+export declare const SYNC_BTN_ATTR = "data-reticle-sync-now";
+export declare const ACCOUNT_TRIGGER_ATTR = "data-reticle-account-trigger";
+export declare const ACCOUNT_MENU_ATTR = "data-reticle-account-menu";
+export declare const ACCOUNT_SIGNOUT_ATTR = "data-reticle-account-signout";
+export declare const ACCOUNT_TEXT: {
+    readonly SIGNED_OUT: "Sign in";
+    readonly SIGNIN_TITLE: "Run `reticle login` in your terminal — click to copy the command";
+    readonly SIGNIN_COMMAND: "reticle login";
+    readonly DASHBOARD_TITLE: "Open this project on the dashboard";
+    readonly SYNC_TITLE: "Push to the dashboard now, instead of waiting for the next sync";
+    readonly COPIED: "Copied";
+    readonly AVATAR_FALLBACK: "•";
+    readonly MENU_LABEL: "Reticle account";
+    readonly TRIGGER_TITLE: "Your Reticle account";
+    readonly SIGNED_IN_AS: "Signed in";
+    readonly DASHBOARD_ACTION: "Open dashboard";
+    readonly LINK_HINT: "Not linked — run `reticle link` to keep a record on the dashboard";
+    readonly LINK_COMMAND: "reticle link";
+    readonly SIGNOUT_ACTION: "Sign out";
+    readonly SIGNOUT_TITLE: "Run `reticle logout` in your terminal — click to copy the command";
+    readonly SIGNOUT_COMMAND: "reticle logout";
+    readonly PROJECT_LABEL: "Project";
+    readonly HOST_LABEL: "Host";
+    readonly VERDICTS_LABEL: "Verdicts";
+    readonly DEFECTS_LABEL: "Defects found";
+};
+export interface AccountDetails {
+    projectName?: string | undefined;
+    dashboardUrl?: string | undefined;
+    verdicts?: number | undefined;
+    defects?: number | undefined;
+}
+export declare function accountInitials(org: string | undefined): string;
+export declare function accountControlHtml(account: AccountState | undefined, details?: AccountDetails, offerSignIn?: boolean): string;
+export declare function accountCapsuleHtml(account: AccountState | undefined, dashboardUrl?: string, offerSignIn?: boolean): string;
+export declare function syncButtonHtml(dashboardUrl: string | undefined): string;
+export declare function mountAccountControl(root: HTMLElement): () => void;

package/dist/presenter/presenter-account.js

@@ -0,0 +1,178 @@
+import { hiIconHtml, PRESENTER_ICON_SIZE, PresenterIcon } from './icons/presenter-icons.js';
+import { esc, isSafeDashboardUrl } from './chrome/presenter-safe-html.js';
+export const ACCOUNT_ROOT_ATTR = 'data-reticle-account';
+export const ACCOUNT_SIGNIN_ATTR = 'data-reticle-account-signin';
+export const SYNC_BTN_ATTR = 'data-reticle-sync-now';
+export const ACCOUNT_TRIGGER_ATTR = 'data-reticle-account-trigger';
+export const ACCOUNT_MENU_ATTR = 'data-reticle-account-menu';
+export const ACCOUNT_SIGNOUT_ATTR = 'data-reticle-account-signout';
+export const ACCOUNT_TEXT = {
+    SIGNED_OUT: 'Sign in',
+    SIGNIN_TITLE: 'Run `reticle login` in your terminal — click to copy the command',
+    SIGNIN_COMMAND: 'reticle login',
+    DASHBOARD_TITLE: 'Open this project on the dashboard',
+    SYNC_TITLE: 'Push to the dashboard now, instead of waiting for the next sync',
+    COPIED: 'Copied',
+    AVATAR_FALLBACK: '•',
+    MENU_LABEL: 'Reticle account',
+    TRIGGER_TITLE: 'Your Reticle account',
+    SIGNED_IN_AS: 'Signed in',
+    DASHBOARD_ACTION: 'Open dashboard',
+    LINK_HINT: 'Not linked — run `reticle link` to keep a record on the dashboard',
+    LINK_COMMAND: 'reticle link',
+    SIGNOUT_ACTION: 'Sign out',
+    SIGNOUT_TITLE: 'Run `reticle logout` in your terminal — click to copy the command',
+    SIGNOUT_COMMAND: 'reticle logout',
+    PROJECT_LABEL: 'Project',
+    HOST_LABEL: 'Host',
+    VERDICTS_LABEL: 'Verdicts',
+    DEFECTS_LABEL: 'Defects found',
+};
+const ACCOUNT_COPIED_MS = 1200;
+export function accountInitials(org) {
+    const words = (org ?? '')
+        .trim()
+        .split(/[\s._-]+/)
+        .filter((word) => word.length > 0);
+    const letters = words
+        .slice(0, 2)
+        .map((word) => [...word][0] ?? '')
+        .join('');
+    return letters.length > 0 ? letters.toUpperCase() : ACCOUNT_TEXT.AVATAR_FALLBACK;
+}
+export function accountControlHtml(account, details = {}, offerSignIn = false) {
+    if (account === undefined)
+        return '';
+    if (!account.signedIn) {
+        if (!offerSignIn)
+            return '';
+        return `<div class="reticle-account" ${ACCOUNT_ROOT_ATTR}><button type="button" class="reticle-account-signin" ${ACCOUNT_SIGNIN_ATTR} title="${ACCOUNT_TEXT.SIGNIN_TITLE}" aria-label="${ACCOUNT_TEXT.SIGNIN_TITLE}">${ACCOUNT_TEXT.SIGNED_OUT}</button></div>`;
+    }
+    const org = account.org ?? '';
+    const label = org.length > 0 ? esc(org) : ACCOUNT_TEXT.SIGNED_IN_AS;
+    const avatar = `<span class="reticle-account-avatar" aria-hidden="true">${esc(accountInitials(account.org))}</span>`;
+    const trigger = `<button type="button" class="reticle-account-trigger" ${ACCOUNT_TRIGGER_ATTR}` +
+        ` aria-haspopup="true" aria-expanded="false" title="${ACCOUNT_TEXT.TRIGGER_TITLE}"` +
+        ` aria-label="${ACCOUNT_TEXT.TRIGGER_TITLE}: ${label}">${avatar}</button>`;
+    return `<div class="reticle-account" ${ACCOUNT_ROOT_ATTR}>${trigger}${accountMenuHtml(account, details)}</div>`;
+}
+function detailRow(key, value) {
+    if (value === undefined || 0 === value.length)
+        return '';
+    return `<div class="reticle-account-row"><span class="reticle-account-k">${esc(key)}</span><span class="reticle-account-v" title="${esc(value)}">${esc(value)}</span></div>`;
+}
+function accountMenuHtml(account, details) {
+    const org = account.org ?? '';
+    const identity = `<div class="reticle-account-head">` +
+        `<span class="reticle-account-avatar reticle-account-avatar--lg" aria-hidden="true">${esc(accountInitials(account.org))}</span>` +
+        `<span class="reticle-account-who">` +
+        `<span class="reticle-account-org">${org.length > 0 ? esc(org) : ACCOUNT_TEXT.SIGNED_IN_AS}</span>` +
+        (account.email !== undefined && account.email.length > 0
+            ? `<span class="reticle-account-email" title="${esc(account.email)}">${esc(account.email)}</span>`
+            : `<span class="reticle-account-email">${ACCOUNT_TEXT.SIGNED_IN_AS}</span>`) +
+        `</span></div>`;
+    const rows = detailRow(ACCOUNT_TEXT.HOST_LABEL, account.host) +
+        detailRow(ACCOUNT_TEXT.PROJECT_LABEL, details.projectName) +
+        detailRow(ACCOUNT_TEXT.VERDICTS_LABEL, details.verdicts !== undefined ? String(details.verdicts) : undefined) +
+        detailRow(ACCOUNT_TEXT.DEFECTS_LABEL, details.defects !== undefined ? String(details.defects) : undefined);
+    const linked = details.dashboardUrl !== undefined && isSafeDashboardUrl(details.dashboardUrl);
+    const dashboard = linked
+        ? `<a class="reticle-account-action" href="${esc(details.dashboardUrl ?? '')}" target="_blank" rel="noreferrer noopener" title="${ACCOUNT_TEXT.DASHBOARD_TITLE}">${hiIconHtml(PresenterIcon.VIEW, PRESENTER_ICON_SIZE.HELP)}<span>${ACCOUNT_TEXT.DASHBOARD_ACTION}</span></a>`
+        :
+            `<button type="button" class="reticle-account-action reticle-account-action--hint" ${ACCOUNT_SIGNIN_ATTR} data-reticle-copy="${ACCOUNT_TEXT.LINK_COMMAND}" title="${ACCOUNT_TEXT.LINK_HINT}"><span>${ACCOUNT_TEXT.LINK_HINT}</span></button>`;
+    const signOut = `<button type="button" class="reticle-account-action" ${ACCOUNT_SIGNOUT_ATTR} data-reticle-copy="${ACCOUNT_TEXT.SIGNOUT_COMMAND}" title="${ACCOUNT_TEXT.SIGNOUT_TITLE}"><span>${ACCOUNT_TEXT.SIGNOUT_ACTION}</span></button>`;
+    return (`<div class="reticle-account-menu" ${ACCOUNT_MENU_ATTR} role="menu" aria-label="${ACCOUNT_TEXT.MENU_LABEL}" aria-hidden="true" hidden>` +
+        identity +
+        (rows.length > 0 ? `<div class="reticle-account-rows">${rows}</div>` : '') +
+        `<div class="reticle-account-actions">${dashboard}${signOut}</div>` +
+        `</div>`);
+}
+export function accountCapsuleHtml(account, dashboardUrl, offerSignIn = false) {
+    return accountControlHtml(account, { dashboardUrl }, offerSignIn);
+}
+export function syncButtonHtml(dashboardUrl) {
+    if (dashboardUrl === undefined || !isSafeDashboardUrl(dashboardUrl))
+        return '';
+    return `<button type="button" class="reticle-sync-now" ${SYNC_BTN_ATTR} title="${ACCOUNT_TEXT.SYNC_TITLE}" aria-label="${ACCOUNT_TEXT.SYNC_TITLE}">${hiIconHtml(PresenterIcon.SYNC, PRESENTER_ICON_SIZE.HELP)}</button>`;
+}
+export function mountAccountControl(root) {
+    const controller = new AbortController();
+    const { signal } = controller;
+    const closeAll = (except) => {
+        for (const menu of root.querySelectorAll(`[${ACCOUNT_MENU_ATTR}]`)) {
+            if (menu === except)
+                continue;
+            menu.setAttribute('hidden', '');
+            menu.setAttribute('aria-hidden', 'true');
+        }
+        for (const trigger of root.querySelectorAll(`[${ACCOUNT_TRIGGER_ATTR}]`)) {
+            if (except !== undefined && trigger.parentElement === except.parentElement)
+                continue;
+            trigger.setAttribute('aria-expanded', 'false');
+        }
+    };
+    const flashCopied = (el) => {
+        const label = el.querySelector('span') ?? el;
+        const previous = label.textContent;
+        label.textContent = ACCOUNT_TEXT.COPIED;
+        setTimeout(() => {
+            label.textContent = previous;
+        }, ACCOUNT_COPIED_MS);
+    };
+    root.addEventListener('click', (event) => {
+        const target = event.target;
+        if (!(target instanceof Element))
+            return;
+        const trigger = target.closest(`[${ACCOUNT_TRIGGER_ATTR}]`);
+        if (trigger instanceof HTMLElement) {
+            event.preventDefault();
+            event.stopPropagation();
+            const menu = trigger.parentElement?.querySelector(`[${ACCOUNT_MENU_ATTR}]`);
+            if (!(menu instanceof HTMLElement))
+                return;
+            const wasOpen = !menu.hasAttribute('hidden');
+            closeAll();
+            if (wasOpen)
+                return;
+            menu.removeAttribute('hidden');
+            menu.setAttribute('aria-hidden', 'false');
+            trigger.setAttribute('aria-expanded', 'true');
+            return;
+        }
+        const copier = target.closest('[data-reticle-copy]');
+        if (copier instanceof HTMLElement) {
+            event.preventDefault();
+            event.stopPropagation();
+            const command = copier.getAttribute('data-reticle-copy') ?? '';
+            if (command.length > 0)
+                void navigator.clipboard?.writeText(command).catch(() => undefined);
+            flashCopied(copier);
+            return;
+        }
+        const signin = target.closest(`[${ACCOUNT_SIGNIN_ATTR}]`);
+        if (signin instanceof HTMLElement) {
+            event.preventDefault();
+            event.stopPropagation();
+            void navigator.clipboard?.writeText(ACCOUNT_TEXT.SIGNIN_COMMAND).catch(() => undefined);
+            flashCopied(signin);
+            return;
+        }
+        closeAll();
+    }, { signal });
+    document.addEventListener('pointerdown', (event) => {
+        const target = event.target;
+        if (target instanceof Node && root.contains(target))
+            return;
+        closeAll();
+    }, { signal });
+    document.addEventListener('keydown', (event) => {
+        if ('Escape' !== event.key)
+            return;
+        const open = root.querySelector(`[${ACCOUNT_MENU_ATTR}]:not([hidden])`);
+        if (null === open)
+            return;
+        event.stopPropagation();
+        closeAll();
+    }, { signal });
+    return () => controller.abort();
+}

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

@@ -1,14 +1,4 @@
-import type { ControlHandler } from './presenter-controls.js';
-/**
- * Presenter tunables + option surface. Split out of presenter.ts so that file is just the controller
- * under the size cap; these are pure declarations (interfaces + named constants), no behavior. None
- * cross the browser↔bridge↔agent wire, so they live here, not in @reticlehq/core.
- */
-/**
- * Border behavior.
- * - 'session': base border persists connect→disconnect; the busy machine drives only the shimmer.
- * - 'busy': back-compat - the busy machine toggles the base border on/off.
- */
+import type { HumanControlKind } from '@reticlehq/core';
 export declare const BorderMode: {
     readonly SESSION: "session";
     readonly BUSY: "busy";
@@ -20,179 +10,92 @@ export declare const BUSY_ON = "1";
 export declare const BUSY_OFF = "0";
 export interface PresenterOptions {
     paceMs?: number;
-    /** Injected monotonic clock for the glow state machine (tests drive transitions). */
     now?: () => number;
-    /** Quiet window before busy -> fading. Overridable so tests run fast. */
     idleAfterMs?: number;
-    /** Fade duration before fading -> idle (keep in sync with the glow CSS opacity transition). */
     glowFadeMs?: number;
-    /** Liveness heartbeat interval (ms). Overridable so tests run fast. */
     heartbeatMs?: number;
-    /** Quiet (ms) after which the act strip shows the live "idle · {duration}" clock. Test-overridable. */
     idleNoticeMs?: number;
-    /** Quiet (ms) after which the session AUTO-ENDS (glow off, panel kept). Default 5min; agent-tunable. */
     idleEndMs?: number;
-    /** Session id, surfaced in the exported run state. */
     sessionId?: string;
-    /** Deprecated: accepted for source compat; the live log no longer auto-expires. */
     narrationDwellMs?: number;
-    /**
-     * 'session' (default): base border persists connect→disconnect, busy machine drives only the
-     * shimmer. 'busy': back-compat - busy machine toggles the base border on/off.
-     */
     border?: BorderMode;
-    /** Max accumulated activity-log rows before the oldest are pruned. Default 50. */
     logMax?: number;
-    /** Called when the human clicks pause/resume/end or sends a message from the panel. */
     onControl?: ControlHandler;
-    /** Overridable ended-border fade delay (native timer). Default 4000. */
     endedFadeMs?: number;
 }
 export declare const DEFAULT_PACE = 450;
-/**
- * The pace to actually use: the default in a browser a human is watching, zero in an automated one.
- *
- * The HUD paces `beforeAct` so a person can see the cursor reach the element before it fires. In a
- * headless browser that is 450ms of nothing, charged to the agent, on every action. Measured with
- * RETICLE_TRACE across the e2e battery: 42 `act` round-trips, 40 of them in a 452–460ms band -
- * a fixed cost, not app work - 19.7 SECONDS in total, 98.5% of all time the battery spent in the
- * browser, while every other command ran in 1–4ms.
- *
- * `navigator.webdriver` is the discriminator because it is exactly the question being asked: true
- * under automation (Playwright, CDP, the browser pool's leased tabs, CI), false in the dev browser
- * a human has open - the case the HUD exists for, which keeps its pacing untouched.
- *
- * An EXPLICIT `paceMs` always wins: a recorded demo runs under automation and still wants the glide,
- * and an option that quietly ignores what the caller asked for is worse than no option.
- */
 export declare function effectivePaceMs(requested: number | undefined, nav?: Navigator | undefined): number;
-/**
- * Glow state machine phases (exposed via glowPhase for tests). A burst of activity flips the
- * border IN once on the first activity, holds steady (the slow reticle-pulse breathing keeps running
- * uninterrupted - no per-action restart/strobe), then fades OUT once after a quiet window.
- */
 export declare const GlowPhase: {
     readonly IDLE: "idle";
     readonly BUSY: "busy";
     readonly FADING: "fading";
 };
 export type GlowPhase = (typeof GlowPhase)[keyof typeof GlowPhase];
-/** Quiet window before busy -> fading. */
 export declare const IDLE_AFTER_MS = 700;
-/** Liveness heartbeat: how often the act strip refreshes its "idle · {duration}" clock. */
 export declare const HEARTBEAT_MS = 1000;
-/**
- * After this much quiet, the act strip stops showing the last action and starts a LIVE, ticking
- * "◌ idle · {duration} since last action" - so a watcher can tell a 3s think from a dead agent
- * (the killer gap: a frozen panel used to look identical whether the agent paused or stopped).
- */
 export declare const IDLE_NOTICE_MS = 4000;
-/** Act-strip copy (presenter-only UI). */
 export declare const ACT_STRIP: {
     readonly READY: "Ready";
-    readonly IDLE_PREFIX: "idle · ";
+    readonly PLANNING_PREFIX: "planning next action · ";
+    readonly STOPPED: "stopped";
+    readonly STOPPED_PREFIX: "stopped · ";
     readonly NOW: "now";
     readonly SINCE_LAST: " since last action";
 };
-/** Default session-idle-end: after this much quiet the session auto-ends (glow off, panel persists
- * for analysis). Agent-tweakable via reticle_session { idleEndMs } for the app's needs. */
 export declare const IDLE_END_MS = 300000;
-/** Floor for a tweaked idle-end so the agent can't set a uselessly tiny window. */
 export declare const IDLE_END_MIN_MS = 5000;
-/** Must match the glow CSS opacity transition.25s) so phase reaches idle after the fade paints. */
 export declare const GLOW_FADE_MS = 250;
 export declare const GLOW_ON = "1";
 export declare const GLOW_OFF = "0";
 export declare const DATA_ON = "data-on";
-/** The overlay root's state attribute, which the shell styles resolve colour against. */
 export declare const STATE_ATTR = "data-reticle-state";
-/**
- * Not a SessionState: there is no session. It is the absence of one, said out loud.
- *
- * Kept off `SessionState` deliberately — that enum crosses the wire, and this state exists only
- * because nothing crossed the wire.
- */
 export declare const UNREACHABLE_STATE = "unreachable";
-/** Overlay-root attribute toggled when the HUD is collapsed to the FAB. */
 export declare const MIN_ATTR = "data-reticle-min";
-/** Overlay-root attribute toggled when the agent chat panel is open. */
 export declare const CHAT_ATTR = "data-reticle-chat";
-/** Fixed dock wrapper that stacks chat above the morphing HUD shell. */
 export declare const DOCK_ATTR = "data-reticle-dock";
-/** Collapsed circular control that expands the toolbar. */
 export declare const FAB_ATTR = "data-reticle-fab";
-/** Toolbar chat toggle button. */
 export declare const CHAT_TOGGLE_ATTR = "data-reticle-chat-toggle";
-/** Agent chat panel anchored to the dock. */
 export declare const CHAT_PANEL_ATTR = "data-reticle-chat-panel";
-/** Chat panel opens above or below the HUD bar depending on viewport space. */
 export declare const CHAT_PLACEMENT_ATTR = "data-reticle-chat-placement";
-/** Settings card opens above or below the HUD bar depending on viewport space. */
 export declare const SETTINGS_PLACEMENT_ATTR = "data-reticle-settings-placement";
-/** Horizontal alignment of dock-anchored panels (start = left, end = right). */
 export declare const DOCK_ALIGN_ATTR = "data-reticle-dock-align";
 export declare const Placement: {
     readonly ABOVE: "above";
     readonly BELOW: "below";
 };
-/** Show/hide annotation markers. */
 export declare const MARKERS_BTN_ATTR = "data-reticle-markers-btn";
-/** Clear every annotation on the page. */
 export declare const CLEAR_MARKS_ATTR = "data-reticle-clear-marks";
-/** Collapsed FAB annotation-count badge. */
 export declare const MARK_COUNT_ATTR = "data-reticle-mark-count";
-/**
- * Turn annotation on and off from the toolbar.
- *
- * Annotation used to be reachable only as a side effect of expanding the HUD, which meant there was
- * no way to keep the HUD open and stop annotating, and nothing on screen said the mode existed at
- * all. It is a mode the user chooses, so it gets a control they can see and press.
- */
 export declare const ANNOTATE_BTN_ATTR = "data-reticle-annotate-btn";
-/** Minimise the agent chat back to the toolbar, without collapsing the whole HUD. */
 export declare const CHAT_MIN_ATTR = "data-reticle-chat-min";
-/** Overlay flag: is the impact report on screen. */
 export declare const REPORT_ATTR = "data-reticle-report";
-/** The report panel itself. */
 export declare const REPORT_PANEL_ATTR = "data-reticle-report-panel";
-/** The report's close button. */
 export declare const REPORT_CLOSE_ATTR = "data-reticle-report-close";
-/** The toolbar button that opens the report. */
 export declare const REPORT_BTN_ATTR = "data-reticle-report-btn";
-/** The capsule that stands in for the chat while it is minimised - state dot + last action. */
 export declare const CHAT_PILL_ATTR = "data-reticle-chat-pill";
-/** Settings gear is open - the card sits above the dock. */
 export declare const SETTINGS_ATTR = "data-reticle-settings";
 export declare const SETTINGS_BTN_ATTR = "data-reticle-settings-btn";
 export declare const SETTINGS_PANEL_ATTR = "data-reticle-settings-panel";
 export declare const SETTINGS_CLOSE_ATTR = "data-reticle-settings-close";
 export declare const SETTING_KEY_ATTR = "data-reticle-setting";
 export declare const SETTINGS_STORAGE_KEY = "reticle-presenter-settings";
-/** Accent swatch applied to the dock chrome. */
-/** Overlay flag: is the page-edge glow wanted at all (user setting). */
 export declare const AMBIENT_GLOW_ATTR = "data-reticle-ambient-glow";
-/** Overlay mirror of the activity strip's liveness, so CSS can pick the ACTIVE status colour. */
 export declare const LIVENESS_ATTR = "data-reticle-live";
-/** When 1, a transparent blocker captures page pointer events. */
 export declare const BLOCK_ATTR = "data-reticle-block";
-/** When 1, the dock is hidden until the page reloads. */
 export declare const HIDDEN_UNTIL_RESTART_ATTR = "data-reticle-hidden";
-/** When 0, activity-log timestamps are hidden. */
 export declare const LOG_TIMESTAMPS_ATTR = "data-reticle-log-ts";
-/** When 1, the chat panel uses a narrower width. */
-/** When 1, HUD motion is reduced for accessibility. */
 export declare const REDUCE_MOTION_ATTR = "data-reticle-reduce-motion";
-/** Docs opened from the settings footer. */
 export declare const MCP_DOCS_URL: string;
-/** HUD has been dragged off the default dock - positioned with explicit left/top. */
 export declare const HUD_DRAGGED_ATTR = "data-dragged";
-/** CSS custom properties written when the HUD is dragged. */
 export declare const HUD_POS_X_VAR = "--reticle-hud-x";
 export declare const HUD_POS_Y_VAR = "--reticle-hud-y";
-/** Pointer movement below this threshold is treated as a click, not a drag. */
 export declare const HUD_DRAG_THRESHOLD_PX = 4;
-/** Minimum gap between a dragged HUD and the viewport edge. */
 export declare const HUD_DOCK_MARGIN_PX = 8;
-/** Interactive nodes inside the drag handle that must not start a drag (not the FAB itself). */
 export declare const HUD_DRAG_IGNORE_SEL: string;
 export declare const THROTTLED_ATTR = "data-reticle-throttled";
+export declare const Z_HUD_TOOLTIP = 100;
+export interface ControlIntent {
+    kind: HumanControlKind;
+    text?: string;
+}
+export type ControlHandler = (intent: ControlIntent) => void;