rcf-lite 0.20.0 → 0.22.0

package/src/browser-verify/boot.js

@@ -0,0 +1,180 @@
+// Boot fallback for probe packs (visual-round-spec-2026-09-04 §3.5).
+//
+// The normal path is a dev server already running at `runtimeUrl`. When
+// a pack declares `boot: { bootCommand, waitForUrl, waitForSelector }`
+// AND the runtime is not answering, this module spawns `bootCommand`
+// from the project root, waits (bounded) for `waitForUrl` then
+// `waitForSelector`, hands the running server off to the pack pass,
+// and stops the process it started when the pass completes.
+//
+// Never used as a per-blueprint harness: this only fires when the URL
+// is genuinely unreachable, per Baz's ruling that the running dev
+// server is the normal case (2026-09-04).
+
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export const DEFAULT_URL_TIMEOUT_MS = 60000;
+export const DEFAULT_SELECTOR_TIMEOUT_MS = 10000;
+export const DEFAULT_REACHABLE_PROBE_TIMEOUT_MS = 3000;
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * @param {string} url
+ * @param {(url: string, init?: object) => Promise<any>} fetchFn
+ * @param {number} timeoutMs
+ * @returns {Promise<boolean>}
+ */
+export async function isReachable(url, fetchFn, timeoutMs = DEFAULT_REACHABLE_PROBE_TIMEOUT_MS) {
+  if (typeof url !== 'string' || url.length === 0) return false;
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(url, { signal: controller.signal });
+    if (!res) return false;
+    // Any HTTP response counts as "server up"; even a 404 tells us a
+    // process is listening. Only a network failure means unreachable.
+    return typeof res.status === 'number' && res.status > 0;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+/**
+ * Choose the first boot config across loaded packs (any is fine; the
+ * spec pins one boot per pack pass because runtimeUrl is single).
+ *
+ * @param {Array<import('./pack-loader.js').LoadedPack>} packs
+ * @returns {object|null}
+ */
+export function pickBootFromPacks(packs) {
+  if (!Array.isArray(packs)) return null;
+  for (const pack of packs) {
+    if (pack?.boot && typeof pack.boot === 'object') return pack.boot;
+  }
+  return null;
+}
+
+/**
+ * If the runtime does not answer AND `boot` is declared, bring it up.
+ *
+ * @param {object} args
+ * @param {object|null} args.boot
+ * @param {string} args.runtimeUrl
+ * @param {string} args.projectRoot
+ * @param {(url: string, init?: object) => Promise<any>} args.fetch
+ * @param {object|null} [args.browser]                probe-pack browser (for waitForSelector via snapshot)
+ * @param {(line: string) => void} [args.logger]
+ * @param {() => number} [args.now]                   injectable clock (unit tests)
+ * @param {{ urlMs?: number, selectorMs?: number, reachableProbeMs?: number }} [args.timeouts]
+ * @param {(command: string, opts: object) => import('node:child_process').ChildProcess} [args.spawnFn]  injectable spawner (unit tests)
+ * @returns {Promise<{ started: boolean, source: 'already-up'|'no-boot'|'no-boot-command'|'boot-command'|'no-runtime-url', stop: () => Promise<void>, notes: string[] }>}
+ */
+export async function bootIfNeeded({
+  boot,
+  runtimeUrl,
+  projectRoot,
+  fetch: fetchFn,
+  browser = null,
+  logger = () => {},
+  now = () => Date.now(),
+  timeouts = {},
+  spawnFn = spawn,
+}) {
+  const notes = [];
+  const urlTimeout = timeouts.urlMs ?? DEFAULT_URL_TIMEOUT_MS;
+  const selectorTimeout = timeouts.selectorMs ?? DEFAULT_SELECTOR_TIMEOUT_MS;
+  const reachableTimeout = timeouts.reachableProbeMs ?? DEFAULT_REACHABLE_PROBE_TIMEOUT_MS;
+
+  if (!boot || typeof boot !== 'object') {
+    return { started: false, source: 'no-boot', stop: async () => {}, notes };
+  }
+  const probeUrl = typeof boot.waitForUrl === 'string' && boot.waitForUrl.length > 0
+    ? boot.waitForUrl
+    : runtimeUrl;
+  if (typeof probeUrl !== 'string' || probeUrl.length === 0) {
+    return { started: false, source: 'no-runtime-url', stop: async () => {}, notes };
+  }
+
+  if (await isReachable(probeUrl, fetchFn, reachableTimeout)) {
+    notes.push(`runtime ${probeUrl} already reachable; boot skipped`);
+    return { started: false, source: 'already-up', stop: async () => {}, notes };
+  }
+  if (typeof boot.bootCommand !== 'string' || boot.bootCommand.length === 0) {
+    notes.push(`runtime ${probeUrl} unreachable but pack declares no bootCommand`);
+    return { started: false, source: 'no-boot-command', stop: async () => {}, notes };
+  }
+
+  logger(`[boot] runtime ${probeUrl} unreachable; spawning: ${boot.bootCommand}`);
+  const [cmd, ...args] = boot.bootCommand.split(/\s+/).filter(Boolean);
+  const child = spawnFn(cmd, args, {
+    cwd: projectRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env },
+    detached: false,
+  });
+  child.stdout?.on('data', (b) => logger(`[boot:stdout] ${b.toString('utf8').trimEnd()}`));
+  child.stderr?.on('data', (b) => logger(`[boot:stderr] ${b.toString('utf8').trimEnd()}`));
+
+  const start = now();
+  let up = false;
+  while (now() - start < urlTimeout) {
+    if (await isReachable(probeUrl, fetchFn, reachableTimeout)) { up = true; break; }
+    await sleep(POLL_INTERVAL_MS);
+  }
+  if (!up) {
+    await stopChild(child);
+    throw new Error(`boot: waitForUrl ${probeUrl} did not respond within ${urlTimeout}ms (bootCommand: ${boot.bootCommand})`);
+  }
+  notes.push(`bootCommand up at ${probeUrl} after ${now() - start}ms`);
+
+  if (typeof boot.waitForSelector === 'string' && boot.waitForSelector.length > 0 && browser) {
+    try {
+      await browser.goto(probeUrl);
+      const s0 = now();
+      let selectorSeen = false;
+      while (now() - s0 < selectorTimeout) {
+        const snap = await browser.snapshot();
+        if (matchesSnapshot(snap, boot.waitForSelector)) { selectorSeen = true; break; }
+        await sleep(POLL_INTERVAL_MS);
+      }
+      if (!selectorSeen) notes.push(`waitForSelector '${boot.waitForSelector}' not observed within ${selectorTimeout}ms; proceeding anyway`);
+      else notes.push(`waitForSelector '${boot.waitForSelector}' observed`);
+    } catch (err) {
+      notes.push(`waitForSelector probe failed: ${err.message}`);
+    }
+  }
+
+  return {
+    started: true,
+    source: 'boot-command',
+    stop: async () => { await stopChild(child); },
+    notes,
+  };
+}
+
+async function stopChild(child) {
+  try { child.kill('SIGTERM'); } catch { /* fine */ }
+  await new Promise((resolve) => {
+    if (typeof child.exitCode === 'number' && child.exitCode !== null) return resolve();
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* fine */ } resolve(); }, 3000);
+    child.once?.('exit', () => { clearTimeout(timer); resolve(); });
+  });
+}
+
+/**
+ * Best-effort match of a "selector-shaped" hint against a snapshot text.
+ * We accept: raw substring, an aria role hint (e.g. `role="grid"` -> "grid"),
+ * or a text-content hint. Exposed for unit tests.
+ */
+export function matchesSnapshot(snapshot, selectorOrRef) {
+  if (typeof snapshot !== 'string' || typeof selectorOrRef !== 'string') return false;
+  if (snapshot.includes(selectorOrRef)) return true;
+  const roleMatch = selectorOrRef.match(/\[role\s*=\s*['"]?([\w-]+)['"]?\]/);
+  if (roleMatch && snapshot.includes(roleMatch[1])) return true;
+  const bracketed = selectorOrRef.replace(/[[\]"'=*]/g, ' ').trim();
+  if (bracketed && snapshot.includes(bracketed)) return true;
+  return false;
+}

package/src/browser-verify/index.js

@@ -27,3 +27,16 @@ export {
   runAgentScreenshotCritique,
   stubBrowserDriver,
 } from './runner.js';
+
+export { validatePackModule, PACK_SCHEMA_INTERNALS } from './pack-schema.js';
+export { loadProbePacks, readContributedAcIds } from './pack-loader.js';
+export { runProbePacksForFbs } from './pack-runner.js';
+export { createPackBrowser, parseEvaluateResult } from './pack-browser.js';
+export {
+  bootIfNeeded,
+  isReachable,
+  matchesSnapshot,
+  pickBootFromPacks,
+  DEFAULT_URL_TIMEOUT_MS,
+  DEFAULT_SELECTOR_TIMEOUT_MS,
+} from './boot.js';

package/src/browser-verify/manifest-writer.js

@@ -27,25 +27,49 @@ export function nextBrowserVerificationId(manifest, fbsId) {
 }
 
 /**
- * Aggregate the record verdict per spec §8.5:
- *   block if any invariant severity=block verdict=fail, OR any auth smoke fail;
- *   warn if any invariant severity=warn verdict=fail (and no block);
+ * Aggregate the record verdict per spec §8.5, extended for the visual
+ * round T-0 probe-pack pass (visual-round-spec-2026-09-04 §3.4):
+ *   block if any invariant severity=block verdict=fail, OR any auth smoke fail,
+ *          OR any pack check / pre-check severity=block verdict=fail;
+ *   warn  if any invariant severity=warn verdict=fail (and no block),
+ *          OR any pack check / pre-check severity=warn verdict=fail (and no block);
  *   pass otherwise.
  *
+ * `probePacks` is optional so pre-T-0 callers keep the old signature.
+ *
  * @param {Array<{ invariant: string, verdict: 'pass'|'warn'|'fail', severity: 'block'|'warn'|'advisory' }>} invariantChecks
  * @param {Array<{ verdict: 'pass'|'warn'|'fail' }>} authSmokeChecks
+ * @param {Array<{ applicable?: boolean, checks?: Array<{ verdict: 'pass'|'warn'|'fail'|'skipped', severity?: 'block'|'warn'|'advisory' }>, preChecks?: Array<{ verdict: 'pass'|'warn'|'fail'|'skipped', severity?: 'block'|'warn'|'advisory' }> }>} [probePacks]
  * @returns {'pass'|'warn'|'block'}
  */
-export function aggregateVerdict(invariantChecks, authSmokeChecks) {
+export function aggregateVerdict(invariantChecks, authSmokeChecks, probePacks) {
   for (const check of invariantChecks) {
     if (check.severity === 'block' && check.verdict === 'fail') return 'block';
   }
   for (const check of authSmokeChecks ?? []) {
     if (check.verdict === 'fail') return 'block';
   }
+  for (const pack of probePacks ?? []) {
+    if (pack?.applicable === false) continue;
+    for (const c of pack?.checks ?? []) {
+      if (c?.severity === 'block' && c?.verdict === 'fail') return 'block';
+    }
+    for (const c of pack?.preChecks ?? []) {
+      if (c?.severity === 'block' && c?.verdict === 'fail') return 'block';
+    }
+  }
   for (const check of invariantChecks) {
     if (check.severity === 'warn' && (check.verdict === 'fail' || check.verdict === 'warn')) return 'warn';
   }
+  for (const pack of probePacks ?? []) {
+    if (pack?.applicable === false) continue;
+    for (const c of pack?.checks ?? []) {
+      if (c?.severity === 'warn' && c?.verdict === 'fail') return 'warn';
+    }
+    for (const c of pack?.preChecks ?? []) {
+      if (c?.severity === 'warn' && c?.verdict === 'fail') return 'warn';
+    }
+  }
   return 'pass';
 }
 
@@ -67,10 +91,10 @@ export function aggregateVerdict(invariantChecks, authSmokeChecks) {
  */
 export function composeBrowserVerificationRecord({
   manifest, fbsId, mode, runtimeProfile, runtimeUrl, routesChecked,
-  invariantChecks, authSmokeChecks = [], notes, now = new Date(),
+  invariantChecks, authSmokeChecks = [], probePacks = [], notes, now = new Date(),
 }) {
   const id = nextBrowserVerificationId(manifest, fbsId);
-  const verdict = aggregateVerdict(invariantChecks, authSmokeChecks);
+  const verdict = aggregateVerdict(invariantChecks, authSmokeChecks, probePacks);
   const record = {
     id,
     fbsId,
@@ -83,6 +107,7 @@ export function composeBrowserVerificationRecord({
     verdict,
   };
   if (authSmokeChecks && authSmokeChecks.length > 0) record.authSmokeChecks = authSmokeChecks;
+  if (Array.isArray(probePacks) && probePacks.length > 0) record.probePacks = probePacks;
   if (typeof notes === 'string' && notes.length > 0) record.notes = notes;
   return record;
 }

package/src/browser-verify/pack-browser.js

@@ -0,0 +1,294 @@
+// packBrowser: a real headless browser exposed to blueprint-shipped
+// probe packs (visual-round-spec-2026-09-04 §3.3). The browser is
+// provisioned through the pinned Playwright MCP server as a JSON-RPC
+// 2.0 stdio client, with an optional cheaper route via a `playwright`
+// installation already resolved from the consuming project's own
+// node_modules. Both routes expose the same small stable API:
+//
+//   goto(url)                  navigate to a URL
+//   snapshot()                 accessibility-tree text (searchable)
+//   evaluate(fn, arg?)         run JS in page context; returns parsed value
+//   click(selectorOrRef, hint) click an element by CSS selector or a11y ref
+//   type(selectorOrRef, text)  type into an editable element
+//   press(key)                 press a keyboard key
+//   resize(width, height)      set viewport dimensions (breakpoint reflow probes)
+//   screenshot(filename?)      capture a PNG; returns descriptor / path
+//   close()                    close the page + terminate the browser process
+//
+// Zero new npm dependencies: MCP over stdio uses only Node built-ins;
+// the cheap route uses `playwright` peer dep if the project already
+// installed it. No LLM call anywhere.
+
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { resolve as resolvePath } from 'node:path';
+
+import { PLAYWRIGHT_MCP_VERSION } from '../verify/engine/launcher.js';
+
+const DEFAULT_TOOL_TIMEOUT_MS = 30000;
+const INIT_TIMEOUT_MS = 45000;
+
+/**
+ * Compose a packBrowser for use by probe packs.
+ *
+ * @param {object} [options]
+ * @param {string} [options.projectRoot]           consuming project root; used to try the cheap route
+ * @param {string} [options.playwrightMcpVersion]  pinned MCP semver (defaults to PLAYWRIGHT_MCP_VERSION)
+ * @param {'auto'|'mcp'|'project'} [options.route] force a route (default 'auto')
+ * @param {(line: string) => void} [options.logger]
+ * @param {NodeJS.ProcessEnv} [options.env]
+ * @param {number} [options.timeoutMs]             per-RPC timeout
+ * @returns {Promise<object>}                      the packBrowser handle
+ */
+export async function createPackBrowser(options = {}) {
+  const {
+    projectRoot,
+    playwrightMcpVersion = PLAYWRIGHT_MCP_VERSION,
+    route = 'auto',
+    logger = () => {},
+    env = process.env,
+    timeoutMs = DEFAULT_TOOL_TIMEOUT_MS,
+  } = options;
+
+  if (route === 'project' || (route === 'auto' && projectRoot && await tryResolveProjectPlaywright(projectRoot))) {
+    const handle = await createProjectPlaywrightHandle({ projectRoot, logger });
+    if (handle) return handle;
+    if (route === 'project') throw new Error(`packBrowser: project route requested but 'playwright' is not installed under ${projectRoot}`);
+  }
+  return createMcpPackBrowser({ playwrightMcpVersion, logger, env, timeoutMs });
+}
+
+async function tryResolveProjectPlaywright(projectRoot) {
+  try {
+    const req = createRequire(resolvePath(projectRoot, 'package.json'));
+    req.resolve('playwright');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createProjectPlaywrightHandle({ projectRoot, logger }) {
+  try {
+    const req = createRequire(resolvePath(projectRoot, 'package.json'));
+    const playwrightPath = req.resolve('playwright');
+    const mod = await import(pathToFileURL(playwrightPath).href);
+    const chromium = mod?.chromium ?? mod?.default?.chromium;
+    if (!chromium) return null;
+    const browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    return Object.freeze({
+      provisioning: { via: 'project-playwright', playwrightPath },
+      async goto(url) { await page.goto(url, { waitUntil: 'load' }); },
+      async snapshot() {
+        const tree = await page.accessibility.snapshot({ interestingOnly: false });
+        return renderA11yTree(tree);
+      },
+      async evaluate(fn, arg) {
+        if (typeof fn === 'function') return page.evaluate(fn, arg);
+        return page.evaluate(String(fn));
+      },
+      async click(selector) { await page.click(selector); },
+      async type(selector, text) { await page.fill(selector, text); },
+      async press(key) { await page.keyboard.press(key); },
+      async resize(width, height) {
+        const w = normaliseDim(width, 'width');
+        const h = normaliseDim(height, 'height');
+        await page.setViewportSize({ width: w, height: h });
+      },
+      async screenshot(filename) {
+        const target = filename ? { path: filename } : undefined;
+        const buf = await page.screenshot(target);
+        return filename ?? `data:image/png;base64,${buf.toString('base64')}`;
+      },
+      async close() {
+        logger('[pack-browser] closing project-playwright browser');
+        try { await page.close(); } catch { /* fine */ }
+        try { await context.close(); } catch { /* fine */ }
+        try { await browser.close(); } catch { /* fine */ }
+      },
+    });
+  } catch (err) {
+    logger(`[pack-browser] project-playwright route failed: ${err.message}`);
+    return null;
+  }
+}
+
+function renderA11yTree(node, depth = 0) {
+  if (!node) return '';
+  const pad = '  '.repeat(depth);
+  const parts = [];
+  parts.push(`${pad}${node.role ?? '?'} ${node.name ? JSON.stringify(node.name) : ''}`.trimEnd());
+  for (const child of node.children ?? []) parts.push(renderA11yTree(child, depth + 1));
+  return parts.join('\n');
+}
+
+async function createMcpPackBrowser({ playwrightMcpVersion, logger, env, timeoutMs }) {
+  const child = spawn('npx', ['-y', `@playwright/mcp@${playwrightMcpVersion}`, '--headless', '--isolated'], {
+    env: { ...env },
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  /** @type {Map<number, { resolve: (v: any) => void, reject: (e: Error) => void, timer: NodeJS.Timeout|null }>} */
+  const pending = new Map();
+  let nextId = 1;
+  let buffer = '';
+  let exited = false;
+
+  child.stdout.on('data', (chunk) => {
+    buffer += chunk.toString('utf8');
+    for (;;) {
+      const nl = buffer.indexOf('\n');
+      if (nl === -1) break;
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }
+      if (msg.id != null && pending.has(msg.id)) {
+        const p = pending.get(msg.id);
+        pending.delete(msg.id);
+        if (p.timer) clearTimeout(p.timer);
+        if (msg.error) p.reject(new Error(msg.error.message ?? `MCP error ${JSON.stringify(msg.error)}`));
+        else p.resolve(msg.result);
+      }
+    }
+  });
+  child.stderr.on('data', (chunk) => logger(`[playwright-mcp] ${chunk.toString('utf8').trimEnd()}`));
+  child.on('exit', (code) => {
+    exited = true;
+    for (const [, p] of pending) {
+      if (p.timer) clearTimeout(p.timer);
+      p.reject(new Error(`Playwright MCP exited (code=${code})`));
+    }
+    pending.clear();
+  });
+
+  function rpc(method, params, { timeout = timeoutMs } = {}) {
+    if (exited) return Promise.reject(new Error('Playwright MCP process already exited'));
+    const id = nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (pending.has(id)) {
+          pending.delete(id);
+          reject(new Error(`MCP method ${method} timed out after ${timeout}ms`));
+        }
+      }, timeout);
+      pending.set(id, { resolve, reject, timer });
+      child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+    });
+  }
+
+  async function tool(name, args) {
+    const result = await rpc('tools/call', { name, arguments: args ?? {} });
+    if (result?.isError) {
+      const text = textOf(result);
+      throw new Error(`Playwright MCP ${name} failed: ${text || JSON.stringify(result)}`);
+    }
+    return result;
+  }
+
+  await rpc('initialize', {
+    protocolVersion: '2024-11-05',
+    capabilities: {},
+    clientInfo: { name: 'rcf-lite-pack-browser', version: '0.0.0' },
+  }, { timeout: INIT_TIMEOUT_MS });
+  // Best-effort initialized notification (some servers ignore, that is fine).
+  try {
+    child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' })}\n`);
+  } catch { /* fine */ }
+
+  return Object.freeze({
+    provisioning: { via: 'playwright-mcp', version: playwrightMcpVersion },
+    async goto(url) {
+      await tool('browser_navigate', { url });
+    },
+    async snapshot() {
+      return textOf(await tool('browser_snapshot', {}));
+    },
+    async evaluate(fn, arg) {
+      const src = composeEvaluateSource(fn, arg);
+      const text = textOf(await tool('browser_evaluate', { function: src }));
+      return parseEvaluateResult(text);
+    },
+    async click(selector, hint) {
+      await tool('browser_click', { target: selector, element: hint ?? selector });
+    },
+    async type(selector, text, hint) {
+      await tool('browser_type', { target: selector, text, element: hint ?? selector });
+    },
+    async press(key) {
+      await tool('browser_press_key', { key });
+    },
+    async resize(width, height) {
+      const w = normaliseDim(width, 'width');
+      const h = normaliseDim(height, 'height');
+      await tool('browser_resize', { width: w, height: h });
+    },
+    async screenshot(filename) {
+      const args = filename ? { filename } : {};
+      return textOf(await tool('browser_take_screenshot', args));
+    },
+    async close() {
+      logger('[pack-browser] closing playwright-mcp browser');
+      try { await tool('browser_close', {}); } catch { /* fine */ }
+      try { child.stdin.end(); } catch { /* fine */ }
+      await new Promise((resolve) => {
+        if (exited) return resolve();
+        const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* fine */ } resolve(); }, 5000);
+        child.once('exit', () => { clearTimeout(timer); resolve(); });
+      });
+    },
+  });
+}
+
+/**
+ * Coerce a viewport dimension argument to a positive integer.
+ * Exposed for unit tests through resize() call sites.
+ */
+function normaliseDim(value, label) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(`packBrowser.resize: ${label} must be a positive number (got ${JSON.stringify(value)})`);
+  }
+  return Math.round(n);
+}
+
+function textOf(result) {
+  const parts = Array.isArray(result?.content) ? result.content : [];
+  return parts.map((c) => (c?.type === 'text' ? (c.text ?? '') : '')).join('\n');
+}
+
+function composeEvaluateSource(fn, arg) {
+  if (typeof fn !== 'function') return String(fn);
+  if (arg === undefined) return fn.toString();
+  return `() => (${fn.toString()})(${JSON.stringify(arg)})`;
+}
+
+/**
+ * The MCP browser_evaluate response is a human-readable text block, usually of
+ * the shape "- Ran Playwright code:\n... - Result: <json-ish>". Parse the trailing
+ * value out of it and JSON-parse when possible. Exported for unit tests.
+ */
+export function parseEvaluateResult(text) {
+  if (typeof text !== 'string') return text;
+  // MCP 0.0.80+ returns "### Result\n<value>\n### Ran Playwright code\n```js..."
+  const headed = text.match(/###\s*Result\s*\n([\s\S]*?)(?=\n###\s|\n?$)/);
+  if (headed) {
+    const inner = headed[1].trim().replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+    try { return JSON.parse(inner); } catch { return inner; }
+  }
+  // Older MCP shape: "Result: <value>" trailing block.
+  const marker = text.lastIndexOf('Result:');
+  const tail = marker >= 0 ? text.slice(marker + 'Result:'.length).trim() : text.trim();
+  const stripped = tail.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+  try { return JSON.parse(stripped); } catch { return stripped; }
+}
+
+/**
+ * Internals exposed to unit tests. Not part of the public seam a
+ * probe pack sees; do not import from a pack.
+ */
+export const PACK_BROWSER_INTERNALS = Object.freeze({ normaliseDim });