@rindle/narrator-react

0.0.0 · Public export map; development manifest version (0.0.0).

Source revision 05d0bf2c2e56 · build details

Source revision: 05d0bf2c2e56.
TypeScript input SHA-256: aabe6cfcc4172b870d5e272142958e9ea8d8784c2aa23133156e5a7ee633318e
Generated 2026-09-04T23:58:25.590Z with TypeScript 6.0.3. Public TypeScript checks and declaration emit passed. Package runtime tests are separate.

Entry point source

Narration

InterfaceDeclaration · Source: packages/narrator-react/src/index.ts:25 · Supporting declarations

A stable handle over a query's live narration buffer.

export interface Narration {
    /** Drain the events accumulated since the last call, then clear — call this when you hand context
     *  to an agent (e.g. on chat send). */
    take(): SemanticEvent[];
    /** Discard the buffer without returning it. */
    clear(): void;
}

useNarration

FunctionDeclaration · Source: packages/narrator-react/src/index.ts:40 · Supporting declarations

Narrate a live query's change stream into buffered {@link SemanticEvent}s — the agent-facing twin of useQuery. It drives off the view's OWN onChanges channel (net of no-op rebase cycles, so a correctly predicted optimistic write narrates nothing) and needs no store-global qid filter.

The returned handle is STABLE and does NOT re-render on each change — narration feeds an agent, not the DOM. Drain it with take() at the moment you send context. Pass a STABLE registry (a module const): a fresh object each render re-subscribes the view.

export declare function useNarration<Q extends AnyQuery>(query: Q, registry: NarratorRegistry, opts?: UseNarrationOptions): Narration;

UseNarrationOptions

InterfaceDeclaration · Source: packages/narrator-react/src/index.ts:10 · Supporting declarations

Options for {@link useNarration}.

export interface UseNarrationOptions {
    /** The registry key for this query's templates. Defaults to a named query's `name`; pass it for an
     *  ad-hoc (unnamed) query, e.g. `{ as: "deckSlides" }`. */
    as?: string;
    /** Context handed to every template (e.g. a human subject label). */
    ctx?: NarrateContext;
    /** Which delivery phases to narrate. Default `["batch"]` — the initial `snapshot` is the current
     *  state (not a change), so "tell me what CHANGED" ignores it. Pass `["snapshot", "batch"]` to also
     *  narrate the initial rows. */
    phases?: ChangePhase[];
    /** Cap the retained event buffer; oldest drop first. Default 200. */
    max?: number;
}