@monoes/monobrowse 1.0.0

package/src/browser/storage.ts

@@ -0,0 +1,54 @@
+import type { CdpClient } from './cdp.js';
+import { evaluateJs } from './actions.js';
+
+export async function getLocalStorageKey(client: CdpClient, sessionId: string, key: string): Promise<string | null> {
+  const result = await evaluateJs(client, sessionId, `localStorage.getItem(${JSON.stringify(key)})`);
+  return result as string | null;
+}
+
+export async function setLocalStorageKey(client: CdpClient, sessionId: string, key: string, value: string): Promise<void> {
+  await evaluateJs(client, sessionId, `localStorage.setItem(${JSON.stringify(key)}, ${JSON.stringify(value)})`);
+}
+
+export async function removeLocalStorageKey(client: CdpClient, sessionId: string, key: string): Promise<void> {
+  await evaluateJs(client, sessionId, `localStorage.removeItem(${JSON.stringify(key)})`);
+}
+
+export async function clearLocalStorage(client: CdpClient, sessionId: string): Promise<void> {
+  await evaluateJs(client, sessionId, 'localStorage.clear()');
+}
+
+export async function getAllLocalStorage(client: CdpClient, sessionId: string): Promise<Record<string, string>> {
+  const result = await evaluateJs(
+    client,
+    sessionId,
+    'JSON.stringify(Object.fromEntries(Object.entries(localStorage)))'
+  );
+  try { return JSON.parse(result as string); } catch { return {}; }
+}
+
+export async function getSessionStorageKey(client: CdpClient, sessionId: string, key: string): Promise<string | null> {
+  const result = await evaluateJs(client, sessionId, `sessionStorage.getItem(${JSON.stringify(key)})`);
+  return result as string | null;
+}
+
+export async function setSessionStorageKey(client: CdpClient, sessionId: string, key: string, value: string): Promise<void> {
+  await evaluateJs(client, sessionId, `sessionStorage.setItem(${JSON.stringify(key)}, ${JSON.stringify(value)})`);
+}
+
+export async function removeSessionStorageKey(client: CdpClient, sessionId: string, key: string): Promise<void> {
+  await evaluateJs(client, sessionId, `sessionStorage.removeItem(${JSON.stringify(key)})`);
+}
+
+export async function clearSessionStorage(client: CdpClient, sessionId: string): Promise<void> {
+  await evaluateJs(client, sessionId, 'sessionStorage.clear()');
+}
+
+export async function getAllSessionStorage(client: CdpClient, sessionId: string): Promise<Record<string, string>> {
+  const result = await evaluateJs(
+    client,
+    sessionId,
+    'JSON.stringify(Object.fromEntries(Object.entries(sessionStorage)))'
+  );
+  try { return JSON.parse(result as string); } catch { return {}; }
+}

package/src/browser/tabs.ts

@@ -0,0 +1,37 @@
+import type { CdpClient } from './cdp.js';
+import type { CdpTarget } from './types.js';
+import { fetchTargets, fetchNewTarget } from './cdp.js';
+
+export async function listTabs(port: number): Promise<CdpTarget[]> {
+  const targets = await fetchTargets(port);
+  return targets.filter((t) => t.type === 'page');
+}
+
+export async function newTab(port: number, url = 'about:blank'): Promise<CdpTarget> {
+  return fetchNewTarget(port, url);
+}
+
+export async function closeTab(client: CdpClient, _sessionId: string, targetId: string): Promise<void> {
+  await client.send('Target.closeTarget', { targetId });
+}
+
+export async function activateTab(client: CdpClient, oldSessionId: string, targetId: string): Promise<string> {
+  if (oldSessionId) {
+    await client.send('Target.detachFromTarget', { sessionId: oldSessionId }).catch(() => {});
+  }
+  await client.send('Target.activateTarget', { targetId });
+  const result = await client.send<{ sessionId: string }>('Target.attachToTarget', { targetId, flatten: true });
+  return result.sessionId;
+}
+
+export async function switchToFrame(
+  _client: CdpClient,
+  _sessionId: string,
+  _frameSelector: string
+): Promise<string | null> {
+  throw new Error(
+    'switchToFrame is not yet implemented. ' +
+    'For same-origin frames, CDP commands already apply to the whole page. ' +
+    'For cross-origin (OOPIF) frames, call Target.attachToTarget with the frame target ID.'
+  );
+}

package/src/browser/trace.ts

@@ -0,0 +1,106 @@
+import type { CdpClient } from './cdp.js';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+
+export interface TraceOptions {
+  path?: string;
+  categories?: string[];
+  screenshots?: boolean;
+}
+
+const DEFAULT_CATEGORIES = [
+  '-*',
+  'devtools.timeline',
+  'v8.execute',
+  'disabled-by-default-devtools.timeline',
+  'disabled-by-default-devtools.timeline.frame',
+  'toplevel',
+  'blink.console',
+  'blink.user_timing',
+  'latencyInfo',
+  'disabled-by-default-devtools.timeline.stack',
+];
+
+const _sessions = new Map<string, { events: unknown[]; offData: () => void }>();
+
+export async function startTrace(
+  client: CdpClient,
+  sessionId: string,
+  options: TraceOptions = {}
+): Promise<void> {
+  if (_sessions.has(sessionId)) {
+    throw new Error('Trace already in progress for this session');
+  }
+
+  const events: unknown[] = [];
+
+  const offData = client.on('Tracing.dataCollected', (params, sid) => {
+    if (sid !== sessionId) return;
+    const value = params.value as unknown[];
+    if (Array.isArray(value)) events.push(...value);
+  });
+
+  _sessions.set(sessionId, { events, offData });
+
+  const cats = [...(options.categories ?? DEFAULT_CATEGORIES)];
+  if (options.screenshots) cats.push('disabled-by-default-devtools.screenshot');
+
+  try {
+    await client.send('Tracing.start', {
+      traceConfig: {
+        includedCategories: cats.filter((c) => !c.startsWith('-')),
+        excludedCategories: cats.filter((c) => c.startsWith('-')).map((c) => c.slice(1)),
+      },
+    }, sessionId);
+  } catch (err) {
+    offData();
+    _sessions.delete(sessionId);
+    throw err;
+  }
+}
+
+export async function stopTrace(
+  client: CdpClient,
+  sessionId: string,
+  outputPath?: string
+): Promise<string> {
+  const state = _sessions.get(sessionId);
+  if (!state) throw new Error('No active trace for this session');
+
+  try {
+    const [completePromise, cancelOnce] = client.onceWithOff('Tracing.tracingComplete', sessionId);
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const timeoutPromise = new Promise<void>((_, reject) => {
+      timeoutHandle = setTimeout(() => {
+        cancelOnce();
+        reject(new Error('Timeout waiting for Tracing.tracingComplete'));
+      }, 30_000);
+    });
+    try {
+      await client.send('Tracing.end', {}, sessionId);
+      await Promise.race([completePromise, timeoutPromise]);
+    } catch (err) {
+      cancelOnce();
+      throw err;
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  } finally {
+    state.offData();
+    _sessions.delete(sessionId);
+  }
+
+  const trace = {
+    traceEvents: state.events,
+    metadata: { 'clock-offset-since-epoch': Date.now() },
+  };
+
+  const path = outputPath ?? join(tmpdir(), `monomind-trace-${Date.now()}.json`);
+  await writeFile(path, JSON.stringify(trace));
+  return path;
+}
+
+export function getTraceStatus(sessionId: string): boolean {
+  return _sessions.has(sessionId);
+}

package/src/browser/types.ts

@@ -0,0 +1,135 @@
+export interface BrowserConfig {
+  port?: number;
+  headless?: boolean;
+  executablePath?: string;
+  userDataDir?: string;
+  args?: string[];
+}
+
+export interface SessionState {
+  targetId: string;
+  sessionId: string;
+  url: string;
+  title: string;
+  cookies: CdpCookie[];
+  localStorage?: Record<string, string>;
+  sessionStorage?: Record<string, string>;
+}
+
+export interface CdpCookie {
+  name: string;
+  value: string;
+  domain?: string;
+  path?: string;
+  expires?: number;
+  httpOnly?: boolean;
+  secure?: boolean;
+  sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+export interface ElementRef {
+  ref: string;
+  role: string;
+  name: string;
+  description?: string;
+  placeholder?: string;
+  value?: string;
+  disabled?: boolean;
+  checked?: boolean;
+  expanded?: boolean;
+  nodeId: number;
+  backendDOMNodeId?: number;
+  objectId?: string;
+}
+
+export interface SnapshotOptions {
+  interactiveOnly?: boolean;
+  compact?: boolean;
+  maxDepth?: number;
+  selector?: string;
+}
+
+export interface SnapshotResult {
+  text: string;
+  refs: Map<string, ElementRef>;
+  url: string;
+  title: string;
+}
+
+export interface ClickOptions {
+  button?: 'left' | 'right' | 'middle';
+  clickCount?: number;
+  modifiers?: number;
+}
+
+export interface WaitOptions {
+  timeout?: number;
+  url?: string;
+  text?: string;
+  selector?: string;
+  load?: 'load' | 'networkidle' | 'domcontentloaded';
+}
+
+export interface NetworkRoute {
+  pattern: string;
+  action: 'abort' | 'fulfill' | 'continue';
+  response?: {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: string;
+  };
+}
+
+export interface ViewportSize {
+  width: number;
+  height: number;
+}
+
+export interface CdpTarget {
+  id: string;
+  type: string;
+  title: string;
+  url: string;
+  webSocketDebuggerUrl?: string;
+}
+
+export interface CdpCommand {
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+  sessionId?: string;
+}
+
+export interface CdpResponse {
+  id?: number;
+  method?: string;
+  params?: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  error?: { code: number; message: string };
+  sessionId?: string;
+}
+
+export interface BrowserSession {
+  targetId: string;
+  sessionId: string;
+  refs: Map<string, ElementRef>;
+  routes: NetworkRoute[];
+  viewport: ViewportSize;
+}
+
+export const INTERACTIVE_ROLES = new Set([
+  'button', 'link', 'textbox', 'combobox', 'listbox', 'checkbox', 'radio',
+  'slider', 'spinbutton', 'searchbox', 'option', 'menuitem', 'tab', 'switch',
+  'treeitem', 'menuitemcheckbox', 'menuitemradio', 'row', 'gridcell', 'cell',
+  'columnheader', 'rowheader', 'scrollbar',
+]);
+
+export const CHROME_EXECUTABLES = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome',
+  '/usr/bin/chromium-browser',
+  '/usr/bin/chromium',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+];

package/src/browser/vitals.ts

@@ -0,0 +1,122 @@
+import type { CdpClient } from './cdp.js';
+import { evaluateJs } from './actions.js';
+
+export interface WebVitals {
+  lcp?: number;
+  fcp?: number;
+  cls?: number;
+  ttfb?: number;
+  inp?: number;
+  domInteractive?: number;
+  domContentLoaded?: number;
+  loadTime?: number;
+  resources?: number;
+}
+
+export async function collectVitals(
+  client: CdpClient,
+  sessionId: string,
+  waitMs = 2000
+): Promise<WebVitals> {
+  // Inject PerformanceObserver collectors and wait for data
+  const script = `
+    new Promise((resolve) => {
+      const vitals = {};
+
+      // Navigation timing
+      const nav = performance.getEntriesByType('navigation')[0];
+      if (nav) {
+        vitals.ttfb = nav.responseStart - nav.requestStart;
+        vitals.domInteractive = nav.domInteractive;
+        vitals.domContentLoaded = nav.domContentLoadedEventEnd;
+        vitals.loadTime = nav.loadEventEnd;
+        vitals.resources = performance.getEntriesByType('resource').length;
+      }
+
+      // FCP via paint entries
+      const paintEntries = performance.getEntriesByType('paint');
+      const fcp = paintEntries.find(e => e.name === 'first-contentful-paint');
+      if (fcp) vitals.fcp = fcp.startTime;
+
+      // LCP
+      let lcpValue = 0;
+      let lcpObs;
+      try {
+        lcpObs = new PerformanceObserver((list) => {
+          const entries = list.getEntries();
+          if (entries.length > 0) {
+            lcpValue = entries[entries.length - 1].startTime;
+            vitals.lcp = lcpValue;
+          }
+        });
+        lcpObs.observe({ type: 'largest-contentful-paint', buffered: true });
+      } catch(e) {}
+
+      // CLS
+      let clsValue = 0;
+      let clsObs;
+      try {
+        clsObs = new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            if (!entry.hadRecentInput) {
+              clsValue += entry.value;
+            }
+          }
+          vitals.cls = clsValue;
+        });
+        clsObs.observe({ type: 'layout-shift', buffered: true });
+      } catch(e) {}
+
+      // INP
+      let inpValue = 0;
+      let inpObs;
+      try {
+        inpObs = new PerformanceObserver((list) => {
+          for (const entry of list.getEntries()) {
+            if (entry.duration > inpValue) {
+              inpValue = entry.duration;
+              vitals.inp = inpValue;
+            }
+          }
+        });
+        inpObs.observe({ type: 'event', buffered: true, durationThreshold: 40 });
+      } catch(e) {}
+
+      setTimeout(() => {
+        try { lcpObs?.disconnect(); } catch(e) {}
+        try { clsObs?.disconnect(); } catch(e) {}
+        try { inpObs?.disconnect(); } catch(e) {}
+        resolve(vitals);
+      }, ${waitMs});
+    })
+  `;
+
+  const result = await evaluateJs(client, sessionId, script);
+  return (result ?? {}) as WebVitals;
+}
+
+export function formatVitals(vitals: WebVitals): string {
+  const lines: string[] = [];
+  const ms = (v?: number) => v !== undefined ? `${Math.round(v)}ms` : 'n/a';
+  const score = (metric: string, v?: number): string => {
+    if (v === undefined) return '';
+    if (metric === 'lcp') return v < 2500 ? ' ✓ good' : v < 4000 ? ' ~ needs improvement' : ' ✗ poor';
+    if (metric === 'fcp') return v < 1800 ? ' ✓ good' : v < 3000 ? ' ~ needs improvement' : ' ✗ poor';
+    if (metric === 'cls') return v < 0.1 ? ' ✓ good' : v < 0.25 ? ' ~ needs improvement' : ' ✗ poor';
+    if (metric === 'inp') return v < 200 ? ' ✓ good' : v < 500 ? ' ~ needs improvement' : ' ✗ poor';
+    if (metric === 'ttfb') return v < 800 ? ' ✓ good' : v < 1800 ? ' ~ needs improvement' : ' ✗ poor';
+    return '';
+  };
+
+  if (vitals.lcp !== undefined) lines.push(`  LCP  (Largest Contentful Paint):  ${ms(vitals.lcp)}${score('lcp', vitals.lcp)}`);
+  if (vitals.fcp !== undefined) lines.push(`  FCP  (First Contentful Paint):     ${ms(vitals.fcp)}${score('fcp', vitals.fcp)}`);
+  if (vitals.cls !== undefined) lines.push(`  CLS  (Cumulative Layout Shift):    ${vitals.cls?.toFixed(4)}${score('cls', vitals.cls)}`);
+  if (vitals.inp !== undefined) lines.push(`  INP  (Interaction to Next Paint):  ${ms(vitals.inp)}${score('inp', vitals.inp)}`);
+  if (vitals.ttfb !== undefined) lines.push(`  TTFB (Time to First Byte):         ${ms(vitals.ttfb)}${score('ttfb', vitals.ttfb)}`);
+  if (vitals.domInteractive !== undefined) lines.push(`  DOM Interactive:                   ${ms(vitals.domInteractive)}`);
+  if (vitals.domContentLoaded !== undefined) lines.push(`  DOMContentLoaded:                  ${ms(vitals.domContentLoaded)}`);
+  if (vitals.loadTime !== undefined) lines.push(`  Load:                              ${ms(vitals.loadTime)}`);
+  if (vitals.resources !== undefined) lines.push(`  Resources loaded:                  ${vitals.resources}`);
+
+  return lines.join('\n');
+}

package/src/browser/wait.ts

@@ -0,0 +1,178 @@
+import type { CdpClient } from './cdp.js';
+import type { WaitOptions } from './types.js';
+import { getCurrentUrl } from './browser.js';
+import { evaluateJs } from './actions.js';
+
+const DEFAULT_TIMEOUT = 30_000;
+const POLL_INTERVAL = 250;
+
+export async function waitFor(
+  client: CdpClient,
+  sessionId: string,
+  options: WaitOptions
+): Promise<void> {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  const deadline = Date.now() + timeout;
+
+  if (options.load) {
+    await waitForLoad(client, sessionId, options.load, timeout);
+    return;
+  }
+
+  if (options.url) {
+    await waitForUrl(client, sessionId, options.url, deadline);
+    return;
+  }
+
+  if (options.text) {
+    await waitForText(client, sessionId, options.text, deadline);
+    return;
+  }
+
+  if (options.selector) {
+    await waitForSelector(client, sessionId, options.selector, deadline);
+    return;
+  }
+
+  // Just wait for timeout
+  await sleep(timeout);
+}
+
+async function waitForLoad(
+  client: CdpClient,
+  sessionId: string,
+  condition: string,
+  timeout: number
+): Promise<void> {
+  if (condition === 'networkidle') {
+    await waitForNetworkIdle(client, sessionId, 500, timeout);
+    return;
+  }
+
+  const event = condition === 'load' ? 'Page.loadEventFired' : 'Page.domContentEventFired';
+  const [eventPromise, cancelOnce] = client.onceWithOff(event, sessionId);
+  let timedOut = false;
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  const timeoutPromise = new Promise<void>((resolve) => {
+    timeoutHandle = setTimeout(() => { timedOut = true; resolve(); }, timeout);
+  });
+  try {
+    await Promise.race([eventPromise, timeoutPromise]);
+    if (timedOut) throw new Error(`Timeout waiting for ${condition}`);
+  } finally {
+    cancelOnce();
+    clearTimeout(timeoutHandle);
+  }
+}
+
+async function waitForNetworkIdle(
+  client: CdpClient,
+  sessionId: string,
+  idleMs: number,
+  timeout: number
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let pending = 0;
+    const inflight = new Set<string>();
+    let idleTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const cleanup = () => {
+      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+      clearTimeout(killTimer);
+      offReq(); offResp(); offFail(); offCache();
+    };
+
+    const killTimer = setTimeout(() => {
+      cleanup();
+      reject(new Error('Timeout waiting for networkidle'));
+    }, timeout);
+
+    const settle = () => { cleanup(); resolve(); };
+
+    const check = () => {
+      if (pending === 0) {
+        if (idleTimer) clearTimeout(idleTimer);
+        idleTimer = setTimeout(settle, idleMs);
+      } else {
+        if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+      }
+    };
+
+    const offReq = client.on('Network.requestWillBeSent', (params, sid) => {
+      if (sid !== sessionId) return;
+      const id = params.requestId as string;
+      if (!inflight.has(id)) { inflight.add(id); pending++; check(); }
+    });
+
+    const decrement = (params: Record<string, unknown>, sid?: string) => {
+      if (sid !== sessionId) return;
+      const id = params.requestId as string;
+      if (inflight.delete(id)) { pending = Math.max(0, pending - 1); check(); }
+    };
+
+    const offResp  = client.on('Network.loadingFinished',        decrement);
+    const offFail  = client.on('Network.loadingFailed',          decrement);
+    const offCache = client.on('Network.requestServedFromCache', decrement);
+
+    check();
+  });
+}
+
+async function waitForUrl(
+  client: CdpClient,
+  sessionId: string,
+  pattern: string,
+  deadline: number
+): Promise<void> {
+  const regex = globToRegex(pattern);
+  while (Date.now() < deadline) {
+    const url = await getCurrentUrl(client, sessionId);
+    if (regex.test(url)) return;
+    await sleep(POLL_INTERVAL);
+  }
+  throw new Error(`Timeout waiting for URL matching: ${pattern}`);
+}
+
+async function waitForText(
+  client: CdpClient,
+  sessionId: string,
+  text: string,
+  deadline: number
+): Promise<void> {
+  while (Date.now() < deadline) {
+    const bodyText = await evaluateJs(client, sessionId, 'document.body?.innerText ?? ""') as string;
+    if (bodyText.includes(text)) return;
+    await sleep(POLL_INTERVAL);
+  }
+  throw new Error(`Timeout waiting for text: ${text}`);
+}
+
+async function waitForSelector(
+  client: CdpClient,
+  sessionId: string,
+  selector: string,
+  deadline: number
+): Promise<void> {
+  while (Date.now() < deadline) {
+    const found = await evaluateJs(
+      client,
+      sessionId,
+      `!!document.querySelector(${JSON.stringify(selector)})`
+    ) as boolean;
+    if (found) return;
+    await sleep(POLL_INTERVAL);
+  }
+  throw new Error(`Timeout waiting for selector: ${selector}`);
+}
+
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[-[\]{}()+?.,\\^$|#\s]/g, '\\$&')
+    .replace(/\*\*/g, '.*')
+    .replace(/\*/g, '[^/]*');
+  return new RegExp(`^${escaped}$`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}