@generative-a11y/dom

Install browser delivery

DOM uses core without depending on React or an AI framework.

Terminal

npm install @generative-a11y/core @generative-a11y/dom

Core prepares announcement intents; DOM delivers them with ariaNotify when available and hidden live regions as a fallback. See bindRuntime for connection and cleanup.

Public export map

Choose direct announcing or bind an existing runtime.

Category	Exports	Reference
Delivery	createAnnouncer	/api/dom/create-announcer
Runtime binding	bindRuntime	/api/dom/bind-runtime
Focus	captureFocus, focusElement, restoreFocus	/api/dom/focus
Attention	createAttentionStore	/api/dom/attention
Preferences	createPreferenceStore and mapping helpers	/api/dom/preferences

Public declarations: @generative-a11y/dom

All exported values and types for this entry point. Import these names from @generative-a11y/dom; the signatures below are reference material, not a replacement for the ownership and lifecycle guidance above.

Announcer — type

interface Announcer {
    announce(intent: AnnouncementIntent): DeliveryResult;
    getRegions(): LiveRegions | undefined;
    dispose(): void;
}

AnnouncerOptions — type

interface AnnouncerOptions {
    document?: Document;
    mode?: DeliveryMode;
    regions?: LiveRegions;
    onDelivery?: (result: DeliveryResult) => void;
}

AttentionBinding — type

interface AttentionBinding {
    dispose(): void;
}

AttentionBindingOptions — type

interface AttentionBindingOptions {
    readonly runtime: Runtime;
    readonly attentionStore: AttentionStore;
}

AttentionIntersectionObserver — type

interface AttentionIntersectionObserver {
    observe(target: Element): void;
    unobserve(target: Element): void;
    disconnect(): void;
}

AttentionIntersectionObserverFactory — type

type AttentionIntersectionObserverFactory = (callback: IntersectionObserverCallback, options?: IntersectionObserverInit) => AttentionIntersectionObserver;

AttentionSnapshot — type

interface AttentionSnapshot {
    readonly visibility: "visible" | "hidden" | "unknown";
    readonly windowFocus: "focused" | "blurred" | "unknown";
    readonly focusArea: "composer" | "conversation" | "elsewhere" | "none" | "unknown";
    readonly newestResponse: "visible" | "outside" | "unobserved" | "unknown";
    readonly mode: "foreground" | "background" | "reading-history" | "away" | "unknown";
}

AttentionStore — type

interface AttentionStore extends ExternalStore<AttentionSnapshot> {
    registerComposer(element: Element): () => void;
    registerConversation(element: Element): () => void;
    registerNewestResponse(element: Element): () => void;
    dispose(): void;
}

AttentionStoreOptions — type

interface AttentionStoreOptions {
    document?: Document;
    createIntersectionObserver?: AttentionIntersectionObserverFactory;
    intersectionObserverInit?: IntersectionObserverInit;
}

bindAttention — value

/** Borrow a store and runtime, forwarding observations without changing overrides. */
declare function bindAttention({ runtime, attentionStore, }: AttentionBindingOptions): AttentionBinding;

bindRuntime — value

declare function bindRuntime(runtime: Runtime, options?: AnnouncerOptions): RuntimeBinding;

captureFocus — value

declare function captureFocus(selectedDocument?: Document): FocusCapture;

CorePreferenceConfiguration — type

interface CorePreferenceConfiguration {
    readonly preset: PresetName;
    readonly policy?: PolicyOverrides;
}

createAnnouncer — value

declare function createAnnouncer(options?: AnnouncerOptions): Announcer;

createAttentionStore — value

declare function createAttentionStore(options?: AttentionStoreOptions): AttentionStore;

createPreferenceStore — value

declare function createPreferenceStore(options?: PreferenceStoreOptions): PreferenceStore;

defaultPreferences — value

declare const defaultPreferences: PreferenceSchemaV1;

DeliveryMode — type

type DeliveryMode = "auto" | "live-region";

DeliveryResult — type

interface DeliveryResult {
    status: "notified" | "mutated" | "unavailable" | "disposed";
    method: "aria-notify" | "live-region" | "none";
    channel: AnnouncementIntent["channel"];
    announcementId: string;
    sourceType: AnnouncementIntent["sourceType"];
    at: number;
    sourceEventId?: string;
    responseId?: string;
    toolId?: string;
    interactionId?: string;
    /** Stable logical run identity associated with the delivered intent. */
    runId?: string;
    /** Stable run attempt identity associated with the delivered intent. */
    runInstanceId?: string;
    /** Stable logical step identity associated with the delivered intent. */
    stepId?: string;
    /** Stable step attempt identity associated with the delivered intent. */
    stepInstanceId?: string;
    error?: {
        name: string;
        message: string;
    };
}

ExternalStore — type

interface ExternalStore<T> {
    subscribe(listener: () => void): () => void;
    getSnapshot(): T;
    getServerSnapshot(): T;
}

FocusCapture — type

interface FocusCapture {
    readonly document: Document | null;
    readonly target: Element | null;
}

focusElement — value

declare function focusElement(target: Element, options?: FocusElementOptions): FocusResult;

FocusElementOptions — type

interface FocusElementOptions {
    preventScroll?: boolean;
}

FocusResult — type

type FocusResult = {
    readonly status: "focused";
    readonly target: Element;
} | {
    readonly status: "skipped";
    readonly reason: FocusSkippedReason;
    readonly target: Element | null;
};

FocusSkippedReason — type

type FocusSkippedReason = "unavailable" | "cross-document" | "disconnected" | "disabled" | "hidden" | "aria-hidden" | "inert" | "missing-focus" | "guard-mismatch" | "focus-error" | "focus-not-applied";

LiveRegions — type

interface LiveRegions {
    polite: HTMLElement;
    assertive: HTMLElement;
}

normalizePreferences — value

declare function normalizePreferences(value: PreferenceSchemaV1): PreferenceSchemaV1;

PreferenceDiagnostic — type

interface PreferenceDiagnostic {
    readonly source: PreferenceDiagnosticSource;
    readonly code: PreferenceDiagnosticCode;
    readonly error?: Readonly<{
        name: string;
        message: string;
    }>;
}

PreferenceDiagnosticCode — type

type PreferenceDiagnosticCode = "operation-failed" | "invalid-json" | "invalid-preference" | "unsupported-version";

PreferenceDiagnosticSource — type

type PreferenceDiagnosticSource = "storage-read" | "storage-write" | "storage-event" | "event-subscribe" | "event-unsubscribe";

PreferencePersistence — type

interface PreferencePersistence {
    readonly key: string;
    readonly storage?: PreferenceStorage;
    readonly events?: PreferenceStorageEventSource;
}

PreferenceSchemaV1 — type

type PreferenceSchemaV1 = Readonly<{
    version: 1;
    preset: "completion-only";
}> | Readonly<{
    version: 1;
    preset: "minimal" | "balanced" | "verbose";
    streaming: StreamingVerbosity;
    tools: ToolVerbosity;
}>;

preferencesToCoreConfiguration — value

declare function preferencesToCoreConfiguration(value: PreferenceSchemaV1): CorePreferenceConfiguration;

PreferenceStorage — type

interface PreferenceStorage {
    getItem(key: string): string | null;
    setItem(key: string, value: string): void;
}

PreferenceStorageEvent — type

interface PreferenceStorageEvent {
    readonly key: string | null;
    readonly newValue: string | null;
    readonly storageArea?: PreferenceStorage | null;
}

PreferenceStorageEventSource — type

interface PreferenceStorageEventSource {
    subscribe(listener: (event: PreferenceStorageEvent) => void): () => void;
}

PreferenceStore — type

interface PreferenceStore extends ExternalStore<PreferenceSchemaV1> {
    setPreferences(value: PreferenceSchemaV1): void;
    dispose(): void;
}

PreferenceStoreOptions — type

interface PreferenceStoreOptions {
    readonly defaultValue?: PreferenceSchemaV1;
    readonly persistence?: PreferencePersistence;
    readonly onDiagnostic?: (diagnostic: PreferenceDiagnostic) => void;
}

restoreFocus — value

declare function restoreFocus(capture: FocusCapture, options?: RestoreFocusOptions): FocusResult;

RestoreFocusOptions — type

interface RestoreFocusOptions extends FocusElementOptions {
    onlyIfFocusWithin?: Element;
}

RuntimeBinding — type

interface RuntimeBinding {
    announcer: Announcer;
    dispose(): void;
}

samePreferences — value

declare function samePreferences(left: PreferenceSchemaV1, right: PreferenceSchemaV1): boolean;

StreamingVerbosity — type

type StreamingVerbosity = "preset" | "off" | "completion" | "paragraph" | "sentence";

ToolVerbosity — type

type ToolVerbosity = "preset" | "off" | "failures" | "status" | "progress";

@generative-a11y/dom

Install browser delivery

Public export map

Public declarations: @generative-a11y/dom

On this page