@monoes/monobrowse 1.0.0

package/src/browser/find.ts

@@ -0,0 +1,225 @@
+import type { CdpClient } from './cdp.js';
+import type { ElementRef } from './types.js';
+import { evaluateJs } from './actions.js';
+import { getObjectIdForRef } from './snapshot.js';
+
+export type FindAction = 'click' | 'fill' | 'type' | 'hover' | 'focus' | 'check' | 'uncheck' | 'text';
+
+export interface FindOptions {
+  name?: string;
+  exact?: boolean;
+  nth?: number;
+  first?: boolean;
+  last?: boolean;
+}
+
+export async function findBySelector(
+  client: CdpClient,
+  sessionId: string,
+  refs: Map<string, ElementRef>,
+  selector: string,
+  options: FindOptions = {}
+): Promise<ElementRef | null> {
+  if (options.nth !== undefined && options.nth < 1) {
+    throw new Error(`nth must be >= 1 (received ${options.nth})`);
+  }
+  try {
+    const doc = await client.send<{ root: { nodeId: number } }>('DOM.getDocument', {}, sessionId);
+
+    let targetNodeId: number;
+    if (options.nth !== undefined || options.last) {
+      const result = await client.send<{ nodeIds: number[] }>(
+        'DOM.querySelectorAll', { nodeId: doc.root.nodeId, selector }, sessionId
+      );
+      const nodeIds = result.nodeIds ?? [];
+      if (nodeIds.length === 0) return null;
+      targetNodeId = options.last ? nodeIds[nodeIds.length - 1] : (nodeIds[(options.nth ?? 1) - 1] ?? 0);
+    } else {
+      const result = await client.send<{ nodeId: number }>(
+        'DOM.querySelector', { nodeId: doc.root.nodeId, selector }, sessionId
+      );
+      targetNodeId = result.nodeId ?? 0;
+    }
+
+    if (!targetNodeId) return null;
+
+    const desc = await client.send<{ node: { backendNodeId: number } }>(
+      'DOM.describeNode', { nodeId: targetNodeId }, sessionId
+    );
+    const backendDOMNodeId = desc.node?.backendNodeId;
+    if (!backendDOMNodeId) return null;
+
+    // Return existing ref from snapshot if this node is already indexed
+    const existing = [...refs.values()].find((r) => r.backendDOMNodeId === backendDOMNodeId);
+    if (existing) return existing;
+
+    // Synthetic ref for elements not represented in the AX tree — insert into refs so it can be used in subsequent commands
+    const syntheticRef: ElementRef = { ref: `sel-${backendDOMNodeId}`, role: 'generic', name: selector, nodeId: targetNodeId, backendDOMNodeId };
+    refs.set(syntheticRef.ref, syntheticRef);
+    return syntheticRef;
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/invalid|illegal|SyntaxError/i.test(msg)) throw err;
+    return null;
+  }
+}
+
+export async function findByRole(
+  client: CdpClient,
+  sessionId: string,
+  refs: Map<string, ElementRef>,
+  role: string,
+  options: FindOptions = {}
+): Promise<ElementRef | null> {
+  if (options.nth !== undefined && options.nth < 1) {
+    throw new Error(`nth must be >= 1 (received ${options.nth})`);
+  }
+  const lowerRole = role.toLowerCase();
+  const candidates = [...refs.values()].filter((r) => r.role.toLowerCase() === lowerRole);
+
+  let matches = candidates;
+  if (options.name) {
+    const nameLower = options.name.toLowerCase();
+    matches = options.exact
+      ? candidates.filter((r) => r.name.toLowerCase() === nameLower)
+      : candidates.filter((r) => r.name.toLowerCase().includes(nameLower));
+  }
+
+  if (matches.length === 0) return null;
+  if (options.nth !== undefined) return matches[options.nth - 1] ?? null;
+  if (options.last) return matches[matches.length - 1];
+  return matches[0];
+}
+
+export async function findByText(
+  client: CdpClient,
+  sessionId: string,
+  refs: Map<string, ElementRef>,
+  text: string,
+  options: FindOptions = {}
+): Promise<ElementRef | null> {
+  if (options.nth !== undefined && options.nth < 1) {
+    throw new Error(`nth must be >= 1 (received ${options.nth})`);
+  }
+  const lower = text.toLowerCase();
+  const candidates = [...refs.values()].filter((r) =>
+    options.exact ? r.name.toLowerCase() === lower : r.name.toLowerCase().includes(lower)
+  );
+  if (options.nth !== undefined) return candidates[options.nth - 1] ?? null;
+  if (options.last) return candidates[candidates.length - 1] ?? null;
+  return candidates[0] ?? null;
+}
+
+export async function findByLabel(
+  client: CdpClient,
+  sessionId: string,
+  refs: Map<string, ElementRef>,
+  label: string,
+  options: FindOptions = {}
+): Promise<ElementRef | null> {
+  return findByText(client, sessionId, refs, label, options);
+}
+
+export async function findByPlaceholder(
+  client: CdpClient,
+  sessionId: string,
+  refs: Map<string, ElementRef>,
+  placeholder: string,
+  options: FindOptions = {}
+): Promise<ElementRef | null> {
+  if (options.nth !== undefined && options.nth < 1) {
+    throw new Error(`nth must be >= 1 (received ${options.nth})`);
+  }
+  const lower = placeholder.toLowerCase();
+  const candidates = [...refs.values()].filter((r) => {
+    const ph = (r.placeholder ?? '').toLowerCase();
+    return options.exact ? ph === lower : ph.includes(lower);
+  });
+  if (options.nth !== undefined) return candidates[options.nth - 1] ?? null;
+  if (options.last) return candidates[candidates.length - 1] ?? null;
+  return candidates[0] ?? null;
+}
+
+export async function findByTestId(
+  client: CdpClient,
+  sessionId: string,
+  testId: string
+): Promise<string | null> {
+  const escapedId = testId.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  const selectors = [
+    `[data-testid="${escapedId}"]`,
+    `[data-test-id="${escapedId}"]`,
+    `[data-test="${escapedId}"]`,
+  ];
+  for (const sel of selectors) {
+    const result = await evaluateJs(client, sessionId, `!!document.querySelector(${JSON.stringify(sel)})`);
+    if (result) return sel;
+  }
+  return null;
+}
+
+export async function isVisible(client: CdpClient, sessionId: string, ref: ElementRef): Promise<boolean> {
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (!objectId) return false;
+
+  const result = await client.send<{ result: { value?: boolean } }>('Runtime.callFunctionOn', {
+    functionDeclaration: `function() {
+      const rect = this.getBoundingClientRect();
+      const style = window.getComputedStyle(this);
+      return rect.width > 0 && rect.height > 0 &&
+             style.display !== 'none' &&
+             style.visibility !== 'hidden' &&
+             style.opacity !== '0';
+    }`,
+    objectId,
+    returnByValue: true,
+  }, sessionId);
+  return result.result?.value ?? false;
+}
+
+export async function isEnabled(client: CdpClient, sessionId: string, ref: ElementRef): Promise<boolean> {
+  return !ref.disabled;
+}
+
+export async function isChecked(client: CdpClient, sessionId: string, ref: ElementRef): Promise<boolean> {
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (!objectId) return false;
+
+  const result = await client.send<{ result: { value?: boolean } }>('Runtime.callFunctionOn', {
+    functionDeclaration: 'function() { return !!this.checked; }',
+    objectId,
+    returnByValue: true,
+  }, sessionId);
+  return result.result?.value ?? false;
+}
+
+export async function scrollIntoView(client: CdpClient, sessionId: string, ref: ElementRef): Promise<void> {
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (!objectId) throw new Error(`Cannot scroll: ref @${ref.ref} not found in DOM`);
+
+  await client.send('Runtime.callFunctionOn', {
+    functionDeclaration: 'function() { this.scrollIntoView({ behavior: "smooth", block: "center" }); }',
+    objectId,
+    returnByValue: true,
+  }, sessionId);
+}
+
+export async function highlightElement(client: CdpClient, sessionId: string, ref: ElementRef): Promise<void> {
+  const objectId = await getObjectIdForRef(client, sessionId, ref);
+  if (!objectId) return;
+
+  await client.send('Runtime.callFunctionOn', {
+    functionDeclaration: `function() {
+      const prev = this.style.outline;
+      const prevBg = this.style.backgroundColor;
+      this.style.outline = '3px solid #ff5722';
+      this.style.backgroundColor = 'rgba(255, 87, 34, 0.1)';
+      setTimeout(() => {
+        this.style.outline = prev;
+        this.style.backgroundColor = prevBg;
+      }, 2000);
+    }`,
+    objectId,
+    returnByValue: true,
+  }, sessionId);
+}

package/src/browser/har.ts

@@ -0,0 +1,202 @@
+import type { CdpClient } from './cdp.js';
+import { writeFile } from 'fs/promises';
+import { join, resolve, relative, isAbsolute } from 'path';
+import { tmpdir, homedir } from 'os';
+
+interface HarRequest {
+  id: string;
+  url: string;
+  method: string;
+  status: number;
+  statusText: string;
+  mimeType: string;
+  requestHeaders: Record<string, string>;
+  responseHeaders: Record<string, string>;
+  startTime: number;
+  endTime: number;
+  size: number;
+  encodedSize: number;
+  fromCache: boolean;
+  responseBody?: string;
+  bodyEncoding?: 'base64';
+}
+
+const MAX_CONCURRENT_SESSIONS = 100;
+const MAX_REQUESTS_PER_SESSION = 5_000;
+
+const _sessions = new Map<string, {
+  requests: Map<string, Partial<HarRequest>>;
+  offReq: () => void;
+  offResp: () => void;
+  offFinished: () => void;
+  startTime: number;
+  startWallMs: number;
+}>();
+
+/** Validate output path is within cwd or home dir to prevent path traversal. */
+function safeOutputPath(p: string): string {
+  const resolved = resolve(p);
+  const cwd = process.cwd();
+  const home = homedir();
+  const relCwd = relative(cwd, resolved);
+  const relHome = relative(home, resolved);
+  if ((!relCwd.startsWith('..') && !isAbsolute(relCwd)) ||
+      (!relHome.startsWith('..') && !isAbsolute(relHome))) {
+    return resolved;
+  }
+  // Reject out-of-scope paths — fall back to tmpdir
+  return join(tmpdir(), `monomind-har-${Date.now()}.har`);
+}
+
+export async function startHarRecording(client: CdpClient, sessionId: string): Promise<void> {
+  if (_sessions.has(sessionId)) throw new Error('HAR recording already in progress');
+  if (_sessions.size >= MAX_CONCURRENT_SESSIONS) {
+    throw new Error(`HAR recording limit reached (max ${MAX_CONCURRENT_SESSIONS} concurrent sessions)`);
+  }
+
+  const requests = new Map<string, Partial<HarRequest>>();
+  const startTime = Date.now();
+  const startWallMs = startTime;
+  let refCdpTs = 0;
+
+  const cdpToWall = (cdpTs: number) => {
+    if (refCdpTs === 0) refCdpTs = cdpTs;
+    return startWallMs + (cdpTs - refCdpTs) * 1000;
+  };
+
+  const offReq = client.on('Network.requestWillBeSent', (params, sid) => {
+    if (sid !== sessionId) return;
+    // Cap to prevent unbounded memory growth on high-traffic pages
+    if (requests.size >= MAX_REQUESTS_PER_SESSION) return;
+    const p = params as { requestId: string; request: { url: string; method: string; headers: Record<string, string> }; timestamp: number };
+    requests.set(p.requestId, {
+      id: p.requestId,
+      url: p.request.url,
+      method: p.request.method,
+      requestHeaders: p.request.headers,
+      startTime: cdpToWall(p.timestamp),
+      fromCache: false,
+    });
+  });
+
+  const offResp = client.on('Network.responseReceived', (params, sid) => {
+    if (sid !== sessionId) return;
+    const p = params as { requestId: string; response: { url: string; status: number; statusText: string; mimeType: string; headers: Record<string, string>; fromDiskCache: boolean; fromServiceWorker: boolean }; timestamp: number };
+    const entry = requests.get(p.requestId);
+    if (entry) {
+      entry.status = p.response.status;
+      entry.statusText = p.response.statusText;
+      entry.mimeType = p.response.mimeType;
+      entry.responseHeaders = p.response.headers;
+      entry.fromCache = p.response.fromDiskCache || p.response.fromServiceWorker;
+      entry.endTime = cdpToWall(p.timestamp);
+    }
+  });
+
+  const offFinished = client.on('Network.loadingFinished', (params, sid) => {
+    if (sid !== sessionId) return;
+    const p = params as { requestId: string; encodedDataLength: number; timestamp: number };
+    const entry = requests.get(p.requestId);
+    if (entry) {
+      entry.encodedSize = p.encodedDataLength;
+      entry.endTime = cdpToWall(p.timestamp);
+    }
+  });
+
+  _sessions.set(sessionId, { requests, offReq, offResp, offFinished, startTime, startWallMs });
+}
+
+export async function stopHarRecording(
+  client: CdpClient,
+  sessionId: string,
+  outputPath?: string,
+  captureResponseBodies = false
+): Promise<string> {
+  const state = _sessions.get(sessionId);
+  if (!state) throw new Error('No active HAR recording for this session');
+
+  state.offReq();
+  state.offResp();
+  state.offFinished();
+  _sessions.delete(sessionId); // remove immediately after detaching listeners to prevent duplicate invocations
+
+  // Optionally fetch response bodies
+  if (captureResponseBodies) {
+    for (const [reqId, entry] of state.requests.entries()) {
+      try {
+        const body = await client.send<{ body: string; base64Encoded: boolean }>(
+          'Network.getResponseBody', { requestId: reqId }, sessionId
+        );
+        entry.responseBody = body.body;
+        entry.bodyEncoding = body.base64Encoded ? 'base64' : undefined;
+        entry.size = body.base64Encoded
+          ? Buffer.byteLength(body.body, 'base64')
+          : Buffer.byteLength(body.body, 'utf8');
+      } catch {
+        // body may not be available for cached/redirected responses
+      }
+    }
+  }
+
+  const har = buildHar(Array.from(state.requests.values()), state.startTime);
+  const safePath = outputPath ? safeOutputPath(outputPath) : join(tmpdir(), `monomind-har-${Date.now()}.har`);
+  await writeFile(safePath, JSON.stringify(har, null, 2));
+  return safePath;
+}
+
+export function getHarStatus(sessionId: string): { recording: boolean; requestCount: number } {
+  const state = _sessions.get(sessionId);
+  return { recording: !!state, requestCount: state?.requests.size ?? 0 };
+}
+
+export function getRequests(sessionId: string): Partial<HarRequest>[] {
+  const state = _sessions.get(sessionId);
+  return state ? Array.from(state.requests.values()) : [];
+}
+
+function buildHar(entries: Partial<HarRequest>[], startTime: number) {
+  return {
+    log: {
+      version: '1.2',
+      creator: { name: 'monomind browse', version: '1.0.0' },
+      pages: [{
+        startedDateTime: new Date(startTime).toISOString(),
+        id: 'page_1',
+        title: '',
+        pageTimings: {},
+      }],
+      entries: entries.map((e) => ({
+        startedDateTime: new Date(e.startTime ?? startTime).toISOString(),
+        time: (e.endTime ?? e.startTime ?? startTime) - (e.startTime ?? startTime),
+        request: {
+          method: e.method ?? 'GET',
+          url: e.url ?? '',
+          httpVersion: 'HTTP/1.1',
+          cookies: [],
+          headers: Object.entries(e.requestHeaders ?? {}).map(([name, value]) => ({ name, value })),
+          queryString: [],
+          headersSize: -1,
+          bodySize: -1,
+        },
+        response: {
+          status: e.status ?? 0,
+          statusText: e.statusText ?? '',
+          httpVersion: 'HTTP/1.1',
+          cookies: [],
+          headers: Object.entries(e.responseHeaders ?? {}).map(([name, value]) => ({ name, value })),
+          content: {
+            size: e.size ?? -1,
+            mimeType: e.mimeType ?? 'application/octet-stream',
+            text: e.responseBody,
+            encoding: e.bodyEncoding,
+          },
+          redirectURL: '',
+          headersSize: -1,
+          bodySize: e.encodedSize ?? -1,
+        },
+        cache: {},
+        timings: { send: 0, wait: 0, receive: 0 },
+      })),
+    },
+  };
+}

package/src/browser/index.ts

@@ -0,0 +1,22 @@
+export * from './types.js';
+export * from './cdp.js';
+export * from './browser.js';
+export * from './snapshot.js';
+export * from './actions.js';
+export * from './wait.js';
+export * from './network.js';
+export * from './screenshot.js';
+export * from './session.js';
+export * from './tabs.js';
+export * from './dialog.js';
+export * from './console-log.js';
+export * from './storage.js';
+export * from './find.js';
+export * from './pdf.js';
+export * from './emulation.js';
+export * from './batch.js';
+export * from './record.js';
+export * from './trace.js';
+export * from './profiler.js';
+export * from './vitals.js';
+export * from './har.js';

package/src/browser/network.ts

@@ -0,0 +1,244 @@
+import type { CdpClient } from './cdp.js';
+import type { CdpCookie, NetworkRoute } from './types.js';
+
+export async function getCookies(client: CdpClient, sessionId: string): Promise<CdpCookie[]> {
+  const result = await client.send<{ cookies: CdpCookie[] }>('Network.getAllCookies', {}, sessionId);
+  return result.cookies ?? [];
+}
+
+export async function setCookies(client: CdpClient, sessionId: string, cookies: CdpCookie[]): Promise<void> {
+  await client.send('Network.setCookies', { cookies }, sessionId);
+}
+
+export async function clearCookies(client: CdpClient, sessionId: string): Promise<void> {
+  await client.send('Network.clearBrowserCookies', {}, sessionId);
+}
+
+export async function setExtraHeaders(
+  client: CdpClient,
+  sessionId: string,
+  headers: Record<string, string>
+): Promise<void> {
+  await client.send('Network.setExtraHTTPHeaders', { headers }, sessionId);
+}
+
+export async function enableInterception(client: CdpClient, sessionId: string): Promise<void> {
+  await client.send('Fetch.enable', {
+    patterns: [{ requestStage: 'Request' }],
+  }, sessionId);
+}
+
+const _routeListeners = new Map<string, () => void>();
+
+export async function setupRoutes(
+  client: CdpClient,
+  sessionId: string,
+  routes: NetworkRoute[]
+): Promise<void> {
+  // Remove previous route listener for this session before registering a new one
+  const prevOff = _routeListeners.get(sessionId);
+  if (prevOff) { prevOff(); _routeListeners.delete(sessionId); }
+
+  if (routes.length === 0) {
+    await client.send('Fetch.disable', {}, sessionId).catch(() => {});
+    return;
+  }
+
+  // Pre-compile route regexes once — avoids creating new RegExp on every paused request
+  const compiledRoutes = routes.map((r) => ({ route: r, regex: globToRegex(r.pattern) }));
+
+  // Register listener BEFORE Fetch.enable to avoid race where Chrome emits
+  // Fetch.requestPaused before the handler is in place, leaving requests hung
+  const off = client.on('Fetch.requestPaused', async (params, sid) => {
+    if (sid !== sessionId) return;
+
+    const { requestId, request } = params as { requestId: string; request: { url: string } };
+    try {
+      const matchedRoute = compiledRoutes.find((e) => e.regex.test(request.url))?.route;
+
+      if (!matchedRoute) {
+        await client.send('Fetch.continueRequest', { requestId }, sessionId);
+        return;
+      }
+
+      switch (matchedRoute.action) {
+        case 'abort':
+          await client.send('Fetch.failRequest', { requestId, errorReason: 'Failed' }, sessionId);
+          break;
+        case 'fulfill':
+          await client.send('Fetch.fulfillRequest', {
+            requestId,
+            responseCode: matchedRoute.response?.status ?? 200,
+            responseHeaders: Object.entries(matchedRoute.response?.headers ?? {}).map(([name, value]) => ({ name, value })),
+            body: matchedRoute.response?.body ? Buffer.from(matchedRoute.response.body).toString('base64') : '',
+          }, sessionId);
+          break;
+        case 'continue':
+        default:
+          await client.send('Fetch.continueRequest', { requestId }, sessionId);
+          break;
+      }
+    } catch {
+      // Best-effort: resume the request so it doesn't hang in Chrome
+      await client.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => {});
+    }
+  });
+  _routeListeners.set(sessionId, off);
+
+  await client.send('Fetch.enable', {
+    patterns: routes.map((r) => ({ urlPattern: globToFetchPattern(r.pattern), requestStage: 'Request' })),
+  }, sessionId);
+}
+
+type CapturedRequest = {
+  id: string; url: string; method: string; status?: number; mimeType?: string;
+  requestHeaders?: Record<string, string>; responseHeaders?: Record<string, string>;
+  startTime: number; endTime?: number; encodedSize?: number;
+};
+
+const _capturedRequests = new Map<string, Map<string, CapturedRequest>>();
+
+const _captureListeners = new Map<string, Array<() => void>>();
+
+export function startRequestCapture(client: CdpClient, sessionId: string): void {
+  stopRequestCapture(sessionId);
+  _capturedRequests.set(sessionId, new Map<string, CapturedRequest>());
+  client.send('Network.enable', {}, sessionId).catch(() => {});
+
+  // Use indirection so clearCapturedRequests (which replaces the Map) affects live listeners
+  const idx = () => _capturedRequests.get(sessionId)!;
+
+  const offReq = client.on('Network.requestWillBeSent', (params, sid) => {
+    if (sid !== sessionId) return;
+    const p = params as { requestId: string; request: { url: string; method: string; headers: Record<string, string> }; timestamp: number };
+    idx().set(p.requestId, { id: p.requestId, url: p.request.url, method: p.request.method, requestHeaders: p.request.headers, startTime: p.timestamp * 1000 });
+  });
+
+  const offResp = client.on('Network.responseReceived', (params, sid) => {
+    if (sid !== sessionId) return;
+    const p = params as { requestId: string; response: { status: number; mimeType: string; headers: Record<string, string> }; timestamp: number };
+    const entry = idx().get(p.requestId);
+    if (entry) { entry.status = p.response.status; entry.mimeType = p.response.mimeType; entry.responseHeaders = p.response.headers; entry.endTime = p.timestamp * 1000; }
+  });
+
+  const offFinished = client.on('Network.loadingFinished', (params, sid) => {
+    if (sid !== sessionId) return;
+    const p = params as { requestId: string; encodedDataLength: number; timestamp: number };
+    const entry = idx().get(p.requestId);
+    if (entry) { entry.encodedSize = p.encodedDataLength; entry.endTime = p.timestamp * 1000; }
+  });
+
+  const offFailed = client.on('Network.loadingFailed', (params, sid) => {
+    if (sid !== sessionId) return;
+    const p = params as { requestId: string; timestamp: number };
+    const entry = idx().get(p.requestId);
+    if (entry) { entry.endTime = p.timestamp * 1000; }
+  });
+
+  _captureListeners.set(sessionId, [offReq, offResp, offFinished, offFailed]);
+}
+
+export function stopRequestCapture(sessionId: string): void {
+  const offs = _captureListeners.get(sessionId);
+  if (offs) { for (const off of offs) off(); _captureListeners.delete(sessionId); }
+  _capturedRequests.delete(sessionId);
+}
+
+export function getCapturedRequests(sessionId: string): CapturedRequest[] {
+  return [...(_capturedRequests.get(sessionId)?.values() ?? [])];
+}
+
+export function clearCapturedRequests(sessionId: string): void {
+  _capturedRequests.set(sessionId, new Map());
+}
+
+export async function disableInterception(client: CdpClient, sessionId: string): Promise<void> {
+  const prevOff = _routeListeners.get(sessionId);
+  if (prevOff) { prevOff(); _routeListeners.delete(sessionId); }
+  await client.send('Fetch.disable', {}, sessionId);
+}
+
+export function teardownRouteInterception(sessionId: string): void {
+  const prevOff = _routeListeners.get(sessionId);
+  if (prevOff) { prevOff(); _routeListeners.delete(sessionId); }
+}
+
+export async function getLocalStorage(client: CdpClient, sessionId: string): Promise<Record<string, string>> {
+  const result = await client.send<{ result: { value?: string }; exceptionDetails?: { text: string; exception?: { description?: string } } }>('Runtime.evaluate', {
+    expression: 'JSON.stringify(Object.fromEntries(Object.entries(localStorage)))',
+    returnByValue: true,
+  }, sessionId);
+  if (result.exceptionDetails) return {};
+  try {
+    return JSON.parse(result.result?.value ?? '{}');
+  } catch {
+    return {};
+  }
+}
+
+export async function setLocalStorage(
+  client: CdpClient,
+  sessionId: string,
+  data: Record<string, string>
+): Promise<void> {
+  const script = Object.entries(data)
+    .map(([k, v]) => `localStorage.setItem(${JSON.stringify(k)}, ${JSON.stringify(v)})`)
+    .join('; ');
+  if (script) {
+    const result = await client.send<{
+      result: unknown;
+      exceptionDetails?: { text: string; exception?: { description?: string } };
+    }>('Runtime.evaluate', { expression: script, returnByValue: true }, sessionId);
+    if (result.exceptionDetails) {
+      throw new Error(`setLocalStorage failed: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
+    }
+  }
+}
+
+export async function getSessionStorage(client: CdpClient, sessionId: string): Promise<Record<string, string>> {
+  const result = await client.send<{ result: { value?: string }; exceptionDetails?: { text: string; exception?: { description?: string } } }>('Runtime.evaluate', {
+    expression: 'JSON.stringify(Object.fromEntries(Object.entries(sessionStorage)))',
+    returnByValue: true,
+  }, sessionId);
+  if (result.exceptionDetails) return {};
+  try {
+    return JSON.parse(result.result?.value ?? '{}');
+  } catch {
+    return {};
+  }
+}
+
+export async function setSessionStorage(
+  client: CdpClient,
+  sessionId: string,
+  data: Record<string, string>
+): Promise<void> {
+  const script = Object.entries(data)
+    .map(([k, v]) => `sessionStorage.setItem(${JSON.stringify(k)}, ${JSON.stringify(v)})`)
+    .join('; ');
+  if (script) {
+    const result = await client.send<{
+      result: unknown;
+      exceptionDetails?: { text: string; exception?: { description?: string } };
+    }>('Runtime.evaluate', { expression: script, returnByValue: true }, sessionId);
+    if (result.exceptionDetails) {
+      throw new Error(`setSessionStorage failed: ${result.exceptionDetails.exception?.description ?? result.exceptionDetails.text}`);
+    }
+  }
+}
+
+function globToRegex(pattern: string): RegExp {
+  // Chrome's Fetch urlPattern treats '*' as matching everything including '/'
+  // and '?' as any single character — match both behaviors here to avoid divergence
+  const escaped = pattern
+    .replace(/[-[\]{}()+.,\\^$|#\s]/g, '\\$&')
+    .replace(/\*\*/g, '\x00')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\x00/g, '.*')
+    .replace(/\?/g, '[^/]');
+  return new RegExp(`^${escaped}$`);
+}
+
+function globToFetchPattern(pattern: string): string {
+  return pattern.replace(/\*\*/g, '*');
+}