Stability and migrations

Public packages follow semantic versioning

Published package versions describe the public exports, event contracts, and documented behavior of that package. Patch releases preserve compatible behavior and minor releases add compatible capability. Before 1.0, a documented minor release may include a breaking public API change; after 1.0, breaking public API changes require a major release.

Internal implementation details, private framework state, and undocumented deep imports are not compatibility surfaces.

Adapter stability includes peer ranges

Framework adapters are supported only with the versions listed in their peer dependency ranges. A new framework version can change the public events an adapter receives even when generative-a11y has not changed.

• Review the compatibility matrix before upgrading a framework peer.
• Pin framework versions when your app depends on exact adapter behavior.
• Send core events directly when a framework does not report an event your app needs.

Package contracts are checked before publication

Release validation inspects package exports, declaration files, provenance-ready metadata, packed contents, dependency boundaries, and installability. Public entry points must resolve from the package users install.

• Every exported API has tests and documentation.
• Package manifests expose only supported public entry points.
• Packed artifacts are inspected instead of trusting the source tree.
• Framework adapters stay within their declared peer ranges.

Each release check answers a different question

A release runs code checks, browser tests, package validation, and a validator for hands-on screen-reader test records. Passing one check does not replace the others.

Migration checklist

Upgrade one package area at a time. Check runtime output first, then test in browsers and with the screen readers you support.

• Read the package release notes and peer dependency changes.
• Update one generative-a11y package family to a consistent version set.
• Run type checking and adapter translation tests.
• Compare diagnostics for suppression, cancellation, and delivery changes.
• Exercise stop, retry, tool failure, and approval workflows in a browser.
• Repeat the application's documented assistive-technology smoke test.

Deprecations remain documented

When an API is deprecated, its replacement and migration path remain documented until removal. This pre-1.0 naming update makes direct breaking replacements without a deprecation period. Release notes identify changed defaults, event semantics, ownership rules, and peer dependency ranges.

Public API naming update

This release replaces the earlier API names directly. There are no deprecated aliases. Update imports, type annotations, and runtime configuration together. The package provides context: createRuntime creates a core runtime, createAnnouncer creates browser delivery, and A11yProvider owns the React integration. Lifecycle event names and accessibility behavior are unchanged.

Associated types follow the same names: A11yProviderProps, AnnouncerOptions, Announcer, RuntimeBinding, SchedulerOptions, ChatObserverOptions, BindThreadOptions, StoreOptions, and OverlayOptions. The diagnostic snapshot's announcementCatalog field is now messages; its content-free { catalogId, locale } value is unchanged.

English is the default. Import messages only when customizing the copy:

import { createRuntime } from "@generative-a11y/core";

const runtime = createRuntime();

import { createRuntime } from "@generative-a11y/core";
import { en, type Messages } from "@generative-a11y/core/messages";

const messages = {
  ...en,
  id: "my-app.en.v1",
  messages: {
    ...en.messages,
    "response.completed": "Your answer is ready.",
  },
} satisfies Messages;

const runtime = createRuntime({ messages });

Messages is the complete configuration with an ID, locale and message map. A different language supplies every message; use your existing translation system inside the typed formatters. See localized announcements.

Additional type replacements

Integration clarity changes

• Provider dom is now delivery; its browser callback is onDelivery. Core and preference-store onDiagnostic callbacks retain their separate meaning.
• useBindings becomes useAttentionRefs, returning composerRef, conversationRef, and newestResponseRef directly. Use ref={composerRef}; these refs observe attention and add no semantic props. The former props types are removed; AttentionRefs describes the callbacks for host HTMLElements.
• Each adapter exports adapterInfo and AdapterInfo instead of CHAT_ADAPTER_METADATA/ChatAdapterMetadata, THREAD_ADAPTER_METADATA/ThreadAdapterMetadata, or AGENT_ADAPTER_METADATA/AgentAdapterMetadata.
• Requested delivery mode aria-notify is removed because it behaved exactly like auto. Use auto for notification with fallback, or live-region to choose that path. The observed result method can still be aria-notify.
• Configuration errors name the invalid field or missing documented message key without including supplied values.

See the API reference for the updated imports, options, and usage examples.