@monoes/monomindcli 2.16.4 → 2.16.5

package/.claude/skills/monodesign/scripts/detector/detect-antipatterns.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Anti-Pattern Detector for Monodesign
+ * Copyright (c) 2026 Paul Bakaus
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Public API facade. Runtime engines live under cli/engine/engines/.
+ */
+
+import { detectCli } from './cli/main.mjs';
+
+export { ANTIPATTERNS, RULE_ENGINE_SUPPORT, getAntipattern, getRulesForCategory, getRuleEngineSupport } from './registry/antipatterns.mjs';
+export { SAFE_TAGS, BORDER_SAFE_TAGS, OVERUSED_FONTS, GENERIC_FONTS, KNOWN_SERIF_FONTS } from './shared/constants.mjs';
+export { isNeutralColor, parseRgb, relativeLuminance, contrastRatio, parseGradientColors, hasChroma, getHue, colorToHex } from './shared/color.mjs';
+export { isFullPage } from './shared/page.mjs';
+export {
+  checkElementBorders,
+  checkElementMotion,
+  checkElementGlow,
+  checkPageTypography,
+  checkPageLayout,
+  checkHtmlPatterns,
+} from './rules/checks.mjs';
+export { createDetectorProfile, summarizeDetectorProfile } from './profile/profiler.mjs';
+export {
+  parseFrontmatter as parseDesignFrontmatter,
+  normalizeDesignSystem,
+  loadDesignSystemForCwd,
+  checkSourceDesignSystem,
+  collectStaticDesignSystemFindings,
+} from './design-system.mjs';
+export { detectHtml } from './engines/static-html/detect-html.mjs';
+export { detectUrl, createBrowserDetector } from './engines/browser/detect-url.mjs';
+export { detectText, extractStyleBlocks, extractCSSinJS } from './engines/regex/detect-text.mjs';
+export {
+  walkDir,
+  SCANNABLE_EXTENSIONS,
+  SKIP_DIRS,
+  buildImportGraph,
+  resolveImport,
+  detectFrameworkConfig,
+  isPortListening,
+  FRAMEWORK_CONFIGS,
+} from './node/file-system.mjs';
+export { formatFindings, detectCli } from './cli/main.mjs';
+
+const isMainModule = process.argv[1]?.endsWith('detect-antipatterns.mjs') ||
+  process.argv[1]?.endsWith('detect-antipatterns.mjs/');
+if (isMainModule) detectCli();

package/.claude/skills/monodesign/scripts/detector/engines/browser/detect-url.mjs

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { finding } from '../../findings.mjs';
+import { filterByProviders } from '../../registry/antipatterns.mjs';
+import { profileFindingsAsync, profileStep, profileStepAsync } from '../../profile/profiler.mjs';
+import { captureVisualContrastCandidate } from '../visual/screenshot-contrast.mjs';
+import { launchDetectionBrowser, normalizeBrowserHandle } from './drivers.mjs';
+
+function serializeDesignSystemForBrowser(designSystem) {
+  if (!designSystem?.present) return null;
+  return {
+    present: true,
+    hasFonts: designSystem.hasFonts === true,
+    allowedFonts: Array.from(designSystem.allowedFonts || []),
+    hasColors: designSystem.hasColors === true,
+    allowedColors: Array.from(designSystem.allowedColorKeys?.values?.() || [])
+      .map(entry => entry?.color)
+      .filter(color => color && Number.isFinite(color.r) && Number.isFinite(color.g) && Number.isFinite(color.b))
+      .map(color => ({ r: color.r, g: color.g, b: color.b })),
+    hasRadii: designSystem.hasRadii === true,
+    allowedRadii: (designSystem.allowedRadii || [])
+      .map(entry => Number(entry?.px))
+      .filter(px => Number.isFinite(px)),
+    hasPillRadius: designSystem.hasPillRadius === true,
+  };
+}
+
+async function runVisualContrastFallback(page, serializedGroups, options, profile, target) {
+  if (options?.visualContrast === false) return [];
+  const maxCandidates = Number.isFinite(options?.visualContrastMaxCandidates)
+    ? options.visualContrastMaxCandidates
+    : 12;
+  const scrollOffscreen = options?.visualContrastScrollOffscreen !== false;
+  const existingLowContrastSelectors = new Set(
+    serializedGroups
+      .filter(group => group.findings?.some(f => f.type === 'low-contrast'))
+      .map(group => group.selector)
+      .filter(Boolean)
+  );
+
+  let browserAnalyses = [];
+  const findings = [];
+  if (options?.visualContrastBrowser !== false) {
+    const browserFindings = await profileFindingsAsync(profile, {
+      engine: 'browser',
+      phase: 'visual-contrast',
+      ruleId: 'browser-fallback',
+      target,
+    }, async () => {
+      browserAnalyses = await page.evaluate(async ({ maxCandidates, scrollOffscreen }) => {
+        if (typeof window.monodesignAnalyzeVisualContrast !== 'function') return [];
+        return window.monodesignAnalyzeVisualContrast({ maxCandidates, scrollOffscreen });
+      }, { maxCandidates, scrollOffscreen });
+      return browserAnalyses
+        .filter(result => result.finding && !existingLowContrastSelectors.has(result.selector))
+        .map(result => result.finding);
+    });
+    findings.push(...browserFindings);
+  }
+
+  let candidates = browserAnalyses.length > 0 ? browserAnalyses : [];
+  if (candidates.length === 0) {
+    candidates = await profileStepAsync(profile, {
+      engine: 'browser',
+      phase: 'visual-contrast',
+      ruleId: 'collect-candidates',
+      target,
+    }, () => page.evaluate(({ maxCandidates }) => {
+      if (typeof window.monodesignCollectVisualContrastCandidates !== 'function') return [];
+      return window.monodesignCollectVisualContrastCandidates({ maxCandidates });
+    }, { maxCandidates }));
+  }
+
+  const viewport = options?.viewport || { width: 1280, height: 800 };
+  const browserResolvedSelectors = new Set(
+    browserAnalyses
+      .filter(result => result.status === 'fail' || result.status === 'pass')
+      .map(result => result.selector)
+      .filter(Boolean)
+  );
+  const filtered = candidates.filter(candidate =>
+    !existingLowContrastSelectors.has(candidate.selector) &&
+    !browserResolvedSelectors.has(candidate.selector)
+  );
+  if (options?.visualContrastPixel === false) return findings;
+  for (const candidate of filtered) {
+    const result = await profileFindingsAsync(profile, {
+      engine: 'browser',
+      phase: 'visual-contrast',
+      ruleId: 'pixel-diff',
+      target,
+    }, async () => {
+      const finding = await captureVisualContrastCandidate(page, candidate, viewport);
+      return finding ? [finding] : [];
+    });
+    findings.push(...result);
+  }
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Browser detection (for URLs) — driver-based: monobrowse (native CDP,
+// preferred) with puppeteer as fallback. See ./drivers.mjs for the seam.
+// ---------------------------------------------------------------------------
+
+async function detectUrl(url, options = {}) {
+  const profile = options?.profile;
+  const waitUntil = options?.waitUntil || 'networkidle0';
+  const settleMs = Number.isFinite(options?.settleMs) ? options.settleMs : 0;
+  const viewport = options?.viewport || { width: 1280, height: 800 };
+  // options.browser accepts either a driver handle (from createBrowserDetector)
+  // or a raw puppeteer Browser (legacy callers).
+  const externalBrowser = options?.browser ? normalizeBrowserHandle(options.browser) : null;
+
+  // Read the browser detection script — reuse it instead of reimplementing
+  const browserScriptPath = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '..',
+    '..',
+    'detect-antipatterns-browser.js'
+  );
+  let browserScript;
+  try {
+    browserScript = profileStep(profile, {
+      engine: 'browser',
+      phase: 'setup',
+      ruleId: 'read-browser-script',
+      target: url,
+    }, () => fs.readFileSync(browserScriptPath, 'utf-8'));
+  } catch {
+    throw new Error(`Browser script not found at ${browserScriptPath}`);
+  }
+
+  const browser = externalBrowser || await profileStepAsync(profile, {
+    engine: 'browser',
+    phase: 'load',
+    ruleId: 'launch-browser',
+    target: url,
+  }, () => launchDetectionBrowser({ launchArgs: options?.launchArgs, headless: true }));
+  const page = await profileStepAsync(profile, {
+    engine: 'browser',
+    phase: 'load',
+    ruleId: 'new-page',
+    target: url,
+  }, () => browser.newPage());
+  let results = [];
+  try {
+    await profileStepAsync(profile, {
+      engine: 'browser',
+      phase: 'load',
+      ruleId: 'set-viewport',
+      target: url,
+    }, () => page.setViewport(viewport));
+    await profileStepAsync(profile, {
+      engine: 'browser',
+      phase: 'load',
+      ruleId: `goto:${waitUntil}`,
+      target: url,
+    }, () => page.goto(url, { waitUntil, timeout: 30000 }));
+    if (settleMs > 0) {
+      await profileStepAsync(profile, {
+        engine: 'browser',
+        phase: 'load',
+        ruleId: 'settle',
+        target: url,
+      }, () => new Promise(resolve => setTimeout(resolve, settleMs)));
+    }
+
+    // Inject the browser detection script and collect results
+    const browserDesignSystem = serializeDesignSystemForBrowser(options?.designSystem);
+    await profileStepAsync(profile, {
+      engine: 'browser',
+      phase: 'scan',
+      ruleId: 'configure-pure-detect',
+      target: url,
+    }, () => page.evaluate((designSystem) => {
+      window.__MONODESIGN_CONFIG__ = {
+        ...(window.__MONODESIGN_CONFIG__ || {}),
+        autoScan: false,
+        ...(designSystem ? { designSystem } : {}),
+      };
+    }, browserDesignSystem));
+    await profileStepAsync(profile, {
+      engine: 'browser',
+      phase: 'scan',
+      ruleId: 'inject-browser-script',
+      target: url,
+    }, () => page.evaluate(browserScript));
+    let serializedGroups = [];
+    results = await profileFindingsAsync(profile, {
+      engine: 'browser',
+      phase: 'scan',
+      ruleId: 'browser-scan',
+      target: url,
+    }, async () => {
+      serializedGroups = await page.evaluate(() => {
+        if (!window.monodesignDetect) return [];
+        return window.monodesignDetect({ decorate: false, serialize: true });
+      });
+      return serializedGroups.flatMap(({ findings }) =>
+        findings.map(f => ({ id: f.type, snippet: f.detail, ignoreValue: f.ignoreValue || '' }))
+      );
+    });
+    const visualFindings = await runVisualContrastFallback(page, serializedGroups, options, profile, url);
+    results.push(...visualFindings);
+  } finally {
+    await profileStepAsync(profile, {
+      engine: 'browser',
+      phase: 'load',
+      ruleId: 'close-page',
+      target: url,
+    }, () => page.close().catch(() => {}));
+    if (!externalBrowser) {
+      await profileStepAsync(profile, {
+        engine: 'browser',
+        phase: 'load',
+        ruleId: 'close-browser',
+        target: url,
+      }, () => browser.close());
+    }
+  }
+  return filterByProviders(results.map(f => {
+    const item = finding(f.id, url, f.snippet);
+    if (f.ignoreValue) item.ignoreValue = f.ignoreValue;
+    return item;
+  }), options.providers);
+}
+
+async function createBrowserDetector(options = {}) {
+  // Pooled reuse for multiple URLs. `browser` is a driver handle (monobrowse
+  // or puppeteer); pass a raw puppeteer Browser via options.browser to reuse
+  // an externally managed instance.
+  const browser = options.browser
+    ? normalizeBrowserHandle(options.browser)
+    : await launchDetectionBrowser({ launchArgs: options.launchArgs, headless: options.headless ?? true });
+  const ownsBrowser = !options.browser;
+  const defaults = {
+    waitUntil: options.waitUntil || 'load',
+    settleMs: Number.isFinite(options.settleMs) ? options.settleMs : 100,
+    viewport: options.viewport || { width: 1280, height: 800 },
+  };
+  return {
+    browser,
+    async detectUrl(url, scanOptions = {}) {
+      return detectUrl(url, {
+        ...defaults,
+        ...scanOptions,
+        browser,
+      });
+    },
+    async close() {
+      if (ownsBrowser) await browser.close().catch(() => {});
+    },
+  };
+}
+
+export { runVisualContrastFallback, detectUrl, createBrowserDetector };

package/.claude/skills/monodesign/scripts/detector/engines/browser/drivers.mjs

@@ -0,0 +1,339 @@
+//
+// Browser driver seam for URL detection.
+//
+// The detection engine (detect-url.mjs) and the visual-contrast fallback
+// (engines/visual/screenshot-contrast.mjs) only need a tiny, puppeteer-shaped
+// page surface:
+//
+//   browser: { driverName, newPage(): Promise<page>, close(): Promise<void> }
+//   page:    {
+//     setViewport({ width, height })
+//     goto(url, { waitUntil, timeout })
+//     evaluate(fnOrExpressionString, ...serializableArgs) -> serializable value
+//     screenshot({ encoding: 'base64', clip?, captureBeyondViewport? }) -> base64 string
+//     close()
+//   }
+//
+// Two drivers implement it:
+//   - monobrowse (preferred): @monoes/monobrowse, the monorepo's native CDP
+//     client. Drives a locally installed Chrome/Edge/Chromium — no bundled
+//     Chromium download needed. Supports the full surface including clip
+//     screenshots (Page.captureScreenshot) and evaluate roundtrips
+//     (Runtime.evaluate), so the visual-contrast pixel fallback runs under it.
+//   - puppeteer (fallback): the original optionalDependency path, kept for
+//     environments that have puppeteer + its downloaded Chrome but no system
+//     browser. A raw puppeteer Page already satisfies the page surface, so the
+//     puppeteer driver returns real puppeteer pages untouched.
+//
+// Selection: MONODESIGN_BROWSER_DRIVER=monobrowse|puppeteer forces one;
+// otherwise monobrowse is tried first and puppeteer is the fallback.
+
+import { createServer } from 'node:net';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const DRIVER_ENV = 'MONODESIGN_BROWSER_DRIVER';
+// Windows CI teardown is the slow case: Chrome acknowledges Browser.close long
+// before the process exits and hands the socket back, and closeBrowser()'s
+// force-kill safety net is itself a deferred 1s timer. 5s is comfortable
+// locally but cuts into a loaded runner's teardown, so give CI more runway —
+// same reasoning as launchTimeoutMs below.
+const CDP_PORT_RELEASE_TIMEOUT_MS = process.env.CI ? 15_000 : 5_000;
+const CDP_PORT_RELEASE_POLL_MS = 25;
+const PROFILE_CLEANUP_RETRY_MS = 2_000;
+
+function serializeEvalArg(arg) {
+  const json = JSON.stringify(arg);
+  return json === undefined ? 'undefined' : json;
+}
+
+function mapWaitUntil(waitUntil) {
+  if (waitUntil === 'domcontentloaded') return 'domcontentloaded';
+  if (waitUntil === 'networkidle0' || waitUntil === 'networkidle2' || waitUntil === 'networkidle') return 'networkidle';
+  return 'load';
+}
+
+// This timer is deliberately NOT unref'd. Both call sites race it against CDP
+// I/O that can die silently: goto() awaits a promise settled only by a
+// Page.loadEventFired/domContentEventFired event, and close() races
+// Browser.close — the very command that tears the websocket down. An unref'd
+// timer never fires once nothing else pins the event loop, and a launched
+// Chrome is detached and unref'd, so that websocket is the only ref'd handle
+// here — exactly the one that goes away. Node would then consider the loop
+// drained and exit 0 with the race still pending, instead of surfacing the
+// timeout. The .finally() below clears it either way, so keeping it ref'd
+// only ever costs a caller `ms`, never a hang. (Same rule as monobrowse's
+// waitForProcessExit, #314.)
+function withTimeout(promise, ms, label) {
+  let handle;
+  const timeout = new Promise((_, reject) => {
+    handle = setTimeout(() => reject(new Error(`Timeout waiting for ${label} after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(handle));
+}
+
+// "Released" has to mean BINDABLE, not merely unreachable. A connect probe
+// stops succeeding as soon as Chrome's listener socket closes, which happens
+// early in its shutdown — while the process is still alive holding both the
+// port and the --user-data-dir singleton lock for this port. On Windows that
+// gap is wide and the socket stays unbindable across it (node does not set
+// SO_REUSEADDR there), so close() reported success and the next launch on the
+// same forced port sat until its timeout: "Chrome failed to start on port N
+// within 30000ms". Binding is the question the next launch actually asks, so
+// ask it directly. A listener that never accepted a connection leaves no
+// TIME_WAIT behind, so probing this way does not itself hold the port.
+function isPortBindable(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+  });
+}
+
+function removeProfileDir(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    /* reclaimed by the OS's temp cleanup instead */
+  }
+}
+
+async function waitForCdpPortRelease(port) {
+  const deadline = Date.now() + CDP_PORT_RELEASE_TIMEOUT_MS;
+  while (Date.now() < deadline) {
+    if (await isPortBindable(port)) return;
+    await new Promise(resolve => setTimeout(resolve, CDP_PORT_RELEASE_POLL_MS));
+  }
+  throw new Error(`Chrome did not release CDP port ${port} within ${CDP_PORT_RELEASE_TIMEOUT_MS}ms`);
+}
+
+// ---------------------------------------------------------------------------
+// monobrowse driver
+// ---------------------------------------------------------------------------
+
+function createMonobrowsePage(mb, client, sessionId, targetId, port) {
+  return {
+    async setViewport({ width, height }) {
+      await mb.setViewport(client, sessionId, width, height);
+    },
+    async goto(url, { waitUntil = 'load', timeout = 30000 } = {}) {
+      const condition = mapWaitUntil(waitUntil);
+      if (condition === 'networkidle') {
+        const nav = await client.send('Page.navigate', { url }, sessionId);
+        if (nav?.errorText) throw new Error(`Navigation to ${url} failed: ${nav.errorText}`);
+        await mb.waitForLoad(client, sessionId, 'networkidle', timeout);
+        return;
+      }
+      // Register the lifecycle listener BEFORE navigating so a fast page load
+      // cannot slip past it (waitForLoad's readyState pre-check would otherwise
+      // race against the previous document's readyState).
+      const event = condition === 'load' ? 'Page.loadEventFired' : 'Page.domContentEventFired';
+      const [eventPromise, cancel] = client.onceWithOff(event, sessionId);
+      try {
+        const nav = await client.send('Page.navigate', { url }, sessionId);
+        if (nav?.errorText) throw new Error(`Navigation to ${url} failed: ${nav.errorText}`);
+        await withTimeout(eventPromise, timeout, condition);
+      } finally {
+        cancel();
+      }
+    },
+    async evaluate(fnOrExpression, ...args) {
+      const expression = typeof fnOrExpression === 'function'
+        ? `(${String(fnOrExpression)})(${args.map(serializeEvalArg).join(', ')})`
+        : String(fnOrExpression);
+      const result = await client.send('Runtime.evaluate', {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+      }, sessionId);
+      if (result?.exceptionDetails) {
+        const details = result.exceptionDetails;
+        throw new Error(details.exception?.description || details.exception?.value || details.text || 'Evaluation failed');
+      }
+      return result?.result?.value;
+    },
+    // Always returns a base64 string (the only mode the engine uses).
+    async screenshot({ clip } = {}) {
+      const params = { format: 'png' };
+      if (clip) {
+        params.clip = { x: clip.x, y: clip.y, width: clip.width, height: clip.height, scale: 1 };
+        params.captureBeyondViewport = true;
+      }
+      const result = await client.send('Page.captureScreenshot', params, sessionId);
+      return result?.data;
+    },
+    async close() {
+      // HTTP endpoint works regardless of which domains the ws connection has.
+      try {
+        await fetch(`http://127.0.0.1:${port}/json/close/${encodeURIComponent(targetId)}`);
+      } catch {
+        // Tab may already be gone; browser close cleans up anything left.
+      }
+      client.close();
+    },
+  };
+}
+
+async function launchMonobrowseBrowser(options = {}) {
+  const mb = await import('@monoes/monobrowse');
+  const headless = options.headless ?? true;
+  const launchArgs = options.launchArgs || (process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : []);
+
+  // We must never attach to a browser we did not launch: browser.close()
+  // issues Browser.close. Picking a "free" port ourselves cannot guarantee
+  // that — the port is only probed, and a concurrent launch (node --test runs
+  // files in parallel) can pick the same one before either Chrome binds it.
+  // The losing Chrome then listens on [::1] instead and its launcher attaches
+  // to the winner's browser, which dies under it ("CDP connection closed")
+  // when the winner closes. Port 0 has Chrome take a kernel-assigned port and
+  // report it in its own profile dir, so the endpoint is always ours.
+  const forcedPort = Number(process.env.MONODESIGN_MONOBROWSE_PORT);
+  const port = Number.isInteger(forcedPort) && forcedPort > 0 ? forcedPort : 0;
+
+  // CI runners (observed on the Windows GH Actions runner) are slower to get
+  // Chrome's CDP port open than the 10s default — a batch of sequential
+  // headless launches in the same job intermittently misses that window and
+  // fails with "Chrome failed to start... within 10000ms" even though the
+  // browser starts fine, just later. Give CI more runway; local dev keeps
+  // the tighter default so a genuinely broken launch still fails fast.
+  const launchTimeoutMs = options.launchTimeoutMs ?? (process.env.CI ? 30000 : undefined);
+  // Throwaway profile per launch. monobrowse defaults --user-data-dir to
+  // tmpdir()/monomind-browser-<port>, which is right for `monomind browse`
+  // (a later process reattaches to the same session by port) but wrong here:
+  // detection launches are stateless, and keying the profile on the port
+  // means two launches on the SAME port share one profile. Chrome enforces
+  // single-instance-per-profile, so the second launch rendezvouses with the
+  // first instead of starting its own — it hands over its command line and
+  // exits without ever opening a debugging port, which surfaces as "Chrome
+  // failed to start on port N" after the full launch timeout. Windows is
+  // where this bites: its singleton lock survives the previous Chrome being
+  // force-killed, and outlives the port being released. A unique dir removes
+  // the sharing entirely rather than racing the lock's cleanup.
+  const userDataDir = mkdtempSync(join(tmpdir(), 'monodesign-cdp-'));
+  const launchedPort = await mb.launchBrowser({ port, headless, args: launchArgs, launchTimeoutMs, userDataDir });
+  // Control connection (to the initial about:blank tab) — used for lifecycle
+  // commands; detection pages get their own dedicated connections.
+  const control = await mb.connectToTarget(launchedPort);
+
+  async function openPage() {
+    const target = await mb.fetchNewTarget(launchedPort, 'about:blank');
+    const wsUrl = target.webSocketDebuggerUrl || `ws://127.0.0.1:${launchedPort}/devtools/page/${target.id}`;
+    const client = new mb.CdpClient();
+    await client.connect(wsUrl);
+    const { sessionId } = await client.send('Target.attachToTarget', { targetId: target.id, flatten: true });
+    await Promise.all([
+      client.send('Page.enable', {}, sessionId),
+      client.send('Runtime.enable', {}, sessionId),
+      client.send('Network.enable', {}, sessionId),
+    ]);
+    return createMonobrowsePage(mb, client, sessionId, target.id, launchedPort);
+  }
+
+  return {
+    driverName: 'monobrowse',
+    newPage: openPage,
+    async close() {
+      try {
+        if (typeof mb.closeBrowser === 'function') {
+          // Newer monobrowse: graceful Browser.close with PID-kill fallback.
+          await mb.closeBrowser(control.client, launchedPort);
+        } else {
+          // Published 1.0.3 has no closeBrowser export — send the CDP
+          // Browser.close command directly (best effort, short timeout).
+          await withTimeout(control.client.send('Browser.close', {}), 3000, 'Browser.close').catch(() => {});
+        }
+        // Browser.close is acknowledged before Chrome has actually exited. A
+        // following detection run on a forced port can otherwise attach to the
+        // shutting-down process and fail creating its first target. Do not
+        // expose close() as complete until that CDP listener is gone.
+        await waitForCdpPortRelease(launchedPort);
+      } finally {
+        control.client.close();
+        // Best effort, twice: Chrome is still flushing profile data when the
+        // port comes back, so an immediate delete gets a few files recreated
+        // under it. The unref'd retry lands after that (same pattern as
+        // monobrowse's own post-close force-kill net) and never holds the
+        // process open. Whatever still survives is a few KB under tmpdir that
+        // nothing reuses, so neither attempt may fail close().
+        removeProfileDir(userDataDir);
+        setTimeout(() => removeProfileDir(userDataDir), PROFILE_CLEANUP_RETRY_MS).unref?.();
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// puppeteer driver (original behavior, kept as fallback)
+// ---------------------------------------------------------------------------
+
+function wrapPuppeteerBrowser(browser) {
+  return {
+    driverName: 'puppeteer',
+    raw: browser,
+    newPage: () => browser.newPage(),
+    close: () => browser.close(),
+  };
+}
+
+async function launchPuppeteerBrowser(options = {}) {
+  let puppeteer;
+  try {
+    puppeteer = await import('puppeteer');
+  } catch {
+    throw new Error('puppeteer is required for URL scanning. Install: npm install puppeteer');
+  }
+  // CI runners (GitHub Actions Ubuntu) block unprivileged user namespaces, so
+  // Chrome can't initialize its sandbox there. Disable the sandbox only when
+  // running in CI; local users keep the default hardened launch.
+  const launchArgs = options.launchArgs || (process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : []);
+  const browser = await puppeteer.default.launch({
+    headless: options.headless ?? true,
+    args: launchArgs,
+  });
+  return wrapPuppeteerBrowser(browser);
+}
+
+// ---------------------------------------------------------------------------
+// Selection
+// ---------------------------------------------------------------------------
+
+/** Accepts either a driver browser handle or a raw puppeteer Browser. */
+function normalizeBrowserHandle(browser) {
+  if (!browser) return null;
+  if (browser.driverName && typeof browser.newPage === 'function') return browser;
+  if (typeof browser.newPage === 'function') return wrapPuppeteerBrowser(browser);
+  throw new Error('Unsupported browser handle passed to detectUrl (expected a driver handle or puppeteer Browser)');
+}
+
+async function launchDetectionBrowser(options = {}) {
+  const forced = (process.env[DRIVER_ENV] || '').trim().toLowerCase();
+  if (forced && forced !== 'monobrowse' && forced !== 'puppeteer') {
+    throw new Error(`Invalid ${DRIVER_ENV}=${forced} (expected "monobrowse" or "puppeteer")`);
+  }
+  const order = forced ? [forced] : ['monobrowse', 'puppeteer'];
+  const errors = [];
+  for (const name of order) {
+    try {
+      return name === 'monobrowse'
+        ? await launchMonobrowseBrowser(options)
+        : await launchPuppeteerBrowser(options);
+    } catch (error) {
+      errors.push(`${name}: ${error?.message || error}`);
+    }
+  }
+  throw new Error(
+    'A browser is required for URL scanning and no driver could start one ' +
+    `(${errors.join(' | ')}). ` +
+    'Install Google Chrome/Chromium/Edge for the native @monoes/monobrowse driver, ' +
+    'or puppeteer is required for URL scanning. Install: npm install puppeteer'
+  );
+}
+
+export {
+  launchDetectionBrowser,
+  launchMonobrowseBrowser,
+  launchPuppeteerBrowser,
+  normalizeBrowserHandle,
+  wrapPuppeteerBrowser,
+};