automatica11y 0.3.3 → 0.4.1

package/src/plan/subpath.js

@@ -0,0 +1,133 @@
+/**
+ * Sub-paths of an npm package: `@scope/pkg/button/v2` imports `button/v2` from `@scope/pkg`.
+ * A package says what it lets people import in its `exports` field. A package without one lets people import any file in it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Split a sub-path into clean segments, or say what's wrong with it. Rejects empty parts, `.` and `..`, and backslashes,
+ * so a sub-path can't point outside the package. A trailing slash is dropped.
+ * @param {string} text
+ * @returns {{ ok: true, subpath: string } | { ok: false, reason: string }}
+ */
+export function cleanSubpath(text) {
+  const trimmed = text.replace(/\/+$/, "");
+  if (!trimmed) return { ok: false, reason: "the sub-path is empty" };
+  if (trimmed.includes("\\")) return { ok: false, reason: "a sub-path uses forward slashes" };
+  const segments = trimmed.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) return { ok: false, reason: 'a sub-path can\'t contain empty parts, "." or ".."' };
+  return { ok: true, subpath: segments.join("/") };
+}
+
+/**
+ * The export keys that name a sub-path (`./button`), and the patterns (`./es/*`), from an `exports` field.
+ * A string, an array, or an object with no `./` keys only exports the package root.
+ */
+function exportKeys(exportsField) {
+  if (!exportsField || typeof exportsField !== "object" || Array.isArray(exportsField)) return { exact: [], patterns: [], hasMap: false };
+  const keys = Object.keys(exportsField).filter((key) => key === "." || key.startsWith("./"));
+  if (keys.length === 0) return { exact: [], patterns: [], hasMap: false };
+  const usable = keys.filter((key) => exportsField[key] !== null);
+  return { exact: usable.filter((key) => !key.includes("*") && key !== "." && key !== "./package.json"), patterns: usable.filter((key) => key.includes("*")), hasMap: true };
+}
+
+/** Does a pattern key like `./es/*` or `./features/*.js` match a sub-path? */
+function matchesPattern(pattern, subpath) {
+  const [before, after] = pattern.slice(2).split("*");
+  return subpath.length >= before.length + after.length && subpath.startsWith(before) && subpath.endsWith(after);
+}
+
+/**
+ * Does the package's `exports` field let a sub-path be imported? Returns the sub-paths to suggest when it doesn't.
+ * `package.json` is always allowed. A package with no exports map isn't judged here, because its files are the answer.
+ * @param {unknown} exportsField
+ * @param {string} subpath
+ * @returns {{ checked: boolean, ok: boolean, exact: string[], patterns: string[] }}
+ */
+export function checkExports(exportsField, subpath) {
+  const { exact, patterns, hasMap } = exportKeys(exportsField);
+  if (!hasMap) {
+    // A string or array exports field means only the root is exported. No field means nothing here can say.
+    return { checked: exportsField !== undefined && exportsField !== null, ok: false, exact: [], patterns: [] };
+  }
+  const key = `./${subpath}`;
+  const ok = key === "./package.json" || exact.includes(key) || patterns.some((pattern) => matchesPattern(pattern, subpath));
+  return { checked: true, ok, exact, patterns };
+}
+
+/**
+ * What's wrong with a sub-path of an installed package, or null when it can be imported.
+ * @param {string} workDir The folder the package was installed into.
+ * @param {string} name
+ * @param {string} subpath
+ * @param {string | null} version
+ * @returns {string | null}
+ */
+export function subpathProblem(workDir, name, subpath, version) {
+  const packageDir = join(workDir, "node_modules", name);
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+  } catch {
+    return `${name} was installed, but its package.json couldn't be read to check the sub-path "${subpath}".`;
+  }
+  const result = checkExports(manifest.exports, subpath);
+  if (result.checked) return result.ok ? null : notExportedMessage({ name, version, subpath, exact: result.exact, patterns: result.patterns });
+  return fileExists(packageDir, subpath) ? null : `"${name}/${subpath}" isn't a file in ${name}${version ? `@${version}` : ""}, and the package has no exports map that lists what it offers.`;
+}
+
+/** The extensions a file can be imported without writing, for a package with no exports map. */
+const EXTENSIONS = ["", ".js", ".mjs", ".cjs", ".json", "/index.js", "/index.mjs", "/index.cjs"];
+
+/** Is there a file for this sub-path in an installed package that has no exports map? */
+export function fileExists(packageDir, subpath) {
+  return EXTENSIONS.some((extension) => existsSync(join(packageDir, `${subpath}${extension}`)));
+}
+
+/** How many single-character edits turn one word into another. */
+function distance(a, b) {
+  let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i += 1) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j += 1) row.push(Math.min(previous[j] + 1, row[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)));
+    previous = row;
+  }
+  return previous[b.length];
+}
+
+/** The exports closest to what was asked for: a shared start, a shared last part, or a typo of it. */
+function closest(subpath, exact) {
+  const wanted = subpath.toLowerCase().split("/");
+  const last = wanted[wanted.length - 1];
+  return exact
+    .map((key) => {
+      const parts = key.slice(2).toLowerCase().split("/");
+      const shared = parts.findIndex((part, i) => part !== wanted[i]);
+      const lead = shared === -1 ? parts.length : shared;
+      const tail = parts[parts.length - 1];
+      const rank = lead * 2 + (tail.includes(last) || last.includes(tail) ? 1 : 0) + (distance(last, tail) <= 2 ? 2 : 0);
+      return { key, rank };
+    })
+    .filter((entry) => entry.rank > 0)
+    .sort((a, b) => b.rank - a.rank || a.key.length - b.key.length)
+    .slice(0, 3)
+    .map((entry) => entry.key);
+}
+
+/**
+ * The message for a sub-path a package doesn't offer, with the closest matches first.
+ * @param {{ name: string, version: string | null, subpath: string, exact: string[], patterns: string[] }} input
+ */
+export function notExportedMessage({ name, version, subpath, exact, patterns }) {
+  const spec = (key) => `${name}${key === "." ? "" : key.slice(1)}`;
+  const close = closest(subpath, exact);
+  const shown = exact.slice(0, 12).map(spec);
+  const more = exact.length > shown.length ? `, and ${exact.length - shown.length} more` : "";
+  const parts = [`"${name}/${subpath}" isn't something ${name}${version ? `@${version}` : ""} exports.`];
+  if (close.length) parts.push(`Did you mean ${close.map(spec).join(" or ")}?`);
+  if (exact.length) parts.push(`It exports ${shown.join(", ")}${more}.`);
+  if (patterns.length) parts.push(`It also exports files by pattern: ${patterns.slice(0, 4).map(spec).join(", ")}.`);
+  if (!exact.length && !patterns.length) parts.push("It exports only its main entry.");
+  return parts.join(" ");
+}

package/src/report/comparison.js

@@ -3,11 +3,13 @@ import { num, plural } from "../text.js";
 import {
   ENGINE_NAMES,
   FINDINGS_NOTE,
+  GENERATED_NOTE,
   TIER_NAMES,
   cell,
   code,
   configLabel,
   finish,
+  hasGenerated,
   notTestableLines,
   reportFooter,
   reportHeader,
@@ -15,7 +17,7 @@ import {
   targetSection,
 } from "./parts.js";
 
-const TIER_ORDER = ["rules", "interactions", "computed", "vsr"];
+const TIER_ORDER = ["rules", "interactions", "computed", "conditions", "vsr"];
 
 /** The archetype rows: component archetypes in a fixed order, then whole pages, then Storybook stories. */
 function archetypeKeys(results) {
@@ -67,7 +69,9 @@ function coverageTable(plan, results, tier, keys) {
       // Name the configuration only when there's more than one to tell apart, or the row stands for several stories.
       const withTier = rows.filter((r) => r.configs?.some((c) => c.tiers[tier]));
       const labels = withTier.length > 1 || withTier[0]?.always ? withTier.map((r) => r.label).filter((l) => l && l !== "-") : [];
-      return labels.length ? `${status} (${labels.join("; ")})` : status;
+      const generated = target.archetypes?.[key]?.fixture?.source === "generated" && String(status).startsWith("ran");
+      const base = labels.length ? `${status} (${labels.join("; ")})` : status;
+      return generated ? `${base} (generated fixture)` : base;
     });
     lines.push(`| ${key} | ${cells.join(" | ")} |`);
   }
@@ -104,9 +108,9 @@ function interactionsCell(configs) {
   return parts.filter(Boolean).join("; ");
 }
 
-function computedCell(configs) {
-  const checks = configs.flatMap((c) => c.tiers.computed?.checks ?? []);
-  if (checks.length === 0) return configs.map((c) => c.tiers.computed?.status).find(Boolean) ?? "-";
+function measuredCell(configs, tier) {
+  const checks = configs.flatMap((c) => c.tiers[tier]?.checks ?? []);
+  if (checks.length === 0) return configs.map((c) => c.tiers[tier]?.status).find(Boolean) ?? "-";
   const failed = checks.filter((c) => c.result === "fail").map((c) => code(c.name));
   const unknown = checks.filter((c) => c.result === "undetermined").length;
   const errors = checks.filter((c) => c.result === "error").length;
@@ -123,17 +127,17 @@ function vsrCell(configs) {
 }
 
 function findingsTable(plan, results, key) {
-  const head = ["Target", "Configuration", ENGINE_NAMES.axe, ENGINE_NAMES.ibm, "Interactions", "Computed checks", "Virtual screen reader (simulated)"];
+  const head = ["Target", "Configuration", ENGINE_NAMES.axe, ENGINE_NAMES.ibm, "Interactions", "Computed checks", "Conditions", "Virtual screen reader (simulated)"];
   const lines = [`| ${head.join(" | ")} |`, `| ${head.map(() => "---").join(" | ")} |`];
   for (const target of results.targets) {
     const planTarget = plan.targets.find((t) => t.id === target.id);
     for (const row of rowsFor(planTarget, target, key)) {
       if (row.note) {
-        lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(row.note)} | | | | |`);
+        lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(row.note)} | | | | | |`);
         continue;
       }
       const c = row.configs;
-      lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(ruleCell(c, "axe"))} | ${cell(ruleCell(c, "ibm"))} | ${cell(interactionsCell(c))} | ${cell(computedCell(c))} | ${cell(vsrCell(c))} |`);
+      lines.push(`| ${cell(target.id)} | ${cell(row.label)} | ${cell(ruleCell(c, "axe"))} | ${cell(ruleCell(c, "ibm"))} | ${cell(interactionsCell(c))} | ${cell(measuredCell(c, "computed"))} | ${cell(measuredCell(c, "conditions"))} | ${cell(vsrCell(c))} |`);
     }
   }
   return lines;
@@ -180,6 +184,7 @@ export function renderComparison({ plan, results }) {
     lines.push(`### ${TIER_NAMES[tier]}${tier === "vsr" ? " (simulated)" : ""}.`, "", ...coverageTable(plan, results, tier, keys), "");
   }
   lines.push(...notTestableLines(results));
+  if (hasGenerated(results)) lines.push(GENERATED_NOTE, "");
 
   lines.push("## Findings.", "", FINDINGS_NOTE, "", ...(o.tiers.includes("rules") ? impactTables(results, o.engines) : []));
   for (const key of keys) {
@@ -187,7 +192,7 @@ export function renderComparison({ plan, results }) {
   }
 
   lines.push("## Details by target.", "", "Every finding, with its elements, rule help, and logs, for each target in turn.", "");
-  for (const target of results.targets) lines.push(targetSection(plan.targets.find((t) => t.id === target.id), target));
+  for (const target of results.targets) lines.push(targetSection(plan.targets.find((t) => t.id === target.id), target, { generatedNote: false }));
   lines.push(...reportFooter(results));
   return finish(lines);
 }

package/src/report/parts.js

@@ -1,3 +1,4 @@
+import { adapterFor } from "../frameworks/index.js";
 import { criterion, criterionName, wcagAttribution } from "../wcag/index.js";
 import { cap, num, plural } from "../text.js";
 
@@ -9,7 +10,7 @@ export const sentence = (text) => String(text).replace(/\.+$/, "");
 /** Escape angle brackets so rule text like <input> doesn't turn into HTML. */
 export const esc = (text) => String(text ?? "").replace(/</g, "\\<");
 export const ENGINE_NAMES = { axe: "axe-core", ibm: "IBM Equal Access" };
-export const TIER_NAMES = { rules: "Rules", interactions: "Interactions", computed: "Computed checks", vsr: "Virtual screen reader" };
+export const TIER_NAMES = { rules: "Rules", interactions: "Interactions", computed: "Computed checks", conditions: "Conditions", vsr: "Virtual screen reader" };
 
 export function toolLines(tools) {
   return Object.entries(tools)
@@ -28,8 +29,8 @@ export function engineCell(summary, engine) {
 export function tierCell(target, tier) {
   const counts = target.summary?.interactions;
   const vsr = target.summary?.vsr;
-  const measured = target.summary?.computed;
-  if (tier === "computed" && measured) {
+  const measured = target.summary?.[tier];
+  if ((tier === "computed" || tier === "conditions") && measured) {
     const parts = [measured.fail && `${num(measured.fail)} failed`, measured.undetermined && `${num(measured.undetermined)} undetermined`, measured.error && plural(measured.error, "error"), measured.pass && `${num(measured.pass)} passed`, measured.notApplicable && `${num(measured.notApplicable)} not applicable`].filter(Boolean);
     return `ran, ${parts.join(", ")}`;
   }
@@ -220,8 +221,14 @@ export function criteriaCell(list) {
   }).join(", ");
 }
 
-export function computedSection(result, nested) {
-  const lines = [`${nested ? "#####" : "####"} Computed checks.`, "", "automatica11y's own measurements from resolved styles in the browser, with the numbers WCAG gives. They're reported on their own and never added to the axe-core or IBM Equal Access counts. A check that can't reduce the page to colors (a gradient, an image, transparency) is undetermined, which counts as a gap and never as a pass.", ""];
+const MEASURED_INTRO = {
+  computed: ["Computed checks", "automatica11y's own measurements from resolved styles in the browser, with the numbers WCAG gives. They're reported on their own and never added to the axe-core or IBM Equal Access counts. A check that can't reduce the page to colors (a gradient, an image, transparency) is undetermined, which counts as a gap and never as a pass."],
+  conditions: ["Conditions", "automatica11y's own checks of how the page holds up under a user's settings (reduced motion, dark mode, more or less contrast, reduced transparency, forced colors) and environment (a 320 pixel window, wider text spacing). Each check opens fresh copies of the page. They're reported on their own and never added to the axe-core or IBM Equal Access counts. A check that can't tell is undetermined, which counts as a gap and never as a pass. \"Not applicable\" means the page doesn't use the feature, which isn't a failure."],
+};
+
+export function measuredSection(tier, result, nested) {
+  const [title, intro] = MEASURED_INTRO[tier];
+  const lines = [`${nested ? "#####" : "####"} ${title}.`, "", intro, ""];
   lines.push("| Check | Result | WCAG | Detail |", "| --- | --- | --- | --- |");
   for (const check of result.checks) {
     lines.push(`| ${code(check.name)} | ${check.result} | ${cell(criteriaCell(check.criteria))} | ${cell(check.detail)}${check.method ? cell(` (method: ${check.method})`) : ""} |`);
@@ -235,17 +242,33 @@ export function configLabel(config) {
   return parts.length ? ` (${parts.join(", ")})` : "";
 }
 
+/** What the Fixture column says about where a fixture came from. */
+function fixtureLabel(archetype) {
+  const f = archetype.fixture;
+  if (!f || f.source === "none") return "-";
+  return f.source === "generated" ? `generated (${f.recipe})` : f.source;
+}
+
 export function archetypeTable(target) {
   const rows = Object.entries(target.archetypes).map(([name, archetype]) => {
-    if (archetype.status === "gap") return `| ${name} | gap | - | ${cell(sentence(archetype.reason ?? "No fixture."))} |`;
+    if (archetype.status === "gap") return `| ${name} | gap | ${fixtureLabel(archetype)} | - | ${cell(sentence(archetype.reason ?? "No fixture."))} |`;
     const states = [...new Set(archetype.configs.map((c) => c.state).filter(Boolean))].join(", ") || "-";
     const libs = [...new Set(archetype.configs.map((c) => c.libA11y).filter((l) => l && l !== "n/a"))];
-    return `| ${name} | ran | ${states} | ${libs.length ? `library accessibility ${libs.join(" and ")}` : ""} |`;
+    const notes = [libs.length ? `library accessibility ${libs.join(" and ")}` : "", archetype.fixture?.source === "generated" ? `${sentence(archetype.fixture.summary ?? "")}, from ${(archetype.fixture.used ?? []).join(", ")}. Source: ${archetype.fixture.file}` : ""].filter(Boolean);
+    return `| ${name} | ran | ${fixtureLabel(archetype)} | ${states} | ${cell(notes.join(". "))} |`;
   });
-  return ["| Archetype | Status | States | Note |", "| --- | --- | --- | --- |", ...rows];
+  return ["| Archetype | Status | Fixture | States | Note |", "| --- | --- | --- | --- | --- |", ...rows];
 }
 
-export function targetSection(planTarget, target) {
+/** True when any archetype in the results ran from a fixture the tool generated. */
+export function hasGenerated(results) {
+  return results.targets.some((t) => Object.values(t.archetypes ?? {}).some((a) => a.fixture?.source === "generated"));
+}
+
+/** What "generated" means, for any report that has one. */
+export const GENERATED_NOTE = "**Generated fixtures.** Where no fixture was written, the tool built one from the parts the package exports (or from what a custom element says about itself) and ran it only after it checked that the trigger and root behaved. A generated fixture is a guess about how the library is meant to be assembled, so a failure may come from how it was wired and not from the library. Treat generated results as lower evidence than an authored fixture. The source of each is in the `generated` folder beside this report. Copy one to `fixtures/<target id>/<archetype>.jsx` (`.js` for web components) and edit it to make it an authored fixture.";
+
+export function targetSection(planTarget, target, { generatedNote = true } = {}) {
   if (target.status === "ran" && target.storybook) return storybookSection(planTarget, target);
   const lines = [`### ${planTarget.label}.`, ""];
   lines.push(`Target ${code(planTarget.input)}, ${planTarget.kind ?? "unclassified"}${planTarget.evidenceLevel ? `, ${planTarget.evidenceLevel} evidence` : ""}.`, "");
@@ -255,13 +278,14 @@ export function targetSection(planTarget, target) {
   }
   if (target.npm) {
     const n = target.npm;
-    lines.push(`Installed ${code(`${n.name}@${n.version}`)} on its own, as ${n.flavor === "react" ? `React${n.react ? ` (react ${n.react})` : ""}` : `web components (${n.tags.length ? n.tags.slice(0, 6).join(", ") : "no tags found"})`}.`, "");
+    lines.push(`Installed ${code(`${n.name}@${n.version}`)} on its own${n.subpath ? ` and tested its ${code(`${n.name}/${n.subpath}`)} entry` : ""}, as ${adapterFor(n.flavor).describe(n)}.`, "");
   }
   for (const warning of target.warnings) lines.push(`Warning: ${warning}`, "");
   if (target.status === "failed") {
     lines.push(`This target failed: ${sentence(target.reason)}. A failed target is a gap in coverage. It isn't a pass.`, "");
   }
   if (target.npm) lines.push("**Archetypes.** A gap means the archetype wasn't tested, so it counts against coverage and never as a pass.", "", ...archetypeTable(target), "");
+  if (generatedNote && target.npm && hasGenerated({ targets: [target] })) lines.push(GENERATED_NOTE, "");
   /** @type {Set<string>} */
   const skipped = new Set();
   for (const [name, archetype] of Object.entries(target.archetypes)) {
@@ -274,8 +298,8 @@ export function targetSection(planTarget, target) {
           lines.push(vsrSection(result, name !== "page"), "");
         } else if (tier === "interactions" && result.status === "ran") {
           lines.push(interactionsSection(result, name !== "page"), "");
-        } else if (tier === "computed" && result.status === "ran") {
-          lines.push(computedSection(result, name !== "page"), "");
+        } else if ((tier === "computed" || tier === "conditions") && result.status === "ran") {
+          lines.push(measuredSection(tier, result, name !== "page"), "");
         } else if (result.status !== "ran") {
           skipped.add(`${TIER_NAMES[tier] ?? tier}: ${sentence(result.reason ?? result.status)}.`);
         }

package/src/run/audit-npm.js

@@ -2,15 +2,19 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { bundleEntries } from "../harness/bundle.js";
-import { installOptionalPeers, installPackage } from "../harness/npm-install.js";
-import * as react from "../harness/npm-react.js";
-import * as wc from "../harness/npm-wc.js";
+import { GENERATABLE } from "../harness/generate/index.js";
+import { generateFixture } from "./generate-fixture.js";
+import { settleAnimations } from "../harness/settle.js";
+import { installExtraPackages, installOptionalPeers, installPackage } from "../harness/npm-install.js";
+import { adapterFor, adapterForKind } from "../frameworks/index.js";
+import { subpathProblem } from "../plan/subpath.js";
 import { closedShadowHosts, notTestableEntries } from "../harness/shadow.js";
 import { serveStatic } from "../harness/static-serve.js";
 import { openPage } from "../harness/url.js";
 import { candidateMapping, findAuthoredFixture } from "../plan/mapping.js";
 import { ARCHETYPES } from "../schema.js";
 import { runComputed } from "../tiers/computed/index.js";
+import { runConditions } from "../tiers/conditions/index.js";
 import { runInteractions } from "../tiers/interactions/index.js";
 import { runRules } from "../tiers/rules/index.js";
 import { failedVsr, runVsr } from "../tiers/vsr.js";
@@ -24,6 +28,7 @@ const STATES = {
   tooltip: ["closed", "open"],
   combobox: ["closed", "open"],
   accordion: ["collapsed", "expanded"],
+  "live-region": ["before message", "message shown"],
 };
 
 const firstLine = (error) => (error instanceof Error ? error.message : String(error)).split("\n").find((l) => l.trim()) ?? "unknown error";
@@ -59,10 +64,10 @@ async function bundleWithPeers(options, warnings) {
 
 /** Load the whole package in a page to list its exports and the custom elements it defines. */
 async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
-  const helper = flavor === "react" ? react : wc;
+  const adapter = adapterFor(flavor);
   const entryFile = join(workDir, "discover.js");
-  writeFileSync(entryFile, helper.discoverEntry(pkg));
-  await bundleWithPeers({ entries: { discover: entryFile }, outdir: buildDir, workDir, react: flavor === "react" }, warnings);
+  writeFileSync(entryFile, adapter.discoverEntry(pkg));
+  await bundleWithPeers({ entries: { discover: entryFile }, outdir: buildDir, workDir, framework: adapter }, warnings);
   const server = await serveStatic(buildDir);
   const errors = [];
   try {
@@ -74,8 +79,31 @@ async function discover({ browser, workDir, flavor, pkg, buildDir, warnings }) {
     }
     const exportsList = await opened.page.evaluate(() => /** @type {any} */ (window).__a11yExports);
     const tags = await opened.page.evaluate(() => [.../** @type {any} */ (window).__a11yDefined ?? []]);
+    // What each element says about itself, so a fixture can be built around it: observed attributes, class members, slots.
+    const facts = await opened.page.evaluate((names) => {
+      const out = {};
+      for (const name of names.slice(0, 80)) {
+        const Element = customElements.get(name);
+        if (!Element) continue;
+        const members = new Set();
+        for (let proto = Element.prototype; proto && proto !== HTMLElement.prototype && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+          for (const key of Object.getOwnPropertyNames(proto)) if (!key.startsWith("_") && key !== "constructor") members.add(key);
+        }
+        let slots = [];
+        try {
+          const el = document.createElement(name);
+          document.body.append(el);
+          slots = [...(el.shadowRoot?.querySelectorAll("slot") ?? [])].map((slot) => slot.getAttribute("name") ?? "");
+          el.remove();
+        } catch {
+          // An element that can't be created on its own has no slots to report.
+        }
+        out[name] = { attributes: [.../** @type {any} */ (Element).observedAttributes ?? []], members: [...members], slots: slots.filter(Boolean) };
+      }
+      return out;
+    }, tags);
     await opened.close();
-    return { exports: exportsList, tags };
+    return { exports: exportsList, tags, facts };
   } finally {
     await server.close();
   }
@@ -96,6 +124,9 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
     if (count !== 1) return { gap: `The fixture must mark exactly one data-a11y-trigger. It marked ${num(count)}.` };
     if (errors.length) return { gap: `The fixture logged errors when it mounted: ${errors[0]}` };
 
+    if (archetype === "live-region" && (await trigger.first().evaluate((el) => el.matches("[data-a11y-root]")))) {
+      return { gap: "The fixture marks the same element as the trigger and the message. A live-region fixture needs a control that makes the message appear (data-a11y-trigger) and the message itself (data-a11y-root)." };
+    }
     const states = STATES[archetype] ?? ["initial"];
     const configs = [];
     for (const [index, state] of states.entries()) {
@@ -105,23 +136,25 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
           if (archetype === "tooltip") await trigger.first().focus();
           else await trigger.first().click();
           await opened.page.waitForFunction(
-            () => {
+            (needsText) => {
               const root = document.querySelector("[data-a11y-root]");
               const shown = root && /** @type {HTMLElement} */ (root).getClientRects().length > 0;
+              // A live region can be on the page and empty until the trigger fills it, so wait for the message itself.
+              if (needsText) return Boolean(shown && ((root.textContent ?? "").trim() || root.getAttribute("aria-label") || root.getAttribute("aria-labelledby")));
               return shown || document.querySelector('[data-a11y-trigger][aria-expanded="true"]') !== null;
             },
-            undefined,
+            archetype === "live-region",
             { timeout: 3000 },
           );
         } catch {
           failure = `The ${state} state never appeared after activating the trigger. A fixture's data-a11y-root has to show up when the ${archetype} opens.`;
         }
       }
-      await opened.page.evaluate(() => new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done))));
+      await settleAnimations(opened.page);
       /** @type {Record<string, any>} */
       const tiers = {};
       for (const tier of plan.options.tiers) {
-        if (tier === "interactions" || tier === "computed") continue;
+        if (tier === "interactions" || tier === "computed" || tier === "conditions") continue;
         if (tier === "vsr") tiers.vsr = failure ? { status: "skipped", simulated: true, reason: failure } : await runVsr(opened.page, { scope: "body", state }).catch(failedVsr);
         else if (failure) tiers.rules = { status: "failed", reason: failure, engines: Object.fromEntries(plan.options.engines.map((e) => [e, { status: "failed", reason: failure }])) };
         else {
@@ -135,6 +168,7 @@ async function auditFixturePage({ browser, url, archetype, plan, libA11y }) {
     // The checks open their own fresh pages, so run them after this page's rules results are in.
     if (plan.options.tiers.includes("interactions")) configs[0].tiers.interactions = await runInteractions(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
     if (plan.options.tiers.includes("computed")) configs[0].tiers.computed = await runComputed(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
+    if (plan.options.tiers.includes("conditions")) configs[0].tiers.conditions = await runConditions(browser, libA11y === "n/a" ? url : `${url}?libA11y=${libA11y}`, archetype);
     return { configs, hidden };
   } finally {
     await opened.close();
@@ -161,14 +195,14 @@ async function auditFixture({ browser, url, archetype, plan, toggle }) {
 /**
  * Audit an npm package: install it on its own, find what it exports, and audit each archetype that has a fixture.
  * An archetype without a usable fixture is a gap with a reason, never a pass.
- * @returns {Promise<{ result: any, mapping: Record<string, any> | null }>}
+ * @returns {Promise<{ result: any, mapping: Record<string, any> | null, files?: Record<string, string> }>}
  */
 export async function auditNpm({ browser, planTarget, plan, cwd, install = installPackage }) {
   install ??= installPackage;
   const base = { id: planTarget.id, reason: null, archetypes: {}, summary: { engines: {}, gaps: [], notTestable: [] }, warnings: [] };
   const resolved = planTarget.resolved ?? {};
   if (planTarget.kind === "npm-unsupported") {
-    return { result: { ...base, status: "unsupported", reason: `${resolved.framework ?? "This framework"} packages aren't supported. v1 covers React and web components.` }, mapping: null };
+    return { result: { ...base, status: "unsupported", reason: `${resolved.framework ?? "This framework"} packages aren't supported. This version covers React, Vue 3, and web components.` }, mapping: null };
   }
   const tmp = mkdtempSync(join(tmpdir(), "automatica11y-npm-"));
   const workDir = join(tmp, "install");
@@ -177,22 +211,33 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
   mkdirSync(fixtureDir, { recursive: true });
   const servers = [];
   try {
-    /** @type {"react" | "wc" | "unknown"} */
-    let flavor = planTarget.kind === "npm-react" ? "react" : planTarget.kind === "npm-wc" ? "wc" : "unknown";
+    /** The framework's id (react, vue, or wc), or "unknown" when the metadata couldn't say. */
+    /** @type {any} */
+    let flavor = adapterForKind(planTarget.kind)?.id ?? "unknown";
     const installed = await install({ dir: workDir, name: resolved.name, version: resolved.version, flavor });
     const warnings = [...installed.warnings];
+    // What fixtures and templates import: the package, or the sub-path of it that was asked for.
+    const importSpec = resolved.subpath ? `${resolved.name}/${resolved.subpath}` : resolved.name;
+    if (resolved.subpath) {
+      const problem = subpathProblem(workDir, resolved.name, resolved.subpath, installed.version ?? resolved.version);
+      if (problem) throw new Error(problem);
+    }
 
-    const found = await discover({ browser, workDir, flavor: flavor === "react" ? "react" : "wc", pkg: resolved.name, buildDir, warnings });
+    // Packages the mapping names (a token stylesheet, a theme) go in beside the library, so a fixture can import them.
+    const extras = await installExtraPackages({ dir: workDir, specs: Object.values(planTarget.mapping ?? {}).flatMap((entry) => entry.install ?? []) });
+    warnings.push(...extras.warnings);
+
+    const found = await discover({ browser, workDir, flavor: flavor === "unknown" ? "wc" : flavor, pkg: importSpec, buildDir, warnings });
     if (flavor === "unknown") {
       if (found.tags.length > 0) flavor = "wc";
       else if (installed.react && found.exports.some((e) => /^[A-Z]/.test(e.name))) flavor = "react";
     }
     if (flavor === "unknown" || (flavor === "wc" && found.tags.length === 0)) {
-      return { result: { ...base, status: "not-applicable", reason: "The package has no rendering surface. It exports no React components and defines no custom elements.", warnings }, mapping: null };
+      return { result: { ...base, status: "not-applicable", reason: "The package has no rendering surface. It exports no components for a supported framework and defines no custom elements.", warnings }, mapping: null };
     }
 
     const candidates = candidateMapping({ flavor, exports: found.exports, tags: found.tags });
-    const kindFlavor = /** @type {"react" | "wc"} */ (flavor);
+    const adapter = adapterFor(flavor);
     const wanted = plan.options.archetypes ?? ARCHETYPES;
     /** @type {Record<string, any>} */
     const mapping = {};
@@ -200,7 +245,20 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
     const archetypes = {};
     const gaps = [];
     const hidden = [];
-    const helper = flavor === "react" ? react : wc;
+    /** Files to write beside the report: the fixtures the tool generated, so they can be reviewed and adopted. */
+    const files = {};
+    /** Where each archetype's fixture came from, for the results. */
+    const sources = {};
+    /** One server for the probes, started when the first one is needed. */
+    let probeServer = null;
+    const getServer = async () => {
+      if (!probeServer) {
+        mkdirSync(buildDir, { recursive: true });
+        probeServer = await serveStatic(buildDir);
+        servers.push(probeServer);
+      }
+      return probeServer;
+    };
 
     // Decide where each archetype's fixture comes from, then bundle each one on its own so one bad fixture can't break the rest.
     const runnable = {};
@@ -218,29 +276,57 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
         entry.status = "needs-fixture";
         entry.reason = `The mapping names ${user.fixture}, but that file doesn't exist.`;
       } else if (entry.status === "template" || (user.export || user.tag) && ["button", "link"].includes(archetype)) {
-        const source = flavor === "react" ? react.template(archetype, resolved.name, entry.export) : wc.template(archetype, entry.tag);
+        const source = adapter.template(archetype, importSpec, flavor === "wc" ? entry.tag : entry.export);
         if (source) {
           entry.status = "template";
           delete entry.reason;
-          fixture = join(fixtureDir, `${archetype}.${flavor === "react" ? "jsx" : "js"}`);
+          fixture = join(fixtureDir, `${archetype}.${adapter.extension}`);
           writeFileSync(fixture, source);
         }
       }
+      /** @type {any} */
+      let source = fixture ? { source: entry.status === "authored" ? "authored" : "template" } : null;
+      let attempts = [];
+      let generationTried = false;
+      // Nothing authored and no template: build candidates from what the package exports, and keep one only if it works.
+      if (!fixture && !user.fixture && plan.options.generate !== false && GENERATABLE.has(archetype) && !(entry.status === "no-match" && flavor === "wc")) {
+        const generated = await generateFixture({ browser, adapter, archetype, entry, found, explicit: Boolean(user.export), pkg: importSpec, tmp, workDir, buildDir, getServer, bundle: (options) => bundleWithPeers(options, warnings) });
+        attempts = generated.attempts;
+        generationTried = attempts.length > 0;
+        if (generated.ok && generated.winner) {
+          const { winner } = generated;
+          const relative = `generated/${planTarget.id}/${archetype}.${winner.extension}`;
+          files[relative] = winner.source;
+          fixture = winner.file;
+          entry.status = "generated";
+          entry.recipe = winner.recipe;
+          entry.summary = winner.summary;
+          entry.used = winner.used;
+          entry.generatedFile = relative;
+          delete entry.reason;
+          source = { source: "generated", recipe: winner.recipe, summary: winner.summary, used: winner.used, file: relative, attempts };
+        } else if (generated.reason && (generationTried || entry.status !== "no-match")) {
+          entry.reason = `${entry.status === "no-match" ? "" : `${entry.reason ?? `The ${archetype} archetype needs a fixture someone writes.`} `}Generating one didn't work. ${generated.reason}`.trim();
+        }
+      }
       mapping[archetype] = entry;
       if (!fixture) {
-        const reason = entry.status === "no-match" ? entry.reason : entry.reason ?? `The ${archetype} archetype needs a fixture someone writes.`;
-        archetypes[archetype] = { status: "gap", reason: archetype && entry.status !== "no-match" ? `${reason} Write fixtures/${planTarget.id}/${archetype}.${flavor === "react" ? "jsx" : "js"}.` : reason, configs: [] };
+        // A no-match archetype has no component to write a fixture for, unless a generator looked and said why it couldn't build one.
+        const writable = entry.status !== "no-match" || generationTried;
+        const reason = entry.reason ?? `The ${archetype} archetype needs a fixture someone writes.`;
+        archetypes[archetype] = { status: "gap", reason: writable ? `${reason} Write fixtures/${planTarget.id}/${archetype}.${adapter.extension}.` : reason, configs: [], ...(attempts.length ? { fixture: { source: "none", attempts } } : {}) };
         gaps.push(`archetype:${archetype}`);
         continue;
       }
       const entryFile = join(tmp, "entries", `${archetype}-entry.js`);
       mkdirSync(join(tmp, "entries"), { recursive: true });
-      writeFileSync(entryFile, helper.entry(fixture, resolved.name));
+      writeFileSync(entryFile, adapter.entry(fixture, importSpec));
       try {
-        await bundleWithPeers({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, react: flavor === "react" }, warnings);
+        await bundleWithPeers({ entries: { [archetype]: entryFile }, outdir: buildDir, workDir, framework: adapter }, warnings);
         runnable[archetype] = `/${archetype}.html`;
+        sources[archetype] = source;
       } catch (error) {
-        archetypes[archetype] = { status: "gap", reason: `The fixture didn't bundle. ${firstLine(error)}`, configs: [] };
+        archetypes[archetype] = { status: "gap", reason: `The fixture didn't bundle. ${firstLine(error)}`, configs: [], ...(attempts.length ? { fixture: { source: "none", attempts } } : {}) };
         gaps.push(`archetype:${archetype}`);
         entry.status = "needs-fixture";
         entry.reason = firstLine(error);
@@ -253,13 +339,14 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
       for (const [archetype, path] of Object.entries(runnable)) {
         /** @type {any} */
         const outcome = await auditFixture({ browser, url: `${live.origin}${path}`, archetype, plan, toggle: mapping[archetype].libA11y === true }).catch((error) => ({ gap: firstLine(error) }));
+        const fixtureInfo = sources[archetype];
         if (outcome.gap) {
-          archetypes[archetype] = { status: "gap", reason: outcome.gap, configs: [] };
+          archetypes[archetype] = { status: "gap", reason: outcome.gap, configs: [], ...(fixtureInfo?.attempts?.length ? { fixture: { source: "none", attempts: fixtureInfo.attempts } } : {}) };
           gaps.push(`archetype:${archetype}`);
           mapping[archetype].status = "needs-fixture";
           mapping[archetype].reason = outcome.gap;
         } else {
-          archetypes[archetype] = { status: "ran", configs: outcome.configs };
+          archetypes[archetype] = { status: "ran", configs: outcome.configs, ...(fixtureInfo ? { fixture: fixtureInfo } : {}) };
           hidden.push(...outcome.hidden.map((h) => `${archetype}: ${h}`));
         }
       }
@@ -275,11 +362,13 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
         archetypes: ordered,
         npm: {
           name: resolved.name,
+          subpath: resolved.subpath ?? null,
           version: installed.version ?? resolved.version,
           flavor,
           framework: resolved.framework ?? null,
           react: installed.react,
           reactDom: installed.reactDom,
+          vue: installed.vue ?? null,
           tags: flavor === "wc" ? found.tags : [],
         },
         summary: (() => {
@@ -289,6 +378,7 @@ export async function auditNpm({ browser, planTarget, plan, cwd, install = insta
         warnings,
       },
       mapping: Object.fromEntries(Object.entries(mapping).map(([k, v]) => [k, { ...v, fixture: v.fixture ?? null }])),
+      files,
     };
   } finally {
     for (const s of servers) await s.close();