import { describe, expect, test } from "bun:test";

import {
  captureScreenshotJpeg,
  dispatchClickAt,
  dispatchHoverAt,
  dispatchInsertText,
  dispatchKeyPress,
  dispatchWheelScroll,
  evaluateExpression,
  focusElement,
  getCenterPoint,
  getCurrentUrl,
  getPageTitle,
  navigateAndWait,
  querySelectorBackendNodeId,
  scrollIntoViewIfNeeded,
  waitForSelector,
  waitForText,
} from "../cdp-dom-helpers.js";
import { CdpError } from "../errors.js";
import type { CdpClient } from "../types.js";

// ── Test utilities ────────────────────────────────────────────────────

type CdpCall = { method: string; params?: Record<string, unknown> };

/**
 * Minimal in-memory fake CdpClient. The programmable `handler` is
 * called for every `send` and must return the raw CDP result object
 * (or throw). Every call is recorded on `calls` so tests can assert
 * method order and param shape.
 */
function fakeCdp(
  handler: (method: string, params?: Record<string, unknown>) => unknown,
): CdpClient & { calls: CdpCall[] } {
  const calls: CdpCall[] = [];
  return {
    calls,
    async send<T>(
      method: string,
      params?: Record<string, unknown>,
    ): Promise<T> {
      calls.push({ method, params });
      const value = handler(method, params);
      return (await value) as T;
    },
    dispose() {},
  };
}

// ── querySelectorBackendNodeId ────────────────────────────────────────

describe("querySelectorBackendNodeId", () => {
  test("returns backendNodeId on happy path", async () => {
    const cdp = fakeCdp((method) => {
      switch (method) {
        case "DOM.getDocument":
          return { root: { nodeId: 1 } };
        case "DOM.querySelector":
          return { nodeId: 42 };
        case "DOM.describeNode":
          return { node: { backendNodeId: 777 } };
        default:
          throw new Error(`unexpected method: ${method}`);
      }
    });

    const backendNodeId = await querySelectorBackendNodeId(cdp, "#submit");

    expect(backendNodeId).toBe(777);
    expect(cdp.calls.map((c) => c.method)).toEqual([
      "DOM.getDocument",
      "DOM.querySelector",
      "DOM.describeNode",
    ]);
    expect(cdp.calls[1]!.params).toEqual({ nodeId: 1, selector: "#submit" });
    expect(cdp.calls[2]!.params).toEqual({ nodeId: 42, depth: 0 });
  });

  test("throws CdpError with code 'cdp_error' when nodeId is 0", async () => {
    const cdp = fakeCdp((method) => {
      switch (method) {
        case "DOM.getDocument":
          return { root: { nodeId: 1 } };
        case "DOM.querySelector":
          return { nodeId: 0 };
        default:
          throw new Error(`unexpected method: ${method}`);
      }
    });

    await expect(
      querySelectorBackendNodeId(cdp, "#missing"),
    ).rejects.toMatchObject({
      name: "CdpError",
      code: "cdp_error",
      cdpMethod: "DOM.querySelector",
      cdpParams: { selector: "#missing" },
    });
  });
});

// ── scrollIntoViewIfNeeded ────────────────────────────────────────────

describe("scrollIntoViewIfNeeded", () => {
  test("sends DOM.scrollIntoViewIfNeeded with backendNodeId", async () => {
    const cdp = fakeCdp(() => ({}));
    await scrollIntoViewIfNeeded(cdp, 99);
    expect(cdp.calls).toEqual([
      { method: "DOM.scrollIntoViewIfNeeded", params: { backendNodeId: 99 } },
    ]);
  });

  test("propagates transport errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("transport_error", "socket closed");
    });
    await expect(scrollIntoViewIfNeeded(cdp, 99)).rejects.toMatchObject({
      name: "CdpError",
      code: "transport_error",
    });
  });
});

// ── getCenterPoint ────────────────────────────────────────────────────

describe("getCenterPoint", () => {
  test("returns midpoint of the content quad", async () => {
    // Content quad: (10,20) (30,20) (30,40) (10,40)
    // Midpoint: ((10+30)/2, (20+40)/2) = (20, 30)
    const cdp = fakeCdp(() => ({
      model: { content: [10, 20, 30, 20, 30, 40, 10, 40] },
    }));

    const point = await getCenterPoint(cdp, 55);

    expect(point).toEqual({ x: 20, y: 30 });
    expect(cdp.calls[0]).toEqual({
      method: "DOM.getBoxModel",
      params: { backendNodeId: 55 },
    });
  });

  test("throws CdpError when DOM.getBoxModel rejects", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("cdp_error", "Could not compute box model.");
    });
    await expect(getCenterPoint(cdp, 55)).rejects.toMatchObject({
      name: "CdpError",
      code: "cdp_error",
    });
  });
});

// ── focusElement ──────────────────────────────────────────────────────

describe("focusElement", () => {
  test("sends DOM.focus with backendNodeId", async () => {
    const cdp = fakeCdp(() => ({}));
    await focusElement(cdp, 123);
    expect(cdp.calls).toEqual([
      { method: "DOM.focus", params: { backendNodeId: 123 } },
    ]);
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("cdp_error", "Element is not focusable");
    });
    await expect(focusElement(cdp, 123)).rejects.toMatchObject({
      name: "CdpError",
      code: "cdp_error",
    });
  });
});

// ── dispatchClickAt ───────────────────────────────────────────────────

describe("dispatchClickAt", () => {
  test("emits exactly three Input.dispatchMouseEvent calls in order", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchClickAt(cdp, { x: 100, y: 200 });

    expect(cdp.calls).toHaveLength(3);
    expect(cdp.calls[0]).toEqual({
      method: "Input.dispatchMouseEvent",
      params: {
        x: 100,
        y: 200,
        button: "left",
        clickCount: 1,
        type: "mouseMoved",
      },
    });
    expect(cdp.calls[1]).toEqual({
      method: "Input.dispatchMouseEvent",
      params: {
        x: 100,
        y: 200,
        button: "left",
        clickCount: 1,
        type: "mousePressed",
      },
    });
    expect(cdp.calls[2]).toEqual({
      method: "Input.dispatchMouseEvent",
      params: {
        x: 100,
        y: 200,
        button: "left",
        clickCount: 1,
        type: "mouseReleased",
      },
    });
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("transport_error", "send failed");
    });
    await expect(dispatchClickAt(cdp, { x: 1, y: 2 })).rejects.toMatchObject({
      name: "CdpError",
      code: "transport_error",
    });
  });
});

// ── dispatchHoverAt ───────────────────────────────────────────────────

describe("dispatchHoverAt", () => {
  test("emits a single mouseMoved event", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchHoverAt(cdp, { x: 10, y: 20 });

    expect(cdp.calls).toEqual([
      {
        method: "Input.dispatchMouseEvent",
        params: { type: "mouseMoved", x: 10, y: 20, button: "none" },
      },
    ]);
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("cdp_error", "boom");
    });
    await expect(dispatchHoverAt(cdp, { x: 10, y: 20 })).rejects.toMatchObject({
      name: "CdpError",
    });
  });
});

// ── dispatchInsertText ────────────────────────────────────────────────

describe("dispatchInsertText", () => {
  test("sends a single Input.insertText with the expected text", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchInsertText(cdp, "hello world");

    expect(cdp.calls).toEqual([
      { method: "Input.insertText", params: { text: "hello world" } },
    ]);
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("cdp_error", "boom");
    });
    await expect(dispatchInsertText(cdp, "x")).rejects.toMatchObject({
      name: "CdpError",
    });
  });
});

// ── dispatchKeyPress ──────────────────────────────────────────────────

describe("dispatchKeyPress", () => {
  test("Enter sends keyDown + char + keyUp with windowsVirtualKeyCode 13", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, "Enter");

    // Enter is text-producing (\r) so we get keyDown + char + keyUp.
    expect(cdp.calls).toHaveLength(3);
    for (const call of cdp.calls) {
      expect(call.method).toBe("Input.dispatchKeyEvent");
      const params = call.params as Record<string, unknown>;
      expect(params.key).toBe("Enter");
      expect(params.code).toBe("Enter");
      expect(params.windowsVirtualKeyCode).toBe(13);
      expect(params.text).toBe("\r");
    }
    expect((cdp.calls[0]!.params as Record<string, unknown>).type).toBe(
      "keyDown",
    );
    expect((cdp.calls[1]!.params as Record<string, unknown>).type).toBe("char");
    expect((cdp.calls[2]!.params as Record<string, unknown>).type).toBe(
      "keyUp",
    );
  });

  test("'a' sends keyCode 65, code KeyA, and a char event", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, "a");

    expect(cdp.calls).toHaveLength(3);
    for (const call of cdp.calls) {
      const params = call.params as Record<string, unknown>;
      expect(params.key).toBe("a");
      expect(params.code).toBe("KeyA");
      expect(params.windowsVirtualKeyCode).toBe(65);
      expect(params.text).toBe("a");
    }
    expect((cdp.calls[1]!.params as Record<string, unknown>).type).toBe("char");
  });

  test("ArrowDown sends keyCode 40 and NO char event", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, "ArrowDown");

    // ArrowDown is non-printing → no char event (just keyDown + keyUp).
    expect(cdp.calls).toHaveLength(2);
    for (const call of cdp.calls) {
      const params = call.params as Record<string, unknown>;
      expect(params.key).toBe("ArrowDown");
      expect(params.code).toBe("ArrowDown");
      expect(params.windowsVirtualKeyCode).toBe(40);
      expect(params.text).toBeUndefined();
    }
    expect((cdp.calls[0]!.params as Record<string, unknown>).type).toBe(
      "keyDown",
    );
    expect((cdp.calls[1]!.params as Record<string, unknown>).type).toBe(
      "keyUp",
    );
  });

  test("digit '7' sends keyCode 55 and code Digit7", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, "7");

    expect(cdp.calls).toHaveLength(3);
    const params = cdp.calls[0]!.params as Record<string, unknown>;
    expect(params.key).toBe("7");
    expect(params.code).toBe("Digit7");
    expect(params.windowsVirtualKeyCode).toBe(55);
    expect(params.text).toBe("7");
  });

  test("Tab sends keyCode 9 and text '\\t'", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, "Tab");

    expect(cdp.calls).toHaveLength(3);
    const params = cdp.calls[0]!.params as Record<string, unknown>;
    expect(params.windowsVirtualKeyCode).toBe(9);
    expect(params.text).toBe("\t");
  });

  test("Escape sends keyCode 27 and NO char event", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, "Escape");

    expect(cdp.calls).toHaveLength(2);
    const params = cdp.calls[0]!.params as Record<string, unknown>;
    expect(params.windowsVirtualKeyCode).toBe(27);
    expect(params.text).toBeUndefined();
  });

  test("'Space' (Playwright convention) sends code 'Space' and keyCode 32", async () => {
    // Playwright callers pass "Space" as the key name, but
    // `event.key` is actually " ". Verify both invariants.
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, "Space");

    expect(cdp.calls).toHaveLength(3);
    for (const call of cdp.calls) {
      const params = call.params as Record<string, unknown>;
      expect(params.key).toBe(" ");
      expect(params.code).toBe("Space");
      expect(params.windowsVirtualKeyCode).toBe(32);
      expect(params.text).toBe(" ");
    }
    expect((cdp.calls[1]!.params as Record<string, unknown>).type).toBe("char");
  });

  test("literal ' ' also maps to code 'Space'", async () => {
    // Passing a literal space character should produce the same
    // event shape as "Space" — not fall through to the generic
    // printable-ASCII path which emits `code: ""`.
    const cdp = fakeCdp(() => ({}));

    await dispatchKeyPress(cdp, " ");

    const params = cdp.calls[0]!.params as Record<string, unknown>;
    expect(params.code).toBe("Space");
    expect(params.windowsVirtualKeyCode).toBe(32);
    expect(params.text).toBe(" ");
  });

  test("Home/End/PageUp/PageDown send the right keyCodes (no char event)", async () => {
    const cases: Array<[string, number]> = [
      ["Home", 36],
      ["End", 35],
      ["PageUp", 33],
      ["PageDown", 34],
    ];
    for (const [key, expectedKeyCode] of cases) {
      const cdp = fakeCdp(() => ({}));
      await dispatchKeyPress(cdp, key);
      // Navigation keys are non-printing → keyDown + keyUp only.
      expect(cdp.calls).toHaveLength(2);
      const params = cdp.calls[0]!.params as Record<string, unknown>;
      expect(params.key).toBe(key);
      expect(params.code).toBe(key);
      expect(params.windowsVirtualKeyCode).toBe(expectedKeyCode);
      expect(params.text).toBeUndefined();
    }
  });

  test("Insert sends keyCode 45 and no char event", async () => {
    const cdp = fakeCdp(() => ({}));
    await dispatchKeyPress(cdp, "Insert");
    expect(cdp.calls).toHaveLength(2);
    const params = cdp.calls[0]!.params as Record<string, unknown>;
    expect(params.windowsVirtualKeyCode).toBe(45);
    expect(params.text).toBeUndefined();
  });

  test("F1-F12 send the right Windows virtual keyCodes", async () => {
    const cases: Array<[string, number]> = [
      ["F1", 112],
      ["F2", 113],
      ["F3", 114],
      ["F4", 115],
      ["F5", 116],
      ["F6", 117],
      ["F7", 118],
      ["F8", 119],
      ["F9", 120],
      ["F10", 121],
      ["F11", 122],
      ["F12", 123],
    ];
    for (const [key, expectedKeyCode] of cases) {
      const cdp = fakeCdp(() => ({}));
      await dispatchKeyPress(cdp, key);
      expect(cdp.calls).toHaveLength(2);
      const params = cdp.calls[0]!.params as Record<string, unknown>;
      expect(params.key).toBe(key);
      expect(params.code).toBe(key);
      expect(params.windowsVirtualKeyCode).toBe(expectedKeyCode);
      expect(params.text).toBeUndefined();
    }
  });

  test("unknown multi-character key falls back to minimal payload", async () => {
    const cdp = fakeCdp(() => ({}));
    // Suppress the console.warn for the duration of the call. F19
    // is not in the static map and cannot be derived dynamically.
    const originalWarn = console.warn;
    console.warn = () => {};
    try {
      await dispatchKeyPress(cdp, "F19");
    } finally {
      console.warn = originalWarn;
    }
    expect(cdp.calls).toHaveLength(2);
    expect(cdp.calls[0]!.params).toEqual({ type: "keyDown", key: "F19" });
    expect(cdp.calls[1]!.params).toEqual({ type: "keyUp", key: "F19" });
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("cdp_error", "boom");
    });
    await expect(dispatchKeyPress(cdp, "a")).rejects.toMatchObject({
      name: "CdpError",
    });
  });
});

// ── dispatchWheelScroll ───────────────────────────────────────────────

describe("dispatchWheelScroll", () => {
  test("emits a mouseWheel event with the requested delta", async () => {
    const cdp = fakeCdp(() => ({}));

    await dispatchWheelScroll(
      cdp,
      { x: 100, y: 200 },
      { deltaX: 0, deltaY: 500 },
    );

    expect(cdp.calls).toEqual([
      {
        method: "Input.dispatchMouseEvent",
        params: {
          type: "mouseWheel",
          x: 100,
          y: 200,
          deltaX: 0,
          deltaY: 500,
        },
      },
    ]);
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("transport_error", "boom");
    });
    await expect(
      dispatchWheelScroll(cdp, { x: 0, y: 0 }, { deltaX: 0, deltaY: 10 }),
    ).rejects.toMatchObject({ name: "CdpError", code: "transport_error" });
  });
});

// ── getCurrentUrl ─────────────────────────────────────────────────────

describe("getCurrentUrl", () => {
  test("returns the result.value from Runtime.evaluate", async () => {
    const cdp = fakeCdp((method, params) => {
      expect(method).toBe("Runtime.evaluate");
      expect(params).toEqual({
        expression: "document.location.href",
        returnByValue: true,
      });
      return { result: { value: "https://example.com/" } };
    });

    const url = await getCurrentUrl(cdp);
    expect(url).toBe("https://example.com/");
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("transport_error", "boom");
    });
    await expect(getCurrentUrl(cdp)).rejects.toMatchObject({
      name: "CdpError",
      code: "transport_error",
    });
  });
});

// ── getPageTitle ──────────────────────────────────────────────────────

describe("getPageTitle", () => {
  test("returns the result.value from Runtime.evaluate", async () => {
    const cdp = fakeCdp((method, params) => {
      expect(method).toBe("Runtime.evaluate");
      expect(params).toEqual({
        expression: "document.title",
        returnByValue: true,
      });
      return { result: { value: "My Page" } };
    });
    expect(await getPageTitle(cdp)).toBe("My Page");
  });

  test("returns empty string when result value is missing", async () => {
    const cdp = fakeCdp(() => ({ result: { value: undefined } }));
    expect(await getPageTitle(cdp)).toBe("");
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("transport_error", "boom");
    });
    await expect(getPageTitle(cdp)).rejects.toMatchObject({
      name: "CdpError",
    });
  });
});

// ── evaluateExpression ────────────────────────────────────────────────

describe("evaluateExpression", () => {
  test("returns result.value on happy path with default opts", async () => {
    const cdp = fakeCdp((method, params) => {
      expect(method).toBe("Runtime.evaluate");
      expect(params).toEqual({
        expression: "1 + 2",
        returnByValue: true,
        awaitPromise: true,
        userGesture: true,
      });
      return { result: { value: 3 } };
    });

    const value = await evaluateExpression<number>(cdp, "1 + 2");
    expect(value).toBe(3);
  });

  test("honors awaitPromise: false override", async () => {
    const cdp = fakeCdp(() => ({ result: { value: "ok" } }));
    await evaluateExpression<string>(cdp, "'ok'", { awaitPromise: false });
    expect(cdp.calls[0]!.params).toMatchObject({
      awaitPromise: false,
    });
  });

  test("throws CdpError when exceptionDetails is present", async () => {
    const cdp = fakeCdp(() => ({
      result: { value: undefined },
      exceptionDetails: {
        text: "Uncaught",
        exception: { description: "ReferenceError: foo is not defined" },
      },
    }));

    await expect(evaluateExpression(cdp, "foo")).rejects.toMatchObject({
      name: "CdpError",
      code: "cdp_error",
      message: "ReferenceError: foo is not defined",
      cdpMethod: "Runtime.evaluate",
      cdpParams: { expression: "foo" },
    });
  });

  test("falls back to exceptionDetails.text if no description", async () => {
    const cdp = fakeCdp(() => ({
      result: { value: undefined },
      exceptionDetails: { text: "Uncaught SyntaxError" },
    }));
    await expect(evaluateExpression(cdp, "???")).rejects.toMatchObject({
      message: "Uncaught SyntaxError",
    });
  });
});

// ── captureScreenshotJpeg ─────────────────────────────────────────────

describe("captureScreenshotJpeg", () => {
  test("returns a Buffer with decoded bytes", async () => {
    const rawBytes = Buffer.from([0xff, 0xd8, 0xff, 0xe0]); // JPEG SOI + APP0
    const base64 = rawBytes.toString("base64");

    const cdp = fakeCdp((method, params) => {
      expect(method).toBe("Page.captureScreenshot");
      expect(params).toEqual({
        format: "jpeg",
        quality: 80,
        captureBeyondViewport: false,
      });
      return { data: base64 };
    });

    const buf = await captureScreenshotJpeg(cdp);
    expect(Buffer.isBuffer(buf)).toBe(true);
    expect(buf.equals(rawBytes)).toBe(true);
  });

  test("forwards quality + fullPage options", async () => {
    const cdp = fakeCdp(() => ({ data: "" }));
    await captureScreenshotJpeg(cdp, { quality: 50, fullPage: true });
    expect(cdp.calls[0]!.params).toEqual({
      format: "jpeg",
      quality: 50,
      captureBeyondViewport: true,
    });
  });

  test("propagates errors from the client", async () => {
    const cdp = fakeCdp(() => {
      throw new CdpError("transport_error", "boom");
    });
    await expect(captureScreenshotJpeg(cdp)).rejects.toMatchObject({
      name: "CdpError",
    });
  });
});

// ── navigateAndWait ───────────────────────────────────────────────────

/**
 * Build a programmable fake for `navigateAndWait` tests. Handles the
 * standard shape: pre-nav `document.location.href` read, then
 * `Page.navigate`, then any number of combined `readyState + href`
 * poll evaluations.
 *
 * The `poll` handler is invoked once per combined readyState/href
 * evaluate and must return `{ readyState, href }` (to continue the
 * poll) or throw (to simulate a transient CDP error).
 */
function fakeNavCdp(opts: {
  urlBeforeNav?: string;
  navResponse?: { frameId?: string; errorText?: string };
  poll: (
    callIndex: number,
  ) => { readyState: string; href: string } | { throwError: CdpError };
  onNavigate?: () => void;
}) {
  let pollCalls = 0;
  return fakeCdp((method, params) => {
    if (method === "Page.navigate") {
      opts.onNavigate?.();
      return opts.navResponse ?? {};
    }
    if (method === "Runtime.evaluate") {
      const expr = (params as { expression: string }).expression;
      if (expr === "document.location.href") {
        return { result: { value: opts.urlBeforeNav ?? "about:blank" } };
      }
      if (expr === "document.title") {
        return { result: { value: "" } };
      }
      if (expr.includes("readyState") && expr.includes("href")) {
        const res = opts.poll(pollCalls++);
        if ("throwError" in res) {
          throw res.throwError;
        }
        return { result: { value: res } };
      }
    }
    throw new Error(
      `unexpected: ${method} ${JSON.stringify((params as Record<string, unknown>)?.expression ?? params)}`,
    );
  });
}

describe("navigateAndWait", () => {
  test("calls Page.navigate and returns finalUrl once readyState is complete and URL has committed", async () => {
    const cdp = fakeNavCdp({
      urlBeforeNav: "https://example.com/start",
      poll: () => ({
        readyState: "complete",
        href: "https://example.com/final",
      }),
    });

    const result = await navigateAndWait(cdp, "https://example.com/target", {
      timeoutMs: 5_000,
    });

    expect(result).toEqual({
      finalUrl: "https://example.com/final",
      timedOut: false,
    });

    const navigateCalls = cdp.calls.filter((c) => c.method === "Page.navigate");
    expect(navigateCalls).toHaveLength(1);
    expect(navigateCalls[0]!.params).toEqual({
      url: "https://example.com/target",
    });
  });

  test("resolves when readyState becomes interactive (not just complete)", async () => {
    const cdp = fakeNavCdp({
      urlBeforeNav: "https://prev",
      poll: () => ({ readyState: "interactive", href: "https://x" }),
    });

    const result = await navigateAndWait(cdp, "https://x", {
      timeoutMs: 5_000,
    });
    expect(result.timedOut).toBe(false);
    expect(result.finalUrl).toBe("https://x");
  });

  test("returns timedOut: true when readyState never becomes ready", async () => {
    const cdp = fakeNavCdp({
      urlBeforeNav: "about:blank",
      poll: () => ({ readyState: "loading", href: "https://slow" }),
    });

    // Use a tiny timeout so the test finishes quickly.
    const result = await navigateAndWait(cdp, "https://slow", {
      timeoutMs: 50,
    });
    expect(result.timedOut).toBe(true);
    // finalUrl should come from the in-loop observations (the last
    // href we successfully saw), not a post-loop fresh read.
    expect(result.finalUrl).toBe("https://slow");
  });

  test("throws CdpError with code 'aborted' when signal fires", async () => {
    const controller = new AbortController();
    const cdp = fakeNavCdp({
      urlBeforeNav: "about:blank",
      onNavigate: () => controller.abort(),
      poll: () => ({ readyState: "loading", href: "https://x" }),
    });

    await expect(
      navigateAndWait(
        cdp,
        "https://x",
        { timeoutMs: 5_000 },
        controller.signal,
      ),
    ).rejects.toMatchObject({
      name: "CdpError",
      code: "aborted",
    });
  });

  test("throws CdpError when Page.navigate returns errorText", async () => {
    // CDP signals DNS / connection errors via `errorText` rather than
    // throwing — navigateAndWait must surface this instead of polling
    // the OLD page's readyState (which is "complete") and reporting
    // success with the stale URL.
    const cdp = fakeNavCdp({
      urlBeforeNav: "about:blank",
      navResponse: {
        frameId: "f1",
        errorText: "net::ERR_CONNECTION_REFUSED",
      },
      poll: () => ({ readyState: "complete", href: "should not be read" }),
    });

    await expect(
      navigateAndWait(cdp, "https://nope.invalid", { timeoutMs: 5_000 }),
    ).rejects.toMatchObject({
      name: "CdpError",
      code: "cdp_error",
      message: "net::ERR_CONNECTION_REFUSED",
      cdpMethod: "Page.navigate",
      cdpParams: { url: "https://nope.invalid" },
    });

    // Should NOT have polled readyState (only the pre-nav
    // `document.location.href` read is allowed before the navigate
    // attempt).
    const pollEvals = cdp.calls.filter((c) => {
      if (c.method !== "Runtime.evaluate") {
        return false;
      }
      const expr = (c.params as { expression?: string } | undefined)
        ?.expression;
      return typeof expr === "string" && expr.includes("readyState");
    });
    expect(pollEvals).toHaveLength(0);
  });

  test("waits for URL to commit before accepting readyState=complete (same-origin race)", async () => {
    // Reproduces the bug where a same-origin navigation resolves
    // `Page.navigate` but the polling loop sees the OLD page's
    // "complete" readyState and the OLD URL for the first few polls
    // before the new document commits.
    //
    // First 3 polls: old page's "complete" + old URL.
    // Fourth poll: new document fully committed.
    const cdp = fakeNavCdp({
      urlBeforeNav: "https://example.com/page1",
      poll: (callIndex) => {
        if (callIndex < 3) {
          return {
            readyState: "complete",
            href: "https://example.com/page1",
          };
        }
        return { readyState: "complete", href: "https://example.com/page2" };
      },
    });

    const result = await navigateAndWait(cdp, "https://example.com/page2", {
      timeoutMs: 5_000,
    });

    expect(result).toEqual({
      finalUrl: "https://example.com/page2",
      timedOut: false,
    });

    // The loop must have polled at least 4 times — proof that it
    // did not break on the first "complete" observation against the
    // old URL.
    const pollEvals = cdp.calls.filter(
      (c) =>
        c.method === "Runtime.evaluate" &&
        typeof (c.params as { expression?: string })?.expression === "string" &&
        (c.params as { expression: string }).expression.includes("readyState"),
    );
    expect(pollEvals.length).toBeGreaterThanOrEqual(4);
  });

  test("retries on transient CdpError during context transition", async () => {
    // After `Page.navigate`, `Runtime.evaluate` can fail transiently
    // while the old execution context is torn down and before the
    // new one is created. navigateAndWait must catch that error and
    // keep polling.
    const cdp = fakeNavCdp({
      urlBeforeNav: "https://prev",
      poll: (callIndex) => {
        if (callIndex === 0) {
          return {
            throwError: new CdpError(
              "cdp_error",
              "Execution context was destroyed.",
            ),
          };
        }
        if (callIndex === 1) {
          return {
            throwError: new CdpError(
              "cdp_error",
              "Cannot find context with specified id",
            ),
          };
        }
        return { readyState: "complete", href: "https://new" };
      },
    });

    const result = await navigateAndWait(cdp, "https://new", {
      timeoutMs: 5_000,
    });
    expect(result).toEqual({
      finalUrl: "https://new",
      timedOut: false,
    });
  });

  test("same-URL reload falls back to readyState-only polling", async () => {
    // When the target URL matches the pre-nav URL (e.g. a reload),
    // there's no URL-change signal to wait for. The commit check
    // must fall back to readyState-only so reloads don't loop
    // forever.
    const cdp = fakeNavCdp({
      urlBeforeNav: "https://example.com/same",
      poll: () => ({
        readyState: "complete",
        href: "https://example.com/same",
      }),
    });

    const result = await navigateAndWait(cdp, "https://example.com/same", {
      timeoutMs: 5_000,
    });

    expect(result).toEqual({
      finalUrl: "https://example.com/same",
      timedOut: false,
    });
  });

  test("falls back to readyState-only when pre-nav URL read fails", async () => {
    // If we can't read the pre-nav URL (e.g. fresh about:blank with
    // no Runtime context), commit detection has no baseline and must
    // fall back to readyState-only.
    let sawPreNavRead = false;
    const cdp = fakeCdp((method, params) => {
      if (method === "Page.navigate") {
        return {};
      }
      if (method === "Runtime.evaluate") {
        const expr = (params as { expression: string }).expression;
        if (expr === "document.location.href" && !sawPreNavRead) {
          sawPreNavRead = true;
          throw new CdpError("cdp_error", "no context");
        }
        if (expr.includes("readyState") && expr.includes("href")) {
          return {
            result: { value: { readyState: "complete", href: "https://x" } },
          };
        }
      }
      throw new Error(
        `unexpected: ${method} ${JSON.stringify((params as Record<string, unknown>)?.expression ?? params)}`,
      );
    });

    const result = await navigateAndWait(cdp, "https://x", {
      timeoutMs: 5_000,
    });

    expect(result).toEqual({
      finalUrl: "https://x",
      timedOut: false,
    });
  });

  test("reports last observed href on timeout instead of racing a post-loop read", async () => {
    // If polling never reaches readyState-ready + committed, the
    // final URL should come from the last in-loop observation (so
    // the caller doesn't race the commit window again via a
    // post-loop `getCurrentUrl`).
    const observedHrefs: string[] = [];
    const cdp = fakeNavCdp({
      urlBeforeNav: "https://pre",
      poll: (callIndex) => {
        // Keep returning "loading" but advance the URL so we can
        // verify the fallback uses the last observation.
        const href = `https://loading/${callIndex}`;
        observedHrefs.push(href);
        return { readyState: "loading", href };
      },
    });

    const result = await navigateAndWait(cdp, "https://target", {
      timeoutMs: 50,
    });
    expect(result.timedOut).toBe(true);
    // finalUrl should match the last href we returned from the poll
    // handler (not the pre-nav URL, and not a separately-read value).
    expect(observedHrefs.length).toBeGreaterThan(0);
    expect(result.finalUrl).toBe(observedHrefs[observedHrefs.length - 1]!);
  });

  test("re-throws non-CdpError exceptions from the polling evaluate", async () => {
    // Only CdpErrors are retry-worthy; unexpected JS errors should
    // propagate so they're not swallowed.
    const cdp = fakeNavCdp({
      urlBeforeNav: "https://pre",
      poll: () => {
        throw new Error("unexpected programmer error");
      },
    });

    await expect(
      navigateAndWait(cdp, "https://target", { timeoutMs: 5_000 }),
    ).rejects.toThrow("unexpected programmer error");
  });
});

// ── waitForSelector ───────────────────────────────────────────────────

describe("waitForSelector", () => {
  test("resolves when the selector appears on the 2nd poll (default visible state)", async () => {
    let evalCount = 0;
    let lastExpression = "";
    const cdp = fakeCdp((method, params) => {
      if (method === "Runtime.evaluate") {
        evalCount++;
        lastExpression = (params as { expression: string }).expression;
        // First poll: not present. Second poll: present.
        return { result: { value: evalCount >= 2 } };
      }
      if (method === "DOM.getDocument") {
        return { root: { nodeId: 1 } };
      }
      if (method === "DOM.querySelector") {
        return { nodeId: 9 };
      }
      if (method === "DOM.describeNode") {
        return { node: { backendNodeId: 321 } };
      }
      throw new Error(`unexpected: ${method}`);
    });

    const backendNodeId = await waitForSelector(cdp, "#ready", 5_000);
    expect(backendNodeId).toBe(321);
    expect(evalCount).toBeGreaterThanOrEqual(2);
    // Default state is "visible" — the polling expression must check
    // bounding box + display + visibility, not just `!== null`.
    expect(lastExpression).toContain("getBoundingClientRect");
    expect(lastExpression).toContain("display");
    expect(lastExpression).toContain("visibility");
  });

  test("with state: 'attached' polls DOM existence only", async () => {
    let evalCount = 0;
    let lastExpression = "";
    const cdp = fakeCdp((method, params) => {
      if (method === "Runtime.evaluate") {
        evalCount++;
        lastExpression = (params as { expression: string }).expression;
        return { result: { value: true } };
      }
      if (method === "DOM.getDocument") {
        return { root: { nodeId: 1 } };
      }
      if (method === "DOM.querySelector") {
        return { nodeId: 9 };
      }
      if (method === "DOM.describeNode") {
        return { node: { backendNodeId: 555 } };
      }
      throw new Error(`unexpected: ${method}`);
    });

    const backendNodeId = await waitForSelector(
      cdp,
      "#exists",
      5_000,
      undefined,
      { state: "attached" },
    );
    expect(backendNodeId).toBe(555);
    expect(evalCount).toBeGreaterThanOrEqual(1);
    // Attached state must use the simple `!== null` check, not the
    // bounding-box / computed-style probe.
    expect(lastExpression).toBe(`document.querySelector("#exists") !== null`);
    expect(lastExpression).not.toContain("getBoundingClientRect");
  });

  test("default state polls until the visible-state probe returns true", async () => {
    let evalCount = 0;
    const cdp = fakeCdp((method, params) => {
      if (method === "Runtime.evaluate") {
        evalCount++;
        const expression = (params as { expression: string }).expression;
        // Sanity-check: the polling expression must be the visible
        // probe, not the simple existence check.
        expect(expression).toContain("getBoundingClientRect");
        // Element exists in DOM but isn't yet visible until the third
        // poll.
        return { result: { value: evalCount >= 3 } };
      }
      if (method === "DOM.getDocument") {
        return { root: { nodeId: 1 } };
      }
      if (method === "DOM.querySelector") {
        return { nodeId: 9 };
      }
      if (method === "DOM.describeNode") {
        return { node: { backendNodeId: 999 } };
      }
      throw new Error(`unexpected: ${method}`);
    });

    const backendNodeId = await waitForSelector(cdp, "#hydrating", 5_000);
    expect(backendNodeId).toBe(999);
    expect(evalCount).toBeGreaterThanOrEqual(3);
  });

  test("throws CdpError on timeout", async () => {
    const cdp = fakeCdp((method) => {
      if (method === "Runtime.evaluate") {
        return { result: { value: false } };
      }
      throw new Error(`unexpected: ${method}`);
    });

    await expect(waitForSelector(cdp, "#nope", 50)).rejects.toMatchObject({
      name: "CdpError",
      code: "cdp_error",
      message: "Timed out waiting for #nope",
    });
  });

  test("throws CdpError with code 'aborted' when signal fires", async () => {
    const controller = new AbortController();
    controller.abort();
    const cdp = fakeCdp(() => ({ result: { value: false } }));
    await expect(
      waitForSelector(cdp, "#x", 5_000, controller.signal),
    ).rejects.toMatchObject({
      name: "CdpError",
      code: "aborted",
    });
  });
});

// ── waitForText ───────────────────────────────────────────────────────

describe("waitForText", () => {
  test("resolves when the text is found", async () => {
    let count = 0;
    const cdp = fakeCdp((method) => {
      if (method === "Runtime.evaluate") {
        count++;
        return { result: { value: count >= 2 } };
      }
      throw new Error(`unexpected: ${method}`);
    });

    await waitForText(cdp, "hello", 5_000);
    expect(count).toBeGreaterThanOrEqual(2);
  });

  test("throws CdpError on timeout", async () => {
    const cdp = fakeCdp((method) => {
      if (method === "Runtime.evaluate") {
        return { result: { value: false } };
      }
      throw new Error(`unexpected: ${method}`);
    });

    await expect(waitForText(cdp, "never-here", 50)).rejects.toMatchObject({
      name: "CdpError",
      code: "cdp_error",
      message: "Timed out waiting for text: never-here",
    });
  });

  test("throws CdpError with code 'aborted' when signal fires", async () => {
    const controller = new AbortController();
    controller.abort();
    const cdp = fakeCdp(() => ({ result: { value: false } }));
    await expect(
      waitForText(cdp, "x", 5_000, controller.signal),
    ).rejects.toMatchObject({
      name: "CdpError",
      code: "aborted",
    });
  });
});