harnery 0.37.0 → 0.38.0

package/dist/lib/browser/client.js

@@ -3,10 +3,13 @@ import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import axe from "axe-core";
 import { chromium, } from "playwright";
+import { CookieStoreParseError, } from "../cookies/index.js";
 import { buildAssertCheck } from "./asserts.js";
+import { stitchPngRows } from "./capture-fidelity.js";
 import { buildClearContentAnnotationsScript, buildContentAnnotateScript, buildContentChecks, } from "./content-checks.js";
 import { buildClearLayoutLintAnnotationsScript, buildLayoutLintAnnotateScript, buildLayoutLintCheck, } from "./geometry.js";
 import { buildClearLayoutAnnotationsScript, buildLayoutAnnotateScript, buildOverflowCheck, buildWidthCheck, } from "./layout.js";
+import { isBenignNextRscAbort } from "./request-diagnostics.js";
 import { buildClearRuntsAnnotationsScript, buildRuntsAnnotateScript, buildRuntsCheck, } from "./runts.js";
 import { buildStandaloneHtmlScript, DEFAULT_MAX_RESOURCE_BYTES, DEFAULT_MAX_TOTAL_RESOURCE_BYTES, } from "./standalone-html.js";
 import { buildClearTargetSizeAnnotationsScript, buildTargetSizeAnnotateScript, buildTargetSizeCheck, } from "./target-size.js";
@@ -81,12 +84,16 @@ export class Browser {
      * the whole sequence — not just the launch — can be retried as a unit.
      */
     async openOnce() {
+        const jarCookies = this.opts.jar?.list() ?? [];
         // Hold a launch slot only across the spawn itself, not the browser's life.
         await acquireLaunchSlot();
         try {
             this.context = await chromium.launchPersistentContext(this.profileDir, {
                 headless: !this.opts.headed,
                 viewport: this.opts.viewport ?? { width: 1280, height: 800 },
+                ...(this.opts.deviceScaleFactor !== undefined
+                    ? { deviceScaleFactor: this.opts.deviceScaleFactor }
+                    : {}),
                 ...(this.opts.colorScheme ? { colorScheme: this.opts.colorScheme } : {}),
                 ...(this.opts.launchTimeout !== undefined ? { timeout: this.opts.launchTimeout } : {}),
                 ...(this.opts.launchArgs && this.opts.launchArgs.length > 0
@@ -102,11 +109,8 @@ export class Browser {
             releaseLaunchSlot();
         }
         this.context.setDefaultNavigationTimeout(this.opts.navigationTimeout ?? 30_000);
-        if (this.opts.jar) {
-            const jarCookies = this.opts.jar.list();
-            if (jarCookies.length > 0) {
-                await this.context.addCookies(jarCookies.map(toPWCookie));
-            }
+        if (jarCookies.length > 0) {
+            await this.context.addCookies(jarCookies.map(toPWCookie));
         }
         // Caller-injected extraHeaders callback (e.g., for Cloudflare-bypass
         // or custom auth headers). Per-request route handler so headers only
@@ -171,6 +175,11 @@ export class Browser {
                 this.consoleEvents = [];
                 this.pageErrors = [];
                 this.failedRequests = [];
+                if (err instanceof CookieStoreParseError) {
+                    throw new Error(`Failed to open browser during cookie-store load: ${err.message}`, {
+                        cause: err,
+                    });
+                }
                 if (attempt < maxAttempts) {
                     await new Promise((resolve) => setTimeout(resolve, attempt * 250));
                 }
@@ -197,11 +206,16 @@ export class Browser {
             this.pageErrors.push({ message: err.message, stack: err.stack });
         });
         page.on("requestfailed", (req) => {
-            this.failedRequests.push({
+            const failedRequest = {
                 url: req.url(),
                 method: req.method(),
                 failure: req.failure()?.errorText ?? "unknown",
                 resourceType: req.resourceType(),
+            };
+            if (isBenignNextRscAbort(failedRequest))
+                return;
+            this.failedRequests.push({
+                ...failedRequest,
                 status: null,
                 kind: "network",
             });
@@ -357,6 +371,152 @@ export class Browser {
         const buf = await this.currentPage.screenshot({ type: "png", clip: rect });
         return buf.toString("base64");
     }
+    /**
+     * PNG of a document-space rect captured the way a reader sees it: scroll so
+     * the rect's top sits at the top of the viewport, wait for the scroll to
+     * settle (instant scroll, then rAF frames until `scrollY` stops moving),
+     * and clip the viewport. Restores the scroll position afterwards.
+     *
+     * Bands are taller than the viewport. Rather than resizing the viewport to
+     * the band height (which reflows `vh`-sized layout, moves sticky and fixed
+     * elements, and so stops matching what the user sees), the rect is captured
+     * in viewport-height pieces at the real viewport and the pieces are
+     * stitched with pngjs. The final piece of a multi-piece rect is anchored to
+     * the viewport bottom so a fixed header, which sits at the viewport top, is
+     * not repeated in the middle of the band. No viewport change is made.
+     *
+     * Pixels come back at the page's device scale factor, so a rect at DPR 2
+     * yields an image twice the rect's CSS size, the same as a full-page
+     * screenshot cropped in pixel space would.
+     *
+     * Parity with the full-page screenshot: a full-page capture renders the
+     * whole document as one viewport, so a fixed header or a stuck sticky bar
+     * appears once, at its document position. Scrolled, the same element would
+     * ride along at the top of every piece and differ from the full-page crop
+     * on every band but the first. So while a piece is captured at a non-zero
+     * scroll, every `position: fixed`/`sticky` element that has left its
+     * scroll-0 document position is given `visibility: hidden` (layout kept,
+     * inline style restored afterwards). The result is the region as a
+     * full-page screenshot would show it, without the full-page raster.
+     */
+    async captureRegionByScroll(rect) {
+        const page = this.currentPage;
+        if (!(rect.width > 0) || !(rect.height > 0)) {
+            throw new Error(`captureRegionByScroll: rect must have a positive size (got ${rect.width}×${rect.height})`);
+        }
+        const settle = (top) => page.evaluate(async (target) => {
+            window.scrollTo({ left: window.scrollX, top: target, behavior: "instant" });
+            const frame = () => new Promise((r) => requestAnimationFrame(() => r()));
+            let last = Number.NaN;
+            for (let i = 0; i < 8; i++) {
+                await frame();
+                const now = window.scrollY;
+                if (now === last)
+                    break;
+                last = now;
+            }
+            return {
+                scrollX: window.scrollX,
+                scrollY: window.scrollY,
+                innerWidth: window.innerWidth,
+                innerHeight: window.innerHeight,
+            };
+        }, top);
+        const original = await page.evaluate(() => ({ x: window.scrollX, y: window.scrollY }));
+        const pieces = [];
+        // Viewport-pinned candidates, measured at scroll 0 so each later capture
+        // can tell "still where the full page shows it" from "riding along".
+        await settle(0);
+        // Hiding uses opacity, not visibility: `visibility: hidden` on the pinned
+        // element is undone by any descendant that sets `visibility: visible`
+        // (a revealed brand label inside a sticky bar did exactly that), while
+        // opacity is a group effect no descendant can override. Transitions are
+        // switched off inline so the capture never lands mid-fade.
+        const pinned = await page.evaluateHandle(() => {
+            const out = [];
+            const all = document.querySelectorAll("body *");
+            const limit = Math.min(all.length, 20_000);
+            for (let i = 0; i < limit; i++) {
+                const el = all[i];
+                const position = getComputedStyle(el).position;
+                if (position !== "fixed" && position !== "sticky")
+                    continue;
+                out.push({
+                    el,
+                    top: el.getBoundingClientRect().top + window.scrollY,
+                    priorOpacity: el.style.getPropertyValue("opacity"),
+                    priorOpacityPriority: el.style.getPropertyPriority("opacity"),
+                    priorTransition: el.style.getPropertyValue("transition"),
+                    priorTransitionPriority: el.style.getPropertyPriority("transition"),
+                });
+            }
+            return out;
+        });
+        const syncPinned = (mode) => page.evaluate(async ([entries, action]) => {
+            for (const entry of entries) {
+                const restore = () => {
+                    entry.el.style.setProperty("opacity", entry.priorOpacity, entry.priorOpacityPriority);
+                    entry.el.style.setProperty("transition", entry.priorTransition, entry.priorTransitionPriority);
+                };
+                if (action === "restore") {
+                    restore();
+                    continue;
+                }
+                const now = entry.el.getBoundingClientRect().top + window.scrollY;
+                if (Math.abs(now - entry.top) > 1) {
+                    entry.el.style.setProperty("transition", "none", "important");
+                    entry.el.style.setProperty("opacity", "0", "important");
+                }
+                else {
+                    restore();
+                }
+            }
+            // Let the style change paint before the screenshot is taken.
+            await new Promise((r) => requestAnimationFrame(() => r()));
+        }, [pinned, mode]);
+        try {
+            const bottom = rect.y + rect.height;
+            let cursor = rect.y;
+            let first = true;
+            while (cursor < bottom) {
+                const remaining = bottom - cursor;
+                // Top-align the piece; a final partial piece is then re-anchored to
+                // the viewport bottom once the viewport height is known.
+                let view = await settle(cursor);
+                if (!first && remaining < view.innerHeight) {
+                    view = await settle(Math.max(0, bottom - view.innerHeight));
+                }
+                await syncPinned("hide-moved");
+                const offset = cursor - view.scrollY;
+                if (offset < 0 || offset >= view.innerHeight) {
+                    throw new Error(`captureRegionByScroll: document y ${cursor} is not reachable in the viewport ` +
+                        `(scrollY ${view.scrollY}, innerHeight ${view.innerHeight})`);
+                }
+                const pieceHeight = Math.min(remaining, view.innerHeight - offset);
+                const clipX = Math.max(0, rect.x - view.scrollX);
+                const clipWidth = Math.min(rect.width, view.innerWidth - clipX);
+                if (!(clipWidth > 0)) {
+                    throw new Error(`captureRegionByScroll: document x ${rect.x} is outside the viewport (innerWidth ${view.innerWidth})`);
+                }
+                pieces.push(await page.screenshot({
+                    type: "png",
+                    clip: { x: clipX, y: offset, width: clipWidth, height: pieceHeight },
+                }));
+                cursor += pieceHeight;
+                first = false;
+            }
+        }
+        finally {
+            try {
+                await syncPinned("restore");
+            }
+            finally {
+                await pinned.dispose();
+                await page.evaluate(({ x, y }) => window.scrollTo({ left: x, top: y, behavior: "instant" }), original);
+            }
+        }
+        return stitchPngRows(pieces);
+    }
     /** Document-space rects + labels for each element matching `selector` (semantic tiling). */
     async elementTiles(selector) {
         return await this.currentPage.evaluate((sel) => {
@@ -1230,9 +1390,7 @@ export class Browser {
         if (this.opts.jar) {
             try {
                 const live = await this.context.cookies();
-                for (const c of live) {
-                    this.opts.jar.set(toJarCookie(c));
-                }
+                this.opts.jar.merge(live.map(toJarCookie));
             }
             catch {
                 // Cookie persist is best-effort; never block close on it.

package/dist/lib/browser/critique.d.ts

@@ -19,10 +19,26 @@ export interface CritiqueFinding {
     category: string;
     description: string;
 }
+/**
+ * How much of the page the tiles actually cover. The tiler keeps at most
+ * `maxTiles` bands and drops the rest, so on a tall page `capped` is true and
+ * `reviewed_height_px` stops short of `page_height_px`. Callers that turn a
+ * critique into a verdict must read this: a pass over the first 24 bands is
+ * not a pass over the page.
+ */
+export interface CritiqueCoverage {
+    page_height_px: number;
+    reviewed_height_px: number;
+    bands_total: number;
+    bands_reviewed: number;
+    capped: boolean;
+}
 export interface CritiqueResult {
     rule: "critique";
     /** Number of tiles the page was cut into. */
     tiles: number;
+    /** Tile coverage of the page; absent only for results built without tiles. */
+    coverage?: CritiqueCoverage;
     /** Whether a provider was available. False → outcome "skipped". */
     provider: boolean;
     findings: CritiqueFinding[];
@@ -82,6 +98,15 @@ export declare function bandRects(pageHeight: number, pageWidth: number, bandHei
  * the provider would downscale. Atom coordinates must be in the same pixel
  * space as the screenshot (identical at deviceScaleFactor 1; scale them if
  * the capture DPR differs).
+ *
+ * `hitRects` (document-space rectangles a deterministic gate already flagged)
+ * add bands past the `maxTiles` cap: every full-page band that intersects a
+ * hit rect and was dropped by the cap is cut as well, labelled `hit band N`
+ * (N is the band's 1-based position in the full band list, and the tile's
+ * `index` is that position minus one), and appended after the kept bands.
+ * `coverage` stays honest about the kept prefix; `hitBands` counts the
+ * extras. Ignored for selector tiling (`elementRects`), which has no cap to
+ * look past in that sense.
  */
 export declare function tilesFromFullPage(fullPageBuffer: Buffer, opts: {
     elementRects?: Array<{
@@ -95,7 +120,19 @@ export declare function tilesFromFullPage(fullPageBuffer: Buffer, opts: {
     overlap?: number;
     maxTiles: number;
     atoms?: VisualAtom[];
-}): CritiqueTile[];
+    hitRects?: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>;
+    /** Cap on hit bands appended past `maxTiles` (default 50). */
+    maxHitBands?: number;
+}): {
+    tiles: CritiqueTile[];
+    coverage: CritiqueCoverage;
+    hitBands: number;
+};
 /**
  * Validate + normalize a provider's raw output into CritiqueFindings. Tolerant
  * of a model returning a bare array or wrapping it in `{ findings: [...] }`,

package/dist/lib/browser/critique.d.ts.map

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

package/dist/lib/browser/critique.js

@@ -17,7 +17,7 @@
 //      false pass. That keeps this portable — the tiling, prompt, and
 //      orchestration live here; the model call lives in the host.
 import { PNG } from "pngjs";
-import { bandOversizedRect, snappedBandRects } from "./tiling.js";
+import { bandOversizedRect, bandsCoveringRects, snappedBandRects, } from "./tiling.js";
 export const DEFAULT_CRITIQUE_RUBRIC = [
     "You are reviewing one vertical slice of a rendered web page for visual defects.",
     "Report ONLY concrete, visible problems a careful designer would flag:",
@@ -71,6 +71,15 @@ export function bandRects(pageHeight, pageWidth, bandHeight, overlap) {
  * the provider would downscale. Atom coordinates must be in the same pixel
  * space as the screenshot (identical at deviceScaleFactor 1; scale them if
  * the capture DPR differs).
+ *
+ * `hitRects` (document-space rectangles a deterministic gate already flagged)
+ * add bands past the `maxTiles` cap: every full-page band that intersects a
+ * hit rect and was dropped by the cap is cut as well, labelled `hit band N`
+ * (N is the band's 1-based position in the full band list, and the tile's
+ * `index` is that position minus one), and appended after the kept bands.
+ * `coverage` stays honest about the kept prefix; `hitBands` counts the
+ * extras. Ignored for selector tiling (`elementRects`), which has no cap to
+ * look past in that sense.
  */
 export function tilesFromFullPage(fullPageBuffer, opts) {
     const png = PNG.sync.read(fullPageBuffer);
@@ -105,8 +114,7 @@ export function tilesFromFullPage(fullPageBuffer, opts) {
             height: b.height,
         }));
     }
-    const tiles = [];
-    for (const rect of rects.slice(0, opts.maxTiles)) {
+    const cutTile = (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.max(1, Math.min(Math.round(rect.width), png.width - sx));
@@ -119,7 +127,7 @@ export function tilesFromFullPage(fullPageBuffer, opts) {
             const dstStart = row * w * 4;
             png.data.copy(dst.data, dstStart, srcStart, srcStart + w * 4);
         }
-        tiles.push({
+        return {
             index: rect.index,
             label: rect.label,
             scrollY: sy,
@@ -127,9 +135,29 @@ export function tilesFromFullPage(fullPageBuffer, opts) {
             width: w,
             height: h,
             pngBase64: PNG.sync.write(dst).toString("base64"),
-        });
+        };
+    };
+    const kept = rects.slice(0, opts.maxTiles);
+    const tiles = kept.map(cutTile);
+    let hitBands = 0;
+    const banding = !(opts.elementRects && opts.elementRects.length > 0);
+    if (banding && opts.hitRects && opts.hitRects.length > 0) {
+        for (const index of bandsCoveringRects(rects, kept.length, opts.hitRects, opts.maxHitBands)) {
+            const band = rects[index];
+            if (!band)
+                continue;
+            tiles.push(cutTile({ ...band, label: `hit band ${index + 1}` }));
+            hitBands++;
+        }
     }
-    return tiles;
+    const coverage = {
+        page_height_px: png.height,
+        reviewed_height_px: kept.reduce((max, rect) => Math.max(max, Math.min(png.height, Math.round(rect.y + rect.height))), 0),
+        bands_total: rects.length,
+        bands_reviewed: kept.length,
+        capped: rects.length > kept.length,
+    };
+    return { tiles, coverage, hitBands };
 }
 /**
  * Validate + normalize a provider's raw output into CritiqueFindings. Tolerant

package/dist/lib/browser/index.d.ts

@@ -1,17 +1,19 @@
 export { type AssertOp, type AssertResult, type AssertSpec, buildAssertCheck, parseAssertSpec, } from "./asserts.js";
 export { Browser, type BrowserOptions, BrowserSessionActionError, type BrowserSessionControl, type BrowserSessionInspection, type BrowserSessionLocator, type BrowserSessionNavigation, type BrowserSessionNavigationType, type BrowserSessionScreenshot, type BrowserSessionStatus, type BrowserSessionTab, type ConsoleEvent, type Diagnostics, type FailedRequest, type NavigateResult, type PageErrorEvent, } from "./client.js";
 export type { CheckRect, ContentAnnotationBox, ContentChecksRequest, ContentChecksResult, ContrastHit, ContrastResult, ImageHealthResult, ImageHit, PlaceholderHit, PlaceholderResult, TruncationHit, TruncationResult, } from "./content-checks.js";
-export { bandRects, type CritiqueFinding, type CritiqueProvider, type CritiqueResult, type CritiqueTile, DEFAULT_CRITIQUE_RUBRIC, normalizeFindings, runCritique, tilesFromFullPage, } from "./critique.js";
+export { bandRects, type CritiqueCoverage, type CritiqueFinding, type CritiqueProvider, type CritiqueResult, type CritiqueTile, DEFAULT_CRITIQUE_RUBRIC, normalizeFindings, runCritique, tilesFromFullPage, } from "./critique.js";
 export { captureDevOverlay, type DevOverlayError, type DevOverlayResult, } from "./dev-overlay.js";
 export type { AlignChild, AlignCluster, AlignResult, ClipIssue, ClipResult, CrowdPair, CrowdResult, GapCluster, GapPair, GapResult, LayoutAxis, LayoutElementMeasurement, LayoutExclusion, LayoutLintRequest, LayoutLintResult, LayoutOutcome, LayoutRect, OverlapIssue, OverlapResult, } from "./geometry.js";
 export { buildLayoutLintCheck } from "./geometry.js";
 export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export type { OverflowElement, OverflowResult, WidthResult, } from "./layout.js";
 export { serializeNetscapeCookies, writeNetscapeCookieFile, } from "./netscape-cookies.js";
+export { type JudgedContext, type JudgePageReviewPackOptions, type JudgePageReviewPackResult, judgePageReviewPack, toCritiqueRecords, } from "./page-review-judge.js";
+export { buildInspectionPlan, type FinalizePageReviewPackInput, finalizePageReviewPack, findingsSchemaDocument, listPackContexts, PAGE_REVIEW_FINDINGS_SCHEMA, PAGE_REVIEW_PACK_DIRNAME, PAGE_REVIEW_PACK_SCHEMA, type PageReviewContextCapture, type PageReviewContextRecord, type PageReviewCritiqueRecord, type PageReviewGateRecord, type PageReviewInspectionPlan, type PageReviewPackManifest, type PageReviewTileRecord, packPaths, readPackContext, readPackDom, readPackFullPage, readPackManifest, readPackSignature, readPackTiles, renderReviewMarkdown, writePackContext, } from "./page-review-pack.js";
 export { type BrowserProxy, type BrowserProxyGate, browserProxyFromEnv, browserProxyGateFromEnv, extractObservedIp, WEBRTC_PROXY_ONLY_ARG, } from "./proxy.js";
 export { buildQaManifest, type ChangeClass, type ClassifyOptions, classifySignatures, fnv1a32, type ManifestOptions, type QaClassification, type QaContext, type QaManifest, type QaNodeSignature, type QaScope, type QaSignature, type QaStylesheetSignature, } from "./qa-plan.js";
 export { defaultQaRunExec, QA_RUN_HEADLESS_ONLY_ENV, QA_RUN_RESULT_FILENAME, type QaRunExec, type QaRunExecOptions, type QaRunExecResult, type QaRunMatrixOptions, runQaMatrix, } from "./qa-run.js";
-export { computeVerdict, contextIdFor, mergeCoverage, QA_RUN_JOB_SCHEMA_VERSION, QA_RUN_RESULT_SCHEMA_VERSION, type QaRunBlocker, type QaRunCheck, type QaRunCommandOutcome, type QaRunContext, type QaRunCritiqueOutcome, type QaRunInteraction, type QaRunJob, type QaRunJobValidation, type QaRunPolicy, type QaRunResult, type QaRunVerdict, validateQaRunJob, } from "./qa-run-contracts.js";
+export { computeVerdict, contextIdFor, mergeCoverage, QA_RUN_JOB_SCHEMA_VERSION, QA_RUN_RESULT_SCHEMA_VERSION, type QaRunBlocker, type QaRunCheck, type QaRunCommandOutcome, type QaRunContext, type QaRunCritiqueOutcome, type QaRunCritiquePool, type QaRunInteraction, type QaRunJob, type QaRunJobValidation, type QaRunPolicy, type QaRunResult, type QaRunReviewPack, type QaRunVerdict, validateQaRunJob, } from "./qa-run-contracts.js";
 export { listQaSnapshotTargets, loadQaSnapshot, QA_SNAPSHOT_DIR, type QaSnapshotStoreOptions, qaSnapshotKey, type ResolvedQaBaseline, resolveQaBaseline, type StoredQaSnapshot, saveQaSnapshot, } from "./qa-snapshot.js";
 export type { RuntHit, RuntsResult, } from "./runts.js";
 export { BROWSER_SESSION_MAX_FILL_BYTES, BROWSER_SESSION_MAX_FRAME_BYTES, BROWSER_SESSION_MAX_INSPECTION_TEXT_BYTES, BROWSER_SESSION_PROTOCOL_VERSION, type BrowserSessionDescriptor, BrowserSessionError, type BrowserSessionRequest, type BrowserSessionResponse, type BrowserSessionResult, type BrowserSessionServer, type BrowserSessionTarget, browserSessionTransport, readBrowserSessionDescriptor, sendBrowserSessionRequest, startBrowserSessionServer, } from "./session-control.js";

package/dist/lib/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,gBAAgB,EAChB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,OAAO,EACP,KAAK,cAAc,EACnB,yBAAyB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,SAAS,EACT,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,SAAS,EACT,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,uBAAuB,EACvB,iBAAiB,EACjB,WAAW,EACX,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,UAAU,EACV,YAAY,EACZ,WAAW,EACX,SAAS,EACT,UAAU,EACV,SAAS,EACT,WAAW,EACX,UAAU,EACV,OAAO,EACP,SAAS,EACT,UAAU,EACV,wBAAwB,EACxB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,YAAY,EACZ,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,kBAAkB,EAClB,OAAO,EACP,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,sBAAsB,EACtB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,aAAa,EACb,yBAAyB,EACzB,4BAA4B,EAC5B,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,KAAK,sBAAsB,EAC3B,aAAa,EACb,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,8BAA8B,EAC9B,+BAA+B,EAC/B,yCAAyC,EACzC,gCAAgC,EAChC,KAAK,wBAAwB,EAC7B,mBAAmB,EACnB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,iBAAiB,EACjB,OAAO,EACP,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/browser/index.js

@@ -5,6 +5,8 @@ export { captureDevOverlay, } from "./dev-overlay.js";
 export { buildLayoutLintCheck } from "./geometry.js";
 export { isWSL, wslHeadedLaunchArgs } from "./launch-args.js";
 export { serializeNetscapeCookies, writeNetscapeCookieFile, } from "./netscape-cookies.js";
+export { judgePageReviewPack, toCritiqueRecords, } from "./page-review-judge.js";
+export { buildInspectionPlan, finalizePageReviewPack, findingsSchemaDocument, listPackContexts, PAGE_REVIEW_FINDINGS_SCHEMA, PAGE_REVIEW_PACK_DIRNAME, PAGE_REVIEW_PACK_SCHEMA, packPaths, readPackContext, readPackDom, readPackFullPage, readPackManifest, readPackSignature, readPackTiles, renderReviewMarkdown, writePackContext, } from "./page-review-pack.js";
 export { browserProxyFromEnv, browserProxyGateFromEnv, extractObservedIp, WEBRTC_PROXY_ONLY_ARG, } from "./proxy.js";
 export { buildQaManifest, classifySignatures, fnv1a32, } from "./qa-plan.js";
 export { defaultQaRunExec, QA_RUN_HEADLESS_ONLY_ENV, QA_RUN_RESULT_FILENAME, runQaMatrix, } from "./qa-run.js";

package/dist/lib/browser/page-review-judge.d.ts

@@ -0,0 +1,64 @@
+import type { CritiqueProvider } from "./critique.js";
+import { type PageReviewContextRecord, type PageReviewCritiqueRecord } from "./page-review-pack.js";
+import { type CritiqueReusePlan } from "./qa-reuse.js";
+import { type QaSnapshotStoreOptions } from "./qa-snapshot.js";
+export interface JudgePageReviewPackOptions {
+    packDir: string;
+    /** Host-injected vision call. Absent: every context reports `skipped`. */
+    provider: CritiqueProvider | undefined;
+    rubric: string;
+    /** Vision calls in flight across the whole pack. Default: the provider's
+     * own concurrency, then 4. */
+    concurrency?: number;
+    /** Subset of context ids to judge (default: every context in the pack). */
+    contextIds?: string[];
+    /** Band-diff reuse against persisted snapshots keyed by `target`. */
+    reuse?: {
+        target: string;
+        store?: QaSnapshotStoreOptions;
+        mismatchThreshold?: number;
+    };
+    /** Absolute epoch-ms deadline. Workers stop claiming tiles once past it;
+     * a context with unjudged tiles reports `incomplete`, never `pass`. */
+    deadlineAt?: number;
+    onLog?: (message: string) => void;
+}
+export interface JudgedContext extends PageReviewCritiqueRecord {
+    record: PageReviewContextRecord;
+    /** Tiles selected for review that the pool never reached (deadline). */
+    tiles_unjudged: number;
+    reuse?: Pick<CritiqueReusePlan, "tiles_total" | "tiles_reused" | "tiles_reviewed" | "invalidation" | "mismatch_threshold">;
+}
+export interface JudgePageReviewPackResult {
+    contexts: JudgedContext[];
+    pool: {
+        concurrency: number;
+        wall_time_ms: number;
+        provider: string;
+    };
+    tiles_total: number;
+    tiles_reviewed: number;
+    tiles_reused: number;
+    outcome: "pass" | "fail" | "skipped" | "incomplete";
+    provider_meta?: Record<string, unknown>;
+}
+/**
+ * Orientation the provider reads before the rubric: which band this tile is,
+ * where it sits on the page, how much of it repeats a neighbour, whether it
+ * touches the page top or bottom, and how it was captured. A tile edge that
+ * continues in the next band is not a clipped element, and a fixed header at
+ * the top of a scrolled-band capture is not a layout defect; the preamble
+ * says so where the pixels cannot. Adds context only: the finding taxonomy
+ * the rubric defines is unchanged. Empty for an unknown tile id.
+ */
+export declare function tileRubricPreamble(record: PageReviewContextRecord, tileId: string): string;
+/**
+ * Judge every tile in the pack through one pool. Findings keep the tiler
+ * index (`tile`) for compatibility with `CritiqueFinding` and add the pack's
+ * stable `tile_id`. A provider throw on one tile becomes a `high`
+ * `provider-error` finding for that tile; nothing else is affected.
+ */
+export declare function judgePageReviewPack(options: JudgePageReviewPackOptions): Promise<JudgePageReviewPackResult>;
+/** Strip the in-memory `record` so the result can be written into the pack. */
+export declare function toCritiqueRecords(result: JudgePageReviewPackResult): PageReviewCritiqueRecord[];
+//# sourceMappingURL=page-review-judge.d.ts.map

package/dist/lib/browser/page-review-judge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-review-judge.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/page-review-judge.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAmB,gBAAgB,EAAgB,MAAM,eAAe,CAAC;AACrF,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAI9B,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,KAAK,iBAAiB,EAAqB,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAkB,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf;kCAC8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,qEAAqE;IACrE,KAAK,CAAC,EAAE;QACN,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,sBAAsB,CAAC;QAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF;2EACuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,aAAc,SAAQ,wBAAwB;IAC7D,MAAM,EAAE,uBAAuB,CAAC;IAChC,wEAAwE;IACxE,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,IAAI,CACV,iBAAiB,EACjB,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,cAAc,GAAG,oBAAoB,CAC1F,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,YAAY,CAAC;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAUD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,uBAAuB,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA2E1F;AAaD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,yBAAyB,CAAC,CA4KpC;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,yBAAyB,GAAG,wBAAwB,EAAE,CAI/F"}