@monoes/monomindcli 2.15.5 → 2.15.7

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

@@ -1,50 +0,0 @@
-#!/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

@@ -1,259 +0,0 @@
-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

@@ -1,349 +0,0 @@
-//
-// 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;
-
-// Ports we launch headless Chrome on for detection runs. Deliberately away
-// from 9222 (the default `monomind browse` port): we must never attach to a
-// browser we did not launch, because browser.close() issues Browser.close.
-const MONOBROWSE_PORT_MIN = 9520;
-const MONOBROWSE_PORT_RANGE = 380;
-
-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'] : []);
-
-  const forcedPort = Number(process.env.MONODESIGN_MONOBROWSE_PORT);
-  let port = null;
-  if (Number.isInteger(forcedPort) && forcedPort > 0) {
-    port = forcedPort;
-  } else {
-    // Pick a free-looking port; skip ports where a CDP endpoint already
-    // listens so we never take over (and later Browser.close) someone
-    // else's browser session.
-    for (let attempt = 0; attempt < 5 && port === null; attempt++) {
-      const candidate = MONOBROWSE_PORT_MIN + Math.floor(Math.random() * MONOBROWSE_PORT_RANGE);
-      if (!(await mb.isPortOpen(candidate))) port = candidate;
-    }
-    if (port === null) throw new Error('Could not find a free CDP port for monobrowse');
-  }
-
-  // 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,
-};