/** Options for a single `Announcer.announce()` call. */
export interface AnnounceOptions{
/** Bypass any in-progress throttle window and flush this text immediately. */
force?:boolean;}export interface AnnouncerOptions{
/** Throttle window in ms. Repeated `announce()` calls arriving within this
*  window of the first call in a burst collapse to one trailing-edge flush
*  of the latest text. Defaults to 500. */
throttleMs?:number;
/** Invoked with the coalesced text whenever a burst flushes (on the
*  trailing edge, or immediately for a `{ force: true }` call). */
onFlush:(text:string)=>void;
/** Timer host used for scheduling and cancellation. Components that can be adopted into another
*  document should pass (or later bind) that document's `defaultView`. */
timerHost?:AnnouncerTimerHost;}
/** Minimal timer surface used by `Announcer`; a `Window` satisfies this contract. */
export interface AnnouncerTimerHost{setTimeout(handler:()=>void,timeout:number):number;clearTimeout(handle:number):void;}
/**
* Trailing-edge debounce/coalesce for screen-reader announcements.
*
* Streaming UIs (token-by-token chat responses, progress ticks, etc.)
* naturally produce far more candidate announcements than a screen-reader
* user can usefully absorb — reading every incremental chunk aloud is spam,
* not information. `Announcer` collapses a burst of `announce()` calls
* arriving within `throttleMs` of the *first* call in that burst down to a
* single flush of the latest text: superseded intermediate text is dropped
* outright, never queued or concatenated. Passing `{ force: true }` always
* flushes immediately regardless of any window in progress, so a final or
* terminal message (e.g. "response complete") is never swallowed mid-burst.
*
* The class itself is pure timing/state logic with no DOM dependency — it
* knows nothing about ARIA, elements, or Lit; `acquireAnnouncementSink()`
* below is the DOM half that a flush writes into. `<lr-live-region>`
* (`../components/utility/live-region/live-region.js`) is the element that
* composes the two. Other components that need throttled announcements (a
* stream-status indicator, a tool-call chip's status transitions, a chat
* message's streaming state) should reuse that wrapper rather than
* instantiating `Announcer` directly.
*/
export declare class Announcer{private _throttleMs;private readonly onFlush;private timerHost;private timer?;private pending?;constructor(options:AnnouncerOptions);
/** Throttle window in ms. Safe to change between bursts; a flush already
*  scheduled keeps the deadline it was scheduled with. A non-finite value (`NaN`/`Infinity`)
*  resets it to the documented 500ms default; a negative finite value clamps to 0 (the next
*  burst still schedules an async timer, never an inline/synchronous flush) -- mirrors
*  `<lr-live-region>`'s own `safeThrottleMs` normalization of this same field. */
get throttleMs():number;set throttleMs(value:number);
/** The latest text awaiting flush, if a burst is currently in progress. */
get pendingText():string|undefined;
/** Whether a flush is currently scheduled (a burst is in progress). */
get isPending():boolean;
/**
* Queue `text` for announcement. Within a single throttle window, only the
* latest text queued survives — this call always overwrites whatever an
* earlier call in the same burst queued.
*/
announce(text:string,options?:AnnounceOptions):void;
/**
* Rebind future timers to `timerHost`. A pending burst is canceled on the previous host and
* rescheduled on the new one without losing its latest text.
*/
setTimerHost(timerHost:AnnouncerTimerHost):void;
/** Cancel any pending (not yet flushed) announcement without flushing it. */
cancel():void;private flush;}
/** Urgency of a shared announcement sink — mirrors native `aria-live`. */
export type AnnouncementPoliteness='polite'|'assertive';
/** Options for `acquireAnnouncementSink()`. */
export interface AnnouncementSinkOptions{
/** Document the sink is mounted in. Defaults to the ambient `document`; pass the consumer's own
*  `ownerDocument` when it may live in an iframe or another adopted document. */
document?:Document;
/** Component or other semantic source whose accessibility visibility gates writes. A document
*  sink cannot inherit `hidden`/`inert`/CSS/closed-details visibility from the source it
*  announces for. A box-generating source also honors `content-visibility:auto` skipping;
*  browsers cannot expose that distinction for a source whose own display is `contents`. */
source?:Element;
/** How long an announced node stays in the sink before it is swept, in ms. Long enough for a
*  screen reader to have read it; short enough that focus returning to the page later never
*  finds a pile of stale text to re-read. Defaults to 5000. */
messageTtlMs?:number;}
/** A ref-counted handle on the shared per-document, per-politeness live region. */
export interface AnnouncementSink{
/** The shared light-DOM element carrying `role`/`aria-live`. */
readonly element:HTMLElement;
/** The politeness this handle was acquired for. */
readonly politeness:AnnouncementPoliteness;
/** Sweep delay for nodes this handle appends; see `AnnouncementSinkOptions.messageTtlMs`. */
messageTtlMs:number;
/** Append `text` as a new child node — an *addition*, which is what assistive tech is asked to
*  read. Empty text is ignored. No-op once `release()` has been called. A handle retains only
*  its latest 32 pending additions, and the shared region retains only the latest 128 across all
*  handles; older nodes have already been exposed as additions and are removed without
*  fabricating or concatenating announcement text. All pending nodes share one batched sweep
*  timer per document/politeness region. */
announce(text:string):void;
/** Drop this handle: its still-pending nodes are removed, their sweeps canceled, and the shared
*  region is unmounted once the last handle releases. Idempotent. */
release():void;}
/**
* Attribute that identifies a shared announcement sink, valued with its politeness
* (`data-lr-live-region="polite"`). Stable and documented so a consumer's own DOM diffing,
* snapshot testing, or `MutationObserver` can recognize (and ignore) library-owned nodes that
* appear at the end of `<body>`.
*/
export declare const ANNOUNCEMENT_SINK_ATTRIBUTE:string;
/**
* Acquire the shared live region for `politeness` in `options.document`, mounting it in that
* document's light DOM on first use and ref-counting it away when the last holder releases.
*
* A live region rendered inside a shadow root is not reliably announced — JAWS with Firefox
* ignores one entirely — so every announcement this library makes has to land in the host
* document instead. One region per politeness is shared by every consumer: creating a region and
* filling it in the same task is also unreliable (assistive tech has to have been observing the
* region before the text arrives), so the region is mounted at acquire time, ahead of any text.
*/
export declare function acquireAnnouncementSink(politeness:AnnouncementPoliteness,options?:AnnouncementSinkOptions):AnnouncementSink;