@jxsuite/import 0.39.8 → 0.40.1

package/README.md

@@ -25,9 +25,35 @@ jx-import <url> [options]
   --ai-components          Use an LLM to refine component names and props
   --ai-model <model>       Model for AI componentization (default: gpt-4o-mini)
   --verify                 After import, build and screenshot-diff vs the original
-  --verify-threshold <n>   Pixel diff threshold 0..1 (default: 0.15)
+  --min-fidelity <n>       Fail (exit 1) below this average fidelity 0..100 (default: 25)
+  --verify-threshold <n>   Per-pixel colour tolerance 0..1 for the diff (default: 0.15)
+  --verify-viewport-only   Diff only the first viewport instead of the whole page
 ```
 
+### What `--verify` can fail on
+
+`--verify` builds the emitted project, serves it, screenshots every page and pixel-diffs each
+against a reference captured during the import. The run exits non-zero when any of three things is
+true: the project did not build cleanly, a page could not be rendered, or the average fidelity is
+below `--min-fidelity`.
+
+`--verify-threshold` is **not** that bar. It is pixelmatch's per-pixel colour tolerance: it decides
+when two pixels count as the same colour, so it moves the score without ever deciding the outcome.
+`--min-fidelity` is the bar, and it defaults to a deliberately low `25`, a floor for "this is not a
+clone of anything" rather than a quality target. A faithful import of a complicated site still
+lands well under 100 for reasons no importer can fix (a rotating hero, a font rendering a hair
+differently).
+
+`verify/report.json` carries the whole picture: per-page fidelity, the console errors and failed or
+404'd requests each rendered page produced, and any build errors. When a page scores badly, read
+`failedRequests` first, because a percentage cannot tell you that fifteen images 404'd and that
+list can.
+
+**Comparing two runs.** The reference screenshot is captured fresh each time, so two runs of the
+same URL are not directly comparable. On a site with a rotating hero the spread across identical
+runs has been measured at around 4 points, which is wide enough to hide a small regression. Compare
+a fidelity number against another run of the same code, not against one from a different session.
+
 Environment: `CHROME_PATH` (explicit browser binary; otherwise `google-chrome-stable`,
 `google-chrome`, `chromium-browser`, or `chromium` is discovered on PATH), `OPENAI_API_KEY` and
 `OPENAI_BASE_URL` for `--ai-components`.
@@ -52,7 +78,8 @@ const result = await importSite(
 ```
 
 Lower-level building blocks (capture, style diffing, crawling, layout detection, componentization,
-emit, verify) are exported from the package root — see `src/index.ts`.
+emit, verify) are exported from the package root; `./capture`, `./to-jx`, `./emit`, `./run` and
+`./verify` are also addressable as subpaths. See `src/index.ts`.
 
 Verification (`verify` option / `--verify`) additionally needs `@jxsuite/compiler` (an optional
 dependency) to build the emitted project before screenshot-diffing it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/import",
-  "version": "0.39.8",
+  "version": "0.40.1",
   "description": "Clone a live website into a Jx project",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,11 @@
     "./capture": "./src/capture.ts",
     "./to-jx": "./src/to-jx.ts",
     "./emit": "./src/emit.ts",
-    "./run": "./src/run.ts"
+    "./io": "./src/io.ts",
+    "./pipeline": "./src/pipeline.ts",
+    "./run": "./src/run.ts",
+    "./verify": "./src/verify.ts",
+    "./breakpoint-plan": "./src/breakpoint-plan.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -31,8 +35,8 @@
     "import": "bun run src/cli.ts"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.7",
-    "@jxsuite/schema": "^1.9.0",
+    "@jxsuite/markup": "^0.4.9",
+    "@jxsuite/schema": "^2.1.0",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "puppeteer-core": "^24.9.0"
@@ -42,6 +46,6 @@
     "happy-dom": "^20.10.6"
   },
   "optionalDependencies": {
-    "@jxsuite/compiler": "^2.0.8"
+    "@jxsuite/compiler": "^3.1.0"
   }
 }

package/src/ai-componentize.ts

@@ -15,7 +15,17 @@ import type { ExtractedComponent, ComponentizeResult } from "./componentize.ts";
 export interface AiComponentizeOptions {
   apiKey: string;
   baseUrl?: string | undefined;
-  model?: string | undefined;
+  /**
+   * The model id, and it has no default on purpose.
+   *
+   * `"gpt-4o-mini"` used to be one, which was harmless while the only caller was the OSS CLI
+   * pointing at OpenAI and wrong the moment a backend brokered anything else: Workers AI answers a
+   * model it does not know with a 404, `callLlm` reads that as "the LLM failed", and every
+   * component silently keeps its heuristic `component-div-0` name. A required id makes the caller
+   * that knows which provider it is talking to say so. The CLI and the OSS server still default to
+   * `gpt-4o-mini` — at their own call site, in `run.ts`.
+   */
+  model: string;
 }
 
 interface RenameResult {
@@ -58,7 +68,7 @@ Respond with ONLY the JSON object, no markdown fences or explanation.`;
 
 async function callLlm(prompt: string, opts: AiComponentizeOptions): Promise<RenameResult | null> {
   const baseUrl = opts.baseUrl || "https://api.openai.com/v1";
-  const model = opts.model || "gpt-4o-mini";
+  const { model } = opts;
 
   const response = await fetch(`${baseUrl}/chat/completions`, {
     method: "POST",

package/src/asset-collect.ts

@@ -5,7 +5,8 @@
  * SVGs are kept as-is (no download needed). Returns absolute URLs for downloading.
  */
 
-import type { Page } from "puppeteer-core";
+import type { ImportPage } from "./capture.ts";
+import { SRCSET_SEPARATOR } from "./srcset.ts";
 
 export interface DiscoveredAsset {
   /** Absolute URL of the asset. */
@@ -45,8 +46,13 @@ export interface AssetCollectionResult {
  * Collect all asset URLs from the live page DOM and stylesheets. Runs entirely in-browser via
  * page.evaluate() — no per-element round-trips.
  */
-export async function collectAssets(page: Page): Promise<AssetCollectionResult> {
-  const result = await page.evaluate(() => {
+export async function collectAssets(page: ImportPage): Promise<AssetCollectionResult> {
+  /*
+   * The separator crosses into the page as a SOURCE STRING: an evaluated body is serialised and
+   * re-parsed in the browser, so it cannot close over a value declared out here.
+   */
+  const result = await page.evaluate((srcsetSeparator: string) => {
+    const separator = new RegExp(srcsetSeparator);
     const assets: { url: string; source: string }[] = [];
     const seen = new Set<string>();
     let inlineSvgCount = 0;
@@ -73,7 +79,7 @@ export async function collectAssets(page: Page): Promise<AssetCollectionResult>
 
     function parseSrcset(srcset: string): string[] {
       return srcset
-        .split(",")
+        .split(separator)
         .map((entry) => entry.trim().split(/\s+/)[0] ?? "")
         .filter(Boolean);
     }
@@ -193,7 +199,7 @@ export async function collectAssets(page: Page): Promise<AssetCollectionResult>
       inlineSvgCount: number;
       stylesheets: { href: string | null; cssText: string | null; fontFaceRules: string[] }[];
     };
-  });
+  }, SRCSET_SEPARATOR.source);
 
   // R2: For cross-origin sheets we couldn't access (cssText=null, has href), fetch them
   // In-browser to get @font-face rules (e.g. Google Fonts loaded via <link>)

package/src/asset-download.ts

@@ -5,14 +5,15 @@
  * subdirectories by type: images/, fonts/, icons/.
  */
 
-import { join, extname } from "node:path";
-import { mkdir } from "node:fs/promises";
+import { extname } from "node:path";
 import type { DiscoveredAsset } from "./asset-collect.ts";
+import type { ImportIo } from "./io.ts";
 
 export interface DownloadResult {
   /**
-   * Maps original absolute URL → relative path from project root (e.g.
-   * "public/assets/images/hero.jpg").
+   * Maps the original absolute URL to the site-absolute path the built asset is served from (e.g.
+   * "/assets/images/hero.jpg") — NOT the path it is written to on disk, which keeps the public/
+   * prefix the compiler copies from.
    */
   rewriteMap: Map<string, string>;
   /** URLs that failed to download. */
@@ -126,7 +127,7 @@ function isBlocked(url: string): boolean {
 
 export async function downloadAssets(
   assets: DiscoveredAsset[],
-  outDir: string,
+  io: ImportIo,
   sourceUrl?: string,
 ): Promise<DownloadResult> {
   const rewriteMap = new Map<string, string>();
@@ -142,12 +143,11 @@ export async function downloadAssets(
     }
   }
 
-  // Create subdirectories
-  const assetsDir = join(outDir, "public", "assets");
-  await mkdir(join(assetsDir, "images"), { recursive: true });
-  await mkdir(join(assetsDir, "fonts"), { recursive: true });
-  await mkdir(join(assetsDir, "icons"), { recursive: true });
-  await mkdir(join(assetsDir, "other"), { recursive: true });
+  // Create subdirectories (a sink with no directories declines — see ImportIo.mkdir)
+  const assetsDir = "public/assets";
+  for (const subdir of ["images", "fonts", "icons", "other"]) {
+    await io.mkdir?.(`${assetsDir}/${subdir}`);
+  }
 
   // Track filenames to avoid collisions
   const usedNames = new Map<string, number>();
@@ -171,8 +171,12 @@ export async function downloadAssets(
     }
     usedNames.set(nameKey, count + 1);
 
-    const destPath = join(assetsDir, subdir, filename);
-    const relativePath = `public/assets/${subdir}/${filename}`;
+    const destPath = `${assetsDir}/${subdir}/${filename}`;
+    // The site-absolute path the built asset is served from. `public/` is the compiler's static
+    // ROOT — its contents land at dist/<path>, so the "public/" segment must not survive into a
+    // Reference, and the leading slash must be there or a reference from /components/x.js or a
+    // Nested route resolves against the wrong base.
+    const relativePath = `/assets/${subdir}/${filename}`;
 
     try {
       const headers: Record<string, string> = {
@@ -190,7 +194,7 @@ export async function downloadAssets(
 
       const buffer = await response.arrayBuffer();
       totalBytes += buffer.byteLength;
-      await Bun.write(destPath, buffer);
+      await io.write(destPath, new Uint8Array(buffer));
       rewriteMap.set(url, relativePath);
     } catch {
       failed.push(url);

package/src/asset-rewrite.ts

@@ -6,6 +6,7 @@
  */
 
 import type { JxElement, JxStyle } from "@jxsuite/schema/types";
+import { SRCSET_SEPARATOR } from "./srcset.ts";
 
 /** Rewrite all asset URLs in a Jx tree in-place. Returns the count of rewrites performed. */
 export function rewriteAssetUrls(
@@ -46,9 +47,14 @@ export function rewriteAssetUrls(
     return null;
   }
 
+  /*
+   * Split by the same rule the collector downloads by (`SRCSET_SEPARATOR`). If the two disagreed,
+   * the importer would fetch one set of URLs and rewrite another — the attribute would be
+   * reassembled around fragments nothing had downloaded.
+   */
   function rewriteSrcset(srcset: string): string {
     return srcset
-      .split(",")
+      .split(SRCSET_SEPARATOR)
       .map((entry) => {
         const parts = entry.trim().split(/\s+/);
         const [url = ""] = parts;

package/src/breakpoint-plan.ts

@@ -0,0 +1,297 @@
+/**
+ * Decide which of a site's breakpoints the imported project gets.
+ *
+ * A real site declares breakpoints the way it grew: one framework's four, a theme's three, a
+ * plugin's two, a hand-written pair for one component. Taken literally that is what the importer
+ * used to emit — nine `$media` entries, unsorted, named `--767` and `--1025`, each one a canvas
+ * size in Studio and a column in every style editor. Nobody authors against nine breakpoints, and
+ * nobody asked for these nine.
+ *
+ * So the widths a site DECLARES and the widths a project KEEPS are two different questions, and
+ * this module is the second one. It is pure — no browser, no page, no capture — because the
+ * decision has to be made BEFORE the re-capture pass: each kept breakpoint costs a viewport change
+ * and a full style walk, so planning first is what makes a limited import faster rather than merely
+ * tidier.
+ *
+ * Nothing is thrown away silently. Every discovered width that is not kept is FOLDED into the kept
+ * one nearest it under the caller's rounding rule, so the styles that width carried still reach the
+ * project — at the breakpoint the project actually has.
+ *
+ * @docs studio/design/breakpoints
+ */
+
+/** One breakpoint: what to call it, what to emit, and the viewport width to sample it at. */
+export interface Breakpoint {
+  /** Jx breakpoint name, e.g. `--768`. */
+  name: string;
+  /** The CSS media query to write into `project.json`'s `$media`, e.g. `(max-width: 768px)`. */
+  query: string;
+  /**
+   * The viewport width to re-capture styles at.
+   *
+   * Usually the query's own width, and deliberately NOT so under an explicit override: the styles
+   * flip at the width the SITE declared, so that is where they must be sampled, even when the
+   * project is going to call the breakpoint something else.
+   */
+  testWidth: number;
+}
+
+/** How a requested width is matched against the widths a site actually declares. */
+export type BreakpointRounding = "nearest" | "down" | "up";
+
+/**
+ * What to do with the widths a capture discovered.
+ *
+ * - `all` — keep every one, sorted. What the importer did before there was a choice.
+ * - `limit` — keep `count` of them, evenly spaced across the discovered range (3 → the narrowest, the
+ *   middle one, and the widest). The default, because "too many breakpoints" is the complaint this
+ *   exists to answer.
+ * - `explicit` — keep the widths the author named, each backed by the declared width nearest it.
+ */
+export type BreakpointPolicy =
+  | { mode: "all" }
+  | { mode: "limit"; count: number; rounding: BreakpointRounding }
+  | { mode: "explicit"; widths: number[]; rounding: BreakpointRounding };
+
+/** What a new import gets when nobody says otherwise. */
+export const DEFAULT_BREAKPOINT_POLICY: BreakpointPolicy = {
+  count: 3,
+  mode: "limit",
+  rounding: "nearest",
+};
+
+/** The most breakpoints a project may be asked to keep. Past this, "limit" is not limiting. */
+export const MAX_BREAKPOINTS = 12;
+
+/** The viewport widths an override may name. Outside this a "width" is a typo, not a breakpoint. */
+export const MIN_BREAKPOINT_WIDTH = 120;
+export const MAX_BREAKPOINT_WIDTH = 4000;
+
+export interface BreakpointPlanResult {
+  /** The breakpoints to capture and emit, ascending by `testWidth`. */
+  keep: Breakpoint[];
+  /**
+   * Discovered breakpoint name → the kept breakpoint name its style deltas merge into.
+   *
+   * A kept breakpoint maps to itself, so a caller can look up every discovered name without a
+   * fallback branch.
+   */
+  fold: Map<string, string>;
+}
+
+/**
+ * Parse a media query into a pixel width, or null when it is not a simple one-clause width query.
+ *
+ * Anchored and `px`-only on purpose: `(min-width: 48rem)` has no pixel width without a root font
+ * size, and `(min-width:768px) and (max-width:1024px)` names a band rather than a threshold. Both
+ * are real and both are refused here rather than guessed at — {@link skippedWidthQueries} is how the
+ * import reports what it could not read.
+ *
+ * @param {string} query - A media query's condition text
+ * @returns {{ type: "min" | "max"; width: number } | null}
+ */
+export function parseWidthQuery(query: string): { type: "min" | "max"; width: number } | null {
+  const minMatch = query.match(/^\s*\(\s*min-width\s*:\s*([\d.]+)px\s*\)\s*$/);
+  if (minMatch) {
+    return { type: "min", width: Number(minMatch[1]) };
+  }
+  const maxMatch = query.match(/^\s*\(\s*max-width\s*:\s*([\d.]+)px\s*\)\s*$/);
+  if (maxMatch) {
+    return { type: "max", width: Number(maxMatch[1]) };
+  }
+  return null;
+}
+
+/** The Jx breakpoint name for a width, e.g. `768` → `--768`. */
+export function breakpointName(width: number): string {
+  return `--${width}`;
+}
+
+/**
+ * Analyze discovered `@media` queries and produce a set of testable breakpoints. Only simple
+ * one-clause `min-width` / `max-width` queries in `px` are readable as a breakpoint;
+ * {@link skippedWidthQueries} names the rest, so an import can say what it could not use instead of
+ * dropping it in silence.
+ *
+ * @param {readonly string[]} queries
+ * @returns {Breakpoint[]} Ascending by width, deduplicated
+ */
+export function analyzeMediaQueries(queries: readonly string[]): Breakpoint[] {
+  const seen = new Set<number>();
+  const breakpoints: Breakpoint[] = [];
+
+  for (const query of queries) {
+    const parsed = parseWidthQuery(query);
+    if (!parsed || seen.has(parsed.width)) {
+      continue;
+    }
+    seen.add(parsed.width);
+
+    // Both directions are tested AT the declared width: for max-width it is the upper bound of the
+    // Narrow rules, for min-width it is where the wide rules start applying.
+    breakpoints.push({ name: breakpointName(parsed.width), query, testWidth: parsed.width });
+  }
+
+  breakpoints.sort((a, b) => a.testWidth - b.testWidth);
+  return breakpoints;
+}
+
+/**
+ * The width-ish queries {@link analyzeMediaQueries} could not read — a compound condition, a `rem`
+ * threshold, a range syntax. A query with no width in it at all (`prefers-color-scheme`, `hover`,
+ * `print`) is not listed: it is not a breakpoint and its absence is not a loss.
+ *
+ * @param {readonly string[]} queries
+ * @returns {string[]}
+ */
+export function skippedWidthQueries(queries: readonly string[]): string[] {
+  const skipped: string[] = [];
+  for (const query of queries) {
+    if (parseWidthQuery(query)) {
+      continue;
+    }
+    if (/\bwidth\b/i.test(query)) {
+      skipped.push(query);
+    }
+  }
+  return [...new Set(skipped)];
+}
+
+/**
+ * The candidate nearest `target` under `rounding`.
+ *
+ * Each rule falls back to the nearest end of the range rather than to nothing: a `down` request
+ * below every candidate still has an answer, and returning null there would silently drop a width
+ * the author explicitly asked for.
+ *
+ * @param {readonly number[]} candidates - Ascending, non-empty
+ * @param {number} target
+ * @param {BreakpointRounding} rounding
+ * @returns {number}
+ */
+function pickNearest(
+  candidates: readonly number[],
+  target: number,
+  rounding: BreakpointRounding,
+): number {
+  if (rounding === "down") {
+    let best = candidates[0]!;
+    for (const width of candidates) {
+      if (width <= target) {
+        best = width;
+      }
+    }
+    return best;
+  }
+  if (rounding === "up") {
+    for (const width of candidates) {
+      if (width >= target) {
+        return width;
+      }
+    }
+    return candidates.at(-1)!;
+  }
+  // Nearest, ties to the narrower width — deterministic, and the narrower styles are the ones a
+  // Reader is more likely to have meant when two are equidistant.
+  let best = candidates[0]!;
+  let bestDelta = Math.abs(best - target);
+  for (const width of candidates) {
+    const delta = Math.abs(width - target);
+    if (delta < bestDelta) {
+      best = width;
+      bestDelta = delta;
+    }
+  }
+  return best;
+}
+
+/**
+ * `count` indices evenly spaced across `[0, length - 1]`, both ends included.
+ *
+ * A single breakpoint takes the MEDIAN rather than the narrowest: asked for one, an author wants
+ * the width the site's layout actually turns at, and the narrowest is usually a phone edge case.
+ */
+function evenIndices(length: number, count: number): number[] {
+  if (count >= length) {
+    return [...Array.from({ length }).keys()];
+  }
+  if (count === 1) {
+    return [Math.floor((length - 1) / 2)];
+  }
+  const out: number[] = [];
+  for (let i = 0; i < count; i += 1) {
+    out.push(Math.round((i * (length - 1)) / (count - 1)));
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * Choose the breakpoints an import keeps, and where the rest of them go.
+ *
+ * @param {readonly Breakpoint[]} discovered - Everything the capture found, in any order
+ * @param {BreakpointPolicy} policy
+ * @returns {BreakpointPlanResult}
+ */
+export function planBreakpoints(
+  discovered: readonly Breakpoint[],
+  policy: BreakpointPolicy = DEFAULT_BREAKPOINT_POLICY,
+): BreakpointPlanResult {
+  const sorted = discovered.toSorted((a, b) => a.testWidth - b.testWidth);
+  if (sorted.length === 0) {
+    return { fold: new Map(), keep: [] };
+  }
+
+  const widths = sorted.map((bp) => bp.testWidth);
+  const byWidth = new Map(sorted.map((bp) => [bp.testWidth, bp]));
+
+  const keep: Breakpoint[] = [];
+  if (policy.mode === "all") {
+    keep.push(...sorted);
+  } else if (policy.mode === "limit") {
+    const count = Math.max(1, Math.min(MAX_BREAKPOINTS, Math.trunc(policy.count) || 1));
+    for (const index of evenIndices(sorted.length, count)) {
+      keep.push(sorted[index]!);
+    }
+  } else {
+    /* An override names the widths the PROJECT will have; each is backed by the declared width
+       nearest it, because that is where the site's own rules actually change. Two overrides that
+       land on the same declared width collapse into one — emitting the same styles twice under two
+       names would be two canvases showing the same thing. */
+    const requested = [...new Set(policy.widths.map((w) => Math.trunc(w)))]
+      .filter((w) => w >= MIN_BREAKPOINT_WIDTH && w <= MAX_BREAKPOINT_WIDTH)
+      .toSorted((a, b) => a - b)
+      .slice(0, MAX_BREAKPOINTS);
+    const claimed = new Set<number>();
+    for (const target of requested) {
+      const backing = pickNearest(widths, target, policy.rounding);
+      if (claimed.has(backing)) {
+        continue;
+      }
+      claimed.add(backing);
+      const source = byWidth.get(backing)!;
+      const parsed = parseWidthQuery(source.query);
+      keep.push({
+        name: breakpointName(target),
+        query: parsed ? `(${parsed.type}-width: ${target}px)` : source.query,
+        testWidth: backing,
+      });
+    }
+    keep.splice(0, keep.length, ...keep.toSorted((a, b) => a.testWidth - b.testWidth));
+  }
+
+  const fold = new Map<string, string>();
+  if (keep.length === 0) {
+    return { fold, keep };
+  }
+
+  const keptWidths = keep.map((bp) => bp.testWidth);
+  const keptByWidth = new Map(keep.map((bp) => [bp.testWidth, bp]));
+  const rounding = policy.mode === "all" ? "nearest" : policy.rounding;
+  for (const bp of sorted) {
+    const target =
+      keptByWidth.get(bp.testWidth) ??
+      keptByWidth.get(pickNearest(keptWidths, bp.testWidth, rounding))!;
+    fold.set(bp.name, target.name);
+  }
+  return { fold, keep };
+}

package/src/browser-local.ts

@@ -0,0 +1,67 @@
+/**
+ * Launching a real Chrome on this machine — the one module in the import that loads
+ * `puppeteer-core` as a VALUE.
+ *
+ * It is separate from `capture.ts` for a bundling reason rather than a tidiness one.
+ * `puppeteer-core` cannot run in workerd at all (it reaches for `child_process`, `net` and a binary
+ * on disk), and a Worker bundler follows value imports transitively — so a single `import { launch
+ * }` anywhere in `pipeline.ts`'s graph would pull the whole of it in and fail the deploy. Keeping
+ * the launch here, and having every phase take a browser it was HANDED, is what lets Jx Cloud run
+ * the same pipeline against a `@cloudflare/puppeteer` session.
+ */
+
+import { launch } from "puppeteer-core";
+import type { Browser } from "puppeteer-core";
+
+const DEFAULT_CHROME_PATHS = [
+  "google-chrome-stable",
+  "google-chrome",
+  "chromium-browser",
+  "chromium",
+];
+
+function findChrome(executablePath?: string): string {
+  if (executablePath) {
+    return executablePath;
+  }
+  const env = process.env.CHROME_PATH;
+  if (env) {
+    return env;
+  }
+
+  for (const name of DEFAULT_CHROME_PATHS) {
+    const path = Bun.which(name);
+    if (path) {
+      return path;
+    }
+  }
+  throw new Error(
+    "Could not find Chrome/Chromium. Set CHROME_PATH or install google-chrome-stable.",
+  );
+}
+
+let _browser: Browser | null = null;
+
+export interface LaunchOptions {
+  /** Explicit browser binary. Wins over CHROME_PATH and PATH discovery. */
+  executablePath?: string;
+}
+
+export async function launchBrowser(options?: LaunchOptions): Promise<Browser> {
+  if (_browser?.connected) {
+    return _browser;
+  }
+  _browser = await launch({
+    executablePath: findChrome(options?.executablePath),
+    headless: true,
+    args: ["--no-sandbox", "--disable-gpu"],
+  });
+  return _browser;
+}
+
+export async function closeBrowser(): Promise<void> {
+  if (_browser?.connected) {
+    await _browser.close();
+    _browser = null;
+  }
+}