@jitsusama/agentic-harness.core 0.1.0

package/dist/web/audit/capture.js

@@ -0,0 +1,185 @@
+/**
+ * Building the structural view from two of the browser's own
+ * accounts of the page.
+ *
+ * The snapshot knows every element, its attributes, whether it
+ * was drawn and where it sits in the tree. The accessibility
+ * tree knows what each one is and what it is called. Neither
+ * knows both, and every structural rule needs both, so they are
+ * joined here on the backend node id that appears in each.
+ *
+ * The join is the whole of this module's job. No role is
+ * inferred from a tag, no name is derived from content, and
+ * nothing is guessed when a node appears in one account and not
+ * the other. What the browser did not say, this does not say.
+ */
+/** Roles the browser reports for things nobody can see. */
+const INVISIBLE_ROLES = new Set(["none", "presentation", "InlineTextBox"]);
+/** Elements the browser lets focus land on without being told. */
+const FOCUSABLE_TAGS = new Set([
+    "BUTTON",
+    "INPUT",
+    "SELECT",
+    "TEXTAREA",
+    "SUMMARY",
+]);
+/**
+ * Whether the markup makes this focusable.
+ *
+ * Used when the accessibility tree declines to say, which it
+ * does for every node it ignored, including everything inside an
+ * aria-hidden subtree. That is precisely the case the
+ * hidden-but-focusable rule is about, so without this the rule
+ * has no way to see its own subject.
+ */
+function focusableByMarkup(node) {
+    const tabindex = node.attributes.tabindex;
+    if (tabindex !== undefined)
+        return Number(tabindex) > -1;
+    if (node.attributes.disabled !== undefined)
+        return false;
+    if (node.nodeName === "A")
+        return node.attributes.href !== undefined;
+    return FOCUSABLE_TAGS.has(node.nodeName);
+}
+/**
+ * Give an element an address a person can act on.
+ *
+ * An id is best, then a test hook, then a class, and a tag with
+ * its position as the last resort. This is presentation, not
+ * measurement: the browser did not offer a selector, and one
+ * that reads well is worth more than one that is unique.
+ */
+export function selectorFor(node) {
+    const tag = node.nodeName.toLowerCase();
+    const { id, class: className } = node.attributes;
+    if (id)
+        return `#${id}`;
+    const hook = node.attributes["data-testid"] ?? node.attributes["data-test-id"];
+    if (hook)
+        return `${tag}[data-testid="${hook}"]`;
+    if (className) {
+        const first = className.trim().split(/\s+/)[0];
+        if (first)
+            return `${tag}.${first}`;
+    }
+    return tag;
+}
+/** How much markup to keep against a finding. */
+const MAX_HTML = 160;
+/**
+ * Rebuild an element's opening tag from its attributes.
+ *
+ * The snapshot does not carry outerHTML, and fetching it per
+ * node would be a protocol round trip each. The opening tag is
+ * what a person needs to recognise the element anyway.
+ */
+function openingTag(node) {
+    const tag = node.nodeName.toLowerCase();
+    const attributes = Object.entries(node.attributes)
+        .map(([name, value]) => (value === "" ? name : `${name}="${value}"`))
+        .join(" ");
+    const rendered = attributes === "" ? `<${tag}>` : `<${tag} ${attributes}>`;
+    return rendered.length <= MAX_HTML
+        ? rendered
+        : `${rendered.slice(0, MAX_HTML)}...`;
+}
+/**
+ * Join a snapshot to an accessibility tree.
+ *
+ * Text nodes are dropped: every structural rule is about
+ * elements, and keeping the text would double the size of the
+ * capture to no purpose.
+ */
+export function buildStructure(nodes, facts) {
+    const byBackendId = new Map(facts.map((fact) => [fact.backendNodeId, fact]));
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const ancestorsOf = (node) => {
+        const chain = [];
+        let current = node.parent;
+        while (current !== undefined) {
+            chain.push(current);
+            current = byId.get(current)?.parent;
+        }
+        return chain;
+    };
+    /**
+     * Whether anything from here up has been made inert.
+     *
+     * inert takes a subtree out of the focus order without changing
+     * how any of it looks, so no style or markup question about the
+     * element itself can see it. A closed dialog is the ordinary
+     * case, and its contents are usually aria-hidden too, which is
+     * exactly the pair that made this matter: on one real page 45
+     * controls inside two closed dialogs were reported as critical
+     * WCAG failures for being aria-hidden and focusable, when none
+     * of the 45 could take focus at all.
+     */
+    const inertHere = (node) => {
+        if (node.attributes.inert !== undefined)
+            return true;
+        for (const id of ancestorsOf(node)) {
+            if (byId.get(id)?.attributes.inert !== undefined)
+                return true;
+        }
+        return false;
+    };
+    /**
+     * Whether focus could actually land here, for a node the
+     * accessibility tree declined to describe.
+     *
+     * Markup says an input is focusable. It cannot say that this one
+     * was never laid out, sits under visibility:hidden, or belongs
+     * to an inert subtree, and each of those settles the question
+     * the other way. Measured on one real page, 48 controls met the
+     * markup test inside aria-hidden subtrees and exactly none of
+     * them could take focus: 42 hidden by visibility, 3 by display,
+     * 3 inert. Reported as they were, that is 48 critical WCAG
+     * failures on a page with none.
+     *
+     * visibility is asked of the element rather than its ancestors
+     * because it inherits, so the computed value already carries
+     * the answer, including a child that opts back in with
+     * visibility:visible.
+     */
+    const couldTakeFocus = (node) => {
+        if (!node.rendered)
+            return false;
+        const visibility = node.styles.visibility;
+        if (visibility === "hidden" || visibility === "collapse")
+            return false;
+        return !inertHere(node);
+    };
+    return nodes
+        .filter((node) => node.nodeName !== "#text" && node.nodeName !== "#comment")
+        .map((node) => {
+        const fact = byBackendId.get(node.backendNodeId);
+        const role = fact?.role && !INVISIBLE_ROLES.has(fact.role) ? fact.role : undefined;
+        return {
+            id: node.id,
+            selector: selectorFor(node),
+            tag: node.nodeName.toLowerCase(),
+            attributes: node.attributes,
+            ...(role === undefined ? {} : { role }),
+            ...(fact?.name === undefined || fact.name === ""
+                ? {}
+                : { name: fact.name }),
+            // The accessibility tree only reports focusable on nodes
+            // it did not ignore, and an aria-hidden subtree is exactly
+            // what it ignores: measured against a live page, every
+            // ignored node arrives with an empty property list. So
+            // asking the tree whether a hidden thing can take focus
+            // always answered no, and the rule built on that question
+            // could never fire. Fall back to the markup, which is
+            // where focusability comes from in the first place.
+            //
+            // The fallback has to carry its own weight, though: see
+            // couldTakeFocus, which is what stops a page's closed
+            // dialogs arriving as a wall of critical failures.
+            focusable: fact?.focusable ?? (focusableByMarkup(node) && couldTakeFocus(node)),
+            rendered: node.rendered,
+            ancestors: ancestorsOf(node),
+            html: openingTag(node),
+        };
+    });
+}

package/dist/web/audit/colour.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Colour arithmetic for accessibility judgments.
+ *
+ * Deliberately narrow. This module does the arithmetic WCAG
+ * specifies and nothing else: it does not know what oklch is,
+ * how display-p3 clamps into sRGB, or what colour-mix resolves
+ * to. Chrome returns modern colour syntax from getComputedStyle
+ * unconverted, and converting it here would mean reimplementing
+ * colour science that the renderer already does exactly.
+ *
+ * So the session asks the browser to paint a colour and reads
+ * the pixel back, and everything below works in sRGB bytes.
+ */
+/** A colour in sRGB, channels 0 to 255 and alpha 0 to 1. */
+export interface Rgba {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly a: number;
+}
+/**
+ * How much light a colour reflects, by WCAG's definition.
+ *
+ * Alpha is ignored, because a translucent colour has no
+ * luminance of its own: composite it over something first.
+ */
+export declare function relativeLuminance(colour: Rgba): number;
+/**
+ * The contrast between two colours, from 1 to 21.
+ *
+ * Order does not matter: the lighter colour always goes on top
+ * of the fraction, so a light-on-dark pair reads the same as its
+ * reverse.
+ */
+export declare function contrastRatio(one: Rgba, other: Rgba): number;
+/**
+ * Paint one colour over another and say what results.
+ *
+ * This is source-over compositing, the same operation the
+ * renderer performs, and it is what makes a translucent
+ * foreground judgeable at all.
+ */
+export declare function composite(over: Rgba, under: Rgba): Rgba;
+/** Whether a colour hides whatever is behind it. */
+export declare function isOpaque(colour: Rgba): boolean;
+/** Whether a colour shows everything behind it. */
+export declare function isTransparent(colour: Rgba): boolean;
+/**
+ * Read the colour syntaxes the browser reliably produces.
+ *
+ * getComputedStyle serializes most colours as rgb() or rgba(),
+ * and a stylesheet written in modern colour syntax comes back as
+ * color(srgb ...) instead, unconverted. Both are read here.
+ * Anything else, oklch and the wider color() spaces among them,
+ * returns nothing rather than being guessed at, so the caller can
+ * ask the browser to resolve it instead of getting a confidently
+ * wrong answer.
+ */
+export declare function parseRgb(css: string): Rgba | undefined;
+/** Say a colour the way CSS would. */
+export declare function formatRgb(colour: Rgba): string;
+/**
+ * How far apart two colours look, as CIE76 delta E.
+ *
+ * Contrast is not a measure of sameness. It compares relative
+ * luminance only, so it is blind to hue by construction: pure
+ * red and a mid grey differ by a contrast ratio of about 1.001,
+ * which any threshold for "these look the same" will accept.
+ * That is the right answer to "can text be read on this" and the
+ * wrong answer to "are these one colour".
+ *
+ * Delta E is the measure for the second question. Roughly, 1 is
+ * the smallest difference an eye can catch under ideal
+ * conditions, 2 to 3 is a just-noticeable difference in
+ * practice, and anything past about 10 reads as two colours.
+ *
+ * CIE76 rather than CIEDE2000: it is a plain Euclidean distance
+ * in Lab, it is close enough at the small distances this is used
+ * for, and it can be read and checked by anyone.
+ *
+ * Alpha is not considered. A caller that cares about opacity
+ * should compare it separately, or composite both colours over
+ * a known background first.
+ */
+export declare function deltaE(one: Rgba, other: Rgba): number;

package/dist/web/audit/colour.js

@@ -0,0 +1,189 @@
+/**
+ * Colour arithmetic for accessibility judgments.
+ *
+ * Deliberately narrow. This module does the arithmetic WCAG
+ * specifies and nothing else: it does not know what oklch is,
+ * how display-p3 clamps into sRGB, or what colour-mix resolves
+ * to. Chrome returns modern colour syntax from getComputedStyle
+ * unconverted, and converting it here would mean reimplementing
+ * colour science that the renderer already does exactly.
+ *
+ * So the session asks the browser to paint a colour and reads
+ * the pixel back, and everything below works in sRGB bytes.
+ */
+/** The threshold WCAG names, which is not the sRGB spec's. */
+const LINEAR_CUTOFF = 0.03928;
+const LINEAR_DIVISOR = 12.92;
+const GAMMA_OFFSET = 0.055;
+const GAMMA_SCALE = 1.055;
+const GAMMA_EXPONENT = 2.4;
+/** How much each channel contributes to perceived lightness. */
+const RED_WEIGHT = 0.2126;
+const GREEN_WEIGHT = 0.7152;
+const BLUE_WEIGHT = 0.0722;
+/** Keeps a ratio finite when both colours are pure black. */
+const RATIO_OFFSET = 0.05;
+const CHANNEL_MAX = 255;
+function linearize(channel) {
+    const scaled = channel / CHANNEL_MAX;
+    return scaled <= LINEAR_CUTOFF
+        ? scaled / LINEAR_DIVISOR
+        : ((scaled + GAMMA_OFFSET) / GAMMA_SCALE) ** GAMMA_EXPONENT;
+}
+/**
+ * How much light a colour reflects, by WCAG's definition.
+ *
+ * Alpha is ignored, because a translucent colour has no
+ * luminance of its own: composite it over something first.
+ */
+export function relativeLuminance(colour) {
+    return (RED_WEIGHT * linearize(colour.r) +
+        GREEN_WEIGHT * linearize(colour.g) +
+        BLUE_WEIGHT * linearize(colour.b));
+}
+/**
+ * The contrast between two colours, from 1 to 21.
+ *
+ * Order does not matter: the lighter colour always goes on top
+ * of the fraction, so a light-on-dark pair reads the same as its
+ * reverse.
+ */
+export function contrastRatio(one, other) {
+    const a = relativeLuminance(one);
+    const b = relativeLuminance(other);
+    const lighter = Math.max(a, b);
+    const darker = Math.min(a, b);
+    return (lighter + RATIO_OFFSET) / (darker + RATIO_OFFSET);
+}
+/**
+ * Paint one colour over another and say what results.
+ *
+ * This is source-over compositing, the same operation the
+ * renderer performs, and it is what makes a translucent
+ * foreground judgeable at all.
+ */
+export function composite(over, under) {
+    if (over.a >= 1)
+        return over;
+    if (over.a <= 0)
+        return under;
+    const alpha = over.a + under.a * (1 - over.a);
+    if (alpha <= 0)
+        return { r: 0, g: 0, b: 0, a: 0 };
+    const blend = (top, bottom) => Math.round((top * over.a + bottom * under.a * (1 - over.a)) / alpha);
+    return {
+        r: blend(over.r, under.r),
+        g: blend(over.g, under.g),
+        b: blend(over.b, under.b),
+        a: alpha,
+    };
+}
+/** Whether a colour hides whatever is behind it. */
+export function isOpaque(colour) {
+    return colour.a >= 1;
+}
+/** Whether a colour shows everything behind it. */
+export function isTransparent(colour) {
+    return colour.a <= 0;
+}
+const RGB_PATTERN = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/;
+/**
+ * The srgb arm of color(), whose channels are fractions of full.
+ *
+ * Only srgb is matched. display-p3 and the rest are written the
+ * same way but describe a wider gamut, so reading their numbers
+ * on this scale would be wrong without a conversion nobody here
+ * is doing.
+ */
+const SRGB_PATTERN = /^color\(\s*srgb\s+([\d.]+)\s+([\d.]+)\s+([\d.]+)(?:\s*\/\s*([\d.]+%?))?\s*\)$/;
+/** Full scale for a channel color(srgb ...) states as a fraction. */
+const FULL_CHANNEL = 255;
+/**
+ * Read the colour syntaxes the browser reliably produces.
+ *
+ * getComputedStyle serializes most colours as rgb() or rgba(),
+ * and a stylesheet written in modern colour syntax comes back as
+ * color(srgb ...) instead, unconverted. Both are read here.
+ * Anything else, oklch and the wider color() spaces among them,
+ * returns nothing rather than being guessed at, so the caller can
+ * ask the browser to resolve it instead of getting a confidently
+ * wrong answer.
+ */
+export function parseRgb(css) {
+    const text = css.trim();
+    const found = RGB_PATTERN.exec(text);
+    const fractions = found ? undefined : SRGB_PATTERN.exec(text);
+    const matched = found ?? fractions;
+    if (!matched)
+        return undefined;
+    const [, red, green, blue, alpha] = matched;
+    // color(srgb ...) states each channel as a fraction of full, so it
+    // needs the scale rgb() already speaks in. The rgb() path is left
+    // exactly as it was, fractional channels included.
+    const channel = (t) => fractions ? Math.round(Number(t ?? "0") * FULL_CHANNEL) : Number(t ?? "0");
+    const opacity = alpha === undefined
+        ? 1
+        : alpha.endsWith("%")
+            ? Number(alpha.slice(0, -1)) / 100
+            : Number(alpha);
+    const colour = {
+        r: channel(red),
+        g: channel(green),
+        b: channel(blue),
+        a: opacity,
+    };
+    return Object.values(colour).some(Number.isNaN) ? undefined : colour;
+}
+/** Say a colour the way CSS would. */
+export function formatRgb(colour) {
+    return isOpaque(colour)
+        ? `rgb(${colour.r}, ${colour.g}, ${colour.b})`
+        : `rgba(${colour.r}, ${colour.g}, ${colour.b}, ${Math.round(colour.a * 1000) / 1000})`;
+}
+/**
+ * How far apart two colours look, as CIE76 delta E.
+ *
+ * Contrast is not a measure of sameness. It compares relative
+ * luminance only, so it is blind to hue by construction: pure
+ * red and a mid grey differ by a contrast ratio of about 1.001,
+ * which any threshold for "these look the same" will accept.
+ * That is the right answer to "can text be read on this" and the
+ * wrong answer to "are these one colour".
+ *
+ * Delta E is the measure for the second question. Roughly, 1 is
+ * the smallest difference an eye can catch under ideal
+ * conditions, 2 to 3 is a just-noticeable difference in
+ * practice, and anything past about 10 reads as two colours.
+ *
+ * CIE76 rather than CIEDE2000: it is a plain Euclidean distance
+ * in Lab, it is close enough at the small distances this is used
+ * for, and it can be read and checked by anyone.
+ *
+ * Alpha is not considered. A caller that cares about opacity
+ * should compare it separately, or composite both colours over
+ * a known background first.
+ */
+export function deltaE(one, other) {
+    const [l1, a1, b1] = toLab(one);
+    const [l2, a2, b2] = toLab(other);
+    return Math.sqrt((l1 - l2) ** 2 + (a1 - a2) ** 2 + (b1 - b2) ** 2);
+}
+/** D65, the white point sRGB is defined against. */
+const WHITE = { x: 0.95047, y: 1, z: 1.08883 };
+/** The knee in the Lab transfer function. */
+const LAB_EPSILON = 216 / 24389;
+const LAB_KAPPA = 24389 / 27;
+/** sRGB to CIELAB, by way of XYZ. */
+function toLab(colour) {
+    const r = linearize(colour.r);
+    const g = linearize(colour.g);
+    const b = linearize(colour.b);
+    const x = (0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / WHITE.x;
+    const y = (0.2126729 * r + 0.7151522 * g + 0.072175 * b) / WHITE.y;
+    const z = (0.0193339 * r + 0.119192 * g + 0.9503041 * b) / WHITE.z;
+    const f = (value) => value > LAB_EPSILON ? Math.cbrt(value) : (LAB_KAPPA * value + 16) / 116;
+    const fx = f(x);
+    const fy = f(y);
+    const fz = f(z);
+    return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
+}

package/dist/web/audit/contrast.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Judging contrast against WCAG's thresholds.
+ *
+ * The arithmetic is in colour.ts; this is the part that says
+ * what counts as enough, which depends on how big the text is
+ * and which level is being held to.
+ *
+ * A judgment can also decline. A gradient, a background image
+ * or a background nobody could determine is not a failure and
+ * not a pass: it is a case where the honest answer is that a
+ * person has to look. Reporting those as passes is how an
+ * automated audit becomes a liability.
+ */
+import { type Rgba } from "./colour.js";
+/** Which WCAG conformance level a judgment is held to. */
+export type ContrastLevel = "AA" | "AAA";
+/** Text at or above this size counts as large. */
+export declare const LARGE_TEXT_PX = 24;
+/** Bold text at or above this size counts as large: 14pt. */
+export declare const LARGE_BOLD_PX = 18.66;
+/** The weight at which text is bold for sizing purposes. */
+export declare const BOLD_WEIGHT = 700;
+/** 1.4.11 Non-text Contrast, for controls and meaningful graphics. */
+export declare const NON_TEXT_MINIMUM = 3;
+/** How text is set, which decides which threshold applies. */
+export interface TextSizing {
+    readonly fontSizePx: number;
+    readonly fontWeight: number;
+}
+/**
+ * Whether text is large enough for the relaxed threshold.
+ *
+ * The bold cutoff is 14pt against 18pt for normal, which is
+ * 18.66px against 24px once points become CSS pixels.
+ */
+export declare function isLargeText(sizing: TextSizing): boolean;
+/** The ratio text of this size must reach at this level. */
+export declare function textThreshold(sizing: TextSizing, level: ContrastLevel): number;
+/** What a contrast judgment concluded. */
+export type ContrastVerdict = {
+    readonly kind: "judged";
+    readonly ratio: number;
+    readonly required: number;
+    readonly passes: boolean;
+    readonly level: ContrastLevel;
+    readonly foreground: Rgba;
+    readonly background: Rgba;
+    readonly large: boolean;
+} | {
+    readonly kind: "undecidable";
+    /** Why nobody could say, in words a person can act on. */
+    readonly because: string;
+};
+/** Judge text against the threshold for its size. */
+export declare function judgeText(input: {
+    readonly foreground: Rgba;
+    readonly background: Rgba;
+    readonly sizing: TextSizing;
+    readonly level?: ContrastLevel;
+}): ContrastVerdict;
+/**
+ * Judge a control's own colours, where size never relaxes it.
+ *
+ * A focus ring, a checkbox border and an icon that carries
+ * meaning are all held to 3:1 regardless of how big they are.
+ */
+export declare function judgeNonText(input: {
+    readonly foreground: Rgba;
+    readonly background: Rgba;
+}): ContrastVerdict;
+/** Decline to judge, and say why. */
+export declare function undecidable(because: string): ContrastVerdict;
+/** Say what the judgment was. */
+export declare function renderContrast(verdict: ContrastVerdict): string;

package/dist/web/audit/contrast.js

@@ -0,0 +1,104 @@
+/**
+ * Judging contrast against WCAG's thresholds.
+ *
+ * The arithmetic is in colour.ts; this is the part that says
+ * what counts as enough, which depends on how big the text is
+ * and which level is being held to.
+ *
+ * A judgment can also decline. A gradient, a background image
+ * or a background nobody could determine is not a failure and
+ * not a pass: it is a case where the honest answer is that a
+ * person has to look. Reporting those as passes is how an
+ * automated audit becomes a liability.
+ */
+import { contrastRatio, formatRgb } from "./colour.js";
+/** Text at or above this size counts as large. */
+export const LARGE_TEXT_PX = 24;
+/** Bold text at or above this size counts as large: 14pt. */
+export const LARGE_BOLD_PX = 18.66;
+/** The weight at which text is bold for sizing purposes. */
+export const BOLD_WEIGHT = 700;
+/** 1.4.3 Contrast (Minimum), normal and large text. */
+const AA_NORMAL = 4.5;
+const AA_LARGE = 3;
+/** 1.4.6 Contrast (Enhanced). */
+const AAA_NORMAL = 7;
+const AAA_LARGE = 4.5;
+/** 1.4.11 Non-text Contrast, for controls and meaningful graphics. */
+export const NON_TEXT_MINIMUM = 3;
+/**
+ * Whether text is large enough for the relaxed threshold.
+ *
+ * The bold cutoff is 14pt against 18pt for normal, which is
+ * 18.66px against 24px once points become CSS pixels.
+ */
+export function isLargeText(sizing) {
+    return sizing.fontWeight >= BOLD_WEIGHT
+        ? sizing.fontSizePx >= LARGE_BOLD_PX
+        : sizing.fontSizePx >= LARGE_TEXT_PX;
+}
+/** The ratio text of this size must reach at this level. */
+export function textThreshold(sizing, level) {
+    const large = isLargeText(sizing);
+    if (level === "AAA")
+        return large ? AAA_LARGE : AAA_NORMAL;
+    return large ? AA_LARGE : AA_NORMAL;
+}
+/** Judge text against the threshold for its size. */
+export function judgeText(input) {
+    const level = input.level ?? "AA";
+    const required = textThreshold(input.sizing, level);
+    return judged(input.foreground, input.background, required, level, {
+        large: isLargeText(input.sizing),
+    });
+}
+/**
+ * Judge a control's own colours, where size never relaxes it.
+ *
+ * A focus ring, a checkbox border and an icon that carries
+ * meaning are all held to 3:1 regardless of how big they are.
+ */
+export function judgeNonText(input) {
+    return judged(input.foreground, input.background, NON_TEXT_MINIMUM, "AA", {
+        large: false,
+    });
+}
+/** Rounded the way the ratio is always quoted. */
+const RATIO_PLACES = 100;
+function judged(foreground, background, required, level, extra) {
+    const exact = contrastRatio(foreground, background);
+    // Reported rounded, judged exact.
+    //
+    // Rounding before the comparison passed 4.4951 as AA, which is
+    // leniency in the one module that must not have any: it
+    // disagrees with axe on the same pair inside the same report,
+    // and the direction of the error is always to approve. A ratio
+    // that reads 4.5 and fails is worth one line of explanation;
+    // a failure reported as a pass is not worth anything.
+    const ratio = Math.round(exact * RATIO_PLACES) / RATIO_PLACES;
+    return {
+        kind: "judged",
+        ratio,
+        required,
+        passes: exact >= required,
+        level,
+        foreground,
+        background,
+        large: extra.large,
+    };
+}
+/** Decline to judge, and say why. */
+export function undecidable(because) {
+    return { kind: "undecidable", because };
+}
+/** Say what the judgment was. */
+export function renderContrast(verdict) {
+    if (verdict.kind === "undecidable") {
+        return `Contrast could not be determined: ${verdict.because}`;
+    }
+    const { ratio, required, passes, level, foreground, background } = verdict;
+    const size = verdict.large ? "large text" : "normal text";
+    const outcome = passes ? "meets" : "falls short of";
+    return (`${ratio}:1 ${outcome} the ${required}:1 ${level} minimum for ` +
+        `${size}. ${formatRgb(foreground)} on ${formatRgb(background)}`);
+}

package/dist/web/audit/health.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One question that asks all the others.
+ *
+ * A person who has just changed something wants to know whether
+ * they broke anything, and does not want to run five checks to
+ * find out. This composes them into one answer: the worst
+ * standing across all of them, a line each, and the detail left
+ * behind a named kind.
+ *
+ * The digest deliberately reports what it could not run. A check
+ * that failed to execute is not a check that passed, and a
+ * digest that quietly drops one is worse than no digest, because
+ * it looks like coverage.
+ */
+import type { Standing } from "./verdict.js";
+/** One check's contribution to the digest. */
+export interface Part {
+    readonly kind: string;
+    readonly standing: Standing;
+    readonly headline: string;
+    /** Set when the check could not run at all. */
+    readonly failedToRun?: string;
+}
+/** The worst standing among the parts. */
+export declare function overallOf(parts: readonly Part[]): Standing;
+/** Say how the page is doing, across every check. */
+export declare function renderHealth(parts: readonly Part[]): string;