improved HUD in debug

Author: FreakDev

CONTEXT.md

@@ -50,11 +50,19 @@ Harness mechanism that limits agent effort when `agent-browser` bash commands fa
 
 ## Action overlay
 
-In-page visual overlay shown during local Chrome headed runs to preview the agent's next browser action (cursor, highlight, intent banner). Distinct from verbose terminal logging. Enabled via `--action-overlay` or `extensions.actionOverlay.enabled`; on by default for `pqa debug`.
+In-page visual overlay shown during local Chrome headed runs to preview the agent's next browser action (ephemeral cursor and highlight) and a persistent stacked HUD panel. Distinct from verbose terminal logging. Enabled via `--action-overlay` or `extensions.actionOverlay.enabled`; on by default for `pqa debug`.
+
+## HUD entry
+
+One slot in the action overlay stack, tied to a single tool call preview: assistant text on top, parsed command label below in smaller type. Consecutive entries are separated by a subtle divider. Up to three entries are kept; the oldest is dropped when a fourth arrives. Entries persist until pushed out — no time-based fade or expiry. Stack order: oldest at top, newest at bottom.
+
+## Action overlay panel
+
+Fixed-size draggable rectangle (320 × 280 px) hosting the HUD entry stack. Drag via a top handle bar; panel body scrolls internally when content overflows; auto-scrolls to the newest entry on each append. Background opacity 0.7 by default, fully opaque on hover. Default position: top-right (12 px margin); user-dragged position is remembered for the rest of the browser session. Remains visible after the scenario ends until the browser window closes.
 
 ## Agent intent
 
-Short assistant narration (`step.text`) emitted by the LLM in the same turn as a browser action — for example « Click the Sign in button — @e6 ». Distinct from extended thinking (`reasoningText`) and from the parsed command label shown in the action overlay HUD.
+Assistant text (`step.text`) captured from the LLM response in the same agent step as a browser action. Shown in full (never truncated) above the command label in each HUD entry. Distinct from extended thinking (`reasoningText`) and from the parsed command label itself.
 
 ## Nudge
 

src/action-overlay/page-script.ts

@@ -9,7 +9,20 @@ export function buildActionOverlayScript(): string {
   if (window.__pqaOverlay) return;
 
   const ROOT_ID = "pqa-action-overlay-root";
+  const PANEL_ID = "pqa-overlay-panel";
+  const PANEL_BODY_ID = "pqa-overlay-panel-body";
   const HIGHLIGHT_CLASS = "pqa-overlay-highlight";
+  const CURSOR_CLASS = "pqa-overlay-cursor";
+  const MAX_ENTRIES = 3;
+  const PANEL_WIDTH = 320;
+  const PANEL_HEIGHT = 280;
+  const PANEL_MARGIN = 12;
+
+  let panelLeft = null;
+  let panelTop = null;
+  let dragActive = false;
+  let dragOffsetX = 0;
+  let dragOffsetY = 0;
 
   function ensureRoot() {
     let root = document.getElementById(ROOT_ID);
@@ -33,27 +46,46 @@ export function buildActionOverlayScript(): string {
     const style = document.createElement("style");
     style.id = "pqa-overlay-styles";
     style.textContent = [
-      "#pqa-action-overlay-root .pqa-overlay-hud {",
-      "  position: fixed; top: 12px; left: 50%; transform: translateX(-50%);",
-      "  max-width: min(90vw, 640px); padding: 10px 16px;",
-      "  background: rgba(15, 23, 42, 0.92); color: #f8fafc;",
-      "  font: 600 14px/1.35 system-ui, -apple-system, sans-serif;",
+      "#pqa-action-overlay-root .pqa-overlay-panel {",
+      "  position: fixed; width: 320px; height: 280px;",
+      "  display: flex; flex-direction: column;",
       "  border-radius: 8px; box-shadow: 0 4px 24px rgba(0,0,0,0.35);",
-      "  text-align: center;",
+      "  overflow: hidden; pointer-events: auto;",
+      "  background: rgba(15, 23, 42, 0.7); color: #f8fafc;",
+      "  font: 500 13px/1.4 system-ui, -apple-system, sans-serif;",
+      "  transition: background 0.15s ease;",
+      "}",
+      "#pqa-action-overlay-root .pqa-overlay-panel:hover {",
+      "  background: rgba(15, 23, 42, 1);",
+      "}",
+      "#pqa-action-overlay-root .pqa-overlay-panel-handle {",
+      "  height: 24px; flex-shrink: 0; cursor: grab;",
+      "  background: rgba(255,255,255,0.06);",
+      "  border-bottom: 1px solid rgba(148, 163, 184, 0.25);",
+      "}",
+      "#pqa-action-overlay-root .pqa-overlay-panel-handle:active { cursor: grabbing; }",
+      "#pqa-action-overlay-root .pqa-overlay-panel-body {",
+      "  flex: 1; overflow-y: auto; padding: 8px 12px; text-align: left;",
       "}",
-      "#pqa-action-overlay-root .pqa-overlay-hud-title {",
-      "  display: block; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;",
+      "#pqa-action-overlay-root .pqa-overlay-entry {",
+      "  padding: 8px 0;",
+      "  border-bottom: 1px solid rgba(148, 163, 184, 0.2);",
       "}",
-      "#pqa-action-overlay-root .pqa-overlay-hud-detail {",
-      "  display: block; margin-top: 2px;",
-      "  font-size: 12px; font-weight: 500; color: #94a3b8;",
-      "  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;",
+      "#pqa-action-overlay-root .pqa-overlay-entry:last-child { border-bottom: none; }",
+      "#pqa-action-overlay-root .pqa-overlay-entry-intent {",
+      "  display: block; font-size: 14px; font-weight: 600; line-height: 1.35;",
+      "  word-break: break-word; white-space: pre-wrap;",
+      "}",
+      "#pqa-action-overlay-root .pqa-overlay-entry-command {",
+      "  display: block; margin-top: 4px; font-size: 12px; font-weight: 500;",
+      "  color: #94a3b8; line-height: 1.45; word-break: break-word;",
       "}",
       "#pqa-action-overlay-root .pqa-overlay-highlight {",
       "  position: fixed; border: 3px solid #f59e0b;",
       "  background: rgba(245, 158, 11, 0.15); border-radius: 4px;",
       "  box-shadow: 0 0 0 4px rgba(245, 158, 11, 0.25);",
       "  transition: top 0.75s ease, left 0.75s ease, width 0.75s ease, height 0.75s ease;",
+      "  pointer-events: none;",
       "}",
       "#pqa-action-overlay-root .pqa-overlay-cursor {",
       "  position: fixed; width: 32px; height: 32px;",
@@ -66,94 +98,225 @@ export function buildActionOverlayScript(): string {
     document.documentElement.appendChild(style);
   }
 
+  function defaultPanelPosition() {
+    return {
+      left: Math.max(PANEL_MARGIN, window.innerWidth - PANEL_WIDTH - PANEL_MARGIN),
+      top: PANEL_MARGIN,
+    };
+  }
+
+  function applyPanelPosition(panel) {
+    const left = panelLeft ?? defaultPanelPosition().left;
+    const top = panelTop ?? defaultPanelPosition().top;
+    Object.assign(panel.style, {
+      left: left + "px",
+      top: top + "px",
+      right: "auto",
+      transform: "none",
+    });
+  }
+
+  function onDragMove(event) {
+    if (!dragActive) return;
+    panelLeft = event.clientX - dragOffsetX;
+    panelTop = event.clientY - dragOffsetY;
+    const panel = document.getElementById(PANEL_ID);
+    if (panel) applyPanelPosition(panel);
+  }
+
+  function onDragEnd() {
+    dragActive = false;
+  }
+
+  function ensurePanel(root) {
+    let panel = document.getElementById(PANEL_ID);
+    if (panel) return panel;
+
+    panel = document.createElement("div");
+    panel.id = PANEL_ID;
+    panel.className = "pqa-overlay-panel";
+
+    const handle = document.createElement("div");
+    handle.className = "pqa-overlay-panel-handle";
+    handle.setAttribute("aria-hidden", "true");
+    handle.addEventListener("mousedown", (event) => {
+      if (event.button !== 0) return;
+      dragActive = true;
+      const rect = panel.getBoundingClientRect();
+      dragOffsetX = event.clientX - rect.left;
+      dragOffsetY = event.clientY - rect.top;
+      panelLeft = rect.left;
+      panelTop = rect.top;
+      event.preventDefault();
+    });
+
+    const body = document.createElement("div");
+    body.id = PANEL_BODY_ID;
+    body.className = "pqa-overlay-panel-body";
+
+    panel.appendChild(handle);
+    panel.appendChild(body);
+    root.appendChild(panel);
+    applyPanelPosition(panel);
+
+    window.addEventListener("mousemove", onDragMove);
+    window.addEventListener("mouseup", onDragEnd);
+
+    return panel;
+  }
+
+  function clearAnimation(root) {
+    root.querySelectorAll("." + HIGHLIGHT_CLASS + ", ." + CURSOR_CLASS).forEach((el) => el.remove());
+  }
+
   function clearOverlay() {
     const root = document.getElementById(ROOT_ID);
     if (root) root.replaceChildren();
   }
 
-  function normalizeHudPayload(input) {
+  function normalizeEntryPayload(input) {
     if (typeof input === "string") {
-      return { intent: "", detail: input };
+      return { command: input, intent: "" };
     }
     if (input && typeof input === "object") {
+      const command =
+        input.command != null && input.command !== ""
+          ? String(input.command)
+          : input.detail != null && input.detail !== ""
+            ? String(input.detail)
+            : input.label != null && input.label !== ""
+              ? String(input.label)
+              : "";
       return {
+        command,
         intent: input.intent ? String(input.intent) : "",
-        detail: input.detail ? String(input.detail) : input.label ? String(input.label) : "",
       };
     }
-    return { intent: "", detail: "" };
+    return { command: "", intent: "" };
+  }
+
+  function trimEntryStack(body) {
+    while (body.children.length >= MAX_ENTRIES) {
+      body.firstElementChild?.remove();
+    }
+  }
+
+  function scrollPanelToBottom(body) {
+    body.scrollTop = body.scrollHeight;
   }
 
-  function appendHud(root, payload) {
-    const { intent, detail } = normalizeHudPayload(payload);
-    const hud = document.createElement("div");
-    hud.className = "pqa-overlay-hud";
+  function appendEntry(root, payload) {
+    const { command, intent } = normalizeEntryPayload(payload);
+    if (!command && !intent) return;
+
+    const panel = ensurePanel(root);
+    const body = panel.querySelector("#" + PANEL_BODY_ID);
+    if (!body) return;
+
+    trimEntryStack(body);
+
+    const entry = document.createElement("div");
+    entry.className = "pqa-overlay-entry";
+
     if (intent) {
-      const title = document.createElement("span");
-      title.className = "pqa-overlay-hud-title";
-      title.textContent = intent;
-      hud.appendChild(title);
+      const text = document.createElement("span");
+      text.className = "pqa-overlay-entry-intent";
+      text.textContent = intent;
+      entry.appendChild(text);
     }
-    if (detail) {
-      const sub = document.createElement("span");
-      sub.className = intent ? "pqa-overlay-hud-detail" : "pqa-overlay-hud-title";
-      sub.textContent = detail;
-      hud.appendChild(sub);
+    if (command) {
+      const cmd = document.createElement("span");
+      cmd.className = "pqa-overlay-entry-command";
+      cmd.textContent = command;
+      entry.appendChild(cmd);
     }
-    root.appendChild(hud);
+
+    body.appendChild(entry);
+    scrollPanelToBottom(body);
   }
 
   function showHud(payload) {
     ensureStyles();
     const root = ensureRoot();
-    clearOverlay();
-    appendHud(root, payload);
+    clearAnimation(root);
+    appendEntry(root, payload);
   }
 
-  function showMutation(payload) {
-    ensureStyles();
-    const root = ensureRoot();
-    clearOverlay();
-
-    appendHud(root, payload);
-    const box = payload && payload.box ? payload.box : null;
-
-    if (box && typeof box.x === "number" && typeof box.y === "number") {
-      const w = typeof box.width === "number" ? box.width : 0;
-      const h = typeof box.height === "number" ? box.height : 0;
-      const cx = box.x + w / 2;
-      const cy = box.y + h / 2;
-
-      const highlight = document.createElement("div");
-      highlight.className = HIGHLIGHT_CLASS;
-      Object.assign(highlight.style, {
-        top: box.y + "px",
-        left: box.x + "px",
-        width: Math.max(w, 4) + "px",
-        height: Math.max(h, 4) + "px",
-      });
-      root.appendChild(highlight);
-
-      const cursor = document.createElement("div");
-      cursor.className = "pqa-overlay-cursor";
-      cursor.innerHTML =
-        '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="32" height="32">' +
-        '<path fill="#f59e0b" stroke="#0f172a" stroke-width="1.2" d="M4 2l14 14h-6l-4 8z"/></svg>';
-      const startX = Math.max(0, cx - 100);
-      const startY = Math.max(0, cy - 80);
-      Object.assign(cursor.style, {
-        top: startY + "px",
-        left: startX + "px",
-      });
-      root.appendChild(cursor);
+  function scrollBoxIntoView(box) {
+    const w = typeof box.width === "number" ? box.width : 0;
+    const h = typeof box.height === "number" ? box.height : 0;
+    let x = box.x;
+    let y = box.y;
+    const margin = 72;
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const cx = x + w / 2;
+    const cy = y + h / 2;
+
+    let scrollX = 0;
+    let scrollY = 0;
+
+    if (cy < margin) scrollY = cy - margin - (vh - margin) / 2;
+    else if (cy > vh - margin) scrollY = cy - (vh + margin) / 2;
+
+    if (cx < margin) scrollX = cx - margin - (vw - margin) / 2;
+    else if (cx > vw - margin) scrollX = cx - (vw + margin) / 2;
+
+    if (scrollX !== 0 || scrollY !== 0) {
+      window.scrollBy({ top: scrollY, left: scrollX, behavior: "instant" });
+      x -= scrollX;
+      y -= scrollY;
+    }
 
+    return { x, y, width: w, height: h };
+  }
+
+  function showMutationAnimation(root, rawBox) {
+    if (!rawBox || typeof rawBox.x !== "number" || typeof rawBox.y !== "number") return;
+
+    const box = scrollBoxIntoView(rawBox);
+    const w = box.width;
+    const h = box.height;
+    const cx = box.x + w / 2;
+    const cy = box.y + h / 2;
+
+    const highlight = document.createElement("div");
+    highlight.className = HIGHLIGHT_CLASS;
+    Object.assign(highlight.style, {
+      top: box.y + "px",
+      left: box.x + "px",
+      width: Math.max(w, 4) + "px",
+      height: Math.max(h, 4) + "px",
+    });
+    root.appendChild(highlight);
+
+    const cursor = document.createElement("div");
+    cursor.className = CURSOR_CLASS;
+    cursor.innerHTML =
+      '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="32" height="32">' +
+      '<path fill="#f59e0b" stroke="#0f172a" stroke-width="1.2" d="M4 2l14 14h-6l-4 8z"/></svg>';
+    const startX = Math.max(0, cx - 100);
+    const startY = Math.max(0, cy - 80);
+    Object.assign(cursor.style, {
+      top: startY + "px",
+      left: startX + "px",
+    });
+    root.appendChild(cursor);
+
+    requestAnimationFrame(() => {
       requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          cursor.style.top = cy + "px";
-          cursor.style.left = cx + "px";
-        });
+        cursor.style.top = cy + "px";
+        cursor.style.left = cx + "px";
       });
-    }
+    });
+  }
+
+  function showMutation(payload) {
+    ensureStyles();
+    const root = ensureRoot();
+    clearAnimation(root);
+    appendEntry(root, payload);
+    showMutationAnimation(root, payload && payload.box ? payload.box : null);
   }
 
   window.__pqaOverlay = {