@jitsusama/agentic-harness.core 0.1.0

package/dist/web/design/inventory.js

@@ -0,0 +1,324 @@
+/**
+ * What a page is actually built from, and where it drifted.
+ *
+ * A design system is a claim about consistency, and a rendered
+ * page is the evidence for or against it. Counting distinct
+ * values is the easy half. The useful half is noticing that four
+ * of the greys differ by one step out of 255, which is not a
+ * palette but an accident that happened four times.
+ *
+ * Nothing here decides whether drift is wrong. Two blues a step
+ * apart may be a bug or may be a hover state, and this cannot
+ * tell which. It reports the cluster and the evidence; the
+ * judgment is a person's.
+ */
+import { count } from "../../ui/count.js";
+import { deltaE } from "../audit/colour.js";
+import { renderVerdict } from "../audit/verdict.js";
+/** How many places to remember per value. */
+const MAX_EXAMPLES = 3;
+/**
+ * Colours closer than this delta E are treated as one intent.
+ *
+ * Delta E rather than contrast ratio. Contrast compares relative
+ * luminance only and is blind to hue, so it called pure red and
+ * a mid grey the same colour: their ratio is about 1.001, well
+ * inside any sameness threshold. That is the right measure for
+ * whether text can be read and the wrong one for whether two
+ * values were meant to be one.
+ *
+ * Around 2 is a just-noticeable difference, so 5 catches the
+ * pairs a person would have to look twice at while leaving a
+ * deliberate step in a palette alone.
+ */
+export const COLOUR_SAMENESS = 5;
+/**
+ * How close two opacities must be to belong to one intent.
+ *
+ * A solid colour and a half-transparent one are a deliberate
+ * pair, and delta E does not see alpha at all.
+ */
+export const ALPHA_SAMENESS = 0.05;
+/**
+ * How close two lengths must be to read as one intent.
+ *
+ * Two thresholds, because one does not work. A purely relative
+ * test is too loose at large values and too strict at small
+ * ones: it clustered 14px with 16px, which is a deliberate step
+ * in any type scale, while leaving 4px and 5px apart, which is
+ * exactly the radius drift worth reporting. An absolute
+ * tolerance handles the small end and a tight relative one
+ * handles the large.
+ */
+export const LENGTH_SAMENESS = 0.08;
+export const LENGTH_TOLERANCE_PX = 1.5;
+/** Count every value of every property across the samples. */
+export function tallyUsage(samples, property) {
+    const counts = new Map();
+    for (const sample of samples) {
+        const raw = sample.values[property];
+        if (raw === undefined || raw === "")
+            continue;
+        const value = canonicalLengths(raw);
+        const entry = counts.get(value) ?? { count: 0, examples: [] };
+        entry.count += 1;
+        if (entry.examples.length < MAX_EXAMPLES)
+            entry.examples.push(sample.selector);
+        counts.set(value, entry);
+    }
+    return [...counts.entries()]
+        .map(([value, entry]) => ({
+        value,
+        count: entry.count,
+        examples: entry.examples,
+    }))
+        .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+}
+/**
+ * Group values that are nearly the same.
+ *
+ * Greedy from the most used value outward, which is what makes
+ * the leader the likely intended one: a value used forty times
+ * with three near neighbours reads as a standard plus three
+ * mistakes, not as four equal options.
+ */
+export function clusterUsage(usages, near) {
+    const remaining = [...usages];
+    const clusters = [];
+    while (remaining.length > 0) {
+        const leader = remaining.shift();
+        if (!leader)
+            break;
+        const nearby = [];
+        for (let index = remaining.length - 1; index >= 0; index -= 1) {
+            const candidate = remaining[index];
+            if (!candidate)
+                continue;
+            if (!near(leader.value, candidate.value))
+                continue;
+            nearby.unshift(candidate);
+            remaining.splice(index, 1);
+        }
+        if (nearby.length === 0)
+            continue;
+        clusters.push({
+            leader,
+            nearby,
+            total: leader.count + nearby.reduce((sum, one) => sum + one.count, 0),
+        });
+    }
+    return clusters;
+}
+/**
+ * Read every colour a value names, for comparison.
+ *
+ * A colour property can be a shorthand: border-color names one
+ * side or four, and the browser serializes them space
+ * separated. Reading only the first turned a one-sided value
+ * and a three-sided one into the same colour.
+ */
+function readColours(css) {
+    const found = [];
+    for (const match of css.matchAll(/rgba?\(([^)]+)\)/g)) {
+        const parts = (match[1] ?? "")
+            .split(/[\s,/]+/)
+            .filter(Boolean)
+            .map(Number);
+        const [r, g, b, a] = parts;
+        if (r === undefined || g === undefined || b === undefined)
+            continue;
+        found.push({ r, g, b, a: a ?? 1 });
+    }
+    return found;
+}
+/** Two colours nobody could tell apart side by side. */
+function oneColourIsNear(a, b) {
+    // Fully transparent is its own thing, not a near-black.
+    if (a.a === 0 || b.a === 0)
+        return a.a === b.a;
+    // Two colours at the same opacity, or near enough. A solid and
+    // a half-transparent version of one colour are a deliberate
+    // pair, not a drift.
+    if (Math.abs((a.a ?? 1) - (b.a ?? 1)) > ALPHA_SAMENESS)
+        return false;
+    return deltaE(a, b) < COLOUR_SAMENESS;
+}
+/** Two colour values nobody could tell apart side by side. */
+export const coloursAreNear = (one, other) => {
+    const a = readColours(one);
+    const b = readColours(other);
+    if (a.length === 0 || b.length === 0)
+        return false;
+    // A different number of sides is a different kind of value,
+    // which is the rule lengths have always followed.
+    if (a.length !== b.length)
+        return false;
+    return a.every((colour, at) => {
+        const against = b[at];
+        return against !== undefined && oneColourIsNear(colour, against);
+    });
+};
+/**
+ * How many decimal places of a pixel anyone could have meant.
+ *
+ * A computed length comes back at the precision the layout engine
+ * happens to hold it at, so the same authored value arrives as
+ * both "24px" and "24.0001px". Treated as two values, they then
+ * cluster, and the report announces design drift between a number
+ * and itself: nobody chose 24.0001px, and being told to reconcile
+ * it is worse than being told nothing.
+ */
+const LENGTH_PRECISION = 2;
+/**
+ * Collapse sub-pixel noise so one authored value stays one value.
+ *
+ * Only the numbers move, and only in their last decimals, so a
+ * real difference of a third of a pixel survives while the layout
+ * engine's rounding does not.
+ */
+export function canonicalLengths(css) {
+    return css.replace(/(-?[\d.]+)px/g, (whole, number) => {
+        const value = Number(number);
+        if (!Number.isFinite(value))
+            return whole;
+        // Number() drops a trailing zero, so 24.10 reads back as 24.1
+        // rather than as a third distinct spelling of the same length.
+        return `${Number(value.toFixed(LENGTH_PRECISION))}px`;
+    });
+}
+/** Every pixel length in a value, in order. */
+function lengths(css) {
+    return [...css.matchAll(/(-?[\d.]+)px/g)].map((found) => Number(found[1]));
+}
+/** Two single lengths close enough to have been meant as one. */
+function oneLengthIsNear(a, b) {
+    if (a === b)
+        return true;
+    // Zero has no neighbours: nothing is nearly nothing.
+    if (a === 0 || b === 0)
+        return false;
+    const apart = Math.abs(a - b);
+    if (apart <= LENGTH_TOLERANCE_PX)
+        return true;
+    return apart / Math.max(Math.abs(a), Math.abs(b)) < LENGTH_SAMENESS;
+}
+/**
+ * Two lengths close enough to have been meant as one.
+ *
+ * Every number is compared, not just the first. A value like a
+ * box shadow or a four-sided padding carries several, and
+ * reading only the first made every shadow whose x offset is
+ * 0px cluster with every other, which is all of them, while
+ * `8px 16px` and `8px 4px` read as the same value.
+ */
+export const lengthsAreNear = (one, other) => {
+    const a = lengths(one);
+    const b = lengths(other);
+    if (a.length === 0 || b.length === 0)
+        return false;
+    // A different number of parts is a different kind of value.
+    if (a.length !== b.length)
+        return false;
+    return a.every((value, at) => oneLengthIsNear(value, b[at] ?? Number.NaN));
+};
+/** Values are the same or they are not. */
+export const exactlyEqual = (one, other) => one === other;
+/** Which properties are worth inventorying, and how they compare. */
+export const DIMENSIONS = [
+    { property: "color", near: coloursAreNear },
+    { property: "background-color", near: coloursAreNear },
+    { property: "border-color", near: coloursAreNear },
+    { property: "font-family", near: exactlyEqual },
+    { property: "font-size", near: lengthsAreNear },
+    { property: "font-weight", near: exactlyEqual },
+    { property: "line-height", near: lengthsAreNear },
+    { property: "padding", near: lengthsAreNear },
+    { property: "margin", near: lengthsAreNear },
+    { property: "border-radius", near: lengthsAreNear },
+    { property: "box-shadow", near: lengthsAreNear },
+];
+/** Take the inventory. */
+export function takeInventory(samples, dimensions = DIMENSIONS) {
+    return dimensions
+        .map(({ property, near }) => {
+        const usages = tallyUsage(samples, property);
+        return {
+            property,
+            distinct: usages.length,
+            usages,
+            clusters: clusterUsage(usages, near),
+        };
+    })
+        .filter((dimension) => dimension.distinct > 0);
+}
+/** How many values to list per property before summarising. */
+const MAX_LISTED = 8;
+/** Say what the page is built from. */
+export function renderInventory(dimensions, options = {}) {
+    if (dimensions.length === 0) {
+        return renderVerdict({ standing: "warn", headline: "Nothing was sampled from this page." }, "");
+    }
+    if (options.property) {
+        const found = dimensions.find((dimension) => dimension.property === options.property);
+        // Like the audit's rule drill-down, this carries a verdict head
+        // so a caller reading the standing gets it from the answer
+        // rather than from the shape of the prose.
+        if (!found) {
+            return renderVerdict({
+                standing: "warn",
+                headline: `Nothing was sampled for '${options.property}'.`,
+                measured: `Sampled: ${dimensions
+                    .map((dimension) => dimension.property)
+                    .join(", ")}.`,
+            }, "");
+        }
+        return renderVerdict({
+            standing: found.clusters.length > 0 ? "warn" : "pass",
+            headline: found.clusters.length > 0
+                ? `${found.property}: ${count(found.clusters.length, "cluster")} ` +
+                    "close enough to look accidental."
+                : `${found.property}: no two values were close enough to ` +
+                    "look accidental.",
+        }, renderDimension(found, Number.POSITIVE_INFINITY));
+    }
+    const drifting = dimensions.filter((dimension) => dimension.clusters.length > 0);
+    const values = dimensions.reduce((sum, dimension) => sum + dimension.distinct, 0);
+    const lines = [];
+    for (const dimension of dimensions) {
+        lines.push(renderDimension(dimension, MAX_LISTED), "");
+    }
+    lines.push("Name a property to see every value and where it is used.");
+    return renderVerdict({
+        // Drift is a question, never a failure. Two blues a step
+        // apart may be a hover state, and this cannot tell.
+        standing: drifting.length === 0 ? "pass" : "warn",
+        headline: drifting.length === 0
+            ? "No two values were close enough to look accidental."
+            : `${drifting.length} of ${dimensions.length} properties hold ` +
+                "values close enough to have been meant as one.",
+        measured: `Sampled ${values} distinct values across ${dimensions.length} properties.`,
+    }, lines.join("\n"));
+}
+function renderDimension(dimension, limit) {
+    const head = `${dimension.property}: ${dimension.distinct} distinct`;
+    const lines = [
+        dimension.clusters.length === 0
+            ? head
+            : `${head}, ${dimension.clusters.length} looking like drift`,
+    ];
+    for (const cluster of dimension.clusters) {
+        lines.push(`  ${cluster.leader.value} (${cluster.leader.count}) sits beside ` +
+            cluster.nearby.map((one) => `${one.value} (${one.count})`).join(", "));
+    }
+    const shown = dimension.usages.slice(0, limit);
+    for (const usage of shown) {
+        const where = limit === Number.POSITIVE_INFINITY
+            ? `  ${usage.examples.join(", ")}`
+            : "";
+        lines.push(`    ${String(usage.count).padStart(4)}  ${usage.value}${where}`);
+    }
+    if (dimension.usages.length > shown.length) {
+        lines.push(`    ... and ${dimension.usages.length - shown.length} more`);
+    }
+    return lines.join("\n");
+}

package/dist/web/design/probe.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Sampling what the page is built from.
+ *
+ * Every value is a resolved computed style, which is the only
+ * honest source: the stylesheet says what was asked for, and the
+ * computed style says what the element got after the cascade,
+ * custom properties, media queries and inheritance all had their
+ * turn. An inventory built from CSS text would describe the
+ * intent rather than the page.
+ *
+ * Inherited values are the one thing filtered out, and for a
+ * reason worth stating: every element inherits a colour, so
+ * sampling all of them makes the body text look like the most
+ * popular decision on the page when nobody decided it at all.
+ */
+export declare const SAMPLED_PROPERTIES: readonly ["color", "background-color", "border-color", "font-family", "font-size", "font-weight", "line-height", "padding", "margin", "border-radius", "box-shadow"];
+/**
+ * Build the expression that samples the page's styles.
+ *
+ * A value is kept only where the element differs from its
+ * parent, which is what turns "every element is 16px" into "one
+ * element chose 14px".
+ */
+export declare function inventorySource(): string;

package/dist/web/design/probe.js

@@ -0,0 +1,88 @@
+/**
+ * Sampling what the page is built from.
+ *
+ * Every value is a resolved computed style, which is the only
+ * honest source: the stylesheet says what was asked for, and the
+ * computed style says what the element got after the cascade,
+ * custom properties, media queries and inheritance all had their
+ * turn. An inventory built from CSS text would describe the
+ * intent rather than the page.
+ *
+ * Inherited values are the one thing filtered out, and for a
+ * reason worth stating: every element inherits a colour, so
+ * sampling all of them makes the body text look like the most
+ * popular decision on the page when nobody decided it at all.
+ */
+/** The properties worth sampling, in the order they are read. */
+import { DEEP_DOM } from "../snapshot/deep.js";
+import { PRESENTED } from "../snapshot/presented.js";
+export const SAMPLED_PROPERTIES = [
+    "color",
+    "background-color",
+    "border-color",
+    "font-family",
+    "font-size",
+    "font-weight",
+    "line-height",
+    "padding",
+    "margin",
+    "border-radius",
+    "box-shadow",
+];
+/**
+ * Build the expression that samples the page's styles.
+ *
+ * A value is kept only where the element differs from its
+ * parent, which is what turns "every element is 16px" into "one
+ * element chose 14px".
+ */
+export function inventorySource() {
+    return `(() => {
+	${DEEP_DOM}
+	${PRESENTED}
+	const PROPERTIES = ${JSON.stringify(SAMPLED_PROPERTIES)};
+
+	const NOTHING = new Set([
+		"none", "normal", "auto", "0px", "rgba(0, 0, 0, 0)", "0px 0px 0px 0px",
+	]);
+
+	const samples = [];
+	for (const el of deepElements(document)) {
+		const tag = el.tagName.toLowerCase();
+		if (tag === "script" || tag === "style" || tag === "head") continue;
+		// An inventory of what the design actually looks like, so it
+		// samples what somebody can actually see: not a closed
+		// dialog's contents, and not a screen-reader-only label whose
+		// colours nobody ever looks at.
+		if (!presented(el)) continue;
+
+		const own = getComputedStyle(el);
+		const parent = el.parentElement ? getComputedStyle(el.parentElement) : null;
+
+		// A border colour with no border is not a decision. Its
+		// initial value is currentColor, so every element reports
+		// one, and sampling them all just echoes the colour list
+		// back under a second heading.
+		const hasBorder =
+			own.borderStyle !== "none" &&
+			parseFloat(own.borderTopWidth) +
+				parseFloat(own.borderRightWidth) +
+				parseFloat(own.borderBottomWidth) +
+				parseFloat(own.borderLeftWidth) >
+				0;
+
+		const values = {};
+		for (const property of PROPERTIES) {
+			if (property === "border-color" && !hasBorder) continue;
+			const value = own.getPropertyValue(property);
+			if (!value || NOTHING.has(value)) continue;
+			// Only what this element decided, not what it was handed.
+			if (parent && parent.getPropertyValue(property) === value) continue;
+			values[property] = value;
+		}
+		if (Object.keys(values).length === 0) continue;
+		samples.push({ selector: deepSelectorFor(el), values });
+	}
+	return samples;
+})()`;
+}

package/dist/web/element/actionable.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Whether an action can land, and what is stopping it.
+ *
+ * A click on an element that is not ready does nothing, and
+ * says nothing, which is the worst failure a driver has: the
+ * caller believes the page was acted on. Judging readiness
+ * first turns that silence into a sentence.
+ */
+import type { Rect } from "./box.js";
+import type { VisibilityVerdict } from "./visibility.js";
+/** What is known about an element's readiness. */
+export interface ActionabilityFacts {
+    readonly present: boolean;
+    readonly visibility?: VisibilityVerdict;
+    readonly enabled: boolean;
+    /** Whether it has stopped moving since the last look. */
+    readonly settled: boolean;
+}
+/** Ready, or the one condition in the way. */
+export interface Actionability {
+    readonly ready: boolean;
+    readonly blocker?: string;
+}
+/**
+ * Judge whether an element can be acted on.
+ *
+ * The order matters for the same reason it does in the
+ * visibility verdict: several conditions can hold at once, and
+ * naming a shallow one sends someone looking at the wrong
+ * thing. A missing element is not usefully also disabled.
+ */
+export declare function judgeActionability(facts: ActionabilityFacts): Actionability;
+/** Whether a box is where it was. */
+export declare function sameBox(before: Rect | undefined, after: Rect | undefined, tolerance?: number): boolean;

package/dist/web/element/actionable.js

@@ -0,0 +1,48 @@
+/**
+ * Whether an action can land, and what is stopping it.
+ *
+ * A click on an element that is not ready does nothing, and
+ * says nothing, which is the worst failure a driver has: the
+ * caller believes the page was acted on. Judging readiness
+ * first turns that silence into a sentence.
+ */
+/**
+ * Judge whether an element can be acted on.
+ *
+ * The order matters for the same reason it does in the
+ * visibility verdict: several conditions can hold at once, and
+ * naming a shallow one sends someone looking at the wrong
+ * thing. A missing element is not usefully also disabled.
+ */
+export function judgeActionability(facts) {
+    if (!facts.present) {
+        return { ready: false, blocker: "it is not in the page" };
+    }
+    if (facts.visibility && facts.visibility.state !== "visible") {
+        // The verdict already explains itself. A second wording of
+        // the same fact is a second thing to keep in agreement.
+        return { ready: false, blocker: facts.visibility.because };
+    }
+    if (!facts.enabled)
+        return { ready: false, blocker: "it is disabled" };
+    if (!facts.settled)
+        return { ready: false, blocker: "it is still moving" };
+    return { ready: true };
+}
+/**
+ * How far a box may drift and still count as still.
+ *
+ * Layout jitter below a pixel is not movement, and treating it
+ * as such would leave an element never settling.
+ */
+const WOBBLE = 0.5;
+/** Whether a box is where it was. */
+export function sameBox(before, after, tolerance = WOBBLE) {
+    // Appearing or vanishing is the largest movement there is.
+    if (!before || !after)
+        return false;
+    return (Math.abs(before.x - after.x) <= tolerance &&
+        Math.abs(before.y - after.y) <= tolerance &&
+        Math.abs(before.width - after.width) <= tolerance &&
+        Math.abs(before.height - after.height) <= tolerance);
+}

package/dist/web/element/animations.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What is moving.
+ *
+ * Motion explains readings that otherwise look wrong: a style
+ * caught mid-transition, an element that is not where it will
+ * be a moment later. It is also an accessibility question,
+ * since something animating without end is a barrier for
+ * readers who need the page to hold still.
+ */
+/** An animation as the page reported it. */
+export interface RawAnimation {
+    readonly name?: string;
+    readonly kind: string;
+    readonly playState: string;
+    readonly durationMs?: number;
+    readonly easing?: string;
+    /**
+     * How many times it repeats, as text. An endless animation
+     * counts Infinity, which becomes null once serialized, so the
+     * page sends the word instead.
+     */
+    readonly iterations?: string;
+}
+/** Something moving on an element. */
+export interface Animation {
+    readonly name: string;
+    readonly kind: string;
+    readonly playState: string;
+    readonly durationMs?: number;
+    readonly easing?: string;
+    readonly iterations: string;
+}
+/** Read a capture's animations. */
+export declare function normalizeAnimations(raw: readonly RawAnimation[]): readonly Animation[];
+/** Say what is moving and how. */
+export declare function renderAnimations(animations: readonly Animation[]): string;
+/**
+ * Read what is animating on an element.
+ *
+ * Runs with the element as its receiver. Iteration counts are
+ * stringified in the page because Infinity does not survive
+ * being serialized and would arrive as null, reading as though
+ * an endless animation had no repeat count at all.
+ *
+ * Page source rather than a function, for the reason given in
+ * the accessibility observer.
+ */
+export declare const ANIMATIONS_PROBE = "function () {\n  if (!this.getAnimations) return [];\n  return this.getAnimations().map(function (animation) {\n    var timing = animation.effect && animation.effect.getTiming\n      ? animation.effect.getTiming()\n      : {};\n    var duration = typeof timing.duration === \"number\"\n      ? timing.duration\n      : undefined;\n    return {\n      name: animation.animationName || animation.transitionProperty || \"\",\n      kind: animation.transitionProperty ? \"transition\" : \"animation\",\n      playState: animation.playState,\n      durationMs: duration,\n      easing: timing.easing,\n      iterations: String(timing.iterations),\n    };\n  });\n}";

package/dist/web/element/animations.js

@@ -0,0 +1,74 @@
+/**
+ * What is moving.
+ *
+ * Motion explains readings that otherwise look wrong: a style
+ * caught mid-transition, an element that is not where it will
+ * be a moment later. It is also an accessibility question,
+ * since something animating without end is a barrier for
+ * readers who need the page to hold still.
+ */
+/** Read a capture's animations. */
+export function normalizeAnimations(raw) {
+    return raw.map((animation) => ({
+        name: animation.name || "unnamed",
+        kind: animation.kind,
+        playState: animation.playState,
+        ...(animation.durationMs === undefined
+            ? {}
+            : { durationMs: animation.durationMs }),
+        ...(animation.easing === undefined ? {} : { easing: animation.easing }),
+        iterations: animation.iterations === "Infinity"
+            ? "endless"
+            : (animation.iterations ?? "1"),
+    }));
+}
+/** Say what is moving and how. */
+export function renderAnimations(animations) {
+    if (animations.length === 0)
+        return "Nothing is animating.";
+    return animations
+        .map((animation) => {
+        const parts = [animation.name, animation.kind, animation.playState];
+        if (animation.durationMs !== undefined) {
+            parts.push(`${animation.durationMs}ms`);
+        }
+        if (animation.easing)
+            parts.push(animation.easing);
+        // Repeating once is what everything does; only an
+        // unusual count is worth the words.
+        if (animation.iterations !== "1")
+            parts.push(animation.iterations);
+        return parts.join("  ");
+    })
+        .join("\n");
+}
+/**
+ * Read what is animating on an element.
+ *
+ * Runs with the element as its receiver. Iteration counts are
+ * stringified in the page because Infinity does not survive
+ * being serialized and would arrive as null, reading as though
+ * an endless animation had no repeat count at all.
+ *
+ * Page source rather than a function, for the reason given in
+ * the accessibility observer.
+ */
+export const ANIMATIONS_PROBE = `function () {
+  if (!this.getAnimations) return [];
+  return this.getAnimations().map(function (animation) {
+    var timing = animation.effect && animation.effect.getTiming
+      ? animation.effect.getTiming()
+      : {};
+    var duration = typeof timing.duration === "number"
+      ? timing.duration
+      : undefined;
+    return {
+      name: animation.animationName || animation.transitionProperty || "",
+      kind: animation.transitionProperty ? "transition" : "animation",
+      playState: animation.playState,
+      durationMs: duration,
+      easing: timing.easing,
+      iterations: String(timing.iterations),
+    };
+  });
+}`;