@ably/ai-transport 0.0.1 → 0.2.0

package/dist/core/transport/types/tree.d.ts

@@ -0,0 +1,315 @@
+import { CodecOutputEvent } from '../../codec/types.js';
+import { RunEndReason } from './shared.js';
+/** Conversation-tree types: nodes, the run-lifecycle event, output events, and the Tree contract. */
+import type * as Ably from 'ably';
+/**
+ * Fields common to every {@link RunLifecycleEvent} arm.
+ */
+interface RunLifecycleBase {
+    /** The run-id this lifecycle event concerns. */
+    runId: string;
+    /** The owning client's identity (Ably publisher `clientId`). */
+    clientId: string;
+    /**
+     * The invocation-id this lifecycle event was published under (wire
+     * `invocation-id`). Lets consumers correlate the run's lifecycle back to the
+     * invocation that drove it; on a run-start the Tree records it on the RunNode
+     * at first creation so an optimistic Run exposes the invocation synchronously.
+     * Empty string if the wire didn't carry an invocation-id.
+     */
+    invocationId: string;
+}
+/**
+ * A structured event describing a run starting, suspending, resuming, or
+ * ending. The `type` discriminator (`start` / `suspend` / `resume` / `end`) is
+ * the in-memory domain vocabulary and is intentionally distinct from the wire
+ * message names (`ai-run-start` / `ai-run-suspend` / `ai-run-resume` /
+ * `ai-run-end`) those events are decoded from.
+ */
+export type RunLifecycleEvent = (RunLifecycleBase & {
+    type: 'start';
+    /**
+     * Ably channel serial of the run-start message, or `undefined` for an
+     * optimistic local event (no serial assigned yet). The Tree reads it to
+     * promote the Run's startSerial.
+     */
+    serial: string | undefined;
+    /** The codec-message-id of the parent message, if known. Omitted for root runs. */
+    parent?: string;
+    /**
+     * The codec-message-id of the user prompt being forked, when the run is an
+     * edit. Carried verbatim from the `fork-of` wire header.
+     */
+    forkOf?: string;
+    /**
+     * The codec-message-id of the assistant message this run regenerates, when
+     * the run is a regenerate continuation. Carried verbatim from the
+     * `msg-regenerate` wire header. The Tree treats regenerates
+     * as continuations (no `forkOf` at the Run level) — the View
+     * realises the replacement when materialising messages.
+     */
+    regenerates?: string;
+}) | (RunLifecycleBase & {
+    type: 'suspend';
+    /**
+     * Ably channel serial of the run-suspend message, or `undefined` for an
+     * optimistic local event. The Tree reads it to set the Run's endSerial
+     * (a suspended run carries the serial at which it paused).
+     */
+    serial: string | undefined;
+}) | (RunLifecycleBase & {
+    type: 'resume';
+    /**
+     * Ably channel serial of the run-resume message, or `undefined` for an
+     * optimistic local event. A resume re-enters an existing run; it does not
+     * promote the Run's startSerial (the original run-start owns that).
+     */
+    serial: string | undefined;
+}) | (RunLifecycleBase & {
+    type: 'end';
+    /**
+     * Ably channel serial of the run-end message, or `undefined` for an
+     * optimistic local event. The Tree reads it to set the Run's endSerial.
+     */
+    serial: string | undefined;
+    /**
+     * Why the run ended — the terminal reason the Tree records as the
+     * RunNode's status: `complete`, `cancelled`, or `error`.
+     */
+    reason: RunEndReason;
+});
+/** A node in the conversation tree, representing a single domain message. */
+export interface MessageNode<TMessage> {
+    /** Discriminator — identifies this as a message node. */
+    kind: 'message';
+    /** The domain message. */
+    message: TMessage;
+    /** The codec-message-id of this node — primary key in the tree. */
+    codecMessageId: string;
+    /** Parent node's codec-message-id (parent), or undefined for root messages. */
+    parentId: string | undefined;
+    /** The codec-message-id this node forks from (fork-of), or undefined if first version. */
+    forkOf: string | undefined;
+    /** The transport-tier headers (`extras.ai.transport`) for this message: the run/stream/identity/branching headers set and read by the transport layer. Codec-tier headers (`extras.ai.codec`) are not included. */
+    headers: Record<string, string>;
+    /**
+     * Ably serial for this message. Lexicographically comparable for total order.
+     * Used to sort siblings deterministically regardless of delivery/history order.
+     * Absent for optimistic messages (set when the server relay arrives).
+     */
+    serial: string | undefined;
+}
+/**
+ * A node in the conversation tree, representing a single Run.
+ *
+ * A RunNode is keyed by its agent-minted `runId`. Each RunNode owns a per-Run
+ * codec {@link TProjection} folded from every event published under that
+ * run-id; the SDK extracts the per-message list via {@link Codec.getMessages}
+ * when it needs to render messages for that Run.
+ *
+ * A regenerate is a sibling reply run: it shares its input-node parent
+ * ({@link parentCodecMessageId}) with the original reply, so same-parent reply
+ * runs form the regenerate group with no `forkOf` involved. (Editing a prompt
+ * instead produces a sibling {@link InputNode} via that node's `forkOf`.)
+ */
+export interface RunNode<TProjection> {
+    /** Discriminator — identifies this as a reply-run node within {@link ConversationNode}. */
+    kind: 'run';
+    /** The run-id of this Run — primary key in the tree. */
+    runId: string;
+    /**
+     * The codec-message-id this Run is rooted at — the `parent` header of the
+     * first observed message (or the run-start lifecycle event's `parent`
+     * field). This is the run's input node's codec-message-id: the user prompt
+     * the agent replied to. The Tree uses it for kind-blind reachability and to
+     * build the input→reply edge. `undefined` for the root Run.
+     */
+    parentCodecMessageId: string | undefined;
+    /**
+     * The node key of the node this Run replaces, or `undefined` if this Run is
+     * not a fork. Populated when the wire's `fork-of` header points at a
+     * codec-message-id that has been observed; the Tree resolves it through the
+     * codec-message-id → node-key index. Reply-run regenerate siblings do not
+     * use this (they group by shared parent) — it carries an explicit fork link
+     * when the wire stamps one.
+     */
+    forkOf: string | undefined;
+    /**
+     * The codec-message-id this Run regenerates, or `undefined` for non-regenerate
+     * Runs. Populated from the wire's `msg-regenerate` header (and the lifecycle
+     * event's `regenerates` field) verbatim — the Tree does not resolve it to a
+     * node key because the anchor is a message position, not a node.
+     *
+     * A regenerate run parents at the SAME input node as the reply it
+     * regenerates, so it joins that input's reply runs as a same-parent sibling;
+     * the message named by `regeneratesCodecMessageId` is replaced by this Run's
+     * content when the View materialises the chain into messages (Spec: AIT-CT13d).
+     */
+    regeneratesCodecMessageId: string | undefined;
+    /**
+     * Identity of the Ably client that started this Run, sourced from the
+     * `run-client-id` wire header (or the run-start lifecycle event's
+     * `clientId` field). Set once at Run creation and never updated; persists
+     * through the Run's lifecycle, including after `run-end`. Empty string if
+     * the wire didn't carry a client id.
+     */
+    clientId: string;
+    /**
+     * Run lifecycle status.
+     * - `'active'` — run-start observed, no terminal event yet.
+     * - `'suspended'` — run-suspend observed; the run is paused awaiting input
+     *   and stays live (a continuation re-activates it). Not terminal.
+     * - {@link RunEndReason} — terminal state reflecting the run-end reason.
+     */
+    status: 'active' | 'suspended' | RunEndReason;
+    /** Per-Run codec projection. Folded by the Tree from every event published under this run-id. */
+    projection: TProjection;
+    /**
+     * The agent-minted invocationId observed for this Run (wire `invocation-id`).
+     * The agent mints it, so an optimistic Run starts with an empty id; it is
+     * adopted from the agent's `ai-run-start` (or set at creation when the Run is
+     * first seen from a wire event carrying one) and never reassigned thereafter.
+     * Empty string until run-start arrives, or if the wire didn't carry an
+     * invocation-id.
+     */
+    invocationId: string;
+    /** Ably serial of the first observed message tagged with this run-id. Absent for optimistic Runs. */
+    startSerial: string | undefined;
+    /** Ably serial of the run-end lifecycle event, if observed. */
+    endSerial: string | undefined;
+}
+/**
+ * A node in the conversation tree, representing a single user input (prompt).
+ *
+ * An input node owns the user's prompt for one turn. It is keyed by the
+ * client-owned `codec-message-id` and never carries a run-id — the agent mints
+ * the run-id for the reply, which becomes a separate {@link RunNode} parented to
+ * this input node. An edit of a prompt is a sibling input node (via `forkOf`).
+ *
+ * Like a {@link RunNode}, it carries its own per-input codec {@link TProjection}
+ * folded from the input event(s) published under its codec-message-id; the SDK
+ * extracts the per-message list via {@link Codec.getMessages} when rendering.
+ */
+export interface InputNode<TProjection> {
+    /** Discriminator — identifies this as an input node within {@link ConversationNode}. */
+    kind: 'input';
+    /** The codec-message-id of this input — primary key in the tree. */
+    codecMessageId: string;
+    /**
+     * The codec-message-id of the node this input hangs off (its structural
+     * parent — the immediately preceding reply run on this chain), or `undefined`
+     * for the first input in a conversation. Used for kind-blind tree
+     * reachability alongside {@link RunNode.parentCodecMessageId}.
+     */
+    parentCodecMessageId: string | undefined;
+    /**
+     * The codec-message-id this input forks from when it is an edit of an earlier
+     * prompt, or `undefined` if it is the first version. Sibling input nodes
+     * (alternate prompts) share the same `forkOf` anchor.
+     */
+    forkOf: string | undefined;
+    /** Per-input codec projection. Folded by the Tree from every input event published under this codec-message-id. */
+    projection: TProjection;
+    /** Ably serial of the first observed message for this input. Absent for optimistic (locally-created) inputs. */
+    serial: string | undefined;
+}
+/**
+ * A node in the conversation tree: either a user {@link InputNode} or an agent
+ * {@link RunNode}. Narrow on `kind` (`'input'` vs `'run'`) before reading
+ * kind-specific fields.
+ */
+export type ConversationNode<TProjection> = InputNode<TProjection> | RunNode<TProjection>;
+/**
+ * Payload of the Tree's `output` event: the decoded agent outputs folded
+ * for a Run from a single inbound message, carrying the routing metadata a
+ * consumer needs to attribute or stream them.
+ */
+export interface OutputEvent<TOutput extends CodecOutputEvent> {
+    /**
+     * The runId the outputs were folded into, or `undefined` when the fold was
+     * into a user input node (which carries no run-id — the agent mints run-ids).
+     * An input fold always has empty {@link events}; consumers route by
+     * {@link inputCodecMessageId}, not this.
+     */
+    runId: string | undefined;
+    /**
+     * The codec-message-id of the input event that triggered this run — the
+     * agent's `input-codec-message-id` header. This is the stable key the client
+     * owns from send time (before the agent mints the runId), so the output
+     * stream can attribute outputs to the request that produced them. Distinct
+     * from {@link runId}: causal (which input produced these outputs) rather than
+     * the run's own identity. `undefined` when the carrying message had no such
+     * header — e.g. a purely-optimistic local fold with no wire echo yet.
+     */
+    inputCodecMessageId: string | undefined;
+    /**
+     * The `codec-message-id` the outputs were published under, or `undefined`
+     * when the message carried none.
+     */
+    codecMessageId: string | undefined;
+    /**
+     * Ably channel serial of the message that carried the outputs, or
+     * `undefined` for an optimistic local fold (no serial assigned yet).
+     */
+    serial: string | undefined;
+    /**
+     * The decoded agent outputs from this message, in wire order. Empty when
+     * the folded message carried only inputs (e.g. an optimistic user
+     * message); the event still fires so consumers can observe that the Run's
+     * projection changed.
+     */
+    events: TOutput[];
+}
+/**
+ * Materializes a branching conversation tree from a flat oplog of Ably
+ * messages. Each turn is two nodes: a user {@link InputNode} keyed by its
+ * client-owned codec-message-id and an agent {@link RunNode} keyed by the
+ * agent-minted run-id, parented to the input node.
+ *
+ * The Tree owns the complete conversation state across every observed node.
+ * Each node holds a per-node codec {@link TProjection} which the Tree folds
+ * from inbound events. The View walks the parent chain to extract a flat
+ * message list for rendering.
+ */
+export interface Tree<TOutput extends CodecOutputEvent, TProjection> {
+    /** Get a Run by runId, or undefined if not found. */
+    getRunNode(runId: string): RunNode<TProjection> | undefined;
+    /**
+     * Get the node that owns a given codec-message-id (via the Tree's
+     * codecMessageId index), or undefined if the codec-message-id hasn't been
+     * observed. The result is a {@link ConversationNode} union: narrow on `kind`
+     * (`'input'` vs `'run'`) before reading kind-specific fields.
+     */
+    getNodeByCodecMessageId(codecMessageId: string): ConversationNode<TProjection> | undefined;
+    /**
+     * Get the sibling group (both kinds) the node keyed by `key` belongs to:
+     * edit versions for an input node (forkOf-linked, same parent), regenerate
+     * runs for a reply run (same input-node parent). Ordered oldest-first by
+     * serial; a single-element array when the node has no siblings. Empty when
+     * `key` is unknown. Narrow each node on `kind` before reading kind-specific
+     * fields.
+     * @param key - The node key ({@link RunNode.runId} or {@link InputNode.codecMessageId}).
+     * @returns The ordered sibling nodes.
+     */
+    getSiblingNodes(key: string): ConversationNode<TProjection>[];
+    /**
+     * Subscribe to tree structural changes (Run insert, delete, sort-reorder,
+     * startSerial promotion, run-start metadata backfill). Does NOT fire on
+     * content-only folds (streaming chunks) or on run-end status changes —
+     * those flow through `output` and `run` respectively.
+     */
+    on(event: 'update', handler: () => void): () => void;
+    /** Subscribe to raw Ably messages arriving on the channel. */
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    /** Subscribe to run lifecycle events (start, suspend, resume, and end). */
+    on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
+    /**
+     * Subscribe to decoded agent outputs as they are folded into a Run.
+     * Fires once per inbound message after its fold, carrying the message's
+     * output events plus routing metadata (runId, codec-message-id, serial).
+     * Fires with an empty `events` array for inputs-only folds so it can also
+     * serve as a projection-changed signal.
+     */
+    on(event: 'output', handler: (event: OutputEvent<TOutput>) => void): () => void;
+}
+export {};

package/dist/core/transport/types/view.d.ts

@@ -0,0 +1,222 @@
+import { CodecInputEvent, CodecMessage } from '../../codec/types.js';
+import { ActiveRun, SendOptions } from './client.js';
+import { RunEndReason } from './shared.js';
+import { RunLifecycleEvent } from './tree.js';
+/** View types: history pagination, branch selection, run info, and the windowed View contract. */
+import type * as Ably from 'ably';
+/** A page of raw history wires from the channel. Internal to View/decodeHistory. */
+export interface HistoryPage {
+    /** Raw Ably messages that produced this page, in chronological order (oldest first). */
+    rawMessages: Ably.InboundMessage[];
+    /** Whether there are older pages available. */
+    hasNext(): boolean;
+    /** Fetch the next (older) page. Returns undefined if no more pages. */
+    next(): Promise<HistoryPage | undefined>;
+}
+/** Options for loading channel history. */
+export interface LoadHistoryOptions {
+    /** Max messages per page. Default: 100. */
+    limit?: number;
+}
+/**
+ * Projection-free, View-facing snapshot of a Run.
+ *
+ * Exposes the Run facts a UI consumer needs (`runId`, owner `clientId`,
+ * lifecycle `status`, `invocationId`) without leaking the codec's
+ * opaque per-Run projection or the Tree's structural fields. Callers
+ * that need the full Run record (parent / fork relationships, serials,
+ * projection) reach `session.tree.getRunNode(runId)` directly.
+ */
+export interface RunInfo {
+    /** The Run's unique identifier. */
+    runId: string;
+    /**
+     * Identity of the Ably client that started this Run. Empty string
+     * when the wire didn't carry an owner client id.
+     */
+    clientId: string;
+    /**
+     * Run lifecycle status. `'active'` while the Run is streaming;
+     * `'suspended'` while it is paused awaiting input (still live, a
+     * continuation re-activates it); otherwise the {@link RunEndReason} the Run
+     * terminated with. Literal lifecycle vocabulary — UIs that want `'streaming'`
+     * rendering language translate at the component boundary.
+     */
+    status: 'active' | 'suspended' | RunEndReason;
+    /**
+     * The agent-minted `invocationId` observed for this Run, adopted from the
+     * wire `ai-run-start`. Stable across the Run's lifecycle once observed.
+     * Empty string until run-start arrives (the agent mints it, so an
+     * optimistic Run carries none) or when the wire didn't carry an
+     * invocation-id.
+     */
+    invocationId: string;
+}
+/**
+ * Bundle returned by {@link View.branchSelection} describing the
+ * sibling group anchored at a given codec-message-id.
+ *
+ * Total / always-defined — `view.branchSelection(id)` is safe to call
+ * for any message:
+ *
+ *  - **Branch anchor (N ≥ 2 siblings)**: `siblings` carries every
+ *    sibling Run's view of the anchor slot, `index` is the selected
+ *    sibling's position, `selected === siblings[index]`,
+ *    `hasSiblings: true`.
+ *  - **Known non-anchor message**: `siblings = [thisMessage]`,
+ *    `index: 0`, `selected: thisMessage`, `hasSiblings: false`.
+ *  - **Unknown codec-message-id**: `siblings: []`, `index: 0`,
+ *    `selected: undefined`, `hasSiblings: false`.
+ *
+ * Because `siblings` always contains the currently rendered message
+ * (for known ids), `siblings.length` is `1` for a plain bubble (not
+ * `0`) and the indexing space matches between read and write —
+ * passing `branch.index` back into {@link View.selectSibling} is a
+ * round-trip no-op.
+ */
+export interface BranchSelection<TMessage> {
+    /** True when the codec-message-id is a branch anchor with more than one sibling. Equivalent to `siblings.length > 1`. */
+    hasSiblings: boolean;
+    /**
+     * The selected sibling and any alternatives, in tree-order (oldest
+     * first). Always contains the currently rendered message itself for
+     * known codec-message-ids; empty only when the id is unknown to the
+     * view.
+     */
+    siblings: TMessage[];
+    /** Index of the selected sibling within `siblings`. `0` when there is no real branching or the id is unknown. */
+    index: number;
+    /** Convenience reference to `siblings[index]`. `undefined` only when `siblings` is empty. */
+    selected: TMessage | undefined;
+}
+/**
+ * A paginated, branch-aware projection of the conversation tree.
+ *
+ * Returns only the visible portion of the selected branch. New live messages
+ * appear immediately; older messages are revealed progressively via
+ * `loadOlder()`. Events are scoped to the visible window — subscribers
+ * are only notified when the visible output changes.
+ */
+export interface View<TInput extends CodecInputEvent, TMessage> {
+    /**
+     * The visible messages along the selected branch, each paired with its
+     * codec-message-id (see {@link CodecMessage}). Computed by walking the
+     * visible Run chain (newest to root) and concatenating each Run's
+     * `codec.getMessages(projection)` in chronological order.
+     *
+     * Correlate a message back to the transport — routing a continuation
+     * input, resolving a regenerate/edit target, looking up the owning Run —
+     * via its `codecMessageId`, which the SDK assigns and tracks
+     * independently of any identity the domain `message` may carry. Read the
+     * domain object from each entry's `message` field.
+     */
+    getMessages(): CodecMessage<TMessage>[];
+    /**
+     * Snapshot of the visible Runs along the selected branch, in
+     * chronological order — already filtered by this view's pagination
+     * window, branch selection, and regenerate substitution. The
+     * companion to {@link getMessages}: same scope, exposed as
+     * projection-free {@link RunInfo} so consumers can iterate Run
+     * identity (runId, clientId, status, invocationId) without touching
+     * the Tree.
+     */
+    runs(): RunInfo[];
+    /** Whether there are older Runs that can be loaded or revealed. */
+    hasOlder(): boolean;
+    /**
+     * Reveal older Runs. Loads from channel history if the tree doesn't have
+     * enough, then advances the pagination window by up to `limit` Runs.
+     * Emits 'update' when the visible list changes.
+     *
+     * The pagination unit is the **Run**, not the message. A single Run
+     * typically contributes more than one message to the flat list returned
+     * by {@link View.getMessages} (e.g. a user prompt + assistant reply
+     * pair). Revealing `limit` Runs may add 1..N messages each to the
+     * visible window.
+     * @param limit - Maximum number of older Runs to reveal. Defaults to 100.
+     */
+    loadOlder(limit?: number): Promise<void>;
+    /**
+     * Look up the {@link RunInfo} for the Run that owns `codecMessageId`.
+     * For a user input node's codec-message-id, resolves to its
+     * currently-selected reply run. Returns `undefined` when the
+     * codec-message-id hasn't been observed by the view, or when it names
+     * an input node that has no reply run yet.
+     * @param codecMessageId - The codec-message-id to look up.
+     */
+    runOf(codecMessageId: string): RunInfo | undefined;
+    /**
+     * Direct lookup by Run id. Kept for symmetry with {@link runOf} so
+     * callers that hold a `runId` (e.g. cancel handlers) get a one-step
+     * lookup. Returns `undefined` when the Run hasn't been observed.
+     * @param runId - The Run id to look up.
+     */
+    run(runId: string): RunInfo | undefined;
+    /**
+     * Resolve the {@link BranchSelection} bundle anchored at
+     * `codecMessageId`. Always returns a safe object — see
+     * {@link BranchSelection} for the per-case shape.
+     *
+     * Per AITRFC-014, branch points are message-anchored: edit forks
+     * point at the user prompt's codec-message-id, regenerate forks
+     * point at the assistant message's codec-message-id.
+     * @param codecMessageId - The codec-message-id of the bubble being rendered.
+     */
+    branchSelection(codecMessageId: string): BranchSelection<TMessage>;
+    /**
+     * Select a sibling at the branch point anchored at
+     * `codecMessageId`. `index` is clamped to
+     * `[0, siblings.length - 1]`. Silent no-op when `codecMessageId`
+     * is not a branch anchor. Emits 'update' when the visible output
+     * changes.
+     * @param codecMessageId - The codec-message-id of the bubble being rendered.
+     * @param index - The index of the sibling to select.
+     */
+    selectSibling(codecMessageId: string, index: number): void;
+    /**
+     * Send one or more TInputs on the channel and fire a POST. Each TInput
+     * carries its own routing metadata (`parent` / `target` / `codecMessageId`)
+     * via the {@link CodecInputEvent} base; the SDK reads those fields
+     * directly without runtime classification.
+     *
+     * To send a fresh user message, wrap the domain message with
+     * {@link Codec.createUserMessage} and pass the result here, e.g.
+     * `view.send(codec.createUserMessage(message))`.
+     *
+     * Convention: a send containing at least one `UserMessage` is a
+     * fresh send (mints a new `runId`). A send containing only
+     * tool-resolution inputs is a continuation — pair with
+     * `options.runId` to extend a suspended run.
+     *
+     * The parent is auto-computed from this view's selected branch unless
+     * overridden. The HTTP POST is fire-and-forget — the returned stream is
+     * available immediately. If the POST fails, the error is surfaced via
+     * the session's `on("error")` and the stream is errored.
+     */
+    send(events: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+    /**
+     * Regenerate an assistant message. Mints a codec `Regenerate` input
+     * carrying `target` (the assistant codec-message-id being regenerated)
+     * and `parent` (the preceding user prompt's codec-message-id), both
+     * auto-computed from this view's branch — there are no new user inputs.
+     * The new reply run is not a `forkOf` fork; it continues the
+     * regenerated message's run, and the message-level replacement (the new
+     * assistant superseding the original) happens at projection-extraction
+     * time.
+     */
+    regenerate(messageId: string, options?: SendOptions): Promise<ActiveRun>;
+    /**
+     * Edit a user message. Creates a new run that forks the target message
+     * with replacement content. Automatically computes `forkOf` (the edited
+     * message) and `parent` from this view's branch.
+     */
+    edit(messageId: string, inputs: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+    /** The visible message list changed (new visible node, branch switch, window shift). */
+    on(event: 'update', handler: () => void): () => void;
+    /** A raw Ably message arrived that corresponds to a visible node. */
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    /** A run event occurred for a run with visible messages in the window. */
+    on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
+    /** Tear down the view — unsubscribe from tree events and clear internal state. */
+    close(): void;
+}