harnery 0.33.0 → 0.34.0

package/src/lib/browser/critique.ts

@@ -18,6 +18,7 @@
 //      orchestration live here; the model call lives in the host.
 
 import { PNG } from "pngjs";
+import { bandOversizedRect, snappedBandRects, type VisualAtom } from "./tiling.js";
 
 export interface CritiqueTile {
   index: number;
@@ -25,6 +26,9 @@ export interface CritiqueTile {
   label: string;
   /** Document-space Y offset of the tile's top, so findings map to a place. */
   scrollY: number;
+  /** Document-space X offset (0 for full-width bands; element-relative for
+   * selector tiles). Optional for backward compatibility — treat absent as 0. */
+  x?: number;
   width: number;
   height: number;
   /** Base64 PNG of the tile (no data: prefix). */
@@ -48,18 +52,32 @@ export interface CritiqueResult {
   outcome: "pass" | "fail" | "skipped";
   /** Set when skipped or a provider call failed. */
   error?: string;
+  /** Host-reported provider provenance (route, attempts, fallbacks, usage). */
+  provider_meta?: Record<string, unknown>;
 }
 
 /**
  * The host-injected model call. Given one tile and the rubric, return the
  * findings for that tile. Throwing is caught and surfaced as an error finding
  * so one bad tile never sinks the run.
+ *
+ * Optional properties let the host shape execution without widening the call
+ * contract: `concurrency` caps how many tiles run at once (default 4 — tiles
+ * are independent, and the wall-clock win is roughly the cap factor), and
+ * `meta()` is read once after the run so route/usage provenance lands on the
+ * result envelope.
  */
-export type CritiqueProvider = (input: {
+export type CritiqueProvider = ((input: {
   url: string;
   rubric: string;
   tile: CritiqueTile;
-}) => Promise<CritiqueFinding[]>;
+}) => Promise<CritiqueFinding[]>) & {
+  concurrency?: number;
+  meta?: () => Record<string, unknown> | undefined;
+  /** Long-edge pixel budget of the routed model's vision input. The tiler
+   * clamps band height to it so tiles are never downscaled by the provider. */
+  tileBudgetPx?: number;
+};
 
 export const DEFAULT_CRITIQUE_RUBRIC = [
   "You are reviewing one vertical slice of a rendered web page for visual defects.",
@@ -70,6 +88,10 @@ export const DEFAULT_CRITIQUE_RUBRIC = [
   "- broken, distorted, or missing images",
   "- leaked template tokens, placeholder text, or obviously wrong values",
   "- anything that looks broken, unfinished, or accidental",
+  "The slice's own top and bottom edges cut through the page at arbitrary points:",
+  "content cropped by the slice boundary itself (a heading, row, or paragraph",
+  "entering or leaving the frame) is a tiling artifact, NOT a defect - never report it.",
+  "Only report clipping that happens at an element's own container edge inside the slice.",
   "Do NOT comment on content quality, wording, tone, or subjective taste.",
   "If the slice looks fine, return an empty list. Be precise and terse.",
   "Return JSON only: an array of objects",
@@ -108,6 +130,13 @@ export function bandRects(
  * resolution. Pass `elementRects` for semantic (per-element) tiling; otherwise
  * the page is banded from the actual image height. Rects are clamped to the
  * image so an off-by-one never throws.
+ *
+ * When `atoms` are supplied (see tiling.ts), band seams snap into content
+ * gaps instead of cutting at fixed offsets, and element rects taller than the
+ * band budget are banded internally rather than shipped as one over-tall tile
+ * 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).
  */
 export function tilesFromFullPage(
   fullPageBuffer: Buffer,
@@ -116,20 +145,46 @@ export function tilesFromFullPage(
     bandHeight?: number;
     overlap?: number;
     maxTiles: number;
+    atoms?: VisualAtom[];
   },
 ): CritiqueTile[] {
   const png = PNG.sync.read(fullPageBuffer);
-  const rects =
-    opts.elementRects && opts.elementRects.length > 0
-      ? opts.elementRects.map((r, index) => ({ index, ...r }))
-      : bandRects(png.height, png.width, opts.bandHeight ?? 1400, opts.overlap ?? 120).map((b) => ({
-          index: b.index,
-          label: `band ${b.index + 1}`,
-          x: b.x,
-          y: b.y,
-          width: b.width,
-          height: b.height,
-        }));
+  const snapOpts = {
+    bandHeight: opts.bandHeight ?? 1400,
+    overlap: opts.overlap ?? 120,
+  };
+  let rects: Array<{
+    index: number;
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>;
+  if (opts.elementRects && opts.elementRects.length > 0) {
+    const expanded = opts.atoms
+      ? opts.elementRects.flatMap((r) => bandOversizedRect(r, opts.atoms ?? [], snapOpts))
+      : opts.elementRects;
+    rects = expanded.map((r, index) => ({ index, ...r }));
+  } else if (opts.atoms && opts.atoms.length > 0) {
+    rects = snappedBandRects(0, png.height, 0, png.width, opts.atoms, snapOpts).rects.map((b) => ({
+      index: b.index,
+      label: `band ${b.index + 1}`,
+      x: b.x,
+      y: b.y,
+      width: b.width,
+      height: b.height,
+    }));
+  } else {
+    rects = bandRects(png.height, png.width, snapOpts.bandHeight, snapOpts.overlap).map((b) => ({
+      index: b.index,
+      label: `band ${b.index + 1}`,
+      x: b.x,
+      y: b.y,
+      width: b.width,
+      height: b.height,
+    }));
+  }
   const tiles: CritiqueTile[] = [];
   for (const rect of rects.slice(0, opts.maxTiles)) {
     const sx = Math.max(0, Math.min(Math.round(rect.x), png.width - 1));
@@ -148,6 +203,7 @@ export function tilesFromFullPage(
       index: rect.index,
       label: rect.label,
       scrollY: sy,
+      x: sx,
       width: w,
       height: h,
       pngBase64: PNG.sync.write(dst).toString("base64"),
@@ -212,20 +268,41 @@ export async function runCritique(args: {
         "no critiqueProvider injected by the host (see HarneryProgramContext.critiqueProvider)",
     };
   }
-  const findings: CritiqueFinding[] = [];
-  for (const tile of tiles) {
-    try {
-      const tileFindings = await provider({ url, rubric, tile });
-      findings.push(...tileFindings.map((f) => ({ ...f, tile: tile.index })));
-    } catch (err: unknown) {
-      findings.push({
-        tile: tile.index,
-        severity: "high",
-        category: "provider-error",
-        description: `critique provider failed on ${tile.label}: ${err instanceof Error ? err.message : String(err)}`,
-      });
+  // Tiles are judged independently, so run them concurrently (bounded) and
+  // reassemble findings in tile order so artifacts stay deterministic.
+  const concurrency = Math.max(1, Math.min(provider.concurrency ?? 4, tiles.length || 1));
+  const perTile: CritiqueFinding[][] = tiles.map(() => []);
+  let cursor = 0;
+  const worker = async (): Promise<void> => {
+    while (true) {
+      const i = cursor++;
+      if (i >= tiles.length) return;
+      const tile = tiles[i];
+      try {
+        const tileFindings = await provider({ url, rubric, tile });
+        perTile[i] = tileFindings.map((f) => ({ ...f, tile: tile.index }));
+      } catch (err: unknown) {
+        perTile[i] = [
+          {
+            tile: tile.index,
+            severity: "high",
+            category: "provider-error",
+            description: `critique provider failed on ${tile.label}: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ];
+      }
     }
-  }
+  };
+  await Promise.all(Array.from({ length: concurrency }, () => worker()));
+  const findings = perTile.flat();
   const outcome = findings.some((f) => f.severity === "high") ? "fail" : "pass";
-  return { rule: "critique", tiles: tiles.length, provider: true, findings, outcome };
+  const meta = provider.meta?.();
+  return {
+    rule: "critique",
+    tiles: tiles.length,
+    provider: true,
+    findings,
+    outcome,
+    ...(meta ? { provider_meta: meta } : {}),
+  };
 }

package/src/lib/browser/geometry.ts

@@ -24,7 +24,13 @@ export interface LayoutElementMeasurement {
 export interface LayoutExclusion {
   index: number;
   tag: string;
-  reason: "hidden" | "zero-area" | "out-of-flow" | "limit";
+  reason:
+    | "hidden"
+    | "zero-area"
+    | "out-of-flow"
+    | "limit"
+    | "visually-hidden"
+    | "ellipsis-truncation";
 }
 
 export interface AlignChild extends LayoutElementMeasurement {
@@ -507,6 +513,53 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       return { x: clips.has(style.overflowX), y: clips.has(style.overflowY) };
     };
 
+    // The visually-hidden idiom (Tailwind `sr-only`, Bootstrap
+    // `visually-hidden`): a ~1px absolutely-positioned box whose content is
+    // clipped ON PURPOSE so it exists for assistive tech only. Its box is 1x1
+    // (not zero-area, so the zero-area exclusion misses it) and the legacy
+    // `clip: rect(0,0,0,0)` it relies on is not an overflow style, so nothing
+    // above recognizes it. Reporting it would flag every accessible page.
+    const isVisuallyHidden = (element: Element): boolean => {
+      const style = getComputedStyle(element);
+      if (style.position !== "absolute" && style.position !== "fixed") return false;
+      if (style.clip && style.clip !== "auto") return true;
+      const rect = element.getBoundingClientRect();
+      return rect.width <= 1 && rect.height <= 1 && style.overflow === "hidden";
+    };
+
+    const hasVisuallyHiddenAncestor = (start: Element | null, scope: Element): boolean => {
+      let current = start;
+      while (current && scope.contains(current)) {
+        if (isVisuallyHidden(current)) return true;
+        if (current === scope) break;
+        current = current.parentElement;
+      }
+      return false;
+    };
+
+    // Deliberate single-line truncation (`text-overflow: ellipsis` + nowrap +
+    // hidden overflow, the `truncate` utility): cutting the text is the
+    // design, and the dedicated truncation check owns auditing it. Only text
+    // under such an ancestor is exempt; element boxes still have to fit.
+    const ellipsizes = (element: Element): boolean => {
+      const style = getComputedStyle(element);
+      return (
+        style.textOverflow === "ellipsis" &&
+        style.whiteSpace === "nowrap" &&
+        (style.overflowX === "hidden" || style.overflowX === "clip")
+      );
+    };
+
+    const hasEllipsizingAncestor = (start: Element | null, scope: Element): boolean => {
+      let current = start;
+      while (current && scope.contains(current)) {
+        if (ellipsizes(current)) return true;
+        if (current === scope) break;
+        current = current.parentElement;
+      }
+      return false;
+    };
+
     // A scroller hides content the same way a clip does, but the reader can
     // reach it. Content below the fold of a capped table or right of a wide
     // code block is not a layout defect, so an axis stops being checked at the
@@ -519,6 +572,20 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       return { x: scrolls.has(style.overflowX), y: scrolls.has(style.overflowY) };
     };
 
+    const scrollsBeforeScope = (
+      start: Element | null,
+      scope: Element,
+      axis: "x" | "y",
+    ): boolean => {
+      let current = start;
+      while (current && scope.contains(current)) {
+        if (scrollingStyle(current)[axis]) return true;
+        if (current === scope) break;
+        current = current.parentElement;
+      }
+      return false;
+    };
+
     const unbounded = (): LayoutRect => ({
       x: Number.NEGATIVE_INFINITY,
       y: Number.NEGATIVE_INFINITY,
@@ -573,7 +640,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       const recordIssue = (
         element: LayoutElementMeasurement,
         allowed: LayoutRect,
-        clippedBy: string,
+        clippedBy: { x: string; y: string },
         axes: { x: boolean; y: boolean } = { x: true, y: true },
       ): void => {
         const rect = element.rect;
@@ -585,7 +652,14 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
         };
         const maxOverrunPx = Math.max(overrun.top, overrun.right, overrun.bottom, overrun.left);
         if (maxOverrunPx > tolerancePx + SUBPIXEL_EPSILON && issues.length < ISSUE_LIMIT) {
-          issues.push({ element, clippedBy, overrun, maxOverrunPx });
+          const horizontalOverrun = Math.max(overrun.left, overrun.right);
+          const verticalOverrun = Math.max(overrun.top, overrun.bottom);
+          issues.push({
+            element,
+            clippedBy: horizontalOverrun >= verticalOverrun ? clippedBy.x : clippedBy.y,
+            overrun,
+            maxOverrunPx,
+          });
         }
       };
 
@@ -599,9 +673,9 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
         container: Element,
         seed: LayoutRect,
         seedLabel: string,
-      ): { allowed: LayoutRect; clippedBy: string } => {
+      ): { allowed: LayoutRect; clippedBy: { x: string; y: string } } => {
         let allowed = { ...seed };
-        let clippedBy = seedLabel;
+        const clippedBy = { x: seedLabel, y: seedLabel };
         const free = { x: false, y: false };
         let current: Element | null = start;
         while (current && container.contains(current)) {
@@ -622,6 +696,14 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
           };
           if (clips.x || clips.y) {
             const candidate = paddingRect(current);
+            const tightensX =
+              clips.x &&
+              (candidate.left > allowed.left + SUBPIXEL_EPSILON ||
+                candidate.right < allowed.right - SUBPIXEL_EPSILON);
+            const tightensY =
+              clips.y &&
+              (candidate.top > allowed.top + SUBPIXEL_EPSILON ||
+                candidate.bottom < allowed.bottom - SUBPIXEL_EPSILON);
             allowed = {
               x: clips.x ? Math.max(allowed.left, candidate.left) : allowed.left,
               y: clips.y ? Math.max(allowed.top, candidate.top) : allowed.top,
@@ -634,7 +716,11 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
             };
             allowed.width = Math.max(0, allowed.right - allowed.left);
             allowed.height = Math.max(0, allowed.bottom - allowed.top);
-            clippedBy = labelOf(current);
+            // Keep the label of the boundary that actually made each axis
+            // smaller. A wider outer scope should not hide the nearer parent
+            // responsible for a horizontal overrun.
+            if (tightensX) clippedBy.x = labelOf(current);
+            if (tightensY) clippedBy.y = labelOf(current);
           }
           if (scrolls.x) free.x = true;
           if (scrolls.y) free.y = true;
@@ -644,7 +730,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
         return { allowed, clippedBy };
       };
 
-      const textContainer = (node: Node, scope: Element): Element | null => {
+      const nearestBlockOwner = (node: Node, scope: Element): Element | null => {
         let current = node.parentElement;
         while (current && scope.contains(current)) {
           if (current instanceof SVGElement) return null;
@@ -665,17 +751,38 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
             excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "hidden" });
             return;
           }
+          if (hasVisuallyHiddenAncestor(element, container)) {
+            excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "visually-hidden" });
+            return;
+          }
           const rect = element.getBoundingClientRect();
           if (rect.width <= 0 || rect.height <= 0) {
             excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "zero-area" });
             return;
           }
-          const chain = clipChain(
-            element.parentElement,
-            container,
-            unbounded(),
-            labelOf(container),
-          );
+          // CSS overflow defaults to visible, so a child can escape a grid or
+          // flex cell without any clipping ancestor noticing. Constrain
+          // in-flow boxes horizontally to their nearest block owner. Vertical
+          // parent containment is intentionally left to real CSS clips because
+          // normal margin collapse can paint outside a parent's vertical box.
+          const owner = nearestBlockOwner(element, container);
+          const seed = unbounded();
+          let seedLabel = labelOf(container);
+          const position = getComputedStyle(element).position;
+          if (
+            owner &&
+            position !== "absolute" &&
+            position !== "fixed" &&
+            !scrollsBeforeScope(owner, container, "x")
+          ) {
+            const ownerRect = paddingRect(owner);
+            seed.left = ownerRect.left;
+            seed.right = ownerRect.right;
+            seed.x = seed.left;
+            seed.width = Math.max(0, seed.right - seed.left);
+            seedLabel = labelOf(owner);
+          }
+          const chain = clipChain(element.parentElement, container, seed, seedLabel);
           recordIssue(measure(element, index, false), chain.allowed, chain.clippedBy);
         });
 
@@ -696,8 +803,24 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
           ) {
             continue;
           }
-          const owner = textContainer(node, container);
+          const owner = nearestBlockOwner(node, container);
           if (!owner) continue;
+          if (hasVisuallyHiddenAncestor(parent, container)) {
+            excluded.push({
+              index: measurementIndex++,
+              tag: parent.tagName.toLowerCase(),
+              reason: "visually-hidden",
+            });
+            continue;
+          }
+          if (hasEllipsizingAncestor(parent, container)) {
+            excluded.push({
+              index: measurementIndex++,
+              tag: parent.tagName.toLowerCase(),
+              reason: "ellipsis-truncation",
+            });
+            continue;
+          }
           let transformed = false;
           let current: Element | null = owner;
           while (current && container.contains(current)) {
@@ -856,6 +979,11 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       "COL",
       "COLGROUP",
     ]);
+    // Code-family chips are inline controls, not layout cards, but the
+    // radius-vs-size pill test misses them (a code chip's radius is modest)
+    // and a flex/grid tag row blockifies their computed display, defeating
+    // the inline-display exclusion. Exclude them by tag.
+    const CONTROL_TAGS = new Set(["CODE", "KBD", "SAMP", "VAR", "OUTPUT"]);
 
     const maxCornerRadiusPx = (style: CSSStyleDeclaration, minDim: number): number => {
       const corners = [
@@ -877,6 +1005,7 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
 
     const isPanel = (element: Element): boolean => {
       if (STRUCTURAL_TAGS.has(element.tagName)) return false;
+      if (CONTROL_TAGS.has(element.tagName)) return false;
       const style = getComputedStyle(element);
       if (style.display.startsWith("table") || style.display.startsWith("inline")) return false;
       if (style.boxShadow && style.boxShadow !== "none") return true;

package/src/lib/browser/index.ts

@@ -93,6 +93,32 @@ export {
   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 {
+  listQaSnapshotTargets,
+  loadQaSnapshot,
+  QA_SNAPSHOT_DIR,
+  type QaSnapshotStoreOptions,
+  qaSnapshotKey,
+  type ResolvedQaBaseline,
+  resolveQaBaseline,
+  type StoredQaSnapshot,
+  saveQaSnapshot,
+} from "./qa-snapshot.js";
 export type {
   RuntHit,
   RuntsResult,
@@ -120,6 +146,14 @@ export type {
   TargetSizeProfile,
   TargetSizeResult,
 } from "./target-size.js";
+export {
+  bandOversizedRect,
+  cutCost,
+  type SnapOptions,
+  type SnapSeam,
+  snappedBandRects,
+  type VisualAtom,
+} from "./tiling.js";
 export type {
   CheckVisibilityOptions,
   VisibilityResult,