@ably/ai-transport 0.1.0 → 0.3.0

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

@@ -1,161 +1,466 @@
 import { Logger } from '../../logger.js';
-import { Codec } from '../codec/types.js';
+import { Codec, CodecInputEvent, CodecMessage, CodecOutputEvent } from '../codec/types.js';
+import { WireApplier } from './decode-fold.js';
 import { TreeInternal } from './tree.js';
-import { ActiveTurn, EventsNode, MessageNode, SendOptions, TurnLifecycleEvent, View } from './types.js';
+import { ActiveRun, BranchSelection, RunInfo, RunLifecycleEvent, SendOptions, View } from './types.js';
 /**
  * DefaultView — a paginated, branch-aware projection over the Tree.
  *
- * Wraps a Tree and manages a pagination window that controls which nodes
- * are visible to the UI. New live messages appear immediately; older messages
- * are revealed progressively via `loadOlder()`.
+ * Wraps a Tree (RunNode-keyed) and manages a pagination window that controls
+ * which Runs are visible to the UI. New live Runs appear immediately; older
+ * Runs are revealed progressively via `loadOlder()`.
+ *
+ * `getMessages()` reads the Tree's visible node chain (input nodes + reply
+ * runs, with sibling selection applied) and concatenates each node's
+ * `codec.getMessages(node.projection)` to produce the flat
+ * `CodecMessage<TMessage>[]` the UI renders.
  *
  * Each View owns its own branch selection state and pagination window,
  * allowing multiple independent Views over the same Tree.
  *
  * Events are scoped to the visible window — 'update' only fires when the
  * visible output changes, 'ably-message' only for messages corresponding to
- * visible nodes, and 'turn' only for turns with visible messages.
+ * visible Runs, and 'run' only for runs with visible content.
  */
 import * as Ably from 'ably';
 /**
- * Internal delegate function provided by the transport for executing sends.
- * The View pre-computes the visible branch history and passes it directly,
- * so the delegate has no back-reference to the View.
- * When `eventNodes` is provided, the transport includes them in the POST body
- * for the server to publish as cross-turn events.
+ * Internal delegate function provided by the session for executing sends.
+ * The View pre-computes the visible branch's flat message list and the
+ * codec-message-id of its tail (for auto-parent routing) before calling
+ * the delegate, so the delegate has no back-reference to the View.
+ *
+ * Each TInput carries its own routing metadata (`parent` / `target` /
+ * `codecMessageId`) via the {@link CodecInputEvent} base; the delegate
+ * reads those fields directly without runtime classification.
+ *
+ * `parentCodecMessageId` is the codec-message-id of the last message in
+ * the visible branch (extracted from the tail Run's projection per codec
+ * convention), or `undefined` for an empty conversation. The session
+ * uses it as the auto-parent for fresh user messages.
  */
-export type SendDelegate<TEvent, TMessage> = (input: TMessage | TMessage[], options: SendOptions | undefined, history: MessageNode<TMessage>[], eventNodes?: EventsNode<TEvent>[]) => Promise<ActiveTurn<TEvent>>;
+export type SendDelegate<TInput extends CodecInputEvent> = (input: TInput[], options: SendOptions | undefined, parentCodecMessageId: string | undefined) => Promise<ActiveRun>;
 /** Options for creating a View. */
-export interface ViewOptions<TEvent, TMessage> {
+interface ViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
     /** The tree to project. */
-    tree: TreeInternal<TMessage>;
+    tree: TreeInternal<TInput, TOutput, TProjection>;
     /** The Ably channel to load history from. */
     channel: Ably.RealtimeChannel;
-    /** The codec for decoding history messages. */
-    codec: Codec<TEvent, TMessage>;
-    /** Delegate for executing sends through the transport. */
-    sendDelegate: SendDelegate<TEvent, TMessage>;
+    /** The codec used to project messages and mint regenerate inputs. */
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /**
+     * The Tree's single decode-and-apply engine, owned by the session and
+     * shared with the live decode loop. History replay feeds pages through it
+     * so the one decoder instance sees every route into the Tree.
+     */
+    applier: WireApplier;
+    /** Delegate for executing sends through the session. */
+    sendDelegate: SendDelegate<TInput>;
     /** Logger for diagnostic output. */
     logger: Logger;
     /** Called when the view is closed, allowing the owner to clean up references. */
     onClose?: () => void;
 }
-export declare class DefaultView<TEvent, TMessage> implements View<TEvent, TMessage> {
+export declare class DefaultView<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> implements View<TInput, TMessage> {
     private readonly _tree;
     private readonly _channel;
     private readonly _codec;
+    private readonly _applier;
     private readonly _sendDelegate;
     private readonly _logger;
     private readonly _emitter;
     private readonly _onClose?;
     /**
-     * View-local branch selections: group root msgId → selection intent.
+     * View-local branch selections: group-root runId → selection intent.
      * Fork points not present here default to the latest sibling.
-     * Replaces the previous numeric-index _selections and _pendingForkSelections
-     * with a single tagged-union map that carries the selected msgId (not index)
-     * and the reason for the selection.
      */
     private readonly _branchSelections;
-    /** Spec: AIT-CT11c — msg-ids loaded from history but not yet revealed to the UI. */
-    private readonly _withheldMsgIds;
-    /** Snapshot of visible msgIds — used to detect structural changes and for selection pinning. */
-    private _lastVisibleIds;
-    /** Snapshot of visible message references — used to detect in-place content updates (streaming). */
-    private _lastVisibleMessages;
-    /** Cached set of turn IDs present on the visible branch — avoids recomputing flattenNodes() on turn events. */
-    private _lastVisibleTurnIds;
+    /**
+     * View-local regenerate-group selections: anchor codec-message-id (the assistant
+     * codec-message-id being regenerated) → selection intent. Distinct from
+     * {@link _branchSelections} because a regenerate group is a set of
+     * same-parent reply runs — message-level alternatives at a single
+     * conversation slot, not edit forks of the prompt. Groups not present here default to the latest
+     * member (the most recent regenerator, or the original if no regen has
+     * landed).
+     */
+    private readonly _regenSelections;
+    /**
+     * Non-head regenerate selections, keyed by the regenerate target's
+     * codec-message-id. Separate from {@link _regenSelections} because a non-head
+     * regenerator parents inside the owner run rather than as a same-parent
+     * sibling, so it lives outside the Tree's `visibleNodes` selection space and
+     * is resolved at extraction (see `_extractMessages`). Value is the selected
+     * member's nodeKey (the owner run id, or a regenerator run id); absent groups
+     * default to the newest regenerator.
+     */
+    private readonly _nonHeadRegenSelections;
+    /** Spec: AIT-CT11c — runIds loaded from history but not yet revealed to the UI. */
+    private readonly _withheldRunIds;
+    /** Snapshot of visible node keys — used to detect structural changes and for selection pinning. */
+    private _lastVisibleNodeKeys;
+    /**
+     * Snapshot of visible projection references — used to detect in-place
+     * projection updates (streaming). One entry per visible Run.
+     */
+    private _lastVisibleProjections;
+    /**
+     * Snapshot of the visible flat message chain with codec-message-ids —
+     * exposed verbatim via `getMessages()` and the internal correlation
+     * source for parent/branch routing.
+     */
+    private _lastVisibleMessagePairs;
+    /** Cached visible node-key Set — for O(1) lookup in event scoping. */
+    private _lastVisibleNodeKeySet;
     /** Whether there are more history pages to fetch from the channel. */
     private _hasMoreHistory;
     /** Internal state for continuing history pagination. */
     private _lastHistoryPage;
-    /** Buffer of withheld nodes, drained newest-first by successive loadOlder() calls. */
+    /** Buffer of withheld nodes (input + reply), drained newest-first by successive loadOlder() calls. */
     private readonly _withheldBuffer;
+    /**
+     * Message-level trim on top of the run-level pagination window. Runs are
+     * revealed whole (via `_withheldRunIds`/`_withheldBuffer`), so a `loadOlder`
+     * may surface more messages than asked; this is the count of OLDEST messages
+     * of the visible node chain to hide from `getMessages()` so a page lands on
+     * exactly `limit` messages. The boundary run still appears in `runs()` (it's
+     * a revealed node); only its oldest messages are trimmed from the flat list.
+     * Live messages append at the newest end and are never trimmed.
+     */
+    private _hiddenMessageCount;
     /** Unsubscribe functions for tree event subscriptions. */
     private readonly _unsubs;
     /**
-     * Cached result of the last flattenNodes computation. Public `flattenNodes()`
-     * returns this in O(1); internal callers use `_computeFlatNodes()` when a
-     * fresh tree walk is needed (structural changes, selection changes, history reveal).
+     * Cached result of the last flat-nodes computation. Drives the visible
+     * message snapshot exposed via `getMessages()`; refreshed by
+     * `_computeFlatNodes()` on structural changes, selection changes,
+     * and history reveal.
      */
     private _cachedNodes;
-    /** Last seen tree structural version - used to distinguish content-only from structural updates. */
-    private _lastStructuralVersion;
     private _loadingOlder;
     private _processingHistory;
     private _closed;
-    constructor(options: ViewOptions<TEvent, TMessage>);
-    getMessages(): TMessage[];
-    flattenNodes(): MessageNode<TMessage>[];
+    constructor(options: ViewOptions<TInput, TOutput, TProjection, TMessage>);
+    /**
+     * Handle decoded outputs folded into a Run (streaming delta). If the run
+     * is on the visible chain, recompute the flat message list and emit
+     * `update`.
+     * @param event - The output event from the Tree.
+     */
+    private _onTreeOutput;
+    getMessages(): CodecMessage<TMessage>[];
+    runs(): RunInfo[];
     /**
-     * Walk the tree and compute a fresh visible node list, applying branch
-     * selections and withheld-message filtering. Use this instead of the
-     * public `flattenNodes()` when the cache may be stale (structural
-     * changes, selection changes, history reveal).
-     * @returns A fresh array of visible nodes.
+     * Compute the fresh visible node chain. The Tree's `visibleNodes` already
+     * applies kind-blind reachability and sibling selection (edit versions /
+     * regenerate runs collapse to the selected member), so the View only layers
+     * its pagination window on top: drop nodes whose key is currently withheld.
+     * @returns A fresh array of visible nodes (inputs + reply runs).
      */
     private _computeFlatNodes;
+    /**
+     * Recompute the visible node chain, refresh the cache + snapshot, and emit
+     * `update` unconditionally. Use after a mutation that always changes the
+     * visible output (e.g. an explicit selection or a withheld-batch reveal).
+     */
+    private _recomputeAndEmit;
+    /**
+     * Recompute the visible node chain and, only if it differs from the current
+     * snapshot, refresh the cache + snapshot and emit `update`. Use after a
+     * mutation that may or may not move the visible window (e.g. a structural
+     * tree update, or a deferred regenerate promotion that may already match).
+     */
+    private _recomputeAndEmitIfChanged;
+    /**
+     * Resolve the reply Run that owns a codec-message-id, narrowing the Tree's
+     * node union to a {@link RunNode}. A user-input codec-message-id resolves to
+     * an input node and yields `undefined` here — callers that must handle input
+     * nodes use {@link _tree.getNodeByCodecMessageId} directly.
+     * @param codecMessageId - The codec-message-id to resolve.
+     * @returns The owning RunNode, or undefined if absent or not a reply Run.
+     */
+    private _runByCodecMessageId;
+    /**
+     * The regenerator runs that replaced a non-head message of a reply run. They
+     * file under the target's predecessor (not the owner run's input node), so the
+     * Tree's `visibleNodes` cannot collapse them into the owner's slot; this
+     * surfaces them for the View to resolve and render. Head-message (index 0)
+     * regenerates are excluded - those are whole-reply sibling runs the Tree
+     * already groups.
+     * @param targetCodecMessageId - The regenerate target's (non-head) message id.
+     * @param predecessorCodecMessageId - The codec-message-id immediately before it in the owner run.
+     * @returns The regenerator runs in startSerial order (oldest first).
+     */
+    private _nonHeadRegenerators;
+    /**
+     * Resolve the selected member of a non-head regenerate group anchored at
+     * `targetCodecMessageId`. Members are the owner run `O` (memberNodeKey =
+     * `ownerRunId`, the regenerate target in place) followed by each regenerator
+     * run. Honours an explicit {@link _nonHeadRegenSelections} entry, else
+     * defaults to the latest member (newest regenerator), mirroring the
+     * whole-reply regenerate default.
+     * @param targetCodecMessageId - The regenerate target's message id (the group anchor).
+     * @param ownerRunId - The runId of the run that owns the regenerate target.
+     * @param regenerators - The regenerator runs (oldest first) from `_nonHeadRegenerators`.
+     * @returns The selected member's node key (`ownerRunId` or a regenerator runId).
+     */
+    private _selectedNonHeadMember;
+    /**
+     * Flatten visible nodes to messages, collapsing a non-head regenerate into the
+     * slot it replaces: while emitting a reply run, at each non-head message that
+     * has a selected regenerator, drop that message and the run's tail and emit the
+     * selected regenerator instead (recursive for regen-of-regen). Whole-reply
+     * regenerates need nothing here - visibleNodes already picks the sibling.
+     * @param nodes - Visible nodes (inputs + reply runs), chronological.
+     * @returns The flat message list, each paired with its codec-message-id.
+     */
+    private _extractMessages;
+    /**
+     * Emit one visible node's messages into `out`, applying non-head regenerate
+     * substitution for a reply run (see `_extractMessages`). Input nodes and runs
+     * with no non-head regenerators emit their projection verbatim.
+     * @param node - The node to emit.
+     * @param out - The accumulating flat message list (mutated in place).
+     * @param consumedRunIds - Set of regenerator runIds already emitted via substitution (mutated in place).
+     */
+    private _emitNodeMessages;
     hasOlder(): boolean;
+    /**
+     * Reveal `limit` more older codecMessages in this view — fewer only when
+     * channel history is exhausted.
+     *
+     * Internally runs are revealed WHOLE (run-granular withholding), counting
+     * codecMessages to decide how many runs to bring in, then the flat list
+     * returned by {@link getMessages} is trimmed to exactly `limit` more
+     * messages. So a run straddling the boundary still appears in {@link runs}
+     * (it's a revealed node) while only its newest messages show in
+     * `getMessages`. Live messages append at the newest end and are never
+     * trimmed.
+     * @param limit - Number of older codecMessages to reveal. Defaults to 10.
+     */
     loadOlder(limit?: number): Promise<void>;
-    select(msgId: string, index: number): void;
-    getSelectedIndex(msgId: string): number;
-    getSiblings(msgId: string): TMessage[];
-    hasSiblings(msgId: string): boolean;
-    getNode(msgId: string): MessageNode<TMessage> | undefined;
-    send(input: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
-    regenerate(messageId: string, options?: SendOptions): Promise<ActiveTurn<TEvent>>;
-    edit(messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
-    update(msgId: string, events: TEvent[], options?: SendOptions): Promise<ActiveTurn<TEvent>>;
-    private _getHistoryBefore;
-    getActiveTurnIds(): Map<string, Set<string>>;
-    on(event: 'update', handler: () => void): () => void;
-    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
-    on(event: 'turn', handler: (event: TurnLifecycleEvent) => void): () => void;
     /**
-     * Tear down the view — unsubscribe from tree events.
+     * Fetch older channel history covering at least `target` more codecMessages,
+     * buffering the older nodes and revealing whole runs. The withheld buffer is
+     * assumed already drained by the caller. Loads the first page when no history
+     * has been fetched yet, otherwise advances to the next older page; the
+     * page-walk inside {@link _revealFromPage} loops until `target` messages are
+     * covered or history runs out. No-op (leaving `_hasMoreHistory` false) once
+     * channel history is exhausted.
+     * @param target - Minimum additional codecMessages this fetch aims to cover.
      */
+    private _fetchOlder;
+    /**
+     * Find the index in `nodes` (chronological, oldest-first) at which the newest
+     * whole runs covering at least `target` codecMessages begin. Walks newest-first
+     * summing each node's `codec.getMessages(projection)` count; once the running
+     * total reaches `target`, the current node (and everything newer) is the
+     * revealed batch — so whole runs are revealed and the batch may overshoot
+     * `target` (the caller trims). Returns `0` when the nodes hold fewer than
+     * `target` messages — reveal everything.
+     *
+     * Shared by the buffer-drain and history-fetch reveal paths so they agree on
+     * "covering `target` messages".
+     * @param nodes - Candidate nodes, oldest-first.
+     * @param target - Minimum codecMessages the revealed batch must cover.
+     * @returns The split index; `nodes[splitIdx..]` is the revealed batch.
+     */
+    private _messageTailSplitIndex;
+    runOf(codecMessageId: string): RunInfo | undefined;
+    /**
+     * Resolve the reply run currently selected for an input node, honouring the
+     * View's regenerate selection. Falls back to the latest reply run when no
+     * selection has been recorded; undefined when no reply run has started.
+     * @param inputCodecMessageId - The input node's codec-message-id.
+     * @returns The selected reply RunNode, or undefined.
+     */
+    private _selectedReplyRun;
+    run(runId: string): RunInfo | undefined;
+    branchSelection(codecMessageId: string): BranchSelection<TMessage>;
+    selectSibling(codecMessageId: string, index: number): void;
+    /**
+     * Resolve the currently selected sibling's index inside a branch group.
+     * Pending selections fall back to the latest sibling. The caller clamps
+     * the returned index against any post-extraction filtering.
+     * @param branch - Resolved branch-point descriptor from `_resolveMessageBranchPoint`.
+     * @returns The selected sibling's index within `branch.siblings`.
+     */
+    private _resolveSelectedIndex;
+    /**
+     * Resolve the branch point anchored at `codecMessageId`, if any, returning the
+     * group `kind` + members + groupRoot so the caller routes to the correct
+     * selection map directly (not via a runId dispatch that would mis-route when
+     * the owning Run is in both a fork-of and a regen group).
+     * @param codecMessageId - The codec-message-id to look up.
+     * @returns The resolved branch point, or undefined when `codecMessageId`
+     *   anchors no group.
+     */
+    private _resolveMessageBranchPoint;
+    /**
+     * Resolve a non-head regenerate branch point from a reply-run message, if any.
+     * `codecMessageId` is either (a) a non-head message `M` of its owner run with
+     * regenerators, or (b) a regenerator run's head; both resolve to the same group
+     * anchored at `M` (key matching {@link _nonHeadRegenSelections}).
+     * @param node - The reply run owning `codecMessageId`.
+     * @param ownMessages - That run's projected messages (already extracted).
+     * @param codecMessageId - The slot's codec-message-id (an `M`, or a regenerator head).
+     * @returns The non-head branch point, or undefined when `codecMessageId` anchors none.
+     */
+    private _resolveNonHeadBranchPoint;
+    /**
+     * Build the {@link MessageBranchPoint} for a non-head regenerate group, or
+     * undefined when the anchor has no regenerators. The owner member's
+     * representative is the anchor message (the regenerate target); each
+     * regenerator's is its head message.
+     * @param anchorCodecMessageId - The regenerate target's (non-head) message id.
+     * @param ownerRunId - The runId owning the regenerate target.
+     * @param predecessorCodecMessageId - The codec-message-id immediately before the anchor in the owner run.
+     * @returns The non-head branch point, or undefined when there are no regenerators.
+     */
+    private _buildNonHeadGroup;
+    /**
+     * Project nodes to {@link BranchMember}s for fork-of / whole-reply regen
+     * groups, where each member's branch-arrow representative is its own head
+     * message and its memberNodeKey is its node key.
+     * @param nodes - The sibling nodes.
+     * @returns One member per node that has a head message.
+     */
+    private _nodeHeadMembers;
+    send(input: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+    /**
+     * Auto-select / pin branch selections after a forking send.
+     * @param result - The ActiveRun returned by the delegate.
+     * @param options - The SendOptions passed by the caller.
+     */
+    private _applyForkAutoSelect;
+    /**
+     * Auto-select / pin the regenerate group anchored at `anchorCodecMessageId` so
+     * the new Run's content appears as soon as the agent's run-start lands.
+     *
+     * `View.regenerate()` calls this with the assistant codec-message-id being
+     * regenerated. The Run doesn't exist yet on the channel (the regenerate
+     * wire is wire-only); the selection is recorded as `pending` and
+     * promoted to `auto` by `_pinRegenSelections` once the corresponding
+     * Run is created in the tree.
+     * @param result - The ActiveRun returned by the delegate (run-id is the new regenerator's).
+     * @param anchorCodecMessageId - The codec-message-id of the assistant being regenerated.
+     */
+    private _applyRegenerateAutoSelect;
+    regenerate(messageId: string, options?: SendOptions): Promise<ActiveRun>;
+    edit(messageId: string, inputs: TInput | TInput[], options?: SendOptions): Promise<ActiveRun>;
+    /**
+     * Find the codec-message-id of the message immediately preceding `targetMsgId` in
+     * the visible conversation.
+     *
+     * Consults the View's visible message chain first so message-level
+     * replacements (regenerate) are respected: regenerating an
+     * already-regenerated assistant lands the predecessor on the user
+     * prompt the regen is responding to, NOT on the hidden original
+     * assistant that occupies the same conversation slot. Falls back to a
+     * projection-walk for the rare case where `targetMsgId` isn't on the
+     * visible chain (e.g. caller is operating on a Run that's selection-
+     * hidden by the current branch).
+     * @param targetNode - The node (input node or reply run) that owns `targetMsgId`.
+     * @param targetMsgId - The codec-message-id to find the parent of.
+     * @returns The parent codec-message-id, or undefined if no predecessor exists.
+     */
+    private _findParentMsgId;
+    on(event: 'update', handler: () => void): () => void;
+    on(event: 'ably-message', handler: (msg: Ably.InboundMessage) => void): () => void;
+    on(event: 'run', handler: (event: RunLifecycleEvent) => void): () => void;
     close(): void;
     private _loadFirstPage;
-    private _loadAndReveal;
+    /**
+     * Walk channel history from `page` until the newly-observed nodes hold at
+     * least `target` codecMessages (or the channel is exhausted), then reveal the
+     * newest whole runs covering `target` and withhold the rest. Snapshots the
+     * already-visible nodes up front so only newly-observed nodes count toward
+     * `target`. No-op if the view closed during the page walk.
+     * @param page - The decoded history page to start from.
+     * @param target - Minimum codecMessages to reveal in this batch.
+     */
+    private _revealFromPage;
+    /**
+     * Reveal the newest whole runs covering `target` codecMessages from
+     * `newVisible` and withhold the rest so subsequent `loadOlder` calls can
+     * drain them. Reveal granularity is the whole run; the caller trims the flat
+     * message list (via `_hiddenMessageCount`) to make the visible message count
+     * exact. Called by {@link _revealFromPage}.
+     * @param newVisible - Newly observed nodes (inputs + reply runs) from the history fetch, chronological.
+     * @param target - Minimum codecMessages the revealed batch must cover.
+     */
+    private _splitReveal;
+    /**
+     * Replay a history page's raw messages into the Tree through the Tree's
+     * single decode-and-apply engine — the same applier (and decoder instance)
+     * the client's live loop uses, so history replay can't drift from it. The
+     * shared decoder's version-guarded trackers make the overlap between the
+     * two routes safe: an in-flight stream that spans the attach boundary is
+     * continued rather than re-started, and content the live route already
+     * incorporated decodes to nothing.
+     * @param page - The history page returned by `loadHistory`.
+     */
     private _processHistoryPage;
     private _loadUntilVisible;
     private _releaseWithheld;
     private _updateVisibleSnapshot;
     private _onTreeUpdate;
     /**
-     * Build a resolved selections map from `_branchSelections` for passing
-     * to `tree.flattenNodes()`. Pending entries (no sibling yet) are omitted,
-     * causing the tree to use the default (latest sibling).
-     * @returns Resolved map of groupRoot → selectedMsgId.
+     * Build the unified selection map the Tree's `visibleNodes` consumes:
+     * `groupRootKey -> selectedKey`, covering both edit forks (input-node groups,
+     * keyed by the input group root) and regenerate groups (reply-run groups,
+     * keyed by the original reply's group root). Pending entries (no chosen
+     * member yet) are omitted so the Tree falls back to the latest sibling.
+     * @returns The merged group-root → selected-key map.
      */
     private _resolveSelections;
     /**
-     * For each previously-visible message that now has siblings but no
-     * explicit selection, pin the selection to that message's msgId.
-     * This preserves the current branch when new forks appear from
-     * other views or external sources.
+     * The Tree's visible node chain under this view's current selections — the
+     * reachable, sibling-resolved nodes before the View's pagination window is
+     * applied.
+     * @returns The selection-resolved visible node chain.
+     */
+    private _treeVisibleNodes;
+    /**
+     * For each previously-visible Run that now has siblings but no explicit
+     * selection, pin the selection to that Run's runId. This preserves the
+     * current branch when new forks appear from other views or external
+     * sources.
      *
      * Exception: if the fork was initiated by this view (tracked as a
-     * `pending` BranchSelection), select the newest sibling instead of
-     * pinning the old one. This handles regenerate, where no optimistic
-     * insert was possible at send time.
+     * `pending` BranchSelection), select the newest sibling (the awaited Run)
+     * instead of pinning the old one.
      */
     private _pinBranchSelections;
     /**
-     * Resolve pending selections that are no longer on the visible branch.
-     * `_pinBranchSelections` only checks visible nodes, so if the user navigated
-     * away before the server response arrived, the pending entry would linger.
-     * This pass checks all pending entries against the tree directly.
+     * Roll `pending` and `auto` regenerate selections forward to the newest
+     * group member. A regenerate slot defaults to the latest member, so each
+     * new regenerator (this view's awaited run, or an external one) auto-rolls
+     * the slot forward — UNLESS the user explicitly selected an earlier member
+     * (`user`), which pins and is left untouched. The agent mints the run-id, so
+     * we can't match the awaited run by id — once the group grows we adopt the
+     * newest as the selected member.
+     */
+    private _resolvePendingRegenSelections;
+    /**
+     * Roll `pending` and `auto` non-head regenerate selections forward to the
+     * newest regenerator of their anchor message. Mirrors
+     * {@link _resolvePendingRegenSelections} for the non-head group, which lives in
+     * a separate selection map (anchored by the regenerate target rather than a
+     * sibling-group root): a `user` selection pins and is left untouched; a
+     * `pending`/`auto` slot adopts the newest regenerator once one lands. The
+     * anchor's predecessor — the key the regenerators file under — is recovered
+     * from the owning run's projection.
      */
-    private _resolvePendingSelections;
+    private _resolvePendingNonHeadRegenSelections;
     private _onTreeAblyMessage;
-    private _onTreeTurn;
+    private _onTreeRun;
     /**
-     * Predict whether a turn-start's messages will be visible on this view's branch
-     * using the parent/forkOf metadata from the event.
-     * @param event - The turn-start lifecycle event with optional branch metadata.
-     * @returns True if the turn's messages are expected to be visible on this view's branch.
+     * Predict whether a run-start's messages will be visible on this view's
+     * branch using the parent/forkOf metadata from the event.
+     * @param event - The run-start lifecycle event.
+     * @returns True if the run is expected to be visible on this view's branch.
      */
-    private _isTurnStartVisible;
+    private _isRunStartVisible;
     private _visibleChanged;
 }
 /**
@@ -163,4 +468,5 @@ export declare class DefaultView<TEvent, TMessage> implements View<TEvent, TMess
  * @param options - The tree, channel, codec, and logger to use.
  * @returns A new {@link DefaultView} instance.
  */
-export declare const createView: <TEvent, TMessage>(options: ViewOptions<TEvent, TMessage>) => DefaultView<TEvent, TMessage>;
+export declare const createView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(options: ViewOptions<TInput, TOutput, TProjection, TMessage>) => DefaultView<TInput, TOutput, TProjection, TMessage>;
+export {};