// DOM interaction tools — click, hover, focus/blur, fill, press, and select.
//
// All interaction tools:
// 1. Resolve target tab (sandbox: must be inside Agent Window).
// 2. Resolve target element by `ref` (compound frame/session identity)
//    or `selector` (DOM.querySelector + describeNode).
// 3. Scroll the node and its frame owners into view, project its live
//    content quad into the top viewport, then dispatch `Input.*` events.
// 4. Honour `AbortSignal` so canceled calls don't issue follow-up CDP
//    commands.

import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
import type { CdpTarget } from "@/browser-driver/frame-graph";
import type { SessionContext, SessionManager } from "@/session-manager/manager";
import type {
  BlurParams,
  BlurResult,
  ClickParams,
  ClickResult,
  FillParams,
  FillResult,
  FocusParams,
  FocusResult,
  HoverParams,
  HoverResult,
  KeyModifier,
  MouseButton,
  PressParams,
  PressResult,
  RpcError,
  SelectParams,
  SelectResult,
} from "@/transport/types";
import { attachDialogs, markDialogCursor } from "./dialogs";
import { backendNodeToObject } from "./element-geometry";
import { rpcError } from "./errors";
import { resolveNodeGeometry, scrollElementAndFramesIntoView } from "./frame-geometry";
import {
  type CdpRunner,
  type ChromeTabsApi,
  cdpRunnerForTarget,
  chromeTabsApi,
  enforceAgentWindow,
  isRpcError,
  lookupSession,
  type ResolvedTargetTab,
  resolveTargetTab,
} from "./shared";
import { resolveSnapshotRef } from "./snapshot-ref";

export interface InteractionDeps {
  cdp: CdpRunner;
  tabsApi: ChromeTabsApi;
  /** Abort hook (full chain wired in M10.2). */
  signal?: AbortSignal;
  defaultTimeoutMs?: number;
  /** Temporarily disable overlay click blocker during CDP automation. */
  bypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
  /** Keep hover hit-testing active for the caller's next observation/action. */
  keepOverlayBypassAfterHover?: boolean;
}

export interface ResolvedActionTarget {
  tab: ResolvedTargetTab;
  backendNodeId: number;
  cdpTarget: CdpTarget;
  frameId?: string;
  usedRef?: string;
  usedSelector?: string;
}

const DEFAULT_TIMEOUT_MS = 30_000;
const DEFAULT_HOVER_SETTLE_MS = 200;

let defaultDeps: { cdp: ChromiumCdp; tabsApi: ChromeTabsApi } | null = null;
function getDefaultDeps(): { cdp: ChromiumCdp; tabsApi: ChromeTabsApi } {
  if (!defaultDeps) {
    defaultDeps = { cdp: new ChromiumCdp(), tabsApi: chromeTabsApi };
  }
  return defaultDeps;
}

/**
 * Fold a list of `KeyModifier`s into CDP's bit layout (§4 of the
 * CDP Input domain): alt=1, ctrl=2, meta=4, shift=8.
 *
 * Exported for unit tests.
 */
export function modifiersBitfield(mods: KeyModifier[] | undefined): number {
  if (!mods) return 0;
  let bits = 0;
  for (const m of mods) {
    switch (m) {
      case "alt":
        bits |= 1;
        break;
      case "ctrl":
        bits |= 2;
        break;
      case "meta":
        bits |= 4;
        break;
      case "shift":
        bits |= 8;
        break;
    }
  }
  return bits;
}

function throwIfAborted(signal: AbortSignal | undefined): RpcError | null {
  if (signal?.aborted) {
    return { code: "cancelled", message: "interaction aborted" };
  }
  return null;
}

function isAbortLikeError(err: unknown): boolean {
  return err instanceof DOMException && err.name === "AbortError";
}

async function wait(ms: number, signal?: AbortSignal): Promise<void> {
  if (signal?.aborted) throw new DOMException("aborted", "AbortError");
  await new Promise<void>((resolve, reject) => {
    const cleanup = () => signal?.removeEventListener("abort", onAbort);
    const timer = setTimeout(() => {
      cleanup();
      resolve();
    }, ms);
    const onAbort = () => {
      clearTimeout(timer);
      cleanup();
      reject(new DOMException("aborted", "AbortError"));
    };
    signal?.addEventListener("abort", onAbort, { once: true });
  });
}

/**
 * Resolve `{ref?, selector?}` into a `backendNodeId`. Returns an
 * `RpcError` if the caller supplied neither (or both), or if neither
 * lookup matched.
 */
export async function resolveBackendNode(
  cdp: CdpRunner,
  ctx: SessionContext,
  target: { tabId: number },
  params: { ref?: string; selector?: string },
  toolName: string,
): Promise<
  | {
      backendNodeId: number;
      cdpTarget: CdpTarget;
      frameId?: string;
      usedRef?: string;
      usedSelector?: string;
    }
  | RpcError
> {
  const hasRef = typeof params.ref === "string" && params.ref.length > 0;
  const hasSelector = typeof params.selector === "string" && params.selector.length > 0;
  if (hasRef && hasSelector) {
    return {
      code: "invalid_params",
      message: `${toolName}: pass either ref or selector, not both`,
    };
  }
  if (!hasRef && !hasSelector) {
    return {
      code: "invalid_params",
      message: `${toolName} requires a ref or a selector`,
    };
  }
  if (hasRef) {
    const resolved = resolveSnapshotRef(ctx, params.ref as string, target.tabId);
    if (isRpcError(resolved)) return resolved;
    return {
      backendNodeId: resolved.backendNodeId,
      cdpTarget: {
        tabId: target.tabId,
        ...(resolved.cdpSessionId ? { sessionId: resolved.cdpSessionId } : {}),
      },
      ...(resolved.frameId ? { frameId: resolved.frameId } : {}),
      usedRef: resolved.refKey,
    };
  }
  // selector path
  try {
    // Selector lookup itself attaches CDP, even when no element is found.
    cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
    const doc = await cdp.send<{ root?: { nodeId?: number } }>(target.tabId, "DOM.getDocument", {
      depth: 0,
    });
    const rootNodeId = doc.root?.nodeId;
    if (typeof rootNodeId !== "number") {
      return {
        code: "cdp_failed",
        message: "DOM.getDocument returned no root nodeId",
      };
    }
    const found = await cdp.send<{ nodeId?: number }>(target.tabId, "DOM.querySelector", {
      nodeId: rootNodeId,
      selector: params.selector,
    });
    if (typeof found.nodeId !== "number" || found.nodeId === 0) {
      return rpcError(
        "not_found",
        "selector_not_found",
        `selector ${params.selector} did not match any element`,
      );
    }
    const described = await cdp.send<{ node?: { backendNodeId?: number } }>(
      target.tabId,
      "DOM.describeNode",
      { nodeId: found.nodeId },
    );
    const backendNodeId = described.node?.backendNodeId;
    if (typeof backendNodeId !== "number") {
      return {
        code: "cdp_failed",
        message: "DOM.describeNode returned no backendNodeId",
      };
    }
    return { backendNodeId, cdpTarget: { tabId: target.tabId }, usedSelector: params.selector };
  } catch (err) {
    return {
      code: "cdp_failed",
      message: err instanceof Error ? err.message : String(err),
    };
  }
}

// Check the target's own root, then its hosts: closed shadow roots are not
// reachable via host.shadowRoot. DOM focus remains meaningful in background tabs.
const FOCUS_CHECK = `function() {
  if (!this.isConnected) return false;
  let element = this;
  while (element) {
    const root = element.getRootNode();
    if (root.activeElement !== element) return false;
    element = root.host;
  }
  return true;
}`;

const BLUR_TARGET = `function() {
  if (!this.isConnected) throw new Error('blur target is detached');
  const wasFocused = (${FOCUS_CHECK}).call(this);
  if (typeof this.blur !== 'function') return { ok: false, was_focused: wasFocused };
  this.blur();
  return { ok: true, was_focused: wasFocused };
}`;

interface FocusScriptReply<T> {
  result?: { value?: T };
  exceptionDetails?: { text?: string; exception?: { description?: string } };
}

function checkFocusAbort(signal: AbortSignal | undefined): void {
  if (signal?.aborted) throw new DOMException("interaction aborted", "AbortError");
}

// Only focus/blur use this view. Guard every CDP boundary, including commands
// inside selector resolution and frame scrolling, without changing other tools.
function focusCdp(cdp: CdpRunner, signal: AbortSignal | undefined): CdpRunner {
  const send = <T = unknown>(target: CdpTarget, method: string, params?: object): Promise<T> => {
    checkFocusAbort(signal);
    return cdpRunnerForTarget(cdp, target).send<T>(target.tabId, method, params);
  };
  return {
    send: (tabId, method, params) => send({ tabId }, method, params),
    sendToTarget: send,
    trackSessionTab: cdp.trackSessionTab?.bind(cdp),
    getFrameGraph: cdp.getFrameGraph
      ? (tabId) => {
          checkFocusAbort(signal);
          return cdp.getFrameGraph!(tabId);
        }
      : undefined,
  };
}

// ---------------------------------------------------------------------------
// tool.focus / tool.blur
// ---------------------------------------------------------------------------

export function handleFocus(
  manager: SessionManager,
  params: FocusParams,
  deps: InteractionDeps = getDefaultDeps(),
): Promise<FocusResult | RpcError> {
  return changeFocus(manager, params, deps, "focus");
}

export function handleBlur(
  manager: SessionManager,
  params: BlurParams,
  deps: InteractionDeps = getDefaultDeps(),
): Promise<BlurResult | RpcError> {
  return changeFocus(manager, params, deps, "blur");
}

function changeFocus(
  manager: SessionManager,
  params: FocusParams,
  deps: InteractionDeps,
  action: "focus",
): Promise<FocusResult | RpcError>;
function changeFocus(
  manager: SessionManager,
  params: BlurParams,
  deps: InteractionDeps,
  action: "blur",
): Promise<BlurResult | RpcError>;
async function changeFocus(
  manager: SessionManager,
  params: FocusParams | BlurParams,
  deps: InteractionDeps,
  action: "focus" | "blur",
): Promise<FocusResult | BlurResult | RpcError> {
  const ctx = lookupSession(manager, params, action);
  if (isRpcError(ctx)) return ctx;
  const cdp = focusCdp(deps.cdp, deps.signal);
  let objectId: string | undefined;
  let cleanupCdp: CdpRunner | undefined;
  let tabId: number | undefined;
  try {
    checkFocusAbort(deps.signal);
    const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
    checkFocusAbort(deps.signal);
    if (isRpcError(target)) return target;
    const denied = enforceAgentWindow(ctx, target, action);
    if (denied) return denied;
    tabId = target.tabId;
    const dialogCursor = markDialogCursor(deps.cdp, tabId);
    const node = await resolveBackendNode(cdp, ctx, target, params, action);
    checkFocusAbort(deps.signal);
    if (isRpcError(node)) return node;
    const nodeCdp = cdpRunnerForTarget(cdp, node.cdpTarget);
    cleanupCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);
    deps.cdp.trackSessionTab?.(ctx.sessionId, tabId);

    if (action === "focus") {
      const scrollErr = await scrollElementAndFramesIntoView(
        cdp,
        tabId,
        node.cdpTarget,
        node.backendNodeId,
        node.frameId,
      );
      checkFocusAbort(deps.signal);
      if (scrollErr) return scrollErr;
    }
    const resolved = await backendNodeToObject(nodeCdp, tabId, node.backendNodeId);
    // Keep the handle before checking cancellation so finally can release it.
    if (!isRpcError(resolved)) objectId = resolved;
    checkFocusAbort(deps.signal);
    if (isRpcError(resolved)) return resolved;

    const runScript = async <T>(functionDeclaration: string): Promise<T | undefined> => {
      const reply = await nodeCdp.send<FocusScriptReply<T>>(
        target.tabId,
        "Runtime.callFunctionOn",
        {
          objectId,
          functionDeclaration,
          returnByValue: true,
        },
      );
      checkFocusAbort(deps.signal);
      if (reply.exceptionDetails) {
        const details = reply.exceptionDetails;
        throw new Error(
          `${action} script failed: ${details.exception?.description ?? details.text ?? "unknown exception"}`,
        );
      }
      return reply.result?.value;
    };

    let wasFocused: boolean | undefined;
    if (action === "focus") {
      await nodeCdp.send(tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
      checkFocusAbort(deps.signal);
    } else {
      const mutation = await runScript<{ ok: boolean; was_focused: boolean }>(BLUR_TARGET);
      if (typeof mutation?.ok !== "boolean" || typeof mutation.was_focused !== "boolean") {
        throw new Error("blur script returned an unexpected result");
      }
      if (!mutation.ok) {
        return { code: "invalid_params", message: "target element does not support blur()" };
      }
      wasFocused = mutation.was_focused;
    }
    // Use a separate call so microtasks from focus/blur handlers finish before
    // we report success. In particular, a blur handler can restore focus.
    const focused = await runScript<boolean>(FOCUS_CHECK);
    if (typeof focused !== "boolean") {
      throw new Error(`${action} verification returned an unexpected result`);
    }
    if (focused !== (action === "focus")) {
      throw new Error(
        action === "focus"
          ? "target element did not become focused"
          : "target element remained focused after blur()",
      );
    }
    return attachDialogs(deps.cdp, tabId, dialogCursor, {
      tab_id: tabId,
      used_ref: node.usedRef,
      used_selector: node.usedSelector,
      focused,
      ...(action === "blur" ? { was_focused: wasFocused! } : {}),
    });
  } catch (err) {
    return (
      throwIfAborted(deps.signal) ?? {
        code: "cdp_failed",
        message: err instanceof Error ? err.message : String(err),
      }
    );
  } finally {
    if (objectId !== undefined && cleanupCdp && tabId !== undefined) {
      // Cleanup must also run after cancellation. Navigation may have already
      // disposed the object, which must not replace the operation's result.
      try {
        await cleanupCdp.send(tabId, "Runtime.releaseObject", { objectId });
      } catch {
        // The target or execution context may no longer exist.
      }
    }
  }
}

export async function resolveActionTarget(
  cdp: CdpRunner,
  ctx: SessionContext,
  target: ResolvedTargetTab,
  params: { ref?: string; selector?: string },
  toolName: string,
): Promise<ResolvedActionTarget | RpcError> {
  const node = await resolveBackendNode(cdp, ctx, target, params, toolName);
  return isRpcError(node) ? node : { tab: target, ...node };
}

// ---------------------------------------------------------------------------
// tool.click
// ---------------------------------------------------------------------------

export async function handleClick(
  manager: SessionManager,
  params: ClickParams,
  deps: InteractionDeps = getDefaultDeps(),
): Promise<ClickResult | RpcError> {
  const ctxOrErr = lookupSession(manager, params, "click");
  if (isRpcError(ctxOrErr)) return ctxOrErr;
  const ctx = ctxOrErr;
  const aborted = throwIfAborted(deps.signal);
  if (aborted) return aborted;
  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
  if (isRpcError(target)) return target;
  const denied = enforceAgentWindow(ctx, target, "click");
  if (denied) return denied;
  const resolved = await resolveActionTarget(deps.cdp, ctx, target, params, "click");
  if (isRpcError(resolved)) return resolved;
  return clickResolvedTarget(ctx, resolved, params, deps);
}

export async function clickResolvedTarget(
  ctx: SessionContext,
  resolved: ResolvedActionTarget,
  params: Pick<ClickParams, "button" | "click_count" | "modifiers">,
  deps: InteractionDeps,
): Promise<ClickResult | RpcError> {
  const { tab: target } = resolved;
  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "click aborted" };
  }

  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
  const geometry = await resolveNodeGeometry(
    deps.cdp,
    target.tabId,
    {
      target: resolved.cdpTarget,
      backendNodeId: resolved.backendNodeId,
      ...(resolved.frameId ? { frameId: resolved.frameId } : {}),
    },
    { scrollIntoView: true },
  );
  if (isRpcError(geometry)) return geometry;
  const centre = geometry.actionPoint;

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "click aborted" };
  }

  const button: MouseButton = params.button ?? "left";
  const clickCount = params.click_count ?? 1;
  if (clickCount < 1) {
    return { code: "invalid_params", message: "click_count must be greater than zero" };
  }
  const modifiers = modifiersBitfield(params.modifiers);

  const overlayBlocking = await checkOverlayAtPoint(deps.cdp, target.tabId, centre.x, centre.y);
  let automationBypassEnabled = false;
  if (overlayBlocking && deps.bypassOverlay) {
    try {
      await deps.bypassOverlay(target.tabId, true);
      automationBypassEnabled = true;
    } catch (err) {
      console.debug("[bsk interaction] overlay bypass enable failed", err);
    }
  }

  try {
    // Move first so hover state activates, then press → release.
    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
      type: "mouseMoved",
      x: centre.x,
      y: centre.y,
      modifiers,
    });
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "click aborted" };
    }
    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
      type: "mousePressed",
      x: centre.x,
      y: centre.y,
      button,
      clickCount,
      modifiers,
    });
    if (throwIfAborted(deps.signal)) {
      try {
        await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
          type: "mouseReleased",
          x: centre.x,
          y: centre.y,
          button,
          clickCount,
          modifiers,
        });
      } catch (err) {
        console.debug("[bsk interaction] best-effort mouseReleased after abort failed", err);
      }
      return { code: "cancelled", message: "click aborted" };
    }
    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
      type: "mouseReleased",
      x: centre.x,
      y: centre.y,
      button,
      clickCount,
      modifiers,
    });
  } catch (err) {
    return {
      code: "cdp_failed",
      message: err instanceof Error ? err.message : String(err),
    };
  } finally {
    if (automationBypassEnabled && deps.bypassOverlay && !deps.keepOverlayBypassAfterHover) {
      try {
        await deps.bypassOverlay(target.tabId, false);
      } catch (err) {
        console.debug("[bsk interaction] overlay bypass disable failed", err);
      }
    }
  }

  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
    tab_id: target.tabId,
    used_ref: resolved.usedRef,
    used_selector: resolved.usedSelector,
    x: centre.x,
    y: centre.y,
  });
}

// ---------------------------------------------------------------------------
// tool.hover
// ---------------------------------------------------------------------------

export async function handleHover(
  manager: SessionManager,
  params: HoverParams,
  deps: InteractionDeps = getDefaultDeps(),
): Promise<HoverResult | RpcError> {
  const ctxOrErr = lookupSession(manager, params, "hover");
  if (isRpcError(ctxOrErr)) return ctxOrErr;
  const ctx = ctxOrErr;
  const aborted = throwIfAborted(deps.signal);
  if (aborted) return aborted;
  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
  if (isRpcError(target)) return target;
  const denied = enforceAgentWindow(ctx, target, "hover");
  if (denied) return denied;
  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);

  const node = await resolveBackendNode(deps.cdp, ctx, target, params, "hover");
  if (isRpcError(node)) return node;

  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
  const geometry = await resolveNodeGeometry(
    deps.cdp,
    target.tabId,
    {
      target: node.cdpTarget,
      backendNodeId: node.backendNodeId,
      ...(node.frameId ? { frameId: node.frameId } : {}),
    },
    { scrollIntoView: true },
  );
  if (isRpcError(geometry)) return geometry;
  const centre = geometry.actionPoint;

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "hover aborted" };
  }

  const modifiers = modifiersBitfield(params.modifiers);
  const overlayBlocking = await checkOverlayAtPoint(deps.cdp, target.tabId, centre.x, centre.y);
  let automationBypassEnabled = false;
  let hoverCompleted = false;
  if (overlayBlocking && deps.bypassOverlay) {
    try {
      await deps.bypassOverlay(target.tabId, true);
      automationBypassEnabled = true;
    } catch (err) {
      console.debug("[bsk interaction] overlay bypass enable failed", err);
    }
  }

  try {
    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
      type: "mouseMoved",
      x: centre.x,
      y: centre.y,
      modifiers,
    });
    const settleMs = params.settle_ms ?? DEFAULT_HOVER_SETTLE_MS;
    if (settleMs > 0) {
      await wait(settleMs, deps.signal);
    }
    hoverCompleted = true;
  } catch (err) {
    if (isAbortLikeError(err)) {
      return { code: "cancelled", message: "hover aborted" };
    }
    return {
      code: "cdp_failed",
      message: err instanceof Error ? err.message : String(err),
    };
  } finally {
    if (
      automationBypassEnabled &&
      deps.bypassOverlay &&
      (!deps.keepOverlayBypassAfterHover || !hoverCompleted)
    ) {
      try {
        await deps.bypassOverlay(target.tabId, false);
      } catch (err) {
        console.debug("[bsk interaction] overlay bypass disable failed", err);
      }
    }
  }

  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
    tab_id: target.tabId,
    used_ref: node.usedRef,
    used_selector: node.usedSelector,
    x: centre.x,
    y: centre.y,
  });
}

interface OverlayHitInspection {
  overlayHostPresent: boolean;
  overlayHostConnected: boolean;
  hitIndex: number;
}

/**
 * Returns true when the control overlay shadow root has a visible layer
 * with pointer-events blocking the click point (mirrors intern execClick).
 */
async function checkOverlayAtPoint(
  cdp: CdpRunner,
  tabId: number,
  x: number,
  y: number,
): Promise<boolean> {
  try {
    const hitTest = await cdp.send<{
      result?: {
        value?: {
          overlayHostPresent?: boolean;
          overlayHostConnected?: boolean;
        } | null;
      };
    }>(tabId, "Runtime.evaluate", {
      expression: `(function() {
        const overlayHost = document.querySelector("[data-bsk-overlay]");
        return {
          overlayHostPresent: !!overlayHost,
          overlayHostConnected: !!overlayHost?.isConnected,
        };
      })()`,
      returnByValue: true,
    });

    const hitTarget = hitTest.result?.value ?? null;
    if (!hitTarget?.overlayHostPresent || !hitTarget.overlayHostConnected) {
      return false;
    }

    const inspection = await cdp.send<{
      result?: { value?: OverlayHitInspection | null };
    }>(tabId, "Runtime.evaluate", {
      expression: `(function() {
        const overlayHost = document.querySelector("[data-bsk-overlay]");
        const shadowRoot = overlayHost instanceof HTMLElement ? overlayHost.shadowRoot : null;
        const overlays = Array.from(shadowRoot?.querySelectorAll("*") ?? []);
        const overlayDetails = overlays
          .map((node) => {
            if (!(node instanceof HTMLElement)) return null;
            const style = window.getComputedStyle(node);
            const rect = node.getBoundingClientRect();
            return {
              display: style.display,
              pointerEvents: style.pointerEvents,
              connected: node.isConnected,
              rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
            };
          })
          .filter((node) => {
            if (!node) return false;
            return (
              node.connected &&
              node.display !== "none" &&
              node.pointerEvents !== "none" &&
              node.rect.width > 0 &&
              node.rect.height > 0
            );
          });
        const hitIndex = overlayDetails.findIndex((node) => {
          const withinX = ${x} >= node.rect.x && ${x} <= node.rect.x + node.rect.width;
          const withinY = ${y} >= node.rect.y && ${y} <= node.rect.y + node.rect.height;
          return withinX && withinY;
        });
        return {
          overlayHostPresent: true,
          overlayHostConnected: true,
          hitIndex,
        };
      })()`,
      returnByValue: true,
    });

    const value = inspection.result?.value;
    return (value?.hitIndex ?? -1) >= 0;
  } catch (err) {
    console.debug("[bsk interaction] overlay hit-test failed", err);
    return false;
  }
}

/**
 * Describes the subset of `DOM.describeNode`'s `node` we inspect to
 * decide whether the target is fillable. `attributes` is the CDP
 * flat-array form (`[name, value, name, value, ...]`).
 */
interface DescribedNode {
  nodeName?: string;
  attributes?: string[];
}

/**
 * Decide whether a node can receive `tool.fill`: native `<input>` /
 * `<textarea>`, or any element flagged `contenteditable="true"`.
 * Exported via `__testing__` for unit coverage.
 */
function isFillable(node: DescribedNode): boolean {
  const tag = (node.nodeName ?? "").toUpperCase();
  if (tag === "INPUT" || tag === "TEXTAREA") return true;
  const attrs = node.attributes ?? [];
  for (let i = 0; i + 1 < attrs.length; i += 2) {
    if (attrs[i].toLowerCase() === "contenteditable") {
      const value = attrs[i + 1].toLowerCase();
      return value === "" || value === "true" || value === "plaintext-only";
    }
  }
  return false;
}

type SelectMutationResult =
  | {
      ok: true;
      multiple: boolean;
      selected_values: string[];
      selected_labels: string[];
    }
  | {
      ok: false;
      reason: "option_not_found";
      missing?: string;
    };

// ---------------------------------------------------------------------------
// tool.fill
// ---------------------------------------------------------------------------

type FillFailureReason =
  | "target_not_fillable"
  | "fill_value_invalid"
  | "fill_target_changed"
  | "fill_focus_lost"
  | "fill_value_mismatch"
  | "fill_failed";

type FillPreparation =
  | { before: string; expected: string }
  | { reason: FillFailureReason; error: string };

type FillReadiness = "ready" | "background" | "fill_target_changed" | "fill_focus_lost";

function fillError(reason: FillFailureReason, message: string): RpcError {
  return rpcError(
    reason === "target_not_fillable" || reason === "fill_value_invalid"
      ? "invalid_params"
      : "cdp_failed",
    reason,
    message,
  );
}

interface FillScriptReply<T> {
  result?: { value?: T };
  exceptionDetails?: unknown;
}

const FILL_EDITABLE_FUNCTION = `function() {
  const tag = this.tagName.toLowerCase();
  const supported = tag === 'input'
    ? ['text', 'search', 'tel', 'url', 'email', 'password', 'number'].includes(this.type)
    : tag === 'textarea' || this.isContentEditable;
  return this.isConnected && supported && !this.readOnly && !this.matches(':disabled');
}`;

// Chrome renders a trailing editable newline with an empty <div><br></div>.
// innerText includes the padding break; it is not an extra typed character.
const FILL_VALUE_FUNCTION = `function() {
  if (!this.isContentEditable) return this.value;
  const value = this.innerText;
  const tail = this.lastChild;
  const padding = tail && tail.nodeName === 'DIV' && tail.childNodes.length === 1 && tail.firstChild.nodeName === 'BR';
  return padding && value.endsWith('\\n\\n') ? value.slice(0, -1) : value;
}`;

export async function handleFill(
  manager: SessionManager,
  params: FillParams,
  deps: InteractionDeps = getDefaultDeps(),
): Promise<FillResult | RpcError> {
  if (!params || typeof params.value !== "string") {
    return { code: "invalid_params", message: "fill requires a value string" };
  }
  const ctxOrErr = lookupSession(manager, params, "fill");
  if (isRpcError(ctxOrErr)) return ctxOrErr;
  const ctx = ctxOrErr;
  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "fill aborted" };
  }
  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
  if (isRpcError(target)) return target;
  const denied = enforceAgentWindow(ctx, target, "fill");
  if (denied) return denied;
  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);

  const node = await resolveBackendNode(deps.cdp, ctx, target, params, "fill");
  if (isRpcError(node)) return node;
  const nodeCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);

  try {
    deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
    const described = await nodeCdp.send<{ node?: DescribedNode }>(
      target.tabId,
      "DOM.describeNode",
      {
        backendNodeId: node.backendNodeId,
      },
    );
    if (!described.node || !isFillable(described.node)) {
      return rpcError(
        "invalid_params",
        "target_not_fillable",
        `element ${described.node?.nodeName ?? "?"} not fillable (need input/textarea/contenteditable)`,
      );
    }
    const scrollErr = await scrollElementAndFramesIntoView(
      deps.cdp,
      target.tabId,
      node.cdpTarget,
      node.backendNodeId,
      node.frameId,
    );
    if (scrollErr) return scrollErr;
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
  } catch (err) {
    return fillError("fill_failed", err instanceof Error ? err.message : String(err));
  }

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "fill aborted" };
  }

  const objectIdOrErr = await backendNodeToObject(nodeCdp, target.tabId, node.backendNodeId);
  if (isRpcError(objectIdOrErr)) return objectIdOrErr;
  const objectId = objectIdOrErr;
  const clearBefore = params.clear_before ?? true;

  try {
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    try {
      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
    } catch (error) {
      // Chrome rejects DOM.focus for disabled controls, including inherited
      // fieldset state. Classify the live target before treating this as a
      // browser failure; the normal path needs no extra round trip.
      const editable = await nodeCdp.send<FillScriptReply<boolean>>(
        target.tabId,
        "Runtime.callFunctionOn",
        { objectId, functionDeclaration: FILL_EDITABLE_FUNCTION, returnByValue: true },
      );
      if (throwIfAborted(deps.signal)) {
        return { code: "cancelled", message: "fill aborted" };
      }
      if (!editable.exceptionDetails && editable.result?.value === false) {
        return fillError(
          "target_not_fillable",
          "fill target is not editable or its input type is unsupported",
        );
      }
      throw error;
    }
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    // Check editability before clearing. Keep the expected result tied to
    // this object, including the existing value on the append path.
    const prepared = await nodeCdp.send<FillScriptReply<FillPreparation>>(
      target.tabId,
      "Runtime.callFunctionOn",
      {
        objectId,
        functionDeclaration: `function(value, clearBefore) {
          const tag = this.tagName.toLowerCase();
          const native = tag === 'input' || tag === 'textarea';
          if (!(${FILL_EDITABLE_FUNCTION}).call(this)) return { reason: 'target_not_fillable', error: 'fill target is not editable or its input type is unsupported' };
          if (this.getRootNode().activeElement !== this) return { reason: 'fill_focus_lost', error: 'fill target does not have focus' };
          const before = clearBefore ? '' : (${FILL_VALUE_FUNCTION}).call(this);
          let expected = before + value;
          if (native) {
            // Use the browser's own value sanitization (e.g. textarea
            // line endings) without changing the live control.
            const normalizer = this.ownerDocument.createElement(tag);
            if (tag === 'input') {
              normalizer.type = this.type;
              normalizer.multiple = this.multiple;
            }
            // insertText treats line breaks in a single-line input as spaces.
            if (tag === 'input') expected = expected.replace(/\\r\\n|\\r|\\n/g, ' ');
            normalizer.value = expected;
            if (expected !== '' && normalizer.value === '' && this.type === 'number') {
              return { reason: 'fill_value_invalid', error: 'fill value is not valid for a number input' };
            }
            expected = normalizer.value;
            if (this.type !== 'number' && this.maxLength >= 0 && expected.length > this.maxLength) {
              return { reason: 'fill_value_invalid', error: 'fill value exceeds the target maxlength' };
            }
          } else {
            expected = expected.replace(/\\r\\n?/g, '\\n');
          }
          if (clearBefore) {
            if (native) {
              const proto = tag === 'textarea' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
              Object.getOwnPropertyDescriptor(proto, 'value').set.call(this, '');
            } else {
              this.textContent = '';
            }
            this.dispatchEvent(new Event('input', { bubbles: true }));
          }
          return { before, expected };
        }`,
        arguments: [{ value: params.value }, { value: clearBefore }],
        returnByValue: true,
      },
    );
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    if (prepared.exceptionDetails) {
      return fillError("fill_failed", "fill preparation script failed");
    }
    const preparation = prepared.result?.value;
    if (preparation && "error" in preparation) {
      return fillError(preparation.reason, preparation.error);
    }
    if (typeof preparation?.before !== "string" || typeof preparation?.expected !== "string") {
      return fillError("fill_failed", "fill preparation returned an unexpected result");
    }
    // A separate call runs after the clearing event's microtasks drain.
    // DOM focus works in background tabs. Use document.hasFocus() only to
    // detect deferred focus events, never to reject background input.
    const checkReady = async (): Promise<FillReadiness | RpcError> => {
      const reply = await nodeCdp.send<FillScriptReply<FillReadiness>>(
        target.tabId,
        "Runtime.callFunctionOn",
        {
          objectId,
          functionDeclaration: `function(before) {
            if (!(${FILL_EDITABLE_FUNCTION}).call(this) ||
                (${FILL_VALUE_FUNCTION}).call(this) !== before) return 'fill_target_changed';
            if (this.getRootNode().activeElement !== this) return 'fill_focus_lost';
            return this.ownerDocument.hasFocus() ? 'ready' : 'background';
          }`,
          arguments: [{ value: preparation.before }],
          returnByValue: true,
        },
      );
      const state = reply.result?.value;
      if (
        reply.exceptionDetails ||
        (state !== "ready" &&
          state !== "background" &&
          state !== "fill_target_changed" &&
          state !== "fill_focus_lost")
      ) {
        return fillError(
          "fill_failed",
          "fill readiness script failed or returned an unexpected result",
        );
      }
      return state;
    };
    let ready = await checkReady();
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    // Restore focus once only if clearing left this same target editable
    // and unchanged. Recheck after focus handlers have run.
    if (clearBefore && ready === "fill_focus_lost") {
      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
      if (throwIfAborted(deps.signal)) {
        return { code: "cancelled", message: "fill aborted" };
      }
      ready = await checkReady();
    }
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    if (typeof ready !== "string") return ready;
    if (ready !== "ready" && ready !== "background") {
      return fillError(ready, "fill target changed or lost focus before typing");
    }
    if (params.value !== "" && (!clearBefore || ready === "background")) {
      // Native editing commands also support number/email inputs, whose
      // selection APIs cannot set a caret, and multiline contenteditables.
      // Also do this for background replacement: CDP input focuses the
      // renderer, delivering deferred focus events before it inserts text.
      // Use a command-only event so this does not invoke an End shortcut.
      try {
        await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
          type: "rawKeyDown",
          commands: ["moveToEndOfDocument"],
        });
      } finally {
        await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", { type: "keyUp" });
      }
      if (throwIfAborted(deps.signal)) {
        return { code: "cancelled", message: "fill aborted" };
      }
      // Focus and key handlers can change the target or move focus too.
      ready = await checkReady();
      if (throwIfAborted(deps.signal)) {
        return { code: "cancelled", message: "fill aborted" };
      }
      if (typeof ready !== "string") return ready;
      if (ready !== "ready" && ready !== "background") {
        return fillError(ready, "fill target changed or lost focus while positioning the caret");
      }
    }
    // CDP `Input.insertText` handles IME / multi-byte input out of the
    // box, much more reliably than per-key `dispatchKeyEvent`.
    if (params.value !== "") {
      await deps.cdp.send(target.tabId, "Input.insertText", { text: params.value });
    }
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    // Keep the existing notifications, then read in a separate call so
    // nested microtasks queued by the page cannot race the verification.
    const notified = await nodeCdp.send<FillScriptReply<unknown>>(
      target.tabId,
      "Runtime.callFunctionOn",
      {
        objectId,
        functionDeclaration: `function() {
          this.dispatchEvent(new Event('input', { bubbles: true }));
          this.dispatchEvent(new Event('change', { bubbles: true }));
        }`,
        returnByValue: true,
      },
    );
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    if (notified.exceptionDetails) {
      return fillError("fill_failed", "fill notification script failed");
    }
    const verified = await nodeCdp.send<
      FillScriptReply<{ connected: boolean; matches: boolean; valueLength: number }>
    >(target.tabId, "Runtime.callFunctionOn", {
      objectId,
      functionDeclaration: `function(expected) {
          const value = (${FILL_VALUE_FUNCTION}).call(this);
          return { connected: this.isConnected, matches: value === expected, valueLength: value.length };
        }`,
      arguments: [{ value: preparation.expected }],
      returnByValue: true,
    });
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
    const verification = verified.result?.value;
    if (
      verified.exceptionDetails ||
      typeof verification?.connected !== "boolean" ||
      typeof verification?.matches !== "boolean" ||
      typeof verification?.valueLength !== "number"
    ) {
      return fillError(
        "fill_failed",
        "fill verification script failed or returned an unexpected result",
      );
    }
    if (!verification.connected) {
      return fillError("fill_target_changed", "fill target was removed or replaced during input");
    }
    if (!verification.matches) {
      return fillError(
        "fill_value_mismatch",
        "fill could not verify the expected value; observe the page before deciding whether to retry",
      );
    }
    return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
      tab_id: target.tabId,
      used_ref: node.usedRef,
      used_selector: node.usedSelector,
      value_length: verification.valueLength,
    });
  } catch (err) {
    return fillError("fill_failed", err instanceof Error ? err.message : String(err));
  } finally {
    await nodeCdp.send(target.tabId, "Runtime.releaseObject", { objectId }).catch(() => undefined);
  }
}

// ---------------------------------------------------------------------------
// tool.press
// ---------------------------------------------------------------------------

const KEY_MODIFIER_SET = new Set<KeyModifier>(["alt", "ctrl", "meta", "shift"]);

/**
 * Normalise a modifier token (case-insensitive, accepts `Control` →
 * `ctrl`, `Cmd`/`Command` → `meta`, `Option`/`Opt` → `alt`). Returns
 * `null` if the token isn't recognised as a modifier.
 */
function normaliseModifier(token: string): KeyModifier | null {
  const lower = token.toLowerCase();
  if (lower === "ctrl" || lower === "control") return "ctrl";
  if (lower === "alt" || lower === "option" || lower === "opt") return "alt";
  if (lower === "shift") return "shift";
  if (lower === "meta" || lower === "cmd" || lower === "command" || lower === "super") {
    return "meta";
  }
  return null;
}

/**
 * Split a compound key spec like `Ctrl+Shift+P` into its modifier
 * list and base key name. Single keys (`Enter`, `a`) come back with
 * an empty modifier list.
 *
 * The split is `+`-delimited; modifier matching is case-insensitive
 * and order-independent. Whitespace around tokens is trimmed.
 */
export function parseKeySpec(spec: string): { key: string; modifiers: KeyModifier[] } {
  const parts = spec
    .split("+")
    .map((s) => s.trim())
    .filter((s) => s.length > 0);
  if (parts.length <= 1) {
    return { key: spec.trim(), modifiers: [] };
  }
  const mods: KeyModifier[] = [];
  let baseKey: string | null = null;
  for (const part of parts) {
    const mod = normaliseModifier(part);
    if (mod) {
      if (!mods.includes(mod)) mods.push(mod);
    } else {
      baseKey = part;
    }
  }
  return { key: baseKey ?? parts[parts.length - 1], modifiers: mods };
}

interface KeyDescriptor {
  key: string;
  code: string;
  text?: string;
  windowsVirtualKeyCode?: number;
}

const SPECIAL_KEYMAP: Record<string, KeyDescriptor> = {
  Enter: { key: "Enter", code: "Enter", text: "\r", windowsVirtualKeyCode: 13 },
  Escape: { key: "Escape", code: "Escape", windowsVirtualKeyCode: 27 },
  Tab: { key: "Tab", code: "Tab", text: "\t", windowsVirtualKeyCode: 9 },
  Backspace: { key: "Backspace", code: "Backspace", windowsVirtualKeyCode: 8 },
  Delete: { key: "Delete", code: "Delete", windowsVirtualKeyCode: 46 },
  Home: { key: "Home", code: "Home", windowsVirtualKeyCode: 36 },
  End: { key: "End", code: "End", windowsVirtualKeyCode: 35 },
  PageUp: { key: "PageUp", code: "PageUp", windowsVirtualKeyCode: 33 },
  PageDown: { key: "PageDown", code: "PageDown", windowsVirtualKeyCode: 34 },
  ArrowLeft: { key: "ArrowLeft", code: "ArrowLeft", windowsVirtualKeyCode: 37 },
  ArrowUp: { key: "ArrowUp", code: "ArrowUp", windowsVirtualKeyCode: 38 },
  ArrowRight: { key: "ArrowRight", code: "ArrowRight", windowsVirtualKeyCode: 39 },
  ArrowDown: { key: "ArrowDown", code: "ArrowDown", windowsVirtualKeyCode: 40 },
  Space: { key: " ", code: "Space", text: " ", windowsVirtualKeyCode: 32 },
};

for (let i = 1; i <= 12; i++) {
  SPECIAL_KEYMAP[`F${i}`] = {
    key: `F${i}`,
    code: `F${i}`,
    windowsVirtualKeyCode: 111 + i,
  };
}

/**
 * Translate a logical key name (`Enter`, `a`, `3`, `F5`, `ArrowDown`)
 * into the CDP `Input.dispatchKeyEvent` descriptor. Returns `null`
 * for keys we don't recognise (caller surfaces `invalid_params`).
 */
export function resolveKeyDescriptor(key: string): KeyDescriptor | null {
  if (key.length === 0) return null;
  if (SPECIAL_KEYMAP[key]) return SPECIAL_KEYMAP[key];
  if (key.length === 1) {
    const ch = key;
    const upper = ch.toUpperCase();
    if (upper >= "A" && upper <= "Z") {
      return {
        key: ch,
        code: `Key${upper}`,
        text: ch,
        windowsVirtualKeyCode: upper.charCodeAt(0),
      };
    }
    if (ch >= "0" && ch <= "9") {
      return {
        key: ch,
        code: `Digit${ch}`,
        text: ch,
        windowsVirtualKeyCode: ch.charCodeAt(0),
      };
    }
    // Common punctuation falls back to `text` only. Browsers
    // synthesise the right code from `text` when CDP can't find one.
    return { key: ch, code: "", text: ch };
  }
  return null;
}

function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
  return new Promise((resolve) => {
    let settled = false;
    let onAbort: (() => void) | null = null;
    const finish = () => {
      if (settled) return;
      settled = true;
      clearTimeout(timer);
      if (onAbort && signal) signal.removeEventListener("abort", onAbort);
      resolve();
    };
    const timer = setTimeout(finish, ms);
    if (signal) {
      onAbort = finish;
      signal.addEventListener("abort", onAbort, { once: true });
    }
  });
}

export async function handlePress(
  manager: SessionManager,
  params: PressParams,
  deps: InteractionDeps = getDefaultDeps(),
): Promise<PressResult | RpcError> {
  if (!params || typeof params.key !== "string" || params.key.length === 0) {
    return { code: "invalid_params", message: "press requires a key string" };
  }
  const ctxOrErr = lookupSession(manager, params, "press");
  if (isRpcError(ctxOrErr)) return ctxOrErr;
  const ctx = ctxOrErr;
  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "press aborted" };
  }
  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
  if (isRpcError(target)) return target;
  const denied = enforceAgentWindow(ctx, target, "press");
  if (denied) return denied;
  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);

  const parsed = parseKeySpec(params.key);
  // Merge param `modifiers` with anything parsed from the compound
  // key string; de-duplicate.
  const mods: KeyModifier[] = [...parsed.modifiers];
  for (const m of params.modifiers ?? []) {
    if (KEY_MODIFIER_SET.has(m) && !mods.includes(m)) mods.push(m);
  }
  const descriptor = resolveKeyDescriptor(parsed.key);
  if (!descriptor) {
    return {
      code: "invalid_params",
      message: `press: unknown key "${parsed.key}"`,
    };
  }

  // Optional focus before key dispatch.
  if (params.ref || params.selector) {
    const node = await resolveBackendNode(deps.cdp, ctx, target, params, "press");
    if (isRpcError(node)) return node;
    const nodeCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);
    try {
      deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
      const scrollErr = await scrollElementAndFramesIntoView(
        deps.cdp,
        target.tabId,
        node.cdpTarget,
        node.backendNodeId,
        node.frameId,
      );
      if (scrollErr) return scrollErr;
      if (throwIfAborted(deps.signal)) {
        return { code: "cancelled", message: "press aborted" };
      }
      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
    } catch (err) {
      return {
        code: "cdp_failed",
        message: err instanceof Error ? err.message : String(err),
      };
    }
  }

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "press aborted" };
  }

  const modifiers = modifiersBitfield(mods);
  // Suppress `text` when any non-shift modifier is held — `Ctrl+a`
  // should not also type the character "a" into the focused field.
  const suppressText = mods.some((m) => m === "ctrl" || m === "meta" || m === "alt");
  try {
    let cancelled = false;
    deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
    await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
      type: "rawKeyDown",
      key: descriptor.key,
      code: descriptor.code,
      windowsVirtualKeyCode: descriptor.windowsVirtualKeyCode,
      modifiers,
    });
    cancelled = throwIfAborted(deps.signal) !== null;
    if (
      !cancelled &&
      !suppressText &&
      typeof descriptor.text === "string" &&
      descriptor.text.length > 0
    ) {
      await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
        type: "char",
        key: descriptor.key,
        code: descriptor.code,
        text: descriptor.text,
        modifiers,
      });
      cancelled = throwIfAborted(deps.signal) !== null;
    }
    if (!cancelled && params.hold_ms && params.hold_ms > 0) {
      await sleep(params.hold_ms, deps.signal);
      if (throwIfAborted(deps.signal)) {
        // Still send keyUp so the page doesn't think the key is stuck
        // down — best-effort.
        cancelled = true;
      }
    }
    await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
      type: "keyUp",
      key: descriptor.key,
      code: descriptor.code,
      windowsVirtualKeyCode: descriptor.windowsVirtualKeyCode,
      modifiers,
    });
    if (cancelled || throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "press aborted" };
    }
  } catch (err) {
    return {
      code: "cdp_failed",
      message: err instanceof Error ? err.message : String(err),
    };
  }

  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
    tab_id: target.tabId,
    key: descriptor.key,
    code: descriptor.code,
    modifiers: mods,
  });
}

// ---------------------------------------------------------------------------
// tool.select
// ---------------------------------------------------------------------------

export async function handleSelect(
  manager: SessionManager,
  params: SelectParams,
  deps: InteractionDeps = getDefaultDeps(),
): Promise<SelectResult | RpcError> {
  if (!params || !Array.isArray(params.values)) {
    return { code: "invalid_params", message: "select requires a values array" };
  }
  if (!params.values.every((value) => typeof value === "string")) {
    return { code: "invalid_params", message: "select values must all be strings" };
  }
  const ctxOrErr = lookupSession(manager, params, "select");
  if (isRpcError(ctxOrErr)) return ctxOrErr;
  const ctx = ctxOrErr;
  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "select aborted" };
  }
  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
  if (isRpcError(target)) return target;
  const denied = enforceAgentWindow(ctx, target, "select");
  if (denied) return denied;
  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);

  const node = await resolveBackendNode(deps.cdp, ctx, target, params, "select");
  if (isRpcError(node)) return node;
  const nodeCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);

  try {
    deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
    const described = await nodeCdp.send<{ node?: DescribedNode }>(
      target.tabId,
      "DOM.describeNode",
      { backendNodeId: node.backendNodeId },
    );
    if (!described.node || (described.node.nodeName ?? "").toUpperCase() !== "SELECT") {
      return rpcError(
        "invalid_params",
        "target_not_select",
        `element ${described.node?.nodeName ?? "?"} not a <select>`,
      );
    }
    const attrs = described.node.attributes ?? [];
    const isMultiple = attrs.some(
      (attr, idx) => idx % 2 === 0 && attr.toLowerCase() === "multiple",
    );
    if (!isMultiple && params.values.length !== 1) {
      return rpcError(
        "invalid_params",
        "single_select_value_count",
        "single-select <select> requires exactly one value",
      );
    }
    const scrollErr = await scrollElementAndFramesIntoView(
      deps.cdp,
      target.tabId,
      node.cdpTarget,
      node.backendNodeId,
      node.frameId,
    );
    if (scrollErr) return scrollErr;
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "select aborted" };
    }
    await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
  } catch (err) {
    return {
      code: "cdp_failed",
      message: err instanceof Error ? err.message : String(err),
    };
  }

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "select aborted" };
  }

  const objectIdOrErr = await backendNodeToObject(nodeCdp, target.tabId, node.backendNodeId);
  if (isRpcError(objectIdOrErr)) return objectIdOrErr;
  const objectId = objectIdOrErr;

  try {
    const evaluated = await nodeCdp.send<{
      result?: { value?: SelectMutationResult | null };
    }>(target.tabId, "Runtime.callFunctionOn", {
      objectId,
      functionDeclaration: `function(values) {
        const select = this;
        const multiple = select.multiple;
        const known = new Set(Array.from(select.options).map((o) => o.value));
        for (const v of values) {
          if (!known.has(v)) {
            return { ok: false, reason: 'option_not_found', missing: v };
          }
        }
        const want = new Set(values);
        for (const opt of select.options) {
          opt.selected = want.has(opt.value);
        }
        select.dispatchEvent(new Event('input', { bubbles: true }));
        select.dispatchEvent(new Event('change', { bubbles: true }));
        const selected = Array.from(select.selectedOptions);
        return {
          ok: true,
          multiple,
          selected_values: selected.map((o) => o.value),
          selected_labels: selected.map((o) => o.text),
        };
      }`,
      arguments: [{ value: params.values }],
      returnByValue: true,
    });
    const mutation = evaluated.result?.value;
    if (!mutation?.ok) {
      if (mutation?.reason === "option_not_found") {
        return rpcError(
          "invalid_params",
          "option_not_found",
          `option value ${mutation.missing ?? "?"} not found in <select>`,
        );
      }
      return { code: "cdp_failed", message: "select mutation returned an unexpected result" };
    }
    return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
      tab_id: target.tabId,
      used_ref: node.usedRef,
      used_selector: node.usedSelector,
      multiple: mutation.multiple,
      selected_values: mutation.selected_values,
      selected_labels: mutation.selected_labels,
    });
  } catch (err) {
    return {
      code: "cdp_failed",
      message: err instanceof Error ? err.message : String(err),
    };
  }
}

export const __testing__ = {
  DEFAULT_TIMEOUT_MS,
  resolveBackendNode,
  isFillable,
};