@reticular/speakable 1.4.0 → 1.5.0

package/dist/mcp.js

@@ -2412,6 +2412,314 @@ function formatValue(value) {
   return String(value);
 }
 
+// src/runtime/verbosity-analyzer.ts
+var DEFAULT_CONFIG = {
+  interactionFrameWindow: 150,
+  textSimilarityThreshold: 0.6
+};
+function textSimilarity(a, b) {
+  if (!a || !b) return 0;
+  const wordsA = new Set(a.toLowerCase().split(/\s+/).filter(Boolean));
+  const wordsB = new Set(b.toLowerCase().split(/\s+/).filter(Boolean));
+  if (wordsA.size === 0 || wordsB.size === 0) return 0;
+  let overlap = 0;
+  for (const word of wordsA) {
+    if (wordsB.has(word)) overlap++;
+  }
+  const maxSize = Math.max(wordsA.size, wordsB.size);
+  return overlap / maxSize;
+}
+function groupIntoFrames(events, windowMs) {
+  if (events.length === 0) return [];
+  const frames = [];
+  let currentFrame = {
+    start: events[0].timestamp,
+    end: events[0].timestamp,
+    events: [events[0]]
+  };
+  for (let i = 1; i < events.length; i++) {
+    const event = events[i];
+    if (event.timestamp - currentFrame.end <= windowMs) {
+      currentFrame.events.push(event);
+      currentFrame.end = event.timestamp;
+    } else {
+      frames.push(currentFrame);
+      currentFrame = {
+        start: event.timestamp,
+        end: event.timestamp,
+        events: [event]
+      };
+    }
+  }
+  frames.push(currentFrame);
+  return frames;
+}
+function detectRedundantStateAndLiveRegion(frame, _config) {
+  const findings = [];
+  const stateChanges = frame.events.filter((e) => e.type === "STATE_CHANGED");
+  const announcements = frame.events.filter((e) => e.type === "ANNOUNCEMENT");
+  for (const stateEvent of stateChanges) {
+    const payload = stateEvent.payload;
+    const announcedAttributes = [
+      "aria-selected",
+      "aria-checked",
+      "aria-pressed",
+      "aria-expanded",
+      "aria-disabled",
+      "aria-invalid",
+      "aria-current"
+    ];
+    if (!announcedAttributes.includes(payload.attribute)) continue;
+    for (const announcement of announcements) {
+      const annoPayload = announcement.payload;
+      const annoText = annoPayload.text.toLowerCase();
+      const elementName = stateEvent.target.accessibleName.toLowerCase();
+      const nameInAnnouncement = elementName.length > 0 && annoText.includes(elementName);
+      const stateEchoWords = ["selected", "deselected", "checked", "unchecked", "expanded", "collapsed", "pressed"];
+      const hasStateEcho = stateEchoWords.some((word) => annoText.includes(word));
+      if (nameInAnnouncement && hasStateEcho) {
+        findings.push({
+          pattern: "redundant-state-and-live-region",
+          severity: "high",
+          description: `The ${payload.attribute} state change on "${stateEvent.target.accessibleName}" (${stateEvent.target.role}) is already announced by the screen reader, but a live region also announces similar content ("${annoPayload.text}"). This causes VoiceOver to read the information 2-3 times.`,
+          remediation: [
+            `Remove the live region announcement when ${payload.attribute} changes on the active element, since the screen reader already announces state transitions on the focused/active item.`,
+            `If you need the live region for summary info (e.g., "3 of 5 selected"), debounce it with a 150ms+ delay and ensure the text does NOT repeat the option name.`,
+            `Use a summary-only pattern in the live region: "3 of 5 selected" instead of "JavaScript selected. 3 of 5 selected." The element name is already announced via the state change.`,
+            `Consider removing the live region entirely and relying on aria-selected/aria-checked state changes for per-item feedback.`
+          ],
+          affectedReaders: ["VoiceOver (macOS)", "VoiceOver (iOS)"],
+          relatedEvents: [stateEvent, announcement],
+          timeWindow: { start: frame.start, end: frame.end },
+          elementSelector: stateEvent.target.selector
+        });
+      }
+    }
+  }
+  return findings;
+}
+function detectActiveDescendantPlusStateChange(frame, _config) {
+  const findings = [];
+  const activedescendantChanges = frame.events.filter(
+    (e) => e.type === "STATE_CHANGED" && e.payload.attribute === "aria-activedescendant"
+  );
+  const otherStateChanges = frame.events.filter(
+    (e) => e.type === "STATE_CHANGED" && e.payload.attribute !== "aria-activedescendant"
+  );
+  for (const adChange of activedescendantChanges) {
+    const adPayload = adChange.payload;
+    const newValue = String(adPayload.newValue);
+    const previousValue = String(adPayload.previousValue ?? "");
+    const isSameElement = newValue === previousValue;
+    for (const stateChange of otherStateChanges) {
+      const statePayload = stateChange.payload;
+      const targetMatchesAD = stateChange.target.selector.includes(newValue) || stateChange.target.selector === adChange.target.selector;
+      if (!targetMatchesAD) continue;
+      if (isSameElement) {
+        findings.push({
+          pattern: "activedescendant-plus-state-change",
+          severity: "high",
+          description: `aria-activedescendant was re-set to the same value ("${newValue}") AND ${statePayload.attribute} changed on that element within ${frame.end - frame.start}ms. VoiceOver reads the element once for the activedescendant update, then again for the state change.`,
+          remediation: [
+            `When toggling selection on the already-active option, do NOT re-set aria-activedescendant to the same value. Only update it when the user navigates to a different option.`,
+            `Batch DOM attribute changes: set aria-selected BEFORE updating aria-activedescendant, or skip the activedescendant update entirely when the active item hasn't changed.`,
+            `For click interactions on options, avoid calling both setActiveDescendant() and toggleSelection() if the clicked item is already the active descendant.`
+          ],
+          affectedReaders: ["VoiceOver (macOS)", "VoiceOver (iOS)", "Narrator"],
+          relatedEvents: [adChange, stateChange],
+          timeWindow: { start: frame.start, end: frame.end },
+          elementSelector: stateChange.target.selector
+        });
+      } else {
+        findings.push({
+          pattern: "activedescendant-plus-state-change",
+          severity: "low",
+          description: `aria-activedescendant moved to "${stateChange.target.accessibleName}" AND ${statePayload.attribute} changed on that element within ${frame.end - frame.start}ms. VoiceOver may announce the option name twice (once for navigation, once for state).`,
+          remediation: [
+            `If this is a click-to-select interaction, consider separating the activedescendant update and the state change by a microtask (Promise.resolve()) so VoiceOver processes them as separate assertions.`,
+            `Alternatively, accept this as expected behavior for click interactions where navigation and selection happen simultaneously.`
+          ],
+          affectedReaders: ["VoiceOver (macOS)"],
+          relatedEvents: [adChange, stateChange],
+          timeWindow: { start: frame.start, end: frame.end },
+          elementSelector: stateChange.target.selector
+        });
+      }
+    }
+  }
+  return findings;
+}
+function detectNameChangePlusLiveRegion(frame, config) {
+  const findings = [];
+  const nameChanges = frame.events.filter((e) => e.type === "ACCESSIBLE_NAME_CHANGED");
+  const announcements = frame.events.filter((e) => e.type === "ANNOUNCEMENT");
+  for (const nameEvent of nameChanges) {
+    for (const announcement of announcements) {
+      const annoPayload = announcement.payload;
+      const similarity = textSimilarity(nameEvent.target.accessibleName, annoPayload.text);
+      if (similarity >= config.textSimilarityThreshold) {
+        findings.push({
+          pattern: "name-change-plus-live-region",
+          severity: "medium",
+          description: `The accessible name of "${nameEvent.target.accessibleName}" (${nameEvent.target.role}) changed AND a live region announced similar content ("${annoPayload.text}"). Screen readers may announce both the name change and the live region.`,
+          remediation: [
+            `Choose one announcement channel: either update the element's accessible name (which the screen reader reads if the element is focused) OR use a live region, not both.`,
+            `If the element is focused, prefer the name change. If it's not focused, prefer the live region.`,
+            `Add a 200ms+ debounce to the live region update to let the name change announce first.`
+          ],
+          affectedReaders: ["VoiceOver (macOS)", "NVDA", "JAWS"],
+          relatedEvents: [nameEvent, announcement],
+          timeWindow: { start: frame.start, end: frame.end },
+          elementSelector: nameEvent.target.selector
+        });
+      }
+    }
+  }
+  return findings;
+}
+function detectFocusPlusActiveDescendant(frame, _config) {
+  const findings = [];
+  const focusEvents = frame.events.filter((e) => e.type === "FOCUS_CHANGED");
+  const adChanges = frame.events.filter(
+    (e) => e.type === "STATE_CHANGED" && e.payload.attribute === "aria-activedescendant"
+  );
+  if (focusEvents.length > 0 && adChanges.length > 0) {
+    findings.push({
+      pattern: "focus-plus-activedescendant",
+      severity: "medium",
+      description: `Both real DOM focus moved AND aria-activedescendant changed within ${frame.end - frame.start}ms. Screen readers may announce the focused element AND then re-announce via activedescendant, causing a double-read.`,
+      remediation: [
+        `Choose one focus management strategy: either move real DOM focus to options (roving tabindex) OR use aria-activedescendant on the container. Do not mix both.`,
+        `If using aria-activedescendant, keep DOM focus on the container (listbox/combobox) and only change the activedescendant attribute.`,
+        `If using roving tabindex, set tabindex="0" on the active item and tabindex="-1" on others, and move focus directly via element.focus().`
+      ],
+      affectedReaders: ["VoiceOver (macOS)", "NVDA", "JAWS", "Narrator"],
+      relatedEvents: [...focusEvents, ...adChanges],
+      timeWindow: { start: frame.start, end: frame.end },
+      elementSelector: focusEvents[0].target.selector
+    });
+  }
+  return findings;
+}
+function detectMultipleStateChangesSameElement(frame, _config) {
+  const findings = [];
+  const stateChanges = frame.events.filter((e) => e.type === "STATE_CHANGED");
+  const bySelector = /* @__PURE__ */ new Map();
+  for (const event of stateChanges) {
+    const existing = bySelector.get(event.target.selector) || [];
+    existing.push(event);
+    bySelector.set(event.target.selector, existing);
+  }
+  for (const [selector, events] of bySelector) {
+    if (events.length >= 3) {
+      const attributes = events.map((e) => e.payload.attribute);
+      findings.push({
+        pattern: "multiple-state-changes-same-element",
+        severity: "medium",
+        description: `${events.length} ARIA attributes changed simultaneously on "${events[0].target.accessibleName}" (${events[0].target.role}): ${attributes.join(", ")}. Some screen readers announce each attribute change individually, causing a verbose multi-part announcement.`,
+        remediation: [
+          `Batch attribute changes into a single DOM mutation frame by setting all attributes before the next microtask. Use requestAnimationFrame() or Promise.resolve() to group them.`,
+          `Evaluate which attributes actually need to be communicated. For example, if aria-selected changes, the screen reader already announces it; additional aria-checked or aria-pressed changes may be redundant.`,
+          `Consider using a single composite state (e.g., just aria-selected for listbox options) rather than multiple state attributes.`
+        ],
+        affectedReaders: ["VoiceOver (macOS)", "Narrator"],
+        relatedEvents: events,
+        timeWindow: { start: frame.start, end: frame.end },
+        elementSelector: selector
+      });
+    }
+  }
+  return findings;
+}
+function detectRapidIdenticalAnnouncements(frame, _config) {
+  const findings = [];
+  const announcements = frame.events.filter((e) => e.type === "ANNOUNCEMENT");
+  const seen = /* @__PURE__ */ new Map();
+  for (const event of announcements) {
+    const text = event.payload.text.toLowerCase().trim();
+    const existing = seen.get(text) || [];
+    existing.push(event);
+    seen.set(text, existing);
+  }
+  for (const [text, events] of seen) {
+    if (events.length >= 2) {
+      findings.push({
+        pattern: "rapid-identical-announcements",
+        severity: "high",
+        description: `The same live region content ("${text}") was announced ${events.length} times within ${frame.end - frame.start}ms. Users will hear the same information repeated.`,
+        remediation: [
+          `Debounce live region updates. Clear the live region text content first, then set the new value after a 100-200ms delay.`,
+          `If updating a live region's textContent to the same value, the screen reader may ignore it OR re-read it depending on implementation. Clear to empty string first.`,
+          `Avoid updating the live region inside a loop or rapid event handler. Compute the final state and announce once.`
+        ],
+        affectedReaders: ["VoiceOver (macOS)", "VoiceOver (iOS)", "NVDA", "Narrator"],
+        relatedEvents: events,
+        timeWindow: { start: frame.start, end: frame.end },
+        elementSelector: events[0].target.selector
+      });
+    }
+  }
+  return findings;
+}
+function analyzeVerbosity(events, config) {
+  const cfg = { ...DEFAULT_CONFIG, ...config };
+  const frames = groupIntoFrames(events, cfg.interactionFrameWindow);
+  const findings = [];
+  for (const frame of frames) {
+    findings.push(...detectRedundantStateAndLiveRegion(frame, cfg));
+    findings.push(...detectActiveDescendantPlusStateChange(frame, cfg));
+    findings.push(...detectNameChangePlusLiveRegion(frame, cfg));
+    findings.push(...detectFocusPlusActiveDescendant(frame, cfg));
+    findings.push(...detectMultipleStateChangesSameElement(frame, cfg));
+    findings.push(...detectRapidIdenticalAnnouncements(frame, cfg));
+  }
+  const severityOrder = { high: 0, medium: 1, low: 2 };
+  findings.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+  const summary = {
+    high: findings.filter((f) => f.severity === "high").length,
+    medium: findings.filter((f) => f.severity === "medium").length,
+    low: findings.filter((f) => f.severity === "low").length,
+    total: findings.length
+  };
+  const deductions = summary.high * 25 + summary.medium * 10 + summary.low * 3;
+  const score = Math.max(0, 100 - deductions);
+  return { findings, summary, score };
+}
+function formatVerbosityReport(report) {
+  const lines = [];
+  lines.push("");
+  lines.push("=== VERBOSITY ANALYSIS REPORT ===");
+  lines.push("");
+  lines.push(`Score: ${report.score}/100 ${report.score >= 80 ? "(Good)" : report.score >= 50 ? "(Needs attention)" : "(Critical verbosity issues)"}`);
+  lines.push(`Findings: ${report.summary.total} (${report.summary.high} high, ${report.summary.medium} medium, ${report.summary.low} low)`);
+  lines.push("");
+  if (report.findings.length === 0) {
+    lines.push("No verbosity issues detected. Announcements appear clean.");
+    return lines.join("\n");
+  }
+  for (let i = 0; i < report.findings.length; i++) {
+    const finding = report.findings[i];
+    const severityIcon = finding.severity === "high" ? "\u2718" : finding.severity === "medium" ? "\u26A0" : "\u2139";
+    lines.push(`${severityIcon} [${finding.severity.toUpperCase()}] ${finding.pattern}`);
+    lines.push(`  Element: ${finding.elementSelector}`);
+    lines.push(`  Window: ${finding.timeWindow.start}ms - ${finding.timeWindow.end}ms`);
+    lines.push(`  ${finding.description}`);
+    lines.push("");
+    lines.push("  Affected: " + finding.affectedReaders.join(", "));
+    lines.push("");
+    lines.push("  Remediation:");
+    for (const step of finding.remediation) {
+      lines.push(`    - ${step}`);
+    }
+    lines.push("");
+    if (i < report.findings.length - 1) {
+      lines.push("  " + "\u2500".repeat(60));
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/mcp.ts
 function renderOutput(model, screenReader) {
   if (screenReader === "all") {
@@ -2599,6 +2907,38 @@ server.tool(
     }
   }
 );
+server.tool(
+  "analyze_verbosity",
+  "Detect redundant and duplicate screen reader announcements in a sequence of accessibility events. Identifies patterns like simultaneous aria-selected + live region updates that cause VoiceOver to read the same content 2-3 times. Provides specific remediation steps and affected screen readers.",
+  {
+    events: z.array(z.object({
+      type: z.string().describe("Event type: STATE_CHANGED, ANNOUNCEMENT, FOCUS_CHANGED, ACCESSIBLE_NAME_CHANGED, etc."),
+      timestamp: z.number().describe("Milliseconds since session start"),
+      target: z.object({
+        role: z.string().describe("ARIA role of the target element"),
+        accessibleName: z.string().describe("Computed accessible name"),
+        selector: z.string().describe("CSS selector for the element")
+      }),
+      payload: z.record(z.unknown()).describe("Event payload (kind field discriminates type)")
+    })).describe("Chronologically ordered accessibility events (from runtime engine or manual capture)"),
+    interaction_frame_window: z.number().optional().describe("Time window (ms) to group related events into a single interaction (default: 150)")
+  },
+  async ({ events, interaction_frame_window }) => {
+    try {
+      const config = interaction_frame_window ? { interactionFrameWindow: interaction_frame_window } : void 0;
+      const report = analyzeVerbosity(events, config);
+      const output = formatVerbosityReport(report);
+      return {
+        content: [{ type: "text", text: output }]
+      };
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : "Unknown error"}` }],
+        isError: true
+      };
+    }
+  }
+);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);