@reticular/speakable 1.1.1 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Simulate how NVDA, JAWS, VoiceOver, and Windows Narrator interpret your HTML — from a single CLI tool. Catch screen reader issues early, detect regressions in CI/CD, and reduce manual testing overhead.
 
 **Try it in your browser — no install needed:** [getspeakable.dev/tool](https://getspeakable.dev/tool)
 
@@ -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
 
@@ -182,7 +183,7 @@ 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 |
 

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(", ")}`
@@ -240,8 +240,15 @@ var ParsingError = class extends Error {
     this.name = "ParsingError";
   }
 };
+var MAX_INPUT_SIZE = 10 * 1024 * 1024;
 function parseHTML(html) {
   const warnings = [];
+  const inputSize = Buffer.byteLength(html, "utf-8");
+  if (inputSize > MAX_INPUT_SIZE) {
+    throw new ParsingError(
+      `Input exceeds maximum size of ${MAX_INPUT_SIZE / (1024 * 1024)} MB (received ${(inputSize / (1024 * 1024)).toFixed(1)} MB). Use CSS selectors to analyze specific sections of large documents.`
+    );
+  }
   try {
     const dom = new JSDOM(html, {
       contentType: "text/html",
@@ -2012,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);
@@ -2554,14 +2791,22 @@ function processHTML(html, options, diffHTML) {
     }
     return processNormal(html, options, warnings, colorize);
   } catch (error) {
-    if (error instanceof Error) {
+    if (error instanceof ParsingError) {
       return {
-        output: `Error: ${error.message}`,
+        output: `Parse error: ${error.message}`,
         exitCode: 2,
         // Content error
         warnings
       };
     }
+    if (error instanceof Error) {
+      return {
+        output: `Error: ${error.message}`,
+        exitCode: 3,
+        // System error
+        warnings
+      };
+    }
     throw error;
   }
 }
@@ -2671,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 ==="),
@@ -2680,7 +2926,10 @@ function formatScreenReaderOutput(model, screenReader, colorize) {
       jaws,
       "",
       c.sectionHeader("=== VoiceOver ==="),
-      voiceover
+      voiceover,
+      "",
+      c.sectionHeader("=== Narrator ==="),
+      narrator
     ].join("\n");
   }
   switch (screenReader) {
@@ -2690,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}`);
   }
@@ -2791,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>",
@@ -2862,6 +3113,7 @@ Screen Readers:
   nvda       - NVDA (Windows)
   jaws       - JAWS (Windows)
   voiceover  - VoiceOver (macOS)
+  narrator   - Narrator (Windows)
   all        - All screen readers
 
 Output Formats: