a11y-hud 0.4.1 → 1.0.0

package/README.md

@@ -5,7 +5,8 @@ A framework-agnostic developer overlay that runs [axe-core](https://github.com/d
 - **No DevTools required** — the HUD runs in the page itself, not as an extension.
 - **Framework-agnostic** — works with any stack. Framework adapters available for React, Vue, Angular, Svelte, and Solid.
 - **Interactive** — violation list with severity filters, click-to-highlight, keyboard navigation, and clipboard export.
-- **Three built-in themes** — `default` (dark), `light`, `high-contrast`; `auto` respects `prefers-color-scheme`.
+- **Eight built-in themes** — `auto` (follows `prefers-color-scheme`, promotes to `high-contrast` under `prefers-contrast: more`) plus `default` (dark), `light`, `high-contrast`, `github-dark`, `github-light`, `tokyo-night`, `solarized-dark`.
+- **ESM + UMD** — import it from a bundler, or load `dist/index.umd.js` from a CDN. Safe to import in SSR code; the HUD mounts only in the browser.
 
 ## Install
 
@@ -37,10 +38,11 @@ hud.unmount();
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `theme` | `"auto" \| "default" \| "light" \| "high-contrast"` | `"auto"` | Panel theme |
+| `theme` | `Theme` | `"auto"` | Panel theme — `"auto"`, `"default"`, `"light"`, `"high-contrast"`, `"github-dark"`, `"github-light"`, `"tokyo-night"`, `"solarized-dark"` |
 | `scope` | `string \| Element` | `document.body` | Restrict scan to a subtree |
 | `autoScan` | `boolean` | `true` | Auto-rescan on DOM mutations |
 | `debounce` | `number` | `500` | Debounce delay in ms |
+| `runOnly` | `string[]` | `[]` | Restrict axe to specific rule-set tags (e.g. `["wcag2a", "wcag2aa"]`) |
 
 ### Headless API
 
@@ -51,6 +53,8 @@ const results = await runScan(document.querySelector("#my-app"));
 console.log(results.violations);
 ```
 
+`runScan()` needs a real browser DOM (run it in the page or inside a Playwright `page.evaluate()`); it is not supported under Node/jsdom.
+
 ## Framework adapters
 
 - React — [`@a11y-hud/react`](https://www.npmjs.com/package/@a11y-hud/react)

package/dist/bookmarklet.html

@@ -121,7 +121,7 @@
 
     <div class="version-row">
       <span>This installer uses <strong>latest</strong>. To pin a specific release:</span>
-      <a href="javascript:(function(){if(window.A11yHud){window.A11yHud.mount();return;}var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/a11y-hud@0.4.1/dist/index.umd.js';s.onload=function(){window.A11yHud.mount();};document.head.appendChild(s);})()" title="Bookmarklet pinned to v0.4.1">Pinned to v0.4.1</a>
+      <a href="javascript:(function(){if(window.A11yHud){window.A11yHud.mount();return;}var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/a11y-hud@1.0.0/dist/index.umd.js';s.onload=function(){window.A11yHud.mount();};document.head.appendChild(s);})()" title="Bookmarklet pinned to v1.0.0">Pinned to v1.0.0</a>
     </div>
 
     <div class="footer">

package/dist/index.d.ts

@@ -40,7 +40,8 @@ interface A11yHudInstance {
     };
 }
 
-declare class A11yHudElement extends HTMLElement {
+declare const BaseElement: typeof HTMLElement;
+declare class A11yHudElement extends BaseElement {
     static observedAttributes: string[];
     private _shadow;
     private _theme;
@@ -49,7 +50,7 @@ declare class A11yHudElement extends HTMLElement {
     private _autoScan;
     private _debounceMs;
     private _results;
-    private _scanning;
+    private _activeScan;
     private _mounted;
     private _observer;
     private _unwatchTheme;
@@ -75,11 +76,15 @@ declare class A11yHudElement extends HTMLElement {
     runScan(): Promise<AxeResults>;
     private _getScopeTarget;
     private _applyResolvedTheme;
+    private _restartObserver;
     private _startObserver;
+    private _scheduleScan;
     private _runScan;
+    private _performScan;
     private _getFilteredViolations;
     private _render;
     private _renderScanning;
+    private _renderError;
     private _renderPanel;
     private _renderFilters;
     private _renderBody;

package/dist/index.js

@@ -276,7 +276,7 @@ async function runScan(target = document.body, runOnly) {
   const options = runOnly && runOnly.length > 0 ? { runOnly: { type: "tag", values: runOnly } } : {};
   const run = axe.run(target, options).then((results) => {
     const ignores = listIgnores();
-    results.violations = results.violations.map((v) => ({
+    const violations = results.violations.map((v) => ({
       ...v,
       nodes: v.nodes.filter((node) => {
         const first = node.target[0];
@@ -296,7 +296,7 @@ async function runScan(target = document.body, runOnly) {
       });
       return nodes.length > 0 ? { ...v, nodes } : null;
     }).filter((v) => v !== null);
-    return results;
+    return { ...results, violations };
   }).finally(() => {
     activeRun = null;
   });
@@ -381,7 +381,9 @@ function buildStyleSheet(css) {
     return null;
   }
 }
-var A11yHudElement = class extends HTMLElement {
+var BaseElement = typeof HTMLElement === "undefined" ? class {
+} : HTMLElement;
+var A11yHudElement = class extends BaseElement {
   static observedAttributes = ["theme", "scope", "auto-scan", "debounce", "run-only"];
   _shadow;
   _theme = "auto";
@@ -390,7 +392,7 @@ var A11yHudElement = class extends HTMLElement {
   _autoScan = true;
   _debounceMs = 500;
   _results;
-  _scanning = false;
+  _activeScan;
   _mounted = false;
   _observer;
   _unwatchTheme;
@@ -407,7 +409,7 @@ var A11yHudElement = class extends HTMLElement {
   constructor() {
     super();
     this._shadow = this.attachShadow({ mode: "open" });
-    this._debouncedScan = debounce(() => void this._runScan(), this._debounceMs);
+    this._debouncedScan = debounce(() => this._scheduleScan(), this._debounceMs);
     this._applyStyles();
   }
   _applyStyles() {
@@ -433,7 +435,7 @@ ${themes_default}`;
       }
     );
     if (this._autoScan) this._startObserver();
-    void this._runScan();
+    this._scheduleScan();
   }
   disconnectedCallback() {
     this._mounted = false;
@@ -454,6 +456,7 @@ ${themes_default}`;
       case "scope":
         this._scopeSelector = value ?? void 0;
         this._scopeElement = void 0;
+        this._restartObserver();
         break;
       case "auto-scan":
         this._autoScan = value !== null;
@@ -470,7 +473,7 @@ ${themes_default}`;
         const parsed = Number.parseInt(value ?? "", 10);
         this._debounceMs = Number.isNaN(parsed) ? 500 : parsed;
         this._debouncedScan.cancel();
-        this._debouncedScan = debounce(() => void this._runScan(), this._debounceMs);
+        this._debouncedScan = debounce(() => this._scheduleScan(), this._debounceMs);
         break;
       }
       case "run-only": {
@@ -489,8 +492,10 @@ ${themes_default}`;
     return this._scopeElement;
   }
   set scopeElement(el) {
+    const changed = el !== this._scopeElement || this._scopeSelector !== void 0;
     this._scopeElement = el;
     this._scopeSelector = void 0;
+    if (changed) this._restartObserver();
   }
   setTheme(theme) {
     this._theme = theme;
@@ -506,27 +511,33 @@ ${themes_default}`;
     }
     this._updateRunOnlyChips();
   }
-  async runScan() {
+  runScan() {
     return this._runScan();
   }
   _getScopeTarget() {
     if (this._scopeElement) return this._scopeElement;
     if (this._scopeSelector) {
-      return document.querySelector(this._scopeSelector) ?? document.body;
+      try {
+        return document.querySelector(this._scopeSelector) ?? document.body;
+      } catch {
+        return document.body;
+      }
     }
     return document.body;
   }
   _applyResolvedTheme() {
     this.dataset.theme = resolveTheme(this._theme);
   }
+  _restartObserver() {
+    if (this._mounted && this._autoScan) this._startObserver();
+  }
   _startObserver() {
     this._observer?.disconnect();
     const target = this._getScopeTarget();
-    const debouncedScan = this._debouncedScan;
     this._observer = new MutationObserver((records) => {
       if (records.every((r) => r.type === "attributes" && r.attributeName === HIGHLIGHT_ATTR))
         return;
-      debouncedScan();
+      this._debouncedScan();
     });
     this._observer.observe(target, {
       childList: true,
@@ -535,9 +546,20 @@ ${themes_default}`;
       characterData: false
     });
   }
-  async _runScan() {
-    if (this._scanning) return this._results ?? { violations: [] };
-    this._scanning = true;
+  // Fire-and-forget entry point for internal triggers (observer, buttons).
+  // Errors are surfaced in the panel by _runScan, so swallow the rejection here.
+  _scheduleScan() {
+    this._runScan().catch(() => {
+    });
+  }
+  _runScan() {
+    if (this._activeScan) return this._activeScan;
+    this._activeScan = this._performScan().finally(() => {
+      this._activeScan = void 0;
+    });
+    return this._activeScan;
+  }
+  async _performScan() {
     const rescanBtn = this._shadow.querySelector("#btn-rescan");
     if (rescanBtn) {
       rescanBtn.setAttribute("data-scanning", "");
@@ -552,8 +574,10 @@ ${themes_default}`;
       this._results = results;
       this._render();
       return results;
+    } catch (error) {
+      if (this._mounted) this._renderError(error);
+      throw error;
     } finally {
-      this._scanning = false;
       const btn = this._shadow.querySelector("#btn-rescan");
       if (btn) {
         btn.removeAttribute("data-scanning");
@@ -612,6 +636,20 @@ ${themes_default}`;
       `;
     }
   }
+  _renderError(error) {
+    if (this._keyboardMode) return;
+    const body = this._shadow.querySelector(".panel-body");
+    if (!body) return;
+    const message = error instanceof Error ? error.message : String(error);
+    body.innerHTML = `
+      <div class="empty-state" role="alert">
+        <span class="empty-state-icon" aria-hidden="true">${icon("alert-triangle")}</span>
+        <span class="empty-state-title">Scan failed</span>
+        <span class="empty-state-body">${escapeHtml(message)}</span>
+      </div>
+      ${this._renderIgnoredSection()}
+    `;
+  }
   _renderPanel(violations, total) {
     return `
       <div class="panel" role="complementary" aria-label="Accessibility panel">
@@ -741,7 +779,7 @@ ${themes_default}`;
     const nodeCount = violation.nodes.length;
     const nodeLabel = `${nodeCount} node${nodeCount !== 1 ? "s" : ""}`;
     const nodes = violation.nodes.map((node, ni) => {
-      const selector = this._nodeSelector(node.target);
+      const selector = escapeHtml(this._nodeSelector(node.target));
       return `
           <li class="violation-node-item">
             <button class="btn-highlight" data-violation="${index}" data-node="${ni}" aria-label="Highlight: ${selector}">
@@ -784,7 +822,7 @@ ${themes_default}`;
     const panel = this._shadow.querySelector(".panel");
     if (!panel) return;
     panel.querySelector(".btn-panel-title")?.addEventListener("click", () => this._toggleFilters());
-    panel.querySelector("#btn-rescan")?.addEventListener("click", () => void this._runScan());
+    panel.querySelector("#btn-rescan")?.addEventListener("click", () => this._scheduleScan());
     panel.querySelector("#btn-minimize")?.addEventListener("click", () => {
       this.setAttribute("data-minimized", "");
     });
@@ -850,7 +888,7 @@ ${themes_default}`;
       const ruleId = ignoreBtn.dataset.ignoreRule;
       if (ruleId) {
         addIgnore(ruleId);
-        void this._runScan();
+        this._scheduleScan();
       }
       return;
     }
@@ -860,7 +898,7 @@ ${themes_default}`;
       const selector = removeIgnoreBtn.dataset.removeSelector || void 0;
       if (ruleId) {
         removeIgnore(ruleId, selector);
-        void this._runScan();
+        this._scheduleScan();
       }
       return;
     }
@@ -874,7 +912,7 @@ ${themes_default}`;
     }
     if (target.closest(".btn-clear-ignores")) {
       clearIgnores();
-      void this._runScan();
+      this._scheduleScan();
       return;
     }
     const ignoredToggle = target.closest(".ignored-section-toggle");
@@ -921,7 +959,7 @@ ${themes_default}`;
           chip.setAttribute("aria-pressed", "true");
         }
         this._updateFilterToggle();
-        void this._runScan();
+        this._scheduleScan();
       }
     }
   }
@@ -1123,7 +1161,7 @@ ${themes_default}`;
       const reader = new FileReader();
       reader.onload = (evt) => {
         importIgnores(evt.target?.result ?? "");
-        void this._runScan();
+        this._scheduleScan();
       };
       reader.readAsText(file);
     };
@@ -1179,7 +1217,9 @@ ${themes_default}`;
     this._removeHighlight = () => el.removeAttribute(HIGHLIGHT_ATTR);
   }
 };
-customElements.define("a11y-hud", A11yHudElement);
+if (typeof customElements !== "undefined" && !customElements.get("a11y-hud")) {
+  customElements.define("a11y-hud", A11yHudElement);
+}
 
 // src/mount.ts
 function mount(options = {}) {