DOM ENGINEV0.27.0FIZLET
Start

ANNOUNCE V0.27.0 BETA

@fzlt/core/announce

Game events read out to screen readers through one polite live region, rate-limited. The game says what happened on the event ring (in its steps, as it already does for sound and effects); words turns an event into a sentence in render; the region speaks at most once per gap seconds. const a = announce(engine, { words: (e) => e.type === "score" ? Score ${e.a} : e.type === "over" ? "Game over" : null, }); a.say("lives", "2 lives left"); // or directly, from a HUD or a menu - One region per page, shared by every engine: [data-fz-announce], role status, polite, atomic, visually hidden. Made on the first word, never before; destroy() removes it if this one made it. - Coalesced by key (an event's type): a newer sentence for the same key replaces the waiting one, so a score that ticks ten times a second is read once, as its latest value. Waiting sentences are read together, in the order their keys first came, joined with ". ". - The same sentence twice is read twice (a trailing no-break space alternates). - Nothing in step; in render it reads the ring only. One timer while something waits, none after. - Recall: destroy() (or the engine's) removes the system, the timer and the region it made.

@fzlt/core/announce · GZIP612 B0.6 KB of a 0.6 KB budget

Measured on this build: minified and gzipped with everything it imports, the way npm run size checks the budget in CI.

STATUS · what the flags meanBETA

Tested and budgeted; not yet carried by a shipped game, or its API is still moving. New (E14): no released game reads out through it yet.

SINCE
v0.28.0
SHIPPED IN
no released game or page yet
MODULES · hosted on this site
import { announce } from "https://fizlet.com/dist/announce.js";
NPM · @fzlt/core
npm install @fzlt/core
import { announce } from "@fzlt/core/announce";
IN SHORT
const a = announce(e, { words: (ev) => ev.type === "score" ? `Score ${ev.a}` : null });
e.events.emit("score", score); // in a step, as for sound: read once per gap, latest value
a.say("over", "Game over"); a.flush(); // from a HUD or a result screen

API

Every export with its signature, parameters, return type, doc comment and status flag, generated at build time from the published type declarations of v0.27.0 by the TypeScript compiler. For AI agents: the whole API as plain text.

AnnounceOptions interface BETA

Options for announce(): words(event) turns ring events into sentences, gap is the least time between writes, doc the document.

export interface AnnounceOptions {
    /** An event in words, or nothing (null, undefined, "" or false) to stay quiet. Runs in render. */
    words?: (e: FizEvent) => string | null | undefined | false | void;
    /** Seconds between two writes to the region (default 1). */
    gap?: number;
    /** The page (default: the engine root's document, else `document`). */
    doc?: Document;
}

announce function BETA

Game events read out to screen readers through one polite live region per page, coalesced by key and rate-limited; destroy() removes the region.

announce(engine: Engine, o?: AnnounceOptions): Announcer
engine
Engine
o?
AnnounceOptions optional
Returns
Announcer
Declaration
export declare function announce(engine: Engine, o?: AnnounceOptions): {
    /** Queue a sentence under a key (coalesced with what waits under that key). */
    say: (key: string, text: string) => void;
    /** Read what waits now, ignoring the gap (a result screen that must not wait). */
    flush: () => void;
    /** Remove the system, the timer and the region this one made. */
    destroy: () => void;
};

Announcer type BETA

What announce() returns: say, flush, destroy.

export type Announcer = ReturnType<typeof announce>;