fix: revalidate hover before dispatch and keep it out of flows

Share one post-scroll hit test for the synthetic and CDP paths, reject a
covered target before any pointer event, and pause recording when a hover
handler navigates. Record why hover is not replayed in a flow.

Author: yashranaway

apps/headless/LinuxHost/BrowserProcess.swift

@@ -778,6 +778,9 @@ final class LinuxBrowserSession: @unchecked Sendable {
         _ = try command("Input.dispatchMouseEvent", parameters: [
             "type": "mouseMoved", "x": target.x, "y": target.y,
         ])
+        // A hover handler can start a cross-document navigation before the next
+        // command. Pause capture so a recording does not composite that frame.
+        pauseRecordingCapture()
         return .object([
             "hovered": .string(target.reference),
             "role": .string(target.role),

apps/headless/Sources/HeadlessProtocol/Resources/AgentRuntime.js

@@ -707,9 +707,8 @@ if (!globalThis.__headlessAgent) {
       element.click();
       return {clicked: refFor(element), role: role(element), name: name(element)};
     };
-    const hover = args => {
-      const element = target(args);
-      element.scrollIntoView({block: 'center', inline: 'center', behavior: 'instant'});
+    // Hit-test the layout after scroll, before any pointer event.
+    const pointerHit = element => {
       if (!visible(element)) fail('ELEMENT_NOT_FOUND', 'ELEMENT_NOT_VISIBLE');
       const rect = element.getBoundingClientRect();
       const left = Math.max(0, rect.left);
@@ -723,10 +722,16 @@ if (!globalThis.__headlessAgent) {
       if (!hit || (hit !== element && !element.contains(hit))) {
         fail('ELEMENT_NOT_FOUND', 'ELEMENT_OBSCURED');
       }
+      return {x, y};
+    };
+    const hover = args => {
+      const element = target(args);
+      element.scrollIntoView({block: 'center', inline: 'center', behavior: 'instant'});
+      const point = pointerHit(element);
       const Pointer = typeof PointerEvent === 'function' ? PointerEvent : MouseEvent;
-      const pointer = {bubbles: true, clientX: x, clientY: y, pointerId: 1,
+      const pointer = {bubbles: true, clientX: point.x, clientY: point.y, pointerId: 1,
         pointerType: 'mouse', isPrimary: true};
-      const mouse = {bubbles: true, clientX: x, clientY: y};
+      const mouse = {bubbles: true, clientX: point.x, clientY: point.y};
       const previous = hoveredElement instanceof Element && hoveredElement.isConnected
         ? hoveredElement : null;
       hoveredElement = element;
@@ -765,26 +770,24 @@ if (!globalThis.__headlessAgent) {
         if (!editable || element.disabled || element.readOnly) throw new Error('NOT_EDITABLE');
       }
       element.scrollIntoView({block: 'center', inline: 'center', behavior: 'instant'});
-      if (action !== 'hover') element.focus({preventScroll: true});
-      if (action === 'hover' && !visible(element)) {
-        fail('ELEMENT_NOT_FOUND', 'ELEMENT_NOT_VISIBLE');
+      if (action === 'hover') {
+        const point = pointerHit(element);
+        return {
+          ref: refFor(element), role: role(element), name: name(element),
+          x: point.x, y: point.y,
+        };
       }
+      element.focus({preventScroll: true});
       const rect = element.getBoundingClientRect();
       const left = Math.max(0, rect.left);
       const right = Math.min(innerWidth, rect.right);
       const top = Math.max(0, rect.top);
       const bottom = Math.min(innerHeight, rect.bottom);
-      if (right <= left || bottom <= top) {
-        if (action === 'hover') fail('ELEMENT_NOT_FOUND', 'ELEMENT_NOT_VISIBLE');
-        throw new Error('ELEMENT_NOT_VISIBLE');
-      }
+      if (right <= left || bottom <= top) throw new Error('ELEMENT_NOT_VISIBLE');
       const x = left + (right - left) / 2;
       const y = top + (bottom - top) / 2;
       const hit = document.elementFromPoint(x, y);
-      if (!hit || (hit !== element && !element.contains(hit))) {
-        if (action === 'hover') fail('ELEMENT_NOT_FOUND', 'ELEMENT_OBSCURED');
-        throw new Error('ELEMENT_OBSCURED');
-      }
+      if (!hit || (hit !== element && !element.contains(hit))) throw new Error('ELEMENT_OBSCURED');
       return {ref: refFor(element), role: role(element), name: name(element), x, y};
     };
     const checkedFileInput = element => {

apps/headless/Tests/agent-runtime.test.mjs

@@ -289,6 +289,29 @@ assert.throws(
   error => error.headlessCode === 'ELEMENT_NOT_FOUND' && error.message === 'ELEMENT_NOT_VISIBLE',
 );
 secondButton.style.opacity = '1';
+window.document.elementFromPoint = () => window.document.body;
+const coveredEvents = secondHoverEvents.length;
+assert.throws(
+  () => agent.hover({target: hiddenHoverRef}),
+  error => error.headlessCode === 'ELEMENT_NOT_FOUND' && error.message === 'ELEMENT_OBSCURED',
+);
+assert.throws(
+  () => agent.inputTarget({target: hiddenHoverRef}, 'hover'),
+  error => error.headlessCode === 'ELEMENT_NOT_FOUND' && error.message === 'ELEMENT_OBSCURED',
+);
+assert.equal(secondHoverEvents.length, coveredEvents, 'obscured hover must not dispatch');
+secondButton.remove();
+assert.throws(
+  () => agent.hover({target: hiddenHoverRef}),
+  error => error.headlessCode === 'ELEMENT_NOT_FOUND' && /detached/.test(error.message),
+);
+const staleHoverRef = agent.snapshot(false, false, {context: 'actions', limit: 20})
+  .elements.find(element => element.name === 'Runtime action').ref;
+agent.snapshot(false, false, {context: 'text', limit: 1});
+assert.throws(
+  () => agent.hover({target: staleHoverRef}),
+  error => error.headlessCode === 'ELEMENT_NOT_FOUND' && /expired/.test(error.message),
+);
 window.document.elementFromPoint = () => button;
 
 const clicked = agent.click({role: 'button', name: 'Runtime action'});

apps/headless/docs/COMMANDS.md

@@ -244,8 +244,11 @@ back | reload
   semantic target (`--role`/`--name`). `fill` accepts a reference; `press` acts
   on the focused control. On Linux click, fill, and key input dispatch trusted
   CDP events; WebKit uses synthetic input. Hover does not focus or click its
-  target and returns no coordinates. Native select and hover dispatch are
-  declared separately by capabilities.
+  target and returns no coordinates. Before dispatch it resolves a ref from the
+  latest inspection only, then rejects a stale, detached, hidden, or
+  center-covered target. Hover is not a flow step: a flow replays commands, and
+  a later replay would not reproduce a transient pointer state. Native select
+  and hover dispatch are declared separately by capabilities.
 - `fill REF -- value` keeps leading dashes in the value. Flow recordings never
   record fill values.
 - `select` supports native single-selection HTML controls only. Choose exactly

apps/headless/docs/P2.md

@@ -91,15 +91,21 @@ operation on both engines. The capability matrix reports this separately as
 `selectDispatch: synthetic-dom`, so Chromium's `inputDispatch: trusted-cdp`
 claim remains limited to click, fill, and key input.
 
-`hover` accepts the same ref or role/name target grammar as `click`. Chromium
-resolves and hit-tests the target in the isolated world, then dispatches one
-trusted CDP mouse move. WebKit emits one fixed synthetic pointer/mouse hover
-transition sequence but cannot activate CSS `:hover`. `hoverDispatch` declares
-the difference. Neither path focuses, clicks, returns coordinates, accepts
-selectors, or exposes caller JavaScript. Page hover handlers may navigate or
-cause other page side effects under the normal browser safety policies. Hover
-is not replayed in flows and is not advertised in action hints because
-meaningful hover behavior cannot be inferred from markup.
+`hover` accepts the same ref or role/name target grammar as `click`. A ref
+resolves only from the latest inspection, so a later inspect or document
+refresh expires it. After scrolling the target into view, both engines reject
+a detached, hidden, or center-covered target before any pointer event.
+Chromium then dispatches one trusted CDP mouse move. WebKit emits one fixed
+synthetic pointer/mouse hover transition sequence but cannot activate CSS
+`:hover`. `hoverDispatch` declares the difference. Neither path focuses,
+clicks, returns coordinates, accepts selectors, or exposes caller JavaScript.
+Page hover handlers may navigate or cause other page side effects under the
+normal browser safety policies. Hover is not a flow step. A flow replays
+commands later, and a replayed hover would not restore the pointer or, on
+WebKit, CSS `:hover`. Screenshot series store images from the capture that
+just ran. Those images are not commands, so a series is not replayed either.
+Inspection does not advertise hover because markup cannot prove that hovering
+has meaningful behavior.
 
 The Linux host accepts only a qualified non-Snap runtime for this CDP pipe.
 Automatic selection prefers an installed bundled runtime and native browser

docs/roadmap/architecture-decisions.md

@@ -1171,21 +1171,33 @@ a narrower region instead of yielding partial or misleading evidence.
 ## 37. Hover is semantic, bounded, and dispatch-accurate
 
 **Decision:** protocol `0.5` gains one compatible portable `hover` command with
-the same fresh element-ref or exact role/name target grammar as `click`. The
-isolated runtime scrolls the target to the viewport and rejects missing, stale, hidden,
-detached, or center-point-obscured targets before dispatch. The public response
-contains only the bounded target ref, role, and name. It never returns the
-internal hit-test coordinates.
-
-Chromium performs one trusted `Input.dispatchMouseEvent` mouse move after the
-isolated-world target check. WebKit tracks the previous synthetic target and
-emits fixed pointer/mouse leave, enter, and move transitions. The capability
-matrix reports `hoverDispatch` as `trusted-cdp` or `synthetic-dom`. The command
-never focuses or clicks directly, accepts selectors or coordinates, or exposes
+the same fresh element-ref or exact role/name target grammar as `click`. A ref
+resolves only against the latest inspection. A later inspect or a document
+refresh expires it, and a detached node fails closed. After scrolling the
+target into view, both engines reject a hidden target and a target whose
+viewport center is covered by another element, including a dropdown or other
+overlay, before any pointer event. The public response contains only the
+bounded target ref, role, and name. It never returns the internal hit-test
+coordinates.
+
+Chromium performs one trusted `Input.dispatchMouseEvent` mouse move after that
+check. WebKit tracks the previous synthetic target and emits fixed
+pointer/mouse leave, enter, and move transitions. The capability matrix
+reports `hoverDispatch` as `trusted-cdp` or `synthetic-dom`. The command never
+focuses or clicks directly, accepts selectors or coordinates, or exposes
 caller JavaScript. Page-controlled hover handlers can still navigate or cause
 other page side effects, subject to the existing navigation and download
-policies. Hover is not a replayable flow step. Inspection does not advertise
-hover because markup cannot prove that hovering has meaningful behavior.
+policies.
+
+Hover is not a flow step. A flow replays commands later. Hover only describes
+where the pointer is now, and WebKit's synthetic sequence does not activate
+CSS `:hover`, so a replay would not reproduce the revealed surface. Screenshot
+series are saved images from one capture. They are not replayed commands, so
+they are not flow steps either. Hover follows that rule. A hover that reveals
+a login form still returns `AUTH_REQUIRED` through the existing challenge
+path, and the hover itself is not stored for replay. Inspection does not
+advertise hover because markup cannot prove that hovering has meaningful
+behavior.
 
 Generic drag remains deferred to
 [#208](https://github.com/LockInTime/headless/issues/208). That contract must