pi-browser-harness 0.10.2 → 0.11.0

package/src/cdp/record-store.ts

@@ -0,0 +1,61 @@
+export type DrainPage<T> = {
+  readonly records: T[];
+  readonly total: number;
+  readonly bufferOverflowed: boolean;
+};
+
+export type RecordStore<K, T> = {
+  set(key: K, rec: T): void;
+  get(key: K): T | undefined;
+  delete(key: K): void;
+  values(): IterableIterator<T>;
+  // Takes the overflow flag as it pages, so each drain reports only the loss since the previous one.
+  page(matched: T[], limit: number | undefined): DrainPage<T>;
+  clear(): void;
+};
+
+const MAX_LIMIT = 500;
+const DEFAULT_LIMIT = 50;
+
+export const createRecordStore = <K, T>(capacity: number): RecordStore<K, T> => {
+  const records = new Map<K, T>();
+  let overflowed = false;
+
+  const evictOldestIfFull = (): void => {
+    while (records.size >= capacity) {
+      const oldest = records.keys().next();
+      if (oldest.done) return;
+      records.delete(oldest.value);
+      overflowed = true;
+    }
+  };
+
+  return {
+    set(key, rec) {
+      evictOldestIfFull();
+      records.set(key, rec);
+    },
+    get(key) {
+      return records.get(key);
+    },
+    delete(key) {
+      records.delete(key);
+    },
+    values() {
+      return records.values();
+    },
+    page(matched, limit) {
+      const bufferOverflowed = overflowed;
+      overflowed = false;
+      return {
+        records: matched.slice(-Math.min(limit ?? DEFAULT_LIMIT, MAX_LIMIT)),
+        total: matched.length,
+        bufferOverflowed,
+      };
+    },
+    clear() {
+      records.clear();
+      overflowed = false;
+    },
+  };
+};

package/src/cdp/session.ts

@@ -1,15 +1,13 @@
-import { type Result, ok } from "../util/result";
-import type { CdpError } from "./errors";
+import { map, type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
 import type { DialogInfo } from "./types";
 import type { OwnershipRegistry } from "./ownership";
-import type { CdpTransport } from "./transport";
+import type { CdpTransport } from "./types";
+import { type CdpMethod, type ParamsOf, type ResultOf, decodeResult } from "./commands";
+import { decodeEvent } from "./events";
 import { createNetworkBuffer, type DrainResult, type NetworkFilter } from "./network-buffer";
 import { createConsoleBuffer, type ConsoleDrainResult, type ConsoleFilter } from "./console-buffer";
 
-// Per-tab state. One TabSession exists per known targetId.
-// Dialog, page-info dirty flag, and CDP buffers are per-tab — switching
-// tabs preserves the previous tab's data in its TabSession instead of
-// clearing it.
 type TabSession = {
   sessionId: string;
   targetId: string;
@@ -17,43 +15,33 @@ type TabSession = {
   pageInfoDirty: boolean;
   networkBuffer: ReturnType<typeof createNetworkBuffer>;
   consoleBuffer: ReturnType<typeof createConsoleBuffer>;
-  // Stable element refs (e1, e2, …) → CDP backendNodeId, from the latest
-  // snapshot of this tab. Replaced wholesale on every snapshot — old refs are
-  // stale anyway, so this stays bounded (~50–60 KB worst case).
   refMap: Map<string, number>;
-  // Per-ref signature ("role|name|value") from the latest snapshot, used as the
-  // baseline for the post-mutation auto-diff. Replaced alongside refMap.
   refSig: Map<string, string>;
 };
 
+const dialogType = (raw: string): DialogInfo["type"] =>
+  raw === "confirm" || raw === "prompt" || raw === "beforeunload" ? raw : "alert";
+
 export type CdpSession = {
   attachFirstPage(): Promise<Result<{ readonly targetId: string; readonly sessionId: string }, CdpError>>;
+  attach(targetId: string): Promise<Result<string, CdpError>>;
+  windowId(targetId: string): Promise<Result<number, CdpError>>;
   switchTo(targetId: string): Promise<Result<void, CdpError>>;
   current(): { readonly sessionId: string; readonly targetId: string } | null;
-  /** Replace the active tab's ref map and ref signatures (from a fresh snapshot). */
   setRefMap(refMap: Map<string, number>, refSig: Map<string, string>): void;
-  /** Resolve a ref (e.g. "e12") to its backendNodeId on the active tab, or undefined if unknown/stale. */
   resolveRef(ref: string): number | undefined;
-  /** The active tab's prior ref signatures — baseline for the post-mutation diff. */
   refSignatures(): ReadonlyMap<string, string>;
-  call(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
-  callOnTarget(method: string, params: Record<string, unknown>, sessionId: string, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
-  callBrowser(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
+  refMappings(): ReadonlyMap<string, number>;
+  call<M extends CdpMethod>(method: M, params?: ParamsOf<M>, opts?: { timeoutMs?: number }): Promise<Result<ResultOf<M>, CdpError>>;
+  callOnTarget<M extends CdpMethod>(method: M, params: ParamsOf<M>, sessionId: string, opts?: { timeoutMs?: number }): Promise<Result<ResultOf<M>, CdpError>>;
+  callBrowser<M extends CdpMethod>(method: M, params?: ParamsOf<M>, opts?: { timeoutMs?: number }): Promise<Result<ResultOf<M>, CdpError>>;
   takeDialog(): DialogInfo | null;
   drainPageInfoInvalidations(): boolean;
   drainNetworkBuffer(filter: NetworkFilter): DrainResult;
   drainConsoleBuffer(filter: ConsoleFilter): ConsoleDrainResult;
 };
 
-/**
- * Supplies the seed tab when attachFirstPage finds no owned tab to attach to.
- * Injected by the client so that seeding goes through the target factory —
- * which, with a profile pinned, opens the window inside that profile. Without
- * it, attachFirstPage's own `Target.createTarget` would land in whichever
- * profile currently has focus.
- *
- * The provider is responsible for its own ownership bookkeeping.
- */
+// Injected so seeding goes through the target factory; attachFirstPage's own `Target.createTarget` would land in whichever profile has focus.
 export type SeedTargetProvider = () => Promise<Result<string, CdpError>>;
 
 export const createCdpSession = (
@@ -64,15 +52,11 @@ export const createCdpSession = (
   let sessionId: string | null = null;
   let targetId: string | null = null;
 
-  // Per-tab tracking: maps targetId → TabSession and sessionId → targetId for
-  // event routing. Lazy: a TabSession is created on the first visit to a tab.
   const tabs = new Map<string, TabSession>();
   const sessionIdToTargetId = new Map<string, string>();
 
   let activeConsumer: Promise<void> = Promise.resolve();
 
-  // Event → TabSession resolver. Uses sessionId from CDP events to find the
-  // correct TabSession, falling back to the current targetId when no sessionId.
   const resolveTab = (evSessionId?: string): TabSession | undefined => {
     const tid = evSessionId ? sessionIdToTargetId.get(evSessionId) : targetId;
     return tid ? tabs.get(tid) : undefined;
@@ -80,81 +64,93 @@ export const createCdpSession = (
 
   const consumeEvents = async (): Promise<void> => {
     for await (const ev of transport.events()) {
-      // Filter: skip events from sessions we're not currently tracking.
-      // Target.targetDestroyed is browser-level (no sessionId) — always process.
       if (ev.method !== "Target.targetDestroyed") {
-        if (ev.sessionId && ev.sessionId !== sessionId) continue;
-      }
-      if (ev.method === "Page.javascriptDialogOpening") {
-        const tab = targetId ? tabs.get(targetId) : undefined;
-        if (!tab) continue;
-        const params = ev.params as Partial<DialogInfo> | undefined;
-        tab.dialog = {
-          type: (params?.type as DialogInfo["type"]) ?? "alert",
-          message: params?.message ?? "",
-          ...(params?.defaultPrompt !== undefined ? { defaultPrompt: params.defaultPrompt } : {}),
-        };
-        continue;
+        if (ev.sessionId && !sessionIdToTargetId.has(ev.sessionId)) continue;
       }
-      // Page.javascriptDialogClosed is intentionally NOT cleared here —
-      // the dialog stays in the buffer until takeDialog() is called.
-      // This prevents fast dismiss flows from dropping a dialog the agent
-      // was about to read. (Fix for spec §7 predictability bug #2.)
-      if (ev.method === "Page.frameNavigated" || ev.method === "Page.loadEventFired") {
-        const tab = targetId ? tabs.get(targetId) : undefined;
-        if (tab) tab.pageInfoDirty = true;
-      }
-      if (ev.method === "Target.targetCreated" && ownership) {
-        // Adopt tabs opened BY a tab we already own (window.open, target=_blank,
-        // popups). Chrome sets openerId to the opener target; if that opener is
-        // owned, the child belongs to this session's window and must be
-        // controllable + cleaned up. Targets the user opens themselves have no
-        // owned opener, so they are never adopted.
-        const info = (ev.params as { targetInfo?: { targetId?: string; type?: string; openerId?: string } } | undefined)?.targetInfo;
-        if (info?.type === "page" && info.targetId && info.openerId && ownership.has(info.openerId)) {
-          ownership.add(info.targetId);
+      switch (ev.method) {
+        case "Page.javascriptDialogOpening": {
+          const tab = resolveTab(ev.sessionId);
+          if (!tab) break;
+          const decoded = decodeEvent(ev.method, ev.params);
+          tab.dialog = decoded.success
+            ? {
+                type: dialogType(decoded.data.type),
+                message: decoded.data.message,
+                ...(decoded.data.defaultPrompt !== undefined
+                  ? { defaultPrompt: decoded.data.defaultPrompt }
+                  : {}),
+              }
+            : { type: "alert", message: "" };
+          break;
         }
-      }
-      if (ev.method === "Target.targetDestroyed" && ownership) {
-        const params = ev.params as { targetId?: string } | undefined;
-        if (params?.targetId) {
-          ownership.remove(params.targetId);
-          // Prune per-tab state for the destroyed target
-          const tab = tabs.get(params.targetId);
+        // Intentionally NOT cleared on javascriptDialogClosed: a fast dismiss would otherwise drop a dialog the agent was about to read.
+        case "Page.frameNavigated":
+        case "Page.loadEventFired": {
+          const tab = resolveTab(ev.sessionId);
+          if (tab) tab.pageInfoDirty = true;
+          break;
+        }
+        case "Target.targetCreated": {
+          if (!ownership) break;
+          const decoded = decodeEvent(ev.method, ev.params);
+          if (!decoded.success) break;
+          const info = decoded.data.targetInfo;
+          if (info.type === "page" && info.targetId && info.openerId && ownership.has(info.openerId)) {
+            ownership.add(info.targetId);
+          }
+          break;
+        }
+        case "Target.targetDestroyed": {
+          if (!ownership) break;
+          const decoded = decodeEvent(ev.method, ev.params);
+          if (!decoded.success || !decoded.data.targetId) break;
+          const destroyed = decoded.data.targetId;
+          ownership.remove(destroyed);
+          const tab = tabs.get(destroyed);
           if (tab) {
             sessionIdToTargetId.delete(tab.sessionId);
-            tabs.delete(params.targetId);
+            tabs.delete(destroyed);
           }
+          break;
         }
-      }
-      if (ev.method === "Network.requestWillBeSent") {
-        const tab = resolveTab(ev.sessionId);
-        if (tab) tab.networkBuffer.ingestRequestWillBeSent(ev.params);
-      } else if (ev.method === "Network.responseReceived") {
-        const tab = resolveTab(ev.sessionId);
-        if (tab) tab.networkBuffer.ingestResponseReceived(ev.params);
-      } else if (ev.method === "Network.loadingFinished") {
-        const tab = resolveTab(ev.sessionId);
-        if (tab) tab.networkBuffer.ingestLoadingFinished(ev.params);
-      } else if (ev.method === "Network.loadingFailed") {
-        const tab = resolveTab(ev.sessionId);
-        if (tab) tab.networkBuffer.ingestLoadingFailed(ev.params);
-      } else if (ev.method === "Runtime.consoleAPICalled") {
-        const tab = resolveTab(ev.sessionId);
-        if (tab) tab.consoleBuffer.ingestConsoleApi(ev.params);
-      } else if (ev.method === "Log.entryAdded") {
-        const tab = resolveTab(ev.sessionId);
-        if (tab) tab.consoleBuffer.ingestLogEntry(ev.params);
+        case "Network.requestWillBeSent": {
+          const tab = resolveTab(ev.sessionId);
+          if (tab) tab.networkBuffer.ingestRequestWillBeSent(ev.params);
+          break;
+        }
+        case "Network.responseReceived": {
+          const tab = resolveTab(ev.sessionId);
+          if (tab) tab.networkBuffer.ingestResponseReceived(ev.params);
+          break;
+        }
+        case "Network.loadingFinished": {
+          const tab = resolveTab(ev.sessionId);
+          if (tab) tab.networkBuffer.ingestLoadingFinished(ev.params);
+          break;
+        }
+        case "Network.loadingFailed": {
+          const tab = resolveTab(ev.sessionId);
+          if (tab) tab.networkBuffer.ingestLoadingFailed(ev.params);
+          break;
+        }
+        case "Runtime.consoleAPICalled": {
+          const tab = resolveTab(ev.sessionId);
+          if (tab) tab.consoleBuffer.ingestConsoleApi(ev.params);
+          break;
+        }
+        case "Log.entryAdded": {
+          const tab = resolveTab(ev.sessionId);
+          if (tab) tab.consoleBuffer.ingestLogEntry(ev.params);
+          break;
+        }
+        default:
+          break;
       }
     }
   };
 
   const restartConsumer = (): void => {
     activeConsumer = activeConsumer.then(() => consumeEvents()).catch((e: unknown) => {
-      // The .then() chain calls consumeEvents() which iterates the transport's
-      // events() AsyncIterable. The iterable resolves cleanly on close (returns
-      // {done:true}); any rejection here is an unexpected bug in the event
-      // handler, not a normal termination. Surface it on stderr so it's not lost.
       console.warn("[pi-browser-harness] CDP event consumer crashed:", e);
     });
   };
@@ -165,37 +161,45 @@ export const createCdpSession = (
     targetId = null;
     tabs.clear();
     sessionIdToTargetId.clear();
-    // Do NOT clear `dialog` here — same rationale as inside consumeEvents:
-    // the agent may have a pending takeDialog() call that should still see it.
+    // Do NOT clear `dialog` here: a pending takeDialog() must still see it.
     restartConsumer();
   });
 
-  // TODO(perf): the four enable calls are sequential here for predictability.
-  // Switching to Promise.all over a single WS pipelines the round-trips and
-  // saves ~3× on tab-switch latency. Defer until session.ts has tests.
   const enableDomains = async (sid: string): Promise<void> => {
     for (const d of ["Page", "DOM", "Runtime", "Network", "Accessibility", "Log"]) {
       await transport.request(`${d}.enable`, {}, { sessionId: sid });
     }
   };
 
-  // CDP response shapes are documented in chromedevtools.github.io but not
-  // available as TypeScript types. We cast `as` from `unknown` only in this
-  // file (the CDP boundary). Each cast is paired with the CDP method that
-  // produced the response. Adding runtime guards for every shape would be
-  // noise — Chrome's protocol is stable enough that a wrong cast surfaces
-  // as a clear Error in normal use.
-  return {
+  const req = async <M extends CdpMethod>(
+    method: M,
+    params: ParamsOf<M> | undefined,
+    sid: string | null,
+    opts: { timeoutMs?: number } = {},
+  ): Promise<Result<ResultOf<M>, CdpError>> => {
+    const raw = await transport.request(method, { ...(params ?? {}) }, {
+      sessionId: sid,
+      ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+    });
+    if (!raw.success) return raw;
+    return decodeResult(method, raw.data);
+  };
+
+  const attach = async (tid: string): Promise<Result<string, CdpError>> =>
+    map(await req("Target.attachToTarget", { targetId: tid, flatten: true }, null), (d) => d.sessionId);
+
+  const windowId = async (tid: string): Promise<Result<number, CdpError>> =>
+    map(await req("Browser.getWindowForTarget", { targetId: tid }, null), (d) => d.windowId);
+
+  const currentTab = (): TabSession | undefined => (targetId ? tabs.get(targetId) : undefined);
+
+  const session: CdpSession = {
     async attachFirstPage() {
-      // Subscribe to Target.* events so we can react to targetDestroyed.
-      // Best-effort: failing to enable discovery is not fatal for attach.
-      await transport.request("Target.setDiscoverTargets", { discover: true }, { sessionId: null });
+      await req("Target.setDiscoverTargets", { discover: true }, null);
 
-      const targets = await transport.request("Target.getTargets", {}, { sessionId: null });
+      const targets = await req("Target.getTargets", {}, null);
       if (!targets.success) return targets;
-      const data = targets.data as { targetInfos: ReadonlyArray<{ targetId: string; type: string; url: string }> };
-      const allPages = data.targetInfos.filter((t) => t.type === "page");
-      // Reconcile the persisted ownership set against live targets — drop dead IDs.
+      const allPages = targets.data.targetInfos.filter((t) => t.type === "page");
       if (ownership) {
         const live = new Set(allPages.map((p) => p.targetId));
         const survivors = ownership.list().filter((id) => live.has(id));
@@ -203,44 +207,31 @@ export const createCdpSession = (
         const hw = ownership.harnessWindow();
         if (hw && !live.has(hw)) ownership.setHarnessWindow(undefined);
 
-        if (survivors.length === 0) {
-          // No owned tab survived — the harness window is gone (user closed it,
-          // or Chrome restarted and reassigned all ids). The persisted windowId
-          // is now meaningless and could even collide with one of the user's
-          // windows, so drop it. attachFirstPage will mint a fresh window below.
+        const anchorId = survivors[0];
+        if (anchorId === undefined) {
           ownership.setHarnessWindowId(undefined);
         } else {
-          // Self-heal ownership from the window itself. We anchor on a tab we
-          // KNOW we own (a survivor) and re-adopt only its live window-mates —
-          // popups/children from last session, tabs reopened in our window.
-          // Ownership is thus DERIVED from the real window, never from the bare
-          // persisted integer (which Chrome may reassign to a user window on
-          // restart — anchoring on a survivor makes that misfire impossible).
-          const anchorId = survivors[0]!;
-          const anchorWin = await transport.request("Browser.getWindowForTarget", { targetId: anchorId }, { sessionId: null });
+          const anchorWin = await windowId(anchorId);
           if (anchorWin.success) {
-            const anchorWindowId = (anchorWin.data as { windowId?: number }).windowId;
-            if (typeof anchorWindowId === "number") {
-              ownership.setHarnessWindowId(anchorWindowId); // refresh to the live id
-              const windows = await Promise.all(
-                allPages.map((p) =>
-                  p.targetId === anchorId
-                    ? Promise.resolve(anchorWin)
-                    : transport.request("Browser.getWindowForTarget", { targetId: p.targetId }, { sessionId: null }),
-                ),
-              );
-              allPages.forEach((p, i) => {
-                const r = windows[i];
-                if (r?.success && (r.data as { windowId?: number }).windowId === anchorWindowId) {
-                  ownership.add(p.targetId);
-                }
-              });
-            }
+            const anchorWindowId = anchorWin.data;
+            ownership.setHarnessWindowId(anchorWindowId);
+            const windows = await Promise.all(
+              allPages.map((p) =>
+                p.targetId === anchorId
+                  ? Promise.resolve(anchorWin)
+                  : windowId(p.targetId),
+              ),
+            );
+            allPages.forEach((p, i) => {
+              const r = windows[i];
+              if (r?.success && r.data === anchorWindowId) {
+                ownership.add(p.targetId);
+              }
+            });
           }
           if (!ownership.harnessWindow()) ownership.setHarnessWindow(anchorId);
         }
       }
-      // Prune per-tab state for pages that no longer exist
       const liveTargetIds = new Set(allPages.map((p) => p.targetId));
       for (const tid of tabs.keys()) {
         if (!liveTargetIds.has(tid)) {
@@ -250,49 +241,39 @@ export const createCdpSession = (
         }
       }
 
-      // Prefer attaching to a tab this session already owns. Falls back to
-      // creating a fresh harness-owned tab in a dedicated window — never
-      // grabs the user's foreground tab.
       let pickTargetId: string | undefined;
       if (ownership) {
         const ownedLive = ownership.list().filter((id) => allPages.some((p) => p.targetId === id));
         pickTargetId = ownedLive[0];
       }
       if (!pickTargetId && createSeedTarget) {
-        // Delegated seeding (see SeedTargetProvider): the provider creates the
-        // window in the right profile and records ownership itself.
         const seeded = await createSeedTarget();
         if (!seeded.success) return seeded;
         pickTargetId = seeded.data;
       }
       if (!pickTargetId) {
-        const createParams: Record<string, unknown> = { url: "about:blank" };
-        if (ownership) createParams["newWindow"] = true;
-        const created = await transport.request("Target.createTarget", createParams, { sessionId: null });
+        const created = await req(
+          "Target.createTarget",
+          { url: "about:blank", ...(ownership ? { newWindow: true } : {}) },
+          null,
+        );
         if (!created.success) return created;
-        const c = created.data as { targetId: string };
-        pickTargetId = c.targetId;
+        pickTargetId = created.data.targetId;
         if (ownership) {
-          ownership.setHarnessWindow(c.targetId);
-          ownership.add(c.targetId);
-          // Capture the real Chrome windowId — the durable identity of the
-          // window this session initialized (survives seed-tab closure).
-          const win = await transport.request("Browser.getWindowForTarget", { targetId: c.targetId }, { sessionId: null });
-          if (win.success) {
-            const wid = (win.data as { windowId?: number }).windowId;
-            if (typeof wid === "number") ownership.setHarnessWindowId(wid);
-          }
+          ownership.setHarnessWindow(created.data.targetId);
+          ownership.add(created.data.targetId);
+          const win = await windowId(created.data.targetId);
+          if (win.success) ownership.setHarnessWindowId(win.data);
         }
       }
 
-      const attached = await transport.request("Target.attachToTarget", { targetId: pickTargetId, flatten: true }, { sessionId: null });
+      const attached = await attach(pickTargetId);
       if (!attached.success) return attached;
-      const a = attached.data as { sessionId: string };
-      sessionId = a.sessionId;
+      const attachedSessionId = attached.data;
+      sessionId = attachedSessionId;
       targetId = pickTargetId;
-      await enableDomains(a.sessionId);
       tabs.set(pickTargetId, {
-        sessionId: a.sessionId,
+        sessionId: attachedSessionId,
         targetId: pickTargetId,
         dialog: null,
         pageInfoDirty: false,
@@ -301,19 +282,19 @@ export const createCdpSession = (
         refMap: new Map(),
         refSig: new Map(),
       });
-      sessionIdToTargetId.set(a.sessionId, pickTargetId);
-      return ok({ targetId: pickTargetId, sessionId: a.sessionId });
+      sessionIdToTargetId.set(attachedSessionId, pickTargetId);
+      await enableDomains(attachedSessionId);
+      return ok({ targetId: pickTargetId, sessionId: attachedSessionId });
     },
     async switchTo(tid) {
-      const activated = await transport.request("Target.activateTarget", { targetId: tid }, { sessionId: null });
+      const activated = await req("Target.activateTarget", { targetId: tid }, null);
       if (!activated.success) return activated;
-      const attached = await transport.request("Target.attachToTarget", { targetId: tid, flatten: true }, { sessionId: null });
+      const attached = await attach(tid);
       if (!attached.success) return attached;
-      const a = attached.data as { sessionId: string };
-      // Reuse existing TabSession or create one on first visit
+      const attachedSessionId = attached.data;
       const existing = tabs.get(tid);
       const tab: TabSession = existing ?? {
-        sessionId: a.sessionId,
+        sessionId: attachedSessionId,
         targetId: tid,
         dialog: null,
         pageInfoDirty: true,
@@ -323,69 +304,100 @@ export const createCdpSession = (
         refSig: new Map(),
       };
       if (existing) {
-        // Each Target.attachToTarget produces a new sessionId — update it.
         sessionIdToTargetId.delete(existing.sessionId);
-        existing.sessionId = a.sessionId;
-        sessionIdToTargetId.set(a.sessionId, tid);
+        existing.sessionId = attachedSessionId;
       } else {
         tabs.set(tid, tab);
-        await enableDomains(a.sessionId);
-        sessionIdToTargetId.set(a.sessionId, tid);
       }
-      // Update global pointers to point at the new active tab
+      sessionIdToTargetId.set(attachedSessionId, tid);
+      await enableDomains(attachedSessionId);
       sessionId = tab.sessionId;
       targetId = tid;
       return ok(undefined);
     },
+    attach,
+    windowId,
     current() {
       return sessionId && targetId ? { sessionId, targetId } : null;
     },
     setRefMap(refMap, refSig) {
-      const tab = targetId ? tabs.get(targetId) : undefined;
+      const tab = currentTab();
       if (!tab) return;
       tab.refMap = refMap;
       tab.refSig = refSig;
     },
     resolveRef(ref) {
-      const tab = targetId ? tabs.get(targetId) : undefined;
+      const tab = currentTab();
       return tab?.refMap.get(ref);
     },
     refSignatures() {
-      const tab = targetId ? tabs.get(targetId) : undefined;
+      const tab = currentTab();
       return tab?.refSig ?? new Map();
     },
-    call(method, params = {}, opts = {}) {
-      return transport.request(method, params, { sessionId, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    refMappings() {
+      const tab = currentTab();
+      return tab?.refMap ?? new Map();
+    },
+    call(method, params, opts) {
+      return req(method, params, sessionId, opts);
     },
-    callOnTarget(method, params, sid, opts = {}) {
-      return transport.request(method, params, { sessionId: sid, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    callOnTarget(method, params, sid, opts) {
+      return req(method, params, sid, opts);
     },
-    callBrowser(method, params = {}, opts = {}) {
-      return transport.request(method, params, { sessionId: null, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    callBrowser(method, params, opts) {
+      return req(method, params, null, opts);
     },
     takeDialog() {
-      const tab = targetId ? tabs.get(targetId) : undefined;
+      const tab = currentTab();
       if (!tab) return null;
       const d = tab.dialog;
       tab.dialog = null;
       return d;
     },
     drainPageInfoInvalidations() {
-      const tab = targetId ? tabs.get(targetId) : undefined;
+      const tab = currentTab();
       if (!tab) return false;
       const dirty = tab.pageInfoDirty;
       tab.pageInfoDirty = false;
       return dirty;
     },
     drainNetworkBuffer(filter) {
-      const tab = targetId ? tabs.get(targetId) : undefined;
+      const tab = currentTab();
       if (!tab) return { records: [], total: 0, bufferOverflowed: false };
       return tab.networkBuffer.drain(filter);
     },
     drainConsoleBuffer(filter) {
-      const tab = targetId ? tabs.get(targetId) : undefined;
+      const tab = currentTab();
       if (!tab) return { records: [], total: 0, bufferOverflowed: false };
       return tab.consoleBuffer.drain(filter);
     },
   };
+  return session;
+};
+
+export const evaluateJson = async <T>(
+  session: CdpSession,
+  expression: string,
+  check: (v: unknown) => v is T,
+  opts?: { sessionId?: string | undefined; timeoutMs?: number | undefined },
+): Promise<Result<T, CdpError>> => {
+  const params = {
+    expression,
+    returnByValue: true,
+    awaitPromise: true,
+  };
+  const callOpts = opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {};
+  const r = opts?.sessionId !== undefined
+    ? await session.callOnTarget("Runtime.evaluate", params, opts.sessionId, callOpts)
+    : await session.call("Runtime.evaluate", params, callOpts);
+  if (!r.success) return r;
+  const { result, exceptionDetails } = r.data;
+  if (exceptionDetails !== undefined) {
+    return err(cdpError("remote_error", exceptionDetails.text, "Runtime.evaluate"));
+  }
+  const value = result.value;
+  if (!check(value)) {
+    return err(cdpError("invalid_response", `unexpected evaluate shape (type: ${result.type}) for: ${expression.slice(0, 60)}`, "Runtime.evaluate"));
+  }
+  return ok(value);
 };