Compatibility
Check supported framework ranges, server behavior, and the limits of automated browser coverage.
Tested integration matrix
Use these ranges when choosing an adapter for an existing app. A checked version is the repository's pinned dependency, not a claim that every version in its range has been tested.
| Integration | Declared peer range | Checked version |
|---|---|---|
| React / React DOM | ^18.2.0 or ^19.0.0 | 19.2.8 |
| AI SDK | ai >=7.0.0 <7.1.0 / @ai-sdk/react >=4.0.0 <4.1.0 | 7.0.77 / 4.0.80 |
| assistant-ui | @assistant-ui/core >=0.3.13 <0.4.0 | 0.3.15 |
| AG-UI | @ag-ui/client >=0.0.59 <0.0.60 | 0.0.59 |
All published packages require Node.js 22+. Host frameworks can have additional peers; the AI SDK guide lists its Zod requirements. Install instructions in each integration guide assume an existing working host app.
CopilotKit reuses the AG-UI adapter through its public v2 hook. This repository does not pin or typecheck a CopilotKit host version; validate its hook and resolved AG-UI dependency in your app. Retest these ranges when changing framework dependencies.
Browser and server support
| Layer | Server behavior | Browser behavior |
|---|---|---|
| Core | Runs without browser globals | Schedules normalized events |
| DOM | Stays inactive when document is unavailable | Delivers live-region updates |
| React | Renders stable hidden regions | Connects runtime delivery after hydration |
| Adapters | Imports do not require browser globals | Observe the host state or callbacks you supply |
Keep providers and browser effects within a client boundary in React Server Components applications. Framework-neutral integrations should attach browser delivery when their surface mounts and dispose it when that surface unmounts.
Automated browser tests have limits
| Engine | Automated coverage | Required manual evidence |
|---|---|---|
| Chromium | Keyboard, focus, structure, DOM delivery | Named browser and screen-reader workflow |
| Firefox | Keyboard, focus, structure, DOM delivery | Named browser and screen-reader workflow |
| WebKit | Keyboard, focus, structure, DOM delivery | Safari and platform screen-reader workflow |
Browser output is not speech evidence
WebKit provides useful coverage, but it cannot replace Safari testing with a real screen reader. Browser transcripts record DOM delivery and deterministic tests record library behavior; neither proves what assistive technology speaks. Record hands-on browser and screen-reader results separately.
Development package compatibility
| Entry | Dependency requirement | Purpose |
|---|---|---|
@generative-a11y/devtools | Core dependency; package declares React / React DOM ^19.0.0 peers | Headless bounded diagnostic store |
@generative-a11y/devtools/overlay | React / React DOM ^19.0.0 | Browser trace explorer |
@generative-a11y/core/testing | No test-runner peer; pass your Vitest expect for matchers | Record, replay, and semantic assertions |
The headless store uses public core contracts. React peers are declared at the package level, even when importing only the headless entry. The overlay's React requirement is narrower than the React accessibility provider's range. Testing helpers accept Vitest structurally and do not add a test-runner dependency to core.
Troubleshooting
Fix missing, repeated, late, delayed, or noisy announcements by checking each step from the framework event to the browser update.
Stability and migrations
Understand generative-a11y package versions, framework compatibility ranges, deprecation policy, migration notes, and the guarantees available before 1.0.