fix(hover-preview): wait for visible frames before timeout

Author: r3b1s

AGENTS.md

@@ -906,10 +906,12 @@ capability result and falls back to the current resized pane rectangle, so the
 refresh loop does not repeat a known-failing probe.
 
 The feature degrades cleanly when no SGR mouse report arrives within the
-bounded support window: it logs once, disables its mouse-mode lease, and leaves
-tracking and lifecycle observers running. Pi imports for the controller and
-overlay stay under `src/host/pi/hover-preview/**`; the renderer, lease, config
-resolver, and tmux plumbing remain host-neutral.
+bounded support window after the first visible frame exists: it logs once,
+disables its mouse-mode lease, and leaves tracking and lifecycle observers
+running. A slow spawn wave therefore does not spend the support window before
+there is anything to hover. Pi imports for the controller and overlay stay
+under `src/host/pi/hover-preview/**`; the renderer, lease, config resolver, and
+tmux plumbing remain host-neutral.
 
 ## Window Targeting: Stable IDs First, Names as Identity Check, Indices Never
 

src/host/pi/hover-preview/controller.ts

@@ -107,26 +107,21 @@ export class HoverPreviewController {
     this.unsubscribeInput = this.deps.registerInputListener(handler);
     this.transition({ kind: "armed-on-mount" }, "mount");
 
-    // There is no portable positive acknowledgement for terminal mouse mode.
-    // Keep a bounded, unref'd fallback: hosts that never deliver an SGR report
-    // get one warning and the controller relinquishes its mode lease.
-    this.mouseSupportTimer = setTimeout(
-      () => {
-        if (this.mounted && !this.disposed) this.abandonMouseSupport();
-      },
-      Math.max(1_000, this.cfg.leaseTtlMs),
-    );
-    const maybeUnref = this.mouseSupportTimer as ReturnType<
-      typeof setTimeout
-    > & {
-      unref?: () => void;
-    };
-    maybeUnref.unref?.();
+    // A widget can mount before the first subagent frame exists. Do not start
+    // the bounded mouse-support fallback until there is something the pointer
+    // can actually hover; a slow spawn wave must not consume the whole grace
+    // period.
+    if (this.hitMap.length > 0) this.armMouseSupportTimer();
     this.deps.onDebug(`[hover-preview] mounted gen=${mountedGeneration}`);
   }
 
   updateHitMap(regions: ReadonlyArray<HitRegion>): void {
     this.hitMap = regions.map((region) => ({ ...region }));
+    if (this.hitMap.length === 0) {
+      this.clearMouseSupportTimer();
+    } else {
+      this.armMouseSupportTimer();
+    }
   }
 
   cprForFirstLine(line: string, lineIndex: number): string {
@@ -402,6 +397,34 @@ export class HoverPreviewController {
     }
   }
 
+  private armMouseSupportTimer(): void {
+    if (
+      !this.mounted ||
+      this.disposed ||
+      this.mouseUnsupported ||
+      this.mouseSupportTimer !== null
+    ) {
+      return;
+    }
+
+    // There is no portable positive acknowledgement for terminal mouse mode.
+    // Keep a bounded, unref'd fallback: hosts that never deliver an SGR report
+    // get one warning and the controller relinquishes its mode lease. This
+    // timer starts only once a visible frame exists (see updateHitMap()).
+    this.mouseSupportTimer = setTimeout(
+      () => {
+        if (this.mounted && !this.disposed) this.abandonMouseSupport();
+      },
+      Math.max(1_000, this.cfg.leaseTtlMs),
+    );
+    const maybeUnref = this.mouseSupportTimer as ReturnType<
+      typeof setTimeout
+    > & {
+      unref?: () => void;
+    };
+    maybeUnref.unref?.();
+  }
+
   private clearHoverTimers(): void {
     this.clearHoverIntentTimer();
     this.clearStickyTimer();

test/hover-preview-controller.test.ts

@@ -137,7 +137,34 @@ describe("HoverPreviewController — mount/dispose", () => {
     const shortCfg = { ...CFG, leaseTtlMs: 1_000 };
     const ctrl = new HoverPreviewController(shortCfg, deps);
     ctrl.mount();
+    ctrl.updateHitMap([
+      { agentId: "a", topRow: 0, bottomRow: 3, leftCol: 0, rightCol: 23 },
+    ]);
+    await vi.advanceTimersByTimeAsync(1_000);
+    expect(deps.notifyCalls).toHaveLength(1);
+    expect(deps.listener.handlers).toHaveLength(0);
+    await ctrl.dispose();
+    vi.useRealTimers();
+  });
+
+  it("does not spend the mouse-support grace period before frames exist", async () => {
+    vi.useFakeTimers();
+    const shortCfg = { ...CFG, leaseTtlMs: 1_000 };
+    const ctrl = new HoverPreviewController(shortCfg, deps);
+    ctrl.mount();
+
     await vi.advanceTimersByTimeAsync(1_000);
+    expect(deps.notifyCalls).toHaveLength(0);
+    expect(deps.listener.handlers).toHaveLength(1);
+
+    ctrl.updateHitMap([
+      { agentId: "a", topRow: 0, bottomRow: 3, leftCol: 0, rightCol: 23 },
+    ]);
+    await vi.advanceTimersByTimeAsync(999);
+    expect(deps.notifyCalls).toHaveLength(0);
+    expect(deps.listener.handlers).toHaveLength(1);
+
+    await vi.advanceTimersByTimeAsync(1);
     expect(deps.notifyCalls).toHaveLength(1);
     expect(deps.listener.handlers).toHaveLength(0);
     await ctrl.dispose();