@jitsusama/agentic-harness.core 0.1.0

package/dist/web/styles/curation.js

@@ -0,0 +1,282 @@
+/**
+ * Which computed styles are worth reading.
+ *
+ * A capture carries around 480 properties, some 11 KB of text,
+ * and most of them sit at a value nobody chose. Dumping that
+ * buries the handful that explain why an element looks and
+ * lays out the way it does. This keeps the curated set, groups
+ * it by concern, and drops anything still at its initial value.
+ *
+ * Which values count as untouched is the browser's to say, not
+ * this module's. The caller reads them from the page and hands
+ * them in; see INITIALS_PROBE.
+ */
+/**
+ * The curated set, in reading order.
+ *
+ * Order within a group is the order declared here rather than
+ * capture order, so two reads of an unchanged element are
+ * diffable.
+ */
+const CURATED = [
+    {
+        name: "box",
+        properties: [
+            "display",
+            "position",
+            "inset",
+            "top",
+            "right",
+            "bottom",
+            "left",
+            "width",
+            "height",
+            "min-width",
+            "min-height",
+            "max-width",
+            "max-height",
+            "box-sizing",
+            "margin",
+            "margin-top",
+            "margin-right",
+            "margin-bottom",
+            "margin-left",
+            "padding",
+            "padding-top",
+            "padding-right",
+            "padding-bottom",
+            "padding-left",
+            "border-width",
+            "border-top-width",
+            "border-right-width",
+            "border-bottom-width",
+            "border-left-width",
+            "overflow-x",
+            "overflow-y",
+            "float",
+            "clear",
+        ],
+    },
+    {
+        name: "layout",
+        properties: [
+            "flex-direction",
+            "flex-wrap",
+            "justify-content",
+            "align-items",
+            "align-self",
+            "align-content",
+            "flex-grow",
+            "flex-shrink",
+            "flex-basis",
+            "order",
+            "gap",
+            "row-gap",
+            "column-gap",
+            "grid-template-columns",
+            "grid-template-rows",
+            "grid-template-areas",
+            "grid-area",
+            "grid-column",
+            "grid-row",
+        ],
+    },
+    {
+        name: "typography",
+        properties: [
+            "font-family",
+            "font-size",
+            "font-weight",
+            "font-style",
+            "line-height",
+            "letter-spacing",
+            "word-spacing",
+            "text-align",
+            "text-transform",
+            "text-decoration-line",
+            "text-overflow",
+            "white-space",
+            "vertical-align",
+        ],
+    },
+    {
+        name: "paint",
+        properties: [
+            "color",
+            "background-color",
+            "background-image",
+            "border-style",
+            "border-top-style",
+            "border-right-style",
+            "border-bottom-style",
+            "border-left-style",
+            "border-color",
+            "border-top-color",
+            "border-right-color",
+            "border-bottom-color",
+            "border-left-color",
+            "border-top-left-radius",
+            "border-top-right-radius",
+            "border-bottom-right-radius",
+            "border-bottom-left-radius",
+            "outline-width",
+            "outline-style",
+            "outline-color",
+            "outline-offset",
+            "box-shadow",
+            "text-shadow",
+            "opacity",
+            "filter",
+            "backdrop-filter",
+            "mix-blend-mode",
+        ],
+    },
+    {
+        name: "interaction",
+        properties: [
+            "visibility",
+            "cursor",
+            "pointer-events",
+            "user-select",
+            "z-index",
+            "resize",
+            "touch-action",
+            "accent-color",
+        ],
+    },
+    {
+        name: "motion",
+        properties: [
+            "transform",
+            "transform-origin",
+            "transition-property",
+            "transition-duration",
+            "transition-timing-function",
+            "transition-delay",
+            "animation-name",
+            "animation-duration",
+            "animation-timing-function",
+            "animation-iteration-count",
+            "animation-play-state",
+            "will-change",
+        ],
+    },
+];
+/** The sides a border is described one at a time. */
+const SIDES = ["top", "right", "bottom", "left"];
+/** Whether a value is present and something other than none. */
+function inEffect(value) {
+    return value !== undefined && value !== "none";
+}
+/** Whether this side actually paints a border. */
+function hasBorder(styles, side) {
+    if (!inEffect(styles[`border-${side}-style`]))
+        return false;
+    return styles[`border-${side}-width`] !== "0px";
+}
+/**
+ * Properties that only mean something when another property is
+ * in effect. Chrome resolves several initial values into
+ * concrete numbers, so a value that differs from its initial
+ * is not proof that it does anything: an outline width of 3px
+ * paints nothing while the outline style is none.
+ */
+const RELEVANT_WHEN = {
+    ...Object.fromEntries(SIDES.flatMap((side) => [
+        [
+            `border-${side}-color`,
+            (styles) => hasBorder(styles, side),
+        ],
+        [
+            `border-${side}-style`,
+            (styles) => hasBorder(styles, side),
+        ],
+    ])),
+    "border-color": (styles) => inEffect(styles["border-style"]),
+    "outline-color": (styles) => inEffect(styles["outline-style"]),
+    "outline-offset": (styles) => inEffect(styles["outline-style"]),
+    "outline-width": (styles) => inEffect(styles["outline-style"]),
+    "transform-origin": (styles) => inEffect(styles.transform),
+};
+/** Curate a capture into groups worth reading. */
+export function curateStyles(styles, options = {}) {
+    if (options.only)
+        return requested(styles, options.only);
+    // Asking for everything means the capture as it was read.
+    const covered = options.all ? new Set() : sidesCoveredBy(styles);
+    const groups = [];
+    for (const { name, properties } of CURATED) {
+        const entries = [];
+        for (const property of properties) {
+            const value = styles[property];
+            if (value === undefined)
+                continue;
+            if (options.all) {
+                entries.push({ property, value });
+                continue;
+            }
+            if (covered.has(property))
+                continue;
+            if (value === options.initials?.[property])
+                continue;
+            if (RELEVANT_WHEN[property]?.(styles) === false)
+                continue;
+            entries.push({ property, value });
+        }
+        if (entries.length > 0)
+            groups.push({ name, entries });
+    }
+    return groups;
+}
+/**
+ * Shorthands and the sides they stand for.
+ *
+ * The browser serializes these itself, so when a capture
+ * carries one it is used and its sides are left out. Nothing
+ * here computes a shorthand: CSS serialization has rules about
+ * uneven sides and omitted values that only the browser can be
+ * trusted to apply.
+ */
+const SHORTHANDS = [
+    { shorthand: "margin", sides: SIDES.map((side) => `margin-${side}`) },
+    { shorthand: "padding", sides: SIDES.map((side) => `padding-${side}`) },
+    { shorthand: "inset", sides: [...SIDES] },
+    {
+        shorthand: "border-width",
+        sides: SIDES.map((side) => `border-${side}-width`),
+    },
+    {
+        shorthand: "border-style",
+        sides: SIDES.map((side) => `border-${side}-style`),
+    },
+    {
+        shorthand: "border-color",
+        sides: SIDES.map((side) => `border-${side}-color`),
+    },
+];
+/** Sides the capture already stated as a shorthand. */
+function sidesCoveredBy(styles) {
+    const covered = new Set();
+    for (const { shorthand, sides } of SHORTHANDS) {
+        if (styles[shorthand] === undefined)
+            continue;
+        for (const side of sides)
+            covered.add(side);
+    }
+    return covered;
+}
+/**
+ * Exactly what was asked for, in the order it was asked for.
+ * An explicit request overrides curation, including the rule
+ * about initial values: the caller knows something the curated
+ * set does not.
+ */
+function requested(styles, properties) {
+    const entries = [];
+    for (const property of properties) {
+        const value = styles[property];
+        if (value !== undefined)
+            entries.push({ property, value });
+    }
+    return entries.length > 0 ? [{ name: "requested", entries }] : [];
+}

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

@@ -0,0 +1,10 @@
+/**
+ * The styles domain: how an element is painted and laid out.
+ *
+ * Analysis here is capture-agnostic. Everything takes plain
+ * serializable data, so styles read by CDP, by another driver
+ * or from a fixture are curated by the same code.
+ */
+export { asCall, COMPUTED_STYLE_PROBE, INITIALS_PROBE, SHORTHAND_PROPERTIES, } from "./capture.js";
+export { type Declaration, type DeclarationOrigin, normalizeCascade, type PropertyTrace, type RawCssProperty, type RawCssRule, type RawMatchedStyles, type RawRuleMatch, traceProperty, } from "./cascade.js";
+export { type ComputedStyles, type CurateOptions, curateStyles, type StyleEntry, type StyleGroup, } from "./curation.js";

package/dist/web/styles/index.js

@@ -0,0 +1,10 @@
+/**
+ * The styles domain: how an element is painted and laid out.
+ *
+ * Analysis here is capture-agnostic. Everything takes plain
+ * serializable data, so styles read by CDP, by another driver
+ * or from a fixture are curated by the same code.
+ */
+export { asCall, COMPUTED_STYLE_PROBE, INITIALS_PROBE, SHORTHAND_PROPERTIES, } from "./capture.js";
+export { normalizeCascade, traceProperty, } from "./cascade.js";
+export { curateStyles, } from "./curation.js";

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

@@ -0,0 +1,7 @@
+/**
+ * Semantic targeting: how an element is named, how that name
+ * resolves to a real node, and what to offer the caller when
+ * it does not.
+ */
+export { ambiguityRefusal, describeRefusal, describeTarget, notFoundRefusal, type TargetCandidate, type TargetRefusal, } from "./refusals.js";
+export { foldEquals, parseTarget, resolveTarget, type Target, type TargetResolution, } from "./target.js";

package/dist/web/target/index.js

@@ -0,0 +1,7 @@
+/**
+ * Semantic targeting: how an element is named, how that name
+ * resolves to a real node, and what to offer the caller when
+ * it does not.
+ */
+export { ambiguityRefusal, describeRefusal, describeTarget, notFoundRefusal, } from "./refusals.js";
+export { foldEquals, parseTarget, resolveTarget, } from "./target.js";

package/dist/web/target/refusals.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Refusals that hand the caller the fix: when a target cannot
+ * be used, say why and offer targets that would work.
+ *
+ * Every candidate offered here is verified against the tree
+ * before it is returned, so a caller can take one and use it
+ * without wondering whether it resolves.
+ */
+import type { AxNode } from "../a11y/index.js";
+import { type Target } from "./target.js";
+/** A target the caller could use instead, and why it is offered. */
+export interface TargetCandidate {
+    readonly target: Target;
+    readonly hint: string;
+}
+/** Why a target could not be used, and what to try instead. */
+export interface TargetRefusal {
+    readonly reason: "ambiguous" | "notFound" | "notActionable";
+    readonly candidates: readonly TargetCandidate[];
+    /**
+     * Near misses that were dropped for being text rather than
+     * controls, described as role and name.
+     *
+     * They are not offered as candidates, since acting on text
+     * spends the caller's next call on something that cannot work.
+     * They are still the answer more often than not: a div dressed
+     * as a button, or a label whose control is named something
+     * else, puts the words on the page under a role nobody can
+     * act on.
+     */
+    readonly inert?: readonly string[];
+    /** How long act waited for actionability before giving up. */
+    readonly waitedMs?: number;
+    /** What stood in the way, when the element was not actionable. */
+    readonly blocking?: string;
+}
+/**
+ * Enumerate the elements an ambiguous target matched, each as
+ * a target that singles it out.
+ */
+export declare function ambiguityRefusal(root: AxNode, target: Target): TargetRefusal;
+/**
+ * Suggest the nearest elements to a target that matched
+ * nothing, climbing a ladder from "same name, written
+ * differently" down to "a character or two off", and
+ * preferring the role the caller asked for at every rung.
+ */
+export declare function notFoundRefusal(root: AxNode, target: Target): TargetRefusal;
+/** Put a refusal into words, the same way for every tool. */
+export declare function describeRefusal(target: Target, refusal: TargetRefusal): string;
+/**
+ * A target written the way a caller would pass it back.
+ *
+ * A control with no accessible name is addressed by its role
+ * alone, so that is how it is written here. Printing an empty
+ * name would be telling the caller to pass punctuation back,
+ * and the outline it was read from does not show one either.
+ */
+export declare function describeTarget(target: Target): string;

package/dist/web/target/refusals.js

@@ -0,0 +1,305 @@
+/**
+ * Refusals that hand the caller the fix: when a target cannot
+ * be used, say why and offer targets that would work.
+ *
+ * Every candidate offered here is verified against the tree
+ * before it is returned, so a caller can take one and use it
+ * without wondering whether it resolves.
+ */
+import { foldEquals, resolveTarget } from "./target.js";
+/** How many suggestions a refusal offers before it stops. */
+const MAX_CANDIDATES = 3;
+/** How far a name may be off and still count as a near miss. */
+const MAX_EDIT_DISTANCE = 2;
+/**
+ * Enumerate the elements an ambiguous target matched, each as
+ * a target that singles it out.
+ */
+export function ambiguityRefusal(root, target) {
+    const matches = matchesOf(root, target);
+    const candidates = matches.map((match, index) => singleOut(root, target, match, index, matches));
+    return { reason: "ambiguous", candidates };
+}
+/** A target for one match, preferring a container over an ordinal. */
+function singleOut(root, target, match, index, matches) {
+    const container = distinguishingContainer(match, matches);
+    if (container) {
+        const proposal = {
+            role: target.role,
+            name: target.name,
+            container: { name: container.name },
+        };
+        if (resolvesTo(root, proposal, match.node)) {
+            return {
+                target: proposal,
+                hint: `in ${container.role} "${container.name}"`,
+            };
+        }
+    }
+    const proposal = {
+        role: target.role,
+        name: target.name,
+        ...(target.container ? { container: target.container } : {}),
+        ordinal: index + 1,
+    };
+    const nearest = nearestNamed(match);
+    const place = `${index + 1} of ${matches.length}`;
+    return {
+        target: proposal,
+        hint: nearest ? `${place}, in ${nearest.role} "${nearest.name}"` : place,
+    };
+}
+/**
+ * The closest named ancestor holding this match and no other,
+ * which therefore tells it apart from its siblings.
+ */
+function distinguishingContainer(match, matches) {
+    for (const ancestor of [...match.ancestors].reverse()) {
+        if (!ancestor.name.trim())
+            continue;
+        const held = matches.filter((other) => other.ancestors.includes(ancestor));
+        if (held.length === 1)
+            return ancestor;
+    }
+    return undefined;
+}
+/** The closest ancestor with a name, for describing where a match sits. */
+function nearestNamed(match) {
+    return [...match.ancestors]
+        .reverse()
+        .find((one) => one.name.trim() !== "" && !NON_CONTAINERS.has(one.role));
+}
+/**
+ * Roles that contain everything and therefore locate nothing.
+ * "In the page" is true of every element and helps no one.
+ */
+const NON_CONTAINERS = new Set(["RootWebArea"]);
+/** Whether a proposed target lands on exactly the intended node. */
+function resolvesTo(root, proposal, intended) {
+    const resolution = resolveTarget(root, proposal);
+    return (resolution.kind === "resolved" &&
+        resolution.backendDomId === intended.backendDomId);
+}
+/** Every node the target matches, in document order. */
+function matchesOf(root, target) {
+    const container = target.container;
+    const scoped = container
+        ? locate(root).filter((one) => inContainer(one, container))
+        : locate(root);
+    return scoped.filter((one) => foldEquals(one.node.role, target.role) &&
+        foldEquals(one.node.name, target.name));
+}
+/** Whether a located node sits in (or is) a matching container. */
+function inContainer(located, container) {
+    const matches = (node) => foldEquals(node.name, container.name) &&
+        (container.role === undefined || foldEquals(node.role, container.role));
+    return matches(located.node) || located.ancestors.some(matches);
+}
+/** Every node under root, each with the ancestors leading to it. */
+function locate(root) {
+    const found = [];
+    const walk = (node, ancestors) => {
+        found.push({ node, ancestors });
+        for (const child of node.children)
+            walk(child, [...ancestors, node]);
+    };
+    walk(root, []);
+    return found;
+}
+/**
+ * Suggest the nearest elements to a target that matched
+ * nothing, climbing a ladder from "same name, written
+ * differently" down to "a character or two off", and
+ * preferring the role the caller asked for at every rung.
+ */
+export function notFoundRefusal(root, target) {
+    const seen = new Set();
+    const candidates = [];
+    const near = locate(root)
+        .map((located) => nearMiss(located, target))
+        .filter((miss) => miss !== undefined)
+        .sort((a, b) => a.rank - b.rank);
+    const ranked = near.filter((miss) => isActionable(miss.located.node));
+    for (const miss of ranked) {
+        if (candidates.length === MAX_CANDIDATES)
+            break;
+        const { role, name } = miss.located.node;
+        const key = `${role}\u0000${name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const proposal = firstResolvable(root, role, name);
+        if (!proposal)
+            continue;
+        candidates.push({ target: proposal, hint: hintFor(miss, target) });
+    }
+    // Only worth saying when there is nothing better to offer. A
+    // caller handed three usable targets does not need to hear
+    // about the text as well.
+    const inert = candidates.length > 0
+        ? []
+        : [
+            ...new Set(near
+                .filter((miss) => !isActionable(miss.located.node))
+                .map((miss) => `${miss.located.node.role} "${miss.located.node.name}"`)),
+        ].slice(0, MAX_CANDIDATES);
+    return {
+        reason: "notFound",
+        candidates,
+        ...(inert.length === 0 ? {} : { inert }),
+    };
+}
+/**
+ * Roles that carry text but cannot be operated. Offering one
+ * as a candidate spends the caller's next call on something
+ * that was never going to work.
+ */
+const INERT_ROLES = new Set([
+    "StaticText",
+    "InlineTextBox",
+    "text",
+    "LabelText",
+    "ListMarker",
+    "RootWebArea",
+]);
+/** Whether a node is something a caller could actually act on. */
+function isActionable(node) {
+    return !INERT_ROLES.has(node.role);
+}
+/** How near this node is to what was asked for, if at all. */
+function nearMiss(located, target) {
+    const { role, name } = located.node;
+    if (!name.trim())
+        return undefined;
+    const sameRole = foldEquals(role, target.role);
+    // Asking for a control with no name says nothing about names,
+    // so there is no ladder to climb: what is worth offering is
+    // the controls that share the role and do have a name, which
+    // is how the caller will end up addressing one. Running the
+    // ladder anyway made a near miss of every named node on the
+    // page, since every name contains the empty string.
+    if (target.name === undefined || target.name === "") {
+        return sameRole
+            ? { located, rank: 0, reason: "same role, and it has a name" }
+            : undefined;
+    }
+    const rung = nameRung(name, target.name);
+    if (rung === undefined)
+        return undefined;
+    // Every rung prefers the asked-for role to the same name elsewhere.
+    return {
+        located,
+        rank: rung.step * 2 + (sameRole ? 0 : 1),
+        reason: rung.reason,
+    };
+}
+/** Which rung of the name ladder this name reaches, if any. */
+function nameRung(found, asked) {
+    if (asked === undefined)
+        return undefined;
+    if (found === asked)
+        return { step: 0, reason: "same name" };
+    if (foldEquals(found, asked)) {
+        return { step: 0, reason: "same name, written differently" };
+    }
+    const haystack = found.trim().toLowerCase();
+    const needle = asked.trim().toLowerCase();
+    if (haystack.includes(needle)) {
+        return { step: 1, reason: "name contains what you asked for" };
+    }
+    if (needle.includes(haystack)) {
+        return { step: 1, reason: "name is part of what you asked for" };
+    }
+    if (editDistance(haystack, needle) <= MAX_EDIT_DISTANCE) {
+        return { step: 2, reason: "a character or two different" };
+    }
+    return undefined;
+}
+/** Say why a suggestion is being offered, and where it sits. */
+function hintFor(miss, target) {
+    const parts = [];
+    if (!foldEquals(miss.located.node.role, target.role)) {
+        parts.push(`${miss.located.node.role} instead of ${target.role}`);
+    }
+    parts.push(miss.reason);
+    const container = nearestNamed(miss.located);
+    if (container)
+        parts.push(`in ${container.role} "${container.name}"`);
+    return parts.join(", ");
+}
+/** A target for this role and name that lands on exactly one node. */
+function firstResolvable(root, role, name) {
+    const plain = { role, name };
+    if (resolveTarget(root, plain).kind === "resolved")
+        return plain;
+    const first = { role, name, ordinal: 1 };
+    return resolveTarget(root, first).kind === "resolved" ? first : undefined;
+}
+/** Levenshtein distance between two strings. */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const substitute = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min(substitute, previous[j] + 1, current[j - 1] + 1);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Put a refusal into words, the same way for every tool. */
+export function describeRefusal(target, refusal) {
+    const asked = describeTarget(target);
+    const lines = [headline(asked, refusal)];
+    for (const candidate of refusal.candidates) {
+        lines.push(`  ${describeTarget(candidate.target)} (${candidate.hint})`);
+    }
+    return lines.join("\n");
+}
+/** The opening line: what happened to the target that was asked for. */
+function headline(asked, refusal) {
+    if (refusal.reason === "ambiguous") {
+        return (`${refusal.candidates.length} elements match ${asked}. ` +
+            `Use one of these instead:`);
+    }
+    if (refusal.reason === "notActionable") {
+        const waited = refusal.waitedMs === undefined
+            ? ""
+            : ` after waiting ${refusal.waitedMs}ms`;
+        const blocking = refusal.blocking ? `: ${refusal.blocking}` : "";
+        return `${asked} did not become actionable${waited}${blocking}.`;
+    }
+    if (refusal.candidates.length > 0)
+        return `Nothing matches ${asked}. Did you mean:`;
+    if (refusal.inert && refusal.inert.length > 0) {
+        // The words are on the page under a role nobody can act on,
+        // which is a different problem from a mistyped name and
+        // wants a different next move.
+        return (`Nothing matches ${asked}. The page carries that name as ` +
+            `${refusal.inert.join(", ")}, which is text rather than ` +
+            "something to act on, so the element may be missing the " +
+            "role you expected.");
+    }
+    return `Nothing matches ${asked}, and nothing on the page is close to it.`;
+}
+/**
+ * A target written the way a caller would pass it back.
+ *
+ * A control with no accessible name is addressed by its role
+ * alone, so that is how it is written here. Printing an empty
+ * name would be telling the caller to pass punctuation back,
+ * and the outline it was read from does not show one either.
+ */
+export function describeTarget(target) {
+    const parts = [
+        target.name
+            ? `role ${target.role} name "${target.name}"`
+            : `role ${target.role}`,
+    ];
+    if (target.container)
+        parts.push(`container "${target.container.name}"`);
+    if (target.ordinal !== undefined)
+        parts.push(`ordinal ${target.ordinal}`);
+    return parts.join(" ");
+}