Core

createAnnouncementScheduler

Low-level scheduler for timing, duplicate removal, merging, cancellation, queue priority, and repeatable tests.

Signature and cleanup

Most apps should use createGenerativeA11y. Use the scheduler directly only if your app already decides which events should produce announcements.

typescript

const scheduler = createAnnouncementScheduler({
  clock,
  minimumGapMs: 750,
  dedupeWindowMs: 4_000,
  maxQueueSize: 64,
  onAnnouncement: deliver,
  onDiagnostic: recordDiagnostic,
});

scheduler.schedule({
  channel: "polite",
  text: "The report is ready.",
  sourceType: "response.completed",
  scope: "response:report-1",
  capacityPriority: "content",
});

How this code works

01
Supply a clock
Scheduler timers use your Clock, so tests can control time.
02
Limit the queue
maxQueueSize limits pending output.
03
Set queue priority
Response text can replace a status update when the queue is full.
04
Group related work
Use one scope to cancel pending work when that response or tool ends.

Options and return values

optionsAnnouncementSchedulerOptionsRequired

Clock, pacing, capacity, announcement listener, and optional diagnostic callbacks.

Default: n/a

returnAnnouncementSchedulerReturn

Owned scheduler with schedule, cancelScope, pendingCount, and dispose methods.

Default: n/a

ScheduleAnnouncement

A candidate describes prepared user-facing output. It must not contain raw backend data.

Options and return values

channelpolite | assertiveRequired

Requested announcement urgency.

Default: n/a

textstringRequired

Translated text with whitespace normalized by the runtime.

Default: n/a

sourceTypeGenerativeA11yEvent['type']Required

Identifies the app event that produced this candidate.

Default: n/a

delayMsnumberOptional

Additional eligibility delay measured by the injected clock.

Default: 0

scopestringOptional

Key used to cancel pending work for one response, tool, or interaction.

Default: undefined

coalesceKeystringOptional

Replaces equivalent pending work with the newest candidate.

Default: undefined

dedupeKeystringOptional

Suppresses equivalent recent delivery within the dedupe window.

Default: normalized text

capacityPrioritystatus | contentOptional

Allows content to displace status work when bounded capacity is exhausted.

Default: "content"

AnnouncementScheduler methods

Dispose cancels the owned timer and pending queue.

Options and return values

schedule(candidate)string | undefinedMethod

Returns a scheduled ID, or undefined when the candidate is merged, deduplicated, rejected, or the scheduler is disposed.

Default: n/a

cancelScope(scope)voidMethod

Cancels every pending candidate with the matching scope.

Default: n/a

pendingCount()numberMethod

Returns the current bounded queue length.

Default: n/a

dispose()voidMethod

Cancels the timer and queue. Repeated calls are safe.

Default: n/a