harnery 0.36.0 → 0.38.0

package/dist/commands/browse.js

@@ -1,14 +1,17 @@
 import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, resolve } from "node:path";
+import { PNG } from "pngjs";
 import { resolveBinName } from "../core/config.js";
+import { CAPTURE_FIDELITY_MISMATCH_THRESHOLD, compareBand, decideFidelity, pngDimensions, } from "../lib/browser/capture-fidelity.js";
 import { Browser, browserProxyFromEnv, browserProxyGateFromEnv, captureDevOverlay, DEFAULT_CRITIQUE_RUBRIC, extractObservedIp, parseAssertSpec, runCritique, tilesFromFullPage, WEBRTC_PROXY_ONLY_ARG, writeNetscapeCookieFile, wslHeadedLaunchArgs, } from "../lib/browser/index.js";
+import { findPackTile, readPackContext, tileId, writePackContext, writePackExpandedTile, } from "../lib/browser/page-review-pack.js";
 import { buildQaManifest, classifySignatures, } from "../lib/browser/qa-plan.js";
 import { DEFAULT_REUSE_MISMATCH_RATIO, planCritiqueReuse, QA_CRITIQUE_CONTRACT_VERSION, rubricDigest, } from "../lib/browser/qa-reuse.js";
 import { loadQaSnapshot, resolveQaBaseline, saveQaSnapshot } from "../lib/browser/qa-snapshot.js";
 import { startBrowserSessionServer, } from "../lib/browser/session-control.js";
 import { diffAgainstBaseline, saveBaseline, } from "../lib/browser/visual-diff.js";
-import { CookieJar } from "../lib/cookies/index.js";
+import { applyExtraCookies, CookieJar } from "../lib/cookies/index.js";
 /**
  * `harn browse <url>`: Playwright-backed page navigation with shared
  * cookie jar + persistent profile + diagnostics capture for LLM
@@ -64,6 +67,9 @@ export function registerBrowseCommand(program, emitParam, context, binName = res
         'Example: `--batch "click button; wait 1500; reload; wait 3000"`. `reload` preserves sessionStorage + cookies, which is how to repro sessionStorage-restored UI state.')
         .option("--network-har <path>", "Record network traffic to a HAR file (finalized on close)")
         .option("--viewport <preset|WxH>", "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>", "With --login, wait for this file instead of terminal Enter, then remove it and close cleanly")
         .option("--control-file <path>", "With --login, publish an owner-only descriptor for repeated browse-session control")
@@ -234,6 +240,23 @@ export function registerBrowseCommand(program, emitParam, context, binName = res
         "full fresh review, never an error. Stats land under `qaReuse` in the JSON envelope.")
         .option("--qa-reuse-threshold <ratio>", "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, previous = []) => [...previous, value], [])
+        .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, previous = []) => [...previous, value], [])
+        .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`.")
         .action(async (url, opts) => {
         try {
@@ -263,8 +286,25 @@ async function runBrowse(url, opts, context) {
     const jar = 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;
+    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) {
@@ -282,6 +322,8 @@ async function runBrowse(url, opts, context) {
         headed,
         jar,
         viewport,
+        ...(deviceScaleFactor !== undefined ? { deviceScaleFactor } : {}),
+        ...(colorScheme ? { colorScheme } : {}),
         navigationTimeout: Number.parseInt(opts.timeout, 10),
         waitUntil: opts.waitUntil,
         recordHarPath: opts.networkHar ? resolve(opts.networkHar) : undefined,
@@ -482,12 +524,26 @@ async function runBrowse(url, opts, context) {
                 emit.log(`qa-reuse: ${qaReuse.tiles_reused}/${qaReuse.tiles_total} tiles reused (band-diff), ` +
                     `${qaReuse.tiles_reviewed} reviewed fresh${qaReuse.invalidation ? ` — ${qaReuse.invalidation}` : ""}`, "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;
+        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).
@@ -499,6 +555,7 @@ async function runBrowse(url, opts, context) {
             const fullCoverage = critique?.provider &&
                 critique.outcome !== "skipped" &&
                 critiqueTiles !== undefined &&
+                !critique.coverage?.capped &&
                 (!qaReuse || qaReuse.tiles_reused === 0);
             const persistedCritique = fullCoverage && critique && critiqueTiles
                 ? {
@@ -620,10 +677,10 @@ async function runBrowse(url, opts, context) {
             if (opts.baseline || opts.diff) {
                 throw new Error("--baseline / --diff require trio mode (screenshot file). Remove --snapshot/--html/--json or capture the screenshot first.");
             }
-            await runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse ? summarizeReuse(qaReuse) : undefined);
+            await runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse ? summarizeReuse(qaReuse) : undefined, reviewPack);
         }
         else {
-            await runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse ? summarizeReuse(qaReuse) : undefined);
+            await runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse ? summarizeReuse(qaReuse) : undefined, reviewPack);
         }
         if (visibility && opts.checkVisibleAnnotate !== false) {
             await browser.clearVisibilityAnnotations();
@@ -821,7 +878,7 @@ function splitBatchSteps(input) {
 // ---------------------------------------------------------------------------
 // Print mode (--snapshot / --html / --json): stdout, no file writes
 // ---------------------------------------------------------------------------
-async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse) {
+async function runPrintMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse, reviewPack) {
     let body = null;
     if (opts.html) {
         body = await browser.htmlContent(opts.selector);
@@ -871,6 +928,8 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
             result.qaPlan = qaPlan;
         if (qaReuse)
             result.qaReuse = qaReuse;
+        if (reviewPack)
+            result.reviewPack = reviewPack;
         if (batchResult && batchResult.clipboardReads.length > 0) {
             result.batchClipboardReads = batchResult.clipboardReads;
         }
@@ -892,7 +951,7 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
 // ---------------------------------------------------------------------------
 // Trio mode (default): write <prefix>.{png,html,json}
 // ---------------------------------------------------------------------------
-async function runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse) {
+async function runTrioMode(browser, navResult, opts, evalResult, visibility, widths, overflow, runts, layoutLint, hit, content, critique, asserts, devOverlay, batchResult, qaPlan, qaReuse, reviewPack) {
     const prefix = resolveOutPrefix(opts.out);
     mkdirSync(dirname(prefix), { recursive: true });
     const written = [];
@@ -1002,6 +1061,8 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         envelope.qaPlan = qaPlan;
     if (qaReuse)
         envelope.qaReuse = qaReuse;
+    if (reviewPack)
+        envelope.reviewPack = reviewPack;
     if (batchResult && batchResult.clipboardReads.length > 0) {
         envelope.batchClipboardReads = batchResult.clipboardReads;
     }
@@ -1377,7 +1438,9 @@ function summarizeReuse(plan) {
  * 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(browser, targetArg, renderedUrl, opts) {
+/** 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, targetArg, renderedUrl, opts) {
     const context = {
         viewport: opts.viewport ?? "desktop",
         theme: opts.qaTheme === "dark" ? "dark" : "light",
@@ -1392,11 +1455,16 @@ async function runQaPlanning(browser, targetArg, renderedUrl, opts) {
         stylesheets: captured.stylesheets,
         ...(captured.truncated ? { truncated: true } : {}),
     };
+    return { target, context, signature, domHtml: captured.domHtml };
+}
+async function runQaPlanning(browser, targetArg, renderedUrl, opts) {
+    const capture = await captureQaState(browser, targetArg, renderedUrl, opts);
+    const { target, context, signature } = capture;
     const report = {
         signature: {
-            nodes: captured.nodes.length,
-            stylesheets: captured.stylesheets.length,
-            truncated: captured.truncated,
+            nodes: signature.nodes.length,
+            stylesheets: signature.stylesheets.length,
+            truncated: Boolean(signature.truncated),
         },
     };
     if (opts.qaPlan) {
@@ -1424,15 +1492,256 @@ async function runQaPlanning(browser, targetArg, renderedUrl, opts) {
             estimatedFullPageTiles,
         });
     }
-    return { report, capture: { target, context, signature, domHtml: captured.domHtml } };
+    return { report, capture };
 }
-async function captureCritiqueTiles(browser, opts, tileBudgetPx) {
+/** 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, tileBudgetPx) {
     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 };
+}
+/**
+ * `--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, opts, dpr) {
+    const packDir = opts.reviewPack;
+    const contextId = opts.reviewPackContext;
+    const tileId = opts.reviewPackExpand;
+    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, tiles) {
+    const threshold = CAPTURE_FIDELITY_MISMATCH_THRESHOLD;
+    const warnings = [];
+    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) => ({
+        x: (tile.x ?? 0) / dpr,
+        y: tile.scrollY / dpr,
+        width: tile.width / dpr,
+        height: tile.height / dpr,
+    });
+    const shots = new Map();
+    const shoot = async (position) => {
+        if (shots.has(position))
+            return shots.get(position);
+        const tile = tiles[position];
+        let shot;
+        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) {
+            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 = [];
+    for (let position = 0; position < tiles.length; position++) {
+        const tile = tiles[position];
+        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 = [];
+    for (let position = 0; position < tiles.length; position++) {
+        const tile = tiles[position];
+        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, targetArg, navResult, opts, qaCapture) {
+    const packDir = opts.reviewPack;
+    const { maxTiles, band, overlap } = critiqueTilingKnobs(opts);
+    const buffer = await browser.fullPageScreenshotBuffer();
+    let atoms;
+    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;
+    const fidelityWarnings = [];
+    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 = [];
+    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 = 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, opts, tileBudgetPx) {
+    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
     // outside the resulting image") — cropping the full-page image sidesteps that
@@ -1451,7 +1760,7 @@ async function captureCritiqueTiles(browser, opts, tileBudgetPx) {
     catch {
         atoms = undefined;
     }
-    const tiles = tilesFromFullPage(buffer, {
+    const { tiles, coverage } = tilesFromFullPage(buffer, {
         elementRects,
         bandHeight: band,
         overlap,
@@ -1464,7 +1773,7 @@ async function captureCritiqueTiles(browser, opts, tileBudgetPx) {
     else if (!elementRects && tiles.length >= maxTiles) {
         emit.log(`check-critique: page banded to the ${maxTiles}-tile cap (raise --check-critique-max-tiles for full coverage)`, "warn");
     }
-    return { tiles, fullPage: buffer };
+    return { tiles, fullPage: buffer, coverage };
 }
 function logCritiqueSummary(critique) {
     if (critique.outcome === "skipped") {
@@ -1549,6 +1858,36 @@ async function waitForTerminalEnter(signal) {
         signal.addEventListener("abort", onAbort, { once: true });
     });
 }
+/** 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) {
+    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;
+        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) {
+    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) {
     const preset = VIEWPORT_PRESETS[spec.toLowerCase()];
     if (preset)

package/dist/commands/diagnostics.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export declare function registerDiagnosticsCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/commands/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/commands/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAyB1E,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAiKN"}