automatica11y 0.4.1 → 0.6.0

package/src/frameworks/angular.js

@@ -0,0 +1,156 @@
+/**
+ * The Angular adapter, for Angular 22 and newer. Angular libraries ship partially compiled, and Angular compiles them in the
+ * browser (JIT) once `@angular/compiler` is loaded, so nothing here runs the Angular linker or a TypeScript transform.
+ * A fixture is plain JavaScript that defines a component by calling the `Component` decorator as a function (see the fixtures
+ * guide). Every framework adapter has this shape (see index.js).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { generateAngular } from "../harness/generate/angular-recipes.js";
+import { attributeText, markupFor } from "./angular-selectors.js";
+
+/** The oldest Angular this version supports. */
+export const ANGULAR_FLOOR = 22;
+const FLOOR = ANGULAR_FLOOR;
+
+/**
+ * Does a peer range allow Angular 22 or newer? A part counts when it names version 22 or later, or has no upper limit (`>=15`, `*`).
+ * `^20 || ^21` doesn't, and `^21 || ^22` does.
+ */
+function allowsSupported(range) {
+  return String(range)
+    .split("||")
+    .some((part) => {
+      const text = part.trim();
+      const major = /(\d+)/.exec(text);
+      if (!major || /^[*x]?$/.test(text)) return true;
+      if (/^>=?/.test(text)) return true;
+      return Number(major[1]) >= FLOOR;
+    });
+}
+
+/**
+ * Loads the compiler, then the whole target, and records what each Angular export is: its kind, selectors, inputs, outputs,
+ * `exportAs`, and whether it's standalone. Services get their method names, and modules the classes they declare.
+ * Exports with no Angular definition (functions, tokens, types) are left out.
+ */
+export const discoverEntry = (pkg) => `import "@angular/compiler";
+import * as lib from ${JSON.stringify(pkg)};
+// A class can be exported under more than one name (a button that is also the anchor), and each name is a record.
+const namesOf = new Map();
+for (const key of Object.keys(lib)) if (typeof lib[key] === "function") namesOf.set(lib[key], [...(namesOf.get(lib[key]) ?? []), key]);
+const listed = (items) => (typeof items === "function" ? items() : items) ?? [];
+const out = [];
+for (const key of Object.keys(lib)) {
+  const value = lib[key];
+  if (typeof value !== "function") continue;
+  try {
+    const cmp = value["ɵcmp"];
+    const dir = value["ɵdir"];
+    const mod = value["ɵmod"];
+    const def = cmp ?? dir;
+    if (def) {
+      out.push({ name: key, type: "function", parts: [], angular: { kind: cmp ? "component" : "directive", selectors: def.selectors ?? [], inputs: Object.keys(def.inputs ?? {}), outputs: Object.keys(def.outputs ?? {}), exportAs: def.exportAs ?? [], standalone: Boolean(def.standalone) } });
+    } else if (mod) {
+      const named = (items) => listed(items).flatMap((c) => namesOf.get(c) ?? []);
+      out.push({ name: key, type: "function", parts: [], angular: { kind: "module", declares: named(mod.declarations), exports: named(mod.exports) } });
+    } else if (value["ɵprov"]) {
+      const methods = Object.getOwnPropertyNames(value.prototype ?? {}).filter((m) => m !== "constructor" && !m.startsWith("ɵ") && typeof value.prototype[m] === "function");
+      out.push({ name: key, type: "function", parts: [], angular: { kind: "service", methods } });
+    }
+  } catch (error) {
+    out.push({ name: key, type: "function", parts: [], angular: { kind: "error", message: String(error).split("\\n")[0] } });
+  }
+}
+// A component that isn't standalone is used through the module that declares it.
+for (const item of out) {
+  if (item.angular.kind === "module" || item.angular.standalone !== false) continue;
+  item.angular.moduleName = out.find((m) => m.angular.kind === "module" && m.angular.declares.includes(item.name))?.name ?? null;
+}
+window.__a11yExports = out;
+`;
+
+/**
+ * Mounts a fixture. The runtime compiler goes first. `zone.js` is loaded only when a library brought it in, because Angular 22
+ * runs without it. The fixture's default export is its component class, and an optional `providers` export adds application providers.
+ * A failure to start is logged and kept on `window.__error`, so the report can say why.
+ */
+export const entry = (fixturePath, _pkg, context = {}) => `import "@angular/compiler";
+${context.zone ? 'import "zone.js";\n' : ""}import { bootstrapApplication } from "@angular/platform-browser";
+import * as fixture from ${JSON.stringify(fixturePath)};
+const Fixture = fixture.default;
+const selector = Fixture?.["ɵcmp"]?.selectors?.[0]?.[0] || "app-fixture";
+document.getElementById("root").append(document.createElement(selector));
+try {
+  await bootstrapApplication(Fixture, { providers: fixture.providers ?? [] });
+} catch (error) {
+  window.__error = String(error);
+  console.error(error);
+}
+`;
+
+/**
+ * A fixture for a button or a link, from the class's own selector. A class that isn't standalone is imported through its module.
+ * A class whose selector can't be written from its name alone (a class name, a :not() form) is left for a person to write.
+ */
+export function template(archetype, pkg, exportName, info) {
+  const want = { button: "button", link: "a" }[archetype];
+  const angular = info?.angular;
+  if (!want || !angular || (angular.kind !== "component" && angular.kind !== "directive")) return null;
+  // A button class may name its own element (`p-button`), which a link class may not: a link has to be an anchor.
+  const match = markupFor(angular.selectors, { prefer: want }) ?? (archetype === "button" ? markupFor(angular.selectors, {}) : null);
+  if (!match || (archetype === "link" && match.tag !== want)) return null;
+  const imports = angular.standalone ? [exportName] : angular.moduleName ? [angular.moduleName] : null;
+  if (!imports) return null;
+  const attrs = [attributeText(match.attrs), "data-a11y-trigger", "data-a11y-root", want === "a" ? 'href="#top"' : 'type="button"'].filter(Boolean).join(" ");
+  const html = `<${match.tag} ${attrs}>${want === "a" ? "Read more" : "Save"}</${match.tag}>`;
+  return `import { Component } from "@angular/core";
+import { ${imports.join(", ")} } from ${JSON.stringify(pkg)};
+
+class Fixture {}
+Component({ selector: "app-fixture", imports: [${imports.join(", ")}], template: \`${html}\` })(Fixture);
+export default Fixture;
+`;
+}
+
+/** Keeps one copy of every Angular package and of rxjs, so a library and a fixture never load two. Secondary entry points need the resolver, not an alias. */
+function singleCopy(workDir) {
+  return {
+    name: "single-angular-copy",
+    setup(build) {
+      build.onResolve({ filter: /^(@angular\/|rxjs(\/|$)|zone\.js(\/|$))/ }, async (args) => {
+        if (args.pluginData === "single-angular-copy") return undefined;
+        const result = await build.resolve(args.path, { resolveDir: workDir, kind: args.kind, pluginData: "single-angular-copy" });
+        return result.errors.length ? undefined : result;
+      });
+    },
+  };
+}
+
+export default {
+  id: "angular",
+  label: "Angular",
+  kind: "npm-angular",
+  noun: "export",
+  extension: "js",
+  runtime: ["@angular/core", "@angular/common", "@angular/compiler", "@angular/platform-browser", "rxjs"],
+  /** @returns {import("./index.js").AdapterDetection | null} */
+  detect(meta) {
+    const peers = meta.peerDependencies ?? {};
+    const deps = meta.dependencies ?? {};
+    const range = peers["@angular/core"] ?? deps["@angular/core"];
+    if (range === undefined) return null;
+    if (!allowsSupported(range)) return { kind: "npm-unsupported", framework: "Angular", reason: `The package needs @angular/core ${range}. Only Angular ${FLOOR} and newer is supported.` };
+    return { kind: "npm-angular", framework: "Angular", reason: `The package lists @angular/core as a ${"@angular/core" in peers ? "peer dependency" : "dependency"}.` };
+  },
+  /** What the install left behind that the entry needs to know about. */
+  inspect: (workDir) => ({ zone: existsSync(join(workDir, "node_modules", "zone.js")) }),
+  // Fixtures can be TypeScript. esbuild strips the types, and legacy decorators are what Angular's JIT reads. It can't emit
+  // constructor parameter metadata, so a TypeScript fixture gets its services from inject().
+  bundle: (workDir) => ({ alias: {}, plugins: [singleCopy(workDir)], esbuild: { tsconfigRaw: { compilerOptions: { experimentalDecorators: true, useDefineForClassFields: false } } } }),
+  entry,
+  discoverEntry,
+  template,
+  generate: (input) => generateAngular(input),
+  describe: (npm) => `Angular${npm.angular ? ` (core ${npm.angular})` : ""}`,
+};

package/src/frameworks/html.js

@@ -0,0 +1,163 @@
+/**
+ * The plain HTML adapter, for packages with no framework: stylesheets, and scripts that wire up behavior on markup the page
+ * already has. A fixture is a snippet of markup. The tool loads the target's stylesheets, puts the markup on the page, then
+ * loads the scripts, so a script that looks for its elements when it starts finds them.
+ *
+ * What loads is named by the target itself. In a list such as `npm:a/components.css,b/interactions.iife.js`, an entry whose
+ * sub-path ends in `.css` is a stylesheet, and one that ends in `.js` or `.mjs` is a script. Every other entry is just a package.
+ */
+
+const STYLE = /\.css$/i;
+const SCRIPT = /\.(m?js)$/i;
+
+/** @param {string | null | undefined} subpath */
+export const isStyle = (subpath) => Boolean(subpath && STYLE.test(subpath));
+/** @param {string | null | undefined} subpath */
+export const isScript = (subpath) => Boolean(subpath && SCRIPT.test(subpath));
+/** Is this sub-path a file the page loads, rather than something a framework imports? */
+export const isAsset = (subpath) => isStyle(subpath) || isScript(subpath);
+
+/**
+ * The stylesheets and scripts a list of packages names, in the order they were written.
+ * @param {Array<{ name: string, subpath: string | null }>} entries
+ * @returns {{ styles: string[], scripts: string[] }}
+ */
+export function assetsOf(entries) {
+  const spec = (entry) => `${entry.name}/${entry.subpath}`;
+  return {
+    styles: entries.filter((entry) => isStyle(entry.subpath)).map(spec),
+    scripts: entries.filter((entry) => isScript(entry.subpath)).map(spec),
+  };
+}
+
+/**
+ * Does the registry's metadata say a package is plain HTML and CSS? It has to ship a stylesheet or a browser script, and it can't
+ * need a framework (those are decided before this runs).
+ * @param {any} meta
+ */
+export function shipsBrowserAssets(meta) {
+  if (typeof meta?.style === "string" || typeof meta?.unpkg === "string" || typeof meta?.jsdelivr === "string") return true;
+  const keys = meta?.exports && typeof meta.exports === "object" ? Object.keys(meta.exports) : [];
+  return keys.some((key) => STYLE.test(key) || /\.(iife|umd)\.m?js$/.test(key));
+}
+
+/** Does the package have a JavaScript entry to import? Then loading it is what tells plain HTML from web components. */
+function hasScriptEntry(meta) {
+  if (typeof meta?.main === "string" || typeof meta?.module === "string") return true;
+  const exported = meta?.exports;
+  if (typeof exported === "string") return true;
+  return Boolean(exported && typeof exported === "object" && exported["."]);
+}
+
+/**
+ * Mounts a fixture. The stylesheets come first, as imports, so they load with the page. The markup goes on the page next. A
+ * `<script>` inside the markup is made again so the browser runs it, because markup set by the page never runs its scripts.
+ * Then the target's scripts load, one after the other.
+ * @param {string} fixturePath
+ * @param {string} _pkg
+ * @param {{ assets?: { styles: string[], scripts: string[] } }} [context]
+ */
+export const entry = (fixturePath, _pkg, context = {}) => {
+  const { styles = [], scripts = [] } = context.assets ?? {};
+  return `${styles.map((spec) => `import ${JSON.stringify(spec)};`).join("\n")}
+import markup from ${JSON.stringify(fixturePath)};
+const root = document.getElementById("root");
+root.innerHTML = markup;
+for (const old of [...root.querySelectorAll("script")]) {
+  const script = document.createElement("script");
+  for (const { name, value } of old.attributes) script.setAttribute(name, value);
+  script.textContent = old.textContent;
+  old.replaceWith(script);
+}
+try {
+${scripts.map((spec) => `  await import(${JSON.stringify(spec)});`).join("\n")}
+} catch (error) {
+  window.__error = String(error);
+  console.error(error);
+}
+`;
+};
+
+/**
+ * The bare native markup for an archetype, with no class names and nothing guessed from a stylesheet. It tests what the target's
+ * styles and scripts do to ordinary elements. A component built on classes needs a fixture a person writes. The browser does the
+ * opening and closing (`<dialog>`, `<details>`, popovers), so a template needs no script of its own except where there's no
+ * native way (a dialog's trigger, a message that appears).
+ */
+const TEMPLATES = {
+  button: '<button type="button" data-a11y-trigger data-a11y-root>Save</button>\n',
+  link: '<a href="#top" data-a11y-trigger data-a11y-root>Read more</a>\n',
+  "form-field": `<fieldset data-a11y-root>
+  <legend>Contact details</legend>
+  <p><label for="name">Name</label> <input id="name" name="name" type="text" autocomplete="name" data-a11y-trigger></p>
+  <p><label for="about">About you</label> <textarea id="about" name="about"></textarea></p>
+  <p><label for="size">Size</label> <select id="size" name="size"><option>Small</option><option>Medium</option><option>Large</option></select></p>
+  <p><input id="news" name="news" type="checkbox"> <label for="news">Send me news</label></p>
+  <fieldset>
+    <legend>Contact me by</legend>
+    <p><input id="by-email" name="by" type="radio" value="email"> <label for="by-email">Email</label></p>
+    <p><input id="by-phone" name="by" type="radio" value="phone"> <label for="by-phone">Phone</label></p>
+  </fieldset>
+  <p><label for="email">Email address</label> <input id="email" name="email" type="email" aria-invalid="true" aria-describedby="email-error"> <span id="email-error">Enter an email address like name@example.com.</span></p>
+</fieldset>
+`,
+  dialog: `<button type="button" id="open-dialog" data-a11y-trigger>Open dialog</button>
+<dialog id="dialog" data-a11y-root aria-labelledby="dialog-title">
+  <h2 id="dialog-title">Edit profile</h2>
+  <p>Update your details.</p>
+  <form method="dialog"><button>Close</button></form>
+</dialog>
+<script>document.getElementById("open-dialog").addEventListener("click", () => document.getElementById("dialog").showModal());</script>
+`,
+  accordion: `<details name="faq">
+  <summary data-a11y-trigger>Shipping</summary>
+  <div data-a11y-root><p>Orders ship within two business days.</p></div>
+</details>
+<details name="faq">
+  <summary>Returns</summary>
+  <div><p>Returns are free for 30 days.</p></div>
+</details>
+`,
+  "live-region": `<button type="button" id="show-message" data-a11y-trigger>Show message</button>
+<div id="message-region" role="status" data-a11y-root></div>
+<script>document.getElementById("show-message").addEventListener("click", () => {
+  document.getElementById("message-region").textContent = "Saved.";
+});</script>
+`,
+  menu: `<button type="button" data-a11y-trigger popovertarget="actions" aria-haspopup="menu">Actions</button>
+<div id="actions" popover data-a11y-root role="menu" aria-label="Actions">
+  <button type="button" role="menuitem">Copy</button>
+  <button type="button" role="menuitem">Paste</button>
+</div>
+`,
+  tooltip: `<button type="button" data-a11y-trigger interestfor="save-tip">Save</button>
+<div id="save-tip" popover="hint" role="tooltip" data-a11y-root>Saves your work.</div>
+`,
+};
+
+export default {
+  id: "html",
+  label: "HTML",
+  kind: "npm-html",
+  noun: "element",
+  extension: "html",
+  runtime: [],
+  /** @returns {import("./index.js").AdapterDetection | null} */
+  detect(meta) {
+    // A package that also has a JavaScript entry could be web components, so the run decides after it loads the package.
+    if (!shipsBrowserAssets(meta) || hasScriptEntry(meta)) return null;
+    return { kind: "npm-html", framework: "HTML", reason: "The package ships a stylesheet or a browser script and needs no framework." };
+  },
+  /** What the page loads, from the packages the target lists. */
+  inspect: (/** @type {string} */ _workDir, /** @type {Array<{ name: string, subpath: string | null }>} */ entries = []) => ({ assets: assetsOf(entries) }),
+  bundle: () => ({ alias: {}, esbuild: { loader: { ".html": /** @type {"text"} */ ("text") } } }),
+  entry,
+  discoverEntry: () => "window.__a11yExports = [];\n",
+  template: (/** @type {string} */ archetype) => TEMPLATES[/** @type {keyof typeof TEMPLATES} */ (archetype)] ?? null,
+  generate: () => ({ candidates: [], reason: "Plain HTML has no exports or selectors to build a fixture from." }),
+  describe: (npm) => {
+    const loaded = /** @type {any} */ (npm).assets;
+    return `plain HTML${loaded ? ` (${loaded.styles.length} ${loaded.styles.length === 1 ? "stylesheet" : "stylesheets"}, ${loaded.scripts.length} ${loaded.scripts.length === 1 ? "script" : "scripts"})` : ""}`;
+  },
+};
+

package/src/frameworks/index.js

@@ -6,6 +6,8 @@
  * To add a framework, write a module with the same shape as react.js, add it here, and add its id to FLAVORS and its kind to
  * TARGET_KINDS in schema.js. A test checks that the two lists agree.
  *
+ * @typedef {"npm-react" | "npm-vue" | "npm-angular" | "npm-html" | "npm-wc" | "npm-unsupported"} AdapterKind
+ * @typedef {{ kind: AdapterKind, framework: string, reason: string }} AdapterDetection
  * @typedef {{
  *   id: string,
  *   label: string,
@@ -13,21 +15,24 @@
  *   noun: string,
  *   extension: string,
  *   runtime: string[],
- *   detect: (meta: any) => { kind: string, framework: string, reason: string } | null,
- *   bundle: (workDir: string) => { alias: Record<string, string>, define?: Record<string, string>, esbuild: Record<string, any> },
- *   entry: (fixturePath: string, pkg: string) => string,
+ *   detect: (meta: unknown) => AdapterDetection | null,
+ *   inspect?: (workDir: string, entries?: Array<{ name: string, subpath: string | null }>) => Record<string, unknown>,
+ *   bundle: (workDir: string) => { alias: Record<string, string>, define?: Record<string, string>, plugins?: import("esbuild").Plugin[], esbuild: import("esbuild").BuildOptions },
+ *   entry: (fixturePath: string, pkg: string, context?: Record<string, unknown>) => string,
  *   discoverEntry: (pkg: string) => string,
- *   template: (archetype: string, pkg: string, name?: string) => string | null,
- *   generate: (input: any) => { candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null },
- *   describe: (npm: any) => string,
+ *   template: (archetype: string, pkg: string, name?: string, info?: unknown) => string | null,
+ *   generate: (input: unknown) => { candidates: Array<{ id: string, summary: string, source: string, used: string[] }>, reason: string | null },
+ *   describe: (npm: unknown) => string,
  * }} Adapter
  */
+import angular from "./angular.js";
+import html from "./html.js";
 import react from "./react.js";
 import vue from "./vue.js";
 import wc from "./wc.js";
 
 /** @type {Record<string, Adapter>} */
-export const ADAPTERS = { react, vue, wc };
+export const ADAPTERS = { react, vue, angular, html, wc };
 
 /** The adapter for a flavor (`react`, `vue`, or `wc`). */
 export function adapterFor(id) {

package/src/frameworks/react.js

@@ -55,6 +55,7 @@ export default {
   /** Packages the fixture and the library must share one copy of, and that the install makes sure are there. */
   runtime: ["react", "react-dom"],
   /** Is this package React, from its registry metadata alone? */
+  /** @returns {import("./index.js").AdapterDetection | null} */
   detect(meta) {
     const peers = meta.peerDependencies ?? {};
     const deps = meta.dependencies ?? {};
@@ -66,7 +67,7 @@ export default {
   bundle: (workDir) => ({
     // One copy of React for the library and the fixture, or hooks break.
     alias: { react: join(workDir, "node_modules", "react"), "react-dom": join(workDir, "node_modules", "react-dom") },
-    esbuild: { jsx: "automatic" },
+    esbuild: { jsx: /** @type {"automatic"} */ ("automatic") },
   }),
   entry,
   discoverEntry,

package/src/frameworks/vue.js

@@ -62,6 +62,7 @@ export default {
   noun: "export",
   extension: "jsx",
   runtime: ["vue"],
+  /** @returns {import("./index.js").AdapterDetection | null} */
   detect(meta) {
     const peers = meta.peerDependencies ?? {};
     const deps = meta.dependencies ?? {};
@@ -79,7 +80,7 @@ export default {
       alias: { vue: join(workDir, "node_modules", "vue") },
       define: { __VUE_OPTIONS_API__: "true", __VUE_PROD_DEVTOOLS__: "false", __VUE_PROD_HYDRATION_MISMATCH_DETAILS__: "false" },
       // Vue has no JSX runtime of its own, so JSX becomes h() calls. The shim is injected wherever h or Fragment is used without being declared.
-      esbuild: { jsx: "transform", jsxFactory: "h", jsxFragment: "Fragment", inject: [shim] },
+      esbuild: { jsx: /** @type {"transform"} */ ("transform"), jsxFactory: "h", jsxFragment: "Fragment", inject: [shim] },
     };
   },
   entry,

package/src/globals.d.ts

@@ -1,12 +1,129 @@
 /** Properties our init scripts and helpers put on the page's window. They only exist inside the browser. */
+type A11yColor = number[];
+type A11yBox = { x: number; y: number; width: number; height: number };
+type A11yTextPart = { key: number; text: string; color: A11yColor | null; size: number; weight: string; backdrop: A11yColor | null; undetermined: string | null };
+type A11yFocusPart = {
+  outlineStyle: string;
+  outlineWidth: string;
+  outlineColor: string;
+  boxShadow: string;
+  borderTopStyle: string;
+  borderTopColor: string;
+  borderTopWidth: string;
+  backgroundColor: string;
+  color: string;
+  textDecorationLine: string;
+  rendered: boolean;
+};
+type A11yFocusSnapshot = { parts: Record<string, A11yFocusPart>; box: A11yBox };
+
+interface A11yHelpers {
+  uid(node: Node | null): number | null;
+  queryDeep(selector: string): Element | null;
+  queryAllDeep(selector: string): Element[];
+  deepActive(): Element | null;
+  within(root: Node | null, node: Node | null): boolean;
+  visible(element: Element | null): boolean;
+  snapshot(): {
+    clicks: number;
+    triggerTag: string | null;
+    triggerRole: string | null;
+    expanded: string | null;
+    rootExists: boolean;
+    rootVisible: boolean;
+    rootModal: boolean;
+    activeIsTrigger: boolean;
+    activeInRoot: boolean;
+    activeUid: number | null;
+    activeTag: string | null;
+    activeText: string;
+    activeRole: string | null;
+    bodyActive: boolean;
+  };
+  items(selector: string): Array<{ uid: number | null; text: string; active: boolean; selected: boolean; hasSelected: boolean; visible: boolean }>;
+  live(): {
+    ancestorUids: Array<number | null>;
+    present: boolean;
+    visible: boolean;
+    text: string;
+    named: boolean;
+    region: { uid: number | null; role: string | null; ariaLive: string | null; politeness: string; isMessage: boolean } | null;
+    regionUids: Array<number | null>;
+  };
+  focusDismiss(): { found: false } | { found: true; tag: string; label: string };
+  nameSources(): string[] | null;
+  errorInfo(): { invalid: boolean; ariaInvalid: boolean; linked: string[]; live: string[] } | null;
+  focusSnapshot(): A11yFocusSnapshot | null;
+  remember(): void;
+  lastSnapshot(): A11yFocusSnapshot | null;
+  inputValue(): string | null;
+}
+
+interface A11yMeasure {
+  rgba(css: string): A11yColor | null;
+  text(scope?: string): A11yTextPart[] | null;
+  boundary(): {
+    outside: A11yColor | null;
+    undetermined: string | null;
+    parts: Array<{ kind: string; color: A11yColor; width?: number }>;
+    graphics: Array<{ kind: string; color: A11yColor }>;
+    hasText: boolean;
+    inputLike: boolean;
+    box: A11yBox;
+  } | null;
+  focusStyles(atRest: boolean): {
+    outside: A11yColor | null;
+    inside: A11yColor | null;
+    undetermined: string | null;
+    outline: { width: number; offset: number; color: A11yColor | null } | null;
+    shadows: Array<{ inset: boolean; x: number; y: number; blur: number; spread: number; color: A11yColor | null }>;
+    border: { width: number; color: A11yColor } | null;
+    box: A11yBox;
+  } | null;
+  compareShots(before: string, after: string): Promise<{ changed: number; strong: number; max: number; width: number; height: number }>;
+}
+
+interface A11yConditions {
+  describe(element: Element | null): string;
+  animations(): Array<{ kind: string; name: string; target: string; duration: number | null; iterations: number | "infinite"; props: string[]; moving: boolean }>;
+  overflow(rootSelector?: string): {
+    viewportWidth: number;
+    scrollWidth: number;
+    offenders: Array<{ element: string; right: number; width: number; left: number }>;
+    offenderCount: number;
+    root: { element: string; left: number; right: number } | null;
+  };
+  clipping(): Array<{ visuallyHidden: boolean; element: string; hidesX: boolean; hidesY: boolean; overX: number; overY: number; text: string }>;
+  applySpacing(): void;
+  translucentSurfaces(): Array<{ element: string; background: string; backdropFilter: string }>;
+  forcedColorOptOuts(): string[];
+  appearance(): { colorScheme: string; background: string; color: string };
+}
+
+interface PackageExport {
+  name: string;
+  type: string;
+  parts: string[];
+}
+
+type AngularExportInfo =
+  | { kind: "component" | "directive"; selectors: Array<Array<string | number>>; inputs: string[]; outputs: string[]; exportAs: string[]; standalone: boolean; moduleName?: string | null }
+  | { kind: "module"; declares: string[]; exports: string[] }
+  | { kind: "service"; methods: string[] }
+  | { kind: "error"; message: string };
+
+interface AngularPackageExport extends PackageExport {
+  angular: AngularExportInfo;
+}
+
 interface Window {
-  __a11y: any;
-  __a11yMeasure: any;
-  __a11yConditions: any;
-  __vsr: any;
+  __a11y: A11yHelpers;
+  __a11yMeasure: A11yMeasure;
+  __a11yConditions: A11yConditions;
+  __vsr: Pick<typeof import("@guidepup/virtual-screen-reader"), "Virtual" | "virtual">;
   __a11yClicks: number;
-  __a11yLast: any;
-  __a11yExports?: any;
+  __a11yLast: Element | null;
+  __a11yExports?: Array<PackageExport | AngularPackageExport>;
   __a11yDefined?: string[];
   __a11yClosedShadowHosts?: string[];
 }

package/src/harness/bundle.js

@@ -42,7 +42,8 @@ export async function bundleEntries({ entries, outdir, workDir, framework = null
       absWorkingDir: workDir,
       nodePaths: [join(workDir, "node_modules")],
       alias: settings.alias,
-      loader: ASSET_LOADERS,
+      plugins: settings.plugins ?? [],
+      loader: { ...ASSET_LOADERS, ...(settings.esbuild.loader ?? {}) },
       define: { "process.env.NODE_ENV": '"development"', ...(settings.define ?? {}) },
       logLevel: "silent",
     });