@jxsuite/import 0.39.8 → 0.40.1

package/src/run.ts

@@ -1,27 +1,24 @@
 /**
- * Programmatic import pipeline — the orchestrator behind both the jx-import CLI and the Studio
- * import endpoint. Runs the same phase sequence as the CLI (capture → styles → assets →
- * componentize → emit → verify), reporting progress through a callback instead of the console.
+ * The local import — the orchestrator behind both the jx-import CLI and the Studio import endpoint.
+ *
+ * Everything portable moved to `pipeline.ts`. What is left is what only a machine with a disk and a
+ * Chrome can do: the empty-directory guard, the `project.json` seed, the local write sink, the
+ * browser launch, and the verify phase (which builds the project with `@jxsuite/compiler` and
+ * serves it over `Bun.serve` to screenshot it — a hosted platform never executes a project's own
+ * JavaScript, so verification does not follow the pipeline anywhere).
  */
 
 import { existsSync, readdirSync } from "node:fs";
-import { isAbsolute } from "node:path";
-import { capturePage, closeBrowser, launchBrowser } from "./capture.ts";
-import { convertToJx } from "./to-jx.ts";
-import { emitMultiPageProject } from "./emit.ts";
-import { captureStyles } from "./style-capture.ts";
-import { diffAllStyles, kebabToCamel } from "./style-diff.ts";
-import { extractMedia } from "./media-extract.ts";
-import { applyStylesToTree } from "./apply-styles.ts";
-import { collectAssets } from "./asset-collect.ts";
-import { downloadAssets } from "./asset-download.ts";
-import { rewriteAssetUrls } from "./asset-rewrite.ts";
-import { applyTokens } from "./css-tokens.ts";
-import { crawlSite } from "./crawl.ts";
-import { detectLayout } from "./layout-detect.ts";
+import { isAbsolute, join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import { closeBrowser, launchBrowser } from "./browser-local.ts";
+import { createLocalIo } from "./io.ts";
+import { runImportPipeline } from "./pipeline.ts";
+import type { BreakpointPolicy } from "./breakpoint-plan.ts";
+import type { ImportPhase, ImportProgressEvent } from "./pipeline.ts";
 import type { Browser } from "puppeteer-core";
-import type { JxElement } from "@jxsuite/schema/types";
-import type { ComponentizeResult } from "./componentize.ts";
+
+export type { ImportPhase, ImportProgressEvent } from "./pipeline.ts";
 
 export interface ImportSiteOptions {
   /** The page to import; must be http(s). */
@@ -34,6 +31,14 @@ export interface ImportSiteOptions {
   maxPages?: number;
   /** Skip styles/assets for pages above this node count (default 5000). */
   maxNodesPerPage?: number;
+  /**
+   * Which of the site's declared breakpoints the project keeps (default: three, evenly spaced).
+   *
+   * A real site declares as many breakpoints as it has accumulated frameworks; nine `$media`
+   * entries is nine canvas sizes in Studio and nine columns in every style editor, and nobody
+   * authors against that. See `breakpoint-plan.ts`.
+   */
+  breakpoints?: BreakpointPolicy;
   /** Capture computed styles (default true). */
   styles?: boolean;
   /** Download and rewrite assets (default true). */
@@ -46,87 +51,77 @@ export interface ImportSiteOptions {
   componentize?: false | { minInstances?: number; minDepth?: number };
   /** LLM refinement of component/prop names; false/undefined to skip. */
   ai?: false | { apiKey: string; baseUrl?: string | undefined; model?: string | undefined };
-  /** Build + screenshot-diff the emitted project against the original; false to skip. */
-  verify?: false | { threshold?: number };
+  /**
+   * Build + screenshot-diff the emitted project against the original; false to skip.
+   *
+   * `threshold` is pixelmatch's per-pixel COLOUR tolerance, not a bar; `minFidelity` is the bar,
+   * and the run reports `passed` against it. `fullPage` compares the whole scrollable page (default
+   * true) rather than the first viewport.
+   */
+  verify?: false | { threshold?: number; minFidelity?: number; fullPage?: boolean | undefined };
   /** Explicit browser binary (wins over CHROME_PATH and PATH discovery). */
   chromePath?: string;
   /** Aborts between phases (and between crawled pages). */
   signal?: AbortSignal;
 }
 
-export type ImportPhase =
-  | "launch"
-  | "capture"
-  | "crawl"
-  | "styles"
-  | "assets"
-  | "layout"
-  | "components"
-  | "ai"
-  | "emit"
-  | "verify"
-  | "done";
-
-export interface ImportProgressEvent {
-  phase: ImportPhase;
-  message: string;
-  current?: number;
-  total?: number;
-}
-
 export interface ImportSiteResult {
   outDir: string;
   pages: { route: string; title: string; nodeCount: number }[];
   fileCount: number;
-  verify: { averageFidelity: number; reportDir: string } | null;
+  verify: {
+    averageFidelity: number;
+    reportDir: string;
+    /**
+     * Whether the run met its bar — it built cleanly, every page rendered, and the average reached
+     * `minFidelity`. Nothing about verify could fail before this existed: a clone scoring 8%
+     * finished exactly like one scoring 95% (issue #232).
+     */
+    passed: boolean;
+    /** The bar `passed` was measured against. */
+    minFidelity: number;
+    /** Errors the compiler reported building the project — recorded, and now also enforced. */
+    buildErrors: string[];
+    /**
+     * Per page, because the average cannot name one.
+     *
+     * "Average fidelity 84%" is a fact nobody can act on; "the pricing page renders at 61%" is a
+     * decision — retry it, patch it by hand, or accept it. The verifier computed both and only the
+     * average was reported, so the actionable half was thrown away one level below the caller.
+     *
+     * The counts alongside it are what a percentage cannot say: a page that 404s on fifteen images
+     * scores badly, and only `failedRequests` says why.
+     */
+    pages: {
+      route: string;
+      fidelity: number;
+      consoleErrors: number;
+      failedRequests: number;
+      error?: string;
+    }[];
+  } | null;
   warnings: string[];
 }
 
-function throwIfAborted(signal?: AbortSignal): void {
-  if (signal?.aborted) {
-    throw new Error("Import aborted");
-  }
-}
-
-function formatBytes(bytes: number): string {
-  if (bytes < 1024) {
-    return `${bytes} B`;
-  }
-  if (bytes < 1024 * 1024) {
-    return `${(bytes / 1024).toFixed(1)} KB`;
-  }
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
-
 /**
- * Run the heuristic componentize pass and refine it with the LLM. Returns undefined when the AI
- * pass is off, componentization is disabled, or the heuristic found nothing (the emit step then
- * runs its own heuristic pass as usual).
+ * What the CLI and the OSS server ask for when the caller named no model.
+ *
+ * It lives at the call site rather than inside `ai-componentize.ts`, because a default belongs to
+ * whoever knows the provider. This path talks to an OpenAI-compatible endpoint; a backend brokering
+ * Workers AI would 404 on this id, which is exactly why the module below it demands one.
  */
-async function maybeAiComponentize(
-  pageMap: Map<string, JxElement>,
-  componentizeOptions: false | { minInstances?: number; minDepth?: number },
-  ai: ImportSiteOptions["ai"],
-  progress: (phase: ImportPhase, message: string) => void,
-): Promise<ComponentizeResult | undefined> {
-  if (!ai || componentizeOptions === false) {
-    return undefined;
-  }
-  const { componentize } = await import("./componentize.ts");
-  const { aiComponentize } = await import("./ai-componentize.ts");
-  progress("components", "Running heuristic componentization...");
-  const heuristic = componentize(pageMap, componentizeOptions);
-  if (heuristic.components.size === 0) {
-    return undefined;
+const DEFAULT_AI_MODEL = "gpt-4o-mini";
+
+/** The one file the seed writes, and the only thing the empty-directory guard tolerates. */
+const PROJECT_FILE = "project.json";
+
+/** A placeholder project name from the URL, replaced by the page title at emit. */
+function seedName(url: string): string {
+  try {
+    return new URL(url).hostname.replace(/^www\./, "") || "Imported Site";
+  } catch {
+    return "Imported Site";
   }
-  progress("ai", `Found ${heuristic.components.size} component(s), refining with AI...`);
-  const refined = await aiComponentize(
-    heuristic,
-    { apiKey: ai.apiKey, baseUrl: ai.baseUrl, model: ai.model },
-    (msg) => progress("ai", msg),
-  );
-  progress("ai", `AI refined ${refined.components.size} component(s)`);
-  return refined;
 }
 
 /**
@@ -139,22 +134,7 @@ export async function importSite(
   options: ImportSiteOptions,
   onProgress?: (e: ImportProgressEvent) => void,
 ): Promise<ImportSiteResult> {
-  const {
-    url,
-    outDir,
-    maxDepth = 2,
-    maxPages = 25,
-    maxNodesPerPage = 5000,
-    styles = true,
-    assets = true,
-    scroll = true,
-    respectRobots = true,
-    componentize: componentizeOptions = {},
-    ai = false,
-    verify = false,
-    chromePath,
-    signal,
-  } = options;
+  const { url, outDir, maxDepth = 2, ai = false, verify = false, chromePath, signal } = options;
 
   if (!url.startsWith("http://") && !url.startsWith("https://")) {
     throw new Error("URL must start with http:// or https://");
@@ -162,16 +142,16 @@ export async function importSite(
   if (!isAbsolute(outDir)) {
     throw new Error(`outDir must be an absolute path, got "${outDir}"`);
   }
-  if (existsSync(outDir) && readdirSync(outDir).length > 0) {
+  /* The guard admits the run's OWN seed and nothing else. It has to: the destination is created and
+     given a `project.json` before the browser launches, so a host can open the project and watch the
+     rest of the run arrive in its file tree — and a guard that could not tell that seed from a
+     stranger's files would refuse every import at its second statement. */
+  if (existsSync(outDir) && readdirSync(outDir).some((entry) => entry !== PROJECT_FILE)) {
     throw new Error(`Directory "${outDir}" is not empty`);
   }
 
-  const progress = (
-    phase: ImportPhase,
-    message: string,
-    counts?: { current?: number; total?: number },
-  ) => {
-    onProgress?.({ phase, message, ...counts });
+  const progress = (phase: ImportPhase, message: string) => {
+    onProgress?.({ phase, message });
   };
   const warnings: string[] = [];
   const warn = (phase: ImportPhase, message: string) => {
@@ -179,350 +159,175 @@ export async function importSite(
     progress(phase, `⚠ ${message}`);
   };
   const verifyThreshold = verify === false ? 0.15 : (verify.threshold ?? 0.15);
+  const verifyMinFidelity = verify === false ? 0 : (verify.minFidelity ?? 0);
+  const verifyFullPage = verify === false ? true : (verify.fullPage ?? true);
 
   try {
-    if (maxDepth === 0) {
-      return await runSinglePage();
-    }
-    return await runCrawl();
-  } finally {
-    await closeBrowser();
-  }
+    await seedProject();
 
-  // ─── Single-page mode: Phase 0-2 pipeline, no crawl overhead ────────────────
-  async function runSinglePage(): Promise<ImportSiteResult> {
     progress("launch", "Launching browser...");
     const browser = await launchBrowser(
       chromePath === undefined ? {} : { executablePath: chromePath },
     );
 
-    throwIfAborted(signal);
-    progress("capture", "Capturing page...");
-    const capture = await capturePage(url, browser, { scrollToBottom: scroll });
-    progress("capture", `Captured: "${capture.title}" (${capture.links.length} links found)`);
-
-    progress("capture", "Converting to Jx...");
-    const jx = convertToJx(capture.bodyHtml);
-    progress(
-      "capture",
-      `Converted: ${jx.nodeCount} nodes, ${jx.collectedStyles.length} inline stylesheets collected`,
-    );
-    if (jx.nodeCount > maxNodesPerPage) {
-      warn("capture", `Large page (${jx.nodeCount} nodes). Studio may be slow.`);
-    }
-
-    let breakpoints: Record<string, string> | undefined;
-    let styleTokens: Record<string, string> | undefined;
-
-    if (styles) {
-      throwIfAborted(signal);
-      progress("styles", "Capturing computed styles...");
-      const styleResult = await captureStyles(capture.page);
-      progress(
-        "styles",
-        `Captured styles for ${styleResult.elements.length} elements, ${Object.keys(styleResult.uaDefaults).length} tag baselines`,
-      );
-
-      progress("styles", "Diffing against UA defaults...");
-      const diffed = diffAllStyles(styleResult.elements, styleResult.uaDefaults);
-      progress("styles", `${diffed.length} elements with non-default styles`);
-
-      // Replace resolved values with var(--name) references
-      const propCount = Object.keys(styleResult.customProperties).length;
-      if (propCount > 0) {
-        const tokenResult = applyTokens(diffed, styleResult.customProperties);
-        if (tokenResult.replacements > 0) {
-          styleTokens = tokenResult.tokens;
-          progress(
-            "styles",
-            `Extracted ${Object.keys(tokenResult.tokens).length} design tokens (${tokenResult.replacements} replacements)`,
-          );
-        } else {
-          progress(
-            "styles",
-            `${propCount} custom properties found, but none matched computed values`,
-          );
-        }
-      }
-
-      if (styleResult.mediaQueries.length > 0) {
-        progress(
-          "styles",
-          `Extracting @media breakpoints (${styleResult.mediaQueries.length} queries found)...`,
-        );
-        const media = await extractMedia(
-          capture.page,
-          styleResult.elements,
-          styleResult.uaDefaults,
-          styleResult.mediaQueries,
-        );
-        const bpCount = Object.keys(media.breakpoints).length;
-        if (bpCount > 0) {
-          progress("styles", `${bpCount} breakpoints with style changes`);
-          ({ breakpoints } = media);
-          applyStylesToTree(jx.document, diffed, media.deltas);
-        } else {
-          progress("styles", "No responsive breakpoints with style changes");
-          applyStylesToTree(jx.document, diffed);
-        }
-      } else {
-        progress("styles", "No @media queries found");
-        applyStylesToTree(jx.document, diffed);
-      }
-
-      // Apply <html>/<body> computed styles to the root wrapper
-      if (Object.keys(styleResult.documentStyles).length > 0) {
-        if (!jx.document.style) {
-          jx.document.style = {};
-        }
-        for (const [prop, val] of Object.entries(styleResult.documentStyles)) {
-          const camel = kebabToCamel(prop);
-          jx.document.style[camel] = val;
-        }
-        progress(
+    const result = await runImportPipeline(
+      {
+        url,
+        browser,
+        io: createLocalIo(outDir),
+        maxDepth,
+        /* The model default is applied here so the pipeline can require one. See DEFAULT_AI_MODEL. */
+        ai: ai === false ? false : { ...ai, model: ai.model ?? DEFAULT_AI_MODEL },
+        referenceScreenshots: verify === false ? false : { fullPage: verifyFullPage },
+        ...pick(options, [
+          "maxPages",
+          "maxNodesPerPage",
+          "breakpoints",
           "styles",
-          `Applied ${Object.keys(styleResult.documentStyles).length} document-level styles to root`,
-        );
-      }
-    }
-
-    let fontFaceRules: string[] | undefined;
-    let fontRewriteMap: Map<string, string> | undefined;
-
-    if (assets) {
-      throwIfAborted(signal);
-      progress("assets", "Collecting asset URLs...");
-      const collected = await collectAssets(capture.page);
-      progress(
-        "assets",
-        `Found ${collected.assets.length} assets (${collected.inlineSvgCount} inline SVGs kept, ${collected.stylesheets.length} stylesheets retained)`,
-      );
-
-      const allFontRules = collected.stylesheets.flatMap((s) => s.fontFaceRules);
-      if (allFontRules.length > 0) {
-        fontFaceRules = allFontRules;
-        progress("assets", `Found ${allFontRules.length} @font-face rules`);
-      }
-
-      if (collected.assets.length > 0) {
-        progress("assets", "Downloading assets...");
-        const downloaded = await downloadAssets(collected.assets, outDir, url);
-        progress(
           "assets",
-          `Downloaded ${downloaded.rewriteMap.size} assets (${formatBytes(downloaded.totalBytes)})`,
-        );
-        if (downloaded.failed.length > 0) {
-          warn("assets", `${downloaded.failed.length} assets failed to download`);
-        }
-        if (downloaded.skipped.length > 0) {
-          progress("assets", `Skipped ${downloaded.skipped.length} tracking/analytics URLs`);
-        }
-
-        if (fontFaceRules) {
-          fontRewriteMap = new Map<string, string>();
-          for (const [originalUrl, localPath] of downloaded.rewriteMap) {
-            if (localPath.includes("/fonts/") || /\.(woff2?|ttf|otf|eot)$/i.test(localPath)) {
-              fontRewriteMap.set(originalUrl, localPath);
-            }
-          }
-        }
-
-        progress("assets", "Rewriting asset URLs...");
-        const rewrites = rewriteAssetUrls(jx.document, downloaded.rewriteMap, url);
-        progress("assets", `Rewrote ${rewrites} URL references`);
-      }
-    }
-
-    // Capture the reference screenshot before closing the page (for verify)
-    let referenceScreenshot: Buffer | undefined;
-    if (verify !== false) {
-      progress("verify", "Capturing reference screenshot...");
-      const { captureReferenceScreenshot } = await import("./verify.ts");
-      referenceScreenshot = await captureReferenceScreenshot(capture.page);
-    }
-
-    await capture.page.close();
-
-    throwIfAborted(signal);
-    const pageMap = new Map([["pages/index.json", jx.document]]);
-    const precomputedComponents = await maybeAiComponentize(
-      pageMap,
-      componentizeOptions,
-      ai,
-      progress,
-    );
-
-    throwIfAborted(signal);
-    progress("emit", "Writing project...");
-    const { files } = await emitMultiPageProject({
-      outDir,
-      title: capture.title,
-      pages: pageMap,
-      sourceUrl: url,
-      breakpoints,
-      componentizeOptions: precomputedComponents ? false : componentizeOptions,
-      precomputedComponents,
-      fontFaceRules,
-      fontRewriteMap,
-      styleTokens,
-    });
-    progress("emit", `Wrote ${files.length} files`);
-
-    let verifySummary: ImportSiteResult["verify"] = null;
-    if (verify !== false && referenceScreenshot) {
-      verifySummary = await runVerify(
-        new Map([["pages/index.json", { sourceUrl: url, screenshot: referenceScreenshot }]]),
-        browser,
-      );
-    }
-
-    progress("done", `Imported ${url} → ${outDir}`);
-    return {
-      outDir,
-      pages: [{ route: "pages/index.json", title: capture.title, nodeCount: jx.nodeCount }],
-      fileCount: files.length,
-      verify: verifySummary,
-      warnings,
-    };
-  }
-
-  // ─── Multi-page crawl mode (Phase 3) ────────────────────────────────────────
-  async function runCrawl(): Promise<ImportSiteResult> {
-    progress("launch", "Launching browser...");
-    await launchBrowser(chromePath === undefined ? {} : { executablePath: chromePath });
-
-    throwIfAborted(signal);
-    const result = await crawlSite({
-      url,
-      outDir,
-      maxDepth,
-      maxPages,
-      maxNodesPerPage,
-      skipStyles: !styles,
-      skipAssets: !assets,
-      respectRobots,
-      noScroll: !scroll,
-      captureScreenshots: verify !== false,
-      onProgress: (msg) => progress("crawl", msg.trim()),
-      ...(signal === undefined ? {} : { signal }),
-    });
-
-    progress(
-      "crawl",
-      `Crawled ${result.pages.length} page${result.pages.length === 1 ? "" : "s"}`,
-      { current: result.pages.length, total: maxPages },
+          "scroll",
+          "respectRobots",
+          "componentize",
+          "signal",
+        ]),
+      },
+      onProgress,
     );
-    if (result.skippedByRobots.length > 0) {
-      progress("crawl", `Skipped ${result.skippedByRobots.length} URLs (robots.txt)`);
-    }
-    if (result.skippedByNodeCap.length > 0) {
-      warn(
-        "crawl",
-        `${result.skippedByNodeCap.length} pages exceeded node cap (styles/assets skipped)`,
-      );
-    }
-
-    const pageMap = new Map<string, JxElement>();
-    for (const page of result.pages) {
-      pageMap.set(page.route, page.jx.document);
-    }
-
-    // Layout detection
-    let layout: JxElement | undefined;
-    if (result.pages.length >= 2) {
-      throwIfAborted(signal);
-      progress("layout", "Detecting shared layout (header/footer)...");
-      const layoutResult = detectLayout(pageMap);
-      if (layoutResult) {
-        ({ layout } = layoutResult);
-        const sharedCount = (Array.isArray(layout.children) ? layout.children.length : 0) - 1; // Minus the slot
-        progress("layout", `Found shared layout with ${sharedCount} shared elements`);
-        for (const [route, stripped] of layoutResult.strippedPages) {
-          pageMap.set(route, stripped);
-        }
-      } else {
-        progress("layout", "No shared layout detected");
-      }
-    }
-
-    throwIfAborted(signal);
-    const precomputedComponents = await maybeAiComponentize(
-      pageMap,
-      componentizeOptions,
-      ai,
-      progress,
-    );
-
-    throwIfAborted(signal);
-    progress("emit", "Writing project...");
-    const title = result.pages[0]?.title || new URL(url).hostname;
-    const { files } = await emitMultiPageProject({
-      outDir,
-      title,
-      sourceUrl: url,
-      pages: pageMap,
-      layout,
-      breakpoints: result.breakpoints,
-      componentizeOptions: precomputedComponents ? false : componentizeOptions,
-      precomputedComponents,
-      fontFaceRules: result.fontFaceRules.length > 0 ? result.fontFaceRules : undefined,
-      fontRewriteMap: result.fontRewriteMap.size > 0 ? result.fontRewriteMap : undefined,
-      styleTokens: result.styleTokens,
-    });
-    progress("emit", `Wrote ${files.length} files`);
+    warnings.push(...result.warnings);
 
     let verifySummary: ImportSiteResult["verify"] = null;
     if (verify !== false) {
-      const verifyPages = new Map<string, { sourceUrl: string; screenshot: Buffer | string }>();
-      for (const page of result.pages) {
-        if (page.screenshot) {
-          verifyPages.set(page.route, { sourceUrl: page.url, screenshot: page.screenshot });
-        }
-      }
-      if (verifyPages.size === 0) {
+      if (result.references.size === 0) {
         progress("verify", "No reference screenshots captured — skipping verify");
       } else {
-        verifySummary = await runVerify(verifyPages);
+        /* Only the single-page run hands the verifier its browser. A crawl's pages were captured
+           and closed one at a time, so by now the connection has outlived every page it opened and
+           `verifyProject` launching its own is the same cost either way. */
+        verifySummary = await runVerify(result.references, maxDepth === 0 ? browser : undefined);
       }
     }
 
     progress("done", `Imported ${url} → ${outDir}`);
     return {
       outDir,
-      pages: result.pages.map((p) => ({
-        route: p.route,
-        title: p.title,
-        nodeCount: p.jx.nodeCount,
-      })),
-      fileCount: files.length,
+      pages: result.pages,
+      fileCount: result.files.length,
       verify: verifySummary,
       warnings,
     };
+  } finally {
+    await closeBrowser();
+  }
+
+  /**
+   * Create the destination and give it a `project.json` valid enough to open.
+   *
+   * The emit phase rewrites this file completely, so nothing here is a guess at what the import
+   * will find — it is the minimum that makes the directory a PROJECT, so the caller can open it now
+   * instead of at the end. Everything a crawl writes then lands in a file tree somebody is
+   * watching.
+   */
+  async function seedProject(): Promise<void> {
+    await mkdir(outDir, { recursive: true });
+    const seed = { name: seedName(url), imports: {}, images: { optimize: false } };
+    await Bun.write(join(outDir, PROJECT_FILE), `${JSON.stringify(seed, null, 2)}\n`);
+    onProgress?.({
+      message: `Created ${outDir}`,
+      phase: "seed",
+      root: outDir,
+    });
   }
 
   // ─── Phase 5: build + screenshot-diff against the original ─────────────────
   async function runVerify(
-    verifyPages: Map<string, { sourceUrl: string; screenshot: Buffer | string }>,
+    references: Map<string, { sourceUrl: string; screenshot: Uint8Array }>,
     browser?: Browser,
   ): Promise<ImportSiteResult["verify"]> {
     throwIfAborted(signal);
     progress("verify", "Verifying against the original...");
     const { verifyProject } = await import("./verify.ts");
+    const verifyPages = new Map<string, { sourceUrl: string; screenshot: Buffer | string }>();
+    for (const [route, ref] of references) {
+      verifyPages.set(route, { sourceUrl: ref.sourceUrl, screenshot: Buffer.from(ref.screenshot) });
+    }
     const verifyResult = await verifyProject({
       projectDir: outDir,
       pages: verifyPages,
       threshold: verifyThreshold,
+      minFidelity: verifyMinFidelity,
+      fullPage: verifyFullPage,
       onProgress: (msg) => progress("verify", msg),
       ...(browser === undefined ? {} : { browser }),
     });
+    /*
+     * Build errors were logged inside the verifier and dropped there. They are warnings on the
+     * import as a whole: a project that did not compile is not a clone of anything, however the
+     * pixels happen to score.
+     */
+    for (const error of verifyResult.buildErrors) {
+      warn("verify", `Build error: ${error}`);
+    }
     for (const page of verifyResult.pages) {
       const status = page.error ? `ERROR: ${page.error}` : `${page.fidelity}% fidelity`;
-      progress("verify", `${page.route} — ${status}`);
+      const misses =
+        page.failedRequests.length > 0 ? `, ${page.failedRequests.length} failed request(s)` : "";
+      progress("verify", `${page.route} — ${status}${misses}`);
     }
     progress("verify", `Average fidelity: ${verifyResult.averageFidelity}%`);
+    if (!verifyResult.passed) {
+      warn(
+        "verify",
+        `Verification failed: average fidelity ${verifyResult.averageFidelity}% ` +
+          `(minimum ${verifyMinFidelity}%). See ${verifyResult.reportDir}/report.json`,
+      );
+    }
     return {
       averageFidelity: verifyResult.averageFidelity,
       reportDir: verifyResult.reportDir,
+      passed: verifyResult.passed,
+      minFidelity: verifyMinFidelity,
+      buildErrors: verifyResult.buildErrors,
+      pages: verifyResult.pages.map((page) => {
+        const entry: {
+          route: string;
+          fidelity: number;
+          consoleErrors: number;
+          failedRequests: number;
+          error?: string;
+        } = {
+          route: page.route,
+          fidelity: page.fidelity,
+          consoleErrors: page.consoleErrors.length,
+          failedRequests: page.failedRequests.length,
+        };
+        if (page.error !== undefined) {
+          entry.error = page.error;
+        }
+        return entry;
+      }),
     };
   }
 }
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw new Error("Import aborted");
+  }
+}
+
+/**
+ * Forward the options this wrapper shares with the pipeline, and only the ones actually given.
+ *
+ * `exactOptionalPropertyTypes` is on, so `{ signal: undefined }` is a different thing from an
+ * absent `signal` and the pipeline would reject it. Copying present keys is also what keeps every
+ * default in ONE place — restating `maxPages = 25` here is how the CLI and the cloud drift apart.
+ */
+function pick<T extends object, K extends keyof T>(source: T, keys: readonly K[]): Pick<T, K> {
+  const out = {} as Pick<T, K>;
+  for (const key of keys) {
+    if (source[key] !== undefined) {
+      out[key] = source[key];
+    }
+  }
+  return out;
+}