chromex-mcp 1.0.0

package/plugins/chromex/skills/chromex/scripts/lib/commands/har.mjs

@@ -0,0 +1,101 @@
+// HAR (HTTP Archive) recording via Network domain
+
+import { writeFileSync } from 'fs';
+
+let recording = false;
+const entries = [];
+const requestMap = new Map();
+let cleanupFns = [];
+
+export async function harStr(cdp, sid, action, filePath) {
+  if (!action) throw new Error('Usage: har <target> start | stop [file]');
+
+  switch (action) {
+    case 'start': {
+      if (recording) return 'HAR recording already active.';
+      entries.length = 0;
+      requestMap.clear();
+
+      await cdp.send('Network.enable', {}, sid);
+      recording = true;
+
+      const off1 = cdp.onEvent('Network.requestWillBeSent', (params) => {
+        requestMap.set(params.requestId, {
+          requestId: params.requestId,
+          url: params.request.url,
+          method: params.request.method,
+          headers: params.request.headers,
+          postData: params.request.postData,
+          startTime: params.timestamp,
+          wallTime: params.wallTime,
+        });
+      });
+
+      const off2 = cdp.onEvent('Network.responseReceived', (params) => {
+        const req = requestMap.get(params.requestId);
+        if (req) {
+          req.status = params.response.status;
+          req.statusText = params.response.statusText;
+          req.responseHeaders = params.response.headers;
+          req.mimeType = params.response.mimeType;
+          req.protocol = params.response.protocol;
+        }
+      });
+
+      const off3 = cdp.onEvent('Network.loadingFinished', (params) => {
+        const req = requestMap.get(params.requestId);
+        if (req) {
+          req.endTime = params.timestamp;
+          req.encodedDataLength = params.encodedDataLength;
+          entries.push(req);
+          requestMap.delete(params.requestId);
+        }
+      });
+
+      cleanupFns = [off1, off2, off3];
+      return `HAR recording started. Use "har <target> stop [file]" to save.`;
+    }
+
+    case 'stop': {
+      if (!recording) return 'No HAR recording active.';
+      recording = false;
+      cleanupFns.forEach(fn => fn());
+      cleanupFns = [];
+
+      const har = {
+        log: {
+          version: '1.2',
+          creator: { name: 'chromex', version: '1.0.0' },
+          entries: entries.map(e => ({
+            startedDateTime: e.wallTime ? new Date(e.wallTime * 1000).toISOString() : new Date().toISOString(),
+            time: e.endTime && e.startTime ? Math.round((e.endTime - e.startTime) * 1000) : 0,
+            request: {
+              method: e.method,
+              url: e.url,
+              headers: Object.entries(e.headers || {}).map(([n, v]) => ({ name: n, value: v })),
+              postData: e.postData ? { mimeType: 'application/x-www-form-urlencoded', text: e.postData } : undefined,
+            },
+            response: {
+              status: e.status || 0,
+              statusText: e.statusText || '',
+              headers: Object.entries(e.responseHeaders || {}).map(([n, v]) => ({ name: n, value: v })),
+              content: { size: e.encodedDataLength || 0, mimeType: e.mimeType || '' },
+            },
+            cache: {},
+            timings: {
+              send: 0, wait: 0,
+              receive: e.endTime && e.startTime ? Math.round((e.endTime - e.startTime) * 1000) : 0,
+            },
+          })),
+        },
+      };
+
+      const out = filePath || '/tmp/chromex.har';
+      writeFileSync(out, JSON.stringify(har, null, 2));
+      return `HAR saved to ${out} (${entries.length} entries).`;
+    }
+
+    default:
+      throw new Error('Usage: har <target> start | stop [file]');
+  }
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/heap.mjs

@@ -0,0 +1,24 @@
+// Heap snapshot via HeapProfiler domain
+
+import { writeFileSync } from 'fs';
+
+export async function heapStr(cdp, sid, action, filePath) {
+  if (!action) throw new Error('Usage: heap <target> snapshot [file]');
+
+  if (action === 'snapshot') {
+    const chunks = [];
+    const off = cdp.onEvent('HeapProfiler.addHeapSnapshotChunk', (params) => {
+      chunks.push(params.chunk);
+    });
+
+    await cdp.send('HeapProfiler.takeHeapSnapshot', { reportProgress: false }, sid);
+    off();
+
+    const out = filePath || '/tmp/chromex-heap.heapsnapshot';
+    writeFileSync(out, chunks.join(''));
+    const sizeMB = (Buffer.byteLength(chunks.join('')) / (1024 * 1024)).toFixed(1);
+    return `Heap snapshot saved to ${out} (${sizeMB}MB). Open in Chrome DevTools > Memory tab.`;
+  }
+
+  throw new Error('Usage: heap <target> snapshot [file]');
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/highlight.mjs

@@ -0,0 +1,36 @@
+// Element highlight overlay via Overlay domain
+
+export async function highlightStr(cdp, sid, selectorOrAction) {
+  if (!selectorOrAction) throw new Error('Usage: highlight <target> <selector> | clear');
+
+  if (selectorOrAction === 'clear') {
+    await cdp.send('Overlay.hideHighlight', {}, sid);
+    return 'Highlight cleared.';
+  }
+
+  // Encontrar o nodeId do elemento
+  await cdp.send('DOM.enable', {}, sid);
+  await cdp.send('Overlay.enable', {}, sid);
+
+  const { root } = await cdp.send('DOM.getDocument', {}, sid);
+  const { nodeId } = await cdp.send('DOM.querySelector', {
+    nodeId: root.nodeId,
+    selector: selectorOrAction,
+  }, sid);
+
+  if (!nodeId) throw new Error(`Element not found: ${selectorOrAction}`);
+
+  await cdp.send('Overlay.highlightNode', {
+    highlightConfig: {
+      contentColor: { r: 111, g: 168, b: 220, a: 0.66 },
+      paddingColor: { r: 147, g: 196, b: 125, a: 0.55 },
+      borderColor: { r: 255, g: 229, b: 153, a: 0.66 },
+      marginColor: { r: 246, g: 178, b: 107, a: 0.66 },
+      showInfo: true,
+      showStyles: true,
+    },
+    nodeId,
+  }, sid);
+
+  return `Highlighting "${selectorOrAction}". Use "highlight <target> clear" to remove.`;
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/html.mjs

@@ -0,0 +1,10 @@
+// HTML extraction
+
+import { evalStr } from './evaluate.mjs';
+
+export async function htmlStr(cdp, sid, selector) {
+  const expr = selector
+    ? `document.querySelector(${JSON.stringify(selector)})?.outerHTML || 'Element not found'`
+    : `document.documentElement.outerHTML`;
+  return evalStr(cdp, sid, expr);
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/inject.mjs

@@ -0,0 +1,39 @@
+// Script injection via Page domain (runs before page scripts on every navigation)
+
+import { readFileSync, existsSync } from 'fs';
+
+// Mantido em memória no daemon via closure no handleCommand
+const injectedScripts = new Map();
+
+export async function injectStr(cdp, sid, action, arg) {
+  if (!action) throw new Error('Usage: inject <target> <script> | --file <path> | --remove <id> | --list');
+
+  if (action === '--list') {
+    if (injectedScripts.size === 0) return 'No injected scripts.';
+    return Array.from(injectedScripts.entries())
+      .map(([id, snippet]) => `${id}  ${snippet}`)
+      .join('\n');
+  }
+
+  if (action === '--remove') {
+    if (!arg) throw new Error('Script identifier required');
+    await cdp.send('Page.removeScriptToEvaluateOnNewDocument', { identifier: arg }, sid);
+    injectedScripts.delete(arg);
+    return `Removed injected script ${arg}.`;
+  }
+
+  let source;
+  if (action === '--file') {
+    if (!arg) throw new Error('File path required');
+    if (!existsSync(arg)) throw new Error(`File not found: ${arg}`);
+    source = readFileSync(arg, 'utf8');
+  } else {
+    // action é o próprio script (pode ter arg como continuação)
+    source = arg ? `${action} ${arg}` : action;
+  }
+
+  await cdp.send('Page.enable', {}, sid);
+  const { identifier } = await cdp.send('Page.addScriptToEvaluateOnNewDocument', { source }, sid);
+  injectedScripts.set(identifier, source.substring(0, 60) + (source.length > 60 ? '...' : ''));
+  return `Script injected (id: ${identifier}). Runs on every new document load.`;
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/interact.mjs

@@ -0,0 +1,88 @@
+// Interação: click, clickxy, type, loadall, waitfor
+
+import { sleep } from '../utils.mjs';
+import { evalStr } from './evaluate.mjs';
+
+export async function clickStr(cdp, sid, selector) {
+  if (!selector) throw new Error('CSS selector required');
+  const expr = `
+    (function() {
+      const el = document.querySelector(${JSON.stringify(selector)});
+      if (!el) return { ok: false, error: 'Element not found: ' + ${JSON.stringify(selector)} };
+      el.scrollIntoView({ block: 'center' });
+      el.click();
+      return { ok: true, tag: el.tagName, text: el.textContent.trim().substring(0, 80) };
+    })()
+  `;
+  const result = await evalStr(cdp, sid, expr);
+  const r = JSON.parse(result);
+  if (!r.ok) throw new Error(r.error);
+  return `Clicked <${r.tag}> "${r.text}"`;
+}
+
+export async function clickXyStr(cdp, sid, x, y) {
+  const cx = parseFloat(x);
+  const cy = parseFloat(y);
+  if (isNaN(cx) || isNaN(cy)) throw new Error('x and y must be numbers (CSS pixels)');
+  const base = { x: cx, y: cy, button: 'left', clickCount: 1, modifiers: 0 };
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseMoved' }, sid);
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mousePressed' }, sid);
+  await sleep(50);
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseReleased' }, sid);
+  return `Clicked at CSS (${cx}, ${cy})`;
+}
+
+export async function typeStr(cdp, sid, text) {
+  if (text == null || text === '') throw new Error('text required');
+  await cdp.send('Input.insertText', { text }, sid);
+  return `Typed ${text.length} characters`;
+}
+
+export async function loadAllStr(cdp, sid, selector, intervalMs = 1500) {
+  if (!selector) throw new Error('CSS selector required');
+  let clicks = 0;
+  const deadline = Date.now() + 5 * 60 * 1000;
+  while (Date.now() < deadline) {
+    const exists = await evalStr(cdp, sid,
+      `!!document.querySelector(${JSON.stringify(selector)})`
+    );
+    if (exists !== 'true') break;
+    const clickExpr = `
+      (function() {
+        const el = document.querySelector(${JSON.stringify(selector)});
+        if (!el) return false;
+        el.scrollIntoView({ block: 'center' });
+        el.click();
+        return true;
+      })()
+    `;
+    const clicked = await evalStr(cdp, sid, clickExpr);
+    if (clicked !== 'true') break;
+    clicks++;
+    await sleep(intervalMs);
+  }
+  return `Clicked "${selector}" ${clicks} time(s) until it disappeared`;
+}
+
+export async function waitForStr(cdp, sid, selector, timeoutMs, config) {
+  if (!selector) throw new Error('CSS selector required');
+  const timeout = timeoutMs || config?.commandTimeout || 15000;
+  const deadline = Date.now() + timeout;
+  while (Date.now() < deadline) {
+    const exists = await evalStr(cdp, sid,
+      `!!document.querySelector(${JSON.stringify(selector)})`
+    );
+    if (exists === 'true') {
+      const info = await evalStr(cdp, sid, `
+        (function() {
+          const el = document.querySelector(${JSON.stringify(selector)});
+          return { tag: el.tagName, text: el.textContent.trim().substring(0, 80) };
+        })()
+      `);
+      const r = JSON.parse(info);
+      return `Found <${r.tag}> "${r.text}" (waited ${Date.now() - deadline + timeout}ms)`;
+    }
+    await sleep(200);
+  }
+  throw new Error(`Timeout (${timeout}ms) waiting for selector: ${selector}`);
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/intercept.mjs

@@ -0,0 +1,99 @@
+// Network interception -- mock, block, or modify requests via Fetch domain
+
+const rules = [];
+let fetchEnabled = false;
+let handlerRegistered = false;
+
+export async function interceptStr(cdp, sid, action, pattern, body) {
+  if (!action) throw new Error('Usage: intercept <target> on [pattern] | block <pattern> | mock <url> <json> | off | rules');
+
+  switch (action) {
+    case 'on': {
+      const patterns = pattern
+        ? [{ urlPattern: pattern, requestStage: 'Request' }]
+        : [{ urlPattern: '*', requestStage: 'Request' }];
+      await cdp.send('Fetch.enable', { patterns }, sid);
+      fetchEnabled = true;
+      if (!handlerRegistered) {
+        registerHandler(cdp, sid);
+        handlerRegistered = true;
+      }
+      return `Interception enabled${pattern ? ` for ${pattern}` : ' for all requests'}.`;
+    }
+
+    case 'block': {
+      if (!pattern) throw new Error('URL pattern required');
+      rules.push({ type: 'block', pattern });
+      if (!fetchEnabled) {
+        await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, sid);
+        fetchEnabled = true;
+        if (!handlerRegistered) { registerHandler(cdp, sid); handlerRegistered = true; }
+      }
+      return `Blocking requests matching: ${pattern} (${rules.length} rule(s) total)`;
+    }
+
+    case 'mock': {
+      if (!pattern) throw new Error('URL pattern required');
+      if (!body) throw new Error('Response body (JSON) required');
+      rules.push({ type: 'mock', pattern, body });
+      if (!fetchEnabled) {
+        await cdp.send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] }, sid);
+        fetchEnabled = true;
+        if (!handlerRegistered) { registerHandler(cdp, sid); handlerRegistered = true; }
+      }
+      return `Mocking ${pattern} with custom response (${rules.length} rule(s) total)`;
+    }
+
+    case 'off': {
+      await cdp.send('Fetch.disable', {}, sid);
+      fetchEnabled = false;
+      rules.length = 0;
+      return 'Interception disabled. All rules cleared.';
+    }
+
+    case 'rules': {
+      if (rules.length === 0) return 'No interception rules.';
+      return rules.map((r, i) => `${i + 1}. ${r.type.toUpperCase()} ${r.pattern}${r.body ? ' -> ' + r.body.substring(0, 50) : ''}`).join('\n');
+    }
+
+    default:
+      throw new Error('Usage: intercept <target> on [pattern] | block <pattern> | mock <url> <json> | off | rules');
+  }
+}
+
+function registerHandler(cdp, sid) {
+  cdp.onEvent('Fetch.requestPaused', async (params) => {
+    const { requestId, request } = params;
+    const url = request.url;
+
+    for (const rule of rules) {
+      if (urlMatches(url, rule.pattern)) {
+        if (rule.type === 'block') {
+          try { await cdp.send('Fetch.failRequest', { requestId, errorReason: 'BlockedByClient' }, sid); } catch {}
+          return;
+        }
+        if (rule.type === 'mock') {
+          try {
+            await cdp.send('Fetch.fulfillRequest', {
+              requestId,
+              responseCode: 200,
+              responseHeaders: [{ name: 'Content-Type', value: 'application/json' }],
+              body: Buffer.from(rule.body).toString('base64'),
+            }, sid);
+          } catch {}
+          return;
+        }
+      }
+    }
+
+    // Sem regra: continuar normalmente
+    try { await cdp.send('Fetch.continueRequest', { requestId }, sid); } catch {}
+  });
+}
+
+function urlMatches(url, pattern) {
+  if (pattern === '*') return true;
+  // Converter glob simples para regex: * -> .*, ? -> .
+  const regex = new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i');
+  return regex.test(url);
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/navigate.mjs

@@ -0,0 +1,45 @@
+// Navegação + wait for document ready
+
+import { sleep } from '../utils.mjs';
+import { checkDomain } from '../security.mjs';
+import { evalStr } from './evaluate.mjs';
+
+export async function waitForDocumentReady(cdp, sid, timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs;
+  let lastState = '';
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const state = await evalStr(cdp, sid, 'document.readyState');
+      lastState = state;
+      if (state === 'complete') return;
+    } catch (e) {
+      lastError = e;
+    }
+    await sleep(200);
+  }
+
+  if (lastState) throw new Error(`Timed out waiting for navigation (last readyState: ${lastState})`);
+  if (lastError) throw new Error(`Timed out waiting for navigation (${lastError.message})`);
+  throw new Error('Timed out waiting for navigation');
+}
+
+export async function navStr(cdp, sid, url, config) {
+  const domainError = checkDomain(url, config);
+  if (domainError) throw new Error(domainError);
+
+  await cdp.send('Page.enable', {}, sid);
+  const loadEvent = cdp.waitForEvent('Page.loadEventFired', config.navigationTimeout);
+  const result = await cdp.send('Page.navigate', { url }, sid);
+  if (result.errorText) {
+    loadEvent.cancel();
+    throw new Error(result.errorText);
+  }
+  if (result.loaderId) {
+    await loadEvent.promise;
+  } else {
+    loadEvent.cancel();
+  }
+  await waitForDocumentReady(cdp, sid, 5000);
+  return `Navigated to ${url}`;
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/network.mjs

@@ -0,0 +1,13 @@
+// Resource timing entries
+
+import { evalStr } from './evaluate.mjs';
+
+export async function netStr(cdp, sid) {
+  const raw = await evalStr(cdp, sid, `JSON.stringify(performance.getEntriesByType('resource').map(e => ({
+    name: e.name.substring(0, 120), type: e.initiatorType,
+    duration: Math.round(e.duration), size: e.transferSize
+  })))`);
+  return JSON.parse(raw).map(e =>
+    `${String(e.duration).padStart(5)}ms  ${String(e.size || '?').padStart(8)}B  ${e.type.padEnd(8)}  ${e.name}`
+  ).join('\n');
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/pdf.mjs

@@ -0,0 +1,16 @@
+// Gerar PDF da página via CDP
+
+import { writeFileSync } from 'fs';
+
+export async function pdfStr(cdp, sid, filePath) {
+  const out = filePath || '/tmp/page.pdf';
+
+  const { data } = await cdp.send('Page.printToPDF', {
+    landscape: false,
+    printBackground: true,
+    preferCSSPageSize: true,
+  }, sid);
+
+  writeFileSync(out, Buffer.from(data, 'base64'));
+  return `PDF saved to ${out}`;
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/perf.mjs

@@ -0,0 +1,98 @@
+// Core Web Vitals + performance metrics
+
+import { evalStr } from './evaluate.mjs';
+
+export async function perfStr(cdp, sid) {
+  // Métricas do CDP
+  await cdp.send('Performance.enable', {}, sid);
+  const { metrics } = await cdp.send('Performance.getMetrics', {}, sid);
+  await cdp.send('Performance.disable', {}, sid);
+
+  // Core Web Vitals via PerformanceObserver
+  const vitals = await evalStr(cdp, sid, `
+    (function() {
+      const result = {};
+      const nav = performance.getEntriesByType('navigation')[0];
+      if (nav) {
+        result.ttfb = Math.round(nav.responseStart - nav.requestStart);
+        result.domContentLoaded = Math.round(nav.domContentLoadedEventEnd - nav.fetchStart);
+        result.load = Math.round(nav.loadEventEnd - nav.fetchStart);
+        result.domInteractive = Math.round(nav.domInteractive - nav.fetchStart);
+      }
+
+      // LCP
+      const lcpEntries = performance.getEntriesByType('largest-contentful-paint');
+      if (lcpEntries.length > 0) {
+        const lcp = lcpEntries[lcpEntries.length - 1];
+        result.lcp = Math.round(lcp.startTime);
+        result.lcpElement = lcp.element?.tagName || 'unknown';
+      }
+
+      // CLS
+      let cls = 0;
+      for (const entry of performance.getEntriesByType('layout-shift')) {
+        if (!entry.hadRecentInput) cls += entry.value;
+      }
+      result.cls = Math.round(cls * 1000) / 1000;
+
+      // FCP
+      const fcpEntries = performance.getEntriesByType('paint');
+      const fcp = fcpEntries.find(e => e.name === 'first-contentful-paint');
+      if (fcp) result.fcp = Math.round(fcp.startTime);
+
+      // Contadores
+      result.resources = performance.getEntriesByType('resource').length;
+      result.transferSize = performance.getEntriesByType('resource')
+        .reduce((sum, r) => sum + (r.transferSize || 0), 0);
+
+      return JSON.stringify(result);
+    })()
+  `);
+
+  const v = JSON.parse(vitals);
+  const cdpMetrics = {};
+  for (const m of metrics) cdpMetrics[m.name] = m.value;
+
+  const lines = ['## Core Web Vitals'];
+
+  if (v.lcp != null) lines.push(`LCP:  ${v.lcp}ms  (${v.lcpElement})${v.lcp <= 2500 ? ' [GOOD]' : v.lcp <= 4000 ? ' [NEEDS IMPROVEMENT]' : ' [POOR]'}`);
+  if (v.fcp != null) lines.push(`FCP:  ${v.fcp}ms${v.fcp <= 1800 ? ' [GOOD]' : v.fcp <= 3000 ? ' [NEEDS IMPROVEMENT]' : ' [POOR]'}`);
+  if (v.cls != null) lines.push(`CLS:  ${v.cls}${v.cls <= 0.1 ? ' [GOOD]' : v.cls <= 0.25 ? ' [NEEDS IMPROVEMENT]' : ' [POOR]'}`);
+  if (v.ttfb != null) lines.push(`TTFB: ${v.ttfb}ms${v.ttfb <= 800 ? ' [GOOD]' : v.ttfb <= 1800 ? ' [NEEDS IMPROVEMENT]' : ' [POOR]'}`);
+
+  lines.push('');
+  lines.push('## Navigation Timing');
+  if (v.domInteractive != null) lines.push(`DOM Interactive:       ${v.domInteractive}ms`);
+  if (v.domContentLoaded != null) lines.push(`DOMContentLoaded:      ${v.domContentLoaded}ms`);
+  if (v.load != null) lines.push(`Load:                  ${v.load}ms`);
+
+  lines.push('');
+  lines.push('## Resources');
+  lines.push(`Total requests:  ${v.resources}`);
+  lines.push(`Transfer size:   ${formatBytes(v.transferSize)}`);
+
+  if (cdpMetrics.JSHeapUsedSize) {
+    lines.push('');
+    lines.push('## Memory');
+    lines.push(`JS Heap Used:  ${formatBytes(cdpMetrics.JSHeapUsedSize)}`);
+    lines.push(`JS Heap Total: ${formatBytes(cdpMetrics.JSHeapTotalSize)}`);
+  }
+
+  if (cdpMetrics.Nodes) {
+    lines.push('');
+    lines.push('## DOM');
+    lines.push(`DOM Nodes:     ${cdpMetrics.Nodes}`);
+    lines.push(`Documents:     ${cdpMetrics.Documents}`);
+    lines.push(`Frames:        ${cdpMetrics.Frames}`);
+    lines.push(`Listeners:     ${cdpMetrics.JSEventListeners}`);
+  }
+
+  return lines.join('\n');
+}
+
+function formatBytes(bytes) {
+  if (bytes == null) return '?';
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/plugins/chromex/skills/chromex/scripts/lib/commands/refs.mjs

@@ -0,0 +1,67 @@
+// Ref-based element resolution: @e1, @e2... -> backendNodeId -> coordinates/actions
+
+import { sleep } from '../utils.mjs';
+
+// Resolve a ref (@eN) to center coordinates using DOM.getBoxModel
+export async function resolveRefToCoords(cdp, sid, refMap, refNum) {
+  const ref = refMap.get(refNum);
+  if (!ref) throw new Error(`Ref @e${refNum} not found. Run "snap --refs" first to assign refs.`);
+  if (!ref.backendNodeId) throw new Error(`Ref @e${refNum} has no DOM node (role: ${ref.role}).`);
+
+  await cdp.send('DOM.enable', {}, sid);
+  const { model } = await cdp.send('DOM.getBoxModel', { backendNodeId: ref.backendNodeId }, sid);
+  // content quad: [x1,y1, x2,y2, x3,y3, x4,y4] -- use center
+  const q = model.content;
+  const x = (q[0] + q[2] + q[4] + q[6]) / 4;
+  const y = (q[1] + q[3] + q[5] + q[7]) / 4;
+  return { x, y, ref };
+}
+
+// Click an element by ref
+export async function clickRefStr(cdp, sid, refMap, refNum) {
+  const { x, y, ref } = await resolveRefToCoords(cdp, sid, refMap, refNum);
+  const base = { x, y, button: 'left', clickCount: 1, modifiers: 0 };
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mousePressed' }, sid);
+  await sleep(50);
+  await cdp.send('Input.dispatchMouseEvent', { ...base, type: 'mouseReleased' }, sid);
+  return `Clicked @e${refNum} [${ref.role}] "${ref.name}" at (${Math.round(x)}, ${Math.round(y)})`;
+}
+
+// Hover over an element by ref
+export async function hoverRefStr(cdp, sid, refMap, refNum) {
+  const { x, y, ref } = await resolveRefToCoords(cdp, sid, refMap, refNum);
+  await cdp.send('Input.dispatchMouseEvent', {
+    type: 'mouseMoved', x, y, button: 'none', modifiers: 0,
+  }, sid);
+  return `Hovering @e${refNum} [${ref.role}] "${ref.name}" at (${Math.round(x)}, ${Math.round(y)})`;
+}
+
+// Focus an element by ref (for fill/type)
+export async function focusRefStr(cdp, sid, refMap, refNum) {
+  const ref = refMap.get(refNum);
+  if (!ref) throw new Error(`Ref @e${refNum} not found. Run "snap --refs" first.`);
+  if (!ref.backendNodeId) throw new Error(`Ref @e${refNum} has no DOM node.`);
+
+  await cdp.send('DOM.enable', {}, sid);
+  await cdp.send('DOM.focus', { backendNodeId: ref.backendNodeId }, sid);
+  return ref;
+}
+
+// Fill an element by ref
+export async function fillRefStr(cdp, sid, refMap, refNum, value) {
+  const ref = await focusRefStr(cdp, sid, refMap, refNum);
+  // Select all + insert text
+  const modKey = process.platform === 'darwin' ? 4 : 2;
+  await cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', key: 'a', code: 'KeyA', modifiers: modKey }, sid);
+  await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: 'a', code: 'KeyA', modifiers: 0 }, sid);
+  await sleep(50);
+  await cdp.send('Input.insertText', { text: String(value) }, sid);
+  return `Filled @e${refNum} [${ref.role}] "${ref.name}" with "${String(value).substring(0, 50)}"`;
+}
+
+// Parse @eN from string, returns null if not a ref
+export function parseRef(str) {
+  if (!str) return null;
+  const m = str.match(/^@e(\d+)$/i);
+  return m ? parseInt(m[1]) : null;
+}