harnery 0.38.0 → 0.40.0

package/dist/commands/browse.js

@@ -3,13 +3,19 @@ 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 { CAPTURE_FIDELITY_MISMATCH_THRESHOLD, compareBand, cropNativePng, 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 { allocateTileBudget, validatePageReviewAllocation, } from "../lib/browser/page-review-budget.js";
+import { PAGE_REVIEW_CAPTURE_PLAN_SCHEMA, } from "../lib/browser/page-review-contracts.js";
+import { findPackTile, gateHitsFromEnvelope, readPackContext, tileId, writePackContext, writePackExpandedTile, } from "../lib/browser/page-review-pack.js";
+import { retainPageReviewSourceIdentity } from "../lib/browser/page-review-source.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 { allocateCaptureReservation, assertGatePlanStable, CaptureSourceChanged, runCaptureTransaction, writeCaptureTransaction, } from "../lib/browser/review-capture-transaction.js";
 import { startBrowserSessionServer, } from "../lib/browser/session-control.js";
+import { captureThumbnailFingerprint, registerCaptureThumbnail, } from "../lib/browser/thumbnail-association.js";
+import { reviewCandidateRects } from "../lib/browser/tiling.js";
 import { diffAgainstBaseline, saveBaseline, } from "../lib/browser/visual-diff.js";
 import { applyExtraCookies, CookieJar } from "../lib/cookies/index.js";
 /**
@@ -244,17 +250,19 @@ export function registerBrowseCommand(program, emitParam, context, binName = res
         "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-plan", "Emit all native capture candidates and gate associations without capturing tiles. " +
+        "With --out, retain private source identity inputs beside the output for diagnostics.")
+        .option("--review-pack-allocation <json-file>", "Capture exactly the selected IDs in a verified context allocation.")
+        .option("--review-pack-reservation <json-file>", "Reserve the preliminary allocation's tile count, then rerun supplied gates and allocate against the same page before capture. Full source checks and native coverage remain required.")
         .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("--review-pack-hit-rect <x,y,w,h>", "Document-space rectangle (integer px) a deterministic gate already flagged. " +
+        "Intersecting bands are prioritized within the hard tile cap " +
+        `(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`.")
@@ -291,6 +299,13 @@ async function runBrowse(url, opts, context) {
     const headed = opts.login || opts.headed;
     const viewport = parseViewport(opts.viewport ?? "desktop");
     const deviceScaleFactor = parseDeviceScaleFactor(opts.deviceScaleFactor);
+    if (opts.reviewPackAllocation && !opts.reviewPack) {
+        throw new Error("--review-pack-allocation requires --review-pack <dir>.");
+    }
+    if (opts.reviewPackReservation &&
+        (!opts.reviewPack || opts.reviewPackAllocation || opts.reviewPackExpand || opts.checkCritique)) {
+        throw new Error("--review-pack-reservation requires an ordinary --review-pack capture without allocation, expansion or inline critique.");
+    }
     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>.");
@@ -371,110 +386,182 @@ async function runBrowse(url, opts, context) {
         if (opts.evaluate) {
             evalResult = await browser.evaluate(opts.evaluate);
         }
+        if (opts.reviewPackPlan || opts.reviewPack)
+            await browser.waitForReviewReady();
         // Run visibility checks AFTER any --batch interactions but BEFORE the
         // screenshot. Annotation injection happens between sampling and capture
         // so the boxes show on the saved PNG; they're cleared post-screenshot
         // so the live profile state isn't polluted.
-        let visibility;
-        if (opts.checkVisible && opts.checkVisible.length > 0) {
-            visibility = await browser.checkVisibility(opts.checkVisible, {
-                sampleGrid: Number.parseInt(opts.checkVisibleSampleGrid ?? "3", 10),
-            });
-            if (opts.checkVisibleAnnotate !== false) {
-                await browser.annotateVisibility(visibility);
+        const collectGates = async (attempt = 0) => {
+            const before = opts.reviewPackReservation
+                ? await buildReviewCapturePlan(browser, opts)
+                : undefined;
+            let visibility;
+            if (opts.checkVisible && opts.checkVisible.length > 0) {
+                visibility = await browser.checkVisibility(opts.checkVisible, {
+                    sampleGrid: Number.parseInt(opts.checkVisibleSampleGrid ?? "3", 10),
+                });
+                if (opts.checkVisibleAnnotate !== false && !opts.reviewPackPlan && !opts.reviewPack) {
+                    await browser.annotateVisibility(visibility);
+                }
             }
-        }
-        let widths;
-        if (opts.checkWidth && opts.checkWidth.length > 0) {
-            widths = await browser.checkWidth(opts.checkWidth);
-        }
-        let overflow;
-        if (opts.checkOverflow) {
-            overflow = await browser.checkOverflow();
-        }
-        let runts;
-        if (opts.checkRunts) {
-            runts = await browser.checkRunts({
-                scope: typeof opts.checkRunts === "string" ? opts.checkRunts : null,
-                minChars: Number.parseInt(opts.checkRuntsMinChars ?? "40", 10),
-            });
-        }
-        const hasLayoutLint = (opts.checkAlign?.length ?? 0) > 0 ||
-            (opts.checkGap?.length ?? 0) > 0 ||
-            (opts.checkClip?.length ?? 0) > 0 ||
-            (opts.checkOverlap?.length ?? 0) > 0 ||
-            (opts.checkCrowd?.length ?? 0) > 0;
-        let layoutLint;
-        if (hasLayoutLint) {
-            layoutLint = await browser.checkLayoutLint({
-                align: (opts.checkAlign ?? []).map((selector) => ({
-                    selector,
-                    axis: alignAxis,
-                    tolerancePx: alignThreshold,
-                })),
-                gap: (opts.checkGap ?? []).map((selector) => ({
-                    selector,
-                    axis: gapAxis,
-                    tolerancePx: gapThreshold,
-                    expectedGapPx: gapExpected,
-                })),
-                clip: (opts.checkClip ?? []).map((selector) => ({
-                    selector,
-                    tolerancePx: clipThreshold,
-                })),
-                overlap: (opts.checkOverlap ?? []).map((selector) => ({
-                    selector,
-                    tolerancePx: overlapThreshold,
-                })),
-                crowd: (opts.checkCrowd ?? []).map((selector) => ({
-                    selector,
-                    minGapPx: crowdMin,
-                })),
-            });
-        }
-        let hit;
-        if (opts.checkHit && opts.checkHit.length > 0) {
-            hit = await browser.checkTargetSize(opts.checkHit, hitProfile);
-        }
-        const hasContentChecks = opts.checkPlaceholder !== undefined ||
-            opts.checkImages !== undefined ||
-            opts.checkTruncation !== undefined ||
-            opts.checkContrast !== undefined;
-        let content;
-        if (hasContentChecks) {
-            content = await browser.checkContent({
-                placeholder: opts.checkPlaceholder !== undefined
-                    ? { scope: contentScope(opts.checkPlaceholder) }
-                    : null,
-                image: opts.checkImages !== undefined
-                    ? {
-                        scope: contentScope(opts.checkImages),
-                        tolerance: parseNonNegativeNumber(opts.checkImagesTolerance ?? "0.1", "--check-images-tolerance"),
-                    }
-                    : null,
-                truncation: opts.checkTruncation !== undefined
-                    ? {
-                        scope: contentScope(opts.checkTruncation),
-                        tolerance: parseNonNegativeNumber(opts.checkTruncationTolerance ?? "2", "--check-truncation-tolerance"),
-                    }
-                    : null,
-                contrast: opts.checkContrast !== undefined ? { scope: contentScope(opts.checkContrast) } : null,
-            });
-        }
-        // Diff-aware QA planning. Signature capture must also happen BEFORE any
-        // annotation overlays are injected — an annotation box is a DOM change.
-        let qaPlan;
-        let qaCapture;
-        if (opts.qaPlan || opts.qaSnapshot) {
-            const qa = await runQaPlanning(browser, url, navResult.url, opts);
-            qaPlan = qa.report;
-            qaCapture = qa.capture;
-            if (qaPlan?.manifest) {
-                const m = qaPlan.manifest;
-                emit.log(`qa-plan: class=${m.change_class} scopes=${m.scopes.map((s) => s.selector).join(",") || "-"} ` +
-                    `contexts=${m.contexts.length} model-calls<=${m.predicted.model_calls_ceiling} baseline=${m.baseline_source}`, "info");
+            let widths;
+            if (opts.checkWidth && opts.checkWidth.length > 0) {
+                widths = await browser.checkWidth(opts.checkWidth);
             }
-        }
+            let overflow;
+            if (opts.checkOverflow) {
+                overflow = await browser.checkOverflow();
+            }
+            let runts;
+            if (opts.checkRunts) {
+                runts = await browser.checkRunts({
+                    scope: typeof opts.checkRunts === "string" ? opts.checkRunts : null,
+                    minChars: Number.parseInt(opts.checkRuntsMinChars ?? "40", 10),
+                });
+            }
+            const hasLayoutLint = (opts.checkAlign?.length ?? 0) > 0 ||
+                (opts.checkGap?.length ?? 0) > 0 ||
+                (opts.checkClip?.length ?? 0) > 0 ||
+                (opts.checkOverlap?.length ?? 0) > 0 ||
+                (opts.checkCrowd?.length ?? 0) > 0;
+            let layoutLint;
+            if (hasLayoutLint) {
+                layoutLint = await browser.checkLayoutLint({
+                    align: (opts.checkAlign ?? []).map((selector) => ({
+                        selector,
+                        axis: alignAxis,
+                        tolerancePx: alignThreshold,
+                    })),
+                    gap: (opts.checkGap ?? []).map((selector) => ({
+                        selector,
+                        axis: gapAxis,
+                        tolerancePx: gapThreshold,
+                        expectedGapPx: gapExpected,
+                    })),
+                    clip: (opts.checkClip ?? []).map((selector) => ({
+                        selector,
+                        tolerancePx: clipThreshold,
+                    })),
+                    overlap: (opts.checkOverlap ?? []).map((selector) => ({
+                        selector,
+                        tolerancePx: overlapThreshold,
+                    })),
+                    crowd: (opts.checkCrowd ?? []).map((selector) => ({
+                        selector,
+                        minGapPx: crowdMin,
+                    })),
+                });
+            }
+            let hit;
+            if (opts.checkHit && opts.checkHit.length > 0) {
+                hit = await browser.checkTargetSize(opts.checkHit, hitProfile);
+            }
+            const hasContentChecks = opts.checkPlaceholder !== undefined ||
+                opts.checkImages !== undefined ||
+                opts.checkTruncation !== undefined ||
+                opts.checkContrast !== undefined;
+            let content;
+            if (hasContentChecks) {
+                content = await browser.checkContent({
+                    placeholder: opts.checkPlaceholder !== undefined
+                        ? { scope: contentScope(opts.checkPlaceholder) }
+                        : null,
+                    image: opts.checkImages !== undefined
+                        ? {
+                            scope: contentScope(opts.checkImages),
+                            tolerance: parseNonNegativeNumber(opts.checkImagesTolerance ?? "0.1", "--check-images-tolerance"),
+                        }
+                        : null,
+                    truncation: opts.checkTruncation !== undefined
+                        ? {
+                            scope: contentScope(opts.checkTruncation),
+                            tolerance: parseNonNegativeNumber(opts.checkTruncationTolerance ?? "2", "--check-truncation-tolerance"),
+                        }
+                        : null,
+                    contrast: opts.checkContrast !== undefined ? { scope: contentScope(opts.checkContrast) } : null,
+                });
+            }
+            // Diff-aware QA planning. Signature capture must also happen BEFORE any
+            // annotation overlays are injected — an annotation box is a DOM change.
+            let qaPlan;
+            let qaCapture;
+            if (opts.qaPlan || opts.qaSnapshot) {
+                const qa = await runQaPlanning(browser, url, navResult.url, opts);
+                qaPlan = qa.report;
+                qaCapture = qa.capture;
+                if (qaPlan?.manifest) {
+                    const m = qaPlan.manifest;
+                    emit.log(`qa-plan: class=${m.change_class} scopes=${m.scopes.map((s) => s.selector).join(",") || "-"} ` +
+                        `contexts=${m.contexts.length} model-calls<=${m.predicted.model_calls_ceiling} baseline=${m.baseline_source}`, "info");
+                }
+            }
+            let asserts;
+            if (opts.assert && opts.assert.length > 0) {
+                const specs = opts.assert.map(parseAssertSpec);
+                asserts = await browser.checkAsserts(specs);
+            }
+            if (opts.reviewPackPlan || opts.reviewPackReservation) {
+                const gateEnvelope = { runts, overflow, hit, ...layoutLint };
+                if (content)
+                    assignContent(gateEnvelope, content);
+                opts.capturePlanResult = await buildReviewCapturePlan(browser, opts);
+                const hits = gateHitsFromEnvelope(gateEnvelope, Number.POSITIVE_INFINITY);
+                for (const candidate of opts.capturePlanResult.candidates) {
+                    const r = candidate.rect;
+                    candidate.gate_hits = hits.flatMap((hit, index) => {
+                        const dpr = opts.capturePlanResult.dpr;
+                        const h = {
+                            x: hit.rect.x * dpr,
+                            y: hit.rect.y * dpr,
+                            width: Math.max(1, hit.rect.width * dpr),
+                            height: Math.max(1, hit.rect.height * dpr),
+                        };
+                        return r.x < h.x + h.width &&
+                            r.x + r.width > h.x &&
+                            r.y < h.y + h.height &&
+                            r.y + r.height > h.y
+                            ? [{ check_id: `${hit.rule}:${index + 1}`, severity: "high" }]
+                            : [];
+                    });
+                }
+            }
+            if (opts.reviewPackReservation) {
+                const prefix = opts.out ?? resolve(opts.reviewPack, opts.reviewPackContext ?? "capture");
+                mkdirSync(dirname(prefix), { recursive: true, mode: 0o700 });
+                writeFileSync(`${prefix}.attempt-${attempt}.gates.json`, JSON.stringify({
+                    attempt,
+                    source_before: before?.source_digest,
+                    source_after: opts.capturePlanResult?.source_digest,
+                    source_evidence: opts.captureSourceEvidence,
+                    visibility,
+                    widths,
+                    overflow,
+                    runts,
+                    layoutLint,
+                    hit,
+                    content,
+                    asserts,
+                }, null, 2), { mode: 0o600 });
+            }
+            if (before)
+                assertGatePlanStable(before, opts.capturePlanResult);
+            return {
+                visibility,
+                widths,
+                overflow,
+                runts,
+                layoutLint,
+                hit,
+                content,
+                qaPlan,
+                qaCapture,
+                asserts,
+            };
+        };
+        let { visibility, widths, overflow, runts, layoutLint, hit, content, qaPlan, qaCapture, asserts, } = opts.reviewPackReservation
+            ? {}
+            : await collectGates();
         // Vision critique. Capture tiles BEFORE any annotation overlays are injected
         // so the model sees the real page, not our boxes.
         let critique;
@@ -542,6 +629,52 @@ async function runBrowse(url, opts, context) {
         if (opts.reviewPack !== undefined && opts.reviewPackExpand !== undefined) {
             reviewPack = await expandReviewPackTile(browser, opts, deviceScaleFactor ?? 1);
         }
+        else if (opts.reviewPackReservation) {
+            const reservation = JSON.parse(readFileSync(resolve(opts.reviewPackReservation), "utf8"));
+            opts.captureTransaction = { attempts: [] };
+            const persistTransaction = () => {
+                const prefix = opts.out ?? resolve(opts.reviewPack, opts.reviewPackContext ?? "capture");
+                mkdirSync(dirname(prefix), { recursive: true, mode: 0o700 });
+                writeFileSync(`${prefix}.capture-transaction.json`, JSON.stringify(opts.captureTransaction, null, 2), { mode: 0o600 });
+            };
+            reviewPack = await runCaptureTransaction(async (attempt) => {
+                await browser.waitForReviewReady();
+                ({
+                    visibility,
+                    widths,
+                    overflow,
+                    runts,
+                    layoutLint,
+                    hit,
+                    content,
+                    qaPlan,
+                    qaCapture,
+                    asserts,
+                } = await collectGates(attempt));
+                opts.captureTransactionAllocation = allocateCaptureReservation(reservation, opts.capturePlanResult);
+                opts.captureTransaction.attempts.push({
+                    attempt,
+                    status: "gated",
+                    source_digest: opts.capturePlanResult.source_digest,
+                });
+                persistTransaction();
+            }, async () => {
+                const captured = await captureReviewPackContext(browser, url, navResult, opts, qaCapture);
+                opts.captureTransaction.source_digest =
+                    opts.captureTransactionAllocation.plan.source_digest;
+                opts.captureTransaction.attempts.at(-1).status = "captured";
+                persistTransaction();
+                return captured;
+            }, (attempt, error) => {
+                opts.captureTransaction.attempts.push({
+                    attempt,
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                    source_digest: opts.capturePlanResult?.source_digest,
+                });
+                persistTransaction();
+            });
+        }
         else if (opts.reviewPack !== undefined) {
             reviewPack = await captureReviewPackContext(browser, url, navResult, opts, qaCapture);
         }
@@ -590,11 +723,6 @@ async function runBrowse(url, opts, context) {
                 `[${qaCapture.context.viewport}/${qaCapture.context.theme}/${qaCapture.context.state}]` +
                 `${persistedCritique ? " (with critique results)" : ""}`, "info");
         }
-        let asserts;
-        if (opts.assert && opts.assert.length > 0) {
-            const specs = opts.assert.map(parseAssertSpec);
-            asserts = await browser.checkAsserts(specs);
-        }
         const widthThreshold = Number.parseFloat(opts.checkWidthThreshold ?? "0.9");
         const annotateWidth = widths && opts.checkWidthAnnotate !== false;
         const annotateOverflow = overflow && opts.checkOverflowAnnotate !== false;
@@ -930,6 +1058,12 @@ async function runPrintMode(browser, navResult, opts, evalResult, visibility, wi
             result.qaReuse = qaReuse;
         if (reviewPack)
             result.reviewPack = reviewPack;
+        if (opts.capturePlanResult)
+            result.review_pack_capture_plan = opts.capturePlanResult;
+        if (opts.captureSourceEvidence)
+            result.review_pack_source_evidence = opts.captureSourceEvidence;
+        if (opts.captureTransaction)
+            result.review_pack_transaction = opts.captureTransaction;
         if (batchResult && batchResult.clipboardReads.length > 0) {
             result.batchClipboardReads = batchResult.clipboardReads;
         }
@@ -958,6 +1092,7 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
     const skipScreenshot = opts.screenshot === false;
     let pngPath;
     let pngBytes;
+    let pngFingerprint = null;
     let captureEvalResult;
     let captureViewport;
     let captureEvidence;
@@ -975,6 +1110,8 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         else {
             pngBytes = await browser.screenshot(pngPath, { fullPage: opts.fullPage !== false });
         }
+        if (!opts.selector && opts.fullPage !== false)
+            pngFingerprint = captureThumbnailFingerprint(pngPath);
         written.push(pngPath);
     }
     else if (opts.captureEvaluate) {
@@ -999,6 +1136,17 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         }
     }
     written.push(htmlPath);
+    const thumbnailAssociation = snapshot && pngPath && pngFingerprint
+        ? registerCaptureThumbnail({
+            htmlPath,
+            pngPath,
+            html: snapshot.html,
+            preview: pngFingerprint,
+            fullDocument: !opts.selector && opts.fullPage !== false,
+            stylesheetsLinked: snapshot.stylesheetsLinked,
+            resourcesLinked: snapshot.resourcesLinked,
+        })
+        : null;
     const diag = browser.diagnostics();
     const jsonPath = `${prefix}.json`;
     const envelope = {
@@ -1014,6 +1162,8 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
     };
     if (pngBytes !== undefined)
         envelope.screenshotBytes = pngBytes;
+    if (thumbnailAssociation)
+        envelope.thumbnailAssociation = thumbnailAssociation;
     if (snapshot) {
         envelope.htmlSnapshot = {
             stylesheetsInlined: snapshot.stylesheetsInlined,
@@ -1063,6 +1213,12 @@ async function runTrioMode(browser, navResult, opts, evalResult, visibility, wid
         envelope.qaReuse = qaReuse;
     if (reviewPack)
         envelope.reviewPack = reviewPack;
+    if (opts.capturePlanResult)
+        envelope.review_pack_capture_plan = opts.capturePlanResult;
+    if (opts.captureSourceEvidence)
+        envelope.review_pack_source_evidence = opts.captureSourceEvidence;
+    if (opts.captureTransaction)
+        envelope.review_pack_transaction = opts.captureTransaction;
     if (batchResult && batchResult.clipboardReads.length > 0) {
         envelope.batchClipboardReads = batchResult.clipboardReads;
     }
@@ -1517,12 +1673,14 @@ 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 originalContext = readPackContext(packDir, contextId);
+    const { tile } = findPackTile([originalContext], tileId, contextId);
+    const originalDpr = originalContext.dpr;
     const region = await browser.captureRegionByScroll({
-        x: tile.x,
-        y: tile.scrollY,
-        width: tile.width,
-        height: tile.height,
+        x: tile.x / originalDpr,
+        y: tile.scrollY / originalDpr,
+        width: tile.width / originalDpr,
+        height: tile.height / originalDpr,
     });
     const { record, expanded } = writePackExpandedTile(packDir, contextId, {
         tileId,
@@ -1547,9 +1705,9 @@ async function expandReviewPackTile(browser, opts, dpr) {
  * 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.
+ * cannot run, or a re-capture with the wrong size, leaves a missing probe;
+ * the caller refuses to save that context. Runs while the capture browser
+ * is open; the judge never opens one.
  */
 async function reconcileCaptureFidelity(browser, tiles) {
     const threshold = CAPTURE_FIDELITY_MISMATCH_THRESHOLD;
@@ -1564,30 +1722,22 @@ async function reconcileCaptureFidelity(browser, tiles) {
         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);
+    try {
+        const captured = await browser.captureRegionsByScroll(tiles.map(cssRect));
+        for (const [position, shot] of captured.entries()) {
+            const tile = tiles[position];
+            const size = pngDimensions(shot);
             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;
+                warnings.push(`Native scrolled capture of ${tileId(position)} has different dimensions; probe incomplete.`);
             }
+            else
+                shots.set(position, shot);
         }
-        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;
-    };
+    }
+    catch (error) {
+        warnings.push(`Native scrolled capture failed: ${error instanceof Error ? error.message : String(error)}; probe incomplete.`);
+    }
+    const shoot = async (position) => shots.get(position);
     // 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
@@ -1622,112 +1772,198 @@ async function reconcileCaptureFidelity(browser, tiles) {
 }
 /**
  * Capture this render into a page review pack: one full-page screenshot,
- * banded tiles (unless --no-review-pack-bands), one tile set per
+ * budgeted native tiles, one candidate 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.
  */
+export const REVIEW_CAPTURE_RECIPE = "native-full-page-scroll-probe/v2";
+async function buildReviewCapturePlan(browser, opts) {
+    await browser.currentPage.evaluate(() => document.fonts.ready);
+    const geometry = await browser.currentPage.evaluate(() => ({
+        dpr: window.devicePixelRatio || 1,
+        width: Math.max(document.documentElement.scrollWidth, document.body?.scrollWidth ?? 0),
+        height: Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0),
+        viewportWidth: window.innerWidth,
+        viewportHeight: window.innerHeight,
+    }));
+    const { dpr } = geometry;
+    const signature = await browser.qaSignature();
+    // Attribute insertion order is serialization noise, not a source change.
+    // Parse an inert document so canonicalization cannot mutate the rendered page.
+    const canonicalDom = await browser.currentPage.evaluate((html) => {
+        const document = new DOMParser().parseFromString(html, "text/html");
+        for (const el of Array.from(document.querySelectorAll("*"))) {
+            const attrs = Array.from(el.attributes)
+                .map((a) => ({ name: a.name, value: a.value, ns: a.namespaceURI }))
+                .sort((a, b) => a.name.localeCompare(b.name));
+            for (const a of Array.from(el.attributes))
+                el.removeAttributeNode(a);
+            for (const a of attrs)
+                el.setAttributeNS(a.ns, a.name, a.value);
+        }
+        return document.documentElement.outerHTML;
+    }, signature.domHtml);
+    const source = retainPageReviewSourceIdentity({ nodes: signature.nodes, stylesheets: signature.stylesheets, dom: canonicalDom }, opts.out ?? (opts.reviewPack ? resolve(opts.reviewPack, "source") : undefined));
+    opts.captureSourceEvidence = source.evidence;
+    const atoms = (await browser.visualAtoms()).map((a) => ({
+        ...a,
+        top: Math.round(a.top * dpr),
+        bottom: Math.round(a.bottom * dpr),
+    }));
+    const { band, overlap } = critiqueTilingKnobs(opts);
+    const scopes = [];
+    for (const selector of opts.reviewPackScope ?? []) {
+        const rects = (await browser.elementTiles(selector)).map((r) => ({
+            ...r,
+            x: Math.round(r.x * dpr),
+            y: Math.round(r.y * dpr),
+            width: Math.round(r.width * dpr),
+            height: Math.round(r.height * dpr),
+        }));
+        scopes.push({ selector, rects });
+    }
+    const theme = opts.qaTheme === "dark" ? "dark" : "light";
+    const viewport = opts.viewport ?? "desktop", state = opts.qaState ?? "default";
+    return {
+        schema: PAGE_REVIEW_CAPTURE_PLAN_SCHEMA,
+        context_id: opts.reviewPackContext ?? `${viewport}--${theme}--${state}`,
+        viewport,
+        viewport_width: geometry.viewportWidth,
+        viewport_height: geometry.viewportHeight,
+        theme,
+        state,
+        dpr,
+        page_width: Math.round(geometry.width * dpr),
+        page_height: Math.round(geometry.height * dpr),
+        source_digest: source.digest,
+        recipe_version: REVIEW_CAPTURE_RECIPE,
+        required_scopes: opts.reviewPackScope ?? [],
+        candidates: reviewCandidateRects({
+            width: Math.round(geometry.width * dpr),
+            height: Math.round(geometry.height * dpr),
+            bandHeight: band,
+            overlap,
+            atoms,
+            scopes,
+        }),
+    };
+}
 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 plan = await buildReviewCapturePlan(browser, opts);
+    let allocation;
+    if (opts.captureTransactionAllocation) {
+        try {
+            allocation = validatePageReviewAllocation(opts.captureTransactionAllocation, plan);
+        }
+        catch (error) {
+            throw new CaptureSourceChanged(String(error));
+        }
     }
-    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;
+    else if (opts.reviewPackAllocation) {
+        try {
+            allocation = validatePageReviewAllocation(JSON.parse(readFileSync(resolve(opts.reviewPackAllocation), "utf8")), plan);
+        }
+        catch (error) {
+            if (error instanceof Error && opts.captureSourceEvidence)
+                error.message += ` Current source identity: ${opts.captureSourceEvidence.path} (sha256 ${plan.source_digest}).`;
+            throw error;
         }
     }
-    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),
+    else {
+        // Standalone capture retains its 24-tile default; it still obeys one hard total.
+        const maxTiles = critiqueTilingKnobs(opts).maxTiles;
+        const hits = parseReviewPackHitRects(opts.reviewPackHitRect);
+        for (const c of plan.candidates) {
+            c.gate_hits = hits.flatMap((h, i) => c.rect.x < (h.x + h.width) * plan.dpr &&
+                c.rect.x + c.rect.width > h.x * plan.dpr &&
+                c.rect.y < (h.y + h.height) * plan.dpr &&
+                c.rect.y + c.rect.height > h.y * plan.dpr
+                ? [{ check_id: `hit:${i + 1}`, severity: "high" }]
+                : []);
+        }
+        allocation = allocateTileBudget([plan], maxTiles).contexts[0];
+    }
+    const start = performance.now();
+    const buffer = await browser.fullPageScreenshotBuffer();
+    const size = pngDimensions(buffer);
+    if (size.width !== plan.page_width || size.height !== plan.page_height)
+        throw opts.captureTransactionAllocation
+            ? new CaptureSourceChanged("Page review image geometry changed after planning.")
+            : new Error("Page review image geometry changed after planning; rerun the review.");
+    const decoded = PNG.sync.read(buffer);
+    const fullPageMs = performance.now() - start;
+    const byId = new Map(plan.candidates.map((c) => [c.id, c]));
+    const selected = allocation.selected_ids.map((id) => byId.get(id));
+    const cropStart = performance.now();
+    const tiles = selected.map((c, index) => ({
+        index,
+        label: c.label,
+        x: c.rect.x,
+        scrollY: c.rect.y,
+        width: c.rect.width,
+        height: c.rect.height,
+        pngBase64: cropNativePng(decoded, c.rect).toString("base64"),
     }));
+    const cropMs = performance.now() - cropStart;
+    const probeStart = performance.now();
+    const reconciled = await reconcileCaptureFidelity(browser, tiles);
+    const probeMs = performance.now() - probeStart;
+    // A lazy image can change the document bottom while a native probe is running.
+    // Revalidate even failed probes so a changed plan gets the same bounded retry.
+    if (opts.captureTransactionAllocation) {
+        const after = await buildReviewCapturePlan(browser, opts);
+        try {
+            validatePageReviewAllocation(allocation, after);
+        }
+        catch (error) {
+            throw new CaptureSourceChanged(String(error));
+        }
+    }
+    if (reconciled.fidelity.probed.length !== tiles.length)
+        throw new Error("Page review native fidelity probe incomplete; no context was saved. " +
+            reconciled.warnings.join("; "));
+    const bandTiles = [];
+    const scopes = new Map();
+    for (const [index, c] of selected.entries()) {
+        const tile = reconciled.tiles[index];
+        if (!c.scope)
+            bandTiles.push(tile);
+        else {
+            const group = scopes.get(c.scope) ?? [];
+            group.push(tile);
+            scopes.set(c.scope, group);
+        }
+    }
     const capture = qaCapture ?? (await captureQaState(browser, targetArg, navResult.url, opts));
-    const record = writePackContext(packDir, {
-        context: {
-            ...capture.context,
-            ...(opts.reviewPackContext ? { id: opts.reviewPackContext } : {}),
-        },
+    const writeContext = (destination) => writePackContext(destination, {
+        context: { ...capture.context, id: plan.context_id },
         url: navResult.url,
         title: navResult.title,
         fullPage: buffer,
-        pageWidth: page.width,
-        pageHeight: page.height,
+        pageWidth: plan.page_width / plan.dpr,
+        pageHeight: plan.page_height / plan.dpr,
         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 })),
+        coverage: allocation.coverage,
+        scopeTiles: [...scopes].map(([selector, tiles]) => ({ selector, tiles })),
         signature: capture.signature,
         domHtml: capture.domHtml,
-        ...(captureFidelity ? { captureFidelity } : {}),
-        hitBands: banded?.hitBands ?? 0,
+        captureFidelity: reconciled.fidelity,
+        viewportSize: { width: plan.viewport_width, height: plan.viewport_height },
+        dpr: plan.dpr,
+        recipeVersion: plan.recipe_version,
+        allocationCoverage: allocation.coverage,
+        capturePlan: allocation.plan,
+        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");
+    const record = opts.captureTransactionAllocation
+        ? writeCaptureTransaction(packDir, plan.context_id, writeContext)
+        : writeContext(packDir);
+    const warnings = [...reconciled.warnings];
+    if (allocation.coverage.capped)
+        warnings.push(`Review coverage is incomplete: ${allocation.coverage.uncovered_intervals.length} uncovered intervals and ${allocation.coverage.omitted_scopes.length} omitted scopes.`);
+    emit.log(`review-pack: ${record.id} captured ${record.tiles.length} tiles; full-page ${Math.round(fullPageMs)} ms, crop ${Math.round(cropMs)} ms, native probe ${Math.round(probeMs)} ms`, "info");
     return {
         dir: packDir,
         context_id: record.id,
@@ -1735,9 +1971,8 @@ async function captureReviewPackContext(browser, targetArg, navResult, opts, qaC
         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 } : {}),
+        capture_fidelity: reconciled.fidelity,
+        ...(warnings.length ? { warnings } : {}),
     };
 }
 async function captureCritiqueTiles(browser, opts, tileBudgetPx) {
@@ -1858,7 +2093,7 @@ 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). */
+/** Upper bound on manually supplied --review-pack-hit-rect values. */
 const REVIEW_PACK_HIT_RECT_MAX = 50;
 /** `x,y,w,h` integer rectangles from repeated --review-pack-hit-rect flags. */
 function parseReviewPackHitRects(specs) {