harnery 0.30.0 → 0.31.0

package/src/lib/browser/critique.ts

@@ -0,0 +1,231 @@
+// Vision-model page critic for `harn browse --check-critique`.
+//
+// Heuristic checks only catch what we can enumerate. The reason a human still
+// eyeballs a page is the long tail — the odd thing that "looks off" without
+// tripping a named rule. This hands a rendered page to a vision model and asks
+// for that judgement, structured.
+//
+// Two things keep it honest:
+//   1. Tiling. A tall page screenshotted whole and downscaled to a model's
+//      input budget loses the detail the critique depends on. So the page is
+//      cut into overlapping vertical bands (or one tile per selector match),
+//      each captured at full resolution and judged on its own, with findings
+//      tagged by tile + document scroll offset for locality.
+//   2. Injection. harnery ships no model client and no API key. The host wires
+//      a `critiqueProvider` into the program context (same pattern as
+//      `extraHeaders`); without one, the check reports `skipped`, never a
+//      false pass. That keeps this portable — the tiling, prompt, and
+//      orchestration live here; the model call lives in the host.
+
+import { PNG } from "pngjs";
+
+export interface CritiqueTile {
+  index: number;
+  /** Section label or "band N", for locating a finding. */
+  label: string;
+  /** Document-space Y offset of the tile's top, so findings map to a place. */
+  scrollY: number;
+  width: number;
+  height: number;
+  /** Base64 PNG of the tile (no data: prefix). */
+  pngBase64: string;
+}
+
+export interface CritiqueFinding {
+  tile: number;
+  severity: "high" | "medium" | "low";
+  category: string;
+  description: string;
+}
+
+export interface CritiqueResult {
+  rule: "critique";
+  /** Number of tiles the page was cut into. */
+  tiles: number;
+  /** Whether a provider was available. False → outcome "skipped". */
+  provider: boolean;
+  findings: CritiqueFinding[];
+  outcome: "pass" | "fail" | "skipped";
+  /** Set when skipped or a provider call failed. */
+  error?: string;
+}
+
+/**
+ * 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.
+ */
+export type CritiqueProvider = (input: {
+  url: string;
+  rubric: string;
+  tile: CritiqueTile;
+}) => Promise<CritiqueFinding[]>;
+
+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:",
+  "- text cut off, overlapping, or colliding with other elements",
+  "- text that is hard to read against its background (low contrast)",
+  "- misaligned or unevenly spaced elements; two blocks touching with no gap",
+  "- broken, distorted, or missing images",
+  "- leaked template tokens, placeholder text, or obviously wrong values",
+  "- anything that looks broken, unfinished, or accidental",
+  "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",
+  '{"severity":"high|medium|low","category":"<short-slug>","description":"<one sentence>"}.',
+].join("\n");
+
+/**
+ * Cut a page of height `pageHeight` into overlapping vertical bands. Pure math
+ * so the caller (which owns the page) can screenshot each `clip` rect. The
+ * overlap keeps a finding that straddles a seam visible in at least one tile.
+ */
+export function bandRects(
+  pageHeight: number,
+  pageWidth: number,
+  bandHeight: number,
+  overlap: number,
+): Array<{ index: number; x: number; y: number; width: number; height: number }> {
+  const bands: Array<{ index: number; x: number; y: number; width: number; height: number }> = [];
+  if (pageHeight <= 0 || pageWidth <= 0) return bands;
+  const step = Math.max(1, bandHeight - overlap);
+  let index = 0;
+  for (let y = 0; y < pageHeight; y += step) {
+    const height = Math.min(bandHeight, pageHeight - y);
+    bands.push({ index, x: 0, y, width: pageWidth, height });
+    index++;
+    if (y + height >= pageHeight) break;
+  }
+  return bands;
+}
+
+/**
+ * Cut tiles out of ONE full-page screenshot with pngjs. Playwright's own
+ * `clip` is viewport-relative, so a band below the fold errors with "clipped
+ * area outside the resulting image" — capturing the whole page once and
+ * cropping in pixel space sidesteps that and keeps every tile at full
+ * 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.
+ */
+export function tilesFromFullPage(
+  fullPageBuffer: Buffer,
+  opts: {
+    elementRects?: Array<{ label: string; x: number; y: number; width: number; height: number }>;
+    bandHeight?: number;
+    overlap?: number;
+    maxTiles: number;
+  },
+): 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 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));
+    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));
+    const h = Math.max(1, Math.min(Math.round(rect.height), png.height - sy));
+    const dst = new PNG({ width: w, height: h });
+    // Manual RGBA row copy — pngjs's bitblt isn't available under every runtime
+    // (missing under Bun's build), so copy the crop window row by row instead.
+    for (let row = 0; row < h; row++) {
+      const srcStart = ((sy + row) * png.width + sx) * 4;
+      const dstStart = row * w * 4;
+      png.data.copy(dst.data, dstStart, srcStart, srcStart + w * 4);
+    }
+    tiles.push({
+      index: rect.index,
+      label: rect.label,
+      scrollY: sy,
+      width: w,
+      height: h,
+      pngBase64: PNG.sync.write(dst).toString("base64"),
+    });
+  }
+  return tiles;
+}
+
+/**
+ * Validate + normalize a provider's raw output into CritiqueFindings. Tolerant
+ * of a model returning a bare array or wrapping it in `{ findings: [...] }`,
+ * and drops entries that are not shaped like a finding.
+ */
+export function normalizeFindings(raw: unknown, tile: number): CritiqueFinding[] {
+  const arr = Array.isArray(raw)
+    ? raw
+    : raw && typeof raw === "object" && Array.isArray((raw as { findings?: unknown }).findings)
+      ? (raw as { findings: unknown[] }).findings
+      : [];
+  const severities = new Set(["high", "medium", "low"]);
+  const out: CritiqueFinding[] = [];
+  for (const item of arr) {
+    if (!item || typeof item !== "object") continue;
+    const record = item as Record<string, unknown>;
+    const severity = String(record.severity ?? "low").toLowerCase();
+    const description = typeof record.description === "string" ? record.description.trim() : "";
+    if (!description) continue;
+    out.push({
+      tile,
+      severity: severities.has(severity) ? (severity as CritiqueFinding["severity"]) : "low",
+      category:
+        typeof record.category === "string" && record.category.trim()
+          ? record.category.trim()
+          : "visual",
+      description,
+    });
+  }
+  return out;
+}
+
+/**
+ * Run the critique over pre-captured tiles with an injected provider. Findings
+ * are collected across tiles; a provider throw becomes a `high` error finding
+ * for that tile rather than aborting. Outcome is `fail` when any `high` finding
+ * survives (the gate escalation lives in the caller).
+ */
+export async function runCritique(args: {
+  url: string;
+  rubric: string;
+  tiles: CritiqueTile[];
+  provider: CritiqueProvider | undefined;
+}): Promise<CritiqueResult> {
+  const { url, rubric, tiles, provider } = args;
+  if (!provider) {
+    return {
+      rule: "critique",
+      tiles: tiles.length,
+      provider: false,
+      findings: [],
+      outcome: "skipped",
+      error:
+        "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)}`,
+      });
+    }
+  }
+  const outcome = findings.some((f) => f.severity === "high") ? "fail" : "pass";
+  return { rule: "critique", tiles: tiles.length, provider: true, findings, outcome };
+}

package/src/lib/browser/geometry.ts

@@ -115,6 +115,35 @@ export interface OverlapResult {
   truncated: boolean;
 }
 
+export interface CrowdPair {
+  before: LayoutElementMeasurement;
+  after: LayoutElementMeasurement;
+  /** Edge separation along `axis` in CSS px; negative means the panels overlap. */
+  separationPx: number;
+  /** "y" = stacked, "x" = side by side, "overlap" = they intersect in 2D. */
+  axis: "x" | "y" | "overlap";
+  minGapPx: number;
+  /** DOM label of the shared parent, so the fix location is obvious. */
+  parentLabel: string;
+  /**
+   * Whether each consecutive sibling peer was a leaf panel or a wrapper that
+   * contains panels. `before`/`after` always measure the nearest face panels
+   * (a descendant when the peer is composite).
+   */
+  beforeKind: "panel" | "composite";
+  afterKind: "panel" | "composite";
+}
+
+export interface CrowdResult {
+  rule: "crowd";
+  selector: string;
+  found: boolean;
+  outcome: LayoutOutcome;
+  minGapPx: number;
+  issues: CrowdPair[];
+  truncated: boolean;
+}
+
 export interface LayoutLintRequest {
   align: Array<{ selector: string; axis: LayoutAxis; tolerancePx: number }>;
   gap: Array<{
@@ -125,6 +154,7 @@ export interface LayoutLintRequest {
   }>;
   clip: Array<{ selector: string; tolerancePx: number }>;
   overlap: Array<{ selector: string; tolerancePx: number }>;
+  crowd: Array<{ selector: string; minGapPx: number }>;
 }
 
 export interface LayoutLintResult {
@@ -132,6 +162,7 @@ export interface LayoutLintResult {
   gap: GapResult[];
   clip: ClipResult[];
   overlap: OverlapResult[];
+  crowd: CrowdResult[];
 }
 
 export function median(values: number[]): number {
@@ -631,7 +662,241 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       };
     });
 
-    return { align, gap, clip, overlap };
+    // A "panel" here means a card-like callout — a block that reads as its own
+    // standalone box: a full (4-side) border, a modest corner radius, or a
+    // box-shadow. Two flush cards read as one merged block, which `overlap`
+    // (needs a 2D intersection) and `gap` (flags uneven spacing, so a
+    // uniformly-flush stack passes) both miss.
+    //
+    // Crowd peers are also *composites*: in-flow siblings that are not panels
+    // themselves but contain at least one panel descendant (a card grid, a
+    // flow of cards, etc.). Comparing only leaf panels missed the common case
+    // where a wrapper-of-cards sits flush against the next card. Separation is
+    // measured between the nearest face panels inside each peer, not the
+    // wrapper boxes, so a tall section with a card near the top and prose
+    // below does not false-fail against the next sibling.
+    //
+    // Deliberately NOT flagged: structural elements that are flush BY DESIGN —
+    // table cells, list/definition rows, and divided segments (a bg-only cell
+    // in a `gap:1px` strip). Those have no card boundary of their own, so the
+    // test below excludes them without a special-case allowlist. Pills, chips,
+    // and badges (radius ≥ half their smaller side) are inline controls, not
+    // layout cards, and are excluded too. Plain blocks with no panel chrome
+    // and no panel descendants stay out of the peer list.
+    const PARENT_LIMIT = 2000;
+    const PANEL_DESCENDANT_LIMIT = 100;
+    const OVERLAP_EPS = 1;
+    const STRUCTURAL_TAGS = new Set([
+      "TD",
+      "TH",
+      "TR",
+      "THEAD",
+      "TBODY",
+      "TFOOT",
+      "COL",
+      "COLGROUP",
+    ]);
+
+    const maxCornerRadiusPx = (style: CSSStyleDeclaration, minDim: number): number => {
+      const corners = [
+        "border-top-left-radius",
+        "border-top-right-radius",
+        "border-bottom-right-radius",
+        "border-bottom-left-radius",
+      ];
+      let max = 0;
+      for (const corner of corners) {
+        const token = (style.getPropertyValue(corner) || "").trim().split(/\s+/)[0] ?? "";
+        const value = token.endsWith("%")
+          ? (Number.parseFloat(token) / 100) * minDim
+          : Number.parseFloat(token) || 0;
+        if (value > max) max = value;
+      }
+      return max;
+    };
+
+    const isPanel = (element: Element): boolean => {
+      if (STRUCTURAL_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;
+      const sides = ["top", "right", "bottom", "left"];
+      const fullBorder = sides.every((side) => {
+        const width = Number.parseFloat(style.getPropertyValue(`border-${side}-width`)) || 0;
+        const lineStyle = style.getPropertyValue(`border-${side}-style`);
+        return width > 0 && lineStyle !== "none" && lineStyle !== "";
+      });
+      if (fullBorder) return true;
+      const rect = element.getBoundingClientRect();
+      const minDim = Math.min(rect.width, rect.height);
+      const radius = maxCornerRadiusPx(style, minDim);
+      // A card has a modest radius; a pill/circle (radius ≥ half its short side)
+      // is a control, not a card.
+      return radius >= 3 && radius < minDim / 2 - 1;
+    };
+
+    const isInFlowBox = (element: Element): boolean => {
+      if (isHidden(element)) return false;
+      const style = getComputedStyle(element);
+      if (style.position === "absolute" || style.position === "fixed") return false;
+      const rect = element.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0;
+    };
+
+    /** Leaf panel faces that represent a crowd peer (self, or descendants). */
+    const collectPanelFaces = (
+      element: Element,
+      selfIsPanel: boolean,
+    ): LayoutElementMeasurement[] => {
+      if (selfIsPanel) return [measure(element, 0, false)];
+      const faces: LayoutElementMeasurement[] = [];
+      const descendants = element.querySelectorAll("*");
+      for (let i = 0; i < descendants.length && faces.length < PANEL_DESCENDANT_LIMIT; i++) {
+        const child = descendants[i];
+        if (!child || !isInFlowBox(child) || !isPanel(child)) continue;
+        faces.push(measure(child, faces.length, false));
+      }
+      return faces;
+    };
+
+    // In-flow, visible, non-zero-area direct children that are crowd peers:
+    // leaf panels, or composites that wrap at least one panel. Non-peer
+    // siblings (plain prose, arrows, spacers) drop out of the list so two
+    // panels separated only by chrome still get a face-to-face check.
+    const collectCrowdPeers = (
+      parent: Element,
+    ): Array<{
+      kind: "panel" | "composite";
+      faces: LayoutElementMeasurement[];
+    }> => {
+      const out: Array<{
+        kind: "panel" | "composite";
+        faces: LayoutElementMeasurement[];
+      }> = [];
+      const children = [...parent.children];
+      for (let index = 0; index < children.length && index < CHILD_LIMIT; index++) {
+        const element = children[index];
+        if (!element || !isInFlowBox(element)) continue;
+        const selfIsPanel = isPanel(element);
+        const faces = collectPanelFaces(element, selfIsPanel);
+        if (faces.length === 0) continue;
+        out.push({
+          kind: selfIsPanel ? "panel" : "composite",
+          faces,
+        });
+      }
+      return out;
+    };
+
+    const separationOf = (
+      a: LayoutElementMeasurement,
+      b: LayoutElementMeasurement,
+    ): { axis: "x" | "y" | "overlap" | "none"; sep: number } => {
+      const ra = a.rect;
+      const rb = b.rect;
+      const yOverlap = Math.min(ra.bottom, rb.bottom) - Math.max(ra.top, rb.top);
+      const xOverlap = Math.min(ra.right, rb.right) - Math.max(ra.left, rb.left);
+      const sharesY = yOverlap > OVERLAP_EPS;
+      const sharesX = xOverlap > OVERLAP_EPS;
+      if (sharesX && sharesY) return { axis: "overlap", sep: -Math.min(xOverlap, yOverlap) };
+      if (sharesX) {
+        const [upper, lower] = ra.top <= rb.top ? [ra, rb] : [rb, ra];
+        return { axis: "y", sep: lower.top - upper.bottom };
+      }
+      if (sharesY) {
+        const [left, right] = ra.left <= rb.left ? [ra, rb] : [rb, ra];
+        return { axis: "x", sep: right.left - left.right };
+      }
+      // Diagonal (e.g. a grid row wrap): not edge-adjacent, so never crowded.
+      const vGap = Math.max(ra.top, rb.top) - Math.min(ra.bottom, rb.bottom);
+      const hGap = Math.max(ra.left, rb.left) - Math.min(ra.right, rb.right);
+      return { axis: "none", sep: Math.max(vGap, hGap) };
+    };
+
+    /** Tightest edge-adjacent face pair across two peers' panel faces. */
+    const nearestCrowdPair = (
+      beforeFaces: LayoutElementMeasurement[],
+      afterFaces: LayoutElementMeasurement[],
+    ): {
+      before: LayoutElementMeasurement;
+      after: LayoutElementMeasurement;
+      axis: "x" | "y" | "overlap";
+      sep: number;
+    } | null => {
+      let best: {
+        before: LayoutElementMeasurement;
+        after: LayoutElementMeasurement;
+        axis: "x" | "y" | "overlap";
+        sep: number;
+      } | null = null;
+      for (const before of beforeFaces) {
+        for (const after of afterFaces) {
+          const { axis, sep } = separationOf(before, after);
+          if (axis === "none") continue;
+          if (best === null || sep < best.sep) {
+            best = { before, after, axis, sep };
+          }
+        }
+      }
+      return best;
+    };
+
+    const crowd = request.crowd.map(({ selector, minGapPx }): CrowdResult => {
+      const container = document.querySelector(selector);
+      if (!(container instanceof Element)) {
+        return {
+          rule: "crowd" as const,
+          selector,
+          found: false,
+          outcome: "fail" as const,
+          minGapPx,
+          issues: [],
+          truncated: false,
+        };
+      }
+      const parents: Element[] = [container, ...container.querySelectorAll("*")];
+      const issues: CrowdPair[] = [];
+      let truncated = parents.length > PARENT_LIMIT;
+      const limit = Math.min(parents.length, PARENT_LIMIT);
+      for (let p = 0; p < limit; p++) {
+        const parent = parents[p]!;
+        const peers = collectCrowdPeers(parent);
+        for (let i = 1; i < peers.length; i++) {
+          const beforePeer = peers[i - 1]!;
+          const afterPeer = peers[i]!;
+          const best = nearestCrowdPair(beforePeer.faces, afterPeer.faces);
+          if (!best) continue;
+          if (best.sep < minGapPx) {
+            issues.push({
+              before: best.before,
+              after: best.after,
+              separationPx: best.sep,
+              axis: best.axis,
+              minGapPx,
+              parentLabel: labelOf(parent),
+              beforeKind: beforePeer.kind,
+              afterKind: afterPeer.kind,
+            });
+            if (issues.length >= ISSUE_LIMIT) {
+              truncated = true;
+              break;
+            }
+          }
+        }
+        if (issues.length >= ISSUE_LIMIT) break;
+      }
+      return {
+        rule: "crowd" as const,
+        selector,
+        found: true,
+        outcome: issues.length > 0 ? ("fail" as const) : ("pass" as const),
+        minGapPx,
+        issues,
+        truncated,
+      };
+    });
+
+    return { align, gap, clip, overlap, crowd };
   };
 }
 
@@ -685,6 +950,37 @@ export function buildLayoutLintAnnotateScript(): (result: LayoutLintResult) => v
         box(issue.intersection, "#e11d48", `overlap ${issue.areaPx.toFixed(0)}px²`);
       }
     }
+    for (const check of result.crowd) {
+      for (const issue of check.issues) {
+        // Draw the touching seam: a thin strip along the edge the two panels
+        // share, so "no space here" is visible even at zero separation.
+        const a = issue.before.rect;
+        const b = issue.after.rect;
+        const seam: LayoutRect =
+          issue.axis === "x"
+            ? {
+                x: Math.min(a.right, b.right),
+                y: Math.max(a.top, b.top),
+                width: Math.max(2, Math.abs(issue.separationPx)),
+                height: Math.max(1, Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top)),
+                top: Math.max(a.top, b.top),
+                right: 0,
+                bottom: 0,
+                left: Math.min(a.right, b.right),
+              }
+            : {
+                x: Math.max(a.left, b.left),
+                y: Math.min(a.bottom, b.bottom),
+                width: Math.max(1, Math.min(a.right, b.right) - Math.max(a.left, b.left)),
+                height: Math.max(2, Math.abs(issue.separationPx)),
+                top: Math.min(a.bottom, b.bottom),
+                right: 0,
+                bottom: 0,
+                left: Math.max(a.left, b.left),
+              };
+        box(seam, "#14b8a6", `crowd ${issue.separationPx.toFixed(1)}px`);
+      }
+    }
   };
 }
 

package/src/lib/browser/index.ts

@@ -1,3 +1,10 @@
+export {
+  type AssertOp,
+  type AssertResult,
+  type AssertSpec,
+  buildAssertCheck,
+  parseAssertSpec,
+} from "./asserts.js";
 export {
   Browser,
   type BrowserOptions,
@@ -7,6 +14,31 @@ export {
   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 {
   captureDevOverlay,
   type DevOverlayError,
@@ -18,6 +50,8 @@ export type {
   AlignResult,
   ClipIssue,
   ClipResult,
+  CrowdPair,
+  CrowdResult,
   GapCluster,
   GapPair,
   GapResult,

package/src/lib/claude-desktop.ts

@@ -226,7 +226,10 @@ export interface MirrorOptions {
 
 export function entryMatchesSelector(entry: DesktopSessionEntry, selector: string): boolean {
   if (entry.cliSessionId === selector || entry.sessionId === selector) return true;
-  return entry.title !== null && entry.title.toLowerCase().includes(selector.toLowerCase());
+  // Optional chain rather than a null guard: the reader normalises a missing
+  // title to null, but this is exported, and a hand-built entry with an absent
+  // title would slip past `!== null` and then throw on the method call.
+  return entry.title?.toLowerCase().includes(selector.toLowerCase()) ?? false;
 }
 
 /**