@rindle/narrator

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

createNarrator

FunctionDeclaration · Source: packages/narrator/src/narrator.ts:95 · Supporting declarations

Build a narrator over an app-supplied {@link NarratorRegistry}. Resolution is driven entirely by the per-query WireSchema passed to {@link Narrator.narrate}, so the narrator holds no schema state of its own.

export declare function createNarrator(narrators: NarratorRegistry): Narrator;

NamedRow

TypeAliasDeclaration · Source: packages/client/src/resolve.ts:26 · Supporting declarations

A row named against its level's wire columns.

export type NamedRow = Record<string, WireValue>;

NarrateContext

InterfaceDeclaration · Source: packages/narrator/src/narrator.ts:18 · Supporting declarations

Context a template may interpolate — e.g. a human label for the subscription's subject.

export interface NarrateContext {
    /** A human name for what the query is scoped to ("the Smith wedding"). */
    subject?: string;
    [k: string]: unknown;
}

Narrator

InterfaceDeclaration · Source: packages/narrator/src/narrator.ts:77 · Supporting declarations

export interface Narrator {
    /** Resolve + render a `FlatChange[]` for a named query into semantic events. `schema` is the
     *  query's `WireSchema`, captured from its `hello` frame (or read off `view.schema`) — the
     *  position→name source. */
    narrate(query: string, schema: WireSchema, changes: FlatChange[], phase: "snapshot" | "batch", ctx?: NarrateContext): SemanticEvent[];
    /** Format a batch of rendered events for an agent prompt (salience-marked, suppressions dropped). */
    digest(events: SemanticEvent[]): string;
}

NarratorRegistry

TypeAliasDeclaration · Source: packages/narrator/src/narrator.ts:66 · Supporting declarations

A registry of {@link QueryNarrator}s, keyed by defineQuery name. Supplied by the app.

export type NarratorRegistry = Record<string, QueryNarrator>;

QueryNarrator

InterfaceDeclaration · Source: packages/narrator/src/narrator.ts:49 · Supporting declarations

export interface QueryNarrator {
    /** Default importance of this query's events; an op handler may override via the return tuple. */
    salience: Salience;
    /** Handlers for changes at the ROOT level, by op. */
    root?: Partial<Record<"add" | "remove" | "edit", Template>>;
    /** Handlers for changes to a NESTED relationship, keyed by op — so ONE materialized view narrates
     *  its whole tree: e.g. a deck's title at the root, slide edits under `slides`, component adds under
     *  `components`. Key by the relationship's LEAF alias (`components`) for the common case, or by the
     *  FULL dotted alias-chain from the root (`slides.components`) to disambiguate two relationships that
     *  share a leaf alias at different tree positions (e.g. `slides.components` vs `appendix.components`).
     *  A dotted key wins over a leaf key when both match; a bare leaf key still matches at any depth. */
    related?: Record<string, RelatedNarrator>;
    /** Handlers for an aggregate slot (`countAs`), keyed by the count's alias. */
    counts?: Record<string, Template>;
}

Handlers for changes to ONE nested relationship (keyed by its alias in {@link QueryNarrator.related}), by op — plus an optional salience override for that relationship's events. A nested template reads row (the nested row), old, and parent (its immediate container — the deck for a slide, the slide for a component).

export interface RelatedNarrator {
    /** Override the query's default salience for events on this relationship (else inherits it). */
    salience?: Salience;
    add?: Template;
    remove?: Template;
    edit?: Template;
}

ResolvedChange

InterfaceDeclaration · Source: packages/client/src/resolve.ts:30 · Supporting declarations

One resolved change: a FlatChange lifted out of positional/indexed wire form into names, using the query's WireSchema (from hello) as the sole position→name source.

export interface ResolvedChange {
    /** Relationship-alias chain from the query root to the changed level (`[]` ⇒ the root rows). */
    aliasChain: string[];
    /** The alias of the changed level (`""` ⇒ root), i.e. the last of `aliasChain`. */
    alias: string;
    op: "add" | "remove" | "edit";
    /** The affected row, named. For `edit` this is the NEW row; see `old` for the prior one. */
    row: NamedRow;
    /** The prior row, named (present only for `edit`). */
    old?: NamedRow;
    /** The PARENT row (named), for a nested/aggregate change — e.g. the `ticket_type` whose `sold`
     *  count moved. Taken from the path's last `parentRow`; absent for a root-level change. */
    parent?: NamedRow;
    /** Set when the changed level is a `countAs`/aggregate slot. The value is EXACT — read from the
     *  slot's projected count column (`WireRel.project.col`). */
    aggregate?: {
        alias: string;
        value: WireValue;
        previous?: WireValue;
    };
    /** The raw node whose children a consumer can dig a named sub-row out of (via {@link subRow}). On
     *  an `add` the engine always ships it; on a `remove` it is present only when the consumer opted
     *  into the removed subtree (see the `op` mapping below). */
    node?: WireNode;
    /** The changed level's `WireSchema` — used by {@link subRow} to resolve a named sub of `node`. */
    levelSchema: WireSchema;
}

Salience

TypeAliasDeclaration · Source: packages/narrator/src/narrator.ts:15 · Supporting declarations

export type Salience = "alert" | "info" | "ambient";

SALIENCE_MARK

VariableDeclaration · Source: packages/narrator/src/narrator.ts:87 · Supporting declarations

Per-salience glyph for a rendered line.

export declare const SALIENCE_MARK: Record<Salience, string>;

salienceRank

VariableDeclaration · Source: packages/narrator/src/narrator.ts:90 · Supporting declarations

Order salience high→low.

export declare const salienceRank: (s: Salience) => number;

SemanticEvent

InterfaceDeclaration · Source: packages/narrator/src/narrator.ts:69 · Supporting declarations

One rendered semantic event. text === null was suppressed by its template (too ambient).

export interface SemanticEvent {
    query: string;
    phase: "snapshot" | "batch";
    salience: Salience;
    resolved: ResolvedChange;
    text: string | null;
}

Template

TypeAliasDeclaration · Source: packages/narrator/src/narrator.ts:35 · Supporting declarations

export type Template = (ctx: TemplateCtx) => string | null;

TemplateCtx

InterfaceDeclaration · Source: packages/narrator/src/narrator.ts:24 · Supporting declarations

export interface TemplateCtx {
    row: NamedRow;
    old?: NamedRow;
    /** The parent row, for an aggregate/nested change (e.g. the `ticket_type` behind a `sold` count). */
    parent?: NamedRow;
    /** Resolve a named sub-row of the change (only populated on `add`). */
    sub: (alias: string) => NamedRow | null;
    aggregate?: ResolvedChange["aggregate"];
    context: NarrateContext;
}