harnery 0.31.5 → 0.32.0

package/dist/lib/browser/geometry.js

@@ -32,8 +32,12 @@ export function intersectRects(a, b) {
  */
 export function buildLayoutLintCheck() {
     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) => ({
             x: rect.x,
             y: rect.y,
@@ -65,6 +69,14 @@ export function buildLayoutLintCheck() {
         const isHidden = (element) => {
             let current = 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 = current.parentElement;
+                if (parent instanceof HTMLDetailsElement && !parent.open && current.tagName !== "SUMMARY") {
+                    return true;
+                }
                 const style = getComputedStyle(current);
                 const contentVisibility = style
                     .contentVisibility;
@@ -300,6 +312,27 @@ export function buildLayoutLintCheck() {
             const clips = new Set(["hidden", "clip", "auto", "scroll"]);
             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) => {
+            const style = getComputedStyle(element);
+            const scrolls = new Set(["auto", "scroll"]);
+            return { x: scrolls.has(style.overflowX), y: scrolls.has(style.overflowY) };
+        };
+        const unbounded = () => ({
+            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) => {
             const rect = element.getBoundingClientRect();
             const html = element;
@@ -319,8 +352,8 @@ export function buildLayoutLintCheck() {
             };
         };
         const clip = request.clip.map(({ selector, tolerancePx }) => {
-            const container = document.querySelector(selector);
-            if (!(container instanceof Element)) {
+            const containers = [...document.querySelectorAll(selector)];
+            if (containers.length === 0) {
                 return {
                     rule: "clip",
                     selector,
@@ -336,31 +369,47 @@ export function buildLayoutLintCheck() {
             const unsupported = new Set();
             const excluded = [];
             const issues = [];
-            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, allowed, clippedBy, axes = { x: true, y: true }) => {
+                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.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, container, seed, seedLabel) => {
+                let allowed = { ...seed };
+                let clippedBy = seedLabel;
+                const free = { x: false, y: false };
+                let current = 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 = {
@@ -377,28 +426,122 @@ export function buildLayoutLintCheck() {
                         allowed.height = Math.max(0, allowed.bottom - allowed.top);
                         clippedBy = labelOf(current);
                     }
-                    if (current === container)
+                    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, scope) => {
+                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 = 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 = issues.length > 0 ? "fail" : unsupported.size > 0 ? "unknown" : "pass";
             return {
                 rule: "clip",

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

@@ -1,12 +1,16 @@
 export { type AssertOp, type AssertResult, type AssertSpec, buildAssertCheck, parseAssertSpec, } from "./asserts.js";
-export { Browser, type BrowserOptions, type ConsoleEvent, type Diagnostics, type FailedRequest, type NavigateResult, type PageErrorEvent, } from "./client.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 { 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 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, TargetSizeProfile, TargetSizeResult, } from "./target-size.js";
 export type { CheckVisibilityOptions, VisibilityResult, VisibilitySample, } from "./visibility.js";
 //# sourceMappingURL=index.d.ts.map

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,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,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,YAAY,EACV,eAAe,EACf,cAAc,EACd,WAAW,GACZ,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,OAAO,EACP,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,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":"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,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,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/lib/browser/index.js

@@ -1,5 +1,9 @@
 export { buildAssertCheck, parseAssertSpec, } from "./asserts.js";
-export { Browser, } from "./client.js";
+export { Browser, BrowserSessionActionError, } from "./client.js";
 export { bandRects, DEFAULT_CRITIQUE_RUBRIC, normalizeFindings, runCritique, tilesFromFullPage, } from "./critique.js";
 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 { browserProxyFromEnv, browserProxyGateFromEnv, extractObservedIp, WEBRTC_PROXY_ONLY_ARG, } from "./proxy.js";
+export { BROWSER_SESSION_MAX_FILL_BYTES, BROWSER_SESSION_MAX_FRAME_BYTES, BROWSER_SESSION_MAX_INSPECTION_TEXT_BYTES, BROWSER_SESSION_PROTOCOL_VERSION, BrowserSessionError, browserSessionTransport, readBrowserSessionDescriptor, sendBrowserSessionRequest, startBrowserSessionServer, } from "./session-control.js";

package/dist/lib/browser/netscape-cookies.d.ts

@@ -0,0 +1,6 @@
+import type { Cookie } from "playwright";
+/** Serialize Playwright cookies in the Netscape cookies.txt format used by yt-dlp. */
+export declare function serializeNetscapeCookies(cookies: readonly Cookie[]): string;
+/** Write a credential-bearing cookie file with owner-only permissions. */
+export declare function writeNetscapeCookieFile(path: string, cookies: readonly Cookie[]): void;
+//# sourceMappingURL=netscape-cookies.d.ts.map

package/dist/lib/browser/netscape-cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"netscape-cookies.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/netscape-cookies.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAMzC,sFAAsF;AACtF,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAsB3E;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAItF"}

package/dist/lib/browser/netscape-cookies.js

@@ -0,0 +1,31 @@
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+function cookieField(value) {
+    return value.replace(/[\t\r\n]/g, "");
+}
+/** Serialize Playwright cookies in the Netscape cookies.txt format used by yt-dlp. */
+export function serializeNetscapeCookies(cookies) {
+    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, cookies) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, serializeNetscapeCookies(cookies), { mode: 0o600 });
+    chmodSync(path, 0o600);
+}

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

@@ -0,0 +1,24 @@
+export interface BrowserProxy {
+    server: string;
+    username?: string;
+    password?: string;
+}
+export interface BrowserProxyGate {
+    checkUrl: string;
+    expectedIp: string;
+}
+/**
+ * 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 declare function browserProxyFromEnv(env?: NodeJS.ProcessEnv): BrowserProxy;
+/**
+ * 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 declare function browserProxyGateFromEnv(env?: NodeJS.ProcessEnv): BrowserProxyGate | null;
+export declare function extractObservedIp(body: string): string | null;
+export declare const WEBRTC_PROXY_ONLY_ARG = "--force-webrtc-ip-handling-policy=disable_non_proxied_udp";
+//# sourceMappingURL=proxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/proxy.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAkCtF;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,gBAAgB,GAAG,IAAI,CAsBzB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB7D;AAED,eAAO,MAAM,qBAAqB,8DAA8D,CAAC"}

package/dist/lib/browser/proxy.js

@@ -0,0 +1,84 @@
+const PROXY_ENV_KEYS = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"];
+/**
+ * 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 = process.env) {
+    const raw = PROXY_ENV_KEYS.map((key) => env[key]).find((value) => 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;
+    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 = { 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 = process.env) {
+    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;
+    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) {
+    try {
+        const parsed = JSON.parse(body);
+        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.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/dist/lib/browser/runts.d.ts

@@ -16,6 +16,12 @@ export interface RuntHit {
     lines: number;
 }
 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). */

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

@@ -1 +1 @@
-{"version":3,"file":"runts.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/runts.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,CAAC,IAAI,EAAE;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAK,WAAW,CAkHhB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,KAAK,IAAI,CAyC/E;AAED,wBAAgB,gCAAgC,IAAI,MAAM,IAAI,CAI7D"}
+{"version":3,"file":"runts.d.ts","sourceRoot":"","sources":["../../../src/lib/browser/runts.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,OAAO;IACtB,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9D,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,CAAC,IAAI,EAAE;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,KAAK,WAAW,CAoIhB;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,KAAK,IAAI,CAyC/E;AAED,wBAAgB,gCAAgC,IAAI,MAAM,IAAI,CAI7D"}

package/dist/lib/browser/runts.js

@@ -45,8 +45,16 @@ export function buildRuntsCheck() {
         const BLOCK_CAP = 5000;
         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;
         const label = (el) => {
@@ -58,7 +66,9 @@ export function buildRuntsCheck() {
                 return `${tag}.${cls.split(/\s+/).slice(0, 2).join(".")}`;
             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 = [];
         let scanned = 0;
         let truncated = false;
@@ -136,7 +146,14 @@ export function buildRuntsCheck() {
                 break;
             }
         }
-        return { scannedBlocks: scanned, truncated, runts };
+        return {
+            scope,
+            found: true,
+            outcome: runts.length > 0 ? "fail" : truncated ? "unknown" : "pass",
+            scannedBlocks: scanned,
+            truncated,
+            runts,
+        };
     };
 }
 /**