harnery 0.31.6 → 0.32.0

package/src/lib/browser/geometry.ts

@@ -198,8 +198,12 @@ export function intersectRects(a: LayoutRect, b: LayoutRect): LayoutRect | null
  */
 export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLintResult {
   return (request) => {
-    const CHILD_LIMIT = 250;
+    const CHILD_LIMIT = 1_000;
+    const TEXT_LIMIT = 1_000;
     const ISSUE_LIMIT = 100;
+    // Chromium geometry is fractional even when authored CSS is integral.
+    // Differences below half a CSS pixel are rasterization noise, not clipping.
+    const SUBPIXEL_EPSILON = 0.5;
 
     const rectOf = (rect: DOMRect): LayoutRect => ({
       x: rect.x,
@@ -233,6 +237,14 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
     const isHidden = (element: Element): boolean => {
       let current: Element | null = element;
       while (current) {
+        // A collapsed disclosure hides its content through the ::details-content
+        // pseudo, which is not in the ancestor chain, so no computed style on a
+        // real ancestor reports it. Without this, every closed accordion panel
+        // reads as text clipped out of its container.
+        const parent: Element | null = current.parentElement;
+        if (parent instanceof HTMLDetailsElement && !parent.open && current.tagName !== "SUMMARY") {
+          return true;
+        }
         const style = getComputedStyle(current);
         const contentVisibility = (style as CSSStyleDeclaration & { contentVisibility?: string })
           .contentVisibility;
@@ -495,6 +507,29 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       return { x: clips.has(style.overflowX), y: clips.has(style.overflowY) };
     };
 
+    // 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
+    // first ancestor that scrolls it. Constraints from ancestors INSIDE that
+    // scroller still apply -- an overflow:hidden box within a scroller really
+    // does cut its content off, and the scroller cannot reveal it.
+    const scrollingStyle = (element: Element): { x: boolean; y: boolean } => {
+      const style = getComputedStyle(element);
+      const scrolls = new Set(["auto", "scroll"]);
+      return { x: scrolls.has(style.overflowX), y: scrolls.has(style.overflowY) };
+    };
+
+    const unbounded = (): LayoutRect => ({
+      x: Number.NEGATIVE_INFINITY,
+      y: Number.NEGATIVE_INFINITY,
+      left: Number.NEGATIVE_INFINITY,
+      top: Number.NEGATIVE_INFINITY,
+      right: Number.POSITIVE_INFINITY,
+      bottom: Number.POSITIVE_INFINITY,
+      width: Number.POSITIVE_INFINITY,
+      height: Number.POSITIVE_INFINITY,
+    });
+
     const paddingRect = (element: Element): LayoutRect => {
       const rect = element.getBoundingClientRect();
       const html = element as HTMLElement;
@@ -515,8 +550,8 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
     };
 
     const clip = request.clip.map(({ selector, tolerancePx }): ClipResult => {
-      const container = document.querySelector(selector);
-      if (!(container instanceof Element)) {
+      const containers = [...document.querySelectorAll(selector)];
+      if (containers.length === 0) {
         return {
           rule: "clip" as const,
           selector,
@@ -532,31 +567,59 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
       const unsupported = new Set<string>();
       const excluded: LayoutExclusion[] = [];
       const issues: ClipIssue[] = [];
-      const descendants = [...container.querySelectorAll("*")];
-      let truncated = descendants.length > CHILD_LIMIT;
-      descendants.slice(0, CHILD_LIMIT).forEach((element, index) => {
-        if (isHidden(element)) {
-          excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "hidden" });
-          return;
-        }
-        const rect = element.getBoundingClientRect();
-        if (rect.width <= 0 || rect.height <= 0) {
-          excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "zero-area" });
-          return;
+      let truncated = false;
+      let measurementIndex = 0;
+
+      const recordIssue = (
+        element: LayoutElementMeasurement,
+        allowed: LayoutRect,
+        clippedBy: string,
+        axes: { x: boolean; y: boolean } = { x: true, y: true },
+      ): void => {
+        const rect = element.rect;
+        const overrun = {
+          top: axes.y ? Math.max(0, allowed.top - rect.top) : 0,
+          right: axes.x ? Math.max(0, rect.right - allowed.right) : 0,
+          bottom: axes.y ? Math.max(0, rect.bottom - allowed.bottom) : 0,
+          left: axes.x ? Math.max(0, allowed.left - rect.left) : 0,
+        };
+        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 });
         }
-        let allowed = paddingRect(container);
-        let clippedBy = labelOf(container);
-        let current: Element | null = element.parentElement;
+      };
+
+      // Walk from `start` up to `container`, intersecting the allowed rect with
+      // every ancestor that genuinely clips. `free` records an axis the reader
+      // can scroll, after which nothing further constrains that axis -- the
+      // scroller's own box still has to fit its outer chain, but its contents
+      // are reachable and so are exempt.
+      const clipChain = (
+        start: Element | null,
+        container: Element,
+        seed: LayoutRect,
+        seedLabel: string,
+      ): { allowed: LayoutRect; clippedBy: string } => {
+        let allowed = { ...seed };
+        let clippedBy = seedLabel;
+        const free = { x: false, y: false };
+        let current: Element | null = start;
         while (current && container.contains(current)) {
           const style = getComputedStyle(current);
           if (style.clipPath && style.clipPath !== "none")
             unsupported.add(`${labelOf(current)}:clip-path`);
-          if (style.borderRadius && !/^0(?:px)?(?: 0(?:px)?){0,3}$/.test(style.borderRadius)) {
-            unsupported.add(`${labelOf(current)}:border-radius`);
-          }
           if (style.transform && style.transform !== "none")
             unsupported.add(`${labelOf(current)}:transform`);
-          const clips = current === container ? { x: true, y: true } : clippingStyle(current);
+          // The container bounds by default even when it does not CSS-clip,
+          // since it is the scope the caller asked about -- but a scroller
+          // hands its axis back whether it is the scope or an ancestor.
+          const scope = current === container;
+          const scrolls = scrollingStyle(current);
+          const css = scope ? { x: true, y: true } : clippingStyle(current);
+          const clips = {
+            x: css.x && !free.x && !scrolls.x,
+            y: css.y && !free.y && !scrolls.y,
+          };
           if (clips.x || clips.y) {
             const candidate = paddingRect(current);
             allowed = {
@@ -573,26 +636,123 @@ export function buildLayoutLintCheck(): (request: LayoutLintRequest) => LayoutLi
             allowed.height = Math.max(0, allowed.bottom - allowed.top);
             clippedBy = labelOf(current);
           }
-          if (current === container) break;
+          if (scrolls.x) free.x = true;
+          if (scrolls.y) free.y = true;
+          if (scope) break;
           current = current.parentElement;
         }
-        const overrun = {
-          top: Math.max(0, allowed.top - rect.top),
-          right: Math.max(0, rect.right - allowed.right),
-          bottom: Math.max(0, rect.bottom - allowed.bottom),
-          left: Math.max(0, allowed.left - rect.left),
-        };
-        const maxOverrunPx = Math.max(overrun.top, overrun.right, overrun.bottom, overrun.left);
-        if (maxOverrunPx > tolerancePx && issues.length < ISSUE_LIMIT) {
-          issues.push({
-            element: measure(element, index, false),
-            clippedBy,
-            overrun,
-            maxOverrunPx,
-          });
+        return { allowed, clippedBy };
+      };
+
+      const textContainer = (node: Node, scope: Element): Element | null => {
+        let current = node.parentElement;
+        while (current && scope.contains(current)) {
+          if (current instanceof SVGElement) return null;
+          const display = getComputedStyle(current).display;
+          if (display !== "inline" && display !== "contents") return current;
+          if (current === scope) return current;
+          current = current.parentElement;
         }
-      });
+        return scope;
+      };
+
+      for (const container of containers) {
+        const descendants = [...container.querySelectorAll("*")];
+        if (descendants.length > CHILD_LIMIT) truncated = true;
+        descendants.slice(0, CHILD_LIMIT).forEach((element) => {
+          const index = measurementIndex++;
+          if (isHidden(element)) {
+            excluded.push({ index, tag: element.tagName.toLowerCase(), reason: "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),
+          );
+          recordIssue(measure(element, index, false), chain.allowed, chain.clippedBy);
+        });
+
+        const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT);
+        let textCount = 0;
+        for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+          if (textCount >= TEXT_LIMIT) {
+            truncated = true;
+            break;
+          }
+          const value = node.nodeValue ?? "";
+          if (!/\S/.test(value)) continue;
+          const parent = node.parentElement;
+          if (
+            !parent ||
+            ["SCRIPT", "STYLE", "NOSCRIPT", "TEMPLATE"].includes(parent.tagName) ||
+            isHidden(parent)
+          ) {
+            continue;
+          }
+          const owner = textContainer(node, container);
+          if (!owner) continue;
+          let transformed = false;
+          let current: Element | null = owner;
+          while (current && container.contains(current)) {
+            const transform = getComputedStyle(current).transform;
+            if (transform && transform !== "none") {
+              unsupported.add(`${labelOf(current)}:transform`);
+              transformed = true;
+              break;
+            }
+            if (current === container) break;
+            current = current.parentElement;
+          }
+          if (transformed) continue;
+          textCount++;
+          // Text glyph boxes routinely extend a few pixels above/below their
+          // line box. That is normal font paint, not clipping. Constrain text
+          // horizontally to its nearest block owner, vertically to the scope,
+          // and on either axis where a CSS ancestor actually clips.
+          const seed = unbounded();
+          // Constrain text horizontally to its nearest block owner -- unless
+          // that owner scrolls sideways, where running past its edge is how a
+          // long line is meant to behave.
+          if (!scrollingStyle(owner).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);
+          }
+          const chain = clipChain(owner, container, seed, labelOf(owner));
+          const allowed = chain.allowed;
+          const clippedBy = chain.clippedBy;
+          const range = document.createRange();
+          range.selectNodeContents(node);
+          for (const fragment of [...range.getClientRects()]) {
+            if (fragment.width <= 0 || fragment.height <= 0) continue;
+            const index = measurementIndex++;
+            recordIssue(
+              {
+                index,
+                tag: parent.tagName.toLowerCase(),
+                label: labelOf(parent),
+                snippet: value.replace(/\s+/g, " ").trim().slice(0, 160),
+                source: "text",
+                rect: rectOf(fragment),
+              },
+              allowed,
+              clippedBy,
+            );
+          }
+        }
+      }
       if (issues.length >= ISSUE_LIMIT) truncated = true;
+      // Border radius keeps the rectangular padding-box contract; only shapes
+      // the rectangle cannot certify contribute to unsupported geometry.
       const outcome: LayoutOutcome =
         issues.length > 0 ? "fail" : unsupported.size > 0 ? "unknown" : "pass";
       return {

package/src/lib/browser/index.ts

@@ -8,6 +8,15 @@ export {
 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,
@@ -65,16 +74,46 @@ export type {
   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 BrowserProxy,
+  type BrowserProxyGate,
+  browserProxyFromEnv,
+  browserProxyGateFromEnv,
+  extractObservedIp,
+  WEBRTC_PROXY_ONLY_ARG,
+} from "./proxy.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";
 export type {
   TargetSizeNode,
   TargetSizeOutcome,

package/src/lib/browser/netscape-cookies.ts

@@ -0,0 +1,39 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { Cookie } from "playwright";
+
+function cookieField(value: string): string {
+  return value.replace(/[\t\r\n]/g, "");
+}
+
+/** Serialize Playwright cookies in the Netscape cookies.txt format used by yt-dlp. */
+export function serializeNetscapeCookies(cookies: readonly Cookie[]): string {
+  const lines = ["# Netscape HTTP Cookie File", "# Generated by harn browse. Keep private.", ""];
+  for (const cookie of [...cookies].sort((a, b) =>
+    `${a.domain}\0${a.path}\0${a.name}`.localeCompare(`${b.domain}\0${b.path}\0${b.name}`),
+  )) {
+    const domain = `${cookie.httpOnly ? "#HttpOnly_" : ""}${cookieField(cookie.domain)}`;
+    const includeSubdomains = cookie.domain.startsWith(".") ? "TRUE" : "FALSE";
+    const secure = cookie.secure ? "TRUE" : "FALSE";
+    const expires = cookie.expires > 0 ? String(Math.floor(cookie.expires)) : "0";
+    lines.push(
+      [
+        domain,
+        includeSubdomains,
+        cookieField(cookie.path || "/"),
+        secure,
+        expires,
+        cookieField(cookie.name),
+        cookieField(cookie.value),
+      ].join("\t"),
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Write a credential-bearing cookie file with owner-only permissions. */
+export function writeNetscapeCookieFile(path: string, cookies: readonly Cookie[]): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, serializeNetscapeCookies(cookies), { mode: 0o600 });
+  chmodSync(path, 0o600);
+}

package/src/lib/browser/proxy.ts

@@ -0,0 +1,105 @@
+export interface BrowserProxy {
+  server: string;
+  username?: string;
+  password?: string;
+}
+
+export interface BrowserProxyGate {
+  checkUrl: string;
+  expectedIp: string;
+}
+
+const PROXY_ENV_KEYS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"] as const;
+
+/**
+ * Parse an authenticated HTTP(S) proxy from the child environment without
+ * requiring credentials in command arguments. The returned server never
+ * contains userinfo, so Playwright owns the 407 challenge response.
+ */
+export function browserProxyFromEnv(env: NodeJS.ProcessEnv = process.env): BrowserProxy {
+  const raw = PROXY_ENV_KEYS.map((key) => env[key]).find(
+    (value): value is string => typeof value === "string" && value.trim().length > 0,
+  );
+  if (!raw) {
+    throw new Error(
+      "--proxy-from-env requires HTTPS_PROXY, https_proxy, HTTP_PROXY, or http_proxy.",
+    );
+  }
+
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error("The proxy environment contains an invalid URL.");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error("Browser proxy URLs must use http:// or https://.");
+  }
+  if (!url.hostname || !url.port || url.pathname !== "/" || url.search || url.hash) {
+    throw new Error(
+      "Browser proxy URLs must contain only scheme, host, port, and optional credentials.",
+    );
+  }
+  if ((url.username && !url.password) || (!url.username && url.password)) {
+    throw new Error("Browser proxy URLs must provide both username and password, or neither.");
+  }
+
+  const proxy: BrowserProxy = { server: `${url.protocol}//${url.host}` };
+  if (url.username) {
+    proxy.username = decodeURIComponent(url.username);
+    proxy.password = decodeURIComponent(url.password);
+  }
+  return proxy;
+}
+
+/**
+ * Read the optional fixed-egress gate injected by an embedding host wrapper.
+ * Both fields are required together so a partial contract
+ * fails before Chromium visits the requested target.
+ */
+export function browserProxyGateFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): BrowserProxyGate | null {
+  const expectedIp = env.HARNERY_BROWSER_PROXY_EXPECTED_IP?.trim();
+  const checkUrl = env.HARNERY_BROWSER_PROXY_CHECK_URL?.trim();
+  if (!expectedIp && !checkUrl) return null;
+  if (!expectedIp || !checkUrl) {
+    throw new Error(
+      "HARNERY_BROWSER_PROXY_EXPECTED_IP and HARNERY_BROWSER_PROXY_CHECK_URL must be set together.",
+    );
+  }
+  if (!/^(?:\d{1,3}\.){3}\d{1,3}$/.test(expectedIp)) {
+    throw new Error("HARNERY_BROWSER_PROXY_EXPECTED_IP must be an IPv4 address.");
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(checkUrl);
+  } catch {
+    throw new Error("HARNERY_BROWSER_PROXY_CHECK_URL must be a valid HTTPS URL.");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error("HARNERY_BROWSER_PROXY_CHECK_URL must use HTTPS.");
+  }
+  return { expectedIp, checkUrl: parsed.toString() };
+}
+
+export function extractObservedIp(body: string): string | null {
+  try {
+    const parsed = JSON.parse(body) as Record<string, unknown>;
+    for (const key of ["ip", "query", "origin"]) {
+      const value = parsed[key];
+      if (typeof value === "string" && value.trim()) return value.trim().split(",")[0].trim();
+    }
+    const proxy = parsed.proxy;
+    if (proxy && typeof proxy === "object") {
+      const value = (proxy as Record<string, unknown>).ip;
+      if (typeof value === "string" && value.trim()) return value.trim();
+    }
+  } catch {
+    // A plain-text IP endpoint is also valid.
+  }
+  const trimmed = body.trim();
+  return /^(?:\d{1,3}\.){3}\d{1,3}$/.test(trimmed) ? trimmed : null;
+}
+
+export const WEBRTC_PROXY_ONLY_ARG = "--force-webrtc-ip-handling-policy=disable_non_proxied_udp";

package/src/lib/browser/runts.ts

@@ -31,6 +31,12 @@ export interface RuntHit {
 }
 
 export interface RuntsResult {
+  /** Requested selector scope, or null for the document body. */
+  scope: string | null;
+  /** False when a requested selector matched nothing. */
+  found: boolean;
+  /** Unknown means the sweep hit a safety cap before proving the page clean. */
+  outcome: "pass" | "fail" | "unknown";
   /** Text blocks scanned (post length/inline-children filters). */
   scannedBlocks: number;
   /** True when the block sweep hit the internal cap (very large page). */
@@ -71,7 +77,16 @@ export function buildRuntsCheck(): (args: {
     const RUNT_CAP = 50;
 
     const root = scope ? document.querySelector(scope) : document.body;
-    if (!root) return { scannedBlocks: 0, truncated: false, runts: [] };
+    if (!root) {
+      return {
+        scope,
+        found: false,
+        outcome: "fail",
+        scannedBlocks: 0,
+        truncated: false,
+        runts: [],
+      };
+    }
 
     const sx = window.scrollX;
     const sy = window.scrollY;
@@ -84,7 +99,9 @@ export function buildRuntsCheck(): (args: {
       return tag;
     };
 
-    const all = root.querySelectorAll("*");
+    // Include the scope itself. A caller commonly points directly at a <p>,
+    // caption, or blurb; querySelectorAll("*") would otherwise scan nothing.
+    const all = [root, ...root.querySelectorAll("*")];
     const runts: RuntHit[] = [];
     let scanned = 0;
     let truncated = false;
@@ -158,7 +175,14 @@ export function buildRuntsCheck(): (args: {
       }
     }
 
-    return { scannedBlocks: scanned, truncated, runts };
+    return {
+      scope,
+      found: true,
+      outcome: runts.length > 0 ? "fail" : truncated ? "unknown" : "pass",
+      scannedBlocks: scanned,
+      truncated,
+      runts,
+    };
   };
 }