automatica11y 0.3.3 → 0.4.1

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

@@ -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,15 +69,46 @@ 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 (MUI needs an Emotion package).
+ * 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.
  */
@@ -113,8 +144,8 @@ 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 React again to keep it.
-  const keep = ["react", "react-dom"].flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
+  // 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);

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 },
   };
 }
 

package/src/plan/mapping.js

@@ -14,6 +14,7 @@ const BASE_NAMES = {
   "form-field": ["input", "textfield", "textinput", "field", "checkbox"],
   accordion: ["accordion", "collapsible", "disclosure"],
   tooltip: ["tooltip", "popover"],
+  "live-region": ["alert", "status", "toast", "snackbar", "notification", "liveregion"],
   chart: ["chart", "linechart", "barchart"],
 };
 
@@ -24,21 +25,23 @@ export const TEMPLATED = new Set(["button", "link"]);
 const words = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_]/g, " ");
 
 /** How well a name fits an archetype. 0 means it doesn't. */
-function score(archetype, name) {
+export function score(archetype, name) {
   if (!ARCHETYPE_PATTERNS[archetype].test(words(name))) return 0;
   const compact = name.replace(/[-_\s]/g, "").toLowerCase();
   const last = words(name).toLowerCase().split(" ").pop();
   const bases = BASE_NAMES[archetype];
-  if (bases.includes(compact)) return 4;
-  if (bases.includes(last)) return 3;
-  if (bases.some((base) => compact.startsWith(base))) return 2;
+  // Names listed first are closer to the archetype itself, so `tooltip` beats `popover` when both are there.
+  if (bases.includes(compact)) return 4 - bases.indexOf(compact) * 0.1;
+  if (bases.includes(last)) return 3 - bases.indexOf(last) * 0.1;
+  const starts = bases.findIndex((base) => compact.startsWith(base));
+  if (starts !== -1) return 2 - starts * 0.1;
   return 1;
 }
 
 /**
- * Guess which exports (React) or tags (web components) stand for each archetype.
+ * Guess which exports (React or Vue) or tags (web components) stand for each archetype.
  * The result is a starting point. A person or the skill checks it before trusting it.
- * @param {{ flavor: "react" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
+ * @param {{ flavor: "react" | "vue" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
  * @returns {Record<string, any>}
  */
 export function candidateMapping({ flavor, exports = [], tags = [] }) {
@@ -59,7 +62,7 @@ export function candidateMapping({ flavor, exports = [], tags = [] }) {
     const parts = info?.parts ?? [];
     // Flat compound libraries (DialogRoot, DialogTrigger, DialogContent) have sibling exports that share a prefix.
     // A button or link usually sits beside ButtonBase, ButtonGroup, and the like, which aren't its parts, so only real parts (Button.Root) count there.
-    const siblings = flavor === "react" && !TEMPLATED.has(archetype) ? names.filter((n) => n !== best && n.startsWith(best) && n.length > best.length) : [];
+    const siblings = flavor !== "wc" && !TEMPLATED.has(archetype) ? names.filter((n) => n !== best && n.startsWith(best) && n.length > best.length) : [];
     const compound = parts.length > 0 || siblings.length >= 2;
     const templated = TEMPLATED.has(archetype) && !compound;
     mapping[archetype] = {

package/src/plan/resolve-npm.js

@@ -1,8 +1,9 @@
 import { execFile } from "node:child_process";
+import { ADAPTERS } from "../frameworks/index.js";
+import { checkExports, notExportedMessage } from "./subpath.js";
 
-const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated"];
+const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated", "exports"];
 const OTHER_FRAMEWORKS = {
-  vue: "Vue",
   "@angular/core": "Angular",
   svelte: "Svelte",
   "solid-js": "Solid",
@@ -44,19 +45,19 @@ export function npmView(spec, { timeoutMs = 60_000 } = {}) {
 }
 
 /**
- * Guess how a package renders from its metadata alone. React wins when both signals appear.
+ * Guess how a package renders from its metadata alone. React wins when both signals appear, then a custom elements manifest, then Vue.
  * `npm` means the metadata can't say, so the run decides after it installs and loads the package.
  * @param {any} meta
- * @returns {{ kind: "npm-react" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
+ * @returns {{ kind: "npm-react" | "npm-vue" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
  */
 export function detectFlavor(meta) {
   const peers = meta.peerDependencies ?? {};
   const deps = meta.dependencies ?? {};
-  if ("react" in peers || "react-dom" in peers || "react" in deps) {
-    const how = "react" in peers || "react-dom" in peers ? "peer dependency" : "dependency";
-    return { kind: "npm-react", framework: "React", reason: `The package lists react as a ${how}.` };
-  }
+  const react = /** @type {any} */ (ADAPTERS.react.detect(meta));
+  if (react) return react;
   if (meta.customElements) return { kind: "npm-wc", framework: "Web components", reason: "The package has a customElements manifest." };
+  const vue = /** @type {any} */ (ADAPTERS.vue.detect(meta));
+  if (vue) return vue;
   for (const [name, label] of Object.entries(OTHER_FRAMEWORKS)) {
     if (name in peers) return { kind: "npm-unsupported", framework: label, reason: `The package needs ${label}.` };
   }
@@ -73,9 +74,14 @@ export function detectFlavor(meta) {
  */
 export async function resolveNpmTarget(target, view) {
   if (target.status !== "ok" || target.kind !== "npm" || !target.resolved) return target;
-  const { name, requested } = target.resolved;
+  const { name, requested, subpath } = target.resolved;
   try {
     const meta = await view(`${name}@${requested ?? "latest"}`);
+    // The registry lists a package's exports, so a wrong sub-path is caught here, before anything is installed.
+    if (subpath) {
+      const result = checkExports(meta.exports, subpath);
+      if (result.checked && !result.ok) throw new Error(notExportedMessage({ name, version: meta.version ?? null, subpath, exact: result.exact, patterns: result.patterns }));
+    }
     const flavor = detectFlavor(meta);
     return {
       ...target,