automatica11y 0.4.1 → 0.7.0

package/src/harness/generate/probe.js

@@ -1,3 +1,4 @@
+import { explainFrameworkError } from "../../frameworks/errors.js";
 import { installHelpers } from "../../tiers/interactions/helpers.js";
 import { openPage } from "../url.js";
 import { ROOT_ROLES } from "./marking.js";
@@ -25,9 +26,9 @@ export async function probeFixture(browser, url, archetype) {
     opened = await openPage(browser, url, {
       waitUntil: "load",
       beforeGoto: async (page) => {
-        page.on("pageerror", (error) => errors.push(error.message.split("\n")[0]));
+        page.on("pageerror", (error) => errors.push(explainFrameworkError(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]);
+          if (message.type() === "error" && !/favicon|Failed to load resource/i.test(message.text())) errors.push(explainFrameworkError(message.text().split("\n")[0]));
         });
         await page.addInitScript(installHelpers);
       },
@@ -60,8 +61,8 @@ export async function probeFixture(browser, url, archetype) {
     } 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(
+    /** Wait for the surface. A tooltip gets a second chance below, so this one is short for it. */
+    const waitForSurface = (timeout) => page.waitForFunction(
         ({ live, needsRoot }) => {
           const state = window.__a11y.live();
           if (live) return state.present && state.visible && Boolean(state.text || state.named);
@@ -71,8 +72,18 @@ export async function probeFixture(browser, url, archetype) {
           return (state.present && state.visible) || trigger?.getAttribute("aria-expanded") === "true";
         },
         { live: archetype === "live-region", needsRoot: Boolean(ROOT_ROLES[archetype]) },
-        { timeout: 4000 },
+        { timeout },
       );
+    try {
+      try {
+        await waitForSurface(archetype === "tooltip" ? 1500 : 4000);
+      } catch (error) {
+        if (archetype !== "tooltip") throw error;
+        // Some tooltips open only for focus that came from the keyboard, so focus the trigger again the way a person would.
+        await page.evaluate(() => /** @type {HTMLElement | null} */ (document.activeElement)?.blur());
+        await page.keyboard.press("Tab");
+        await waitForSurface(3000);
+      }
     } 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` };
     }

package/src/harness/npm-install.js

@@ -35,7 +35,7 @@ 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, 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" | "vue" | "wc" | "unknown", run?: typeof runNpm }} options
+ * @param {{ dir: string, name: string, version: string, flavor: "react" | "vue" | "angular" | "svelte" | "html" | "wc" | "unknown", run?: typeof runNpm }} options
  */
 export async function installPackage({ dir, name, version, flavor, run = runNpm }) {
   mkdirSync(dir, { recursive: true });
@@ -66,23 +66,59 @@ export async function installPackage({ dir, name, version, flavor, run = runNpm
   if (flavor === "react") {
     const react = installedVersion(dir, "react");
     if (!react) {
-      await npm(["install", "react", "react-dom", ...NPM_FLAGS, "--legacy-peer-deps"]);
+      await npm(["install", "react", "react-dom", ...pinnedRuntime(dir, ["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")) {
       // 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"]);
+      await npm(["install", `react@${react}`, `react-dom@${react}`, ...pinnedRuntime(dir, ["react", "react-dom"]), ...NPM_FLAGS, "--legacy-peer-deps"]);
     }
   }
   if (flavor === "vue" && !installedVersion(dir, "vue")) {
-    await npm(["install", "vue", ...NPM_FLAGS, "--legacy-peer-deps"]);
+    await npm(["install", "vue", ...pinnedRuntime(dir, ["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) };
+  if (flavor === "svelte" && !installedVersion(dir, "svelte")) {
+    await npm(["install", "svelte", ...pinnedRuntime(dir, ["svelte"]), ...NPM_FLAGS, "--legacy-peer-deps"]);
+    warnings.push(`${name} didn't bring in svelte, so the latest svelte was added.`);
+  }
+  if (flavor === "angular") {
+    // The Angular packages have to be the same version as core. A library's peers usually bring in core and common, not the compiler or the platform.
+    const core = installedVersion(dir, "@angular/core");
+    const missing = ANGULAR_RUNTIME.filter((pkg) => !installedVersion(dir, pkg));
+    if (!core) {
+      await npm(["install", ...ANGULAR_RUNTIME, ...pinnedRuntime(dir, ANGULAR_RUNTIME), ...NPM_FLAGS, "--legacy-peer-deps"]);
+      warnings.push(`${name} didn't bring in @angular/core, so the latest Angular packages were added.`);
+    } else if (missing.length) {
+      // Name everything already installed too. A loose install prunes a package that only arrived as a peer.
+      const adding = missing.map((pkg) => (pkg.startsWith("@angular/") ? `${pkg}@${core}` : pkg));
+      await npm(["install", ...adding, ...pinnedRuntime(dir, adding), ...NPM_FLAGS, "--legacy-peer-deps"]);
+    }
+  }
+  return { dir, warnings, react: installedVersion(dir, "react"), reactDom: installedVersion(dir, "react-dom"), vue: installedVersion(dir, "vue"), angular: installedVersion(dir, "@angular/core"), svelte: installedVersion(dir, "svelte"), 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)}`] : []));
+/** What an Angular fixture needs beside the library: core, the runtime compiler, the platform, and the pieces core uses. */
+const ANGULAR_RUNTIME = ["@angular/core", "@angular/common", "@angular/compiler", "@angular/platform-browser", "rxjs"];
+
+/**
+ * Every package installed at the top level, as exact specs. A loose install (--legacy-peer-deps) prunes a package that only arrived
+ * as someone's peer, which is how React, and then Angular's CDK, went missing. Naming everything that's already there keeps it all.
+ * A spec for a package in `except` is left out, because the caller is installing that one at a different version.
+ * @param {string} dir
+ * @param {string[]} [except] Package names, or specs such as `name@range`.
+ * @returns {string[]}
+ */
+function pinnedRuntime(dir, except = []) {
+  const skip = new Set(except.map((spec) => spec.replace(/^(@?[^@]+)@.*$/, "$1")));
+  const root = join(dir, "node_modules");
+  /** @type {string[]} */
+  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);
+  }
+  return names.filter((name) => !skip.has(name)).flatMap((name) => (installedVersion(dir, name) ? [`${name}@${installedVersion(dir, name)}`] : []));
 }
 
 const PACKAGE_SPEC = /^(@[a-z0-9~][\w.~-]*\/)?[a-z0-9~][\w.~-]*(@[\w.^~<>=*|-]+)?$/i;
@@ -98,7 +134,7 @@ export async function installExtraPackages({ dir, specs, run = runNpm }) {
   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);
+    await run(["install", ...wanted, ...pinnedRuntime(dir, wanted), "--legacy-peer-deps", ...NPM_FLAGS], dir);
   } catch (error) {
     throw new Error(`npm couldn't install ${wanted.join(", ")}: ${firstLine(error.message)}`);
   }
@@ -145,8 +181,8 @@ export async function installOptionalPeers({ dir, unresolved, run = runNpm }) {
   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];
+  const adding = wanted.map((name) => `${name}@${declared.get(name)}`);
+  const specs = [...adding, ...pinnedRuntime(dir, adding)];
   try {
     await run(["install", ...specs, "--legacy-peer-deps", ...NPM_FLAGS], dir);
   } catch (error) {

package/src/harness/shadow.js

@@ -18,7 +18,7 @@ export function recordClosedShadowRoots() {
  * @returns {Promise<Record<string, number>>}
  */
 export async function closedShadowHosts(page) {
-  const hosts = await page.evaluate(() => /** @type {any} */ (window).__a11yClosedShadowHosts ?? []).catch(() => []);
+  const hosts = await page.evaluate(() => window.__a11yClosedShadowHosts ?? []).catch(() => []);
   /** @type {Record<string, number>} */
   const counts = {};
   for (const host of hosts) counts[host] = (counts[host] ?? 0) + 1;

package/src/harness/storybook.js

@@ -16,20 +16,32 @@ export const ARCHETYPE_PATTERNS = {
   chart: /\bcharts?\b|\bgraphs?\b|\bplots?\b/i,
 };
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is unknown[]} */
+function isArray(value) {
+  return Array.isArray(value);
+}
+
 /**
  * Pull the stories out of a Storybook index. Handles `index.json` (`entries`, with docs pages) and the older `stories.json`.
- * @param {any} index
+ * @param {unknown} index
  * @returns {Array<{ id: string, title: string, name: string, tags: string[] }>}
  */
 export function listStories(index) {
-  const table = index.entries ?? index.stories ?? {};
+  const data = isRecord(index) ? index : {};
+  const table = (isRecord(data.entries) ? data.entries : null) ?? (isRecord(data.stories) ? data.stories : {});
   return Object.values(table)
-    .filter((entry) => entry && typeof entry === "object" && (entry.type === undefined || entry.type === "story"))
+    .filter(isRecord)
+    .filter((entry) => entry.type === undefined || entry.type === "story")
     .map((entry) => ({
       id: String(entry.id),
       title: String(entry.title ?? entry.kind ?? ""),
       name: String(entry.name ?? entry.story ?? ""),
-      tags: Array.isArray(entry.tags) ? entry.tags.map(String) : [],
+      tags: isArray(entry.tags) ? entry.tags.map(String) : [],
     }))
     .sort((a, b) => a.id.localeCompare(b.id));
 }
@@ -88,7 +100,8 @@ export function storyUrl(base, id) {
 /**
  * Read a Storybook's index from disk or over HTTP.
  * @param {{ path?: string | null, url?: string | null, index: string }} resolved
- * @param {Function} [doFetch]
+ * @param {(url: URL, options?: { signal?: AbortSignal }) => Promise<{ ok: boolean, status: number, json(): Promise<unknown> }>} [doFetch]
+ * @returns {Promise<unknown>}
  */
 export async function readIndex(resolved, doFetch = globalThis.fetch) {
   if (resolved.path) return JSON.parse(readFileSync(join(resolved.path, resolved.index), "utf8"));

package/src/plan/build-plan.js

@@ -36,6 +36,7 @@ export async function buildPlan({ command, targets, options, browserVersion = nu
       kind: target.kind,
       evidenceLevel: target.evidenceLevel,
       resolved: target.resolved,
+      ...(target.companions?.length ? { companions: target.companions } : {}),
       mapping: null,
     };
   });

package/src/plan/classify.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { cleanSubpath } from "./subpath.js";
 
 /**
- * @typedef {"npm" | "storybook" | "url" | "html-file" | "static-dir"} TargetKind
+ * @typedef {"npm" | "npm-react" | "npm-vue" | "npm-angular" | "npm-svelte" | "npm-html" | "npm-wc" | "npm-unsupported" | "storybook" | "url" | "html-file" | "static-dir"} TargetKind
  * @typedef {{
  *   input: string,
  *   label: string | null,
@@ -15,9 +15,10 @@ import { cleanSubpath } from "./subpath.js";
  *   kind: TargetKind | null,
  *   evidenceLevel: "component" | "page" | null,
  *   resolved: Record<string, string | null> | null,
+ *   companions?: Array<{ name: string, requested: string | null, version: string | null, subpath: string | null }>,
  * }} ClassifiedTarget
  * @typedef {(url: string | URL, init?: { signal?: AbortSignal, redirect?: string }) => Promise<{ ok: boolean, status: number, text(): Promise<string> }>} FetchLike
- * @typedef {{ cwd?: string, home?: string, fetch?: FetchLike, timeoutMs?: number, npmView?: (spec: string) => Promise<any> }} ClassifyContext
+ * @typedef {{ cwd?: string, home?: string, fetch?: FetchLike, timeoutMs?: number, npmView?: (spec: string) => Promise<unknown> }} ClassifyContext
  */
 
 const LOCAL_PATH = /^(\.{1,2}(\/|$)|\/|~(\/|$)|file:)/;
@@ -123,30 +124,57 @@ async function classifyUrl(spec, base, ctx) {
   }
 }
 
-/** @param {string} spec @param {{ input: string, label: string | null, name: string }} base @returns {ClassifiedTarget} */
-function classifyNpm(spec, base) {
+/**
+ * Read one npm spec: `name`, `name@version`, or either with a sub-path.
+ * @param {string} spec
+ * @returns {{ name: string, requested: string | null, subpath: string | null } | { error: string }}
+ */
+function parseNpmSpec(spec) {
   const match = NPM_NAME.exec(spec);
   if (!match) {
-    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);
+    if (/[A-Z]/.test(spec) && NPM_NAME.test(spec.toLowerCase())) return { error: `"${spec}" isn't a valid package name. npm package names are lowercase.` };
+    return { error: `"${spec}" isn't a valid npm package name. Write npm:name, npm:@scope/name, or npm:name@version.` };
   }
   const [, scope, name, version, rawSubpath] = match;
-  if (version === "") return failed(`"${spec}" ends with @ but has no version.`, base);
+  if (version === "") return { error: `"${spec}" ends with @ but has no version.` };
   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);
+    if ("reason" in cleaned) return { error: `"${spec}" isn't a valid sub-path: ${cleaned.reason}. Write npm:name/sub/path or npm:name@version/sub/path.` };
     subpath = /** @type {{ subpath: string }} */ (cleaned).subpath;
   }
-  const full = scope ? `@${scope}/${name}` : name;
+  return { name: scope ? `@${scope}/${name}` : name, requested: version ?? null, subpath };
+}
+
+/**
+ * An npm target. A comma-separated list (`npm:a,b@1.2`) is one target made of several packages that install into one folder.
+ * The first is the primary: it names the target and decides the framework. The rest are companions, such as a script package
+ * that goes with a stylesheet package.
+ * @param {string} spec @param {{ input: string, label: string | null, name: string }} base @returns {ClassifiedTarget}
+ */
+function classifyNpm(spec, base) {
+  const entries = spec.split(",").map((entry) => entry.trim());
+  if (entries.length > 1 && entries.some((entry) => entry === "")) {
+    return failed(`"${spec}" has an empty entry in its list. Write the packages with commas and no spaces, for example npm:a,b.`, base);
+  }
+  const parsed = entries.map(parseNpmSpec);
+  for (const entry of parsed) if ("error" in entry) return failed(entry.error, base);
+  const [primary, ...companions] = /** @type {Array<{ name: string, requested: string | null, subpath: string | null }>} */ (parsed);
+  const seen = new Set();
+  for (const entry of [primary, ...companions]) {
+    const key = `${entry.name}/${entry.subpath ?? ""}`;
+    if (seen.has(key)) return failed(`"${entry.name}${entry.subpath ? `/${entry.subpath}` : ""}" is in the list more than once.`, base);
+    seen.add(key);
+  }
   return {
     ...base,
-    name: base.name || (subpath ? `${full}/${subpath}` : full),
+    name: base.name || (primary.subpath ? `${primary.name}/${primary.subpath}` : primary.name),
     status: "ok",
     reason: null,
     kind: "npm",
     evidenceLevel: "component",
-    resolved: { name: full, requested: version ?? null, version: null, subpath },
+    resolved: { name: primary.name, requested: primary.requested, version: null, subpath: primary.subpath },
+    ...(companions.length ? { companions: companions.map((c) => ({ name: c.name, requested: c.requested, version: null, subpath: c.subpath })) } : {}),
   };
 }
 

package/src/plan/mapping.js

@@ -39,14 +39,14 @@ export function score(archetype, name) {
 }
 
 /**
- * Guess which exports (React or Vue) or tags (web components) stand for each archetype.
+ * Guess which exports (React, Vue, or Angular) 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" | "vue" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
- * @returns {Record<string, any>}
+ * @param {{ flavor: "react" | "vue" | "angular" | "svelte" | "html" | "wc", exports?: Array<{ name: string, type: string, parts: string[] }>, tags?: string[] }} input
+ * @returns {ReturnType<typeof parseMappingFile>[string]}
  */
 export function candidateMapping({ flavor, exports = [], tags = [] }) {
   const names = flavor === "wc" ? tags : exports.filter((e) => /^[A-Z]/.test(e.name)).map((e) => e.name);
-  /** @type {Record<string, any>} */
+  /** @type {ReturnType<typeof parseMappingFile>[string]} */
   const mapping = {};
   for (const archetype of ARCHETYPES) {
     const ranked = names
@@ -64,7 +64,9 @@ export function candidateMapping({ flavor, exports = [], tags = [] }) {
     // 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 !== "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;
+    // A button written as `Button.Root` (a namespace whose only part is the root) is still one element, so a template can use the root.
+    const hasRoot = TEMPLATED.has(archetype) && parts.length === 1 && /^root$/i.test(parts[0]);
+    const templated = TEMPLATED.has(archetype) && (!compound || hasRoot);
     mapping[archetype] = {
       flavor,
       ...(flavor === "wc" ? { tag: best } : { export: best }),
@@ -97,7 +99,7 @@ export function findAuthoredFixture({ cwd, targetId, archetype, mapped }) {
     const file = resolve(cwd, mapped.fixture);
     return existsSync(file) ? file : null;
   }
-  for (const ext of ["jsx", "js"]) {
+  for (const ext of ["jsx", "js", "ts", "svelte", "html"]) {
     const file = resolve(cwd, "fixtures", targetId, `${archetype}.${ext}`);
     if (existsSync(file)) return file;
   }

package/src/plan/resolve-npm.js

@@ -1,11 +1,10 @@
 import { execFile } from "node:child_process";
+import { isAsset } from "../frameworks/html.js";
 import { ADAPTERS } from "../frameworks/index.js";
 import { checkExports, notExportedMessage } from "./subpath.js";
 
-const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated", "exports"];
+const FIELDS = ["name", "version", "peerDependencies", "dependencies", "keywords", "customElements", "deprecated", "exports", "style", "unpkg", "jsdelivr"];
 const OTHER_FRAMEWORKS = {
-  "@angular/core": "Angular",
-  svelte: "Svelte",
   "solid-js": "Solid",
   preact: "Preact",
   "@builder.io/qwik": "Qwik",
@@ -13,11 +12,16 @@ const OTHER_FRAMEWORKS = {
 };
 const WEB_COMPONENT_BASES = ["lit", "lit-element", "@lit/reactive-element", "@stencil/core", "@microsoft/fast-element", "@polymer/polymer"];
 
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * Read a package's registry metadata without installing it.
  * @param {string} spec `name`, `name@version`, or `name@range`
  * @param {{ timeoutMs?: number }} [options]
- * @returns {Promise<any>} The metadata. Throws an Error with a plain reason when the package can't be read.
+ * @returns {Promise<unknown>} The metadata. Throws an Error with a plain reason when the package can't be read.
  */
 export function npmView(spec, { timeoutMs = 60_000 } = {}) {
   return new Promise((resolve, reject) => {
@@ -45,48 +49,75 @@ export function npmView(spec, { timeoutMs = 60_000 } = {}) {
 }
 
 /**
- * Guess how a package renders from its metadata alone. React wins when both signals appear, then a custom elements manifest, then Vue.
+ * Guess how a package renders from its metadata alone. React wins when both signals appear, then a custom elements manifest, then Vue, then Angular.
  * `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-vue" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
+ * @param {unknown} meta
+ * @returns {{ kind: "npm-react" | "npm-vue" | "npm-angular" | "npm-svelte" | "npm-html" | "npm-wc" | "npm-unsupported" | "npm", framework: string | null, reason: string }}
  */
 export function detectFlavor(meta) {
-  const peers = meta.peerDependencies ?? {};
-  const deps = meta.dependencies ?? {};
-  const react = /** @type {any} */ (ADAPTERS.react.detect(meta));
+  const data = isRecord(meta) ? meta : {};
+  const peers = isRecord(data.peerDependencies) ? data.peerDependencies : {};
+  const deps = isRecord(data.dependencies) ? data.dependencies : {};
+  const react = ADAPTERS.react.detect(data);
   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 (data.customElements) return { kind: "npm-wc", framework: "Web components", reason: "The package has a customElements manifest." };
+  const vue = ADAPTERS.vue.detect(data);
   if (vue) return vue;
+  const angular = ADAPTERS.angular.detect(data);
+  if (angular) return angular;
+  const svelte = ADAPTERS.svelte.detect(data);
+  if (svelte) return svelte;
   for (const [name, label] of Object.entries(OTHER_FRAMEWORKS)) {
     if (name in peers) return { kind: "npm-unsupported", framework: label, reason: `The package needs ${label}.` };
   }
   const base = WEB_COMPONENT_BASES.find((name) => name in deps || name in peers);
   if (base) return { kind: "npm-wc", framework: "Web components", reason: `The package builds on ${base}.` };
+  const html = ADAPTERS.html.detect(data);
+  if (html) return html;
   return { kind: "npm", framework: null, reason: "The metadata doesn't say. The run decides after it loads the package." };
 }
 
 /**
  * Fill in a classified npm target: the concrete version and the framework guess.
  * @param {import("./classify.js").ClassifiedTarget} target
- * @param {(spec: string) => Promise<any>} view
+ * @param {(spec: string) => Promise<unknown>} view
  * @returns {Promise<import("./classify.js").ClassifiedTarget>}
  */
 export async function resolveNpmTarget(target, view) {
   if (target.status !== "ok" || target.kind !== "npm" || !target.resolved) return target;
   const { name, requested, subpath } = target.resolved;
   try {
-    const meta = await view(`${name}@${requested ?? "latest"}`);
+    const metadata = await view(`${name}@${requested ?? "latest"}`);
+    if (!isRecord(metadata)) throw new Error("npm returned package metadata in an unreadable shape.");
+    const meta = metadata;
     // 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 }));
+      if (result.checked && !result.ok) throw new Error(notExportedMessage({ name, version: typeof meta.version === "string" ? meta.version : null, subpath, exact: result.exact, patterns: result.patterns }));
+    }
+    let flavor = detectFlavor(meta);
+    // A list that names a stylesheet or a script (`npm:a/components.css,b/interactions.iife.js`) is plain HTML when the metadata names no framework.
+    if (flavor.kind === "npm" && [target.resolved.subpath, ...(target.companions ?? []).map((c) => c.subpath)].some(isAsset)) {
+      flavor = { kind: "npm-html", framework: "HTML", reason: "The target names a stylesheet or a script to load." };
+    }
+    // Each companion is looked up the same way, so a wrong name, version, or sub-path fails here, before anything is installed.
+    /** @type {Array<{ name: string, requested: string | null, version: string | null, subpath: string | null }>} */
+    const companions = [];
+    for (const companion of target.companions ?? []) {
+      const found = await view(`${companion.name}@${companion.requested ?? "latest"}`);
+      if (!isRecord(found)) throw new Error(`npm returned metadata for ${companion.name} in an unreadable shape.`);
+      const version = typeof found.version === "string" ? found.version : null;
+      if (companion.subpath) {
+        const result = checkExports(found.exports, companion.subpath);
+        if (result.checked && !result.ok) throw new Error(notExportedMessage({ name: companion.name, version, subpath: companion.subpath, exact: result.exact, patterns: result.patterns }));
+      }
+      companions.push({ ...companion, version });
     }
-    const flavor = detectFlavor(meta);
     return {
       ...target,
-      kind: /** @type {any} */ (flavor.kind),
-      resolved: { ...target.resolved, version: meta.version ?? null, framework: flavor.framework, detectedBy: flavor.reason },
+      kind: flavor.kind,
+      resolved: { ...target.resolved, version: typeof meta.version === "string" ? meta.version : null, framework: flavor.framework, detectedBy: flavor.reason },
+      ...(companions.length ? { companions } : {}),
     };
   } catch (error) {
     return { ...target, status: "failed", reason: error instanceof Error ? error.message : String(error), kind: null, evidenceLevel: null, resolved: null };

package/src/plan/subpath.js

@@ -77,6 +77,23 @@ export function subpathProblem(workDir, name, subpath, version) {
   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.`;
 }
 
+/**
+ * Sub-paths an installed package offers, as specs a person could pass (`@scope/pkg/button`), for a message that says where
+ * to look when a package's main entry has no components. Patterns and `package.json` are left out.
+ * @param {string} workDir
+ * @param {string} name
+ * @param {number} [limit]
+ * @returns {string[]}
+ */
+export function offeredSubpaths(workDir, name, limit = 4) {
+  try {
+    const manifest = JSON.parse(readFileSync(join(workDir, "node_modules", name, "package.json"), "utf8"));
+    return exportKeys(manifest.exports).exact.slice(0, limit).map((key) => `${name}${key.slice(1)}`);
+  } catch {
+    return [];
+  }
+}
+
 /** 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"];
 

package/src/report/comparison.js

@@ -10,6 +10,8 @@ import {
   configLabel,
   finish,
   hasGenerated,
+  hasNativeTemplates,
+  NATIVE_NOTE,
   notTestableLines,
   reportFooter,
   reportHeader,
@@ -168,7 +170,7 @@ function impactTables(results, engines) {
 /**
  * Render report.md for a comparison of two or more targets.
  * Every target ran with the same settings, so the columns line up. A gap or a failure shows in its cell, and never reads as a pass.
- * @param {{ plan: any, results: any }} input
+ * @param {{ plan: ReturnType<typeof import("../schema.js").parsePlan>, results: ReturnType<typeof import("../schema.js").parseResults> }} input
  */
 export function renderComparison({ plan, results }) {
   const o = plan.options;
@@ -185,6 +187,7 @@ export function renderComparison({ plan, results }) {
   }
   lines.push(...notTestableLines(results));
   if (hasGenerated(results)) lines.push(GENERATED_NOTE, "");
+  if (hasNativeTemplates(results)) lines.push(NATIVE_NOTE, "");
 
   lines.push("## Findings.", "", FINDINGS_NOTE, "", ...(o.tiers.includes("rules") ? impactTables(results, o.engines) : []));
   for (const key of keys) {

package/src/report/index.js

@@ -3,7 +3,7 @@ import { renderSingleReport } from "./single.js";
 
 /**
  * Render report.md. A comparison of two or more targets gets the side-by-side report. Anything else gets the single report.
- * @param {{ plan: any, results: any }} input
+ * @param {{ plan: ReturnType<typeof import("../schema.js").parsePlan>, results: ReturnType<typeof import("../schema.js").parseResults> }} input
  */
 export function renderReport(input) {
   return input.plan.command === "compare" && input.results.targets.length > 1 ? renderComparison(input) : renderSingleReport(input);

package/src/report/parts.js

@@ -2,6 +2,8 @@ import { adapterFor } from "../frameworks/index.js";
 import { criterion, criterionName, wcagAttribution } from "../wcag/index.js";
 import { cap, num, plural } from "../text.js";
 
+/** @typedef {NonNullable<ReturnType<typeof import("../schema.js").parseResults>["targets"][number]["archetypes"][string]["configs"][number]["tiers"][string]["flags"]>[number]} VsrFlag */
+
 /** Markdown helpers. */
 export const cell = (text) => String(text ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
 export const code = (text) => `\`${String(text).replace(/`/g, "'")}\``;
@@ -162,7 +164,7 @@ export function storybookSection(planTarget, target) {
   }
   const walks = Object.entries(target.archetypes).map(([key, a]) => ({ id: key.replace(/^story:/, ""), vsr: a.configs[0]?.tiers.vsr })).filter((w) => w.vsr?.status === "ran");
   if (walks.length) {
-    /** @type {Map<string, { flag: any, stories: string[] }>} */
+    /** @type {Map<string, { flag: VsrFlag, stories: string[] }>} */
     const byFlag = new Map();
     for (const { id, vsr } of walks) for (const flag of vsr.flags) {
       const key = `${flag.type}|${flag.phrase}`;
@@ -265,6 +267,14 @@ export function hasGenerated(results) {
   return results.targets.some((t) => Object.values(t.archetypes ?? {}).some((a) => a.fixture?.source === "generated"));
 }
 
+/** True when a plain HTML target ran from a native-markup template. */
+export function hasNativeTemplates(results) {
+  return results.targets.some((t) => t.npm?.flavor === "html" && Object.values(t.archetypes ?? {}).some((a) => a.fixture?.source === "template"));
+}
+
+/** What a plain HTML template is, and what it can't say about a package. */
+export const NATIVE_NOTE = "**Native markup templates.** For a plain HTML target the tool used bare native markup (a button, a link, a fieldset, a dialog, details, a popover) with none of the package's classes, so these results show what the package's styles and scripts do to ordinary elements. They don't test a component the package built, and a pass here never means the package's own components pass. A check that needs script behavior the markup doesn't have, such as arrow keys in a menu, measures the bare markup and not the package. Bring a fixture of your own to test the package's components.";
+
 /** 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.";
 
@@ -279,6 +289,7 @@ export function targetSection(planTarget, target, { generatedNote = true } = {})
   if (target.npm) {
     const n = target.npm;
     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)}.`, "");
+    if (n.companions?.length) lines.push(`Installed beside it, in the same folder: ${n.companions.map((c) => code(`${c.name}@${c.version}${c.subpath ? `/${c.subpath}` : ""}`)).join(", ")}.`, "");
   }
   for (const warning of target.warnings) lines.push(`Warning: ${warning}`, "");
   if (target.status === "failed") {
@@ -286,6 +297,7 @@ export function targetSection(planTarget, target, { generatedNote = true } = {})
   }
   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, "");
+  if (generatedNote && target.npm && hasNativeTemplates({ targets: [target] })) lines.push(NATIVE_NOTE, "");
   /** @type {Set<string>} */
   const skipped = new Set();
   for (const [name, archetype] of Object.entries(target.archetypes)) {

package/src/report/single.js

@@ -2,7 +2,7 @@ import { FINDINGS_NOTE, coverageMatrix, finish, failCheckSection, notTestableLin
 
 /**
  * Render report.md for an audit. The text comes from results.json and nothing else.
- * @param {{ plan: any, results: any }} input
+ * @param {{ plan: ReturnType<typeof import("../schema.js").parsePlan>, results: ReturnType<typeof import("../schema.js").parseResults> }} input
  */
 export function renderSingleReport({ plan, results }) {
   const lines = reportHeader(plan, results, "Accessibility report.");