automatica11y 0.4.1 → 0.7.0

package/src/frameworks/angular.js

@@ -0,0 +1,162 @@
+/**
+ * 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) {
+      // A library asks for the same few Angular paths over and over, so each is looked up once per build.
+      /** @type {Map<string, Promise<import("esbuild").OnResolveResult | undefined>>} */
+      const resolved = new Map();
+      build.onResolve({ filter: /^(@angular\/|rxjs(\/|$)|zone\.js(\/|$))/ }, (args) => {
+        if (args.pluginData === "single-angular-copy") return undefined;
+        const key = `${args.kind}\0${args.path}`;
+        if (!resolved.has(key)) {
+          resolved.set(key, build.resolve(args.path, { resolveDir: workDir, kind: args.kind, pluginData: "single-angular-copy" }).then((result) => (result.errors.length ? undefined : result)));
+        }
+        return resolved.get(key);
+      });
+    },
+  };
+}
+
+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/errors.js

@@ -0,0 +1,12 @@
+import { explainAngularError } from "./angular-errors.js";
+import { explainSvelteError } from "./svelte-errors.js";
+
+/**
+ * One place that turns a framework's own error into a plain sentence, for any framework. The codes and wording don't overlap,
+ * so each explainer leaves what isn't its own alone.
+ * @param {string} text The first line of an error.
+ * @returns {string}
+ */
+export function explainFrameworkError(text) {
+  return explainAngularError(explainSvelteError(text));
+}

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-svelte" | "npm-html" | "npm-wc" | "npm-unsupported"} AdapterKind
+ * @typedef {{ kind: AdapterKind, framework: string, reason: string }} AdapterDetection
  * @typedef {{
  *   id: string,
  *   label: string,
@@ -13,21 +15,25 @@
  *   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 svelte from "./svelte.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, svelte, html, wc };
 
 /** The adapter for a flavor (`react`, `vue`, or `wc`). */
 export function adapterFor(id) {

package/src/frameworks/react.js

@@ -31,10 +31,13 @@ window.__a11yExports = out;
  * A fixture for the simple archetypes, from the export name alone.
  * Compound components (dialog, tabs, menu) can't be guessed, so they come from generation or from a fixture someone writes.
  */
-export function template(archetype, pkg, exportName) {
+export function template(archetype, pkg, exportName, info) {
+  // A namespace with a root part (`Button.Root`) is used through its root.
+  const root = /** @type {any} */ (info)?.parts?.find((part) => /^root$/i.test(part));
+  const tag = root ? `Component.${root}` : "Component";
   const body = {
-    button: `<Component data-a11y-trigger data-a11y-root type="button">Save</Component>`,
-    link: `<Component data-a11y-trigger data-a11y-root href="#top">Read more</Component>`,
+    button: `<${tag} data-a11y-trigger data-a11y-root type="button">Save</${tag}>`,
+    link: `<${tag} data-a11y-trigger data-a11y-root href="#top">Read more</${tag}>`,
   }[archetype];
   if (!body) return null;
   return `import { ${exportName} as Component } from ${JSON.stringify(pkg)};
@@ -55,6 +58,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 +70,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/svelte-errors.js

@@ -0,0 +1,30 @@
+/**
+ * Svelte's own errors point at its source and its docs. A report is read without either, so the ones a fixture is likely to hit
+ * get a plain sentence. Anything else passes through.
+ * @param {string} text The first line of an error.
+ * @returns {string}
+ */
+export function explainSvelteError(text) {
+  // A library written for SvelteKit imports modules that only exist inside a SvelteKit app.
+  const kit = /Could not resolve "(\$(?:app|env|lib|service-worker)(?:\/[^"]*)?)"/.exec(text);
+  if (kit) return `the library imports ${kit[1]}, which only exists inside a SvelteKit app, so it can't run on its own (${text.split(" (")[0].replace(/^Bundling failed: /, "")})`;
+  const code = /svelte\.dev\/e\/(\w+)/.exec(text)?.[1];
+  const name = /["'`]([\w$.-]+)["'`]/.exec(text)?.[1];
+  if (/missing_context|Context "?[^"]*"? not found|Could not find .*context|getContext\(\) .*undefined|Cannot read properties of undefined \(reading 'getContext'\)/i.test(text) || code === "missing_context") {
+    return `a part of the library needs a context that its parent part provides${name ? ` (${name})` : ""}. Put it inside its root part${code ? ` (${code})` : ""}`;
+  }
+  if (code === "lifecycle_outside_component" || /can only be used during component initiali[sz]ation/i.test(text)) {
+    return "the library called a lifecycle or context function outside a component, so it can't be mounted this way (lifecycle_outside_component)";
+  }
+  if (code === "props_invalid_value" || code === "invalid_default_snippet" || code === "snippet_without_render_tag") {
+    return `a component got a value of the wrong kind for a prop${name ? ` (${name})` : ""}, such as content where it wanted a snippet (${code})`;
+  }
+  if (code === "bind_not_bindable" || code === "props_not_bindable") {
+    return `the fixture binds a prop that the component doesn't allow to be bound${name ? ` (${name})` : ""} (${code})`;
+  }
+  // A namespace object (`Dialog`) used as a component is compiled to a call, and the call fails like this.
+  if (/^TypeError: (\w*_)?exports\w* is not a function/.test(text)) {
+    return `${text} (a namespace of parts, such as Dialog, was used as if it were one component)`;
+  }
+  return text;
+}

package/src/frameworks/svelte.js

@@ -0,0 +1,162 @@
+/**
+ * The Svelte adapter, for Svelte 5 and newer. Svelte libraries ship source: `.svelte` files, and `.svelte.js` modules that use
+ * runes. A consumer's bundler compiles them, so this adapter gives esbuild a small plugin that does. The compiler comes from the
+ * target's own `svelte` install, so the compiler and the runtime that runs the output are always the same version.
+ */
+import { createRequire } from "node:module";
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { svelteDialect } from "../harness/generate/dialects.js";
+import { generateJsx } from "../harness/generate/jsx.js";
+import { discoverEntry } from "./react.js";
+
+/** The oldest Svelte this version supports. */
+export const SVELTE_FLOOR = 5;
+
+/**
+ * Does a peer range allow Svelte 5 or newer? A part counts when it names version 5 or later, or has no upper limit (`>=3`, `*`).
+ * `^3 || ^4` doesn't, and `^4 || ^5` does.
+ * @param {string} range
+ */
+export function allowsSvelte5(range) {
+  return String(range)
+    .split("||")
+    .some((part) => {
+      const text = part.trim();
+      const major = /(\d+)/.exec(text);
+      if (!major || /^[*x]?$/.test(text) || /^>=?/.test(text)) return true;
+      return Number(major[1]) >= SVELTE_FLOOR;
+    });
+}
+
+/** Mounts a fixture's default export. */
+export const entry = (fixturePath, _pkg) => `import { mount } from "svelte";
+import Fixture from ${JSON.stringify(fixturePath)};
+const libA11y = new URLSearchParams(location.search).get("libA11y") === "on";
+try {
+  mount(Fixture, { target: document.getElementById("root"), props: { libA11y } });
+} catch (error) {
+  window.__error = String(error);
+  console.error(error);
+}
+`;
+
+/**
+ * A fixture for the simple archetypes, from the export name alone.
+ * @param {string} archetype @param {string} pkg @param {string} exportName @param {unknown} [info]
+ */
+export function template(archetype, pkg, exportName, info) {
+  // A namespace with a root part (`Button.Root`) is used through its root.
+  const root = /** @type {any} */ (info)?.parts?.find((part) => /^root$/i.test(part));
+  const tag = root ? `Component.${root}` : "Component";
+  const body = {
+    button: `<${tag} data-a11y-trigger data-a11y-root type="button">Save</${tag}>`,
+    link: `<${tag} data-a11y-trigger data-a11y-root href="#top">Read more</${tag}>`,
+  }[archetype];
+  if (!body) return null;
+  return `<script>
+  import { ${exportName} as Component } from ${JSON.stringify(pkg)};
+</script>
+${body}
+`;
+}
+
+/**
+ * What the compiler produced for a file, kept for the life of the run. A run bundles the same library many times (every generated
+ * candidate is a bundle), and compiling a large library's components again each time dominates the run.
+ * The key is the file and the compiler's own version, so a changed file or a different Svelte compiles again.
+ * @type {Map<string, string>}
+ */
+const compiled = new Map();
+
+/** Compile a file once per version of the file. */
+function cached(path, kind, build) {
+  const stat = statSync(path);
+  const key = `${kind}\0${path}\0${stat.size}\0${stat.mtimeMs}`;
+  let code = compiled.get(key);
+  if (code === undefined) {
+    code = build();
+    compiled.set(key, code);
+  }
+  return code;
+}
+
+/**
+ * Compiles `.svelte` files and `.svelte.js` modules with the Svelte that's installed beside the library. The compiler loads the
+ * first time a file needs it. A compile error becomes a build error with the file and line, so it can't pass as a result.
+ * @param {string} workDir
+ * @returns {import("esbuild").Plugin}
+ */
+function compilerPlugin(workDir) {
+  /** @type {Promise<any> | null} */
+  let compiler = null;
+  const load = () => {
+    // The compiler may load as a module or as CommonJS, which puts the functions under `default`.
+    compiler ??= import(pathToFileURL(createRequire(join(workDir, "package.json")).resolve("svelte/compiler")).href).then((loaded) => (loaded.compile ? loaded : loaded.default));
+    return compiler;
+  };
+  return {
+    name: "svelte-compiler",
+    setup(build) {
+      // One copy of Svelte for the library and the fixture, or the runtime's state is split in two.
+      // A library of a thousand modules asks for the same few Svelte paths over and over, so each is looked up once per build.
+      /** @type {Map<string, Promise<import("esbuild").OnResolveResult | undefined>>} */
+      const resolved = new Map();
+      build.onResolve({ filter: /^svelte(\/|$)/ }, (args) => {
+        if (args.pluginData === "svelte-compiler") return undefined;
+        const key = `${args.kind}\0${args.path}`;
+        if (!resolved.has(key)) {
+          resolved.set(key, build.resolve(args.path, { resolveDir: workDir, kind: args.kind, pluginData: "svelte-compiler" }).then((result) => (result.errors.length ? undefined : result)));
+        }
+        return resolved.get(key);
+      });
+      const failure = (error, file) => ({ errors: [{ text: String(error?.message ?? error).split("\n")[0], location: { file, line: error?.start?.line ?? 0, column: error?.start?.column ?? 0 } }] });
+      build.onLoad({ filter: /\.svelte$/ }, async (args) => {
+        try {
+          const { compile } = await load();
+          return { contents: cached(args.path, "component", () => compile(readFileSync(args.path, "utf8"), { filename: args.path, generate: "client", css: "injected", dev: false }).js.code), loader: "js" };
+        } catch (error) {
+          return failure(error, args.path);
+        }
+      });
+      build.onLoad({ filter: /\.svelte\.js$/ }, async (args) => {
+        try {
+          const { compileModule } = await load();
+          return { contents: cached(args.path, "module", () => compileModule(readFileSync(args.path, "utf8"), { filename: args.path, generate: "client" }).js.code), loader: "js" };
+        } catch (error) {
+          return failure(error, args.path);
+        }
+      });
+    },
+  };
+}
+
+export default {
+  id: "svelte",
+  label: "Svelte",
+  kind: "npm-svelte",
+  noun: "export",
+  extension: "svelte",
+  runtime: ["svelte"],
+  /** @returns {import("./index.js").AdapterDetection | null} */
+  detect(meta) {
+    const peers = meta.peerDependencies ?? {};
+    const deps = meta.dependencies ?? {};
+    const range = peers.svelte ?? deps.svelte;
+    if (range === undefined) return null;
+    if (!allowsSvelte5(range)) return { kind: "npm-unsupported", framework: "Svelte", reason: `The package needs svelte ${range}. Only Svelte ${SVELTE_FLOOR} and newer is supported.` };
+    return { kind: "npm-svelte", framework: "Svelte", reason: `The package lists svelte as a ${"svelte" in peers ? "peer dependency" : "dependency"}.` };
+  },
+  bundle: (workDir) => ({
+    alias: {},
+    plugins: [compilerPlugin(workDir)],
+    // Svelte libraries name their source entry with the `svelte` condition, and some with the `svelte` field.
+    esbuild: { conditions: ["svelte"], mainFields: ["svelte", "browser", "module", "main"] },
+  }),
+  entry,
+  discoverEntry,
+  template,
+  generate: (input) => generateJsx(svelteDialect, input),
+  describe: (npm) => `Svelte${/** @type {any} */ (npm).svelte ? ` (svelte ${/** @type {any} */ (npm).svelte})` : ""}`,
+};

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,