harnery 0.32.0 → 0.34.0

package/dist/lib/browser/qa-plan.js

@@ -0,0 +1,321 @@
+// Diff-aware QA planner: classify a page change against a baseline signature
+// and emit a machine-readable review manifest BEFORE any expensive work runs.
+//
+// The motivating failure is spend without proportionality: a one-word copy
+// edit and a theme rewrite both trigger the same full-page, every-context
+// vision review. This module makes review proportional to the change:
+//   - text/data-only edits produce zero vision calls;
+//   - a local component change reviews only that component's stable root;
+//   - global CSS, unprovable blast radius, or a missing baseline widen to
+//     full coverage — ambiguity always widens, never silently downgrades.
+//
+// Everything here is pure data-in/data-out: signatures are captured elsewhere
+// (the browser client), baselines are persisted elsewhere (qa-snapshot.ts),
+// and execution happens elsewhere (the critique engine). Keeping the planner
+// pure means the classification can be reviewed, logged, and overridden
+// before a single model call is made.
+//
+// One deliberate portability boundary: a stylesheet change classifies as
+// `large-structural` here because CSS blast radius is not provable from
+// digests alone. A host that can map component-scoped stylesheets to
+// selectors can downgrade after the fact; the portable layer never does.
+/** FNV-1a 32-bit over a string, hex-encoded, with a length suffix so the
+ * (tiny) collision surface also has to match on length. Used for text and
+ * stylesheet digests — a comparison fingerprint, not a security hash. */
+export function fnv1a32(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `${(hash >>> 0).toString(16).padStart(8, "0")}-${text.length}`;
+}
+const UNAVAILABLE = "unavailable";
+function diffStylesheets(baseline, current) {
+    const base = new Map(baseline.map((s) => [s.key, s.digest]));
+    const cur = new Map(current.map((s) => [s.key, s.digest]));
+    const unavailable = [...baseline, ...current].some((s) => s.digest === UNAVAILABLE);
+    const changed = [];
+    for (const [key, digest] of cur) {
+        const prior = base.get(key);
+        if (prior === undefined || prior !== digest)
+            changed.push(key);
+    }
+    for (const key of base.keys()) {
+        if (!cur.has(key))
+            changed.push(key);
+    }
+    return { changed: changed.sort(), unavailable };
+}
+/**
+ * Classify current against baseline. Pure: no browser, no filesystem. The
+ * bias is stated in the plan and enforced here — ambiguity widens (to
+ * `unknown`/`large-structural`), never narrows. A `null` baseline is the
+ * "no baseline available" case and is always `unknown`.
+ */
+export function classifySignatures(baseline, current, opts = {}) {
+    const maxScopes = opts.maxScopes ?? 4;
+    const none = {
+        text_changed_paths: [],
+        structural_changed_paths: [],
+        stylesheets_changed: [],
+        scopes: [],
+        identical: false,
+    };
+    if (!baseline) {
+        return {
+            ...none,
+            change_class: "unknown",
+            reasons: ["no baseline available — cannot prove any change class"],
+        };
+    }
+    if (baseline.truncated || current.truncated) {
+        return {
+            ...none,
+            change_class: "unknown",
+            reasons: [
+                "signature capture was truncated at its node cap — absence of change cannot be proven",
+            ],
+        };
+    }
+    const sheets = diffStylesheets(baseline.stylesheets, current.stylesheets);
+    if (sheets.unavailable) {
+        return {
+            ...none,
+            change_class: "unknown",
+            stylesheets_changed: sheets.changed,
+            reasons: [
+                "stylesheet digest unavailable (cross-origin without CORS) — style stability cannot be proven, DOM equality alone never proves text-only",
+            ],
+        };
+    }
+    const baseNodes = new Map(baseline.nodes.map((n) => [n.path, n]));
+    const curNodes = new Map(current.nodes.map((n) => [n.path, n]));
+    const unavailableVisual = [...baseline.nodes, ...current.nodes].find((node) => node.visual === UNAVAILABLE);
+    if (unavailableVisual) {
+        return {
+            ...none,
+            change_class: "unknown",
+            reasons: [
+                `visual digest unavailable at ${unavailableVisual.path} — text-only cannot be proven`,
+            ],
+        };
+    }
+    const textChanged = [];
+    const structuralChanged = new Map();
+    for (const [path, node] of curNodes) {
+        const prior = baseNodes.get(path);
+        if (!prior) {
+            structuralChanged.set(path, node); // added
+        }
+        else if (prior.tag !== node.tag ||
+            prior.attrs !== node.attrs ||
+            (prior.visual ?? "") !== (node.visual ?? "")) {
+            structuralChanged.set(path, node);
+        }
+        else if ((prior.text ?? "") !== (node.text ?? "")) {
+            textChanged.push(path);
+        }
+    }
+    for (const [path, node] of baseNodes) {
+        if (!curNodes.has(path) && !structuralChanged.has(path)) {
+            structuralChanged.set(path, node); // removed — anchor comes from baseline side
+        }
+    }
+    if (sheets.changed.length > 0) {
+        return {
+            ...none,
+            change_class: "large-structural",
+            text_changed_paths: textChanged.sort(),
+            structural_changed_paths: [...structuralChanged.keys()].sort(),
+            stylesheets_changed: sheets.changed,
+            reasons: [
+                `stylesheet changed (${sheets.changed.join(", ")}) — CSS blast radius is not provable portably, widening to full coverage`,
+            ],
+        };
+    }
+    if (structuralChanged.size === 0) {
+        if (textChanged.length === 0) {
+            return {
+                ...none,
+                change_class: "text-data-only",
+                identical: true,
+                reasons: ["no differences detected between baseline and current signatures"],
+            };
+        }
+        return {
+            ...none,
+            change_class: "text-data-only",
+            text_changed_paths: textChanged.sort(),
+            reasons: [
+                `only direct text content changed (${textChanged.length} node${textChanged.length === 1 ? "" : "s"}); element structure, attributes, and stylesheet digests are unchanged`,
+            ],
+        };
+    }
+    // Structural changes: lift every changed node to its nearest strict-ancestor
+    // stable anchor. Any node without one is an unprovable boundary — widen.
+    const anchorless = [];
+    const scopeNodes = new Map();
+    for (const [path, node] of structuralChanged) {
+        if (!node.anchor) {
+            anchorless.push(path);
+            continue;
+        }
+        const existing = scopeNodes.get(node.anchor.selector);
+        if (existing)
+            existing.count++;
+        else
+            scopeNodes.set(node.anchor.selector, { path: node.anchor.path, count: 1 });
+    }
+    if (anchorless.length > 0) {
+        return {
+            ...none,
+            change_class: "large-structural",
+            text_changed_paths: textChanged.sort(),
+            structural_changed_paths: [...structuralChanged.keys()].sort(),
+            reasons: [
+                `${anchorless.length} changed node${anchorless.length === 1 ? "" : "s"} without a stable ancestor (first: ${anchorless.sort()[0]}) — visual impact cannot be proven to stay inside stable selectors`,
+            ],
+        };
+    }
+    // Dedupe nested anchors to the outermost root: reviewing a container once
+    // beats one model call per anchored descendant.
+    const entries = [...scopeNodes.entries()].sort((a, b) => a[1].path.length - b[1].path.length);
+    const roots = [];
+    for (const entry of entries) {
+        const container = roots.find(([, root]) => entry[1].path.startsWith(`${root.path}>`));
+        if (container)
+            container[1].count += entry[1].count;
+        else
+            roots.push(entry);
+    }
+    if (roots.length > maxScopes) {
+        return {
+            ...none,
+            change_class: "large-structural",
+            text_changed_paths: textChanged.sort(),
+            structural_changed_paths: [...structuralChanged.keys()].sort(),
+            reasons: [
+                `changes span ${roots.length} independent scope roots (limit ${maxScopes}) — a multi-region change is a page-level change`,
+            ],
+        };
+    }
+    return {
+        change_class: "local-visual",
+        identical: false,
+        text_changed_paths: textChanged.sort(),
+        structural_changed_paths: [...structuralChanged.keys()].sort(),
+        stylesheets_changed: [],
+        scopes: roots
+            .sort((a, b) => a[0].localeCompare(b[0]))
+            .map(([selector, root]) => ({
+            selector,
+            reason: `nearest stable ancestor of ${root.count} changed node${root.count === 1 ? "" : "s"}`,
+            matches: 1,
+        })),
+        reasons: [
+            `structural changes contained by ${roots.length} stable scope root${roots.length === 1 ? "" : "s"}`,
+        ],
+    };
+}
+const DEFAULT_DETERMINISTIC = ["console", "overflow", "truncation", "placeholder"];
+/**
+ * Turn a classification into an executable review manifest. Pure: rendering,
+ * baseline acquisition, and critique execution stay in the caller. The
+ * separation is the point — the manifest can be printed by a dry run,
+ * reviewed, and overridden before expensive work starts.
+ */
+export function buildQaManifest(classification, opts) {
+    const viewports = opts.viewports ?? ["desktop", "mobile"];
+    const fullPageTiles = opts.estimatedFullPageTiles ?? 24;
+    const states = opts.states ?? [];
+    const scopes = opts.explicitScopes?.length ? opts.explicitScopes : classification.scopes;
+    let changeClass = classification.change_class;
+    const reasons = [...classification.reasons];
+    if (opts.explicitScopes?.length && changeClass === "unknown") {
+        // Explicit scope input is resolution-order rung 1: the producing task
+        // knows its own blast radius better than a missing baseline does.
+        changeClass = "local-visual";
+        reasons.push("explicit scope selectors supplied — overriding unknown classification");
+    }
+    if (opts.explicitScopes?.length &&
+        changeClass === "large-structural" &&
+        classification.stylesheets_changed.length > 0 &&
+        classification.structural_changed_paths.length === 0) {
+        changeClass = "local-visual";
+        reasons.push("explicit scope selectors supplied for a stylesheet-only change — host proved the component boundary");
+    }
+    if (states.length > 0 && (changeClass === "text-data-only" || changeClass === "local-visual")) {
+        changeClass = "interaction-state";
+        reasons.push(`explicit interaction states requested: ${states.join(", ")}`);
+    }
+    let incomplete;
+    if (classification.change_class === "unknown" && changeClass === "unknown") {
+        if (opts.stopOnUnknown) {
+            incomplete = { reason: classification.reasons[0] ?? "classification unknown" };
+        }
+        else {
+            reasons.push("unknown class widened to large-structural coverage");
+        }
+    }
+    if ((changeClass === "local-visual" || changeClass === "interaction-state") &&
+        (scopes.length === 0 || scopes.some((scope) => scope.matches < 1))) {
+        const missing = scopes.find((scope) => scope.matches < 1)?.selector;
+        incomplete = {
+            reason: missing
+                ? `scope selector matched no elements: ${missing}`
+                : `${changeClass} requires at least one stable scope selector`,
+        };
+    }
+    const matrix = viewports.flatMap((viewport) => ["light", "dark"].map((theme) => ({ viewport, theme, state: "default" })));
+    let contexts;
+    let visual;
+    switch (changeClass) {
+        case "text-data-only":
+            contexts = [];
+            visual = "none";
+            break;
+        case "local-visual":
+            contexts = viewports.map((viewport) => ({ viewport, theme: "light", state: "default" }));
+            visual = "scoped";
+            break;
+        case "interaction-state":
+            contexts = [
+                { viewport: viewports[0] ?? "desktop", theme: "light", state: "default" },
+                ...states.map((state) => ({
+                    viewport: viewports[0] ?? "desktop",
+                    theme: "light",
+                    state,
+                })),
+            ];
+            visual = "scoped";
+            break;
+        default:
+            contexts = incomplete ? [] : matrix;
+            visual = "full-page";
+            break;
+    }
+    if (incomplete)
+        contexts = [];
+    const tilesPerContext = visual === "none" ? 0 : visual === "scoped" ? Math.max(1, scopes.length) : fullPageTiles;
+    const tilesCeiling = tilesPerContext * contexts.length;
+    return {
+        schema_version: 1,
+        change_class: changeClass,
+        classification_reasons: reasons,
+        ...(opts.sourceRevision ? { source_revision: opts.sourceRevision } : {}),
+        ...(opts.baselineRevision ? { baseline_revision: opts.baselineRevision } : {}),
+        baseline_source: opts.baselineSource,
+        scopes: visual === "none" ? [] : scopes,
+        contexts,
+        checks: {
+            deterministic: opts.deterministicChecks ?? DEFAULT_DETERMINISTIC,
+            interaction: opts.outcomeAssertions ?? [],
+            visual,
+        },
+        concurrency: opts.concurrency ?? { headless: 4, metered: 2 },
+        reuse: opts.reuse ?? { mode: "none", cache: false },
+        predicted: { tiles_ceiling: tilesCeiling, model_calls_ceiling: tilesCeiling },
+        ...(incomplete ? { incomplete } : {}),
+    };
+}

package/dist/lib/browser/qa-reuse.d.ts

@@ -0,0 +1,99 @@
+import { PNG } from "pngjs";
+import type { CritiqueFinding, CritiqueTile } from "./critique.js";
+/** Bump when the critique request/response contract changes in a way that
+ * invalidates persisted findings (rubric semantics, finding schema, tiling
+ * geometry meaning). Part of every cache key and persisted critique. */
+export declare const QA_CRITIQUE_CONTRACT_VERSION = 1;
+/** Default Path B mismatch-ratio threshold. Strict on purpose: reuse trades
+ * essentially nothing for robustness against rasterization noise, and a
+ * looser threshold could hide a sub-threshold real change. */
+export declare const DEFAULT_REUSE_MISMATCH_RATIO = 0.001;
+/** Critique results persisted beside a QA snapshot, enough to decide reuse
+ * later: findings plus the geometry they were judged under. */
+export interface PersistedCritique {
+    contract_version: number;
+    /** fnv1a32 of the exact rubric text the findings were judged under. */
+    rubric_digest: string;
+    outcome: "pass" | "fail";
+    findings: CritiqueFinding[];
+    tiles: Array<{
+        index: number;
+        label: string;
+        x: number;
+        scrollY: number;
+        width: number;
+        height: number;
+    }>;
+}
+/** Versioned, canonicalized Path A cache key (observe mode). Field order is
+ * part of the contract — never reorder without bumping the version. */
+export declare function qaTileCacheKey(parts: {
+    tilePngSha256: string;
+    rubricDigest: string;
+    provider: string;
+    model: string;
+    viewport: string;
+    deviceScaleFactor: number;
+    theme: string;
+    state: string;
+    tileLabel: string;
+    browserVersion?: string;
+}): string;
+export declare function sha256Hex(buf: Buffer | Uint8Array): string;
+export declare function rubricDigest(rubric: string): string;
+/**
+ * Pixel-compare one document-space rect across two full-page screenshots.
+ * `sizeMismatch` is true when the rect isn't fully comparable in both images
+ * (page grew/shrank past it) — the caller treats that as changed.
+ */
+export declare function rectMismatch(baselineFullPage: PNG, currentFullPage: PNG, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, opts?: {
+    pixelThreshold?: number;
+}): {
+    ratio: number;
+    comparablePixels: number;
+    sizeMismatch: boolean;
+};
+export interface TileReuseDecision {
+    index: number;
+    label: string;
+    reuse: boolean;
+    reason: string;
+    /** Rect mismatch ratio, present when a pixel comparison ran. */
+    mismatch_ratio?: number;
+}
+export interface CritiqueReusePlan {
+    mode: "band-diff";
+    /** Tiles that must be reviewed fresh, in original order. */
+    review: CritiqueTile[];
+    decisions: TileReuseDecision[];
+    tiles_total: number;
+    tiles_reused: number;
+    tiles_reviewed: number;
+    provider_calls_avoided: number;
+    mismatch_threshold: number;
+    /** Set when the whole baseline was unusable (everything reviews fresh). */
+    invalidation?: string;
+}
+/**
+ * Path B reuse plan: decide per tile whether the baseline run's verdict still
+ * covers it. A tile is reused ONLY when (a) the baseline is valid for this
+ * rubric and contract, (b) no baseline finding overlaps the tile's document
+ * region (a prior failure is never converted into a pass), and (c) its rect
+ * pixel-matches the baseline screenshot at or below the strict threshold.
+ * Everything else reviews fresh — reuse can produce false REVIEWS, never
+ * false passes.
+ */
+export declare function planCritiqueReuse(args: {
+    baselineScreenshot: Buffer;
+    baselineCritique: PersistedCritique;
+    currentScreenshot: Buffer;
+    tiles: CritiqueTile[];
+    rubric: string;
+    mismatchThreshold?: number;
+}): CritiqueReusePlan;
+//# sourceMappingURL=qa-reuse.d.ts.map

package/dist/lib/browser/qa-reuse.d.ts.map

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

package/dist/lib/browser/qa-reuse.js

@@ -0,0 +1,222 @@
+// Visual-result reuse for critique tiles (plan 3.3): avoid re-judging pixels
+// that did not change.
+//
+// Two mechanisms share this module; which is primary was decided by the
+// Stage 0 byte-stability experiment, not preference:
+//
+//   Path B (primary): band-level pixel diff. Compare each candidate tile's
+//   document-space rect in the CURRENT full-page screenshot against the SAME
+//   rect in the persisted baseline screenshot (qa-snapshot.ts), with
+//   pixelmatch's anti-aliasing tolerance. At or below a strict mismatch
+//   ratio (default 0.001), the tile region provably didn't change and the
+//   provider call is skipped. No byte identity required, so font
+//   rasterization and raster-path drift don't defeat it.
+//
+//   Path A (observe mode: key computation + logging only): the Stage 0
+//   byte-stability experiment PASSED its gate (100% cross-restart identical
+//   bands on real pages, same-day/same-machine, deterministic settle), so an
+//   exact-digest cache is viable — but Path B subsumes its win (a
+//   byte-identical band pixel-diffs at ratio 0) with zero extra storage, so
+//   only the versioned cache key ships until telemetry shows a payoff Path B
+//   misses (e.g. cross-target tile sharing).
+//
+// Hard rules, both paths: never convert a prior failure into a pass — any
+// baseline finding overlapping a tile's region forces a fresh review; a
+// missing/invalid baseline, changed rubric, or changed critique contract is
+// a miss, never an error.
+import { createHash } from "node:crypto";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { fnv1a32 } from "./qa-plan.js";
+/** Bump when the critique request/response contract changes in a way that
+ * invalidates persisted findings (rubric semantics, finding schema, tiling
+ * geometry meaning). Part of every cache key and persisted critique. */
+export const QA_CRITIQUE_CONTRACT_VERSION = 1;
+/** Default Path B mismatch-ratio threshold. Strict on purpose: reuse trades
+ * essentially nothing for robustness against rasterization noise, and a
+ * looser threshold could hide a sub-threshold real change. */
+export const DEFAULT_REUSE_MISMATCH_RATIO = 0.001;
+/** Versioned, canonicalized Path A cache key (observe mode). Field order is
+ * part of the contract — never reorder without bumping the version. */
+export function qaTileCacheKey(parts) {
+    const canonical = [
+        `v${QA_CRITIQUE_CONTRACT_VERSION}`,
+        `png:${parts.tilePngSha256}`,
+        `rubric:${parts.rubricDigest}`,
+        `provider:${parts.provider}`,
+        `model:${parts.model}`,
+        `viewport:${parts.viewport}`,
+        `dpr:${parts.deviceScaleFactor}`,
+        `theme:${parts.theme}`,
+        `state:${parts.state}`,
+        `tile:${parts.tileLabel}`,
+        `browser:${parts.browserVersion ?? "unknown"}`,
+    ].join("\x1f");
+    return `qa1-${createHash("sha256").update(canonical).digest("hex")}`;
+}
+export function sha256Hex(buf) {
+    return createHash("sha256").update(buf).digest("hex");
+}
+export function rubricDigest(rubric) {
+    // Whitespace-normalized so formatting-only edits don't invalidate reuse.
+    return fnv1a32(rubric.replace(/\s+/g, " ").trim());
+}
+function cropRegion(png, rect) {
+    const sx = Math.max(0, Math.min(Math.round(rect.x), png.width - 1));
+    const sy = Math.max(0, Math.min(Math.round(rect.y), png.height - 1));
+    const w = Math.min(Math.round(rect.width), png.width - sx);
+    const h = Math.min(Math.round(rect.height), png.height - sy);
+    if (w <= 0 || h <= 0)
+        return null;
+    const out = new PNG({ width: w, height: h });
+    for (let row = 0; row < h; row++) {
+        const srcStart = ((sy + row) * png.width + sx) * 4;
+        png.data.copy(out.data, row * w * 4, srcStart, srcStart + w * 4);
+    }
+    return out;
+}
+/**
+ * Pixel-compare one document-space rect across two full-page screenshots.
+ * `sizeMismatch` is true when the rect isn't fully comparable in both images
+ * (page grew/shrank past it) — the caller treats that as changed.
+ */
+export function rectMismatch(baselineFullPage, currentFullPage, rect, opts = {}) {
+    const base = cropRegion(baselineFullPage, rect);
+    const cur = cropRegion(currentFullPage, rect);
+    if (!base || !cur || base.width !== cur.width || base.height !== cur.height) {
+        return { ratio: 1, comparablePixels: 0, sizeMismatch: true };
+    }
+    const mismatched = pixelmatch(base.data, cur.data, undefined, base.width, base.height, {
+        threshold: opts.pixelThreshold ?? 0.1,
+        includeAA: false,
+    });
+    const total = base.width * base.height;
+    return { ratio: mismatched / total, comparablePixels: total, sizeMismatch: false };
+}
+function wholeRunMiss(tiles, threshold, invalidation) {
+    return {
+        mode: "band-diff",
+        review: tiles,
+        decisions: tiles.map((t) => ({
+            index: t.index,
+            label: t.label,
+            reuse: false,
+            reason: invalidation,
+        })),
+        tiles_total: tiles.length,
+        tiles_reused: 0,
+        tiles_reviewed: tiles.length,
+        provider_calls_avoided: 0,
+        mismatch_threshold: threshold,
+        invalidation,
+    };
+}
+/**
+ * Path B reuse plan: decide per tile whether the baseline run's verdict still
+ * covers it. A tile is reused ONLY when (a) the baseline is valid for this
+ * rubric and contract, (b) no baseline finding overlaps the tile's document
+ * region (a prior failure is never converted into a pass), and (c) its rect
+ * pixel-matches the baseline screenshot at or below the strict threshold.
+ * Everything else reviews fresh — reuse can produce false REVIEWS, never
+ * false passes.
+ */
+export function planCritiqueReuse(args) {
+    const threshold = args.mismatchThreshold ?? DEFAULT_REUSE_MISMATCH_RATIO;
+    const { baselineCritique, tiles } = args;
+    if (baselineCritique.outcome !== "pass") {
+        return wholeRunMiss(tiles, threshold, "baseline critique did not pass");
+    }
+    if (baselineCritique.contract_version !== QA_CRITIQUE_CONTRACT_VERSION) {
+        return wholeRunMiss(tiles, threshold, `baseline critique contract v${baselineCritique.contract_version} != v${QA_CRITIQUE_CONTRACT_VERSION}`);
+    }
+    if (baselineCritique.rubric_digest !== rubricDigest(args.rubric)) {
+        return wholeRunMiss(tiles, threshold, "rubric changed since the baseline run");
+    }
+    let baselinePng;
+    let currentPng;
+    try {
+        baselinePng = PNG.sync.read(args.baselineScreenshot);
+        currentPng = PNG.sync.read(args.currentScreenshot);
+    }
+    catch {
+        return wholeRunMiss(tiles, threshold, "unreadable baseline or current screenshot");
+    }
+    // Document regions of baseline tiles that produced findings.
+    const findingTiles = new Set(baselineCritique.findings.map((f) => f.tile));
+    const dirtyRegions = baselineCritique.tiles
+        .filter((t) => findingTiles.has(t.index))
+        .map((t) => ({ top: t.scrollY, bottom: t.scrollY + t.height }));
+    const decisions = [];
+    const review = [];
+    for (const tile of tiles) {
+        const top = tile.scrollY;
+        const bottom = tile.scrollY + tile.height;
+        const left = tile.x ?? 0;
+        const right = left + tile.width;
+        const coverage = baselineCritique.tiles
+            .filter((prior) => prior.x <= left && prior.x + prior.width >= right)
+            .map((prior) => ({ top: prior.scrollY, bottom: prior.scrollY + prior.height }))
+            .sort((a, b) => a.top - b.top);
+        let coveredTo = top;
+        for (const region of coverage) {
+            if (region.bottom <= coveredTo || region.top > coveredTo)
+                continue;
+            coveredTo = Math.max(coveredTo, region.bottom);
+            if (coveredTo >= bottom)
+                break;
+        }
+        if (coveredTo < bottom) {
+            decisions.push({
+                index: tile.index,
+                label: tile.label,
+                reuse: false,
+                reason: "baseline critique did not cover this entire region",
+            });
+            review.push(tile);
+            continue;
+        }
+        const overlapsFinding = dirtyRegions.some((r) => r.top < bottom && r.bottom > top);
+        if (overlapsFinding) {
+            decisions.push({
+                index: tile.index,
+                label: tile.label,
+                reuse: false,
+                reason: "baseline run had findings in this region — always re-reviewed",
+            });
+            review.push(tile);
+            continue;
+        }
+        const rect = { x: tile.x ?? 0, y: tile.scrollY, width: tile.width, height: tile.height };
+        const cmp = rectMismatch(baselinePng, currentPng, rect);
+        if (cmp.sizeMismatch || cmp.ratio > threshold) {
+            decisions.push({
+                index: tile.index,
+                label: tile.label,
+                reuse: false,
+                reason: cmp.sizeMismatch
+                    ? "region not comparable across screenshots (layout size changed)"
+                    : `mismatch ratio ${cmp.ratio.toFixed(6)} > ${threshold}`,
+                mismatch_ratio: cmp.sizeMismatch ? undefined : cmp.ratio,
+            });
+            review.push(tile);
+            continue;
+        }
+        decisions.push({
+            index: tile.index,
+            label: tile.label,
+            reuse: true,
+            reason: `clean region pixel-matched baseline (ratio ${cmp.ratio.toFixed(6)})`,
+            mismatch_ratio: cmp.ratio,
+        });
+    }
+    return {
+        mode: "band-diff",
+        review,
+        decisions,
+        tiles_total: tiles.length,
+        tiles_reused: tiles.length - review.length,
+        tiles_reviewed: review.length,
+        provider_calls_avoided: tiles.length - review.length,
+        mismatch_threshold: threshold,
+    };
+}