@jitsusama/agentic-harness.core 0.1.0

package/dist/web/element/measure.js

@@ -0,0 +1,118 @@
+/**
+ * The space between two elements.
+ *
+ * Most of design review is one question asked over and over: is
+ * that gap 16 or 12. Every box needed to answer it was already
+ * being read; nothing subtracted them, so the answer came from
+ * squinting at a screenshot.
+ */
+/**
+ * Sub-pixel layout is normal and a designer does not mean it.
+ *
+ * Two edges a thousandth of a pixel apart were meant to line up,
+ * and reporting them as misaligned would bury the one case that
+ * is a real mistake in noise.
+ */
+const SAME = 0.5;
+/** Measure one axis: the space between two spans on a line. */
+function relate(startA, endA, startB, endB) {
+    const between = Math.max(startA, startB) - Math.min(endA, endB);
+    if (between > 0)
+        return { kind: "gap", pixels: round(between) };
+    // They touch or cross. How far they cross is the smaller of the
+    // two overhangs, which is the distance one would have to move
+    // to clear the other.
+    const into = Math.min(endA, endB) - Math.max(startA, startB);
+    if (into <= 0)
+        return { kind: "gap", pixels: 0 };
+    // One fully inside the other on this axis is the ordinary case
+    // for boxes in a row, and is not an overlap anybody wants told.
+    const shorter = Math.min(endA - startA, endB - startB);
+    if (into >= shorter - SAME)
+        return { kind: "spans", pixels: 0 };
+    return { kind: "overlap", pixels: round(into) };
+}
+/** Pixels, to a tenth, without a trailing zero. */
+function round(value) {
+    return Math.round(value * 10) / 10;
+}
+const near = (a, b) => Math.abs(a - b) <= SAME;
+/** Measure the space between two boxes. */
+export function measureBetween(a, b) {
+    const horizontal = relate(a.x, a.x + a.width, b.x, b.x + b.width);
+    const vertical = relate(a.y, a.y + a.height, b.y, b.y + b.height);
+    const aligned = [];
+    if (near(a.x, b.x))
+        aligned.push("left");
+    if (near(a.x + a.width, b.x + b.width))
+        aligned.push("right");
+    if (near(a.y, b.y))
+        aligned.push("top");
+    if (near(a.y + a.height, b.y + b.height))
+        aligned.push("bottom");
+    // A centre line only earns a mention when no edge on that axis
+    // already explains the alignment, or every centred pair would
+    // be reported three times.
+    if (!aligned.includes("left") && !aligned.includes("right")) {
+        if (near(a.x + a.width / 2, b.x + b.width / 2)) {
+            aligned.push("horizontal centre");
+        }
+    }
+    if (!aligned.includes("top") && !aligned.includes("bottom")) {
+        if (near(a.y + a.height / 2, b.y + b.height / 2)) {
+            aligned.push("vertical centre");
+        }
+    }
+    const widthDelta = round(Math.abs(a.width - b.width));
+    const heightDelta = round(Math.abs(a.height - b.height));
+    return {
+        horizontal,
+        vertical,
+        aligned,
+        sameSize: widthDelta <= SAME && heightDelta <= SAME,
+        widthDelta,
+        heightDelta,
+    };
+}
+/** One axis in words. */
+function say(relation, axis) {
+    if (relation.kind === "gap") {
+        return `${relation.pixels}px ${axis} between them`;
+    }
+    if (relation.kind === "overlap") {
+        return `they overlap by ${relation.pixels}px ${axis}`;
+    }
+    return undefined;
+}
+/**
+ * Say what was measured, gap first because that is what was asked.
+ */
+export function renderMeasurement(m, nameA, nameB) {
+    const lines = [`${nameA} and ${nameB}:`];
+    const across = say(m.horizontal, "horizontally");
+    const down = say(m.vertical, "vertically");
+    if (across === undefined && down === undefined) {
+        // Both axes spanning means one contains the other, which is
+        // worth saying plainly rather than reporting as no news.
+        lines.push("  One sits inside the other; there is no gap to measure.");
+    }
+    if (across !== undefined)
+        lines.push(`  ${across}`);
+    if (down !== undefined)
+        lines.push(`  ${down}`);
+    if (m.aligned.length > 0) {
+        lines.push(`  Lined up on: ${m.aligned.join(", ")}`);
+    }
+    if (m.sameSize) {
+        lines.push("  Same size.");
+    }
+    else {
+        const parts = [];
+        if (m.widthDelta > SAME)
+            parts.push(`${m.widthDelta}px in width`);
+        if (m.heightDelta > SAME)
+            parts.push(`${m.heightDelta}px in height`);
+        lines.push(`  Differ by ${parts.join(" and ")}.`);
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Asking the browser about one element.
+ *
+ * Page sources rather than functions, for the same reason the
+ * accessibility observer is: the compiler wraps named inner
+ * bindings in a __name helper the page has never heard of, so
+ * a serialized function that declares helpers of its own
+ * throws on arrival.
+ */
+/**
+ * Who receives a click at a point, when it is not the element
+ * being asked about.
+ *
+ * Runs with the element as its receiver and the hit node as its
+ * only argument. Anything the element contains counts as
+ * itself, since a click there still reaches it. Returns a short
+ * description of the obstruction, or null when there is none.
+ */
+/**
+ * Stop an element's own text from painting, and put it back.
+ *
+ * Runs with the element as its receiver. Only colour and shadow are
+ * touched, because neither affects layout: the glyphs still occupy
+ * the same pixels and simply leave no mark, which is what lets two
+ * shots of the same region be subtracted from one another.
+ *
+ * The element's own inline values are remembered on the node itself
+ * rather than in the caller, so a restore still works if the caller
+ * lost track of what it changed. An element with no inline colour of
+ * its own is restored by removing the property, not by writing an
+ * empty string over it, since those differ once a stylesheet has an
+ * opinion.
+ */
+/**
+ * Whether an element paints text of its own.
+ *
+ * Its own text nodes only, not its descendants'. A card wrapping a
+ * paragraph is a surface being looked at; the paragraph is the thing
+ * being read. Judging the card as text would compare its colour,
+ * which nothing there paints, against the wrong criterion.
+ */
+/**
+ * The element that paints this node.
+ *
+ * A `StaticText` target resolves to a DOM text node, which is the
+ * honest answer to what was named but has no style, no class list
+ * and no `getBoundingClientRect`. Anything that wants to read or
+ * change how the text is painted has to work on the element holding
+ * it. Without this, hiding a paragraph's text quietly did nothing
+ * and the contrast measurement concluded there was no text there.
+ */
+export declare const PAINTING_ELEMENT_PROBE = "function () {\n  return this.nodeType === 3 ? this.parentElement : this;\n}";
+export declare const OWN_TEXT_PROBE = "function () {\n  var kids = this.childNodes || [];\n  for (var i = 0; i < kids.length; i++) {\n    var node = kids[i];\n    if (node.nodeType === 3 && (node.textContent || \"\").trim()) return true;\n  }\n  return false;\n}";
+export declare const HIDE_TEXT = "function (hidden) {\n  var KEY = \"__piHiddenText\";\n  if (hidden) {\n    if (!this[KEY]) {\n      this[KEY] = {\n        color: this.style.getPropertyValue(\"color\"),\n        colorPriority: this.style.getPropertyPriority(\"color\"),\n        shadow: this.style.getPropertyValue(\"text-shadow\"),\n        shadowPriority: this.style.getPropertyPriority(\"text-shadow\")\n      };\n    }\n    this.style.setProperty(\"color\", \"transparent\", \"important\");\n    this.style.setProperty(\"text-shadow\", \"none\", \"important\");\n    return true;\n  }\n  var had = this[KEY];\n  if (!had) return false;\n  this.style.removeProperty(\"color\");\n  this.style.removeProperty(\"text-shadow\");\n  if (had.color) {\n    this.style.setProperty(\"color\", had.color, had.colorPriority);\n  }\n  if (had.shadow) {\n    this.style.setProperty(\"text-shadow\", had.shadow, had.shadowPriority);\n  }\n  delete this[KEY];\n  return true;\n}";
+/**
+ * Select everything in a text field, the way the field itself
+ * offers to.
+ *
+ * Runs with the element as its receiver. Used instead of a
+ * triple click so that clearing a field does not need an
+ * unobstructed centre, and instead of a select-all shortcut so
+ * there is no platform to guess at.
+ */
+export declare const SELECT_TEXT_PROBE = "function () {\n  if (typeof this.select === \"function\") {\n    this.select();\n    return true;\n  }\n  return false;\n}";
+/**
+ * What an element says, holds, and is tagged with.
+ *
+ * Runs with the element as its receiver. Text is trimmed and
+ * capped, because a container's textContent can be the whole
+ * page and the question being asked is almost always about a
+ * short piece of it. Only data attributes and a handful of
+ * state attributes are returned: the rest are either already in
+ * the accessibility tree or noise.
+ */
+export declare const CONTENT_PROBE = "function () {\n  var text = (this.textContent || \"\").replace(/\\s+/g, \" \").trim();\n  if (text.length > 400) text = text.slice(0, 400) + \"...\";\n  var attributes = [];\n  var names = this.getAttributeNames ? this.getAttributeNames() : [];\n  for (var at = 0; at < names.length; at++) {\n    var name = names[at];\n    if (name.indexOf(\"data-\") === 0 || name === \"disabled\" ||\n        name === \"readonly\" || name === \"open\" || name === \"hidden\" ||\n        name === \"contenteditable\" || name === \"autocomplete\" ||\n        name === \"inputmode\" || name === \"type\" || name === \"name\") {\n      attributes.push([name, this.getAttribute(name)]);\n    }\n  }\n  var held;\n  if (typeof this.value === \"string\") held = this.value;\n  return { text: text, value: held, attributes: attributes };\n}";
+/**
+ * What is painted over the element's own centre, if anything.
+ *
+ * The whole question is answered in the page, deliberately. It was
+ * once split: the centre came from the box model out here and the
+ * hit test from `DOM.getNodeForLocation` over there. Those two are
+ * not in the same coordinate space once the page has scrolled, and
+ * a scrolled page reported whatever happened to sit at the wrong
+ * point as an occluder. Every target the driver had to scroll to
+ * became unclickable, blamed on a paragraph elsewhere on the page.
+ * `getBoundingClientRect` and `elementFromPoint` are both viewport
+ * space by definition, so asking for both together is what makes
+ * the answer sound, not merely what makes it shorter.
+ *
+ * The hit is asked of the element's own root, not of the document.
+ * `document.elementFromPoint` retargets a hit inside a shadow tree
+ * to the host, so an element in a shadow root was reported as
+ * covered by the very host that contains it. A host that covers
+ * something else is still named as itself, which is the useful
+ * answer: the component is what is in the way.
+ *
+ * A point off the viewport reads as nothing here, where the
+ * protocol call answered with whatever node it found instead. That
+ * difference is the safety: an unanswerable question now returns no
+ * occluder rather than a confident wrong one.
+ *
+ * With `alsoCorners`, the corners are tried after the centre, which
+ * is what a full inspection wants: an element clipped at one edge
+ * is worth reporting even though a click at its middle would land.
+ * The readiness poll asks for the centre alone, since that is where
+ * a click is aimed and it runs on every pass.
+ */
+export declare const OCCLUDER_PROBE = "function (alsoCorners) {\n  var box = this.getBoundingClientRect();\n  if (!box.width || !box.height) return null;\n\n  var inset = 2;\n  var points = [[box.left + box.width / 2, box.top + box.height / 2]];\n  if (alsoCorners) {\n    points.push([box.left + inset, box.top + inset]);\n    points.push([box.right - inset, box.top + inset]);\n    points.push([box.left + inset, box.bottom - inset]);\n    points.push([box.right - inset, box.bottom - inset]);\n  }\n\n  var root = this.getRootNode();\n  var from = root.elementFromPoint ? root : document;\n  for (var at = 0; at < points.length; at++) {\n    var x = points[at][0];\n    var y = points[at][1];\n    var hit = from.elementFromPoint(x, y);\n    if (!hit || hit === this || this.contains(hit)) continue;\n    var described = hit.nodeName.toLowerCase();\n    if (hit.id) described += \" id=\" + hit.id;\n    else if (hit.classList && hit.classList.length) {\n      described += \" class=\" + hit.classList[0];\n    }\n    return described;\n  }\n  return null;\n}";

package/dist/web/element/probes.js

@@ -0,0 +1,195 @@
+/**
+ * Asking the browser about one element.
+ *
+ * Page sources rather than functions, for the same reason the
+ * accessibility observer is: the compiler wraps named inner
+ * bindings in a __name helper the page has never heard of, so
+ * a serialized function that declares helpers of its own
+ * throws on arrival.
+ */
+/**
+ * Who receives a click at a point, when it is not the element
+ * being asked about.
+ *
+ * Runs with the element as its receiver and the hit node as its
+ * only argument. Anything the element contains counts as
+ * itself, since a click there still reaches it. Returns a short
+ * description of the obstruction, or null when there is none.
+ */
+/**
+ * Stop an element's own text from painting, and put it back.
+ *
+ * Runs with the element as its receiver. Only colour and shadow are
+ * touched, because neither affects layout: the glyphs still occupy
+ * the same pixels and simply leave no mark, which is what lets two
+ * shots of the same region be subtracted from one another.
+ *
+ * The element's own inline values are remembered on the node itself
+ * rather than in the caller, so a restore still works if the caller
+ * lost track of what it changed. An element with no inline colour of
+ * its own is restored by removing the property, not by writing an
+ * empty string over it, since those differ once a stylesheet has an
+ * opinion.
+ */
+/**
+ * Whether an element paints text of its own.
+ *
+ * Its own text nodes only, not its descendants'. A card wrapping a
+ * paragraph is a surface being looked at; the paragraph is the thing
+ * being read. Judging the card as text would compare its colour,
+ * which nothing there paints, against the wrong criterion.
+ */
+/**
+ * The element that paints this node.
+ *
+ * A `StaticText` target resolves to a DOM text node, which is the
+ * honest answer to what was named but has no style, no class list
+ * and no `getBoundingClientRect`. Anything that wants to read or
+ * change how the text is painted has to work on the element holding
+ * it. Without this, hiding a paragraph's text quietly did nothing
+ * and the contrast measurement concluded there was no text there.
+ */
+export const PAINTING_ELEMENT_PROBE = `function () {
+  return this.nodeType === 3 ? this.parentElement : this;
+}`;
+export const OWN_TEXT_PROBE = `function () {
+  var kids = this.childNodes || [];
+  for (var i = 0; i < kids.length; i++) {
+    var node = kids[i];
+    if (node.nodeType === 3 && (node.textContent || "").trim()) return true;
+  }
+  return false;
+}`;
+export const HIDE_TEXT = `function (hidden) {
+  var KEY = "__piHiddenText";
+  if (hidden) {
+    if (!this[KEY]) {
+      this[KEY] = {
+        color: this.style.getPropertyValue("color"),
+        colorPriority: this.style.getPropertyPriority("color"),
+        shadow: this.style.getPropertyValue("text-shadow"),
+        shadowPriority: this.style.getPropertyPriority("text-shadow")
+      };
+    }
+    this.style.setProperty("color", "transparent", "important");
+    this.style.setProperty("text-shadow", "none", "important");
+    return true;
+  }
+  var had = this[KEY];
+  if (!had) return false;
+  this.style.removeProperty("color");
+  this.style.removeProperty("text-shadow");
+  if (had.color) {
+    this.style.setProperty("color", had.color, had.colorPriority);
+  }
+  if (had.shadow) {
+    this.style.setProperty("text-shadow", had.shadow, had.shadowPriority);
+  }
+  delete this[KEY];
+  return true;
+}`;
+/**
+ * Select everything in a text field, the way the field itself
+ * offers to.
+ *
+ * Runs with the element as its receiver. Used instead of a
+ * triple click so that clearing a field does not need an
+ * unobstructed centre, and instead of a select-all shortcut so
+ * there is no platform to guess at.
+ */
+export const SELECT_TEXT_PROBE = `function () {
+  if (typeof this.select === "function") {
+    this.select();
+    return true;
+  }
+  return false;
+}`;
+/**
+ * What an element says, holds, and is tagged with.
+ *
+ * Runs with the element as its receiver. Text is trimmed and
+ * capped, because a container's textContent can be the whole
+ * page and the question being asked is almost always about a
+ * short piece of it. Only data attributes and a handful of
+ * state attributes are returned: the rest are either already in
+ * the accessibility tree or noise.
+ */
+export const CONTENT_PROBE = `function () {
+  var text = (this.textContent || "").replace(/\\s+/g, " ").trim();
+  if (text.length > 400) text = text.slice(0, 400) + "...";
+  var attributes = [];
+  var names = this.getAttributeNames ? this.getAttributeNames() : [];
+  for (var at = 0; at < names.length; at++) {
+    var name = names[at];
+    if (name.indexOf("data-") === 0 || name === "disabled" ||
+        name === "readonly" || name === "open" || name === "hidden" ||
+        name === "contenteditable" || name === "autocomplete" ||
+        name === "inputmode" || name === "type" || name === "name") {
+      attributes.push([name, this.getAttribute(name)]);
+    }
+  }
+  var held;
+  if (typeof this.value === "string") held = this.value;
+  return { text: text, value: held, attributes: attributes };
+}`;
+/**
+ * What is painted over the element's own centre, if anything.
+ *
+ * The whole question is answered in the page, deliberately. It was
+ * once split: the centre came from the box model out here and the
+ * hit test from `DOM.getNodeForLocation` over there. Those two are
+ * not in the same coordinate space once the page has scrolled, and
+ * a scrolled page reported whatever happened to sit at the wrong
+ * point as an occluder. Every target the driver had to scroll to
+ * became unclickable, blamed on a paragraph elsewhere on the page.
+ * `getBoundingClientRect` and `elementFromPoint` are both viewport
+ * space by definition, so asking for both together is what makes
+ * the answer sound, not merely what makes it shorter.
+ *
+ * The hit is asked of the element's own root, not of the document.
+ * `document.elementFromPoint` retargets a hit inside a shadow tree
+ * to the host, so an element in a shadow root was reported as
+ * covered by the very host that contains it. A host that covers
+ * something else is still named as itself, which is the useful
+ * answer: the component is what is in the way.
+ *
+ * A point off the viewport reads as nothing here, where the
+ * protocol call answered with whatever node it found instead. That
+ * difference is the safety: an unanswerable question now returns no
+ * occluder rather than a confident wrong one.
+ *
+ * With `alsoCorners`, the corners are tried after the centre, which
+ * is what a full inspection wants: an element clipped at one edge
+ * is worth reporting even though a click at its middle would land.
+ * The readiness poll asks for the centre alone, since that is where
+ * a click is aimed and it runs on every pass.
+ */
+export const OCCLUDER_PROBE = `function (alsoCorners) {
+  var box = this.getBoundingClientRect();
+  if (!box.width || !box.height) return null;
+
+  var inset = 2;
+  var points = [[box.left + box.width / 2, box.top + box.height / 2]];
+  if (alsoCorners) {
+    points.push([box.left + inset, box.top + inset]);
+    points.push([box.right - inset, box.top + inset]);
+    points.push([box.left + inset, box.bottom - inset]);
+    points.push([box.right - inset, box.bottom - inset]);
+  }
+
+  var root = this.getRootNode();
+  var from = root.elementFromPoint ? root : document;
+  for (var at = 0; at < points.length; at++) {
+    var x = points[at][0];
+    var y = points[at][1];
+    var hit = from.elementFromPoint(x, y);
+    if (!hit || hit === this || this.contains(hit)) continue;
+    var described = hit.nodeName.toLowerCase();
+    if (hit.id) described += " id=" + hit.id;
+    else if (hit.classList && hit.classList.length) {
+      described += " class=" + hit.classList[0];
+    }
+    return described;
+  }
+  return null;
+}`;

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

@@ -0,0 +1,51 @@
+/**
+ * How an element looks in states a person has to reach for.
+ *
+ * Hover, focus and active styles are invisible to a static
+ * reading, and they are where accessibility problems hide: a
+ * focus ring that never appears, a hover state that is the only
+ * cue a thing is interactive. The browser can be told to hold a
+ * state, which is the only way to read one without a mouse.
+ */
+import type { StyleEntry, StyleGroup } from "../styles/index.js";
+/** A state the browser can be asked to hold. */
+export type PseudoState = "hover" | "focus" | "active" | "focus-visible";
+/** What changed about an element while a state was held. */
+export interface PseudoVariant {
+    readonly state: PseudoState;
+    readonly changes: readonly StyleChange[];
+}
+/** One property that differs between two readings. */
+export interface StyleChange {
+    readonly property: string;
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * What a state changed.
+ *
+ * Only differences are reported. Repeating everything that
+ * stayed the same would bury the two lines that answer whether
+ * the state is visible at all.
+ */
+export declare function diffStyles(atRest: readonly StyleGroup[], held: readonly StyleGroup[]): readonly StyleChange[];
+/** Say what each held state changed. */
+export declare function renderVariants(variants: readonly PseudoVariant[]): string;
+/** An entry list as a group, for callers holding a flat read. */
+export declare function asGroup(name: string, entries: readonly StyleEntry[]): StyleGroup;
+/**
+ * Wait until the element has stopped moving.
+ *
+ * Forcing a state starts whatever transition the page declared,
+ * and reading the styles immediately catches them at their
+ * resting values, which reports that nothing changed. Rather
+ * than guessing a delay from the declared durations, this waits
+ * on the browser's own promise that each animation has
+ * finished. Endless animations are skipped, since waiting for
+ * one would never return, and a cap keeps a page that keeps
+ * starting new work from holding the read open.
+ *
+ * Runs with the element as its receiver, and resolves rather
+ * than rejecting so a caller always gets its reading.
+ */
+export declare const SETTLE_PROBE = "function (capMs) {\n  if (!this.getAnimations) return Promise.resolve(false);\n  var running = this.getAnimations().filter(function (animation) {\n    var timing = animation.effect && animation.effect.getTiming\n      ? animation.effect.getTiming()\n      : {};\n    return Number.isFinite(timing.iterations);\n  });\n  if (running.length === 0) return Promise.resolve(true);\n  var settled = Promise.all(running.map(function (animation) {\n    return animation.finished.catch(function () { return null; });\n  }));\n  var capped = new Promise(function (resolve) {\n    setTimeout(function () { resolve(false); }, capMs);\n  });\n  return Promise.race([settled.then(function () { return true; }), capped]);\n}";

package/dist/web/element/pseudo.js

@@ -0,0 +1,96 @@
+/**
+ * How an element looks in states a person has to reach for.
+ *
+ * Hover, focus and active styles are invisible to a static
+ * reading, and they are where accessibility problems hide: a
+ * focus ring that never appears, a hover state that is the only
+ * cue a thing is interactive. The browser can be told to hold a
+ * state, which is the only way to read one without a mouse.
+ */
+/** Flatten grouped styles into one lookup. */
+function flatten(groups) {
+    const flat = new Map();
+    for (const group of groups) {
+        for (const entry of group.entries)
+            flat.set(entry.property, entry.value);
+    }
+    return flat;
+}
+/**
+ * What a state changed.
+ *
+ * Only differences are reported. Repeating everything that
+ * stayed the same would bury the two lines that answer whether
+ * the state is visible at all.
+ */
+export function diffStyles(atRest, held) {
+    const before = flatten(atRest);
+    const after = flatten(held);
+    const changes = [];
+    for (const [property, to] of after) {
+        const from = before.get(property);
+        if (from !== to) {
+            changes.push({ property, from: from ?? "not set", to });
+        }
+    }
+    // A property present at rest and gone while held changed too,
+    // and it is the shape a disappearing outline takes.
+    for (const [property, from] of before) {
+        if (!after.has(property)) {
+            changes.push({ property, from, to: "not set" });
+        }
+    }
+    return changes;
+}
+/** Say what each held state changed. */
+export function renderVariants(variants) {
+    if (variants.length === 0)
+        return "";
+    return variants
+        .map((variant) => {
+        if (variant.changes.length === 0) {
+            return `${variant.state}: nothing changes`;
+        }
+        return [
+            `${variant.state}:`,
+            ...variant.changes.map((change) => `  ${change.property}: ${change.from} -> ${change.to}`),
+        ].join("\n");
+    })
+        .join("\n");
+}
+/** An entry list as a group, for callers holding a flat read. */
+export function asGroup(name, entries) {
+    return { name, entries };
+}
+/**
+ * Wait until the element has stopped moving.
+ *
+ * Forcing a state starts whatever transition the page declared,
+ * and reading the styles immediately catches them at their
+ * resting values, which reports that nothing changed. Rather
+ * than guessing a delay from the declared durations, this waits
+ * on the browser's own promise that each animation has
+ * finished. Endless animations are skipped, since waiting for
+ * one would never return, and a cap keeps a page that keeps
+ * starting new work from holding the read open.
+ *
+ * Runs with the element as its receiver, and resolves rather
+ * than rejecting so a caller always gets its reading.
+ */
+export const SETTLE_PROBE = `function (capMs) {
+  if (!this.getAnimations) return Promise.resolve(false);
+  var running = this.getAnimations().filter(function (animation) {
+    var timing = animation.effect && animation.effect.getTiming
+      ? animation.effect.getTiming()
+      : {};
+    return Number.isFinite(timing.iterations);
+  });
+  if (running.length === 0) return Promise.resolve(true);
+  var settled = Promise.all(running.map(function (animation) {
+    return animation.finished.catch(function () { return null; });
+  }));
+  var capped = new Promise(function (resolve) {
+    setTimeout(function () { resolve(false); }, capMs);
+  });
+  return Promise.race([settled.then(function () { return true; }), capped]);
+}`;

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

@@ -0,0 +1,30 @@
+/**
+ * Laying out what was found about one element.
+ *
+ * Kept apart from the judging so the two have separate reasons
+ * to change: what is true about an element and how it reads are
+ * different questions.
+ */
+import type { PropertyTrace, StyleGroup } from "../styles/index.js";
+import type { BoxModel } from "./box.js";
+import type { VisibilityVerdict } from "./visibility.js";
+/** The verdict, as a sentence. */
+export declare function renderVisibility(verdict: VisibilityVerdict): string;
+/**
+ * The boxes, innermost outwards, with the offsets between them
+ * stated only where they exist. Four zeroes for the margin of
+ * an element with no margin is noise.
+ *
+ * The position says which space it is measured in. These numbers
+ * come from the box model, which measures from the viewport, while
+ * a page query reports the same element measured down the document.
+ * On a scrolled page the two differ by however far it has moved,
+ * and an unlabelled pair of numbers invites reading one as the
+ * other: that confusion hid a real defect for hours, because every
+ * reading was true in its own frame and none were comparable.
+ */
+export declare function renderBox(box: BoxModel): string;
+/** Curated styles, grouped as they were curated. */
+export declare function renderStyles(groups: readonly StyleGroup[]): string;
+/** Everything that had a say in one property, strongest first. */
+export declare function renderTrace(trace: PropertyTrace): string;