harnery 0.36.0 → 0.38.0

package/src/commands/browse.ts

@@ -2,8 +2,16 @@ import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSyn
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve } from "node:path";
 import type { Command } from "commander";
+import { PNG } from "pngjs";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { resolveBinName } from "../core/config.ts";
+import {
+  CAPTURE_FIDELITY_MISMATCH_THRESHOLD,
+  compareBand,
+  decideFidelity,
+  type FidelityProbe,
+  pngDimensions,
+} from "../lib/browser/capture-fidelity.ts";
 import {
   type AssertResult,
   Browser,
@@ -11,6 +19,7 @@ import {
   browserProxyGateFromEnv,
   type ContentAnnotationBox,
   type ContentChecksResult,
+  type CritiqueCoverage,
   type CritiqueResult,
   type CritiqueTile,
   captureDevOverlay,
@@ -34,6 +43,16 @@ import {
   writeNetscapeCookieFile,
   wslHeadedLaunchArgs,
 } from "../lib/browser/index.ts";
+import {
+  findPackTile,
+  type PageReviewCaptureFidelity,
+  type PageReviewContextRecord,
+  type PageReviewExpandedTileRecord,
+  readPackContext,
+  tileId,
+  writePackContext,
+  writePackExpandedTile,
+} from "../lib/browser/page-review-pack.ts";
 import {
   buildQaManifest,
   classifySignatures,
@@ -62,7 +81,7 @@ import {
   type SaveBaselineResult,
   saveBaseline,
 } from "../lib/browser/visual-diff.ts";
-import { CookieJar } from "../lib/cookies/index.ts";
+import { applyExtraCookies, CookieJar } from "../lib/cookies/index.ts";
 
 /**
  * `harn browse <url>`: Playwright-backed page navigation with shared
@@ -117,6 +136,8 @@ interface BrowseOpts {
   store?: string;
   profile?: string;
   viewport?: string;
+  deviceScaleFactor?: string;
+  colorScheme?: string;
   waitUntil: string;
   timeout: string;
   json?: boolean;
@@ -210,6 +231,16 @@ interface BrowseOpts {
   qaStates?: string[];
   qaReuse?: boolean;
   qaReuseThreshold?: string;
+  // Page review pack capture (page-review-pack.ts): tiles + DOM to disk, no
+  // vision call; the judge stage reviews the pack after the browser closed.
+  reviewPack?: string;
+  reviewPackContext?: string;
+  reviewPackScope?: string[];
+  reviewPackBands?: boolean;
+  /** Re-capture ONE existing tile of --review-pack-context at --device-scale-factor. */
+  reviewPackExpand?: string;
+  /** Gate-hit rectangles (`x,y,w,h` strings) whose bands are captured past the tile cap. */
+  reviewPackHitRect?: string[];
   // Next.js dev-overlay capture (auto-on; --no-dev-overlay opts out)
   devOverlay?: boolean;
 }
@@ -275,6 +306,12 @@ export function registerBrowseCommand(
       "Viewport: mobile (390x844), tablet (820x1180), desktop (1280x800), hd (1920x1080), or explicit '1920x1080'",
       "desktop",
     )
+    .option(
+      "--color-scheme <scheme>",
+      "Emulate prefers-color-scheme for the whole session: light | dark. " +
+        "Renders theme-aware pages in that scheme without page-specific toggles. " +
+        "Absent = browser default (unchanged behavior).",
+    )
     .option("--login", "Headed mode for one-time auth flow (cookies persist in profile)")
     .option(
       "--login-close-file <path>",
@@ -681,6 +718,48 @@ export function registerBrowseCommand(
       "Band-diff mismatch ratio at or below which a clean tile region is reused " +
         `(default ${DEFAULT_REUSE_MISMATCH_RATIO}; lower it toward 0 for stricter reuse).`,
     )
+    .option(
+      "--review-pack <dir>",
+      "Capture this render into a page review pack at <dir> (contexts/<id>/: full-page " +
+        "screenshot, critique tiles as PNG files, serialized DOM, QA signature) and make no " +
+        "vision call. A judge stage (`review-pack judge`, or qa-run) reviews the tiles from disk " +
+        "after every browser has closed. Tiling knobs are the --check-critique-* flags.",
+    )
+    .option(
+      "--review-pack-context <id>",
+      "Context id inside the pack (default <viewport>-<theme>-<state> from --viewport, " +
+        "--qa-theme, --qa-state).",
+    )
+    .option(
+      "--review-pack-scope <selector>",
+      "Also tile one screenshot per element matching <selector> into the pack (repeatable).",
+      (value: string, previous: string[] = []) => [...previous, value],
+      [] as string[],
+    )
+    .option(
+      "--no-review-pack-bands",
+      "Skip full-page bands in the pack and keep only --review-pack-scope tiles (a scoped " +
+        "visual pass).",
+    )
+    .option(
+      "--review-pack-expand <tile-id>",
+      "Instead of capturing a context, re-render ONE existing tile of --review-pack-context " +
+        "(e.g. T012) at --device-scale-factor and write it beside the original as " +
+        "tiles/<tile>@<dpr>x.png. Existing tiles are untouched.",
+    )
+    .option(
+      "--review-pack-hit-rect <x,y,w,h>",
+      "Document-space rectangle (integer px) a deterministic gate already flagged. Every " +
+        "full-page band that contains it is captured even past --check-critique-max-tiles, " +
+        `labelled \`hit band N\` (repeatable, at most ${REVIEW_PACK_HIT_RECT_MAX}).`,
+      (value: string, previous: string[] = []) => [...previous, value],
+      [] as string[],
+    )
+    .option(
+      "--device-scale-factor <n>",
+      "Device scale factor for the browser context (default 1). 2 renders every screenshot " +
+        "at twice the pixels; pair with --review-pack-expand for a sharper look at one tile.",
+    )
     .option(
       "--no-dev-overlay",
       "Skip auto-capture of Next.js dev-overlay issues. Default: capture every queued error (kind/code/message/stack) when a <nextjs-portal> shadow root is present. Necessary because Next.js 16 + React 19 route hydration errors + most React warnings through onCaughtError → next-devtools' errorQueue, NOT through console.error, so Playwright's standard listener doesn't see them. Surfaces them in the JSON envelope under `devOverlay`.",
@@ -732,8 +811,26 @@ async function runBrowse(
     opts.cookies === false
       ? null
       : new CookieJar({ path: opts.store ?? DEFAULT_STORE, source: "harn-browse" });
+  if (jar) applyExtraCookies(url, jar, context?.extraCookies);
   const headed = opts.login || opts.headed;
   const viewport = parseViewport(opts.viewport ?? "desktop");
+  const deviceScaleFactor = parseDeviceScaleFactor(opts.deviceScaleFactor);
+  if (opts.reviewPackExpand !== undefined) {
+    if (opts.reviewPack === undefined || opts.reviewPackContext === undefined) {
+      throw new Error(
+        "--review-pack-expand requires --review-pack <dir> and --review-pack-context <id>.",
+      );
+    }
+  }
+  // Malformed hit rects fail here, before a browser launches.
+  parseReviewPackHitRects(opts.reviewPackHitRect);
+  let colorScheme: "light" | "dark" | undefined;
+  if (opts.colorScheme !== undefined) {
+    if (opts.colorScheme !== "light" && opts.colorScheme !== "dark") {
+      throw new Error(`--color-scheme must be light or dark (got: ${opts.colorScheme}).`);
+    }
+    colorScheme = opts.colorScheme;
+  }
   const proxy = opts.proxyFromEnv ? browserProxyFromEnv() : undefined;
   const proxyGate = opts.proxyFromEnv ? browserProxyGateFromEnv() : null;
   if (opts.loginCloseFile && !opts.login) {
@@ -754,6 +851,8 @@ async function runBrowse(
     headed,
     jar,
     viewport,
+    ...(deviceScaleFactor !== undefined ? { deviceScaleFactor } : {}),
+    ...(colorScheme ? { colorScheme } : {}),
     navigationTimeout: Number.parseInt(opts.timeout, 10),
     waitUntil: opts.waitUntil as BrowseOpts["waitUntil"] as never,
     recordHarPath: opts.networkHar ? resolve(opts.networkHar) : undefined,
@@ -979,12 +1078,25 @@ async function runBrowse(
           "info",
         );
       }
-      critique = await runCritique({
-        url: navResult.url,
-        rubric,
-        tiles: tilesToReview,
-        provider: critiqueProvider,
-      });
+      critique = {
+        ...(await runCritique({
+          url: navResult.url,
+          rubric,
+          tiles: tilesToReview,
+          provider: critiqueProvider,
+        })),
+        // Coverage rides on every envelope, skipped or not, so a reader can
+        // tell a pass over the whole page from a pass over its first N bands.
+        coverage: captured.coverage,
+      };
+    }
+    // Page review pack capture: tiles, DOM, and signature to disk, no vision
+    // call. Also before annotations, for the same reason as the critique.
+    let reviewPack: ReviewPackReport | undefined;
+    if (opts.reviewPack !== undefined && opts.reviewPackExpand !== undefined) {
+      reviewPack = await expandReviewPackTile(browser, opts, deviceScaleFactor ?? 1);
+    } else if (opts.reviewPack !== undefined) {
+      reviewPack = await captureReviewPackContext(browser, url, navResult, opts, qaCapture);
     }
     // Persist the QA baseline AFTER critique so a passing run's verdicts ride
     // along with the snapshot (still before annotations mutate the page).
@@ -997,6 +1109,7 @@ async function runBrowse(
         critique?.provider &&
         critique.outcome !== "skipped" &&
         critiqueTiles !== undefined &&
+        !critique.coverage?.capped &&
         (!qaReuse || qaReuse.tiles_reused === 0);
       const persistedCritique: PersistedCritique | undefined =
         fullCoverage && critique && critiqueTiles
@@ -1160,6 +1273,7 @@ async function runBrowse(
         batchResult,
         qaPlan,
         qaReuse ? summarizeReuse(qaReuse) : undefined,
+        reviewPack,
       );
     } else {
       await runTrioMode(
@@ -1180,6 +1294,7 @@ async function runBrowse(
         batchResult,
         qaPlan,
         qaReuse ? summarizeReuse(qaReuse) : undefined,
+        reviewPack,
       );
     }
 
@@ -1425,6 +1540,7 @@ async function runPrintMode(
   batchResult: BatchResult | undefined,
   qaPlan: QaPlanReport | undefined,
   qaReuse: Record<string, unknown> | undefined,
+  reviewPack: ReviewPackReport | undefined,
 ): Promise<void> {
   let body: string | null = null;
   if (opts.html) {
@@ -1461,6 +1577,7 @@ async function runPrintMode(
     if (devOverlay) result.devOverlay = devOverlay;
     if (qaPlan) result.qaPlan = qaPlan;
     if (qaReuse) result.qaReuse = qaReuse;
+    if (reviewPack) result.reviewPack = reviewPack;
     if (batchResult && batchResult.clipboardReads.length > 0) {
       result.batchClipboardReads = batchResult.clipboardReads;
     }
@@ -1499,6 +1616,7 @@ async function runTrioMode(
   batchResult: BatchResult | undefined,
   qaPlan: QaPlanReport | undefined,
   qaReuse: Record<string, unknown> | undefined,
+  reviewPack: ReviewPackReport | undefined,
 ): Promise<void> {
   const prefix = resolveOutPrefix(opts.out);
   mkdirSync(dirname(prefix), { recursive: true });
@@ -1595,6 +1713,7 @@ async function runTrioMode(
   if (devOverlay) envelope.devOverlay = devOverlay;
   if (qaPlan) envelope.qaPlan = qaPlan;
   if (qaReuse) envelope.qaReuse = qaReuse;
+  if (reviewPack) envelope.reviewPack = reviewPack;
   if (batchResult && batchResult.clipboardReads.length > 0) {
     envelope.batchClipboardReads = batchResult.clipboardReads;
   }
@@ -2088,12 +2207,14 @@ interface QaCaptureState {
  * supplies the live-page inputs (signature, page height, explicit scope match
  * counts). Classification and manifest math live in lib/browser/qa-plan.ts.
  */
-async function runQaPlanning(
+/** Capture the live page's QA signature and serialized DOM for the store key
+ * `--qa-target` (default: the url argument) and the labelled context. */
+async function captureQaState(
   browser: Browser,
   targetArg: string,
   renderedUrl: string,
   opts: BrowseOpts,
-): Promise<{ report: QaPlanReport; capture: QaCaptureState }> {
+): Promise<QaCaptureState> {
   const context: QaContext = {
     viewport: opts.viewport ?? "desktop",
     theme: opts.qaTheme === "dark" ? "dark" : "light",
@@ -2108,11 +2229,22 @@ async function runQaPlanning(
     stylesheets: captured.stylesheets,
     ...(captured.truncated ? { truncated: true } : {}),
   };
+  return { target, context, signature, domHtml: captured.domHtml };
+}
+
+async function runQaPlanning(
+  browser: Browser,
+  targetArg: string,
+  renderedUrl: string,
+  opts: BrowseOpts,
+): Promise<{ report: QaPlanReport; capture: QaCaptureState }> {
+  const capture = await captureQaState(browser, targetArg, renderedUrl, opts);
+  const { target, context, signature } = capture;
   const report: QaPlanReport = {
     signature: {
-      nodes: captured.nodes.length,
-      stylesheets: captured.stylesheets.length,
-      truncated: captured.truncated,
+      nodes: signature.nodes.length,
+      stylesheets: signature.stylesheets.length,
+      truncated: Boolean(signature.truncated),
     },
   };
 
@@ -2150,20 +2282,324 @@ async function runQaPlanning(
     });
   }
 
-  return { report, capture: { target, context, signature, domHtml: captured.domHtml } };
+  return { report, capture };
 }
 
-async function captureCritiqueTiles(
-  browser: Browser,
+/** Tiling knobs shared by the critique and the review-pack capture. The
+ * routed provider's vision long-edge budget caps band height so tiles are
+ * never silently downscaled by the model. */
+function critiqueTilingKnobs(
   opts: BrowseOpts,
   tileBudgetPx?: number,
-): Promise<{ tiles: CritiqueTile[]; fullPage: Buffer }> {
+): { maxTiles: number; band: number; overlap: number } {
   const maxTiles = Math.max(1, Number.parseInt(opts.checkCritiqueMaxTiles ?? "24", 10));
-  // The routed provider's vision long-edge budget caps band height so tiles
-  // are never silently downscaled by the model.
   const bandFlag = Math.max(200, Number.parseInt(opts.checkCritiqueBand ?? "1400", 10));
   const band = tileBudgetPx ? Math.max(200, Math.min(bandFlag, tileBudgetPx)) : bandFlag;
   const overlap = Math.max(0, Number.parseInt(opts.checkCritiqueOverlap ?? "120", 10));
+  return { maxTiles, band, overlap };
+}
+
+/** What `--review-pack` puts in the JSON envelope. */
+interface ReviewPackReport {
+  dir: string;
+  context_id: string;
+  tiles: number;
+  scopes: Array<{ selector: string; tiles: number }>;
+  coverage: CritiqueCoverage;
+  files: PageReviewContextRecord["files"];
+  /** Bands captured past the tile cap for --review-pack-hit-rect rectangles. */
+  hit_bands?: number;
+  /** Where the tiles came from and what the fidelity probe saw. */
+  capture_fidelity?: PageReviewCaptureFidelity;
+  /** Capture warnings worth surfacing beside coverage (fidelity fallback, failed probes). */
+  warnings?: string[];
+  /** Set by --review-pack-expand: the one region that was re-captured. */
+  expanded?: PageReviewExpandedTileRecord;
+}
+
+/**
+ * `--review-pack-expand`: re-render one existing tile of a pack context at
+ * the context's device scale factor. The tile's CSS-pixel rect is captured by
+ * scrolling the viewport to it and clipping (`captureRegionByScroll`), which
+ * renders the region the way a reader sees it and yields tile size × DPR
+ * pixels. A second full-page screenshot is not taken: it would reproduce the
+ * very raster artifact the expand is meant to check. No other pack file
+ * changes.
+ */
+async function expandReviewPackTile(
+  browser: Browser,
+  opts: BrowseOpts,
+  dpr: number,
+): Promise<ReviewPackReport> {
+  const packDir = opts.reviewPack as string;
+  const contextId = opts.reviewPackContext as string;
+  const tileId = opts.reviewPackExpand as string;
+  const { tile } = findPackTile([readPackContext(packDir, contextId)], tileId, contextId);
+  const region = await browser.captureRegionByScroll({
+    x: tile.x,
+    y: tile.scrollY,
+    width: tile.width,
+    height: tile.height,
+  });
+  const { record, expanded } = writePackExpandedTile(packDir, contextId, {
+    tileId,
+    dpr,
+    region,
+  });
+  emit.log(
+    `review-pack: ${record.id}/${tileId} expanded at ${dpr}× → ${expanded.width}×${expanded.height} px, ${expanded.file}`,
+    "info",
+  );
+  return {
+    dir: packDir,
+    context_id: record.id,
+    tiles: record.tiles.length,
+    scopes: record.scopes,
+    coverage: record.coverage,
+    files: record.files,
+    expanded,
+  };
+}
+
+/**
+ * Capture-fidelity probe (capture-fidelity.ts). Every band is re-shot by
+ * scrolling the viewport (`Browser.captureRegionByScroll`) and pixel compared
+ * with the crop the tiler took from the full-page screenshot. When they all
+ * agree the tiles stand and the record says `full-page`; when any disagrees,
+ * every band is re-cut from its scrolled capture (same rects, same ids, only
+ * the pixels change) and the record says `scrolled-bands`. A probe that
+ * cannot run, or a re-capture that comes back the wrong size (a page wider
+ * than the viewport), keeps the full-page crop for that band and says so in a
+ * warning. Runs while the capture browser is open; the judge never opens one.
+ */
+async function reconcileCaptureFidelity(
+  browser: Browser,
+  tiles: CritiqueTile[],
+): Promise<{ tiles: CritiqueTile[]; fidelity: PageReviewCaptureFidelity; warnings: string[] }> {
+  const threshold = CAPTURE_FIDELITY_MISMATCH_THRESHOLD;
+  const warnings: string[] = [];
+  const dpr = await browser.currentPage.evaluate(() => window.devicePixelRatio || 1);
+  // Tile rects live in the full-page PNG's pixel space; the scroll capture
+  // takes CSS px and renders at the page's DPR, so the two line up again.
+  const cssRect = (tile: CritiqueTile) => ({
+    x: (tile.x ?? 0) / dpr,
+    y: tile.scrollY / dpr,
+    width: tile.width / dpr,
+    height: tile.height / dpr,
+  });
+  const shots = new Map<number, Buffer | undefined>();
+  const shoot = async (position: number): Promise<Buffer | undefined> => {
+    if (shots.has(position)) return shots.get(position);
+    const tile = tiles[position] as CritiqueTile;
+    let shot: Buffer | undefined;
+    try {
+      const captured = await browser.captureRegionByScroll(cssRect(tile));
+      const size = pngDimensions(captured);
+      if (Math.abs(size.width - tile.width) > 1 || Math.abs(size.height - tile.height) > 1) {
+        warnings.push(
+          `review-pack: scrolled capture of ${tileId(position)} came back ` +
+            `${size.width}×${size.height} px for a ${tile.width}×${tile.height} px band; ` +
+            "its full-page crop was kept",
+        );
+      } else {
+        shot = captured;
+      }
+    } catch (err: unknown) {
+      warnings.push(
+        `review-pack: scrolled capture of ${tileId(position)} failed ` +
+          `(${err instanceof Error ? err.message : String(err)}); its full-page crop was kept`,
+      );
+    }
+    shots.set(position, shot);
+    return shot;
+  };
+  // Every band is probed. A two-band sample (top and middle) missed a raster
+  // artifact that sat elsewhere on the page, and once every band has been
+  // shot by scrolling, the fallback below costs nothing extra: the same shots
+  // become the tiles.
+  const probes: FidelityProbe[] = [];
+  for (let position = 0; position < tiles.length; position++) {
+    const tile = tiles[position] as CritiqueTile;
+    const shot = await shoot(position);
+    if (!shot) continue;
+    const cmp = compareBand(
+      PNG.sync.read(Buffer.from(tile.pngBase64, "base64")),
+      PNG.sync.read(shot),
+      threshold,
+    );
+    probes.push({
+      tile_id: tileId(position),
+      scrollY: tile.scrollY,
+      height: tile.height,
+      mismatch_ratio: cmp.mismatch_ratio,
+    });
+  }
+  const fidelity = decideFidelity(probes, threshold);
+  if (fidelity.source === "full-page") return { tiles, fidelity, warnings };
+  const recut: CritiqueTile[] = [];
+  for (let position = 0; position < tiles.length; position++) {
+    const tile = tiles[position] as CritiqueTile;
+    const shot = await shoot(position);
+    recut.push(shot ? { ...tile, pngBase64: shot.toString("base64") } : tile);
+  }
+  warnings.unshift(
+    `review-pack: the full-page screenshot disagreed with the viewport render on ` +
+      `${fidelity.mismatched.join(", ")} (mismatch ratio above ${threshold}); every band was ` +
+      "re-captured by scrolling the viewport",
+  );
+  return { tiles: recut, fidelity, warnings };
+}
+
+/**
+ * Capture this render into a page review pack: one full-page screenshot,
+ * banded tiles (unless --no-review-pack-bands), one tile set per
+ * --review-pack-scope selector, the serialized DOM, and the QA signature —
+ * all written to disk, with no vision call. The judge stage reads them back
+ * once the browser is gone.
+ */
+async function captureReviewPackContext(
+  browser: Browser,
+  targetArg: string,
+  navResult: { url: string; title: string },
+  opts: BrowseOpts,
+  qaCapture: QaCaptureState | undefined,
+): Promise<ReviewPackReport> {
+  const packDir = opts.reviewPack as string;
+  const { maxTiles, band, overlap } = critiqueTilingKnobs(opts);
+  const buffer = await browser.fullPageScreenshotBuffer();
+  let atoms: Awaited<ReturnType<Browser["visualAtoms"]>> | undefined;
+  try {
+    atoms = await browser.visualAtoms();
+  } catch {
+    atoms = undefined;
+  }
+  const tiling = { bandHeight: band, overlap, maxTiles, atoms };
+  const withBands = opts.reviewPackBands !== false;
+  // Gate-hit rectangles (qa-run lifts them from the gate stage, which runs
+  // first) pull the bands they land in past the cap; those tiles follow the
+  // kept bands as `hit band N`. Coverage still describes the kept prefix.
+  const hitRects = parseReviewPackHitRects(opts.reviewPackHitRect);
+  const banded = withBands
+    ? tilesFromFullPage(buffer, { ...tiling, hitRects, maxHitBands: REVIEW_PACK_HIT_RECT_MAX })
+    : undefined;
+  if (banded?.coverage.capped) {
+    emit.log(
+      `review-pack: page banded to the ${maxTiles}-tile cap (raise --check-critique-max-tiles for full coverage)`,
+      "warn",
+    );
+  }
+  if (banded && banded.hitBands > 0) {
+    emit.log(
+      `review-pack: ${banded.hitBands} band(s) below the tile cap captured for ${hitRects.length} gate-hit rect(s)`,
+      "info",
+    );
+  }
+  // Fidelity: prove the full-page screenshot against scrolled viewport
+  // renders while the browser is still open; on disagreement the bands are
+  // re-cut from scrolled captures (see reconcileCaptureFidelity).
+  let bandTiles = banded?.tiles ?? [];
+  let captureFidelity: PageReviewCaptureFidelity | undefined;
+  const fidelityWarnings: string[] = [];
+  if (bandTiles.length > 0) {
+    const reconciled = await reconcileCaptureFidelity(browser, bandTiles);
+    bandTiles = reconciled.tiles;
+    captureFidelity = reconciled.fidelity;
+    fidelityWarnings.push(...reconciled.warnings);
+    for (const warning of reconciled.warnings) emit.log(warning, "warn");
+    emit.log(
+      `review-pack: capture fidelity ${captureFidelity.source} ` +
+        `(${captureFidelity.probed.length} band(s) probed, ${captureFidelity.mismatched.length} mismatched)`,
+      "info",
+    );
+  }
+  const scopeTiles: Array<{ selector: string; tiles: CritiqueTile[]; coverage: CritiqueCoverage }> =
+    [];
+  for (const selector of opts.reviewPackScope ?? []) {
+    const elementRects = await browser.elementTiles(selector);
+    const scoped = tilesFromFullPage(buffer, { ...tiling, elementRects });
+    if (elementRects.length > maxTiles) {
+      emit.log(
+        `review-pack: ${elementRects.length} elements matched ${selector}, capped to ${maxTiles} tiles`,
+        "warn",
+      );
+    }
+    scopeTiles.push({ selector, tiles: scoped.tiles, coverage: scoped.coverage });
+  }
+  // Coverage: the bands when present, else the scopes folded together
+  // (heights worst-case, band counts add, capped sticky).
+  let coverage: CritiqueCoverage | undefined = banded?.coverage;
+  if (!coverage) {
+    for (const scope of scopeTiles) {
+      coverage = coverage
+        ? {
+            page_height_px: Math.max(coverage.page_height_px, scope.coverage.page_height_px),
+            reviewed_height_px: Math.min(
+              coverage.reviewed_height_px,
+              scope.coverage.reviewed_height_px,
+            ),
+            bands_total: coverage.bands_total + scope.coverage.bands_total,
+            bands_reviewed: coverage.bands_reviewed + scope.coverage.bands_reviewed,
+            capped: coverage.capped || scope.coverage.capped,
+          }
+        : scope.coverage;
+    }
+  }
+  const page = await browser.currentPage.evaluate(() => ({
+    width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0),
+    height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0),
+  }));
+  const capture = qaCapture ?? (await captureQaState(browser, targetArg, navResult.url, opts));
+  const record = writePackContext(packDir, {
+    context: {
+      ...capture.context,
+      ...(opts.reviewPackContext ? { id: opts.reviewPackContext } : {}),
+    },
+    url: navResult.url,
+    title: navResult.title,
+    fullPage: buffer,
+    pageWidth: page.width,
+    pageHeight: page.height,
+    tiles: bandTiles,
+    coverage: coverage ?? {
+      page_height_px: page.height,
+      reviewed_height_px: 0,
+      bands_total: 0,
+      bands_reviewed: 0,
+      capped: false,
+    },
+    scopeTiles: scopeTiles.map(({ selector, tiles }) => ({ selector, tiles })),
+    signature: capture.signature,
+    domHtml: capture.domHtml,
+    ...(captureFidelity ? { captureFidelity } : {}),
+    hitBands: banded?.hitBands ?? 0,
+  });
+  emit.log(
+    `review-pack: ${record.id} → ${record.tiles.length} tile(s)` +
+      (record.scopes.length > 0
+        ? ` (${record.scopes.map((s) => `${s.selector}: ${s.tiles}`).join(", ")})`
+        : "") +
+      ` written to ${packDir}`,
+    "info",
+  );
+  return {
+    dir: packDir,
+    context_id: record.id,
+    tiles: record.tiles.length,
+    scopes: record.scopes,
+    coverage: record.coverage,
+    files: record.files,
+    ...(record.hit_bands !== undefined ? { hit_bands: record.hit_bands } : {}),
+    ...(record.capture_fidelity ? { capture_fidelity: record.capture_fidelity } : {}),
+    ...(fidelityWarnings.length > 0 ? { warnings: fidelityWarnings } : {}),
+  };
+}
+
+async function captureCritiqueTiles(
+  browser: Browser,
+  opts: BrowseOpts,
+  tileBudgetPx?: number,
+): Promise<{ tiles: CritiqueTile[]; fullPage: Buffer; coverage: CritiqueCoverage }> {
+  const { maxTiles, band, overlap } = critiqueTilingKnobs(opts, tileBudgetPx);
 
   // Capture the whole page ONCE, then crop tiles from the pixels. Playwright's
   // clip is viewport-relative, so a below-fold band clip throws ("clipped area
@@ -2183,7 +2619,7 @@ async function captureCritiqueTiles(
   } catch {
     atoms = undefined;
   }
-  const tiles = tilesFromFullPage(buffer, {
+  const { tiles, coverage } = tilesFromFullPage(buffer, {
     elementRects,
     bandHeight: band,
     overlap,
@@ -2202,7 +2638,7 @@ async function captureCritiqueTiles(
       "warn",
     );
   }
-  return { tiles, fullPage: buffer };
+  return { tiles, fullPage: buffer, coverage };
 }
 function logCritiqueSummary(critique: CritiqueResult): void {
   if (critique.outcome === "skipped") {
@@ -2299,6 +2735,46 @@ async function waitForTerminalEnter(signal: AbortSignal): Promise<void> {
   });
 }
 
+/** Upper bound on --review-pack-hit-rect values (and on hit bands cut past the cap). */
+const REVIEW_PACK_HIT_RECT_MAX = 50;
+
+/** `x,y,w,h` integer rectangles from repeated --review-pack-hit-rect flags. */
+function parseReviewPackHitRects(
+  specs: string[] | undefined,
+): Array<{ x: number; y: number; width: number; height: number }> {
+  const list = specs ?? [];
+  if (list.length > REVIEW_PACK_HIT_RECT_MAX) {
+    throw new Error(
+      `--review-pack-hit-rect accepts at most ${REVIEW_PACK_HIT_RECT_MAX} rectangles (got ${list.length}).`,
+    );
+  }
+  return list.map((spec) => {
+    const parts = spec.split(",").map((part) => part.trim());
+    const nums = parts.map((part) => (/^-?\d+$/.test(part) ? Number.parseInt(part, 10) : NaN));
+    if (parts.length !== 4 || nums.some((n) => !Number.isFinite(n))) {
+      throw new Error(
+        `--review-pack-hit-rect must be four integers x,y,w,h in document px (got: ${spec}).`,
+      );
+    }
+    const [x, y, width, height] = nums as [number, number, number, number];
+    if (width < 0 || height < 0) {
+      throw new Error(
+        `--review-pack-hit-rect width and height must not be negative (got: ${spec}).`,
+      );
+    }
+    return { x, y, width, height };
+  });
+}
+
+function parseDeviceScaleFactor(spec: string | undefined): number | undefined {
+  if (spec === undefined) return undefined;
+  const value = Number.parseFloat(spec);
+  if (!Number.isFinite(value) || value < 1 || value > 4) {
+    throw new Error(`--device-scale-factor must be a number between 1 and 4 (got: ${spec})`);
+  }
+  return value;
+}
+
 function parseViewport(spec: string): { width: number; height: number } {
   const preset = VIEWPORT_PRESETS[spec.toLowerCase()];
   if (preset) return preset;