automatica11y 0.3.2 → 0.4.0

package/src/harness/generate/jsx.js

@@ -0,0 +1,76 @@
+import { ARCHETYPE_PATTERNS } from "../storybook.js";
+import { score } from "../../plan/mapping.js";
+import { buildKit } from "./kit.js";
+import { buildRecipes } from "./jsx-recipes.js";
+import { ATTEMPT_LIMIT, GENERATABLE, nameSaysSo } from "./shared.js";
+
+/** The names a part of a compound component ends with. A name that ends in one belongs to a family that shares the rest. */
+const PART_SUFFIX = /(Root|Trigger|Portal|Overlay|Backdrop|Positioner|Content|Popup|Panel|Title|Description|Close|Header|Item|List|Input|Label|Control|Provider)$/;
+
+/**
+ * The prefix a family of flat exports shares. `DialogClose` and `DialogRoot` belong to `Dialog`, even when no export is
+ * named `Dialog`. It counts only when at least two exports start with it.
+ */
+export function inferBase(name, exports) {
+  if (!name) return null;
+  const base = name.replace(PART_SUFFIX, "");
+  if (!base || base === name) return null;
+  return exports.filter((e) => e.name.startsWith(base) && e.name !== base).length >= 2 ? base : null;
+}
+
+const words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ");
+
+/**
+ * The component families in a package that look like this archetype, best first. A family is a base name and the parts that share
+ * it (`DropdownMenuRoot`, `DropdownMenuItem`), a namespaced export with parts, or a single export. A family ranks by how well its
+ * base fits the archetype's own name, then by how many parts it has. At most three are tried, so a library with a context menu,
+ * a dropdown menu, and a menubar gets the plainest ones first.
+ */
+export function familyBases(archetype, exports) {
+  const families = new Map();
+  for (const e of exports) {
+    if (!/^[A-Z]/.test(e.name) || !ARCHETYPE_PATTERNS[archetype].test(words(e.name))) continue;
+    const base = inferBase(e.name, exports) ?? e.name;
+    if (families.has(base)) continue;
+    const size = exports.filter((other) => other.name !== base && other.name.startsWith(base)).length + (exports.find((other) => other.name === base)?.parts?.length ?? 0);
+    families.set(base, { base, fit: score(archetype, base), size });
+  }
+  return [...families.values()].sort((a, b) => b.fit - a.fit || b.size - a.size || a.base.localeCompare(b.base)).slice(0, 3).map((f) => f.base);
+}
+
+/**
+ * Candidate fixtures for a JSX framework: the recipes, run over the parts of the component the mapping found,
+ * then over the package itself when its own name says it is this archetype.
+ * @param {import("./dialects.js").Dialect} dialect
+ * @param {{ archetype: string, pkg: string, entry: { export?: string }, exports: Array<{ name: string, type: string, parts?: string[] }>, explicit?: boolean }} input
+ *   `explicit` means a person named the export in a mapping, so only that component is tried.
+ * @returns {{ candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null }}
+ */
+export function generateJsx(dialect, { archetype, pkg, entry, exports, explicit = false }) {
+  if (!GENERATABLE.has(archetype)) return { candidates: [], reason: `Nothing is generated for the ${archetype} archetype.` };
+  const recipes = buildRecipes(dialect)[archetype] ?? [];
+  const bases = [];
+  if (explicit && entry.export) {
+    bases.push(inferBase(entry.export, exports) ?? entry.export);
+  } else {
+    bases.push(...familyBases(archetype, exports));
+    if (bases.length === 0 && entry.export) bases.push(inferBase(entry.export, exports) ?? entry.export);
+  }
+  if (nameSaysSo(archetype, pkg)) bases.push(null);
+  const candidates = [];
+  const seen = new Set();
+  for (const base of [...new Set(bases)]) {
+    const makeKit = () => buildKit(exports, base);
+    for (const recipe of recipes) {
+      const candidate = recipe(makeKit, pkg, dialect);
+      if (candidate && !seen.has(candidate.source)) {
+        seen.add(candidate.source);
+        candidates.push(candidate);
+      }
+    }
+  }
+  if (candidates.length === 0) {
+    return { candidates: [], reason: `The package's exports don't have the parts a ${archetype} recipe needs${entry.export ? ` (looked at ${entry.export} and the exports that start with it)` : ""}.` };
+  }
+  return { candidates: candidates.slice(0, ATTEMPT_LIMIT), reason: null };
+}

package/src/harness/generate/kit.js

@@ -0,0 +1,50 @@
+/**
+ * Find the parts of a compound component from the names a package exports.
+ *
+ * Two shapes are common. A namespaced export carries its parts as properties (`Dialog.Root`, `Dialog.Trigger`).
+ * A flat set of exports shares a prefix (`DialogRoot`, `DialogTrigger`, or `Dialog` plus `DialogContent`).
+ * A package that is one component's parts, such as a `Root` and a `Trigger` with no `Dialog` in front, works too.
+ * Parts are found by name only. Nothing here knows any one library.
+ */
+
+/**
+ * @param {Array<{ name: string, type: string, parts?: string[] }>} exports
+ * @param {string | null} base The export that names the component, or null when the package itself is the component.
+ */
+export function buildKit(exports, base) {
+  /** @type {Map<string, string>} lower-case part name to the expression that reaches it */
+  const parts = new Map();
+  const baseInfo = base ? exports.find((e) => e.name === base) : null;
+  if (base) {
+    for (const part of baseInfo?.parts ?? []) parts.set(part.toLowerCase(), `Lib.${base}.${part}`);
+    for (const e of exports) {
+      if (e.name === base || !e.name.startsWith(base)) continue;
+      const rest = e.name.slice(base.length);
+      if (/^[A-Z]/.test(rest) && !parts.has(rest.toLowerCase())) parts.set(rest.toLowerCase(), `Lib.${e.name}`);
+    }
+  } else {
+    for (const e of exports) if (/^[A-Z]/.test(e.name) && !parts.has(e.name.toLowerCase())) parts.set(e.name.toLowerCase(), `Lib.${e.name}`);
+  }
+  const used = new Set();
+  return {
+    base,
+    /** The component itself (`Lib.Dialog`), or null for a package with no single base. */
+    self: base && baseInfo ? `Lib.${base}` : null,
+    /** True when any of these part names exists. */
+    has: (...names) => names.some((name) => parts.has(name)),
+    /** The first part that exists, as a JSX tag. Records what was used. */
+    pick(...names) {
+      for (const name of names) {
+        const ref = parts.get(name);
+        if (ref) {
+          used.add(ref.replace(/^Lib\./, ""));
+          return ref;
+        }
+      }
+      return null;
+    },
+    /** What the candidates used, for the report. */
+    used: () => [...used],
+    names: () => [...parts.keys()],
+  };
+}

package/src/harness/generate/marking.js

@@ -0,0 +1,64 @@
+/**
+ * The code a generated fixture carries to mark its trigger and root.
+ *
+ * The harness needs exactly one element with `data-a11y-trigger` and, once the component is showing, one with
+ * `data-a11y-root` on the element that carries the role. A generated fixture can't know how a library forwards props,
+ * so it doesn't rely on that. It passes the trigger attribute where it can, and this code then marks whatever is missing,
+ * by role, every 50 milliseconds, reaching into open shadow roots. The probe that follows checks the result.
+ */
+
+/** What to look for, per archetype. `root` is a selector, or "trigger", "parent", or "controls". */
+export const MARKING = {
+  dialog: { root: "dialog, [role=dialog], [role=alertdialog]", trigger: "[aria-haspopup], [aria-expanded], button, [role=button]" },
+  menu: { root: "[role=menu]", trigger: "[aria-haspopup], [aria-expanded], button, [role=button]" },
+  tooltip: { root: "[role=tooltip]", trigger: "button, [role=button], a[href], input" },
+  tabs: { root: "trigger", trigger: "[role=tab]" },
+  accordion: { root: "controls", trigger: "[aria-expanded], summary, button" },
+  combobox: { root: "[role=listbox]", trigger: "input[role=combobox], [role=combobox], input" },
+  "form-field": { root: "parent", trigger: "input:not([type=hidden]), textarea, select, [role=textbox], [role=combobox], [role=checkbox], [role=switch]" },
+  "live-region": { root: "[role=alert], [role=status], [role=log], [aria-live=polite], [aria-live=assertive]", trigger: "button, [role=button]" },
+};
+
+/** The roles each archetype's root may carry, so the probe can tell a right mark from a wrong one. */
+export const ROOT_ROLES = {
+  dialog: ["dialog", "alertdialog"],
+  menu: ["menu", "menubar"],
+  tooltip: ["tooltip"],
+  tabs: ["tab"],
+  combobox: ["listbox", "combobox", "grid", "tree"],
+  "live-region": ["alert", "status", "log"],
+};
+
+/** The source that goes at the top of a generated fixture. It defines `startMarking()`, which returns a function that stops it. */
+export function markingSource(archetype) {
+  const config = MARKING[archetype];
+  return `function a11yDeepAll(selector, root) {
+  const scope = root || document;
+  const found = [...scope.querySelectorAll(selector)];
+  for (const el of scope.querySelectorAll("*")) if (el.shadowRoot) found.push(...a11yDeepAll(selector, el.shadowRoot));
+  return found;
+}
+function a11yMark() {
+  const config = ${JSON.stringify(config)};
+  if (a11yDeepAll("[data-a11y-trigger]").length === 0) {
+    const fallback = a11yDeepAll(config.trigger).find((el) => el.getClientRects().length > 0);
+    if (fallback) fallback.setAttribute("data-a11y-trigger", "");
+  }
+  const trigger = a11yDeepAll("[data-a11y-trigger]")[0];
+  if (a11yDeepAll("[data-a11y-root]").length > 0) return;
+  let root = null;
+  if (config.root === "trigger") root = trigger;
+  else if (config.root === "parent") root = trigger && trigger.parentElement;
+  else if (config.root === "controls") {
+    const id = trigger && trigger.getAttribute("aria-controls");
+    root = (id && document.getElementById(id)) || a11yDeepAll("[role=region]")[0];
+  } else root = a11yDeepAll(config.root)[0];
+  if (root) root.setAttribute("data-a11y-root", "");
+}
+function startMarking() {
+  a11yMark();
+  const timer = setInterval(a11yMark, 50);
+  return () => clearInterval(timer);
+}
+`;
+}

package/src/harness/generate/probe.js

@@ -0,0 +1,97 @@
+import { installHelpers } from "../../tiers/interactions/helpers.js";
+import { openPage } from "../url.js";
+import { ROOT_ROLES } from "./marking.js";
+
+/** Archetypes whose root appears after the trigger is activated, as the audit expects. */
+const OPENS = new Set(["dialog", "menu", "tooltip", "accordion", "combobox", "live-region"]);
+
+const FOCUSABLE_FIELD = "input:not([type=hidden]), textarea, select, [contenteditable=true], [role=textbox], [role=combobox], [role=checkbox], [role=switch], [role=radio], [role=slider], [role=spinbutton]";
+
+/**
+ * Check that a generated fixture does what the audit needs, before the audit trusts it.
+ * It loads the page, then checks that exactly one element is marked as the trigger, that nothing logged an error,
+ * that activating the trigger shows a root, and that the root carries a role that fits the archetype.
+ * A fixture that fails any of these isn't used, and the reason says which.
+ * @param {import("playwright-core").Browser} browser
+ * @param {string} url
+ * @param {string} archetype
+ * @returns {Promise<{ ok: boolean, reason: string | null }>}
+ */
+export async function probeFixture(browser, url, archetype) {
+  const errors = [];
+  /** @type {Awaited<ReturnType<typeof openPage>> | null} */
+  let opened = null;
+  try {
+    opened = await openPage(browser, url, {
+      waitUntil: "load",
+      beforeGoto: async (page) => {
+        page.on("pageerror", (error) => errors.push(error.message.split("\n")[0]));
+        page.on("console", (message) => {
+          if (message.type() === "error" && !/favicon|Failed to load resource/i.test(message.text())) errors.push(message.text().split("\n")[0]);
+        });
+        await page.addInitScript(installHelpers);
+      },
+    });
+    const page = opened.page;
+    try {
+      await page.waitForFunction(() => window.__a11y?.queryAllDeep("[data-a11y-trigger]").length > 0, undefined, { timeout: 4000 });
+    } catch {
+      return { ok: false, reason: errors.length ? `it logged an error and rendered nothing to mark as the trigger: ${errors[0]}` : "no element could be marked as the trigger" };
+    }
+    await page.waitForTimeout(150);
+    const count = await page.evaluate(() => window.__a11y.queryAllDeep("[data-a11y-trigger]").length);
+    if (count !== 1) return { ok: false, reason: `${count} elements were marked as the trigger` };
+    if (errors.length) return { ok: false, reason: `it logged an error: ${errors[0]}` };
+
+    if (archetype === "form-field") {
+      const field = await page.evaluate((selector) => window.__a11y.queryDeep("[data-a11y-trigger]")?.matches(selector) ?? false, FOCUSABLE_FIELD);
+      return field ? { ok: true, reason: null } : { ok: false, reason: "the element marked as the trigger isn't a field a person can type in" };
+    }
+    if (archetype === "tabs") {
+      const role = await page.evaluate(() => window.__a11y.queryDeep("[data-a11y-trigger]")?.getAttribute("role") ?? null);
+      return role === "tab" ? { ok: true, reason: null } : { ok: false, reason: `the element marked as the trigger has ${role ? `role ${role}` : "no role"}, not tab` };
+    }
+    if (!OPENS.has(archetype)) return { ok: true, reason: null };
+
+    const trigger = page.locator("[data-a11y-trigger]").first();
+    try {
+      if (archetype === "tooltip") await trigger.focus();
+      else await trigger.click({ timeout: 3000 });
+    } catch (error) {
+      return { ok: false, reason: `the trigger couldn't be activated: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}` };
+    }
+    try {
+      await page.waitForFunction(
+        ({ live, needsRoot }) => {
+          const state = window.__a11y.live();
+          if (live) return state.present && state.visible && Boolean(state.text || state.named);
+          // The trigger can say it's expanded an instant before the root is marked, so a role-carrying root has to be there itself.
+          if (needsRoot) return state.present && state.visible;
+          const trigger = window.__a11y.queryDeep("[data-a11y-trigger]");
+          return (state.present && state.visible) || trigger?.getAttribute("aria-expanded") === "true";
+        },
+        { live: archetype === "live-region", needsRoot: Boolean(ROOT_ROLES[archetype]) },
+        { timeout: 4000 },
+      );
+    } catch {
+      return { ok: false, reason: `activating the trigger showed no ${archetype === "live-region" ? "message" : "element marked as the root"}${ROOT_ROLES[archetype] ? ` (looked for an element with role ${ROOT_ROLES[archetype].join(", ")})` : ""}, which can also mean the library doesn't set that role` };
+    }
+    const roles = ROOT_ROLES[archetype];
+    if (roles) {
+      const fits = await page.evaluate((allowed) => {
+        const root = window.__a11y.queryDeep("[data-a11y-root]");
+        if (!root) return null;
+        const role = root.getAttribute("role");
+        return { role, fits: Boolean(role && allowed.includes(role)) || root.localName === "dialog" || root.hasAttribute("aria-live") };
+      }, roles);
+      if (!fits) return { ok: false, reason: "the root wasn't marked" };
+      if (!fits.fits) return { ok: false, reason: `the element marked as the root has ${fits.role ? `role ${fits.role}` : "no role"}, not ${roles.join(" or ")}` };
+    }
+    if (errors.length) return { ok: false, reason: `it logged an error when the trigger was activated: ${errors[0]}` };
+    return { ok: true, reason: null };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message.split("\n")[0] : String(error) };
+  } finally {
+    await opened?.close();
+  }
+}

package/src/harness/generate/shared.js

@@ -0,0 +1,12 @@
+import { ARCHETYPE_PATTERNS } from "../storybook.js";
+
+/** Archetypes a fixture can be generated for. Buttons and links use templates. A chart has nothing to wire. */
+export const GENERATABLE = new Set(["dialog", "menu", "tooltip", "tabs", "accordion", "combobox", "form-field", "live-region"]);
+
+/** The most candidates probed for one archetype, so a package that matches nothing doesn't cost minutes. */
+export const ATTEMPT_LIMIT = 8;
+
+/** Does the package's own name say it is this archetype? `@scope/react-dialog` is a dialog. */
+export function nameSaysSo(archetype, pkg) {
+  return ARCHETYPE_PATTERNS[archetype].test(pkg.replace(/[^a-z0-9]+/gi, " "));
+}

package/src/harness/generate/wc-recipes.js

@@ -0,0 +1,132 @@
+/**
+ * Candidate web component fixtures, built from what the element says about itself once it's defined:
+ * the attributes it observes, the members its class has, and the slots its shadow root offers.
+ * A candidate is a guess until the probe has seen it behave (see probe.js). None of this names a library.
+ */
+import { markingSource } from "./marking.js";
+import { ATTEMPT_LIMIT, GENERATABLE } from "./shared.js";
+
+/** The module around every candidate: the marking code and a mount function that starts it. */
+function frame(archetype, body) {
+  return `${markingSource(archetype)}
+export default function mount(container) {
+${body.split("\n").map((line) => (line ? `  ${line}` : line)).join("\n")}
+  startMarking();
+}
+`;
+}
+
+const has = (facts, name) => facts.attributes.includes(name) || facts.members.includes(name);
+const slotFor = (facts, pattern) => facts.slots.find((name) => pattern.test(name));
+
+// ---- dialog ----
+
+/** The ways a dialog element is commonly opened, from what it has. */
+function openers(facts) {
+  const found = [];
+  if (facts.attributes.includes("open")) found.push(["attribute", `dialog.setAttribute("open", "");`]);
+  if (facts.members.includes("open")) found.push(["property", "dialog.open = true;"]);
+  if (facts.members.includes("showModal")) found.push(["showModal()", "dialog.showModal();"]);
+  if (facts.members.includes("show")) found.push(["show()", "dialog.show();"]);
+  return found;
+}
+
+function dialogs(tagName, facts) {
+  const titleSlot = slotFor(facts, /title|header|heading/i);
+  const heading = titleSlot ? `<h2 slot="${titleSlot}">Edit profile</h2>` : "<h2>Edit profile</h2>";
+  return openers(facts).map(([how, code]) => ({
+    id: `dialog-${how.replace(/[^a-z]+/gi, "-").replace(/-$/, "")}`,
+    summary: `a ${tagName} opened with its ${how}`,
+    source: frame("dialog", `container.innerHTML = \`<button type="button" data-a11y-trigger>Open dialog</button><${tagName}>${heading}<p>Update your details.</p><button type="button">Close</button></${tagName}>\`;
+const dialog = container.querySelector(${JSON.stringify(tagName)});
+container.querySelector("[data-a11y-trigger]").addEventListener("click", () => {
+  ${code}
+});`),
+    used: [tagName],
+  }));
+}
+
+// ---- tooltip ----
+
+function tooltips(tagName, facts) {
+  return facts.attributes.filter((name) => /^(tip|tooltip|content|text|label|title|message|description)$/.test(name)).map((name) => ({
+    id: `tooltip-${name}`,
+    summary: `a ${tagName} that takes its text from ${name}`,
+    source: frame("tooltip", `container.innerHTML = \`<${tagName} ${name}="Saves your work."><button type="button" data-a11y-trigger>Save</button></${tagName}>\`;`),
+    used: [tagName],
+  }));
+}
+
+// ---- live region ----
+
+function messages(tagName, facts) {
+  const list = [{
+    id: "message-appended",
+    summary: `a ${tagName} added to the page when the trigger is pressed`,
+    source: frame("live-region", `container.innerHTML = \`<button type="button" data-a11y-trigger>Show message</button><div id="slot"></div>\`;
+container.querySelector("[data-a11y-trigger]").addEventListener("click", () => {
+  const message = document.createElement(${JSON.stringify(tagName)});
+  message.textContent = "Saved.";
+  container.querySelector("#slot").append(message);
+});`),
+    used: [tagName],
+  }];
+  if (has(facts, "open")) {
+    list.push({
+      id: "message-open",
+      summary: `a ${tagName} shown by setting open`,
+      source: frame("live-region", `container.innerHTML = \`<button type="button" data-a11y-trigger>Show message</button><${tagName}>Saved.</${tagName}>\`;
+const message = container.querySelector(${JSON.stringify(tagName)});
+container.querySelector("[data-a11y-trigger]").addEventListener("click", () => message.setAttribute("open", ""));`),
+      used: [tagName],
+    });
+  }
+  return list;
+}
+
+// ---- form field ----
+
+/** The element isn't marked as the trigger here. The marking code finds the input inside its shadow root, which is the thing a person types in. */
+function fields(tagName, facts) {
+  if (!["value", "name", "label", "placeholder", "checked", "type"].some((name) => has(facts, name))) return [];
+  const list = [{
+    id: "field-wrapped-label",
+    summary: `a ${tagName} inside a wrapping label`,
+    source: frame("form-field", `container.innerHTML = \`<label>Name <${tagName}></${tagName}></label>\`;`),
+    used: [tagName],
+  }];
+  if (has(facts, "label")) {
+    list.push({
+      id: "field-label-attribute",
+      summary: `a ${tagName} with a label attribute`,
+      source: frame("form-field", `container.innerHTML = \`<${tagName} label="Name"></${tagName}>\`;`),
+      used: [tagName],
+    });
+  }
+  return list;
+}
+
+/**
+ * Candidates for one element and archetype. Archetypes with no recipe here (menu, tabs, accordion, combobox) return none,
+ * because those depend on child elements and slots that an element can't describe well enough to guess.
+ * @param {{ archetype: string, tag: string, facts: { attributes: string[], members: string[], slots: string[] } }} input
+ */
+export function wcCandidates({ archetype, tag, facts }) {
+  const build = { dialog: dialogs, tooltip: tooltips, "live-region": messages, "form-field": fields }[archetype];
+  return build ? build(tag, facts) : [];
+}
+
+/**
+ * Candidates for a web component package, from what the element the mapping found says about itself.
+ * @param {{ archetype: string, entry: { tag?: string }, facts: Record<string, { attributes: string[], members: string[], slots: string[] }> }} input
+ * @returns {{ candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null }}
+ */
+export function generateWc({ archetype, entry, facts }) {
+  if (!GENERATABLE.has(archetype)) return { candidates: [], reason: `Nothing is generated for the ${archetype} archetype.` };
+  const tag = entry.tag;
+  if (!tag || !facts[tag]) return { candidates: [], reason: "No custom element looks like this archetype, so there's nothing to build a fixture around." };
+  const candidates = wcCandidates({ archetype, tag, facts: facts[tag] }).slice(0, ATTEMPT_LIMIT);
+  return candidates.length
+    ? { candidates, reason: null }
+    : { candidates: [], reason: `${tag} doesn't show a way to wire a ${archetype} (for example, an open attribute or a tip attribute), and no recipe covers a web component ${archetype} without one.` };
+}

package/src/harness/npm-install.js

@@ -1,5 +1,5 @@
 import { execFile } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 const NPM_FLAGS = ["--ignore-scripts", "--no-audit", "--no-fund", "--prefer-offline", "--loglevel=error"];
@@ -33,9 +33,9 @@ export function installedVersion(dir, name) {
 
 /**
  * Install a package into its own directory, never next to another target's install.
- * npm adds the peer dependencies. A React package also needs react-dom, so add it when the peers left it out.
+ * npm adds the peer dependencies. A React package also needs react-dom, and a Vue package needs vue, so add them when the peers left them out.
  * Install scripts stay off, because the code is untrusted until it runs in the browser sandbox.
- * @param {{ dir: string, name: string, version: string, flavor: "react" | "wc" | "unknown", run?: typeof runNpm }} options
+ * @param {{ dir: string, name: string, version: string, flavor: "react" | "vue" | "wc" | "unknown", run?: typeof runNpm }} options
  */
 export async function installPackage({ dir, name, version, flavor, run = runNpm }) {
   mkdirSync(dir, { recursive: true });
@@ -69,10 +69,90 @@ export async function installPackage({ dir, name, version, flavor, run = runNpm
       await npm(["install", "react", "react-dom", ...NPM_FLAGS, "--legacy-peer-deps"]);
       warnings.push(`${name} didn't bring in react, so the latest react and react-dom were added.`);
     } else if (!installedVersion(dir, "react-dom")) {
-      await npm(["install", `react-dom@${react}`, ...NPM_FLAGS, "--legacy-peer-deps"]);
+      // Name react too. A loose install prunes a package that only arrived as a peer, and react did.
+      await npm(["install", `react@${react}`, `react-dom@${react}`, ...NPM_FLAGS, "--legacy-peer-deps"]);
     }
   }
-  return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), version: installedVersion(dir, name) };
+  if (flavor === "vue" && !installedVersion(dir, "vue")) {
+    await npm(["install", "vue", ...NPM_FLAGS, "--legacy-peer-deps"]);
+    warnings.push(`${name} didn't bring in vue, so the latest vue was added.`);
+  }
+  return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), vue: installedVersion(dir, "vue"), version: installedVersion(dir, name) };
+}
+
+/** The installed framework runtimes (React, React DOM, Vue), named again so a loose install can't prune them. */
+function pinnedRuntime(dir) {
+  return ["react", "react-dom", "vue"].flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
+}
+
+const PACKAGE_SPEC = /^(@[a-z0-9~][\w.~-]*\/)?[a-z0-9~][\w.~-]*(@[\w.^~<>=*|-]+)?$/i;
+
+/**
+ * Install packages a mapping names beside the target: a token stylesheet, a theme, or another package the library's own
+ * documentation says to load. Only plain package specs are accepted (no flags, paths, or URLs). Install scripts stay off.
+ * @param {{ dir: string, specs: string[], run?: typeof runNpm }} options
+ * @returns {Promise<{ installed: string[], warnings: string[] }>}
+ */
+export async function installExtraPackages({ dir, specs, run = runNpm }) {
+  const wanted = [...new Set(specs)];
+  if (wanted.length === 0) return { installed: [], warnings: [] };
+  for (const spec of wanted) if (!PACKAGE_SPEC.test(spec)) throw new Error(`The mapping's install list has "${spec}", which isn't a package name with an optional version.`);
+  try {
+    await run(["install", ...wanted, ...pinnedRuntime(dir), "--legacy-peer-deps", ...NPM_FLAGS], dir);
+  } catch (error) {
+    throw new Error(`npm couldn't install ${wanted.join(", ")}: ${firstLine(error.message)}`);
+  }
+  return { installed: wanted, warnings: [`The mapping named ${wanted.join(", ")} to install beside the library, so it was installed.`] };
+}
+
+/**
+ * Find the optional peer dependencies that installed packages declare, with the range each asks for.
+ * npm leaves these out, but a library's default setup can still need one
+ * (e.g., React libraries may need an Emotion package).
+ * @param {string} dir The install folder.
+ * @returns {Map<string, string>} Package name to range.
+ */
+export function declaredOptionalPeers(dir) {
+  const root = join(dir, "node_modules");
+  const found = new Map();
+  const names = [];
+  for (const entry of existsSync(root) ? readdirSync(root) : []) {
+    if (entry.startsWith(".")) continue;
+    if (entry.startsWith("@")) for (const inner of readdirSync(join(root, entry))) names.push(`${entry}/${inner}`);
+    else names.push(entry);
+  }
+  for (const name of names) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(root, name, "package.json"), "utf8"));
+      for (const [peer, meta] of Object.entries(pkg.peerDependenciesMeta ?? {})) {
+        if (meta?.optional && pkg.peerDependencies?.[peer] && !found.has(peer)) found.set(peer, pkg.peerDependencies[peer]);
+      }
+    } catch {
+      // A folder without a readable package.json isn't a package.
+    }
+  }
+  return found;
+}
+
+/**
+ * Install the optional peer dependencies a failed bundle was missing. Only packages that an installed library
+ * declares as optional peers are added, so a typo in a fixture can't pull in an arbitrary package.
+ * @param {{ dir: string, unresolved: string[], run?: typeof runNpm }} options
+ * @returns {Promise<{ installed: string[], warnings: string[] }>}
+ */
+export async function installOptionalPeers({ dir, unresolved, run = runNpm }) {
+  const declared = declaredOptionalPeers(dir);
+  const wanted = unresolved.filter((name) => declared.has(name) && !installedVersion(dir, name));
+  if (wanted.length === 0) return { installed: [], warnings: [] };
+  // A loose install prunes packages that only arrived as peers, so name the framework again to keep it.
+  const keep = pinnedRuntime(dir);
+  const specs = [...wanted.map((name) => `${name}@${declared.get(name)}`), ...keep];
+  try {
+    await run(["install", ...specs, "--legacy-peer-deps", ...NPM_FLAGS], dir);
+  } catch (error) {
+    throw new Error(`npm couldn't install the optional peer dependencies ${wanted.join(", ")}: ${firstLine(error.message)}`);
+  }
+  return { installed: wanted, warnings: [`The library lists ${wanted.join(", ")} as optional peer dependencies and its code needs them to load, so they were installed.`] };
 }
 
 function firstLine(text) {

package/src/harness/settle.js

@@ -0,0 +1,17 @@
+/**
+ * Wait for fades and slides to finish before a state is scanned, so contrast is measured on the settled colors and not on a
+ * half-transparent element mid-transition. Animations that never end (a spinner) are left alone. Waits at most 2 seconds.
+ * @param {import("playwright-core").Page} page
+ */
+export async function settleAnimations(page) {
+  await page.evaluate(async () => {
+    const frame = () => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
+    await frame();
+    const finite = () => document.getAnimations().filter((a) => a.effect && a.effect.getComputedTiming().endTime !== Infinity);
+    const deadline = Date.now() + 2000;
+    while (finite().length > 0 && Date.now() < deadline) {
+      await Promise.race([Promise.allSettled(finite().map((a) => a.finished)), new Promise((done) => setTimeout(done, 200))]);
+      await frame();
+    }
+  });
+}

package/src/harness/storybook.js

@@ -12,6 +12,7 @@ export const ARCHETYPE_PATTERNS = {
   "form-field": /\binputs?\b|\btext ?(field|area|box)\b|\bform\b|\bcheckbox(es)?\b|\bradio\b|\bswitch\b|\bfield\b/i,
   accordion: /\baccordions?\b|\bcollaps(e|ible)\b|\bdisclosure\b/i,
   tooltip: /\btooltips?\b|\bpopovers?\b/i,
+  "live-region": /\balerts?\b(?! ?dialogs?)|\bstatus\b|\btoasts?\b|\bsnackbars?\b|\bnotifications?\b|\blive ?regions?\b/i,
   chart: /\bcharts?\b|\bgraphs?\b|\bplots?\b/i,
 };
 

package/src/harness/url.js

@@ -8,12 +8,12 @@ const NETWORK_IDLE_MS = 30_000;
  * The returned `warnings` hold anything the report should mention, such as a network that never went idle.
  * @param {import("playwright-core").Browser} browser
  * @param {string} url
- * @param {{ viewport?: { width: number, height: number }, forcedColors?: boolean, beforeGoto?: (page: import("playwright-core").Page) => void | Promise<unknown>, waitUntil?: "load" | "networkidle" }} [options]
+ * @param {{ viewport?: { width: number, height: number }, forcedColors?: boolean, colorScheme?: "light" | "dark", reducedMotion?: boolean, contrast?: "more" | "less", reducedTransparency?: boolean, beforeGoto?: (page: import("playwright-core").Page) => void | Promise<unknown>, waitUntil?: "load" | "networkidle" }} [options]
  *   `beforeGoto` runs before navigation, so a caller can attach console listeners that see the first messages.
  *   `waitUntil` defaults to `networkidle`. Local fixture pages don't need to wait for the network.
  */
-export async function openPage(browser, url, { viewport = VIEWPORT, forcedColors = false, beforeGoto, waitUntil = "networkidle" } = {}) {
-  const context = await browser.newContext({ viewport, deviceScaleFactor: 1, forcedColors: forcedColors ? "active" : "none" });
+export async function openPage(browser, url, { viewport = VIEWPORT, forcedColors = false, colorScheme = "light", reducedMotion = false, contrast, reducedTransparency = false, beforeGoto, waitUntil = "networkidle" } = {}) {
+  const context = await browser.newContext({ viewport, deviceScaleFactor: 1, forcedColors: forcedColors ? "active" : "none", colorScheme, reducedMotion: reducedMotion ? "reduce" : "no-preference" });
   await context.addInitScript(recordClosedShadowRoots);
   await context.addInitScript(recordCustomElements);
   /** @type {string[]} */
@@ -21,6 +21,16 @@ export async function openPage(browser, url, { viewport = VIEWPORT, forcedColors
   try {
     const page = await context.newPage();
     page.setDefaultTimeout(30_000);
+    // Playwright can't set prefers-reduced-transparency or prefers-contrast: less, so ask the browser directly.
+    // A page opened this way sets nothing else, because the call replaces any other emulated media features.
+    const features = [
+      ...(contrast ? [{ name: "prefers-contrast", value: contrast }] : []),
+      ...(reducedTransparency ? [{ name: "prefers-reduced-transparency", value: "reduce" }] : []),
+    ];
+    if (features.length) {
+      const session = await context.newCDPSession(page);
+      await session.send("Emulation.setEmulatedMedia", { features });
+    }
     await beforeGoto?.(page);
     let response;
     try {

package/src/plan/classify.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, extname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { cleanSubpath } from "./subpath.js";
 
 /**
  * @typedef {"npm" | "storybook" | "url" | "html-file" | "static-dir"} TargetKind
@@ -22,7 +23,7 @@ import { fileURLToPath } from "node:url";
 const LOCAL_PATH = /^(\.{1,2}(\/|$)|\/|~(\/|$)|file:)/;
 const LABEL = /^([A-Za-z0-9][\w.-]*)=(.+)$/;
 const HTTP_URL = /^https?:\/\//i;
-const NPM_NAME = /^(?:@([a-z0-9][a-z0-9._~-]*)\/)?([a-z0-9][a-z0-9._~-]*)(?:@(.*))?$/;
+const NPM_NAME = /^(?:@([a-z0-9][a-z0-9._~-]*)\/)?([a-z0-9][a-z0-9._~-]*)(?:@([^/]*))?(?:\/(.+))?$/;
 const COMPONENT_SOURCE = new Set([".tsx", ".jsx", ".ts", ".js", ".mjs", ".cjs", ".vue", ".svelte"]);
 
 /**
@@ -129,17 +130,23 @@ function classifyNpm(spec, base) {
     if (/[A-Z]/.test(spec) && NPM_NAME.test(spec.toLowerCase())) return failed(`"${spec}" isn't a valid package name. npm package names are lowercase.`, base);
     return failed(`"${spec}" isn't a valid npm package name. Write npm:name, npm:@scope/name, or npm:name@version.`, base);
   }
-  const [, scope, name, version] = match;
+  const [, scope, name, version, rawSubpath] = match;
   if (version === "") return failed(`"${spec}" ends with @ but has no version.`, base);
+  let subpath = null;
+  if (rawSubpath !== undefined) {
+    const cleaned = cleanSubpath(rawSubpath);
+    if ("reason" in cleaned) return failed(`"${spec}" isn't a valid sub-path: ${cleaned.reason}. Write npm:name/sub/path or npm:name@version/sub/path.`, base);
+    subpath = /** @type {{ subpath: string }} */ (cleaned).subpath;
+  }
   const full = scope ? `@${scope}/${name}` : name;
   return {
     ...base,
-    name: base.name || full,
+    name: base.name || (subpath ? `${full}/${subpath}` : full),
     status: "ok",
     reason: null,
     kind: "npm",
     evidenceLevel: "component",
-    resolved: { name: full, requested: version ?? null, version: null },
+    resolved: { name: full, requested: version ?? null, version: null, subpath },
   };
 }