@reticlehq/browser 2.13.1 → 2.14.0

package/dist/presenter/presenter-controls.js

@@ -4,46 +4,28 @@ import { CHAT_TOGGLE_ATTR, CLEAR_MARKS_ATTR, MARKERS_BTN_ATTR } from './presente
 import { PresenterIcon, PRESENTER_ICON_SIZE, hiIcon, hiIconHtml, hiToggleIconHtml, } from './presenter-icons.js';
 import { getPresenterSettings } from './presenter-settings.js';
 import { mountWorkspaceSelector, workspaceRowHtml } from './presenter-workspace.js';
-// Live-control panel: the two-way control surface inside the floating HUD - Pause/Resume + End
-// (header), a message input + Send (footer), and the data-reticle-state visual machine. Split out of
-// presenter.ts to keep both files under the 500-line cap (mirrors the presenter-log.ts split).
-// All nodes carry data-reticle-* attrs so they're excluded from snapshots (see dom-ignore.ts). The
-// strings here are presenter-only UI; the control kinds + state values reuse protocol constants.
-/** data-reticle-state attribute on the overlay root; its value is always a SessionState. */
 const DATA_RETICLE_STATE = 'data-reticle-state';
-/** data-reticle-tone on the overlay root - waiting/ask/warn distinguishes how the agent handed back. */
 const DATA_RETICLE_TONE = 'data-reticle-tone';
 const DATA_ON = 'data-on';
 const GLOW_OFF = '0';
-/** Button copy (presenter-only UI; never a wire string). */
 const CONTROL_LABEL = {
     PAUSE: 'Pause',
     RESUME: 'Resume',
     END: 'End',
     SEND: 'Send',
 };
-const INPUT_PLACEHOLDER = 'Tell the agent something…';
-/** Accessible name for the composer (a placeholder is not an accessible name). */
-const INPUT_ARIA_LABEL = 'Message to the agent';
 const PAUSED_BADGE_TEXT = 'PAUSED';
 const ENDED_BANNER_TEXT = 'Session ended';
 const COPY_LABEL = 'Copy run';
 const EXPORT_LABEL = 'Export';
 const FLOWS_LABEL = 'Replay a flow';
 const COPIED_TEXT = 'Copied ✓';
-/** Download filename for the exported run state. */
 const RUN_FILENAME = 'reticle-run.json';
-/** Border fade-out delay after a session ends (native timer; presenter-only tunable). */
 export const ENDED_FADE_MS = 4000;
-/** Max composer height (px) before it scrolls. One source for both the CSS cap and the JS auto-grow
- * clamp - they measure the same border-box, so the scrollbar appears exactly when growth stops. */
-const MSG_MAX_H = 96;
-/** CSS for the control surface (injected with the rest of the presenter stylesheet). */
 export const CONTROLS_CSS = `
 [data-reticle-chat-panel] [data-reticle-foot]{flex:none;padding:8px 10px 10px;border-top:1px solid rgba(255,255,255,.07);
   background:linear-gradient(180deg,rgba(0,0,0,.35) 0%,rgba(0,0,0,.55) 100%);pointer-events:auto;}
 [data-reticle-chat-panel] .reticle-hud-log-well{margin:0 0 4px;}
-[data-reticle-chat-panel] .reticle-composer-stack{display:flex;flex-direction:column;gap:6px;}
 [data-reticle-chat-panel] .reticle-workspace-wrap{position:relative;align-self:flex-start;max-width:100%;}
 [data-reticle-chat-panel] .reticle-workspace{
   display:inline-flex;align-items:center;gap:5px;max-width:100%;padding:3px 8px 3px 6px;border-radius:999px;cursor:pointer;
@@ -78,30 +60,6 @@ export const CONTROLS_CSS = `
 [data-reticle-chat-panel] .reticle-workspace-menu-row{display:flex;align-items:flex-start;justify-content:space-between;gap:10px;padding:4px 0;}
 [data-reticle-chat-panel] .reticle-workspace-menu-k{flex:none;color:rgba(255,255,255,.42);}
 [data-reticle-chat-panel] .reticle-workspace-menu-v{min-width:0;text-align:right;color:rgba(255,255,255,.9);font-weight:500;word-break:break-all;}
-[data-reticle-chat-panel] .reticle-composer{display:flex;align-items:center;gap:6px;background:rgba(255,255,255,.03);
-  border:1px solid rgba(255,255,255,.1);border-radius:999px;padding:4px 4px 4px 14px;
-  box-shadow:inset 0 1px 0 rgba(255,255,255,.05);transition:border-color .2s,box-shadow .2s,background .2s;}
-[data-reticle-chat-panel] .reticle-composer:focus-within{
-  border-color:color-mix(in srgb,var(--reticle-accent) 50%,transparent);background:rgba(255,255,255,.06);
-  box-shadow:inset 0 1px 0 rgba(255,255,255,.06),
-    0 0 0 1px color-mix(in srgb,var(--reticle-accent) 50%,transparent);}
-[data-reticle-chat-panel] .reticle-msg{flex:1;min-width:0;pointer-events:auto;background:transparent;border:none;outline:none;resize:none;
-  box-sizing:border-box;color:var(--reticle-fg);font-family:var(--reticle-font);font-size:12.5px;line-height:18px;
-  height:28px;min-height:28px;max-height:${MSG_MAX_H}px;padding:5px 0;overflow-y:auto;
-  scrollbar-width:thin;scrollbar-color:rgba(255,255,255,.14) transparent;}
-[data-reticle-chat-panel] .reticle-msg::-webkit-scrollbar{width:9px;}
-[data-reticle-chat-panel] .reticle-msg::-webkit-scrollbar-thumb{background:rgba(255,255,255,.14);border-radius:9px;border:2px solid transparent;background-clip:content-box;}
-[data-reticle-chat-panel] .reticle-msg::placeholder{color:var(--reticle-faint);}
-[data-reticle-chat-panel] .reticle-msg:disabled{opacity:.5;}
-[data-reticle-chat-panel] .reticle-send{flex:none;width:28px;height:28px;padding:0;border-radius:50%;border:none;cursor:pointer;pointer-events:auto;
-  background:var(--reticle-accent);color:#ffffff;display:inline-flex;align-items:center;justify-content:center;
-  transition:background .15s,transform .1s,box-shadow .15s;
-  box-shadow:0 1px 3px color-mix(in srgb,var(--reticle-accent) 30%,transparent);}
-[data-reticle-chat-panel] .reticle-send:hover{
-  background:color-mix(in srgb,var(--reticle-accent) 85%,#000);
-  box-shadow:0 2px 6px color-mix(in srgb,var(--reticle-accent) 40%,transparent);}
-[data-reticle-chat-panel] .reticle-send:active{transform:scale(.92);}
-[data-reticle-chat-panel] .reticle-send:disabled{background:#374151;color:#9ca3af;box-shadow:none;opacity:.5;cursor:default;}
 [data-reticle-chat-panel] .reticle-banner{display:none;flex:none;align-items:center;gap:8px;padding:10px 14px;color:var(--reticle-fg);
   font-size:12px;font-weight:500;border-bottom:1px solid var(--reticle-line2);background:var(--reticle-surface);}
 [data-reticle-overlay][data-reticle-state="ended"] [data-reticle-chat-panel] .reticle-banner{display:block;}
@@ -141,7 +99,6 @@ export const CONTROLS_CSS = `
 [data-reticle-hud] .reticle-export-msg{position:absolute;width:1px;height:1px;margin:-1px;padding:0;
   overflow:hidden;clip-path:inset(50%);white-space:nowrap;border:0;}
 `;
-/** Swap pause/resume icon + accessible label without visible text clutter in the toolbar. */
 function paintPauseBtn(btn, paused) {
     const iconName = paused ? PresenterIcon.PLAY : PresenterIcon.PAUSE;
     const labelText = paused ? CONTROL_LABEL.RESUME : CONTROL_LABEL.PAUSE;
@@ -165,7 +122,6 @@ function pauseToolbarHtml() {
     const tip = `<span class="reticle-tb-tip">${CONTROL_LABEL.PAUSE}</span>`;
     return `<div class="reticle-tb-wrap reticle-tb-wrap--pause">${btn}${badge}${tip}</div>`;
 }
-/** Icon toolbar: pause, chat, markers, end, clear - copy/export appear after a run ends. */
 export const CONTROLS_TOOLBAR_HTML = [
     pauseToolbarHtml(),
     tbWrap(`<button type="button" ${CHAT_TOGGLE_ATTR} class="reticle-tb-btn reticle-tb-btn--toggle" title="${CHAT_LABEL}" aria-label="${CHAT_LABEL}" aria-pressed="false" data-active="0">${hiToggleIconHtml(PresenterIcon.MESSAGE, TB)}</button>`, CHAT_LABEL),
@@ -176,18 +132,13 @@ export const CONTROLS_TOOLBAR_HTML = [
     `<button type="button" data-reticle-export class="reticle-tb-btn reticle-tb-btn--export" title="${EXPORT_LABEL}" aria-label="${EXPORT_LABEL}" hidden>${hiIconHtml(PresenterIcon.DOWNLOAD, TB)}</button>`,
     '<span data-reticle-export-msg class="reticle-export-msg" aria-live="polite"></span>',
 ].join('');
-/** Banner markup (between head and log, hidden unless ended). */
 export const CONTROLS_BANNER_HTML = `<div data-reticle-banner class="reticle-banner">${ENDED_BANNER_TEXT}</div>`;
-/** Replay-a-flow row (between log and footer); buttons are filled in by setFlows once flows arrive. */
 export const CONTROLS_FLOWS_HTML = `<div data-reticle-flows class="reticle-flows"><span class="reticle-flows-cap">${FLOWS_LABEL}</span></div>`;
-/** Footer markup: composer only (export icons live in the toolbar). */
-export const CONTROLS_FOOT_HTML = `<div data-reticle-foot><div class="reticle-composer-stack">${workspaceRowHtml()}<div class="reticle-composer"><textarea data-reticle-input class="reticle-msg" rows="1" aria-label="${INPUT_ARIA_LABEL}" placeholder="${INPUT_PLACEHOLDER}"></textarea><button type="button" data-reticle-send class="reticle-send" aria-label="${CONTROL_LABEL.SEND}">${hiIconHtml(PresenterIcon.SEND, PRESENTER_ICON_SIZE.SEND)}</button></div></div></div>`;
+export const CONTROLS_FOOT_HTML = `<div data-reticle-foot><div class="reticle-foot-stack">${workspaceRowHtml()}</div></div>`;
 function queryControlRefs(root) {
     return {
         pauseBtn: root.querySelector('[data-reticle-pause]') ?? undefined,
         endBtn: root.querySelector('[data-reticle-end]') ?? undefined,
-        input: root.querySelector('[data-reticle-input]') ?? undefined,
-        sendBtn: root.querySelector('[data-reticle-send]') ?? undefined,
         banner: root.querySelector('[data-reticle-banner]') ?? undefined,
         copyBtn: root.querySelector('[data-reticle-copy]') ?? undefined,
         exportBtn: root.querySelector('[data-reticle-export]') ?? undefined,
@@ -195,18 +146,10 @@ function queryControlRefs(root) {
         flows: root.querySelector('[data-reticle-flows]') ?? undefined,
     };
 }
-/**
- * The live-control panel: owns the control element refs, the SessionState, the ended-fade timer,
- * the DOM wiring, and the data-reticle-state visual machine. Split out of Presenter to keep both files
- * under the 500-line cap. A click handler both emits a control AND optimistically applies state; the
- * server's PRESENTER echo re-syncs via setState only (never emits) so a control is delivered once.
- */
 export class ControlPanel {
     #refs = {
         pauseBtn: undefined,
         endBtn: undefined,
-        input: undefined,
-        sendBtn: undefined,
         banner: undefined,
         copyBtn: undefined,
         exportBtn: undefined,
@@ -217,16 +160,8 @@ export class ControlPanel {
     #fadeTimer;
     #root;
     #glow;
-    /** The full replayable-flow list from the last push; re-filtered per page on route change. */
     #flowItems = [];
     #workspaceTeardown;
-    /**
-     * One signal for every listener this controller registers.
-     *
-     * All eight are anonymous closures over `this`, so there was no reference to hand
-     * `removeEventListener` and teardown removed none of them — each kept the controller reachable
-     * for as long as its element lived, and a second mount stacked another set on top.
-     */
     #listeners;
     #host;
     constructor(host) {
@@ -235,7 +170,6 @@ export class ControlPanel {
     get state() {
         return this.#state;
     }
-    /** Query control refs out of the mounted root and bind the DOM listeners, then paint active. */
     mount(root, glow) {
         this.#listeners = new AbortController();
         const { signal } = this.#listeners;
@@ -248,16 +182,6 @@ export class ControlPanel {
         }
         this.#refs.pauseBtn?.addEventListener('click', () => this.#onPauseToggle(), { signal });
         this.#refs.endBtn?.addEventListener('click', () => this.#onEnd(), { signal });
-        this.#refs.sendBtn?.addEventListener('click', () => this.#onSend(), { signal });
-        this.#refs.input?.addEventListener('keydown', (e) => {
-            // Enter sends; Shift+Enter inserts a newline (falls through to the textarea's default).
-            if (e instanceof KeyboardEvent && 'Enter' === e.key && !e.shiftKey) {
-                e.preventDefault();
-                this.#onSend();
-            }
-        }, { signal });
-        this.#refs.input?.addEventListener('input', () => this.#autosize(), { signal });
-        // Replay-a-flow: one ▶ click re-runs a saved flow (no agent). Delegated so it covers all chips.
         this.#refs.flows?.addEventListener('click', (e) => {
             const target = e.target;
             if (!(target instanceof HTMLElement))
@@ -272,11 +196,9 @@ export class ControlPanel {
         this.#workspaceTeardown = mountWorkspaceSelector(root);
         this.setState(SessionState.ACTIVE);
     }
-    /** Serialize the run state to pretty JSON for Copy/Export. */
     #runJson() {
         return JSON.stringify(this.#host.runState(), null, 2);
     }
-    /** Copy the run state to the clipboard (with a brief "Copied ✓" flash). */
     #onCopy() {
         void navigator.clipboard?.writeText(this.#runJson());
         if (getPresenterSettings().clearOnCopy) {
@@ -289,7 +211,6 @@ export class ControlPanel {
             nativeSetTimeout(() => msg.setAttribute('data-show', '0'), 1600);
         }
     }
-    /** Download the run state as reticle-run.json. */
     #onExport() {
         const blob = new Blob([this.#runJson()], { type: 'application/json' });
         const url = URL.createObjectURL(blob);
@@ -302,9 +223,7 @@ export class ControlPanel {
             this.#host.clearRunLog?.();
         }
     }
-    /** Clear any pending ended-fade timer (called from Presenter.destroy). */
     teardown() {
-        // All eight registrations, in one call that cannot drift from mount().
         this.#listeners?.abort();
         this.#listeners = undefined;
         this.#workspaceTeardown?.();
@@ -329,32 +248,6 @@ export class ControlPanel {
         this.#host.emit(HumanControlKind.END);
         this.setState(SessionState.ENDED);
     }
-    #onSend() {
-        if (this.#state === SessionState.ENDED)
-            return;
-        const text = (this.#refs.input?.value ?? '').trim();
-        if (0 === text.length)
-            return;
-        this.#host.emit(HumanControlKind.MESSAGE, text);
-        this.#host.logHuman(text);
-        if (getPresenterSettings().clearOnCopy) {
-            this.#host.clearRunLog?.();
-        }
-        if (this.#refs.input !== undefined)
-            this.#refs.input.value = '';
-        this.#autosize();
-    }
-    /** Grow the composer to fit its content (up to the CSS max-height), then shrink back - soothing,
-     * no scrollbar until it's genuinely long. Driven on input and after a send clears the field. */
-    #autosize() {
-        const el = this.#refs.input;
-        if (el === undefined)
-            return;
-        el.style.height = 'auto';
-        el.style.height = `${String(Math.min(el.scrollHeight, MSG_MAX_H))}px`;
-    }
-    /** Render the replayable-flow chips from the server push. Each ▶ click re-runs that flow, no agent.
-     * Takes the raw wire value and narrows it here (the panel is the consumer of this push). */
     setFlows(flows) {
         const list = Array.isArray(flows) ? flows : [];
         this.#flowItems = list
@@ -374,13 +267,6 @@ export class ControlPanel {
             .filter((c) => c !== null);
         this.#renderFlows();
     }
-    /**
-     * Re-render the replay chips for the CURRENT page. A flow "starts here" iff its first step's anchor
-     * (a testid `start` hint) is present in the live DOM; flows with no start hint (signal/role-first,
-     * un-checkable) always show. Called on connect and on every route change so the list tracks the page -
-     * so you never see (or click) a flow that can't replay from where you are. Existing flows benefit
-     * without re-recording, since the hint is derived from the first step, not stored on the flow.
-     */
     refilterFlows() {
         this.#renderFlows();
     }
@@ -391,26 +277,20 @@ export class ControlPanel {
         const doc = el.ownerDocument;
         const testids = new Set(Array.from(doc.querySelectorAll('[data-testid]')).map((n) => n.getAttribute('data-testid')));
         const visible = this.#flowItems.filter((f) => f.start === undefined || testids.has(f.start));
-        el.querySelectorAll('[data-reticle-replay]').forEach((b) => b.remove()); // rebuild, keep the caption
+        el.querySelectorAll('[data-reticle-replay]').forEach((b) => b.remove());
         for (const flow of visible) {
             const btn = doc.createElement('button');
             btn.type = 'button';
             btn.className = 'reticle-flow';
-            btn.setAttribute('data-reticle-replay', flow.name); // setAttribute → no markup injection from a name
+            btn.setAttribute('data-reticle-replay', flow.name);
             btn.textContent = `▶ ${flow.name}`;
             el.appendChild(btn);
         }
         el.setAttribute('data-has', visible.length > 0 ? '1' : '0');
     }
-    /**
-     * Drive the panel's visual state. Idempotent; NEVER emits a control - the shared path for both the
-     * optimistic local click and the authoritative server PRESENTER echo. Only the ended-border fade
-     * touches a clock, via the injected native timer.
-     */
     setState(state, text, tone) {
         this.#state = state;
         this.#root?.setAttribute(DATA_RETICLE_STATE, state);
-        // A handoff tone (waiting/ask/warn) drives a distinct panel treatment; calm/undefined = a plain end.
         const handoff = tone !== undefined && tone !== PresenterTone.CALM;
         if (handoff)
             this.#root?.setAttribute(DATA_RETICLE_TONE, tone);
@@ -440,12 +320,6 @@ export class ControlPanel {
             else
                 refs.exportBtn.setAttribute('hidden', '');
         }
-        if (refs.sendBtn !== undefined)
-            refs.sendBtn.disabled = ended;
-        if (refs.input !== undefined)
-            refs.input.disabled = ended;
-        // A calm end leads with "Session ended"; a handoff (waiting/ask/warn) leads with the notice itself,
-        // since the toned styling already conveys "ended" and the notice is the actionable headline.
         if (refs.banner !== undefined) {
             const summary = text !== undefined && text.trim().length > 0 ? text.trim() : '';
             refs.banner.textContent =
@@ -454,8 +328,6 @@ export class ControlPanel {
                     : `${ENDED_BANNER_TEXT}${summary.length > 0 ? ` · ${summary}` : ''}`;
         }
         if (ended) {
-            // End the run: fade out the page BORDER (testing is over) but KEEP the panel so the human can
-            // read the result and Copy/Export the run state. The composer disables; the export row reveals.
             const glow = this.#glow;
             this.#fadeTimer = nativeSetTimeout(() => {
                 glow?.setAttribute(DATA_ON, GLOW_OFF);

package/dist/presenter/presenter-dock-layout.d.ts

@@ -1,6 +1,3 @@
-/** Flip floating panels and reclamp a dragged dock so everything stays on-screen. */
 export declare function syncDockLayout(dock: HTMLElement, overlay: HTMLElement): void;
-/** Batch dock layout work on the next frame (resize, panel open, drag end). */
 export declare function scheduleSyncDockLayout(dock: HTMLElement, overlay: HTMLElement): void;
-/** Resolve the dock node from an overlay root. */
 export declare function findDock(overlay: HTMLElement): HTMLElement | undefined;

package/dist/presenter/presenter-dock-layout.js

@@ -49,7 +49,6 @@ function visiblePanel(el) {
     const style = window.getComputedStyle(el);
     return 'none' !== style.display && 'hidden' !== style.visibility;
 }
-/** Resolve the HUD bar inside a dock (or the node itself in minimal fixtures). */
 function resolveHudBar(dock) {
     const nested = dock.querySelector(`[${HUD_ATTR}]`);
     if (nested instanceof HTMLElement)
@@ -60,7 +59,6 @@ function resolveHudBar(dock) {
         return dock;
     return undefined;
 }
-/** Flip floating panels and reclamp a dragged dock so everything stays on-screen. */
 export function syncDockLayout(dock, overlay) {
     const hud = resolveHudBar(dock);
     if (hud === undefined)
@@ -153,7 +151,6 @@ export function syncDockLayout(dock, overlay) {
     applyHudPosition(dock, base.left + dx, base.top + dy);
 }
 let syncRafId;
-/** Batch dock layout work on the next frame (resize, panel open, drag end). */
 export function scheduleSyncDockLayout(dock, overlay) {
     if (syncRafId !== undefined)
         cancelAnimationFrame(syncRafId);
@@ -163,7 +160,6 @@ export function scheduleSyncDockLayout(dock, overlay) {
         requestAnimationFrame(() => syncDockLayout(dock, overlay));
     });
 }
-/** Resolve the dock node from an overlay root. */
 export function findDock(overlay) {
     const dock = overlay.querySelector(`[${DOCK_ATTR}]`);
     return dock instanceof HTMLElement ? dock : undefined;

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

@@ -1,48 +1,26 @@
-export interface HudDragCallbacks {
+interface HudDragCallbacks {
     onDragMove?: () => void;
-    /** Fires when a drag gesture ends; `moved` is true when the panel actually changed position. */
     onDragEnd?: (moved: boolean) => void;
 }
-/** Whether the HUD is off the default bottom-right dock. */
 export declare function isHudDragged(hud: HTMLElement): boolean;
-/** Clamp a HUD position so the full panel stays inside the viewport. */
 export declare function clampHudPosition(left: number, top: number, width: number, height: number, viewportWidth: number, viewportHeight: number, margin?: number): {
     left: number;
     top: number;
 };
-/** Paint an explicit left/top position (switches the HUD off the default bottom-right dock). */
 export declare function applyHudPosition(hud: HTMLElement, left: number, top: number): void;
-/** Return the HUD to the default bottom-right dock. */
 export declare function resetHudDockPosition(hud: HTMLElement): void;
-/** Return the HUD's laid-out box (rounded to whole pixels for stable clamping). */
 export declare function hudLayoutBox(hud: HTMLElement): {
     left: number;
     top: number;
     width: number;
     height: number;
 };
-/** Read the dragged HUD's authored position (CSS vars), falling back to layout box. */
 export declare function readHudPosition(hud: HTMLElement): {
     left: number;
     top: number;
 };
-/**
- * Re-clamp a dragged HUD after resize, minimise/expand, or any layout-driven size change.
- * No-op when the panel is still on the default dock.
- */
 export declare function relayoutHudPosition(hud: HTMLElement): void;
-/**
- * Keep a dragged HUD inside the viewport when the window or panel size changes
- * (minimise ↔ expand, tally appearing, viewport resize).
- */
 export declare function installHudPositionGuards(hud: HTMLElement, overlay: HTMLElement): () => void;
-/**
- * Drag the presenter HUD by its header. Returns a teardown that removes listeners.
- * Uses pointer capture so the drag stays smooth even when the cursor leaves the head.
- */
 export declare function installHudDrag(hud: HTMLElement, head: HTMLElement, callbacks?: HudDragCallbacks): () => void;
-/**
- * Drag the presenter HUD from multiple handles (FAB when collapsed, toolbar brand when expanded).
- * Returns a teardown that removes listeners from every handle.
- */
 export declare function installHudDragHandles(hud: HTMLElement, handles: HTMLElement[], callbacks?: HudDragCallbacks): () => void;
+export {};

package/dist/presenter/presenter-drag.js

@@ -1,11 +1,9 @@
 import { HUD_DOCK_MARGIN_PX, HUD_DRAG_IGNORE_SEL, HUD_DRAG_THRESHOLD_PX, HUD_DRAGGED_ATTR, HUD_POS_X_VAR, HUD_POS_Y_VAR, MIN_ATTR, CHAT_ATTR, SETTINGS_ATTR, } from './presenter-config.js';
 import { scheduleSyncDockLayout } from './presenter-dock-layout.js';
 const DRAG_HANDLE_DRAGGING_CLASS = 'reticle-drag-handle--dragging';
-/** Whether the HUD is off the default bottom-right dock. */
 export function isHudDragged(hud) {
     return '1' === hud.getAttribute(HUD_DRAGGED_ATTR);
 }
-/** Clamp a HUD position so the full panel stays inside the viewport. */
 export function clampHudPosition(left, top, width, height, viewportWidth, viewportHeight, margin = HUD_DOCK_MARGIN_PX) {
     const minLeft = margin;
     const minTop = margin;
@@ -16,19 +14,16 @@ export function clampHudPosition(left, top, width, height, viewportWidth, viewpo
         top: Math.max(minTop, Math.min(top, maxTop)),
     };
 }
-/** Paint an explicit left/top position (switches the HUD off the default bottom-right dock). */
 export function applyHudPosition(hud, left, top) {
     hud.setAttribute(HUD_DRAGGED_ATTR, '1');
     hud.style.setProperty(HUD_POS_X_VAR, `${String(left)}px`);
     hud.style.setProperty(HUD_POS_Y_VAR, `${String(top)}px`);
 }
-/** Return the HUD to the default bottom-right dock. */
 export function resetHudDockPosition(hud) {
     hud.removeAttribute(HUD_DRAGGED_ATTR);
     hud.style.removeProperty(HUD_POS_X_VAR);
     hud.style.removeProperty(HUD_POS_Y_VAR);
 }
-/** Return the HUD's laid-out box (rounded to whole pixels for stable clamping). */
 export function hudLayoutBox(hud) {
     const rect = hud.getBoundingClientRect();
     return {
@@ -38,7 +33,6 @@ export function hudLayoutBox(hud) {
         height: rect.height,
     };
 }
-/** Read the dragged HUD's authored position (CSS vars), falling back to layout box. */
 export function readHudPosition(hud) {
     const x = hud.style.getPropertyValue(HUD_POS_X_VAR);
     const y = hud.style.getPropertyValue(HUD_POS_Y_VAR);
@@ -48,10 +42,6 @@ export function readHudPosition(hud) {
     const rect = hud.getBoundingClientRect();
     return { left: rect.left, top: rect.top };
 }
-/**
- * Re-clamp a dragged HUD after resize, minimise/expand, or any layout-driven size change.
- * No-op when the panel is still on the default dock.
- */
 export function relayoutHudPosition(hud) {
     if (!isHudDragged(hud))
         return;
@@ -60,16 +50,10 @@ export function relayoutHudPosition(hud) {
     const next = clampHudPosition(left, top, width, height, window.innerWidth, window.innerHeight);
     applyHudPosition(hud, next.left, next.top);
 }
-/**
- * Keep a dragged HUD inside the viewport when the window or panel size changes
- * (minimise ↔ expand, tally appearing, viewport resize).
- */
 export function installHudPositionGuards(hud, overlay) {
     const scheduleRelayout = () => {
         scheduleSyncDockLayout(hud, overlay);
     };
-    // One signal for all three listeners here. The observers below are NOT covered — neither
-    // ResizeObserver nor MutationObserver accepts one — so they keep their explicit disconnects.
     const listeners = new AbortController();
     const { signal } = listeners;
     const onResize = () => scheduleRelayout();
@@ -93,10 +77,6 @@ export function installHudPositionGuards(hud, overlay) {
         minObserver.disconnect();
     };
 }
-/**
- * Drag the presenter HUD by its header. Returns a teardown that removes listeners.
- * Uses pointer capture so the drag stays smooth even when the cursor leaves the head.
- */
 export function installHudDrag(hud, head, callbacks = {}) {
     let dragging = false;
     let startX = 0;
@@ -173,8 +153,6 @@ export function installHudDrag(hud, head, callbacks = {}) {
         releaseCapture(e.pointerId);
         finishDrag();
     };
-    // All four pointer phases share one signal: they are added together and must come off
-    // together, and a partial removal would leave a half-live drag.
     const listeners = new AbortController();
     const { signal } = listeners;
     head.addEventListener('pointerdown', onPointerDown, { signal });
@@ -188,10 +166,6 @@ export function installHudDrag(hud, head, callbacks = {}) {
         finishDrag();
     };
 }
-/**
- * Drag the presenter HUD from multiple handles (FAB when collapsed, toolbar brand when expanded).
- * Returns a teardown that removes listeners from every handle.
- */
 export function installHudDragHandles(hud, handles, callbacks = {}) {
     const teardowns = handles.map((handle) => installHudDrag(hud, handle, callbacks));
     return () => {

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

@@ -1,13 +1,4 @@
-/**
- * Synthetic-cursor + click effects - the visible "the agent is acting here" motion. Pure DOM helpers
- * extracted from presenter.ts so the controller stays under the size cap; each is a no-op when its
- * element is absent (the panel may not be mounted). Behavior is unchanged from the inlined methods.
- */
-/** Fly the synthetic cursor to a viewport point and show it. */
 export declare function moveCursor(cursor: HTMLElement | undefined, x: number, y: number): void;
-/** Briefly draw the green focus ring around an element's box, then fade it. */
 export declare function ringAround(ring: HTMLElement | undefined, rect: DOMRect): void;
-/** Spawn a one-shot click ripple at a viewport point (self-removing). */
 export declare function spawnRipple(root: HTMLElement | undefined, x: number, y: number): void;
-/** Pace for the human so an action is watchable, not instant. */
 export declare function pace(ms: number): Promise<void>;

package/dist/presenter/presenter-effects.js

@@ -1,17 +1,10 @@
 import { nativeSetTimeout } from '../timers/native-timers.js';
-/**
- * Synthetic-cursor + click effects - the visible "the agent is acting here" motion. Pure DOM helpers
- * extracted from presenter.ts so the controller stays under the size cap; each is a no-op when its
- * element is absent (the panel may not be mounted). Behavior is unchanged from the inlined methods.
- */
-/** Fly the synthetic cursor to a viewport point and show it. */
 export function moveCursor(cursor, x, y) {
     if (cursor === undefined)
         return;
     cursor.setAttribute('data-on', '1');
     cursor.style.transform = `translate(${String(x)}px, ${String(y)}px)`;
 }
-/** Briefly draw the green focus ring around an element's box, then fade it. */
 export function ringAround(ring, rect) {
     if (ring === undefined)
         return;
@@ -22,7 +15,6 @@ export function ringAround(ring, rect) {
     ring.setAttribute('data-on', '1');
     nativeSetTimeout(() => ring.setAttribute('data-on', '0'), 700);
 }
-/** Spawn a one-shot click ripple at a viewport point (self-removing). */
 export function spawnRipple(root, x, y) {
     if (root === undefined)
         return;
@@ -33,7 +25,6 @@ export function spawnRipple(root, x, y) {
     root.appendChild(r);
     nativeSetTimeout(() => r.remove(), 520);
 }
-/** Pace for the human so an action is watchable, not instant. */
 export function pace(ms) {
     return new Promise((res) => nativeSetTimeout(res, ms));
 }

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

@@ -1,42 +1,21 @@
 import { PresenterMode } from '@reticlehq/core';
 import { GlowPhase, BorderMode } from './presenter-config.js';
-/** What the controller needs from the Presenter: the clock, the timing knobs, and a setMode callback. */
 interface GlowDeps {
     now: () => number;
     idleAfterMs: number;
     glowFadeMs: number;
     borderMode: BorderMode;
-    /** Called when the glow fades to idle, so the Presenter clears the READING/ACTING chip. */
     setMode: (mode: PresenterMode) => void;
 }
-/**
- * The glow / activity state machine - drives the border shimmer + synthetic-cursor visibility from
- * agent-activity timing. Extracted from presenter.ts so the controller file stays under the size cap;
- * behavior is byte-for-byte the same. It holds references to the same `#glow`/`#cursor` nodes the
- * Presenter does (both call setAttribute on those elements - the Presenter owns the SESSION border via
- * data-on; this owns the BUSY shimmer via data-busy). A burst flips the glow IN once, holds it (the
- * slow reticle-pulse keeps breathing - no per-action restart/strobe), then fades it OUT once after a quiet
- * window.
- */
 export declare class GlowController {
     #private;
     constructor(deps: GlowDeps);
-    /** Wire the glow + cursor elements after the Presenter mounts the DOM. */
     setElements(glow: HTMLElement | undefined, cursor: HTMLElement | undefined): void;
-    /** Current glow phase (test/diagnostic accessor). */
     phase(): GlowPhase;
-    /** Last activity timestamp - read by the Presenter's liveness heartbeat. */
     lastActivityMs(): number;
-    /** Set the activity baseline WITHOUT entering busy (sessionStart / revive). */
     resetActivity(ms: number): void;
-    /**
-     * Record agent activity. Idempotent while busy - only the first activity from idle/fading flips the
-     * glow on (no strobe). `ms` lets log read the clock exactly once per row.
-     */
     markActivity(ms?: number): void;
-    /** Re-arm the quiet-window idle check (kept for reticle.ts's finally block). */
     scheduleIdle(): void;
-    /** Clear both timers (called from Presenter.destroy). */
     teardown(): void;
 }
 export {};