harnery 0.38.0 → 0.40.0

package/src/commands/browse.ts

@@ -8,6 +8,7 @@ import { resolveBinName } from "../core/config.ts";
 import {
   CAPTURE_FIDELITY_MISMATCH_THRESHOLD,
   compareBand,
+  cropNativePng,
   decideFidelity,
   type FidelityProbe,
   pngDimensions,
@@ -43,8 +44,19 @@ import {
   writeNetscapeCookieFile,
   wslHeadedLaunchArgs,
 } from "../lib/browser/index.ts";
+import {
+  allocateTileBudget,
+  validatePageReviewAllocation,
+} from "../lib/browser/page-review-budget.ts";
+import {
+  PAGE_REVIEW_CAPTURE_PLAN_SCHEMA,
+  type PageReviewCapturePlan,
+  type PageReviewContextAllocation,
+  type PageReviewSourceEvidence,
+} from "../lib/browser/page-review-contracts.ts";
 import {
   findPackTile,
+  gateHitsFromEnvelope,
   type PageReviewCaptureFidelity,
   type PageReviewContextRecord,
   type PageReviewExpandedTileRecord,
@@ -53,6 +65,7 @@ import {
   writePackContext,
   writePackExpandedTile,
 } from "../lib/browser/page-review-pack.ts";
+import { retainPageReviewSourceIdentity } from "../lib/browser/page-review-source.ts";
 import {
   buildQaManifest,
   classifySignatures,
@@ -71,10 +84,23 @@ import {
   rubricDigest,
 } from "../lib/browser/qa-reuse.ts";
 import { loadQaSnapshot, resolveQaBaseline, saveQaSnapshot } from "../lib/browser/qa-snapshot.ts";
+import {
+  allocateCaptureReservation,
+  assertGatePlanStable,
+  CaptureSourceChanged,
+  runCaptureTransaction,
+  writeCaptureTransaction,
+} from "../lib/browser/review-capture-transaction.ts";
 import {
   type BrowserSessionServer,
   startBrowserSessionServer,
 } from "../lib/browser/session-control.ts";
+import {
+  type CaptureFingerprint,
+  captureThumbnailFingerprint,
+  registerCaptureThumbnail,
+} from "../lib/browser/thumbnail-association.ts";
+import { reviewCandidateRects } from "../lib/browser/tiling.ts";
 import {
   type DiffResult,
   diffAgainstBaseline,
@@ -108,6 +134,16 @@ const DEFAULT_STORE = resolve(homedir(), ".cache", "harnery", "cookies.json");
 const FALLBACK_OUT_PREFIX = resolve(homedir(), ".cache", "harnery", "browse", "last");
 
 interface BrowseOpts {
+  reviewPackPlan?: boolean;
+  reviewPackAllocation?: string;
+  reviewPackReservation?: string;
+  captureTransactionAllocation?: PageReviewContextAllocation;
+  captureTransaction?: {
+    attempts: Array<{ attempt: number; status: string; source_digest?: string; error?: string }>;
+    source_digest?: string;
+  };
+  capturePlanResult?: PageReviewCapturePlan;
+  captureSourceEvidence?: PageReviewSourceEvidence;
   out?: string;
   // Commander expands `--no-X` into `opts.x = false` (default true), not
   // `opts.noX`. So `--no-screenshot` toggles `screenshot`, `--no-full-page`
@@ -236,7 +272,7 @@ interface BrowseOpts {
   reviewPack?: string;
   reviewPackContext?: string;
   reviewPackScope?: string[];
-  reviewPackBands?: boolean;
+
   /** Re-capture ONE existing tile of --review-pack-context at --device-scale-factor. */
   reviewPackExpand?: string;
   /** Gate-hit rectangles (`x,y,w,h` strings) whose bands are captured past the tile cap. */
@@ -725,6 +761,19 @@ export function registerBrowseCommand(
         "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, " +
@@ -736,11 +785,6 @@ export function registerBrowseCommand(
       (value: string, previous: string[] = []) => [...previous, value],
       [] as string[],
     )
-    .option(
-      "--no-review-pack-bands",
-      "Skip full-page bands in the pack and keep only --review-pack-scope tiles (a scoped " +
-        "visual pass).",
-    )
     .option(
       "--review-pack-expand <tile-id>",
       "Instead of capturing a context, re-render ONE existing tile of --review-pack-context " +
@@ -749,9 +793,9 @@ export function registerBrowseCommand(
     )
     .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}).`,
+      "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: string, previous: string[] = []) => [...previous, value],
       [] as string[],
     )
@@ -815,6 +859,17 @@ async function runBrowse(
   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(
@@ -905,126 +960,216 @@ async function runBrowse(
       evalResult = await browser.evaluate<unknown>(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: VisibilityResult[] | undefined;
-    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: VisibilityResult[] | undefined;
+      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: WidthResult[] | undefined;
-    if (opts.checkWidth && opts.checkWidth.length > 0) {
-      widths = await browser.checkWidth(opts.checkWidth);
-    }
-    let overflow: OverflowResult | undefined;
-    if (opts.checkOverflow) {
-      overflow = await browser.checkOverflow();
-    }
-    let runts: RuntsResult | undefined;
-    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: LayoutLintResult | undefined;
-    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: TargetSizeResult[] | undefined;
-    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: ContentChecksResult | undefined;
-    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: QaPlanReport | undefined;
-    let qaCapture: QaCaptureState | undefined;
-    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: WidthResult[] | undefined;
+      if (opts.checkWidth && opts.checkWidth.length > 0) {
+        widths = await browser.checkWidth(opts.checkWidth);
+      }
+      let overflow: OverflowResult | undefined;
+      if (opts.checkOverflow) {
+        overflow = await browser.checkOverflow();
+      }
+      let runts: RuntsResult | undefined;
+      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: LayoutLintResult | undefined;
+      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: TargetSizeResult[] | undefined;
+      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: ContentChecksResult | undefined;
+      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: QaPlanReport | undefined;
+      let qaCapture: QaCaptureState | undefined;
+      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: AssertResult[] | undefined;
+      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: Record<string, unknown> = { 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" as const }]
+              : [];
+          });
+        }
+      }
+
+      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,
+    }: Partial<Awaited<ReturnType<typeof collectGates>>> = 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: CritiqueResult | undefined;
@@ -1095,6 +1240,62 @@ async function runBrowse(
     let reviewPack: ReviewPackReport | undefined;
     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);
     }
@@ -1153,11 +1354,7 @@ async function runBrowse(
         "info",
       );
     }
-    let asserts: AssertResult[] | undefined;
-    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;
@@ -1578,6 +1775,9 @@ async function runPrintMode(
     if (qaPlan) result.qaPlan = qaPlan;
     if (qaReuse) 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;
     }
@@ -1626,6 +1826,7 @@ async function runTrioMode(
   const skipScreenshot = opts.screenshot === false;
   let pngPath: string | undefined;
   let pngBytes: number | undefined;
+  let pngFingerprint: CaptureFingerprint | null = null;
   let captureEvalResult: unknown;
   let captureViewport: { width: number; height: number } | undefined;
   let captureEvidence: unknown;
@@ -1642,6 +1843,8 @@ async function runTrioMode(
     } 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) {
     throw new Error("--capture-evaluate requires a screenshot; remove --no-screenshot.");
@@ -1665,6 +1868,19 @@ async function runTrioMode(
   }
   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: Record<string, unknown> = {
@@ -1679,6 +1895,7 @@ async function runTrioMode(
     ...summarizeDiagnostics(diag),
   };
   if (pngBytes !== undefined) envelope.screenshotBytes = pngBytes;
+  if (thumbnailAssociation) envelope.thumbnailAssociation = thumbnailAssociation;
   if (snapshot) {
     envelope.htmlSnapshot = {
       stylesheetsInlined: snapshot.stylesheetsInlined,
@@ -1714,6 +1931,9 @@ async function runTrioMode(
   if (qaPlan) envelope.qaPlan = qaPlan;
   if (qaReuse) 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;
   }
@@ -2334,12 +2554,14 @@ async function expandReviewPackTile(
   const packDir = opts.reviewPack as string;
   const contextId = opts.reviewPackContext as string;
   const tileId = opts.reviewPackExpand as string;
-  const { tile } = findPackTile([readPackContext(packDir, contextId)], tileId, contextId);
+  const 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,
@@ -2368,9 +2590,9 @@ async function expandReviewPackTile(
  * 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: Browser,
@@ -2388,31 +2610,23 @@ async function reconcileCaptureFidelity(
     height: tile.height / dpr,
   });
   const shots = new Map<number, Buffer | undefined>();
-  const shoot = async (position: number): Promise<Buffer | undefined> => {
-    if (shots.has(position)) return shots.get(position);
-    const tile = tiles[position] as CritiqueTile;
-    let shot: Buffer | undefined;
-    try {
-      const captured = await browser.captureRegionByScroll(cssRect(tile));
-      const size = pngDimensions(captured);
+  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",
+          `Native scrolled capture of ${tileId(position)} has different dimensions; probe incomplete.`,
         );
-      } else {
-        shot = captured;
-      }
-    } catch (err: unknown) {
-      warnings.push(
-        `review-pack: scrolled capture of ${tileId(position)} failed ` +
-          `(${err instanceof Error ? err.message : String(err)}); its full-page crop was kept`,
-      );
+      } else shots.set(position, shot);
     }
-    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: number) => 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
@@ -2452,11 +2666,90 @@ async function reconcileCaptureFidelity(
 
 /**
  * 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: Browser,
+  opts: BrowseOpts,
+): Promise<PageReviewCapturePlan> {
+  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: Browser,
   targetArg: string,
@@ -2465,120 +2758,125 @@ async function captureReviewPackContext(
   qaCapture: QaCaptureState | undefined,
 ): Promise<ReviewPackReport> {
   const packDir = opts.reviewPack as string;
-  const { maxTiles, band, overlap } = critiqueTilingKnobs(opts);
-  const buffer = await browser.fullPageScreenshotBuffer();
-  let atoms: Awaited<ReturnType<Browser["visualAtoms"]>> | undefined;
-  try {
-    atoms = await browser.visualAtoms();
-  } catch {
-    atoms = undefined;
-  }
-  const tiling = { bandHeight: band, overlap, maxTiles, atoms };
-  const withBands = opts.reviewPackBands !== false;
-  // Gate-hit rectangles (qa-run lifts them from the gate stage, which runs
-  // first) pull the bands they land in past the cap; those tiles follow the
-  // kept bands as `hit band N`. Coverage still describes the kept prefix.
-  const hitRects = parseReviewPackHitRects(opts.reviewPackHitRect);
-  const banded = withBands
-    ? tilesFromFullPage(buffer, { ...tiling, hitRects, maxHitBands: REVIEW_PACK_HIT_RECT_MAX })
-    : undefined;
-  if (banded?.coverage.capped) {
-    emit.log(
-      `review-pack: page banded to the ${maxTiles}-tile cap (raise --check-critique-max-tiles for full coverage)`,
-      "warn",
-    );
-  }
-  if (banded && banded.hitBands > 0) {
-    emit.log(
-      `review-pack: ${banded.hitBands} band(s) below the tile cap captured for ${hitRects.length} gate-hit rect(s)`,
-      "info",
-    );
-  }
-  // Fidelity: prove the full-page screenshot against scrolled viewport
-  // renders while the browser is still open; on disagreement the bands are
-  // re-cut from scrolled captures (see reconcileCaptureFidelity).
-  let bandTiles = banded?.tiles ?? [];
-  let captureFidelity: PageReviewCaptureFidelity | undefined;
-  const fidelityWarnings: string[] = [];
-  if (bandTiles.length > 0) {
-    const reconciled = await reconcileCaptureFidelity(browser, bandTiles);
-    bandTiles = reconciled.tiles;
-    captureFidelity = reconciled.fidelity;
-    fidelityWarnings.push(...reconciled.warnings);
-    for (const warning of reconciled.warnings) emit.log(warning, "warn");
-    emit.log(
-      `review-pack: capture fidelity ${captureFidelity.source} ` +
-        `(${captureFidelity.probed.length} band(s) probed, ${captureFidelity.mismatched.length} mismatched)`,
-      "info",
-    );
-  }
-  const scopeTiles: Array<{ selector: string; tiles: CritiqueTile[]; coverage: CritiqueCoverage }> =
-    [];
-  for (const selector of opts.reviewPackScope ?? []) {
-    const elementRects = await browser.elementTiles(selector);
-    const scoped = tilesFromFullPage(buffer, { ...tiling, elementRects });
-    if (elementRects.length > maxTiles) {
-      emit.log(
-        `review-pack: ${elementRects.length} elements matched ${selector}, capped to ${maxTiles} tiles`,
-        "warn",
+  const plan = await buildReviewCapturePlan(browser, opts);
+  let allocation: PageReviewContextAllocation;
+  if (opts.captureTransactionAllocation) {
+    try {
+      allocation = validatePageReviewAllocation(opts.captureTransactionAllocation, plan);
+    } catch (error) {
+      throw new CaptureSourceChanged(String(error));
+    }
+  } 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;
     }
-    scopeTiles.push({ selector, tiles: scoped.tiles, coverage: scoped.coverage });
-  }
-  // Coverage: the bands when present, else the scopes folded together
-  // (heights worst-case, band counts add, capped sticky).
-  let coverage: CritiqueCoverage | undefined = banded?.coverage;
-  if (!coverage) {
-    for (const scope of scopeTiles) {
-      coverage = coverage
-        ? {
-            page_height_px: Math.max(coverage.page_height_px, scope.coverage.page_height_px),
-            reviewed_height_px: Math.min(
-              coverage.reviewed_height_px,
-              scope.coverage.reviewed_height_px,
-            ),
-            bands_total: coverage.bands_total + scope.coverage.bands_total,
-            bands_reviewed: coverage.bands_reviewed + scope.coverage.bands_reviewed,
-            capped: coverage.capped || scope.coverage.capped,
-          }
-        : scope.coverage;
+  } 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" as const }]
+          : [],
+      );
     }
+    allocation = allocateTileBudget([plan], maxTiles).contexts[0];
   }
-  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 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: CritiqueTile[] = 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: CritiqueTile[] = [];
+  const scopes = new Map<string, CritiqueTile[]>();
+  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 } : {}),
-    },
-    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,
-  });
+  const writeContext = (destination: string) =>
+    writePackContext(destination, {
+      context: { ...capture.context, id: plan.context_id },
+      url: navResult.url,
+      title: navResult.title,
+      fullPage: buffer,
+      pageWidth: plan.page_width / plan.dpr,
+      pageHeight: plan.page_height / plan.dpr,
+      tiles: bandTiles,
+      coverage: allocation.coverage,
+      scopeTiles: [...scopes].map(([selector, tiles]) => ({ selector, tiles })),
+      signature: capture.signature,
+      domHtml: capture.domHtml,
+      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,
+    });
+  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} → ${record.tiles.length} tile(s)` +
-      (record.scopes.length > 0
-        ? ` (${record.scopes.map((s) => `${s.selector}: ${s.tiles}`).join(", ")})`
-        : "") +
-      ` written to ${packDir}`,
+    `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 {
@@ -2588,9 +2886,8 @@ async function captureReviewPackContext(
     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 } : {}),
   };
 }
 
@@ -2735,7 +3032,7 @@ async function waitForTerminalEnter(signal: AbortSignal): Promise<void> {
   });
 }
 
-/** 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. */