@jitsusama/agentic-harness.core 0.1.0

package/dist/web/compare/images.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Comparing two screenshots.
+ *
+ * The comparison itself is pixelmatch, which already handles the
+ * thing that makes naive diffing useless: antialiasing. Two
+ * renders of identical markup differ along every curved edge,
+ * and a tool that reports those has told you nothing while
+ * looking thorough.
+ *
+ * What is added here is the refusal to compare images of
+ * different sizes. Padding or cropping one to fit would produce
+ * a number, and the number would be a lie: everything below the
+ * join would read as changed. A page that got taller is a real
+ * result and deserves saying so.
+ */
+import { PNG } from "pngjs";
+import { type Comparison, type Placed } from "./regions.js";
+/**
+ * How different a pixel must be to count.
+ *
+ * pixelmatch's own scale, where zero matches exactly. This is a
+ * presentational choice: it decides what counts as a change, not
+ * what one is.
+ */
+export declare const MATCH_THRESHOLD = 0.1;
+/** Read a PNG from bytes. */
+export declare function readPng(bytes: Buffer): PNG;
+/** What a diff produced, including the image of itself. */
+export interface DiffResult {
+    readonly comparison: Comparison;
+    /** The diff image, when there was anything to draw. */
+    readonly image?: Buffer;
+}
+/**
+ * Compare two images and locate what changed.
+ *
+ * The diff image is only produced when something differs, since
+ * writing an empty overlay to disk for an unchanged page is a
+ * file somebody has to open to learn nothing.
+ */
+export declare function compareImages(baseline: PNG, current: PNG, elements?: readonly Placed[], options?: {
+    readonly threshold?: number;
+    readonly cell?: number;
+    readonly scale?: number;
+}): DiffResult;

package/dist/web/compare/images.js

@@ -0,0 +1,101 @@
+/**
+ * Comparing two screenshots.
+ *
+ * The comparison itself is pixelmatch, which already handles the
+ * thing that makes naive diffing useless: antialiasing. Two
+ * renders of identical markup differ along every curved edge,
+ * and a tool that reports those has told you nothing while
+ * looking thorough.
+ *
+ * What is added here is the refusal to compare images of
+ * different sizes. Padding or cropping one to fit would produce
+ * a number, and the number would be a lie: everything below the
+ * join would read as changed. A page that got taller is a real
+ * result and deserves saying so.
+ */
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+import { attributeRegions, clusterRegions, } from "./regions.js";
+/**
+ * How different a pixel must be to count.
+ *
+ * pixelmatch's own scale, where zero matches exactly. This is a
+ * presentational choice: it decides what counts as a change, not
+ * what one is.
+ */
+export const MATCH_THRESHOLD = 0.1;
+/** Read a PNG from bytes. */
+export function readPng(bytes) {
+    return PNG.sync.read(bytes);
+}
+/**
+ * Compare two images and locate what changed.
+ *
+ * The diff image is only produced when something differs, since
+ * writing an empty overlay to disk for an unchanged page is a
+ * file somebody has to open to learn nothing.
+ */
+export function compareImages(baseline, current, elements = [], options = {}) {
+    if (baseline.width !== current.width || baseline.height !== current.height) {
+        return {
+            comparison: {
+                kind: "incomparable",
+                because: `the baseline is ${baseline.width} by ${baseline.height} and ` +
+                    `this one is ${current.width} by ${current.height}. A page ` +
+                    "that changed size is a result in itself, so neither was " +
+                    "cropped to fit.",
+            },
+        };
+    }
+    const { width, height } = baseline;
+    const diff = new PNG({ width, height });
+    const changedPixels = pixelmatch(baseline.data, current.data, diff.data, width, height, { threshold: options.threshold ?? MATCH_THRESHOLD });
+    if (changedPixels === 0) {
+        return {
+            comparison: {
+                kind: "compared",
+                width,
+                height,
+                changedPixels: 0,
+                fraction: 0,
+                regions: [],
+            },
+        };
+    }
+    // pixelmatch paints differing pixels red into the diff image,
+    // so the mask is read back out of what it drew rather than
+    // diffing a second time.
+    const changed = new Uint8Array(width * height);
+    for (let index = 0; index < changed.length; index += 1) {
+        const at = index * 4;
+        changed[index] =
+            diff.data[at] === 255 && (diff.data[at + 1] ?? 0) < 128 ? 1 : 0;
+    }
+    // A screenshot taken at device pixel ratio two is twice the
+    // size of the layout the elements were measured in, so region
+    // coordinates are brought back to CSS pixels before anything
+    // is attributed to an element.
+    const scale = options.scale ?? 1;
+    const regions = clusterRegions(changed, width, height, {
+        ...(options.cell === undefined ? {} : { cell: options.cell }),
+    }).map((region) => scale === 1
+        ? region
+        : {
+            ...region,
+            x: Math.round(region.x / scale),
+            y: Math.round(region.y / scale),
+            width: Math.round(region.width / scale),
+            height: Math.round(region.height / scale),
+        });
+    return {
+        comparison: {
+            kind: "compared",
+            width,
+            height,
+            changedPixels,
+            fraction: changedPixels / (width * height),
+            regions: attributeRegions(regions, elements),
+        },
+        image: PNG.sync.write(diff),
+    };
+}

package/dist/web/compare/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Comparing a page against a baseline of itself.
+ *
+ * Only the region logic is exported here, and that is the point:
+ * it is pure, it works on any change mask whatever produced one,
+ * and importing it must not drag in a PNG decoder. Somebody
+ * clustering a diff they already have should not pay for
+ * pixelmatch and pngjs to do it.
+ *
+ * The image half lives in ./images.js and is imported directly
+ * by the session, which is already holding a browser open and
+ * has no purity left to protect.
+ */
+export { type BaselineProvenance, describeDrift, parse, sidecarFor, stringify, } from "./provenance.js";
+export { type AttributedRegion, attributeRegions, CELL_SIZE, type Comparison, clusterRegions, IGNORABLE_FRACTION, MIN_REGION_PIXELS, type Placed, type Region, renderComparison, } from "./regions.js";

package/dist/web/compare/index.js

@@ -0,0 +1,15 @@
+/**
+ * Comparing a page against a baseline of itself.
+ *
+ * Only the region logic is exported here, and that is the point:
+ * it is pure, it works on any change mask whatever produced one,
+ * and importing it must not drag in a PNG decoder. Somebody
+ * clustering a diff they already have should not pay for
+ * pixelmatch and pngjs to do it.
+ *
+ * The image half lives in ./images.js and is imported directly
+ * by the session, which is already holding a browser open and
+ * has no purity left to protect.
+ */
+export { describeDrift, parse, sidecarFor, stringify, } from "./provenance.js";
+export { attributeRegions, CELL_SIZE, clusterRegions, IGNORABLE_FRACTION, MIN_REGION_PIXELS, renderComparison, } from "./regions.js";

package/dist/web/compare/provenance.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a visual baseline was recorded under, and whether a later
+ * capture is comparable to it.
+ *
+ * A baseline is a claim about one page under one set of
+ * conditions. Without recording those conditions a comparison
+ * cannot tell a regression from a change of subject: record on
+ * the cart page, navigate to the checkout page, compare, and the
+ * diff reports confident failures attributed to the checkout
+ * page's elements. Image size alone cannot catch it, because two
+ * pages at the same viewport are the same size.
+ *
+ * Pure: the session captures the facts, this decides what they
+ * mean, and a capture from anywhere else works the same way.
+ */
+/** The conditions a baseline image was taken under. */
+export interface BaselineProvenance {
+    /** The page the shot was of. */
+    readonly url: string;
+    /** Emulated viewport width, when one was set. */
+    readonly width?: number;
+    /** Emulated viewport height, when one was set. */
+    readonly height?: number;
+    /** Device pixel ratio the shot was rasterized at. */
+    readonly deviceScaleFactor: number;
+}
+/** Where the provenance for a baseline image lives. */
+export declare function sidecarFor(baselinePath: string): string;
+/** Serialize provenance for storage beside its image. */
+export declare function stringify(provenance: BaselineProvenance): string;
+/**
+ * Read provenance back, or undefined when there is none to read.
+ *
+ * Undefined is a real answer rather than a failure: baselines
+ * recorded before provenance existed have no sidecar, and
+ * discarding them would turn an upgrade into silent data loss.
+ */
+export declare function parse(text: string): BaselineProvenance | undefined;
+/**
+ * Say how a capture differs from the baseline's conditions, or
+ * undefined when the two are comparable.
+ *
+ * The message names both sides, because the useful next step
+ * differs completely depending on which one is wrong: a changed
+ * URL means the wrong baseline was named, and a changed viewport
+ * means the emulation drifted.
+ */
+export declare function describeDrift(was: BaselineProvenance, now: BaselineProvenance): string | undefined;

package/dist/web/compare/provenance.js

@@ -0,0 +1,86 @@
+/**
+ * What a visual baseline was recorded under, and whether a later
+ * capture is comparable to it.
+ *
+ * A baseline is a claim about one page under one set of
+ * conditions. Without recording those conditions a comparison
+ * cannot tell a regression from a change of subject: record on
+ * the cart page, navigate to the checkout page, compare, and the
+ * diff reports confident failures attributed to the checkout
+ * page's elements. Image size alone cannot catch it, because two
+ * pages at the same viewport are the same size.
+ *
+ * Pure: the session captures the facts, this decides what they
+ * mean, and a capture from anywhere else works the same way.
+ */
+/** Where the provenance for a baseline image lives. */
+export function sidecarFor(baselinePath) {
+    return `${baselinePath}.json`;
+}
+/** Serialize provenance for storage beside its image. */
+export function stringify(provenance) {
+    return `${JSON.stringify(provenance, null, "\t")}\n`;
+}
+/**
+ * Read provenance back, or undefined when there is none to read.
+ *
+ * Undefined is a real answer rather than a failure: baselines
+ * recorded before provenance existed have no sidecar, and
+ * discarding them would turn an upgrade into silent data loss.
+ */
+export function parse(text) {
+    try {
+        const raw = JSON.parse(text);
+        if (typeof raw !== "object" || raw === null)
+            return undefined;
+        const record = raw;
+        if (typeof record.url !== "string")
+            return undefined;
+        if (typeof record.deviceScaleFactor !== "number")
+            return undefined;
+        return {
+            url: record.url,
+            ...(typeof record.width === "number" ? { width: record.width } : {}),
+            ...(typeof record.height === "number" ? { height: record.height } : {}),
+            deviceScaleFactor: record.deviceScaleFactor,
+        };
+    }
+    catch {
+        // A truncated or hand-edited sidecar is not worth failing a
+        // comparison over. Treating it as absent falls back to the
+        // behaviour baselines had before provenance was recorded.
+        return undefined;
+    }
+}
+/** A viewport as it reads in a refusal. */
+function viewportOf(provenance) {
+    const { width, height } = provenance;
+    if (width === undefined && height === undefined)
+        return "no set viewport";
+    return `${width ?? "auto"}x${height ?? "auto"}`;
+}
+/**
+ * Say how a capture differs from the baseline's conditions, or
+ * undefined when the two are comparable.
+ *
+ * The message names both sides, because the useful next step
+ * differs completely depending on which one is wrong: a changed
+ * URL means the wrong baseline was named, and a changed viewport
+ * means the emulation drifted.
+ */
+export function describeDrift(was, now) {
+    if (was.url !== now.url) {
+        return (`the baseline was recorded on ${was.url} and this is ` +
+            `${now.url}. Comparing two different pages would report ` +
+            "every difference between them as a regression.");
+    }
+    if (was.width !== now.width || was.height !== now.height) {
+        return (`the baseline was recorded at ${viewportOf(was)} and this is ` +
+            `${viewportOf(now)}. Re-record it, or set the viewport back.`);
+    }
+    if (was.deviceScaleFactor !== now.deviceScaleFactor) {
+        return (`the baseline was rasterized at ${was.deviceScaleFactor}x and ` +
+            `this is ${now.deviceScaleFactor}x. Every edge would differ.`);
+    }
+    return undefined;
+}

package/dist/web/compare/regions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Turning a field of changed pixels into places that changed.
+ *
+ * A pixel count is nearly useless on its own. Two hundred
+ * thousand differing pixels might be the whole page shifted by
+ * one row, or one image swapped, and those need opposite
+ * responses. What a person wants is where, and how many
+ * separate wheres there are.
+ *
+ * Regions are built on a coarse grid rather than by exact
+ * connected pixels, deliberately. Pixel-exact blobs split a
+ * single moved paragraph into one region per glyph; a grid of a
+ * few pixels joins them into the thing that actually moved.
+ */
+/** A changed area of the image, in pixels. */
+export interface Region {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    /** How many pixels inside it actually differ. */
+    readonly pixels: number;
+}
+/** How wide a grid cell is when grouping changes. */
+export declare const CELL_SIZE = 8;
+/** Regions smaller than this are noise, not a change. */
+export declare const MIN_REGION_PIXELS = 4;
+/**
+ * Group changed pixels into rectangles.
+ *
+ * `changed` is one entry per pixel, row-major, truthy where the
+ * two images differ. That shape is what an image diff produces
+ * and costs nothing to build from one.
+ */
+export declare function clusterRegions(changed: ArrayLike<number> | readonly boolean[], width: number, height: number, options?: {
+    readonly cell?: number;
+    readonly minPixels?: number;
+}): readonly Region[];
+/** An element, for saying what a changed region sits on. */
+export interface Placed {
+    readonly selector: string;
+    readonly rect: {
+        readonly x: number;
+        readonly y: number;
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/** A region with the element it most likely belongs to. */
+export interface AttributedRegion extends Region {
+    readonly selector?: string;
+}
+/**
+ * Say what each changed region sits on.
+ *
+ * The smallest element that fully contains the region wins,
+ * since every region is inside the body and saying so helps
+ * nobody. A region spanning two elements is left unattributed
+ * rather than blamed on their common ancestor: "something under
+ * main changed" is not an answer.
+ */
+export declare function attributeRegions(regions: readonly Region[], elements: readonly Placed[]): readonly AttributedRegion[];
+/** What a comparison concluded. */
+export type Comparison = {
+    readonly kind: "compared";
+    readonly width: number;
+    readonly height: number;
+    readonly changedPixels: number;
+    readonly fraction: number;
+    readonly regions: readonly AttributedRegion[];
+} | {
+    readonly kind: "incomparable";
+    readonly because: string;
+};
+/** Below this share of the image, a change is worth ignoring. */
+export declare const IGNORABLE_FRACTION = 0.0001;
+/** Say what changed, and where. */
+export declare function renderComparison(comparison: Comparison, artifacts?: readonly string[]): string;

package/dist/web/compare/regions.js

@@ -0,0 +1,211 @@
+/**
+ * Turning a field of changed pixels into places that changed.
+ *
+ * A pixel count is nearly useless on its own. Two hundred
+ * thousand differing pixels might be the whole page shifted by
+ * one row, or one image swapped, and those need opposite
+ * responses. What a person wants is where, and how many
+ * separate wheres there are.
+ *
+ * Regions are built on a coarse grid rather than by exact
+ * connected pixels, deliberately. Pixel-exact blobs split a
+ * single moved paragraph into one region per glyph; a grid of a
+ * few pixels joins them into the thing that actually moved.
+ */
+import { renderVerdict } from "../audit/verdict.js";
+/** How wide a grid cell is when grouping changes. */
+export const CELL_SIZE = 8;
+/** Regions smaller than this are noise, not a change. */
+export const MIN_REGION_PIXELS = 4;
+/**
+ * Group changed pixels into rectangles.
+ *
+ * `changed` is one entry per pixel, row-major, truthy where the
+ * two images differ. That shape is what an image diff produces
+ * and costs nothing to build from one.
+ */
+export function clusterRegions(changed, width, height, options = {}) {
+    const cell = options.cell ?? CELL_SIZE;
+    const minPixels = options.minPixels ?? MIN_REGION_PIXELS;
+    if (width <= 0 || height <= 0)
+        return [];
+    const across = Math.ceil(width / cell);
+    const down = Math.ceil(height / cell);
+    // One count per cell, so a region knows how much of it moved,
+    // and the true extent of the changed pixels inside it. The
+    // grid decides what groups together; it must not decide the
+    // bounds, or a region snapped out to cell edges stops fitting
+    // inside the element it belongs to and gets blamed on the body.
+    const counts = new Int32Array(across * down);
+    const leftOf = new Int32Array(across * down).fill(width);
+    const topOf = new Int32Array(across * down).fill(height);
+    const rightOf = new Int32Array(across * down).fill(-1);
+    const bottomOf = new Int32Array(across * down).fill(-1);
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            if (!changed[y * width + x])
+                continue;
+            const at = Math.floor(y / cell) * across + Math.floor(x / cell);
+            counts[at] += 1;
+            if (x < (leftOf[at] ?? width))
+                leftOf[at] = x;
+            if (y < (topOf[at] ?? height))
+                topOf[at] = y;
+            if (x > (rightOf[at] ?? -1))
+                rightOf[at] = x;
+            if (y > (bottomOf[at] ?? -1))
+                bottomOf[at] = y;
+        }
+    }
+    const seen = new Uint8Array(across * down);
+    const regions = [];
+    for (let index = 0; index < counts.length; index += 1) {
+        if (seen[index] || (counts[index] ?? 0) === 0)
+            continue;
+        // Flood fill across touching cells, diagonals included, so a
+        // change running at an angle stays one region.
+        const stack = [index];
+        seen[index] = 1;
+        let minX = width;
+        let minY = height;
+        let maxX = -1;
+        let maxY = -1;
+        let pixels = 0;
+        while (stack.length > 0) {
+            const at = stack.pop();
+            if (at === undefined)
+                continue;
+            const cellX = at % across;
+            const cellY = Math.floor(at / across);
+            pixels += counts[at] ?? 0;
+            minX = Math.min(minX, leftOf[at] ?? width);
+            minY = Math.min(minY, topOf[at] ?? height);
+            maxX = Math.max(maxX, rightOf[at] ?? -1);
+            maxY = Math.max(maxY, bottomOf[at] ?? -1);
+            for (let dy = -1; dy <= 1; dy += 1) {
+                for (let dx = -1; dx <= 1; dx += 1) {
+                    const nx = cellX + dx;
+                    const ny = cellY + dy;
+                    if (nx < 0 || ny < 0 || nx >= across || ny >= down)
+                        continue;
+                    const next = ny * across + nx;
+                    if (seen[next] || (counts[next] ?? 0) === 0)
+                        continue;
+                    seen[next] = 1;
+                    stack.push(next);
+                }
+            }
+        }
+        if (pixels < minPixels)
+            continue;
+        regions.push({
+            x: minX,
+            y: minY,
+            width: maxX - minX + 1,
+            height: maxY - minY + 1,
+            pixels,
+        });
+    }
+    // Biggest change first: it is the one most likely to matter.
+    return regions.sort((a, b) => b.pixels - a.pixels);
+}
+/**
+ * Whether an element covers a changed region.
+ *
+ * The element's box is rounded outward to the pixels it can
+ * paint into before comparing. A rect is fractional and a
+ * region is whole pixels, so an element starting at y=442.5
+ * paints row 442, and comparing the two raw numbers rejected it
+ * by half a pixel. Every change then fell through to the body,
+ * which is an answer that helps nobody.
+ */
+function contains(outer, region) {
+    return (region.x >= Math.floor(outer.x) &&
+        region.y >= Math.floor(outer.y) &&
+        region.x + region.width <= Math.ceil(outer.x + outer.width) &&
+        region.y + region.height <= Math.ceil(outer.y + outer.height));
+}
+function area(rect) {
+    return rect.width * rect.height;
+}
+/**
+ * Say what each changed region sits on.
+ *
+ * The smallest element that fully contains the region wins,
+ * since every region is inside the body and saying so helps
+ * nobody. A region spanning two elements is left unattributed
+ * rather than blamed on their common ancestor: "something under
+ * main changed" is not an answer.
+ */
+export function attributeRegions(regions, elements) {
+    return regions.map((region) => {
+        let best;
+        for (const element of elements) {
+            if (!contains(element.rect, region))
+                continue;
+            if (best === undefined || area(element.rect) < area(best.rect)) {
+                best = element;
+            }
+        }
+        return best === undefined ? region : { ...region, selector: best.selector };
+    });
+}
+/** Below this share of the image, a change is worth ignoring. */
+export const IGNORABLE_FRACTION = 0.0001;
+/** How many regions to name before counting the rest. */
+const MAX_NAMED_REGIONS = 8;
+/** Say what changed, and where. */
+export function renderComparison(comparison, artifacts = []) {
+    if (comparison.kind === "incomparable") {
+        return renderVerdict({
+            standing: "warn",
+            headline: "The two images cannot be compared.",
+            measured: comparison.because,
+        }, "");
+    }
+    const { changedPixels, fraction, regions, width, height } = comparison;
+    if (changedPixels === 0) {
+        return renderVerdict({
+            standing: "pass",
+            headline: "Identical to the baseline.",
+            measured: `Compared every pixel of ${width} by ${height}.`,
+        }, "");
+    }
+    const percent = (fraction * 100).toFixed(fraction < 0.001 ? 4 : 2);
+    const noise = fraction < IGNORABLE_FRACTION;
+    const lines = [];
+    for (const region of regions.slice(0, MAX_NAMED_REGIONS)) {
+        const where = region.selector ? `  ${region.selector}` : "";
+        lines.push(`  ${region.width} by ${region.height} at ` +
+            `(${region.x}, ${region.y}), ${region.pixels} pixels${where}`);
+    }
+    if (regions.length > MAX_NAMED_REGIONS) {
+        lines.push(`  ... and ${regions.length - MAX_NAMED_REGIONS} more regions`);
+    }
+    if (artifacts.length > 0) {
+        lines.push("", ...artifacts);
+    }
+    return renderVerdict({
+        // A change too small to see is worth a warning rather than
+        // a failure: it is usually the renderer, not the page.
+        standing: noise ? "warn" : "fail",
+        headline: regions.length === 0
+            ? // Clustering drops anything under a few pixels, while
+                // the changed count keeps them, so a change scattered
+                // thinly across the image used to render a failure
+                // headline over an empty body: nowhere to look and
+                // nothing to do.
+                `${changedPixels} pixels differ, ${percent} percent of ` +
+                    "the image, too scattered to gather into a region."
+            : `${changedPixels} pixels differ, ${percent} percent of the ` +
+                `image, across ${regions.length} ` +
+                `${regions.length === 1 ? "region" : "separate regions"}.`,
+        measured: noise
+            ? "That is small enough to be rendering noise rather than a change."
+            : regions.length === 0
+                ? `Compared every pixel of ${width} by ${height}. Look at ` +
+                    "the diff image below; single-pixel differences spread " +
+                    "over an image are usually a font or antialiasing change."
+                : `Compared every pixel of ${width} by ${height}.`,
+    }, lines.join("\n"));
+}

package/dist/web/cookies/extract.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cookie extraction: reads encrypted cookies from the local
+ * Chrome profile, decrypts them, and returns puppeteer-compatible
+ * cookie objects.
+ *
+ * Handles __Host- prefix cookies and correct domain matching
+ * per RFC 6265.
+ */
+/** Cookie in puppeteer-compatible format. */
+export interface PuppeteerCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path: string;
+    expires: number;
+    httpOnly: boolean;
+    secure: boolean;
+    sameSite?: "Strict" | "Lax" | "None";
+}
+/**
+ * Read Chrome cookies for a URL, decrypt them, and return in
+ * puppeteer-compatible format. Returns an empty array if the key
+ * hasn't been set up, the profile can't be found, or decryption
+ * fails.
+ */
+export declare function getCookiesForUrl(url: string): Promise<PuppeteerCookie[]>;