harnery 0.36.0 → 0.38.0

package/src/lib/browser/client.ts

@@ -11,8 +11,13 @@ import {
   type Cookie as PWCookie,
   type Request,
 } from "playwright";
-import type { CookieJar, Cookie as JarCookie } from "../cookies/index.ts";
+import {
+  type CookieJar,
+  CookieStoreParseError,
+  type Cookie as JarCookie,
+} from "../cookies/index.ts";
 import { type AssertResult, type AssertSpec, buildAssertCheck } from "./asserts.js";
+import { stitchPngRows } from "./capture-fidelity.js";
 import {
   buildClearContentAnnotationsScript,
   buildContentAnnotateScript,
@@ -36,6 +41,7 @@ import {
   type OverflowResult,
   type WidthResult,
 } from "./layout.js";
+import { isBenignNextRscAbort } from "./request-diagnostics.js";
 import {
   buildClearRuntsAnnotationsScript,
   buildRuntsAnnotateScript,
@@ -86,6 +92,17 @@ export interface BrowserOptions {
   jar?: CookieJar | null;
   /** Viewport. Default 1280x800. */
   viewport?: { width: number; height: number };
+  /**
+   * Device scale factor (DPR) for the context. Unset keeps Playwright's
+   * default of 1, so screenshots are CSS-pixel sized. A higher value renders
+   * every screenshot at that multiple (2 doubles both dimensions).
+   */
+  deviceScaleFactor?: number;
+  /**
+   * Emulated `prefers-color-scheme` for the context. Unset keeps Playwright's
+   * default (light), byte-identical to prior behavior.
+   */
+  colorScheme?: "light" | "dark";
   /** Default navigation timeout in ms. Default 30000. */
   navigationTimeout?: number;
   /**
@@ -308,12 +325,18 @@ export class Browser {
    * the whole sequence — not just the launch — can be retried as a unit.
    */
   private async openOnce(): Promise<void> {
+    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
           ? { args: this.opts.launchArgs }
@@ -328,11 +351,8 @@ export class Browser {
     }
     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
@@ -396,6 +416,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));
         }
@@ -425,11 +450,15 @@ export class Browser {
       this.pageErrors.push({ message: err.message, stack: err.stack });
     });
     page.on("requestfailed", (req: Request) => {
-      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",
       });
@@ -607,6 +636,181 @@ export class Browser {
     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: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }): Promise<Buffer> {
+    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: number) =>
+      page.evaluate(async (target: number) => {
+        window.scrollTo({ left: window.scrollX, top: target, behavior: "instant" });
+        const frame = () => new Promise<void>((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: Buffer[] = [];
+    // 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: Array<{
+        el: HTMLElement;
+        top: number;
+        priorOpacity: string;
+        priorOpacityPriority: string;
+        priorTransition: string;
+        priorTransitionPriority: string;
+      }> = [];
+      const all = document.querySelectorAll<HTMLElement>("body *");
+      const limit = Math.min(all.length, 20_000);
+      for (let i = 0; i < limit; i++) {
+        const el = all[i] as HTMLElement;
+        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: "hide-moved" | "restore") =>
+      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<void>((r) => requestAnimationFrame(() => r()));
+        },
+        [pinned, mode] as const,
+      );
+    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 }: { x: number; y: number }) =>
+            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: string,
@@ -1594,9 +1798,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/src/lib/browser/critique.ts

@@ -18,7 +18,12 @@
 //      orchestration live here; the model call lives in the host.
 
 import { PNG } from "pngjs";
-import { bandOversizedRect, snappedBandRects, type VisualAtom } from "./tiling.js";
+import {
+  bandOversizedRect,
+  bandsCoveringRects,
+  snappedBandRects,
+  type VisualAtom,
+} from "./tiling.js";
 
 export interface CritiqueTile {
   index: number;
@@ -42,10 +47,27 @@ export interface CritiqueFinding {
   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[];
@@ -137,6 +159,15 @@ export function bandRects(
  * 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: Buffer,
@@ -146,8 +177,11 @@ export function tilesFromFullPage(
     overlap?: number;
     maxTiles: number;
     atoms?: VisualAtom[];
+    hitRects?: Array<{ x: number; y: number; width: number; height: number }>;
+    /** Cap on hit bands appended past `maxTiles` (default 50). */
+    maxHitBands?: number;
   },
-): CritiqueTile[] {
+): { tiles: CritiqueTile[]; coverage: CritiqueCoverage; hitBands: number } {
   const png = PNG.sync.read(fullPageBuffer);
   const snapOpts = {
     bandHeight: opts.bandHeight ?? 1400,
@@ -185,8 +219,7 @@ export function tilesFromFullPage(
       height: b.height,
     }));
   }
-  const tiles: CritiqueTile[] = [];
-  for (const rect of rects.slice(0, opts.maxTiles)) {
+  const cutTile = (rect: (typeof rects)[number]): CritiqueTile => {
     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));
@@ -199,7 +232,7 @@ export function tilesFromFullPage(
       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,
@@ -207,9 +240,31 @@ export function tilesFromFullPage(
       width: w,
       height: h,
       pngBase64: PNG.sync.write(dst).toString("base64"),
-    });
+    };
+  };
+  const kept = rects.slice(0, opts.maxTiles);
+  const tiles: CritiqueTile[] = 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: CritiqueCoverage = {
+    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 };
 }
 
 /**

package/src/lib/browser/index.ts

@@ -39,6 +39,7 @@ export type {
 } from "./content-checks.js";
 export {
   bandRects,
+  type CritiqueCoverage,
   type CritiqueFinding,
   type CritiqueProvider,
   type CritiqueResult,
@@ -85,6 +86,39 @@ 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,
@@ -108,6 +142,37 @@ export {
   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 QaRunCritiquePool,
+  type QaRunInteraction,
+  type QaRunJob,
+  type QaRunJobValidation,
+  type QaRunPolicy,
+  type QaRunResult,
+  type QaRunReviewPack,
+  type QaRunVerdict,
+  validateQaRunJob,
+} from "./qa-run-contracts.js";
 export {
   listQaSnapshotTargets,
   loadQaSnapshot,