@jitsusama/agentic-harness.core 0.1.0

package/dist/web/audit/visual.js

@@ -0,0 +1,297 @@
+/**
+ * Rules about what the layout actually did.
+ *
+ * A visual linter earns its keep or loses it on false positives.
+ * Every rule here reports only where the browser's own numbers
+ * leave no room for argument, and two well-known deliberate
+ * idioms are recognised rather than reported: content parked far
+ * off to the left, and the one-pixel clipped box used to hide
+ * text from sight but not from a screen reader. Flagging those
+ * would train the reader to ignore the whole report.
+ *
+ * Where a judgment is presentational rather than measured, it
+ * says so at the rule. Whether eight pixel text is too small is
+ * an opinion; whether an image failed to load is not.
+ */
+import { HIDDEN_BOX_PX } from "../snapshot/presented.js";
+/**
+ * The viewport WCAG 1.4.10 Reflow is specified at.
+ *
+ * The criterion asks that content reflow at 320 CSS pixels, so a
+ * capture wider than this has not tested it and must not cite
+ * it. A little headroom above 320 keeps a 375px phone capture,
+ * the usual narrow case, inside the claim.
+ */
+export const REFLOW_WIDTH = 400;
+/** Below this, text is hard to read for many people. */
+export const SMALL_TEXT_PX = 10;
+/** How far an image's shape may differ before it looks wrong. */
+export const ASPECT_TOLERANCE = 0.1;
+/**
+ * A box no larger than this is a hiding technique, not content.
+ *
+ * Owned by the page-side module that embeds it into the probes, so
+ * the threshold the browser is measured against and the one this
+ * analysis judges by cannot drift apart. Re-exported here because
+ * this is where consumers have always found it.
+ */
+export { HIDDEN_BOX_PX };
+/** Slack for sub-pixel layout, so rounding is not a finding. */
+const SUBPIXEL = 1;
+/**
+ * Assemble one finding.
+ *
+ * `kind` matters as much as `impact`. A rule that measures a
+ * failure files a violation; a rule that reports a judgment
+ * files needs-review, which counts as a warning rather than a
+ * failure. Everything here used to be a violation, so a rule
+ * whose own help text called itself a judgment and not a WCAG
+ * threshold still failed the check on a single 9px disclaimer.
+ *
+ * A criterion is only ever cited when this module measured the
+ * thing the criterion is about. Asserting one an auditor can
+ * disprove costs more credibility than staying quiet.
+ */
+function make(rule, impact, help, nodes, criteria = [], kind = "violation") {
+    if (nodes.length === 0)
+        return [];
+    return [
+        {
+            rule,
+            kind,
+            impact,
+            authority: criteria.length > 0 ? "wcag" : "best-practice",
+            criteria,
+            levels: criteria.length > 0 ? ["AA"] : [],
+            help,
+            nodes,
+        },
+    ];
+}
+function at(node, message) {
+    return { selector: node.selector, html: "", messages: [message] };
+}
+/**
+ * Whether the author asked for this text to be cut short.
+ *
+ * An ellipsis and a line clamp are promises, not accidents: they
+ * say there is more and the author knows. Their computed
+ * signature (content wider or taller than the box, overflow
+ * hidden) is indistinguishable from a real amputation, so this
+ * is the exception that decides whether the clipping rule is
+ * usable or noise.
+ *
+ * Presentational recognition, like isVisuallyHidden below: the
+ * browser has no notion of a deliberate idiom.
+ */
+function isDeliberatelyTruncated(node) {
+    if (node.textOverflow === "ellipsis")
+        return true;
+    const clamp = node.lineClamp;
+    return clamp !== undefined && clamp !== "none" && clamp !== "";
+}
+/**
+ * Whether an element is using a known way of hiding text from
+ * sight while leaving it to a screen reader.
+ *
+ * This is pattern recognition, not measurement: the browser has
+ * no notion of a visually-hidden idiom. It is here because the
+ * alternative is reporting every correctly built skip link on
+ * every page, which would make the clipping rule worthless.
+ */
+export function isVisuallyHidden(node) {
+    const tiny = node.rect.width <= HIDDEN_BOX_PX && node.rect.height <= HIDDEN_BOX_PX;
+    if (tiny && node.clipPath !== "none")
+        return true;
+    if (tiny && node.overflowX === "hidden")
+        return true;
+    // The older idiom: parked far off to the left, where no
+    // scrollable area is created in a left-to-right page.
+    return node.rect.x + node.rect.width < 0;
+}
+/**
+ * The page scrolls sideways.
+ *
+ * Almost always a mistake, and a serious one on a narrow screen,
+ * where it makes every line of text require two-directional
+ * scrolling to read.
+ */
+export function horizontalOverflow(nodes, viewport) {
+    if (viewport.documentWidth <= viewport.width + SUBPIXEL)
+        return [];
+    const culprits = nodes
+        .filter((node) => !isVisuallyHidden(node))
+        .filter((node) => node.rect.x + node.rect.width > viewport.width + SUBPIXEL)
+        .sort((a, b) => b.rect.x + b.rect.width - (a.rect.x + a.rect.width))
+        .slice(0, 5)
+        .map((node) => at(node, `Reaches ${Math.round(node.rect.x + node.rect.width)} pixels ` +
+        `across, past the ${viewport.width} pixel viewport.`));
+    return make("page-scrolls-sideways", "serious", `The page is ${Math.round(viewport.documentWidth)} pixels wide in a ` +
+        `${viewport.width} pixel viewport, so it scrolls horizontally.`, culprits.length > 0
+        ? culprits
+        : [
+            {
+                selector: "document",
+                html: "",
+                messages: ["Nothing single element accounts for the width."],
+            },
+        ], 
+    // 1.4.10 Reflow is specified at a 320 CSS pixel viewport.
+    // Citing it from a 1280px capture asserts a criterion that
+    // was not tested; horizontal scrolling at a desktop width is
+    // a real problem, just not that one.
+    viewport.width <= REFLOW_WIDTH ? ["1.4.10"] : []);
+}
+/**
+ * Content cut off by the box it sits in.
+ *
+ * Measured, not guessed: the browser reports what the content
+ * wanted and what the box gave it, and a difference with
+ * overflow hidden means the rest is gone with no way to reach
+ * it.
+ */
+export function clippedContent(nodes) {
+    const found = nodes
+        .filter((node) => !isVisuallyHidden(node))
+        .filter((node) => node.text)
+        // Truncation that the author asked for is not lost content:
+        // an ellipsis and a line clamp both say "there is more, and I
+        // know". Their computed signature is identical to a real
+        // amputation, so without excepting them this rule fires on
+        // nearly every table cell, card title and breadcrumb on the
+        // real web, at serious severity with a WCAG citation. A rule
+        // that is red on every page gates nothing.
+        .filter((node) => !isDeliberatelyTruncated(node))
+        .filter((node) => {
+        const cutX = node.scrollWidth > node.clientWidth + SUBPIXEL &&
+            (node.overflowX === "hidden" || node.overflowX === "clip");
+        const cutY = node.scrollHeight > node.clientHeight + SUBPIXEL &&
+            (node.overflowY === "hidden" || node.overflowY === "clip");
+        return cutX || cutY;
+    })
+        .map((node) => {
+        const across = node.scrollWidth - node.clientWidth;
+        const down = node.scrollHeight - node.clientHeight;
+        const how = across > down
+            ? `${Math.round(across)} pixels wider than its box`
+            : `${Math.round(down)} pixels taller than its box`;
+        return at(node, `Content is ${how}, and the rest cannot be reached.`);
+    });
+    return make("content-is-clipped", "serious", "Content is cut off by a box with overflow hidden. Nothing " +
+        "scrolls it into view, so the remainder is simply lost.", found, 
+    // Not 1.4.4, which is about text resized to 200 percent and
+    // is a thing this rule never does. The clipping is real and
+    // worth reporting on its own terms.
+    []);
+}
+/**
+ * Elements that escaped to the right of the document.
+ *
+ * Off to the left is the old way of hiding something, and does
+ * not extend the page. Off to the right does, so it drags the
+ * whole document wider and is nearly always an accident.
+ */
+export function escapedElements(nodes, viewport) {
+    // Say it only when it is true. This rule asserts that an
+    // element drags the page wider, and had no gate on whether the
+    // page actually got wider, while the sibling rule above opens
+    // with exactly that check. So a clipped carousel or an
+    // off-canvas drawer, both of which live beyond the viewport by
+    // design inside a clipping ancestor, were accused of widening
+    // a document this module had already measured as viewport-wide.
+    // The two rules contradicted each other inside one report.
+    if (viewport.documentWidth <= viewport.width + SUBPIXEL)
+        return [];
+    const found = nodes
+        .filter((node) => !isVisuallyHidden(node))
+        .filter((node) => node.rect.width > 0 && node.rect.height > 0)
+        .filter((node) => node.rect.x > viewport.width)
+        .map((node) => at(node, `Sits at x=${Math.round(node.rect.x)}, beyond the ` +
+        `${viewport.width} pixel viewport, dragging the page wider.`));
+    return make("element-escaped-right", "moderate", "An element is positioned past the right of the viewport. Unlike " +
+        "the off-to-the-left idiom, this extends the scrollable page.", found);
+}
+/**
+ * Images that did not load.
+ *
+ * The browser is unambiguous about this: it finished trying and
+ * has no dimensions to show for it.
+ */
+export function brokenImages(nodes) {
+    const found = nodes
+        .filter((node) => node.tag === "img" && node.src)
+        .filter((node) => node.complete === true && node.naturalWidth === 0)
+        .map((node) => at(node, `${node.src} did not load.`));
+    return make("image-loads", "serious", "An image failed to load. The browser finished trying and has no " +
+        "dimensions for it.", found);
+}
+/**
+ * Images drawn at a shape they were not.
+ *
+ * Measured against the image's own dimensions, so this is a
+ * comparison rather than an opinion; only the tolerance is
+ * chosen.
+ */
+export function distortedImages(nodes) {
+    const found = nodes
+        .filter((node) => node.tag === "img")
+        // cover and contain crop or letterbox; they never distort a
+        // pixel, so comparing drawn shape to source shape says
+        // nothing about them. Without this the standard idiom for
+        // every hero, avatar and thumbnail on the web reports as
+        // squashed, at every width of a sweep. Only fill and
+        // scale-down can actually change the shape.
+        .filter((node) => node.objectFit === undefined ||
+        node.objectFit === "fill" ||
+        node.objectFit === "scale-down")
+        .filter((node) => (node.naturalWidth ?? 0) > 0 &&
+        (node.naturalHeight ?? 0) > 0 &&
+        node.rect.width > 0 &&
+        node.rect.height > 0)
+        .flatMap((node) => {
+        const natural = (node.naturalWidth ?? 1) / (node.naturalHeight ?? 1);
+        const drawn = node.rect.width / node.rect.height;
+        const drift = Math.abs(drawn - natural) / natural;
+        if (drift <= ASPECT_TOLERANCE)
+            return [];
+        return [
+            at(node, `Drawn at ${Math.round(node.rect.width)} by ` +
+                `${Math.round(node.rect.height)} from a source that is ` +
+                `${node.naturalWidth} by ${node.naturalHeight}, a ` +
+                `${Math.round(drift * 100)} percent difference in shape.`),
+        ];
+    });
+    return make("image-keeps-its-shape", "moderate", "An image is drawn at a different shape from the file, so it is " +
+        "squashed or stretched.", found);
+}
+/**
+ * Text below a readable size.
+ *
+ * Presentational judgment, and labelled as one. WCAG sets no
+ * minimum font size, because it requires the page to survive
+ * being zoomed instead. This is here because text this small is
+ * usually an accident rather than a decision.
+ */
+export function tinyText(nodes) {
+    const found = nodes
+        .filter((node) => node.text && !isVisuallyHidden(node))
+        .filter((node) => node.fontSizePx > 0 && node.fontSizePx < SMALL_TEXT_PX)
+        .map((node) => at(node, `Set at ${node.fontSizePx} pixels.`));
+    return make("text-is-legible", "minor", `Text below ${SMALL_TEXT_PX} pixels. This is a judgment rather ` +
+        "than a WCAG threshold, which asks instead that the page survive " +
+        "being zoomed.", found, [], 
+    // Says of itself that it is an opinion, so it asks for a
+    // person rather than declaring the page broken.
+    "needs-review");
+}
+/** Every layout rule, run against one capture. */
+export function analyseVisual(nodes, viewport) {
+    return [
+        ...horizontalOverflow(nodes, viewport),
+        ...clippedContent(nodes),
+        ...escapedElements(nodes, viewport),
+        ...brokenImages(nodes),
+        ...distortedImages(nodes),
+        ...tinyText(nodes),
+    ];
+}

package/dist/web/browser.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Browser lifecycle: launch Chrome once, reuse across tool calls.
+ * Pure Chrome management: no cookie knowledge.
+ *
+ * The singleton lives on globalThis rather than in a module
+ * variable. Pi loads each extension as its own module instance,
+ * so a module-level singleton would give web search, mermaid and
+ * the browser tool a browser each, all racing to launch Chrome
+ * against the same per-pid profile; the first wins the profile
+ * lock and the rest fail to launch. A process-global instance,
+ * plus a shared in-flight launch promise, means one browser and
+ * one profile no matter how many extensions reach for it.
+ */
+import { type Browser, type BrowserContext, type Page } from "puppeteer-core";
+/** Diagnostic detail teased out of a failed Chrome launch. */
+export interface LaunchFailureInfo {
+    exitCode?: number;
+    chromeStderr?: string;
+}
+/** Parse a Puppeteer launch error into an exit code and Chrome's stderr. */
+export declare function classifyLaunchError(err: unknown): LaunchFailureInfo;
+/** Build a human-readable message for a launch that never came up. */
+export declare function formatLaunchFailure(info: LaunchFailureInfo, attempts: number, fallback?: string): string;
+/** Thrown when Chrome could not be launched after the retry budget. */
+export declare class BrowserLaunchFailed extends Error {
+    readonly exitCode?: number;
+    readonly chromeStderr?: string;
+    constructor(cause: unknown, attempts: number);
+}
+/** Signal delivery, injectable so the reaping logic is testable. */
+type GroupKill = (pid: number, signal: string) => void;
+/**
+ * Kill a detached Chrome's whole process group, falling back to the
+ * bare pid. Chrome is spawned detached, so its pgid equals its pid;
+ * the negative pid reaps every helper (GPU, network, renderers) that
+ * a lone pid kill would leave to reparent to launchd.
+ */
+export declare function killPidGroup(pid: number, groupKill?: GroupKill): void;
+/** Kill a live browser process tree: group first, then proc.kill fallback. */
+export declare function killTree(proc: {
+    pid?: number;
+    kill: (signal?: NodeJS.Signals) => boolean;
+} | null | undefined, groupKill?: GroupKill): void;
+/** What a process records about the Chrome it owns, written into its profile dir. */
+export interface OwnerRecord {
+    /** Pid of the owning process. */
+    ownerPid: number;
+    /** Pid (and process-group leader) of the Chrome this process launched. */
+    browserPid?: number;
+    /**
+     * The browser-wide DevTools WebSocket URL, when Chrome published one.
+     * A separate process passes this to connectShared() to attach to this
+     * same browser instead of launching its own. Absent when the port
+     * file never appeared or the DevTools HTTP endpoint never answered;
+     * either way the owning process's own pipe-based connection, which
+     * does not depend on this, is unaffected.
+     */
+    browserWSEndpoint?: string;
+}
+/** Inputs for reaping Chrome trees and profile dirs a dead owner left behind. */
+export interface ReapOrphansOptions {
+    root: string;
+    listEntries: () => string[];
+    readOwner: (profileDir: string) => OwnerRecord | undefined;
+    isPidAlive: (pid: number) => boolean;
+    verifyBrowser: (pid: number, profileDir: string) => boolean;
+    /** Pids naming this exact profile, or undefined when the probe failed. */
+    findProcsByProfile: (profileDir: string) => number[] | undefined;
+    killPid: (pid: number) => void;
+    removeDir: (dir: string) => void;
+}
+/**
+ * Reap Chrome trees and profile dirs a prior run left behind. Each
+ * dir is reaped only when its owning process is dead. The candidate kill
+ * set is the exact-profile matches unioned with a recorded pid; each
+ * candidate is re-verified immediately before it is signalled, so a
+ * pid that exited and was reused is never group-killed. The dir is
+ * removed only once discovery has run and a fresh check confirms no
+ * candidate still names it, so a failed probe or a surviving process
+ * keeps the dir for a later sweep. Every step is best-effort: one bad
+ * entry can never abort the sweep or block a launch.
+ */
+export declare function reapOrphans(opts: ReapOrphansOptions): void;
+/** Decide whether an idle browser is truly unused and safe to close. */
+export declare function shouldCloseWhenIdle(openPageCount: number): boolean;
+/**
+ * Decide whether teardown should force-kill the browser process group.
+ * Never after a clean graceful close, since the pid is already gone and
+ * could be reused; only when the close did not happen and the process
+ * still verifies as our Chrome.
+ */
+export declare function shouldForceKill(closedGracefully: boolean, stillVerifies: boolean): boolean;
+/** A countdown that closes an idle browser and rearms on use. */
+export interface IdleCloser {
+    touch(): void;
+    cancel(): void;
+}
+/** Inputs for the idle-close countdown; timers are injectable for tests. */
+export interface IdleCloserOptions {
+    idleMs: number;
+    close: () => void;
+    setTimer?: (fn: () => void, ms: number) => NodeJS.Timeout;
+    clearTimer?: (id: NodeJS.Timeout) => void;
+}
+/** Build an idle-close countdown that rearms on touch and stops on cancel. */
+export declare function createIdleCloser(opts: IdleCloserOptions): IdleCloser;
+/** True when a pid names a live process (EPERM still means it exists). */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * True when `command` carries this exact profile as its
+ * --user-data-dir. Both sides of the value are anchored, so neither a
+ * longer sibling path nor a differently-prefixed flag can collide.
+ */
+export declare function namesProfile(command: string, profileDir: string): boolean;
+/**
+ * Settle on the binary to launch, refusing a configured path that is
+ * not there.
+ *
+ * CHROME_PATH used to be taken on trust, so a stale or mistyped
+ * value fell through to the launch loop: three attempts, two
+ * backoffs, and then a message whose first line blamed a Chrome
+ * auto-update. None of that is true of a path that does not exist,
+ * and no amount of retrying fixes it. A missing Chrome was already
+ * treated as the settled misconfig it is; this is the same fault
+ * arriving by a different door.
+ */
+export declare function resolveChromePath(configured: string | undefined, exists?: (p: string) => boolean): string;
+/**
+ * Attach to a browser a different, still-live process already launched,
+ * instead of spawning one of our own. For a stateless-per-invocation
+ * caller (a CLI, not a long-lived extension host that keeps its own
+ * processGlobal state) that wants to reuse whatever browser is already
+ * warm rather than paying a fresh launch every call.
+ *
+ * Scans every profile under PROFILE_ROOT for a live owner that published
+ * a reconnectable endpoint, and attaches to the first one that answers.
+ * Returns undefined when none is found or reachable, so the caller can
+ * fall back to getBrowser().
+ *
+ * The caller does not own what this returns: closing it must be
+ * `browser.disconnect()`, never `browser.close()`, which would tear down
+ * the browser out from under the process that actually launched it.
+ */
+export declare function connectShared(): Promise<Browser | undefined>;
+/**
+ * Stop the warm browser from being the only reason this process
+ * stays alive.
+ *
+ * The browser is kept between sessions so the next call does not
+ * pay a second and a half to launch Chrome again. But its child
+ * process, its stdio pipes and its DevTools socket all hold the
+ * event loop, so a script that opened a session, did its work
+ * and closed it sat there until the five-minute idle close fired
+ * and only then exited. Measured: two and a half seconds of
+ * work, three hundred and one seconds of wall clock, three and a
+ * half seconds of CPU. Anything wiring this into CI would have
+ * read that as a hang.
+ *
+ * unref does not close anything. The browser stays usable and
+ * the idle close still runs; it just stops counting as a reason
+ * to keep running. A session has its own handles and is
+ * unaffected, and a script exits when its own work is done.
+ */
+export declare function releaseEventLoop(child: LoopHandle | null): void;
+/**
+ * The part of a child process this cares about.
+ *
+ * stdio is left loose because a pipe's declared stream type does
+ * not carry ref and unref even though a socket-backed one has
+ * them, so each entry is asked rather than assumed.
+ */
+export interface LoopHandle {
+    ref(): void;
+    unref(): void;
+    readonly stdio: readonly unknown[];
+}
+/**
+ * Keep the process alive for as long as a teardown needs.
+ *
+ * The inverse of releaseEventLoop. Closing a browser is several
+ * round trips, and once nothing is ref'd Node is free to exit
+ * in the middle of them, which leaves the caller's promise
+ * hanging and Chrome to be reaped as an orphan next run.
+ */
+export declare function holdEventLoop(child: LoopHandle | null): void;
+/**
+ * Get the shared headless Chrome instance, launching it if
+ * needed. Concurrent callers share one in-flight launch, so two
+ * extensions reaching for the browser in the same tick do not
+ * race two Chrome processes onto the same profile.
+ */
+export declare function getBrowser(): Promise<Browser>;
+/** Open a new browser tab with a standard user agent string. */
+export declare function newPage(): Promise<Page>;
+/**
+ * Open a tab in a browser context of its own: separate
+ * cookies, storage and cache from every other context in the
+ * shared Chrome. Two sessions opened this way are two
+ * genuinely independent users. Closing the context closes the
+ * tabs inside it and leaves its siblings alone.
+ */
+export declare function newContextPage(): Promise<{
+    page: Page;
+    context: BrowserContext;
+}>;
+/** Shut down the shared Chrome instance if it's running. */
+export declare function closeBrowser(): Promise<void>;
+/**
+ * Force-kill the Chrome process synchronously. Called from
+ * `process.on('exit')` where async work isn't possible.
+ */
+export declare function killBrowserSync(): void;
+export {};