harnery 0.37.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
@@ -237,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 {
@@ -266,8 +286,18 @@ 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") {
@@ -292,6 +322,7 @@ async function runBrowse(url, opts, context) {
         headed,
         jar,
         viewport,
+        ...(deviceScaleFactor !== undefined ? { deviceScaleFactor } : {}),
         ...(colorScheme ? { colorScheme } : {}),
         navigationTimeout: Number.parseInt(opts.timeout, 10),
         waitUntil: opts.waitUntil,
@@ -493,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).
@@ -510,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
                 ? {
@@ -631,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();
@@ -832,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);
@@ -882,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;
         }
@@ -903,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 = [];
@@ -1013,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;
     }
@@ -1388,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",
@@ -1403,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) {
@@ -1435,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
@@ -1462,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,
@@ -1475,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") {
@@ -1560,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/fetch.js

@@ -63,6 +63,7 @@ async function runFetch(url, opts, emit, context) {
             redirect: opts.redirect,
             signal: ac.signal,
             extraHeaders: context?.extraHeaders,
+            extraCookies: context?.extraCookies,
             responseType: "bytes",
         });
     }

package/dist/commands/qa-record.d.ts

@@ -0,0 +1,144 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+import { type QaRunContext, type QaRunResult } from "../lib/browser/qa-run-contracts.js";
+export declare const QA_RECORD_EVIDENCE_SCHEMA_VERSION: 1;
+/** The evidence document is copied into the run directory beside the result:
+ * the run identity's job_digest is taken over it, so without the copy nothing
+ * downstream could re-derive the digest. qa-run writes `job.json` for the same
+ * reason; the manual name keeps the two from being confused. */
+export declare const QA_RECORD_EVIDENCE_FILENAME = "manual-evidence.json";
+/** argv marker for a hand-performed check. The contract types argv as a string
+ * array and consumers print it, so an empty array would render as a command
+ * that ran with no arguments. A single explicit marker reads as "no process
+ * executed" and can never be mistaken for a re-runnable command line. */
+export declare const QA_RECORD_MANUAL_ARGV: readonly ["<manual>"];
+export type QaManualOutcome = "passed" | "failed" | "unknown";
+/** One check a human or agent performed by hand. */
+export interface QaManualCheck {
+    /** Context the check was performed in; matches a `contexts[].id` when the
+     * document declares contexts. */
+    context_id: string;
+    /** Stable check identifier. Prefix with `manual:` by convention. */
+    check_id: string;
+    outcome: QaManualOutcome;
+    /** What the recorder observed. Carried into the result's `failures` field. */
+    notes?: string[];
+    /** Files that back the observation. Every path must exist on disk. */
+    artifacts?: {
+        png?: string;
+        html?: string;
+        json?: string;
+    };
+    /** Time the check took, when the recorder measured it. */
+    wall_time_ms?: number;
+}
+export interface QaManualEvidence {
+    schema_version: typeof QA_RECORD_EVIDENCE_SCHEMA_VERSION;
+    /** Who performed the checks (agent name or operator identity). */
+    recorded_by: string;
+    /** Why the runner could not be used. Required: a hand record with no stated
+     * reason is an assertion, not evidence. */
+    reason: string;
+    checks: QaManualCheck[];
+    /** Declared contexts. Absent: derived from the checks' context IDs. */
+    contexts?: QaRunContext[];
+}
+export type QaManualEvidenceValidation = {
+    ok: true;
+    evidence: QaManualEvidence;
+} | {
+    ok: false;
+    errors: string[];
+};
+/** Artifact paths are resolved against the directory holding the evidence
+ * document, not the working directory: an evidence file names the captures
+ * sitting beside it, and that stays true wherever it is recorded from. */
+export declare function resolveArtifactPath(baseDir: string, path: string): string;
+/**
+ * Validate an untrusted evidence document. Every structural problem, every
+ * missing artifact, and every secret-bearing field is reported at once, before
+ * anything is written: a caller fixes the document in one pass, and a
+ * half-valid record never reaches disk.
+ */
+export declare function validateManualEvidence(value: unknown, options: {
+    baseDir: string;
+}): QaManualEvidenceValidation;
+/** Contexts the result reports: the document's own declarations when it has
+ * them, otherwise one derived per distinct check context ID. Derivation reads
+ * the runner's `<viewport>-<theme>-<state>` convention when the ID follows it
+ * and records `unknown` rather than guessing when it does not. */
+export declare function deriveContexts(evidence: QaManualEvidence): QaRunContext[];
+/** One git probe for the identity block, matching qa-run. Failure is not an
+ * error: work outside any repository legitimately records "unknown". */
+export declare function probeRevision(): {
+    tested_revision?: string;
+    worktree_dirty?: boolean;
+} | undefined;
+export interface BuildManualResultInput {
+    evidence: QaManualEvidence;
+    target: string;
+    mode: "signoff" | "review";
+    /** Parent directory; the result lands in `<outParent>/run-<run_id>/`. */
+    outParent: string;
+    /** Pre-minted run ID (tests); default crypto.randomUUID. */
+    runId?: string;
+    /** Directory the artifact paths resolve against (the evidence file's dir). */
+    baseDir: string;
+    revisionProbe?: {
+        tested_revision?: string;
+        worktree_dirty?: boolean;
+    };
+    /** Completion instant (tests); default now. */
+    completedAt?: Date;
+}
+/**
+ * Build the QaRunResult for a validated evidence document. Pure apart from the
+ * host sample and the clock, so the shape is testable without touching disk.
+ */
+export declare function buildManualResult(input: BuildManualResultInput): QaRunResult;
+export interface QaRecordWritePaths {
+    runDir: string;
+    resultPath: string;
+    evidencePath: string;
+    statusPath: string;
+    latestPath: string;
+}
+/**
+ * Write the run directory exactly the way the runner does: the result, the
+ * source document, a terminal status document, and the parent's latest.json
+ * pointer written temp-then-rename so a reader never sees a torn write.
+ */
+export declare function writeManualRun(result: QaRunResult, evidence: QaManualEvidence): QaRecordWritePaths;
+export interface QaRecordOutcome {
+    /** 1 usage or validation error · 2 verdict failed · 4 verdict incomplete.
+     * Never 0: a hand-recorded result cannot report a pass. */
+    exit: 1 | 2 | 4;
+    result?: QaRunResult;
+    paths?: QaRecordWritePaths;
+    error?: string;
+    /** Individual validation errors, all of them, when the document was bad. */
+    evidenceErrors?: string[];
+}
+export interface QaRecordInput {
+    target: string;
+    evidencePath: string;
+    mode?: string;
+    outDir?: string;
+    /** Lazy default so invalid evidence does not create an empty artifact workspace. */
+    defaultOutDir?: () => string;
+    runId?: string;
+    completedAt?: Date;
+    /** Injectable for tests; default: the real git probe. */
+    revisionProbe?: () => {
+        tested_revision?: string;
+        worktree_dirty?: boolean;
+    } | undefined;
+}
+/**
+ * Pure core of qa-record: read the evidence document, validate it completely,
+ * build the result, and write the run directory. The commander action is a
+ * thin wrapper over this so the whole path tests without a CLI harness.
+ */
+export declare function recordManualQa(input: QaRecordInput): QaRecordOutcome;
+export declare function registerQaRecordCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=qa-record.d.ts.map

package/dist/commands/qa-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"qa-record.d.ts","sourceRoot":"","sources":["../../src/commands/qa-record.ts"],"names":[],"mappings":"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"}