automatica11y 0.0.0-stage → 0.3.0

package/src/tiers/interactions/archetypes.js

@@ -0,0 +1,417 @@
+/**
+ * The interaction checks, one table per archetype. A check is a name, the WCAG criteria it speaks to,
+ * and a function that gets a context (`ctx`) and returns pass, fail, or not-applicable with a detail.
+ * The runner in index.js owns everything else: fresh page for each check, timeouts, and errors.
+ * Checks only use the two hooks (`data-a11y-trigger`, `data-a11y-root`) and ARIA roles.
+ */
+
+const pass = (detail, extra = {}) => ({ result: "pass", detail, ...extra });
+const fail = (detail, extra = {}) => ({ result: "fail", detail, ...extra });
+const na = (detail) => ({ result: "not-applicable", detail });
+
+const where = (s) => (s.bodyActive ? "nothing (the page body)" : `${s.activeTag}${s.activeText ? ` "${s.activeText}"` : ""}`);
+const quote = (list) => list.map((item) => `"${item}"`).join(", ");
+
+// ---- Shared by every archetype ----
+
+const COMMON = [
+  {
+    name: "trigger-reachable-by-tab",
+    criteria: ["2.1.1"],
+    async run(ctx) {
+      const presses = await ctx.tabToTrigger();
+      return presses === null ? fail("Pressing Tab 12 times never put focus on the trigger.") : pass(`Tab reached the trigger after ${presses} ${presses === 1 ? "press" : "presses"}.`);
+    },
+  },
+  {
+    name: "focus-indicator-visible",
+    criteria: ["2.4.7"],
+    async run(ctx) {
+      if ((await ctx.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so its focus indicator wasn't checked.");
+      const focused = await ctx.page.evaluate(() => window.__a11y.focusStyle());
+      await ctx.page.evaluate(() => window.__a11y.remember());
+      const clip = ctx.clipAround(focused.box);
+      const shotFocused = await ctx.page.screenshot({ clip });
+      await ctx.page.evaluate(() => /** @type {any} */ (window).__a11yLast?.blur());
+      await ctx.settle();
+      const unfocused = await ctx.page.evaluate(() => window.__a11y.lastStyle());
+      const changed = Object.keys(focused.style).filter((key) => focused.style[key] !== unfocused?.[key]);
+      if (changed.length) return pass(`Computed style changed on focus: ${changed.join(", ")}.`, { method: "computed-style" });
+      const shotBlurred = await ctx.page.screenshot({ clip });
+      if (!shotFocused.equals(shotBlurred)) return pass("The pixels around the trigger changed on focus, though no style property did.", { method: "screenshot" });
+      return fail("Nothing visible changed when the trigger got keyboard focus. Checked computed styles first, then a screenshot comparison.", { method: "screenshot" });
+    },
+  },
+  {
+    name: "no-focus-trap",
+    criteria: ["2.1.2"],
+    async run(ctx) {
+      if ((await ctx.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so focus-trap behavior wasn't checked.");
+      for (let press = 1; press <= 12; press += 1) {
+        await ctx.press("Tab");
+        const s = await ctx.snap();
+        if (!s.activeIsTrigger) return pass(`Focus moved on after ${press} more Tab ${press === 1 ? "press" : "presses"}.`);
+      }
+      return fail("Focus stayed on the trigger through 12 more Tab presses.");
+    },
+  },
+];
+
+// ---- button and link ----
+
+const activates = (key, label) => async (ctx) => {
+  const s0 = await ctx.snap();
+  if (key === "Space" && (s0.triggerTag === "a" || s0.triggerRole === "link")) return na("Links activate with Enter only.");
+  await ctx.focus();
+  await ctx.press(key);
+  const s1 = await ctx.snap();
+  return s1.clicks > s0.clicks ? pass(`${label} activated the trigger.`) : fail(`${label} did not activate the trigger.`);
+};
+
+// ---- dialog and menu ----
+
+/** Open with the keyboard and wait for the root to show. Returns the snapshot, or null. */
+async function openWith(ctx, key = "Enter") {
+  await ctx.focus();
+  await ctx.press(key);
+  return ctx.waitFor((s) => s.rootVisible || s.expanded === "true");
+}
+
+async function openMenu(ctx) {
+  for (const key of ["Enter", "ArrowDown"]) {
+    const s = await openWith(ctx, key);
+    if (s) return { s, key };
+  }
+  return null;
+}
+
+// ---- The tables ----
+
+export const ARCHETYPE_CHECKS = {
+  button: [
+    { name: "enter-activates", criteria: ["2.1.1"], run: activates("Enter", "Enter") },
+    { name: "space-activates", criteria: ["2.1.1"], run: activates("Space", "Space") },
+  ],
+
+  link: [
+    { name: "enter-activates", criteria: ["2.1.1"], run: activates("Enter", "Enter") },
+    { name: "space-activates", criteria: ["2.1.1"], run: activates("Space", "Space") },
+  ],
+
+  dialog: [
+    {
+      name: "focus-moves-into-dialog",
+      criteria: ["2.4.3"],
+      async run(ctx) {
+        if (!(await openWith(ctx))) return fail("The dialog didn't open when Enter was pressed on the trigger.");
+        const s = await ctx.waitFor((x) => x.activeInRoot, 800);
+        if (s) return pass("Focus moved into the dialog when it opened.");
+        return fail(`Focus stayed outside the dialog, on ${where(await ctx.snap())}.`);
+      },
+    },
+    {
+      name: "tab-stays-inside-dialog",
+      criteria: ["2.4.3", "2.1.2"],
+      async run(ctx) {
+        if (!(await openWith(ctx))) return na("The dialog didn't open with the keyboard, so Tab behavior wasn't checked.");
+        await ctx.waitFor((x) => x.activeInRoot, 600);
+        for (let press = 1; press <= 8; press += 1) {
+          await ctx.press("Tab");
+          const s = await ctx.snap();
+          if (!s.activeInRoot) {
+            const detail = `Focus left the dialog after ${press} Tab ${press === 1 ? "press" : "presses"}, onto ${where(s)}.`;
+            return s.rootModal ? fail(detail) : na(`${detail} The dialog isn't marked aria-modal, so it counts as non-modal and the check doesn't apply.`);
+          }
+        }
+        return pass("Focus stayed inside the dialog through 8 Tab presses.");
+      },
+    },
+    {
+      name: "escape-closes",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        if (!(await openWith(ctx))) return na("The dialog didn't open with the keyboard, so Escape wasn't checked.");
+        await ctx.waitFor((x) => x.activeInRoot, 600);
+        await ctx.press("Escape");
+        const closed = await ctx.waitFor((x) => !x.rootVisible && x.expanded !== "true", 800);
+        return closed ? pass("Escape closed the dialog.") : fail("The dialog stayed open after Escape.");
+      },
+    },
+    {
+      name: "focus-returns-to-trigger",
+      criteria: ["2.4.3"],
+      async run(ctx) {
+        if (!(await openWith(ctx))) return na("The dialog didn't open with the keyboard, so focus return wasn't checked.");
+        await ctx.waitFor((x) => x.activeInRoot, 600);
+        await ctx.press("Escape");
+        if (!(await ctx.waitFor((x) => !x.rootVisible && x.expanded !== "true", 800))) return na("Escape didn't close the dialog, so focus return wasn't checked.");
+        const back = await ctx.waitFor((x) => x.activeIsTrigger, 800);
+        return back ? pass("Focus returned to the trigger.") : fail(`Focus went to ${where(await ctx.snap())} instead of the trigger.`);
+      },
+    },
+  ],
+
+  menu: [
+    {
+      name: "opens-with-enter-or-arrow",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        const opened = await openMenu(ctx);
+        return opened ? pass(`${opened.key} opened the menu.`) : fail("Neither Enter nor ArrowDown opened the menu.");
+      },
+    },
+    {
+      name: "arrow-keys-move-between-items",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        if (!(await openMenu(ctx))) return na("The menu didn't open with the keyboard, so item navigation wasn't checked.");
+        await ctx.settle(120);
+        const items = (await ctx.items('[role^="menuitem"]')).filter((i) => i.visible);
+        if (items.length < 2) return na(`The menu has ${items.length} visible menu ${items.length === 1 ? "item" : "items"}, so there is nothing to move between.`);
+        const start = items.find((i) => i.active)?.uid ?? null;
+        await ctx.press("ArrowDown");
+        const afterDown = (await ctx.items('[role^="menuitem"]')).find((i) => i.active)?.uid ?? null;
+        if (afterDown === null || afterDown === start) return fail("ArrowDown didn't move to another menu item.");
+        await ctx.press("ArrowUp");
+        const afterUp = (await ctx.items('[role^="menuitem"]')).find((i) => i.active)?.uid ?? null;
+        return afterUp === start || (start === null && afterUp !== afterDown) ? pass("ArrowDown and ArrowUp moved between menu items.") : fail("ArrowUp didn't move back to the previous menu item.");
+      },
+    },
+    {
+      name: "escape-closes-and-returns-focus",
+      criteria: ["2.1.1", "2.4.3"],
+      async run(ctx) {
+        if (!(await openMenu(ctx))) return na("The menu didn't open with the keyboard, so Escape wasn't checked.");
+        await ctx.settle(120);
+        await ctx.press("Escape");
+        if (!(await ctx.waitFor((x) => !x.rootVisible && x.expanded !== "true", 800))) return fail("The menu stayed open after Escape.");
+        const back = await ctx.waitFor((x) => x.activeIsTrigger, 800);
+        return back ? pass("Escape closed the menu and focus returned to the trigger.") : fail(`Escape closed the menu, but focus went to ${where(await ctx.snap())} instead of the trigger.`);
+      },
+    },
+  ],
+
+  tabs: [
+    {
+      name: "arrow-keys-move-between-tabs",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        const tabs = (await ctx.items('[role="tab"]')).filter((t) => t.visible);
+        if (tabs.length === 0) return fail("The fixture has no elements with role=tab.");
+        if (tabs.length < 2) return na("There is only one tab, so there is nothing to move between.");
+        await ctx.focus();
+        const vertical = await ctx.page.evaluate(() => window.__a11y.queryDeep('[role="tablist"]')?.getAttribute("aria-orientation") === "vertical");
+        const [next, prev] = vertical ? ["ArrowDown", "ArrowUp"] : ["ArrowRight", "ArrowLeft"];
+        const active = async () => (await ctx.items('[role="tab"]')).find((t) => t.active)?.uid ?? null;
+        const start = await active();
+        await ctx.press(next);
+        const afterNext = await active();
+        if (afterNext === null || afterNext === start) return fail(`${next} didn't move focus to another tab.`);
+        await ctx.press(prev);
+        return (await active()) === start ? pass(`${next} and ${prev} moved focus between tabs.`) : fail(`${prev} didn't move focus back to the previous tab.`);
+      },
+    },
+    {
+      name: "home-and-end-work",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        const tabs = (await ctx.items('[role="tab"]')).filter((t) => t.visible);
+        if (tabs.length < 2) return na("There are fewer than two tabs, so Home and End wouldn't show anything.");
+        await ctx.focus();
+        const activeIndex = async () => (await ctx.items('[role="tab"]')).filter((t) => t.visible).findIndex((t) => t.active);
+        await ctx.press("End");
+        const end = await activeIndex();
+        await ctx.press("Home");
+        const home = await activeIndex();
+        const problems = [];
+        if (end !== tabs.length - 1) problems.push("End didn't move to the last tab");
+        if (home !== 0) problems.push("Home didn't move to the first tab");
+        return problems.length ? fail(`${problems.join(". ")}.`) : pass("Home moved to the first tab and End to the last.");
+      },
+    },
+    {
+      name: "selected-state-exposed",
+      criteria: ["4.1.2"],
+      async run(ctx) {
+        const tabs = await ctx.items('[role="tab"]');
+        if (tabs.length === 0) return fail("The fixture has no elements with role=tab.");
+        const missing = tabs.filter((t) => !t.hasSelected).length;
+        const selected = tabs.filter((t) => t.selected).length;
+        if (missing) return fail(`${missing} of ${tabs.length} tabs have no aria-selected attribute.`);
+        return selected === 1 ? pass("Every tab has aria-selected, and exactly one is true.") : fail(`${selected} tabs are aria-selected="true". A tab list should have exactly one.`);
+      },
+    },
+  ],
+
+  combobox: [
+    {
+      name: "arrow-down-opens-list",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        return (await ctx.openCombo()) ? pass("ArrowDown opened the list.") : fail("ArrowDown didn't open the list.");
+      },
+    },
+    {
+      name: "arrow-keys-change-active-option",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        if (!(await ctx.openCombo())) return na("The list didn't open with ArrowDown, so option navigation wasn't checked.");
+        const options = (await ctx.items('[role="option"]')).filter((o) => o.visible);
+        if (options.length < 2) return na("The list has fewer than two visible options.");
+        const active = async () => (await ctx.items('[role="option"]')).find((o) => o.active)?.uid ?? null;
+        const start = await active();
+        await ctx.press("ArrowDown");
+        const afterDown = await active();
+        if (afterDown === null || afterDown === start) return fail("ArrowDown didn't change the active option.");
+        await ctx.press("ArrowUp");
+        return (await active()) === start || (await active()) !== afterDown ? pass("ArrowDown and ArrowUp changed the active option.") : fail("ArrowUp didn't change the active option.");
+      },
+    },
+    {
+      name: "enter-selects",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        if (!(await ctx.openCombo())) return na("The list didn't open with ArrowDown, so selection wasn't checked.");
+        const before = await ctx.page.evaluate(() => window.__a11y.inputValue());
+        await ctx.press("ArrowDown");
+        await ctx.press("Enter");
+        const closed = await ctx.waitFor((x) => x.expanded !== "true", 800);
+        const after = await ctx.page.evaluate(() => window.__a11y.inputValue());
+        const selected = (await ctx.items('[role="option"]')).some((o) => o.selected);
+        if (!closed) return fail("The list stayed open after Enter.");
+        return after !== before || selected ? pass("Enter chose an option and closed the list.") : fail("Enter closed the list, but nothing was chosen: the value didn't change and no option is selected.");
+      },
+    },
+    {
+      name: "escape-closes",
+      criteria: ["2.1.1"],
+      async run(ctx) {
+        if (!(await ctx.openCombo())) return na("The list didn't open with ArrowDown, so Escape wasn't checked.");
+        await ctx.press("Escape");
+        return (await ctx.waitFor((x) => x.expanded !== "true", 800)) ? pass("Escape closed the list.") : fail("The list stayed open after Escape.");
+      },
+    },
+  ],
+
+  "form-field": [
+    {
+      name: "label-associated",
+      criteria: ["1.3.1", "3.3.2", "4.1.2"],
+      async run(ctx) {
+        const sources = await ctx.page.evaluate(() => window.__a11y.nameSources());
+        if (!sources) return fail("The fixture has no data-a11y-trigger control.");
+        return sources.length ? pass(`The control has a name from: ${sources.join(", ")}.`) : fail("The control has no label element, aria-labelledby, aria-label, or title.");
+      },
+    },
+    {
+      name: "error-associated-on-invalid",
+      criteria: ["3.3.1", "4.1.3"],
+      async run(ctx) {
+        const facts = await ctx.page.evaluate(() => {
+          const c = window.__a11y.queryDeep("[data-a11y-trigger]");
+          return { tag: c?.localName, type: c?.getAttribute("type") ?? "text", required: c?.hasAttribute("required"), pattern: c?.hasAttribute("pattern"), minlength: c?.hasAttribute("minlength"), valid: c?.checkValidity?.() ?? true };
+        });
+        const control = ctx.trigger;
+        const before = await ctx.page.evaluate(() => window.__a11y.errorInfo());
+        try {
+          if (facts.required) await control.fill("");
+          else if (facts.pattern || facts.minlength || ["email", "url", "tel"].includes(facts.type) || facts.tag === "input") await control.fill("x");
+          else return na("The control has no validation to trigger. Add required, a type such as email, or a pattern to the fixture.");
+        } catch {
+          return na("The control couldn't be filled, so invalid input wasn't tried.");
+        }
+        await ctx.press("Tab");
+        await ctx.settle(200);
+        /** Error text that wasn't there before the input went wrong. A hint linked all along doesn't count. */
+        const read = async () => {
+          const now = await ctx.page.evaluate(() => window.__a11y.errorInfo());
+          return { ...now, linked: now.linked.filter((t) => !before.linked.includes(t)), live: now.live.filter((t) => !before.live.includes(t)) };
+        };
+        let info = await read();
+        if (!info.invalid && !info.linked.length && !info.live.length) {
+          // Some fields only validate on submit.
+          await ctx.trigger.press("Enter").catch(() => {});
+          await ctx.settle(200);
+          info = await read();
+        }
+        if (!info.invalid && !info.linked.length && !info.live.length) return na("Invalid input didn't put the field in an invalid state, so there was no error to check.");
+        if (info.linked.length || info.live.length) {
+          const how = [info.linked.length ? `linked by aria-describedby or aria-errormessage: ${quote(info.linked)}` : null, info.live.length ? `in an alert or live region: ${quote(info.live)}` : null].filter(Boolean).join("; ");
+          return pass(`The error is ${how}.${info.ariaInvalid ? "" : " The field doesn't set aria-invalid."}`);
+        }
+        return fail("The field is invalid, but no error text is tied to it through aria-describedby or aria-errormessage, and no alert or live region shows one. If the field relies on the browser's built-in message, this check can't see it.");
+      },
+    },
+  ],
+
+  accordion: [
+    {
+      name: "expanded-state-exposed",
+      criteria: ["4.1.2"],
+      async run(ctx) {
+        const s = await ctx.snap();
+        return s.expanded === null ? fail("The trigger has no aria-expanded attribute, so the expanded state isn't exposed.") : pass(`The trigger exposes aria-expanded="${s.expanded}".`);
+      },
+    },
+    { name: "enter-toggles", criteria: ["2.1.1", "4.1.2"], run: toggles("Enter") },
+    { name: "space-toggles", criteria: ["2.1.1", "4.1.2"], run: toggles("Space") },
+  ],
+
+  tooltip: [
+    {
+      name: "appears-on-focus",
+      criteria: ["1.4.13"],
+      async run(ctx) {
+        if ((await ctx.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so focus behavior wasn't checked.");
+        return (await ctx.waitFor((s) => s.rootVisible, 1000)) ? pass("The tooltip appeared when the trigger got keyboard focus.") : fail("The tooltip didn't appear when the trigger got keyboard focus.");
+      },
+    },
+    {
+      name: "escape-dismisses",
+      criteria: ["1.4.13"],
+      async run(ctx) {
+        if ((await ctx.tabToTrigger()) === null) return na("The trigger can't be reached with Tab, so Escape wasn't checked.");
+        if (!(await ctx.waitFor((s) => s.rootVisible, 1000))) return na("The tooltip didn't appear on focus, so there was nothing to dismiss.");
+        await ctx.press("Escape");
+        return (await ctx.waitFor((s) => !s.rootVisible, 800)) ? pass("Escape dismissed the tooltip.") : fail("The tooltip stayed visible after Escape.");
+      },
+    },
+    {
+      name: "content-reachable-on-hover",
+      criteria: ["1.4.13"],
+      async run(ctx) {
+        await ctx.trigger.hover();
+        if (!(await ctx.waitFor((s) => s.rootVisible, 1000))) return na("The tooltip didn't appear on hover, so hoverable content wasn't checked.");
+        const root = ctx.page.locator("[data-a11y-root]").first();
+        const box = await root.boundingBox();
+        if (!box) return na("The tooltip has no box to move onto.");
+        await ctx.page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 8 });
+        await ctx.settle(400);
+        return (await ctx.snap()).rootVisible ? pass("The tooltip stayed visible when the pointer moved onto it.") : fail("The tooltip disappeared when the pointer moved from the trigger onto it. Content shown on hover must stay reachable.");
+      },
+    },
+  ],
+};
+
+/** An accordion toggle check for one key. The state flips on the first press and flips back on the second. */
+function toggles(key) {
+  return async (ctx) => {
+    const read = async () => {
+      const s = await ctx.snap();
+      return { expanded: s.expanded, shown: s.rootVisible };
+    };
+    const before = await read();
+    await ctx.focus();
+    await ctx.press(key);
+    await ctx.settle(150);
+    const after = await read();
+    const changed = (a, b) => (a.expanded !== null ? a.expanded !== b.expanded : a.shown !== b.shown);
+    if (!changed(before, after)) return fail(`${key} didn't toggle the section.`);
+    await ctx.press(key);
+    await ctx.settle(150);
+    const again = await read();
+    return changed(after, again) ? pass(`${key} expanded and collapsed the section (aria-expanded ${before.expanded} then ${after.expanded}).`) : fail(`${key} opened the section but didn't close it again.`);
+  };
+}
+
+export { COMMON };

package/src/tiers/interactions/helpers.js

@@ -0,0 +1,145 @@
+/**
+ * Runs inside the page before any page script. It sets `window.__a11y`, a small kit the interaction checks use.
+ * It reaches through open shadow roots, because fixtures often put the trigger or the options there.
+ * This function is serialized and sent to the browser, so it can't use anything from outside itself.
+ */
+export function installHelpers() {
+  let uidCounter = 0;
+  const uids = new WeakMap();
+  const uid = (el) => {
+    if (!el) return null;
+    if (!uids.has(el)) uids.set(el, (uidCounter += 1));
+    return uids.get(el);
+  };
+
+  /** All matches in the document and in every open shadow root. */
+  const queryAllDeep = (selector, root = /** @type {Document | ShadowRoot} */ (document)) => {
+    const found = [...root.querySelectorAll(selector)];
+    for (const el of root.querySelectorAll("*")) if (el.shadowRoot) found.push(...queryAllDeep(selector, el.shadowRoot));
+    return found;
+  };
+  const queryDeep = (selector) => queryAllDeep(selector)[0] ?? null;
+
+  const deepActive = () => {
+    let active = document.activeElement;
+    while (active && active.shadowRoot && active.shadowRoot.activeElement) active = active.shadowRoot.activeElement;
+    return active;
+  };
+  /** True when `node` is `root` or sits inside it, across shadow boundaries. */
+  const within = (root, node) => {
+    while (node) {
+      if (node === root) return true;
+      node = node.assignedSlot || node.parentNode || node.host;
+    }
+    return false;
+  };
+  const visible = (el) => {
+    if (!el || el.getClientRects().length === 0) return false;
+    const style = getComputedStyle(el);
+    return style.visibility !== "hidden" && style.display !== "none";
+  };
+  const byId = (el, id) => (el.getRootNode().getElementById ? el.getRootNode().getElementById(id) : document.getElementById(id));
+  const text = (el) => (el?.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 80);
+
+  /** The element ARIA says is active: the focused element, or the descendant it points to. */
+  const activeTarget = () => {
+    const active = deepActive();
+    if (!active) return null;
+    const pointed = active.getAttribute?.("aria-activedescendant");
+    return (pointed && byId(active, pointed)) || active;
+  };
+
+  window.__a11yClicks = 0;
+  document.addEventListener("click", () => (window.__a11yClicks += 1), true);
+
+  window.__a11y = {
+    uid,
+    queryDeep,
+    queryAllDeep,
+    deepActive,
+    within,
+    visible,
+    /** What the page looks like to a check, right now. */
+    snapshot() {
+      const trigger = queryDeep("[data-a11y-trigger]");
+      const root = queryDeep("[data-a11y-root]");
+      const active = deepActive();
+      const target = activeTarget();
+      return {
+        clicks: window.__a11yClicks,
+        triggerTag: trigger?.localName ?? null,
+        triggerRole: trigger?.getAttribute("role") ?? null,
+        expanded: trigger?.getAttribute("aria-expanded") ?? null,
+        rootExists: Boolean(root),
+        rootVisible: visible(root),
+        rootModal: root?.getAttribute("aria-modal") === "true" || root?.getAttribute("role") === "alertdialog",
+        activeIsTrigger: Boolean(trigger && active && within(trigger, active)),
+        activeInRoot: Boolean(root && active && within(root, active)),
+        activeUid: uid(target),
+        activeTag: active?.localName ?? null,
+        activeText: text(target),
+        activeRole: target?.getAttribute?.("role") ?? null,
+        bodyActive: !active || active === document.body,
+      };
+    },
+    /** Items for a role selector, with which one is active and which are selected. */
+    items(selector) {
+      const target = activeTarget();
+      return queryAllDeep(selector).map((el) => ({
+        uid: uid(el),
+        text: text(el),
+        active: Boolean(target && (el === target || within(el, target))),
+        selected: el.getAttribute("aria-selected") === "true" || el.getAttribute("aria-checked") === "true",
+        hasSelected: el.hasAttribute("aria-selected"),
+        visible: visible(el),
+      }));
+    },
+    /** The name a control gets from its label, in the order browsers use. */
+    nameSources() {
+      const control = queryDeep("[data-a11y-trigger]");
+      if (!control) return null;
+      const sources = [];
+      if (control.labels && control.labels.length) sources.push("label element");
+      const labelledby = control.getAttribute("aria-labelledby");
+      if (labelledby && labelledby.split(/\s+/).some((id) => text(byId(control, id)))) sources.push("aria-labelledby");
+      if ((control.getAttribute("aria-label") ?? "").trim()) sources.push("aria-label");
+      if ((control.getAttribute("title") ?? "").trim()) sources.push("title");
+      return sources;
+    },
+    /** Error text tied to the control, if any. */
+    errorInfo() {
+      const control = queryDeep("[data-a11y-trigger]");
+      if (!control) return null;
+      const ids = [control.getAttribute("aria-errormessage"), ...(control.getAttribute("aria-describedby") ?? "").split(/\s+/)].filter(Boolean);
+      const linked = ids.map((id) => text(byId(control, id))).filter(Boolean);
+      const root = queryDeep("[data-a11y-root]") ?? document.body;
+      const live = [...root.querySelectorAll('[role="alert"], [aria-live="assertive"], [aria-live="polite"], [role="status"]')].map(text).filter(Boolean);
+      return { invalid: control.getAttribute("aria-invalid") === "true" || control.matches(":invalid"), ariaInvalid: control.getAttribute("aria-invalid") === "true", linked, live };
+    },
+    /** Computed style properties that can show a focus indicator. */
+    focusStyle() {
+      const el = deepActive();
+      if (!el) return null;
+      const s = getComputedStyle(el);
+      const pick = ["outlineStyle", "outlineWidth", "outlineColor", "outlineOffset", "boxShadow", "borderTopColor", "borderTopWidth", "backgroundColor", "color", "textDecorationLine"];
+      const style = Object.fromEntries(pick.map((key) => [key, s[key]]));
+      const box = el.getBoundingClientRect();
+      return { style, box: { x: box.x, y: box.y, width: box.width, height: box.height } };
+    },
+    /** Remember the focused element, so its style can be read after it loses focus. */
+    remember() {
+      window.__a11yLast = deepActive();
+    },
+    lastStyle() {
+      const el = window.__a11yLast;
+      if (!el) return null;
+      const s = getComputedStyle(el);
+      const pick = ["outlineStyle", "outlineWidth", "outlineColor", "outlineOffset", "boxShadow", "borderTopColor", "borderTopWidth", "backgroundColor", "color", "textDecorationLine"];
+      return Object.fromEntries(pick.map((key) => [key, s[key]]));
+    },
+    inputValue() {
+      const el = queryDeep("[data-a11y-trigger]");
+      return el ? (el.value ?? el.textContent ?? "").toString().trim() : null;
+    },
+  };
+}

package/src/tiers/interactions/index.js

@@ -0,0 +1,107 @@
+import { VIEWPORT } from "../../harness/browser.js";
+import { openPage } from "../../harness/url.js";
+import { ARCHETYPE_CHECKS, COMMON } from "./archetypes.js";
+import { installHelpers } from "./helpers.js";
+
+const CHECK_TIMEOUT_MS = 25_000;
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+/** Everything a check can do, bound to one fresh page. */
+function makeContext(page) {
+  const ctx = {
+    page,
+    trigger: page.locator("[data-a11y-trigger]").first(),
+    snap: () => page.evaluate(() => window.__a11y.snapshot()),
+    items: (selector) => page.evaluate((s) => window.__a11y.items(s), selector),
+    async settle(ms = 60) {
+      await page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+      await sleep(ms);
+    },
+    async press(key) {
+      await page.keyboard.press(key);
+      await ctx.settle();
+    },
+    async focus() {
+      await ctx.trigger.focus();
+      await ctx.settle();
+    },
+    /** Poll the snapshot until `predicate` holds. Returns that snapshot, or null on timeout. */
+    async waitFor(predicate, ms = 1000) {
+      const deadline = Date.now() + ms;
+      for (;;) {
+        const s = await ctx.snap();
+        if (predicate(s)) return s;
+        if (Date.now() > deadline) return null;
+        await sleep(50);
+      }
+    },
+    /** Press Tab from the top of the page until focus lands on the trigger. Returns the presses, or null. */
+    async tabToTrigger(max = 12) {
+      await page.evaluate(() => /** @type {HTMLElement} */ (document.activeElement)?.blur?.());
+      for (let presses = 1; presses <= max; presses += 1) {
+        await page.keyboard.press("Tab");
+        await ctx.settle(30);
+        if ((await ctx.snap()).activeIsTrigger) return presses;
+      }
+      return null;
+    },
+    async openCombo() {
+      await ctx.focus();
+      await ctx.press("ArrowDown");
+      for (let i = 0; i < 16; i += 1) {
+        const s = await ctx.snap();
+        if (s.expanded === "true" || (await ctx.items('[role="option"]')).some((o) => o.visible)) return true;
+        await sleep(50);
+      }
+      return false;
+    },
+    /** A screenshot region around an element, kept inside the viewport. */
+    clipAround(box, margin = 8) {
+      const x = Math.max(0, Math.floor(box.x - margin));
+      const y = Math.max(0, Math.floor(box.y - margin));
+      return { x, y, width: Math.max(1, Math.min(VIEWPORT.width - x, Math.ceil(box.width + margin * 2))), height: Math.max(1, Math.min(VIEWPORT.height - y, Math.ceil(box.height + margin * 2))) };
+    },
+  };
+  return ctx;
+}
+
+/** Run one check on a fresh page, so no check inherits another's state. */
+export async function runCheck(browser, url, check, { timeoutMs = CHECK_TIMEOUT_MS } = {}) {
+  /** @type {Awaited<ReturnType<typeof openPage>> | null} */
+  let opened = null;
+  try {
+    opened = await openPage(browser, url, { beforeGoto: (page) => page.addInitScript(installHelpers), waitUntil: "load" });
+    const ctx = makeContext(opened.page);
+    await ctx.trigger.waitFor({ state: "attached", timeout: 3000 });
+    const outcome = await Promise.race([
+      check.run(ctx),
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`The check took longer than ${timeoutMs / 1000} seconds.`)), timeoutMs)),
+    ]);
+    return { name: check.name, criteria: check.criteria, ...outcome };
+  } catch (error) {
+    return { name: check.name, criteria: check.criteria, result: "error", detail: `The check couldn't finish: ${(error instanceof Error ? error.message : String(error)).split("\n")[0]}` };
+  } finally {
+    await opened?.close();
+  }
+}
+
+/**
+ * Run the interaction checks for one archetype against its fixture page.
+ * Each check gets a fresh page. A check that can't finish reports `error`, which counts as a gap, never as a pass.
+ * @param {import("playwright-core").Browser} browser
+ * @param {string} url
+ * @param {string} archetype
+ */
+export async function runInteractions(browser, url, archetype) {
+  if (archetype === "chart") return { status: "not-applicable", reason: "No interaction checks are defined for the chart archetype." };
+  const checks = [...COMMON, ...(ARCHETYPE_CHECKS[archetype] ?? [])];
+  const results = [];
+  for (const check of checks) results.push(await runCheck(browser, url, check));
+  return { status: "ran", checks: results };
+}
+
+/** What a page or Storybook target says about this tier. */
+export const NOT_APPLICABLE_FOR_PAGES = {
+  status: "not-applicable",
+  reason: "Interaction checks need an archetype fixture with trigger and root hooks. Page and Storybook targets don't have them.",
+};