@reticular/speakable 1.2.0 → 1.4.0

package/README.md

@@ -1,10 +1,10 @@
 # Speakable
 
-Simulate how NVDA, JAWS, and VoiceOver interpret your HTML — from a single CLI tool. Catch screen reader issues early, detect regressions in CI/CD, and reduce manual testing overhead.
+Predict how NVDA, JAWS, VoiceOver, and Windows Narrator interpret your HTML, and detect accessibility behavior regressions during component interaction. Catch screen reader issues early, analyze runtime focus management, and prevent regressions in CI/CD.
 
-**Try it in your browser — no install needed:** [getspeakable.dev/tool](https://getspeakable.dev/tool)
+**Try it in your browser:** [getspeakable.dev/tool](https://getspeakable.dev/tool)
 
-Speakable bridges the gap between rule-based linting tools (like axe) and manual screen reader testing. It gives you scalable, automated insight into how assistive technologies will interpret your UI.
+Speakable bridges the gap between rule-based linting tools (like axe) and manual screen reader testing. It provides both static HTML analysis and runtime accessibility behavior tracking, giving you automated insight into how assistive technologies interpret your UI throughout the development lifecycle.
 
 > Screen reader output is heuristic and may differ from actual behavior. Speakable complements manual testing — it doesn't replace it.
 
@@ -43,7 +43,7 @@ cat page.html | speakable -
 
 ## Web Analyzer
 
-If you want to test HTML quickly without installing anything, paste it directly into the web analyzer at [getspeakable.dev/tool](https://getspeakable.dev/tool). It runs the same simulation engine in the browser — supports NVDA, JAWS, and VoiceOver output, CSS selector filtering, and diff mode. Useful for quick iteration, debugging a specific component, or sharing results with teammates who don't have the CLI installed.
+If you want to test HTML quickly without installing anything, paste it directly into the web analyzer at [getspeakable.dev/tool](https://getspeakable.dev/tool). It runs the same simulation engine in the browser — supports NVDA, JAWS, VoiceOver, and Narrator output, CSS selector filtering, and diff mode. Useful for quick iteration, debugging a specific component, or sharing results with teammates who don't have the CLI installed.
 
 ## CLI Reference
 
@@ -83,9 +83,10 @@ Options:
 | NVDA | `-s nvda` | Windows |
 | JAWS | `-s jaws` | Windows |
 | VoiceOver | `-s voiceover` | macOS |
-| All | `-s all` | All three readers side by side |
+| Narrator | `-s narrator` | Windows |
+| All | `-s all` | All four readers side by side |
 
-Each renderer produces heuristic output approximating the real screen reader's behavior. Key differences are preserved — for example, NVDA says "navigation landmark" while JAWS says "navigation region" and VoiceOver says "navigation".
+Each renderer produces heuristic output approximating the real screen reader's behavior. Key differences are preserved — for example, NVDA says "navigation landmark" while JAWS says "navigation region", VoiceOver says "navigation", and Narrator says "navigation".
 
 ## Features
 
@@ -159,6 +160,123 @@ Verify that the accessibility model serializes and deserializes consistently:
 speakable page.html --validate
 ```
 
+## Runtime Accessibility Analysis
+
+Beyond static HTML analysis, Speakable tracks accessibility behavior during component interaction: focus transitions, ARIA state changes, live region announcements, and dialog lifecycle events.
+
+### CLI Usage
+
+```bash
+# Analyze runtime behavior of a URL
+speakable runtime https://localhost:3000/settings
+
+# Use a built-in interaction pattern
+speakable runtime https://localhost:3000 --interaction modal-dialog
+
+# Analyze all Storybook stories
+speakable runtime http://localhost:6006 --storybook
+
+# Filter to specific components
+speakable runtime http://localhost:6006 --storybook --story "Dialog*"
+
+# Save baselines for regression detection
+speakable runtime http://localhost:6006 --storybook --runtime-snapshot ./baselines
+
+# CI mode: fail on behavior regressions
+speakable runtime http://localhost:6006 --storybook --runtime-snapshot ./baselines --runtime-ci
+
+# Authenticate with protected Storybook instances
+speakable runtime https://storybook.internal.co --storybook \
+  --storybook-auth-header "Bearer your-token"
+```
+
+### Programmatic API
+
+```typescript
+import { runtime } from '@reticular/speakable';
+
+const generator = runtime.createTimelineGenerator({
+  document: myDocument,
+  componentName: 'SettingsDialog',
+});
+
+const sequence = runtime.getBuiltinPattern('modal-dialog', {
+  trigger: 'button.open-settings',
+});
+
+const timeline = await generator.capture(sequence);
+
+// Inspect events
+timeline.events.forEach(event => {
+  console.log(`${event.type}: ${event.target.accessibleName}`);
+});
+
+// Check for warnings (focus escape, missing announcements, etc.)
+timeline.warnings.forEach(w => {
+  console.warn(w.payload.message);
+});
+```
+
+### Built-in Interaction Patterns
+
+| Pattern | What it tests |
+|---------|---------------|
+| `modal-dialog` | Focus moves to dialog, stays trapped, returns on close |
+| `combobox` | Options announced on arrow navigation, selection confirmed |
+| `tabs` | Arrow keys switch tabs, panel content communicated |
+| `accordion` | Expanded/collapsed state announced on toggle |
+
+### Heuristic Warnings
+
+The runtime engine automatically detects common anti-patterns without needing a baseline:
+
+- Focus not moved into modal dialog on open
+- Focus escaped modal dialog (broken focus trap)
+- Rapid announcements (aria-live flooding)
+- Keyboard action with no accessibility response
+- Focused element removed without focus management
+
+### Behavior Diffing and Regression Detection
+
+Compare accessibility timelines across builds to catch regressions:
+
+```typescript
+import { runtime } from '@reticular/speakable';
+
+const diff = runtime.diffTimelines(baselineTimeline, currentTimeline);
+// diff.added, diff.removed, diff.modified
+
+const classified = runtime.classifyDiff(diff);
+// classified.highestSeverity: 'critical' | 'high' | 'medium' | 'low'
+```
+
+Severity levels:
+- **Critical**: Focus loss, modal focus escape, missing required announcements
+- **High**: Incorrect focus restoration, keyboard navigation regression
+- **Medium**: Additional announcements, accessible name changes
+- **Low**: Timing differences, non-breaking behavior changes
+
+### Storybook Integration
+
+Connect to a running Storybook instance to analyze accessibility behavior across your component library:
+
+```typescript
+import { createStorybookAdapter, createStoryLoader } from '@reticular/speakable/storybook';
+
+const adapter = createStorybookAdapter({
+  url: 'http://localhost:6006',
+  componentFilter: 'Dialog*',
+  authHeader: 'Bearer token',  // for protected instances
+});
+
+await adapter.connect();
+const stories = await adapter.discoverStories();
+```
+
+The Storybook pipeline discovers stories, loads them in isolation, runs interaction patterns, and produces timelines that can be baselined and compared. Works with Storybook 7.x and 8.x.
+
+> See the [Runtime Analysis docs](https://getspeakable.dev/docs/runtime-analysis) for interactive demos and full API reference.
+
 ## MCP Integration (AI Assistants)
 
 Speakable includes a Model Context Protocol (MCP) server that lets AI coding assistants analyze accessibility in real-time. Ask your assistant "check if this component is accessible" and it calls Speakable automatically.
@@ -182,9 +300,11 @@ Add to your MCP config (Kiro, VS Code, Cursor, Claude Desktop, Windsurf):
 
 | Tool | Description |
 |------|-------------|
-| `analyze_html` | Predict screen reader output for NVDA, JAWS, and VoiceOver |
+| `analyze_html` | Predict screen reader output for NVDA, JAWS, VoiceOver, and Narrator |
 | `audit_html` | Generate accessibility audit report with issues and remediation |
 | `diff_html` | Compare two HTML versions for accessibility regressions |
+| `analyze_runtime` | Run runtime accessibility analysis with interaction sequences |
+| `diff_runtime` | Compare two accessibility timelines for behavior regressions |
 
 All tools run locally — no network requests, no data leaves your machine. See the [MCP Integration docs](https://getspeakable.dev/docs/mcp-integration) for full setup instructions.
 
@@ -269,10 +389,10 @@ Speakable processes HTML through a four-stage pipeline:
 
 - Replace manual screen reader testing with real assistive technology
 - Guarantee WCAG compliance
-- Test dynamic/JavaScript-driven content (it analyzes static HTML)
 - Perfectly replicate screen reader behavior (output is heuristic)
+- Execute JavaScript in static analysis mode (use runtime mode for dynamic content)
 
-Use Speakable to catch issues early and reduce the manual testing burden — then validate critical flows with real screen readers.
+Use Speakable to catch issues early and reduce the manual testing burden. Validate critical flows with real screen readers.
 
 ## Best Practices
 

package/dist/cli.js

@@ -22,7 +22,7 @@ function validateOptions(rawOptions) {
       `Invalid format: ${format}. Must be one of: ${validFormats.join(", ")}`
     );
   }
-  const validReaders = ["nvda", "jaws", "voiceover", "all"];
+  const validReaders = ["nvda", "jaws", "voiceover", "narrator", "all"];
   if (!validReaders.includes(screenReader)) {
     throw new Error(
       `Invalid screen reader: ${screenReader}. Must be one of: ${validReaders.join(", ")}`
@@ -2019,6 +2019,236 @@ function formatStatesVoiceOver(node) {
   return states.join(", ");
 }
 
+// src/renderer/narrator-renderer.ts
+function renderNarrator(model, colorize) {
+  const c = createColors(colorize ?? false);
+  const announcements = [];
+  renderNodeNarrator(model.root, announcements, c);
+  return announcements.join("\n");
+}
+function renderNodeNarrator(node, announcements, c) {
+  const announcement = formatNodeNarrator(node, c);
+  if (announcement) {
+    announcements.push(announcement);
+  }
+  for (const child of node.children) {
+    if (child.name && child.name === node.name && node.children.length === 1) {
+      for (const grandchild of child.children) {
+        renderNodeNarrator(grandchild, announcements, c);
+      }
+      continue;
+    }
+    renderNodeNarrator(child, announcements, c);
+  }
+}
+function formatNodeNarrator(node, c) {
+  const parts = [];
+  const roleFirst = shouldAnnounceRoleFirst2(node.role);
+  if (roleFirst) {
+    const roleText = formatRoleNarrator(node);
+    if (roleText) {
+      parts.push(c.roleName(roleText));
+    }
+    if (node.name) {
+      parts.push(c.elementName(node.name));
+    }
+  } else {
+    if (node.name) {
+      parts.push(c.elementName(node.name));
+    }
+    const roleText = formatRoleNarrator(node);
+    if (roleText) {
+      parts.push(c.roleName(roleText));
+    }
+  }
+  const stateText = formatStatesNarrator(node);
+  if (stateText) {
+    parts.push(c.stateName(stateText));
+  }
+  if (node.value) {
+    const valueText = node.value.text || String(node.value.current);
+    if (valueText) {
+      parts.push(valueText);
+    }
+  }
+  if (node.description) {
+    parts.push(c.description(node.description));
+  }
+  return parts.join(", ");
+}
+function shouldAnnounceRoleFirst2(role) {
+  const roleFirstRoles = [
+    "link",
+    "heading",
+    "navigation",
+    "main",
+    "banner",
+    "contentinfo",
+    "complementary",
+    "region",
+    "form",
+    "search",
+    "blockquote",
+    "figure",
+    "dialog",
+    "group",
+    "document"
+  ];
+  return roleFirstRoles.includes(role);
+}
+function formatRoleNarrator(node) {
+  const role = node.role;
+  switch (role) {
+    case "button":
+      return "button";
+    case "link":
+      return "link";
+    case "heading":
+      if (node.state.level) {
+        return `Heading level ${node.state.level}`;
+      }
+      return "Heading";
+    case "textbox":
+      return "edit";
+    case "checkbox":
+      return "check box";
+    case "radio":
+      return "radio button";
+    case "combobox":
+      return "combo box";
+    case "listbox":
+      return "list box";
+    case "option":
+      return "option";
+    case "list":
+      return "list";
+    case "listitem":
+      return "list item";
+    case "navigation":
+      return "navigation";
+    case "main":
+      return "main";
+    case "banner":
+      return "banner";
+    case "contentinfo":
+      return "content info";
+    case "complementary":
+      return "complementary";
+    case "form":
+      return "form";
+    case "search":
+      return "search";
+    case "region":
+      return "region";
+    case "img":
+      return "image";
+    case "article":
+      return "article";
+    case "generic":
+      return "";
+    case "staticText":
+    case "paragraph":
+    case "cell":
+    case "term":
+    case "definition":
+    case "caption":
+      return "";
+    case "blockquote":
+      return "block quote";
+    case "code":
+      return "code";
+    case "table": {
+      const rows = node.children.filter((c) => c.role === "row");
+      const rowCount = rows.length;
+      const colCount = rows.length > 0 ? rows[0].children.length : 0;
+      return `table, ${rowCount} rows, ${colCount} columns`;
+    }
+    case "row":
+      return "row";
+    case "columnheader":
+      return "column header";
+    case "rowheader":
+      return "row header";
+    case "figure":
+      return "figure";
+    case "dialog":
+      return "dialog";
+    case "meter":
+      return "meter";
+    case "progressbar":
+      return "progress bar";
+    case "status":
+      return "status";
+    case "group":
+      return node.name ? "group" : "";
+    case "document":
+      return "document";
+    case "application":
+      return "application";
+    case "separator":
+      return "separator";
+    default:
+      return role;
+  }
+}
+function formatStatesNarrator(node) {
+  const states = [];
+  if (node.state.expanded !== void 0) {
+    states.push(node.state.expanded ? "expanded" : "collapsed");
+  }
+  if (node.state.checked !== void 0) {
+    if (node.state.checked === "mixed") {
+      states.push("partially selected");
+    } else {
+      states.push(node.state.checked ? "checked" : "unchecked");
+    }
+  }
+  if (node.state.pressed !== void 0) {
+    if (node.state.pressed === "mixed") {
+      states.push("partially pressed");
+    } else {
+      states.push(node.state.pressed ? "pressed" : "not pressed");
+    }
+  }
+  if (node.state.selected !== void 0) {
+    states.push(node.state.selected ? "selected" : "not selected");
+  }
+  if (node.state.disabled) {
+    states.push("disabled");
+  }
+  if (node.state.invalid) {
+    states.push("invalid");
+  }
+  if (node.state.required) {
+    states.push("required");
+  }
+  if (node.state.readonly) {
+    states.push("read only");
+  }
+  if (node.state.busy) {
+    states.push("busy");
+  }
+  if (node.state.current) {
+    if (node.state.current === "page") {
+      states.push("current page");
+    } else if (node.state.current === "step") {
+      states.push("current step");
+    } else if (node.state.current === "location") {
+      states.push("current location");
+    } else if (node.state.current === "date") {
+      states.push("current date");
+    } else if (node.state.current === "time") {
+      states.push("current time");
+    } else if (node.state.current === "true") {
+      states.push("current");
+    }
+  }
+  if (node.state.grabbed !== void 0) {
+    states.push(node.state.grabbed ? "grabbed" : "not grabbed");
+  }
+  return states.join(", ");
+}
+
 // src/renderer/audit-renderer.ts
 function renderAuditReport(model, colorize) {
   const report = generateAuditReport(model);
@@ -2686,6 +2916,7 @@ function formatScreenReaderOutput(model, screenReader, colorize) {
     const nvda = renderNVDA(model, colorize);
     const jaws = renderJAWS(model, colorize);
     const voiceover = renderVoiceOver(model, colorize);
+    const narrator = renderNarrator(model, colorize);
     const c = createColors(colorize);
     return [
       c.sectionHeader("=== NVDA ==="),
@@ -2695,7 +2926,10 @@ function formatScreenReaderOutput(model, screenReader, colorize) {
       jaws,
       "",
       c.sectionHeader("=== VoiceOver ==="),
-      voiceover
+      voiceover,
+      "",
+      c.sectionHeader("=== Narrator ==="),
+      narrator
     ].join("\n");
   }
   switch (screenReader) {
@@ -2705,6 +2939,8 @@ function formatScreenReaderOutput(model, screenReader, colorize) {
       return renderJAWS(model, colorize);
     case "voiceover":
       return renderVoiceOver(model, colorize);
+    case "narrator":
+      return renderNarrator(model, colorize);
     default:
       throw new Error(`Unknown screen reader: ${screenReader}`);
   }
@@ -2806,7 +3042,7 @@ program.argument("[input...]", 'HTML file path(s) or "-" for stdin').option("-o,
   "json"
 ).option(
   "-s, --screen-reader <reader>",
-  "Screen reader: nvda, jaws, voiceover, or all (default: nvda)",
+  "Screen reader: nvda, jaws, voiceover, narrator, or all (default: nvda)",
   "nvda"
 ).option(
   "--selector <selector>",
@@ -2877,6 +3113,7 @@ Screen Readers:
   nvda       - NVDA (Windows)
   jaws       - JAWS (Windows)
   voiceover  - VoiceOver (macOS)
+  narrator   - Narrator (Windows)
   all        - All screen readers
 
 Output Formats: