API Reference

# Analyze an HTML file (default JSON output)
speakable page.html

import { parseHTML } from '@reticular/speakable';

// Parse any HTML string — raw snippets, full pages, file contents
const { document, warnings } = parseHTML('<button>Submit</button>');

// Or read from a file
import { readFileSync } from 'fs';
const html = readFileSync('page.html', 'utf-8');
const result = parseHTML(html);

import {
  buildAccessibilityTree,
  buildAccessibilityTreeWithSelector,
  computeAccessibleName,
  computeRole,
} from '@reticular/speakable';

// Build the full accessibility tree from a DOM element
const { model, warnings } = buildAccessibilityTree(document.body);

// Or filter to specific elements with a CSS selector
const results = buildAccessibilityTreeWithSelector(document.body, 'button');

import { renderNVDA, renderJAWS, renderVoiceOver, renderAuditReport }
  from '@reticular/speakable';

renderNVDA(model);          // plain text
renderNVDA(model, true);    // ANSI-colored output
renderJAWS(model);          // JAWS-style output
renderVoiceOver(model);     // VoiceOver-style output
renderAuditReport(model);   // structured audit report

import { serializeModel, deserializeModel, validateModel }
  from '@reticular/speakable';

// Serialize to deterministic JSON (sorted keys)
const json = serializeModel(model);

// Deserialize back with validation
const restored = deserializeModel(json);

// Validate model structure (throws ValidationError)
validateModel(model);

interface AnnouncementModel {
  version: { major: number; minor: number };
  root: AccessibleNode;
  metadata: {
    extractedAt: string;   // ISO 8601 timestamp
    sourceHash?: string;   // hash of source HTML
  };
}

interface AccessibleNode {
  role: AccessibleRole;       // "button", "link", "heading", etc.
  name: string;               // computed accessible name
  description?: string;       // aria-describedby / title
  value?: AccessibleValue;    // form control values
  state: AccessibleState;     // expanded, checked, pressed, etc.
  focus: FocusInfo;           // { focusable, tabindex? }
  children: AccessibleNode[]; // child nodes
}

# Compare two HTML files
speakable new.html --diff old.html

# Diff with text output
speakable new.html --diff old.html -f text

import { diffAccessibilityTrees } from '@reticular/speakable';

const diff = diffAccessibilityTrees(oldTree, newTree);
// diff.changes → [{ type, path, node?, changes? }]
// diff.summary → { added, removed, changed, total }