@jxsuite/import 0.39.7 → 0.40.0

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.7",
+  "version": "0.40.0",
   "description": "Clone a live website into a Jx project",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,9 @@
     "./capture": "./src/capture.ts",
     "./to-jx": "./src/to-jx.ts",
     "./emit": "./src/emit.ts",
-    "./run": "./src/run.ts"
+    "./run": "./src/run.ts",
+    "./verify": "./src/verify.ts",
+    "./breakpoint-plan": "./src/breakpoint-plan.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -31,8 +33,8 @@
     "import": "bun run src/cli.ts"
   },
   "dependencies": {
-    "@jxsuite/markup": "^0.4.6",
-    "@jxsuite/schema": "^1.8.1",
+    "@jxsuite/markup": "^0.4.8",
+    "@jxsuite/schema": "^2.0.0",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "puppeteer-core": "^24.9.0"
@@ -42,6 +44,6 @@
     "happy-dom": "^20.10.6"
   },
   "optionalDependencies": {
-    "@jxsuite/compiler": "^2.0.7"
+    "@jxsuite/compiler": "^3.0.0"
   }
 }

package/src/asset-collect.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Page } from "puppeteer-core";
+import { SRCSET_SEPARATOR } from "./srcset.ts";
 
 export interface DiscoveredAsset {
   /** Absolute URL of the asset. */
@@ -46,7 +47,12 @@ export interface AssetCollectionResult {
  * page.evaluate() — no per-element round-trips.
  */
 export async function collectAssets(page: Page): Promise<AssetCollectionResult> {
-  const result = await page.evaluate(() => {
+  /*
+   * 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

@@ -11,8 +11,9 @@ import type { DiscoveredAsset } from "./asset-collect.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. */
@@ -172,7 +173,11 @@ export async function downloadAssets(
     usedNames.set(nameKey, count + 1);
 
     const destPath = join(assetsDir, subdir, filename);
-    const relativePath = `public/assets/${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> = {

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/cli.ts

@@ -3,6 +3,13 @@
 import { resolve } from "node:path";
 import { homedir } from "node:os";
 import { importSite } from "./run.ts";
+import {
+  DEFAULT_BREAKPOINT_POLICY,
+  MAX_BREAKPOINTS,
+  MAX_BREAKPOINT_WIDTH,
+  MIN_BREAKPOINT_WIDTH,
+} from "./breakpoint-plan.ts";
+import type { BreakpointPolicy, BreakpointRounding } from "./breakpoint-plan.ts";
 
 function usage(): never {
   console.log(`Usage: jx-import <url> [options]
@@ -14,6 +21,10 @@ Options:
   --depth <n>              Max crawl depth (default: 2, 0 = single page)
   --max-pages <n>          Max pages to capture (default: 25)
   --max-nodes-per-page <n> Skip styles/assets for pages above this (default: 5000)
+  --max-breakpoints <n>    Keep at most n of the site's breakpoints (default: 3, 0 = keep all)
+  --breakpoints <list>     Keep these widths instead, e.g. 640,1024,1440
+  --breakpoint-rounding <r> How a kept width matches a declared one: nearest|down|up
+                           (default: nearest)
   --no-styles              Skip CSS capture
   --no-assets              Skip asset download
   --no-crawl               Single page only (equivalent to --depth 0)
@@ -25,7 +36,10 @@ Options:
   --ai-components          Use LLM to refine component names and props (Phase 4 AI pass)
   --ai-model <model>       Model for AI componentization (default: gpt-4o-mini)
   --verify                 After import, build and screenshot-diff vs original (Phase 5)
-  --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).
+                           Moves the score; it is NOT the pass bar — --min-fidelity is.
+  --verify-viewport-only   Diff only the first viewport instead of the whole page
 
 Environment:
   OPENAI_API_KEY           Required for --ai-components
@@ -37,6 +51,8 @@ Examples:
   jx-import https://example.com --depth 1 --max-pages 10
   jx-import https://example.com --no-crawl
   jx-import https://example.com --out sites/my-clone --no-styles
+  jx-import https://example.com --breakpoints 640,1024,1440
+  jx-import https://example.com --max-breakpoints 0
   jx-import https://example.com --verify
   jx-import https://example.com --ai-components`);
   process.exit(1);
@@ -73,7 +89,60 @@ const verifyThreshold =
   verifyThresholdIdx !== -1 && args[verifyThresholdIdx + 1]
     ? Number(args[verifyThresholdIdx + 1]) || 0.15
     : 0.15;
+/*
+ * The floor below which the output is not a clone of anything.
+ *
+ * It is deliberately low rather than a quality bar: a real import of a complicated site lands well
+ * under 100 for reasons nobody can fix from here (a rotating hero, a font that renders a hair
+ * differently), and failing those would train people to pass `--min-fidelity 0` and stop looking.
+ * Under a quarter of pixels matching is a different question — that is the 8%-fidelity Wix clone
+ * that printed `Done!` and exited 0, which is worse than a failure because the only way to see it
+ * is to open the result (issue #232).
+ */
+const minFidelity = parseIntArg(args, "--min-fidelity", 25);
+const verifyFullPage = !args.includes("--verify-viewport-only");
 
+/**
+ * The breakpoint policy from the flags.
+ *
+ * `--breakpoints` wins over `--max-breakpoints` because it is the more specific answer: naming the
+ * widths says everything a count could have.
+ */
+function breakpointPolicy(): BreakpointPolicy {
+  const roundingIdx = args.indexOf("--breakpoint-rounding");
+  const roundingArg = roundingIdx === -1 ? "" : (args[roundingIdx + 1] ?? "");
+  const rounding: BreakpointRounding =
+    roundingArg === "down" || roundingArg === "up" ? roundingArg : "nearest";
+
+  const widthsIdx = args.indexOf("--breakpoints");
+  const widthsArg = widthsIdx === -1 ? "" : (args[widthsIdx + 1] ?? "");
+  if (widthsArg) {
+    const widths = widthsArg
+      .split(",")
+      .map((part) => Math.trunc(Number(part.trim())))
+      .filter((n) => Number.isFinite(n) && n >= MIN_BREAKPOINT_WIDTH && n <= MAX_BREAKPOINT_WIDTH);
+    if (widths.length === 0) {
+      console.error(
+        `Error: --breakpoints needs widths between ${MIN_BREAKPOINT_WIDTH} and ` +
+          `${MAX_BREAKPOINT_WIDTH}, e.g. --breakpoints 640,1024,1440`,
+      );
+      process.exit(1);
+    }
+    return { mode: "explicit", rounding, widths };
+  }
+
+  if (!args.includes("--max-breakpoints")) {
+    return DEFAULT_BREAKPOINT_POLICY;
+  }
+  const count = parseIntArg(args, "--max-breakpoints", 3);
+  // Zero is the only spelling of "keep all" a count can have, and it reads better than omitting the
+  // Flag when a script is choosing between the two.
+  return count <= 0
+    ? { mode: "all" }
+    : { count: Math.min(MAX_BREAKPOINTS, count), mode: "limit", rounding };
+}
+
+const breakpoints = breakpointPolicy();
 const maxDepth = noCrawl ? 0 : parseIntArg(args, "--depth", 2);
 const maxPages = parseIntArg(args, "--max-pages", 25);
 const maxNodesPerPage = parseIntArg(args, "--max-nodes-per-page", 5000);
@@ -116,6 +185,7 @@ async function main() {
       {
         url: url as string,
         outDir,
+        breakpoints,
         maxDepth,
         maxPages,
         maxNodesPerPage,
@@ -125,7 +195,9 @@ async function main() {
         respectRobots: !args.includes("--no-robots"),
         componentize: noComponents ? false : { minInstances, minDepth },
         ai,
-        verify: doVerify ? { threshold: verifyThreshold } : false,
+        verify: doVerify
+          ? { threshold: verifyThreshold, minFidelity, fullPage: verifyFullPage }
+          : false,
       },
       (e) => console.log(`  ${e.message}`),
     );
@@ -136,9 +208,41 @@ async function main() {
     }
     if (result.verify) {
       console.log(`  Average fidelity: ${result.verify.averageFidelity}%`);
+      for (const page of result.verify.pages) {
+        const misses = [
+          page.failedRequests > 0 ? `${page.failedRequests} failed request(s)` : "",
+          page.consoleErrors > 0 ? `${page.consoleErrors} console error(s)` : "",
+        ].filter(Boolean);
+        if (misses.length > 0) {
+          console.log(`    ${page.route}: ${misses.join(", ")}`);
+        }
+      }
       console.log(`  Report: ${result.verify.reportDir}/report.json`);
     }
 
+    /*
+     * A verify that cannot fail is a report, not a gate. An import nobody opens and looks at is
+     * exactly the case the exit code exists for, so a build error or a fidelity under the floor
+     * ends the run non-zero and says which one it was.
+     */
+    if (result.verify && !result.verify.passed) {
+      for (const error of result.verify.buildErrors) {
+        console.error(`Build error: ${error}`);
+      }
+      console.error(
+        `\nVerification FAILED — the project is at ${outDir}, but it does not match the original.`,
+      );
+      if (result.verify.buildErrors.length === 0) {
+        console.error(
+          `  Average fidelity ${result.verify.averageFidelity}% is below the ` +
+            `${result.verify.minFidelity}% minimum. Pass --min-fidelity to change it.`,
+        );
+      }
+      console.error(`  Report: ${result.verify.reportDir}/report.json`);
+      process.exitCode = 1;
+      return;
+    }
+
     console.log(`\nDone! Open in Studio:`);
     console.log(
       `  http://localhost:3000/packages/studio/index.html?project=${outDir}/project.json`,

package/src/componentize.ts

@@ -54,6 +54,16 @@ function structuralHash(node: JxElement | string): string {
   return `<${tag}>${childHashes.join(",")}`;
 }
 
+/**
+ * Attributes that may not become a component prop.
+ *
+ * A prop is something a person fills in per instance, and a class is not one: `emit.ts` strips the
+ * source site's classes on the way out (`strip-classes.ts`), so a class that happened to differ
+ * between two instances of the same block would otherwise mint a `${state.class}` prop whose value
+ * is then deleted — a prop with a name nobody chose, wired to nothing.
+ */
+const PRESENTATION_ATTRS = new Set(["class", "className"]);
+
 function collectLeafValues(node: JxElement | string, prefix: string, out: Map<string, string>) {
   if (typeof node === "string") {
     out.set(`${prefix}.$text`, node);
@@ -64,6 +74,9 @@ function collectLeafValues(node: JxElement | string, prefix: string, out: Map<st
   }
   if (node.attributes) {
     for (const [k, v] of Object.entries(node.attributes)) {
+      if (PRESENTATION_ATTRS.has(k)) {
+        continue;
+      }
       if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
         out.set(`${prefix}.attr.${k}`, String(v));
       }