@mochi.js/core 0.1.2 → 0.2.2

package/src/__tests__/selector.test.ts

@@ -0,0 +1,188 @@
+/**
+ * Unit tests for the host-side CSS selector parser + matcher used by
+ * `Page.querySelectorPiercing`. Covers the exact subset documented in
+ * `packages/core/src/page/selector.ts`:
+ *
+ *   - tag / id / class / attribute / descendant combinator
+ *   - comma-separated lists
+ *   - quoted attribute values, attribute operators (`=`, `~=`, `|=`, `^=`,
+ *     `$=`, `*=`, presence)
+ *
+ * NOT covered here (intentional out-of-scope per task 0253): `>`/`+`/`~`
+ * combinators, pseudo-classes / -elements, XPath. The matcher should reject
+ * those at parse time.
+ */
+
+import { describe, expect, it } from "bun:test";
+import type { PierceDomNode } from "../cdp/types";
+import { matchSelector, parseSelector, readAttribute, SelectorParseError } from "../page/selector";
+
+/** Build a minimal element node for matcher tests. */
+function el(tag: string, attrs: Record<string, string> = {}): PierceDomNode {
+  const flat: string[] = [];
+  for (const [k, v] of Object.entries(attrs)) {
+    flat.push(k, v);
+  }
+  return {
+    nodeId: 1,
+    backendNodeId: 1,
+    nodeType: 1,
+    nodeName: tag.toUpperCase(),
+    localName: tag.toLowerCase(),
+    attributes: flat,
+  };
+}
+
+describe("parseSelector — accepted grammar", () => {
+  it("parses a bare tag", () => {
+    const p = parseSelector("div");
+    expect(p.chains).toHaveLength(1);
+    expect(p.chains[0]?.parts).toHaveLength(1);
+    expect(p.chains[0]?.parts[0]?.tag).toBe("div");
+  });
+
+  it("parses a class selector with no tag (universal)", () => {
+    const p = parseSelector(".btn");
+    expect(p.chains[0]?.parts[0]?.tag).toBe("*");
+    expect(p.chains[0]?.parts[0]?.classes).toEqual(["btn"]);
+  });
+
+  it("parses tag + id + multiple classes", () => {
+    const p = parseSelector("button#submit.primary.large");
+    const part = p.chains[0]?.parts[0];
+    expect(part?.tag).toBe("button");
+    expect(part?.id).toBe("submit");
+    expect(part?.classes).toEqual(["primary", "large"]);
+  });
+
+  it("parses an attribute selector with no value", () => {
+    const p = parseSelector("input[disabled]");
+    const part = p.chains[0]?.parts[0];
+    expect(part?.attrs[0]?.name).toBe("disabled");
+    expect(part?.attrs[0]?.op).toBe("exists");
+  });
+
+  it("parses every attribute operator", () => {
+    const ops: Array<["=" | "~=" | "|=" | "^=" | "$=" | "*=", string]> = [
+      ["=", "[a=x]"],
+      ["~=", '[a~="x"]'],
+      ["|=", '[a|="x"]'],
+      ["^=", '[a^="x"]'],
+      ["$=", '[a$="x"]'],
+      ["*=", '[a*="x"]'],
+    ];
+    for (const [op, src] of ops) {
+      const p = parseSelector(src);
+      expect(p.chains[0]?.parts[0]?.attrs[0]?.op).toBe(op);
+      expect(p.chains[0]?.parts[0]?.attrs[0]?.value).toBe("x");
+    }
+  });
+
+  it("parses a descendant chain", () => {
+    const p = parseSelector("section .btn");
+    expect(p.chains[0]?.parts).toHaveLength(2);
+    expect(p.chains[0]?.parts[0]?.tag).toBe("section");
+    expect(p.chains[0]?.parts[1]?.classes).toEqual(["btn"]);
+  });
+
+  it("parses a comma-separated list with attributes", () => {
+    const p = parseSelector('iframe[src*="cf"], a#x, .btn');
+    expect(p.chains).toHaveLength(3);
+    expect(p.chains[0]?.parts[0]?.tag).toBe("iframe");
+    expect(p.chains[0]?.parts[0]?.attrs[0]?.value).toBe("cf");
+    expect(p.chains[1]?.parts[0]?.id).toBe("x");
+    expect(p.chains[2]?.parts[0]?.classes).toEqual(["btn"]);
+  });
+
+  it("preserves whitespace inside quoted attribute values", () => {
+    const p = parseSelector('input[name="hello world"]');
+    expect(p.chains[0]?.parts[0]?.attrs[0]?.value).toBe("hello world");
+  });
+});
+
+describe("parseSelector — rejected input", () => {
+  it("rejects empty string", () => {
+    expect(() => parseSelector("")).toThrow(SelectorParseError);
+  });
+
+  it("rejects unterminated bracket", () => {
+    expect(() => parseSelector("input[name=")).toThrow(SelectorParseError);
+  });
+
+  it("rejects bad tag chars", () => {
+    // We only enforce on tag prefix when present — `.foo!` parses tag `*`
+    // then class. But a leading numeric tag like `9foo` is rejected.
+    expect(() => parseSelector("9foo")).toThrow(SelectorParseError);
+  });
+});
+
+describe("matchSelector — basic matchers", () => {
+  it("matches tag", () => {
+    const node = el("div");
+    expect(matchSelector(parseSelector("div"), node, [])).toBe(true);
+    expect(matchSelector(parseSelector("span"), node, [])).toBe(false);
+  });
+
+  it("matches universal", () => {
+    expect(matchSelector(parseSelector("*"), el("div"), [])).toBe(true);
+    expect(matchSelector(parseSelector("*"), el("img"), [])).toBe(true);
+  });
+
+  it("matches id", () => {
+    const node = el("div", { id: "main" });
+    expect(matchSelector(parseSelector("#main"), node, [])).toBe(true);
+    expect(matchSelector(parseSelector("#other"), node, [])).toBe(false);
+  });
+
+  it("matches class (single + multiple)", () => {
+    const node = el("button", { class: "btn primary large" });
+    expect(matchSelector(parseSelector(".btn"), node, [])).toBe(true);
+    expect(matchSelector(parseSelector(".btn.primary"), node, [])).toBe(true);
+    expect(matchSelector(parseSelector(".btn.primary.large"), node, [])).toBe(true);
+    expect(matchSelector(parseSelector(".btn.missing"), node, [])).toBe(false);
+  });
+
+  it("matches every attribute operator", () => {
+    const node = el("a", {
+      href: "https://example.com/foo/bar",
+      "data-tags": "alpha beta gamma",
+      lang: "en-US",
+    });
+    expect(matchSelector(parseSelector("a[href]"), node, [])).toBe(true);
+    expect(matchSelector(parseSelector('a[href="https://example.com/foo/bar"]'), node, [])).toBe(
+      true,
+    );
+    expect(matchSelector(parseSelector('a[href^="https://"]'), node, [])).toBe(true);
+    expect(matchSelector(parseSelector('a[href$="/bar"]'), node, [])).toBe(true);
+    expect(matchSelector(parseSelector('a[href*="example"]'), node, [])).toBe(true);
+    expect(matchSelector(parseSelector('a[data-tags~="beta"]'), node, [])).toBe(true);
+    expect(matchSelector(parseSelector('a[data-tags~="zeta"]'), node, [])).toBe(false);
+    expect(matchSelector(parseSelector('a[lang|="en"]'), node, [])).toBe(true);
+    expect(matchSelector(parseSelector('a[lang|="fr"]'), node, [])).toBe(false);
+  });
+
+  it("matches descendant chains", () => {
+    const section = el("section", { class: "panel" });
+    const wrapper = el("div", { class: "wrap" });
+    const button = el("button", { class: "btn" });
+    expect(matchSelector(parseSelector("section .btn"), button, [section, wrapper])).toBe(true);
+    expect(matchSelector(parseSelector("section button"), button, [section, wrapper])).toBe(true);
+    // Reject when the leftmost compound is missing from the ancestor chain.
+    expect(matchSelector(parseSelector("article button"), button, [section, wrapper])).toBe(false);
+  });
+
+  it("matches comma-separated branches", () => {
+    const node = el("button", { class: "btn" });
+    expect(matchSelector(parseSelector("a, button"), node, [])).toBe(true);
+    expect(matchSelector(parseSelector("a, span"), node, [])).toBe(false);
+  });
+});
+
+describe("readAttribute", () => {
+  it("returns the value if present (case-insensitive name)", () => {
+    const node = el("div", { id: "x", DataFoo: "yes" });
+    expect(readAttribute(node, "id")).toBe("x");
+    expect(readAttribute(node, "datafoo")).toBe("yes");
+    expect(readAttribute(node, "missing")).toBeUndefined();
+  });
+});

package/src/__tests__/window-size.e2e.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Task 0252 conformance E2E — verify the OS-level outer-window pin
+ * (`--window-size=<W>,<H>`, derived from `matrix.display.{width,height}`)
+ * is honored under `--headless=new` such that
+ * `window.outerWidth === matrix.display.width`.
+ *
+ * UDC issue #2242 documents that `--window-size` is honored at the OS
+ * level under headless, but the JS API surface (`window.outerWidth/Height`)
+ * historically did not reflect it without a CDP `Browser.setWindowBounds`
+ * follow-up. This test is the canonical check that the leak is closed
+ * end-to-end on the Chromium versions we care about. If `outerWidth`
+ * comes back as 800 (the legacy headless default) the test fails loudly
+ * and the orchestrator knows to layer in the CDP fix.
+ *
+ * Mochi's inject layer also defines `window.outerWidth/outerHeight` from
+ * `matrix.uaCh["window-viewport"]` (R-029). On macOS the R-029 outerWidth
+ * equals `display.width` exactly (OS_CHROME_WIDTH = 0), so the assertion
+ * holds regardless of whether the OS-level honoring works as promised.
+ * The OS-level fix is what hardens the surface against:
+ *   - inject-bypassed flows (`bypassInject: true`, `mochi capture`)
+ *   - cross-realm reads where the spoof hasn't installed yet
+ *
+ * Gated by `MOCHI_E2E=1`. Set `MOCHI_CHROMIUM_PATH` to a real binary.
+ *
+ * @see tasks/0252-window-size-flag-from-matrix.md
+ * @see UDC `__init__.py:410-411`, UDC issue #2242
+ */
+
+import { describe, expect, it } from "bun:test";
+import { mochi } from "../index";
+
+const E2E_ENABLED = process.env.MOCHI_E2E === "1";
+const TEST_TIMEOUT_MS = 15_000;
+
+const describeOrSkip = E2E_ENABLED ? describe : describe.skip;
+
+const PROBE_HTML = `<!doctype html><html><body><pre id="p"></pre><script>
+document.getElementById("p").textContent = JSON.stringify({
+  outerWidth: window.outerWidth,
+  outerHeight: window.outerHeight,
+  screenWidth: screen.width,
+  screenHeight: screen.height,
+});
+</script></body></html>`;
+
+const PROBE_DATA_URL = `data:text/html;charset=utf-8,${encodeURIComponent(PROBE_HTML)}`;
+
+interface ProbeShape {
+  outerWidth: number;
+  outerHeight: number;
+  screenWidth: number;
+  screenHeight: number;
+}
+
+describeOrSkip("@mochi.js/core --window-size E2E (MOCHI_E2E=1) — task 0252", () => {
+  it(
+    "window.outerWidth matches matrix.display.width under --headless=new",
+    async () => {
+      const session = await mochi.launch({
+        seed: "task-0252-window-size",
+        headless: true,
+        profile: {
+          id: "window-size-e2e-fixture",
+          version: "0.0.0-e2e",
+          engine: "chromium",
+          browser: { name: "chrome", channel: "stable", minVersion: "131", maxVersion: "133" },
+          os: { name: "macos", version: "14", arch: "arm64" },
+          device: {
+            vendor: "Apple",
+            model: "Mac14,2",
+            cpuFamily: "apple-silicon-m2",
+            cores: 8,
+            memoryGB: 16,
+          },
+          // Distinctive non-default dimensions so an 800×600 leak is glaring.
+          display: { width: 1728, height: 1117, dpr: 2, colorDepth: 30, pixelDepth: 30 },
+          gpu: {
+            vendor: "Apple Inc.",
+            renderer: "Apple M2",
+            webglUnmaskedVendor: "Google Inc. (Apple)",
+            webglUnmaskedRenderer:
+              "ANGLE (Apple, ANGLE Metal Renderer: Apple M2, Unspecified Version)",
+            webglMaxTextureSize: 16384,
+            webglMaxColorAttachments: 8,
+            webglExtensions: [],
+          },
+          audio: {
+            contextSampleRate: 48000,
+            audioWorkletLatency: 0.005,
+            destinationMaxChannelCount: 2,
+          },
+          fonts: { family: "macos-baseline", list: ["Helvetica"] },
+          timezone: "America/Los_Angeles",
+          locale: "en-US",
+          languages: ["en-US", "en"],
+          behavior: { hand: "right", tremor: 0.18, wpm: 60, scrollStyle: "smooth" },
+          wreqPreset: "chrome_131_macos",
+          userAgent:
+            "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.6778.86 Safari/537.36",
+          uaCh: {},
+          entropyBudget: { fixed: [], perSeed: [] },
+        },
+      });
+
+      try {
+        const matrix = session.profile;
+        const page = await session.newPage();
+        await page.goto(PROBE_DATA_URL);
+        const txt = await page.text("#p");
+        if (txt === null) throw new Error("[mochi e2e] probe element produced no textContent");
+        const probe = JSON.parse(txt) as ProbeShape;
+
+        // Task 0252 success criterion #4: probe-time conformance.
+        // The 800×600 leak under --headless=new manifests as outerWidth=800.
+        // Failing here means the OS-level pin is NOT honored AND the inject
+        // spoof did not install — orchestrator should layer in CDP
+        // `Browser.setWindowBounds` per UDC issue #2242 follow-up.
+        expect(probe.outerWidth).toBe(matrix.display.width);
+        expect(probe.outerWidth).not.toBe(800);
+
+        // screen.width must match too (separate path: inject layer R-010).
+        expect(probe.screenWidth).toBe(matrix.display.width);
+        expect(probe.screenHeight).toBe(matrix.display.height);
+      } finally {
+        await session.close();
+      }
+    },
+    TEST_TIMEOUT_MS,
+  );
+});

package/src/cdp/types.ts

@@ -68,6 +68,53 @@ export interface DomNode {
   nodeName: string;
 }
 
+/**
+ * Wider subset of `DOM.Node` used by the closed-shadow piercing locator
+ * (`Page.querySelectorPiercing`).
+ *
+ * Returned by `DOM.getDocument({ depth: -1, pierce: true })` — `pierce: true`
+ * yields shadow descendants under `shadowRoots[]` for *both* open and closed
+ * roots, and iframe descendants under `contentDocument`. Element-node fields
+ * (`localName`, `attributes`) drive selector matching in JS without round-
+ * tripping each candidate through `DOM.querySelector` (which would not pierce
+ * closed shadows even when called against the parent's document node).
+ *
+ * Reference: <https://chromedevtools.github.io/devtools-protocol/tot/DOM/#type-Node>
+ *
+ * @see PLAN.md §8.2 — `DOM.getDocument` and `DOM.resolveNode` are not on the
+ * forbidden list; both are fine to use.
+ * @see tasks/0253-closed-shadow-piercing-locator.md
+ */
+export interface PierceDomNode {
+  nodeId: number;
+  backendNodeId: number;
+  /** 1 = ELEMENT, 3 = TEXT, 9 = DOCUMENT, 11 = DOCUMENT_FRAGMENT, etc. */
+  nodeType: number;
+  /** Upper-case tag for element nodes (e.g. `"DIV"`); `"#document"` for the document. */
+  nodeName: string;
+  /** Lower-case tag (`"div"`) — only present on element nodes. */
+  localName?: string;
+  /** Flat `[name, value, name, value, ...]` array — only on element nodes. */
+  attributes?: string[];
+  /** Element / document children. */
+  children?: PierceDomNode[];
+  /**
+   * Shadow-root subtrees attached to this element. CDP yields BOTH open and
+   * closed shadows here when `pierce: true` is set; `shadowRootType` is
+   * `"open" | "closed" | "user-agent"`. The piercing walker traverses all of
+   * them — that's the whole point of this type vs. `DomNode`.
+   */
+  shadowRoots?: PierceDomNode[];
+  /** `"open" | "closed" | "user-agent"` — present on shadow-root nodes. */
+  shadowRootType?: "open" | "closed" | "user-agent";
+  /** iframe descendant tree. CDP yields it as a single-element array. */
+  contentDocument?: PierceDomNode;
+  /** Pseudo-element children (::before, ::after) — element nodes only. */
+  pseudoElements?: PierceDomNode[];
+  /** Template content fragment — present on `<template>` elements. */
+  templateContent?: PierceDomNode;
+}
+
 /** Subset of `Page.Frame`. */
 export interface PageFrame {
   id: string;

package/src/index.ts

@@ -44,6 +44,7 @@ export {
   type WaitState,
   type WaitUntil,
 } from "./page";
+export { ElementHandle, type ElementHandleInit } from "./page/element-handle";
 // Proxy URL parsing — exported so tests + downstream tools can normalize
 // proxy strings without going through `launch()`.
 export { type ParsedProxy, parseProxyUrl } from "./proxy-auth";

package/src/launch.ts

@@ -91,6 +91,16 @@ export interface LaunchOptions {
   args?: string[];
   out?: { traceDir?: string };
   timeout?: number;
+  /**
+   * Opt out of mochi's "auto-add `--no-sandbox` when running as root on
+   * Linux" fallback. Default `false` (the fallback is on). When `true`,
+   * mochi will NOT inject `--no-sandbox` even under root + Linux — useful
+   * if you've configured a SUID `chrome-sandbox` helper and want to keep
+   * the user-namespace sandbox active. The launch will crash with EPIPE
+   * if the SUID setup is wrong, but you keep stealth posture intact
+   * (`--no-sandbox` is a fingerprint leak per PLAN.md §8.6).
+   */
+  allowRootWithSandbox?: boolean;
   /**
    * When `true`, the {@link Session} skips both `buildPayload` (no payload
    * is compiled) and `Page.addScriptToEvaluateOnNewDocument` on every new
@@ -107,6 +117,27 @@ export interface LaunchOptions {
    * Chromium); task 0040.
    */
   bypassInject?: boolean;
+  /**
+   * When `true`, re-applies the harness/CI-only Chromium flags
+   * (`--disable-component-update`, `--disable-default-apps`,
+   * `--disable-background-networking`, `--disable-sync`, plus a noise-
+   * reduction `--disable-features=` block) on top of the production
+   * default flag set. Used by `@mochi.js/harness`, CI runs, and
+   * `mochi capture` flows where update traffic, default-apps auto-install,
+   * sync, and feed prefetches would inject non-determinism into baseline
+   * collection or stealth conformance.
+   *
+   * Defaults to `false` — production users get a cleaner flag set without
+   * the passive command-line bot-tells that patchright explicitly removes
+   * from its Playwright fork (`chromiumSwitchesPatch.ts:20-34`) and that
+   * `puppeteer-real-browser` strips for the same reason
+   * (`lib/cjs/index.js:57-58`).
+   *
+   * Pairs with — but is independent of — {@link bypassInject}. Capture
+   * flows set both `true`; harness conformance runs set `hermetic: true`
+   * with full inject pipeline active. PLAN.md §8.6 + task 0256.
+   */
+  hermetic?: boolean;
   /**
    * Convenience layer toggles for common bot-defense widgets. When
    * `challenges.turnstile.autoClick` is `true`, every page returned by
@@ -129,23 +160,57 @@ export interface LaunchOptions {
 export async function launch(opts: LaunchOptions): Promise<Session> {
   const binary = await resolveBinary(opts.binary);
   const normalized = normalizeProxy(opts.proxy);
+
+  // Resolve the `MatrixV1` BEFORE spawning so matrix-derived values flow
+  // into both the `--lang` flag (task 0251) and `--window-size` flag
+  // (task 0252). The matrix is otherwise read post-spawn for inject;
+  // deriving early is cheap (~µs, pure function) and lets us close the
+  // I-5 leaks between Chromium's native network/OS-window state and the
+  // JS-layer spoof.
+  //
+  // Inline `ProfileV1` objects flow straight through; string profile ids
+  // are resolved against a placeholder profile until `@mochi.js/profiles`
+  // ships its first capture (phase 0.4). The matrix is bit-stable per
+  // `(profile, seed)` excluding the `derivedAt` timestamp.
+  const profile = resolveProfile(opts.profile);
+  const matrix = deriveMatrix(profile, opts.seed);
+
   const proc = await spawnChromium({
     binary,
     extraArgs: opts.args,
     headless: opts.headless ?? false,
+    // Opt-out for the auto-no-sandbox-as-root fallback (default: fallback
+    // is on so first-run on a Linux server box doesn't crash).
+    ...(opts.allowRootWithSandbox === true ? { allowRootWithSandbox: true } : {}),
     // Chromium rejects inline auth on `--proxy-server`; pass the
     // auth-stripped server URL.
     ...(normalized !== undefined ? { proxy: normalized.server } : {}),
+    // Primary BCP-47 locale → `--lang=<value>`. Locks the network-layer
+    // `Accept-Language` header to the JS spoof (PLAN.md I-5). The full
+    // multi-locale list still flows through `matrix.languages` to the
+    // inject layer's `navigator.languages` spoof; Chromium derives the
+    // q-weighted `Accept-Language` value from the single `--lang` primary
+    // automatically. Task 0251.
+    locale: matrix.locale,
+    // Pin OS-level outer window from the matrix's display geometry so
+    // `window.outerWidth/outerHeight` (which reads from the OS window,
+    // NOT the JS-spoofed `screen.*`) matches the spoof. Closes the
+    // `fingerprint-scan.com` 800×600 leak under `--headless=new`.
+    // UDC fixes the same issue at `__init__.py:410-411`. Task 0252.
+    ...(Number.isInteger(matrix.display.width) &&
+    Number.isInteger(matrix.display.height) &&
+    matrix.display.width > 0 &&
+    matrix.display.height > 0
+      ? { windowSize: { width: matrix.display.width, height: matrix.display.height } }
+      : {}),
+    // Hermetic harness/CI escape hatch — re-applies the patchright-trim
+    // flags (`--disable-component-update`, `--disable-default-apps`,
+    // `--disable-background-networking`, `--disable-sync`, hermetic
+    // `--disable-features=` extras). Default `false` keeps production users
+    // off the passive command-line bot-tell list. Task 0256, PLAN.md §8.6.
+    ...(opts.hermetic === true ? { hermetic: true } : {}),
   });
 
-  // Resolve the `MatrixV1` for this session via the consistency engine.
-  // Inline `ProfileV1` objects flow straight through; string profile ids
-  // are resolved against a placeholder profile until `@mochi.js/profiles`
-  // ships its first capture (phase 0.4). The matrix is bit-stable per
-  // `(profile, seed)` excluding the `derivedAt` timestamp.
-  const profile = resolveProfile(opts.profile);
-  const matrix = deriveMatrix(profile, opts.seed);
-
   const session = new Session({
     proc,
     matrix,

package/src/page/element-handle.ts

@@ -0,0 +1,110 @@
+/**
+ * `ElementHandle` — lightweight wrapper around a CDP `RemoteObject` that lets
+ * callers operate on an element resolved via the closed-shadow piercing
+ * locator (`Page.querySelectorPiercing`).
+ *
+ * The handle is intentionally minimal — Phase 0.2 only needs enough surface
+ * for the Turnstile auto-clicker to ask "is this an iframe whose src matches
+ * cf-turnstile?" and then position a click. Wider parity with Playwright's
+ * `ElementHandle` (waitFor, fill, hover, screenshot…) is deferred — those
+ * compose on top of the same primitives once they're needed.
+ *
+ * Lifecycle: the underlying `objectId` is bound to a CDP `Runtime` execution
+ * context. Closing the page invalidates every handle the page produced; we
+ * don't try to release them via `Runtime.releaseObject` because there's no
+ * `Runtime.enable` in this session (PLAN.md §8.2). Stale handles surface as
+ * `Cannot find context with specified id` errors from the next CDP call,
+ * which is fine for a v0.2 surface.
+ *
+ * @see PLAN.md §8.2 / §8.3
+ * @see tasks/0253-closed-shadow-piercing-locator.md
+ */
+
+import type { MessageRouter } from "../cdp/router";
+import type { CdpSessionId, RemoteObject } from "../cdp/types";
+
+export interface ElementHandleInit {
+  router: MessageRouter;
+  sessionId: CdpSessionId;
+  objectId: string;
+  /** CDP `backendNodeId` — stable across DOM mutations. */
+  backendNodeId: number;
+}
+
+/**
+ * A handle to a single DOM element exposed to host-side automation. Issued
+ * by `Page.querySelectorPiercing` / `Page.querySelectorAllPiercing`.
+ */
+export class ElementHandle {
+  private readonly router: MessageRouter;
+  private readonly sessionId: CdpSessionId;
+  private readonly objectId: string;
+  private readonly _backendNodeId: number;
+
+  constructor(init: ElementHandleInit) {
+    this.router = init.router;
+    this.sessionId = init.sessionId;
+    this.objectId = init.objectId;
+    this._backendNodeId = init.backendNodeId;
+  }
+
+  /** The CDP `backendNodeId` for the element — stable across DOM mutations. */
+  get backendNodeId(): number {
+    return this._backendNodeId;
+  }
+
+  /**
+   * Read a single attribute via `Runtime.callFunctionOn`. Returns `null` when
+   * the attribute is absent (mirrors `Element.getAttribute`).
+   */
+  async getAttribute(name: string): Promise<string | null> {
+    const r = await this.router.send<{ result: RemoteObject }>(
+      "Runtime.callFunctionOn",
+      {
+        objectId: this.objectId,
+        functionDeclaration:
+          "function(n) { var v = this.getAttribute(n); return v === null ? null : String(v); }",
+        arguments: [{ value: name }],
+        returnByValue: true,
+      },
+      { sessionId: this.sessionId },
+    );
+    const v = r.result.value;
+    return v === null || v === undefined ? null : String(v);
+  }
+
+  /**
+   * Get the element's text content via `Runtime.callFunctionOn`.
+   */
+  async textContent(): Promise<string | null> {
+    const r = await this.router.send<{ result: RemoteObject }>(
+      "Runtime.callFunctionOn",
+      {
+        objectId: this.objectId,
+        functionDeclaration: "function() { return this.textContent; }",
+        returnByValue: true,
+      },
+      { sessionId: this.sessionId },
+    );
+    const v = r.result.value;
+    return v === null || v === undefined ? null : String(v);
+  }
+
+  /**
+   * Evaluate a function bound to this element (the handle is `this`). Result
+   * is JSON-serialised via `returnByValue: true`. Same contract as
+   * `Page.evaluate` — no closures, no arguments, no DOM-node returns.
+   */
+  async evaluate<T>(fn: (this: Element) => T): Promise<T> {
+    const r = await this.router.send<{ result: RemoteObject }>(
+      "Runtime.callFunctionOn",
+      {
+        objectId: this.objectId,
+        functionDeclaration: fn.toString(),
+        returnByValue: true,
+      },
+      { sessionId: this.sessionId },
+    );
+    return r.result.value as T;
+  }
+}