generative-a11y
GitHubnpm
Core

createGenerativeA11y

Create the core runtime that turns app events into well-timed AnnouncementIntent objects and useful debugging details.

Signature and import

Create one runtime for your app or for each conversation that needs separate settings. Connect delivery before sending events that can produce output.

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

const runtime = createGenerativeA11y({
  preset: "balanced",
  onAnnouncement(intent) {
    deliver(intent);
  },
});

How this code works

  1. 01
    Import the constructor

    Import createGenerativeA11y from the package root.

  2. 02
    Choose a preset

    Presets supply default behavior. policy changes only the settings you provide.

  3. 03
    Connect output

    onAnnouncement registers the first listener. Browser apps usually use connectRuntimeToDOM instead.

Options and return values

optionsGenerativeA11yOptionsRequired

Construction options for policy, time, announcement delivery, delivery errors, and diagnostics.

Default
{} is not implicit
returnGenerativeA11yRuntimeReturn

An owned runtime with synchronous dispatch, subscriptions, policy inspection, pending work inspection, and disposal.

Default
n/a

GenerativeA11yOptions

Options are read during construction. Nested policy overrides merge with the selected preset.

Options and return values

presetPresetNameOptional

Selects a complete baseline policy: minimal, balanced, verbose, or completion-only behavior.

Default
"balanced"
policyPolicyOverridesOptional

Overrides only intentional text, tool, status, pacing, channel, and capacity differences.

Default
{}
clockClockOptional

Injects time and timers. Use ManualClock for deterministic tests.

Default
systemClock
onAnnouncementAnnouncementListenerOptional

Registers the first intent listener. Dispatch that produces output requires at least one listener.

Default
undefined
onDeliveryError(error, intent) => voidOptional

Observes listener failures while delivery continues to later listeners.

Default
undefined
onDiagnosticDiagnosticListenerOptional

Observes queued, merged, suppressed, cancelled, announced, and delivery-error decisions.

Default
undefined

GenerativeA11yRuntime methods

Runtime methods are synchronous. Unsubscribe functions and dispose are idempotent.

Options and return values

dispatch(event)booleanMethod

Processes one serializable GenerativeA11yEvent synchronously. Returns false after disposal or when a nested dispatch transaction reaches capacity.

Default
n/a
getPolicy()ReadonlyAnnouncementPolicyMethod

Returns the resolved immutable policy used by this runtime.

Default
n/a
pendingCount()numberMethod

Counts scheduler candidates and owned response flush timers. Use it for tests and diagnostics, not application rendering.

Default
n/a
subscribeAnnouncements(listener)() => voidMethod

Registers an AnnouncementIntent listener and returns an idempotent unsubscribe function.

Default
n/a
subscribeDiagnostics(listener)() => voidMethod

Registers an AnnouncementDiagnostic listener and returns an idempotent unsubscribe function.

Default
n/a
subscribeDiagnosticEvents(listener)() => voidMethod

Observes a versioned ordered stream of source events and diagnostic decisions without changing scheduling.

Default
n/a
getDiagnosticSnapshot()RuntimeDiagnosticSnapshotV1Method

Returns immutable content-free response, tool, queue, and flush timing state for diagnostic consumers.

Default
n/a
dispose()voidMethod

Cancels every owned timer, clears bounded state and queued work, then releases listeners. Repeated calls are safe.

Default
n/a

Complete response lifecycle

Each delta contains only new text. A completed event announces useful text that is still waiting, then closes the response.

typescript
const accepted = runtime.dispatch({
  type: "response.started",
  responseId: "report-1",
});

runtime.dispatch({
  type: "response.text.delta",
  responseId: "report-1",
  delta: "The migration completed successfully.",
});

runtime.dispatch({
  type: "response.completed",
  responseId: "report-1",
});

console.log({ accepted, pending: runtime.pendingCount() });
runtime.dispose();

How this code works

  1. 01
    Start the response

    Send response.started before text or final events for this responseId.

  2. 02
    Send new text

    Each delta contains only the text added since the last event.

  3. 03
    Finish the response

    Completion announces useful text that is still waiting and cancels response timers.

  4. 04
    Clean up

    Call dispose when the app no longer needs the runtime.