@ably/ai-transport 0.2.0 → 0.3.0

package/src/core/transport/view.ts

@@ -26,7 +26,7 @@ import { EventEmitter } from '../../event-emitter.js';
 import type { Logger } from '../../logger.js';
 import { getTransportHeaders } from '../../utils.js';
 import type { Codec, CodecInputEvent, CodecMessage, CodecOutputEvent } from '../codec/types.js';
-import { applyWireMessage } from './decode-fold.js';
+import type { WireApplier } from './decode-fold.js';
 import { loadHistory } from './load-history.js';
 import { nodeKey, type TreeInternal } from './tree.js';
 import type {
@@ -82,13 +82,19 @@ export type SendDelegate<TInput extends CodecInputEvent> = (
 // ---------------------------------------------------------------------------
 
 /** Options for creating a View. */
-export interface ViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+interface ViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
   /** The tree to project. */
   tree: TreeInternal<TInput, TOutput, TProjection>;
   /** The Ably channel to load history from. */
   channel: Ably.RealtimeChannel;
-  /** The codec used to project messages, mint regenerate inputs, and decode history. */
+  /** 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. */
@@ -139,15 +145,48 @@ type RegenSelection =
   | { kind: 'pending'; carrierCodecMessageId: string };
 
 /**
- * A resolved branch point: the group `kind` plus the sibling nodes that make
- * up the alternatives. `fork-of` is an edit-style branch anchored at the user
- * input node; `regen` is a regenerate-style branch anchored at the assistant
- * slot. `groupRoot` is the group's key (input group root for fork-of, the
- * original reply's group root for regen).
+ * One alternative inside a {@link MessageBranchPoint}. The representative is the
+ * member's own head message for fork-of and whole-reply regen groups, but the
+ * *regenerate target* (a non-head message) for a non-head regen group - so it is
+ * tracked explicitly rather than re-derived from the node's head.
  */
-type MessageBranchPoint<TProjection> =
-  | { kind: 'fork-of'; groupRoot: string; siblings: ConversationNode<TProjection>[] }
-  | { kind: 'regen'; groupRoot: string; siblings: ConversationNode<TProjection>[] };
+interface BranchMember {
+  /**
+   * The member node's `nodeKey` (tree.ts): a runId for a reply/regenerator run,
+   * a codecMessageId for an input node. Matched by `_resolveSelectedIndex`.
+   */
+  memberNodeKey: string;
+  /** The codec-message-id rendered in this member's branch-arrow slot. */
+  representativeCodecMessageId: string;
+}
+
+/**
+ * A resolved branch point: the group `kind` plus the member alternatives.
+ *
+ * Terms: "regenerate target" = the message being replaced; "regenerator run" =
+ * the run that replaces it; "non-head message" = any message after a run's
+ * first (index > 0, includes the tail).
+ *
+ * The three kinds, by anchor:
+ * - `fork-of` — edit-style branch anchored at the user input node; members are
+ *   the alternate prompts (input-node sibling group).
+ * - `regen` — whole-reply regenerate branch anchored at the assistant slot;
+ *   members are the original reply + its regenerator runs (same-input-node
+ *   sibling reply runs).
+ * - `non-head-regen` — a regenerate that replaced a non-head message inside a
+ *   multi-message reply run; members are the owner run (the regenerate target in
+ *   place) plus each regenerator run. Not expressible as a same-parent
+ *   sibling-run group, so the View resolves and renders it itself (see
+ *   `_extractMessages`).
+ *
+ * `groupRoot` is the selection-map key: the input group root for fork-of, the
+ * original reply's group root for regen, and the regenerate target's
+ * codec-message-id for non-head-regen.
+ */
+type MessageBranchPoint =
+  | { kind: 'fork-of'; groupRoot: string; members: BranchMember[] }
+  | { kind: 'regen'; groupRoot: string; members: BranchMember[] }
+  | { kind: 'non-head-regen'; groupRoot: string; members: BranchMember[] };
 
 // ---------------------------------------------------------------------------
 // Send-input normalisation
@@ -162,22 +201,6 @@ type MessageBranchPoint<TProjection> =
 const _normaliseSend = <TInput extends CodecInputEvent>(input: TInput | TInput[]): TInput[] =>
   Array.isArray(input) ? input : [input];
 
-// ---------------------------------------------------------------------------
-// Fetch tuning
-// ---------------------------------------------------------------------------
-
-/**
- * Multiplier applied to the user-supplied Run-unit `loadOlder(limit)`
- * when issuing the first `loadHistory` page request. `loadHistory`
- * counts complete domain *messages* per page, not Runs; a typical Run
- * produces ~2 messages (user + assistant). Asking for `limit * factor`
- * messages on the first page reduces extra round-trips when the actual
- * messages-per-Run ratio is around the factor. `_loadUntilVisible`
- * still loops on the Run count regardless, so this is purely a
- * fetch-efficiency hint.
- */
-const _RUN_TO_MESSAGE_FETCH_FACTOR = 3;
-
 /**
  * Project a Tree `RunNode` down to the View-facing `RunInfo` shape:
  * drop the codec projection and the structural fields that callers
@@ -188,8 +211,8 @@ const _RUN_TO_MESSAGE_FETCH_FACTOR = 3;
 const _toRunInfo = <TProjection>(run: RunNode<TProjection>): RunInfo => ({
   runId: run.runId,
   clientId: run.clientId,
-  status: run.status,
   invocationId: run.invocationId,
+  ...run.state,
 });
 
 // ---------------------------------------------------------------------------
@@ -205,6 +228,7 @@ export class DefaultView<
   private readonly _tree: TreeInternal<TInput, TOutput, TProjection>;
   private readonly _channel: Ably.RealtimeChannel;
   private readonly _codec: Codec<TInput, TOutput, TProjection, TMessage>;
+  private readonly _applier: WireApplier;
   private readonly _sendDelegate: SendDelegate<TInput>;
   private readonly _logger: Logger;
   private readonly _emitter: EventEmitter<ViewEventsMap>;
@@ -227,6 +251,17 @@ export class DefaultView<
    */
   private readonly _regenSelections = new Map<string, RegenSelection>();
 
+  /**
+   * 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 = new Map<string, RegenSelection>();
+
   /** Spec: AIT-CT11c — runIds loaded from history but not yet revealed to the UI. */
   private readonly _withheldRunIds = new Set<string>();
 
@@ -258,6 +293,17 @@ export class DefaultView<
   /** Buffer of withheld nodes (input + reply), drained newest-first by successive loadOlder() calls. */
   private readonly _withheldBuffer: ConversationNode<TProjection>[] = [];
 
+  /**
+   * 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 = 0;
+
   /** Unsubscribe functions for tree event subscriptions. */
   private readonly _unsubs: (() => void)[] = [];
 
@@ -277,6 +323,7 @@ export class DefaultView<
     this._tree = options.tree;
     this._channel = options.channel;
     this._codec = options.codec;
+    this._applier = options.applier;
     this._sendDelegate = options.sendDelegate;
     this._onClose = options.onClose;
     this._logger = options.logger.withContext({ component: 'View' });
@@ -330,7 +377,7 @@ export class DefaultView<
     // boundary already dedup by array reference, so a redundant emit is a
     // no-op for unchanged hook consumers.
     this._lastVisibleProjections = this._cachedNodes.map((n) => n.projection);
-    this._lastVisibleMessagePairs = this._extractMessages(this._cachedNodes);
+    this._lastVisibleMessagePairs = this._extractMessages(this._cachedNodes).slice(this._hiddenMessageCount);
     this._emitter.emit('update');
   }
 
@@ -404,84 +451,185 @@ export class DefaultView<
   }
 
   /**
-   * Extract the flat TMessage[] from a visible node chain.
-   *
-   * In the two-node model the Tree's `visibleNodes` has already selected one
-   * member per sibling group (the chosen edit version, the chosen regenerate
-   * run), so a regenerate is just a sibling reply run that appears in place of
-   * the original. Each visible node contributes its own messages in projection
-   * order; the flat list is their concatenation.
-   *
-   * Deferred caveat: a mid-reply regenerate that replaces a non-head message
-   * inside a multi-message reply run is not expressible as a sibling run in
-   * this model and is not handled here (see the `regenerate-of-multi-message`
-   * golden test).
-   * @param nodes - The visible nodes (inputs + reply runs) in chronological order.
-   * @returns The flat message list, each message paired with its codec-message-id.
+   * 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(
+    targetCodecMessageId: string,
+    predecessorCodecMessageId: string,
+  ): RunNode<TProjection>[] {
+    return this._tree
+      .getReplyRuns(predecessorCodecMessageId)
+      .filter((r) => r.regeneratesCodecMessageId === targetCodecMessageId)
+      .toSorted((a, b) => (a.startSerial ?? '￿').localeCompare(b.startSerial ?? '￿'));
+  }
+
+  /**
+   * 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(
+    targetCodecMessageId: string,
+    ownerRunId: string,
+    regenerators: RunNode<TProjection>[],
+  ): string {
+    const sel = this._nonHeadRegenSelections.get(targetCodecMessageId);
+    if (sel && sel.kind !== 'pending') {
+      const keys = [ownerRunId, ...regenerators.map((r) => r.runId)];
+      if (keys.includes(sel.selectedRunId)) return sel.selectedRunId;
+    }
+    // Default: latest member = newest regenerator (regenerators is oldest-first).
+    return regenerators.at(-1)?.runId ?? ownerRunId;
+  }
+
+  /**
+   * 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(nodes: ConversationNode<TProjection>[]): CodecMessage<TMessage>[] {
     const messages: CodecMessage<TMessage>[] = [];
+    // Regenerator runs already emitted via substitution at their anchor — skip
+    // them when the node walk reaches them directly.
+    const consumedRunIds = new Set<string>();
+
     for (const node of nodes) {
-      for (const m of this._codec.getMessages(node.projection)) {
-        messages.push(m);
-      }
+      if (node.kind === 'run' && consumedRunIds.has(node.runId)) continue;
+      this._emitNodeMessages(node, messages, consumedRunIds);
     }
     return messages;
   }
 
+  /**
+   * 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(
+    node: ConversationNode<TProjection>,
+    out: CodecMessage<TMessage>[],
+    consumedRunIds: Set<string>,
+  ): void {
+    const own = this._codec.getMessages(node.projection);
+    if (node.kind !== 'run') {
+      out.push(...own);
+      return;
+    }
+    for (let i = 0; i < own.length; i++) {
+      const m = own[i];
+      if (!m) continue;
+      // Head message (i === 0) regenerates are whole-reply sibling runs, already
+      // resolved by visibleNodes — only non-head messages anchor a non-head group.
+      const predecessor = i > 0 ? own[i - 1]?.codecMessageId : undefined;
+      if (predecessor !== undefined) {
+        const regenerators = this._nonHeadRegenerators(m.codecMessageId, predecessor);
+        if (regenerators.length > 0) {
+          // Every regenerator (and any same-anchor sibling the Tree already
+          // collapsed in `visibleNodes`) is an alternative at THIS one slot, so
+          // mark them all consumed up front — the node walk must not re-emit the
+          // Tree's default-latest sibling once we render a different member here.
+          for (const r of regenerators) consumedRunIds.add(r.runId);
+          const selectedKey = this._selectedNonHeadMember(m.codecMessageId, node.runId, regenerators);
+          if (selectedKey !== node.runId) {
+            // A regenerator is selected: drop M and the rest of O, emit the
+            // selected regenerator in M's place (recursively for nested regen).
+            const chosen = regenerators.find((r) => r.runId === selectedKey);
+            if (chosen) {
+              this._emitNodeMessages(chosen, out, consumedRunIds);
+              return;
+            }
+          }
+          // Original (owner run) selected: fall through and emit M from O.
+        }
+      }
+      out.push(m);
+    }
+  }
+
   hasOlder(): boolean {
-    return this._withheldBuffer.length > 0 || this._hasMoreHistory;
+    return this._hiddenMessageCount > 0 || this._withheldBuffer.length > 0 || this._hasMoreHistory;
   }
 
   /**
-   * Reveal up to `limit` older Runs in this view.
+   * Reveal `limit` more older codecMessages in this view — fewer only when
+   * channel history is exhausted.
    *
-   * The pagination unit is the **Run**, not the message. A single Run
-   * typically materialises into multiple messages (e.g. user + assistant
-   * pair) so revealing `limit` Runs may add several messages to the flat
-   * list returned by {@link getMessages}. Channel pages don't align to
-   * Run boundaries, so {@link _loadUntilVisible} keeps fetching channel
-   * pages until at least `limit` Runs are buffered (or the channel is
-   * exhausted).
-   * @param limit - Maximum number of older Runs to reveal. Defaults to 100.
+   * 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.
    */
-  async loadOlder(limit = 100): Promise<void> {
+  async loadOlder(limit = 10): Promise<void> {
     if (this._closed || this._loadingOlder) return;
     this._loadingOlder = true;
     this._logger.trace('DefaultView.loadOlder();', { limit });
 
     try {
-      // Drain withheld buffer first (older nodes, released newest-first). The
-      // buffer holds a union of input + reply nodes, so this splices the newest
-      // `limit` NODES, not `limit` runs. Because an input node travels with the
-      // reply run it precedes, a drain may surface fewer than `limit` runs.
-      if (this._withheldBuffer.length > 0) {
-        const batch = this._withheldBuffer.splice(-limit, limit);
-        this._releaseWithheld(batch);
-        return;
-      }
-
-      // Buffer exhausted - load from channel history.
-      if (!this._hasMoreHistory && !this._lastHistoryPage) {
-        await this._loadFirstPage(limit);
+      // Phase A: the boundary run is already revealed (a previous loadOlder
+      // pulled in a whole run that overshot the message limit); reveal more of
+      // its trimmed-off oldest messages without fetching or revealing new runs.
+      if (this._hiddenMessageCount >= limit) {
+        this._hiddenMessageCount -= limit;
+        this._recomputeAndEmit();
         return;
       }
 
-      if (!this._hasMoreHistory) return;
+      // Phase B: reveal whole older runs covering the remaining message budget,
+      // then re-trim so exactly `limit` new messages surface. Runs are revealed
+      // whole (node granularity); the trim makes the message count exact.
+      const need = limit - this._hiddenMessageCount;
+      const before = this._extractMessages(this._computeFlatNodes()).length;
+      const revealedSoFar = (): number => this._extractMessages(this._computeFlatNodes()).length - before;
 
-      if (!this._lastHistoryPage?.hasNext()) {
-        this._hasMoreHistory = false;
-        return;
+      // Drain the withheld buffer toward `need` (whole older runs, newest-first).
+      if (this._withheldBuffer.length > 0) {
+        const splitIdx = this._messageTailSplitIndex(this._withheldBuffer, need);
+        const batch = this._withheldBuffer.splice(splitIdx);
+        this._releaseWithheld(batch);
       }
 
-      const nextPage = await this._lastHistoryPage.next();
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- close() may be called during await
-      if (this._closed || !nextPage) {
-        if (!nextPage) this._hasMoreHistory = false;
-        return;
+      // If the buffer was empty or fell short of `need` (e.g. it held a
+      // zero-message run), fetch channel history for the remainder. The fetch
+      // path loops over pages internally until it covers its target or history
+      // is exhausted, so a single call here suffices.
+      if (revealedSoFar() < need) {
+        await this._fetchOlder(need - revealedSoFar());
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- close() may be set during the await above
+        if (this._closed) return;
       }
 
-      await this._revealFromPage(nextPage, limit);
+      const after = this._extractMessages(this._computeFlatNodes()).length;
+      // `after - before` whole-run messages were added at the oldest end; show
+      // `limit` of them (newest), hiding the overshoot plus what was already
+      // trimmed. `<= 0` when history is exhausted before `limit` is reached.
+      this._hiddenMessageCount = Math.max(0, this._hiddenMessageCount + (after - before) - limit);
+      this._recomputeAndEmit();
     } catch (error) {
       this._logger.error('DefaultView.loadOlder(); failed', { error });
       throw error;
@@ -490,6 +638,64 @@ export class DefaultView<
     }
   }
 
+  /**
+   * 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 async _fetchOlder(target: number): Promise<void> {
+    if (!this._hasMoreHistory && !this._lastHistoryPage) {
+      await this._loadFirstPage(target);
+      return;
+    }
+
+    if (!this._hasMoreHistory) return;
+
+    if (!this._lastHistoryPage?.hasNext()) {
+      this._hasMoreHistory = false;
+      return;
+    }
+
+    const nextPage = await this._lastHistoryPage.next();
+    if (this._closed || !nextPage) {
+      if (!nextPage) this._hasMoreHistory = false;
+      return;
+    }
+
+    await this._revealFromPage(nextPage, target);
+  }
+
+  /**
+   * 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(nodes: ConversationNode<TProjection>[], target: number): number {
+    let messages = 0;
+    for (let i = nodes.length - 1; i >= 0; i--) {
+      const node = nodes[i];
+      if (!node) continue;
+      messages += this._codec.getMessages(node.projection).length;
+      if (messages >= target) return i; // reveal nodes[i..]
+    }
+    return 0; // fewer than `target` messages — reveal everything
+  }
+
   // -------------------------------------------------------------------------
   // Run lookup
   // -------------------------------------------------------------------------
@@ -547,12 +753,18 @@ export class DefaultView<
   branchSelection(codecMessageId: string): BranchSelection<TMessage> {
     const branch = this._resolveMessageBranchPoint(codecMessageId);
     if (branch) {
-      // Each sibling contributes its head message as the branch-arrow slot:
-      // for an edit fork that is the alternate user prompt; for a regenerate
-      // group it is the variant's first (anchor-equivalent) message.
-      const siblings = branch.siblings.flatMap((s) => {
-        const first = this._codec.getMessages(s.projection).at(0);
-        return first ? [first.message] : [];
+      // Each member contributes its representative message as the branch-arrow
+      // slot: for an edit fork that is the alternate user prompt; for a
+      // whole-reply regenerate group the variant's first message; for a non-head
+      // regenerate group the regenerate target (original) or the regenerator's
+      // first message.
+      const siblings = branch.members.flatMap((member) => {
+        const owner = this._tree.getNodeByCodecMessageId(member.representativeCodecMessageId);
+        if (!owner) return [];
+        const found = this._codec
+          .getMessages(owner.projection)
+          .find((m) => m.codecMessageId === member.representativeCodecMessageId);
+        return found ? [found.message] : [];
       });
 
       if (siblings.length > 0) {
@@ -595,22 +807,32 @@ export class DefaultView<
     this._logger.trace('DefaultView.selectSibling();', { codecMessageId, index });
     const branch = this._resolveMessageBranchPoint(codecMessageId);
     if (!branch) return;
-    const clamped = Math.max(0, Math.min(index, branch.siblings.length - 1));
-    const selected = branch.siblings[clamped];
+    const clamped = Math.max(0, Math.min(index, branch.members.length - 1));
+    const selected = branch.members[clamped];
     if (!selected) return; // unreachable: clamped is always in bounds
     if (branch.kind === 'fork-of') {
-      this._branchSelections.set(branch.groupRoot, { kind: 'user', selectedKey: nodeKey(selected) });
+      this._branchSelections.set(branch.groupRoot, { kind: 'user', selectedKey: selected.memberNodeKey });
       this._logger.debug('DefaultView.selectSibling(); fork-of', {
         codecMessageId,
         index: clamped,
-        selectedKey: nodeKey(selected),
+        selectedKey: selected.memberNodeKey,
+      });
+    } else if (branch.kind === 'non-head-regen') {
+      // Non-head groups live outside the visibleNodes sibling space — store in
+      // the dedicated map the message-extraction substitution reads.
+      this._nonHeadRegenSelections.set(branch.groupRoot, { kind: 'user', selectedRunId: selected.memberNodeKey });
+      this._logger.debug('DefaultView.selectSibling(); non-head-regen', {
+        codecMessageId,
+        index: clamped,
+        selectedRunId: selected.memberNodeKey,
+        anchor: branch.groupRoot,
       });
     } else {
-      this._regenSelections.set(branch.groupRoot, { kind: 'user', selectedRunId: nodeKey(selected) });
+      this._regenSelections.set(branch.groupRoot, { kind: 'user', selectedRunId: selected.memberNodeKey });
       this._logger.debug('DefaultView.selectSibling(); regenerate', {
         codecMessageId,
         index: clamped,
-        selectedRunId: nodeKey(selected),
+        selectedRunId: selected.memberNodeKey,
         groupRoot: branch.groupRoot,
       });
     }
@@ -624,41 +846,32 @@ export class DefaultView<
    * @param branch - Resolved branch-point descriptor from `_resolveMessageBranchPoint`.
    * @returns The selected sibling's index within `branch.siblings`.
    */
-  private _resolveSelectedIndex(branch: MessageBranchPoint<TProjection>): number {
+  private _resolveSelectedIndex(branch: MessageBranchPoint): number {
     if (branch.kind === 'fork-of') {
       const sel = this._branchSelections.get(branch.groupRoot);
-      if (!sel) return branch.siblings.length - 1;
-      const idx = branch.siblings.findIndex((n) => nodeKey(n) === sel.selectedKey);
-      return idx === -1 ? branch.siblings.length - 1 : idx;
+      if (!sel) return branch.members.length - 1;
+      const idx = branch.members.findIndex((m) => m.memberNodeKey === sel.selectedKey);
+      return idx === -1 ? branch.members.length - 1 : idx;
     }
-    const sel = this._regenSelections.get(branch.groupRoot);
-    if (!sel || sel.kind === 'pending') return branch.siblings.length - 1;
-    const idx = branch.siblings.findIndex((n) => nodeKey(n) === sel.selectedRunId);
-    return idx === -1 ? branch.siblings.length - 1 : idx;
+    const sel =
+      branch.kind === 'non-head-regen'
+        ? this._nonHeadRegenSelections.get(branch.groupRoot)
+        : this._regenSelections.get(branch.groupRoot);
+    if (!sel || sel.kind === 'pending') return branch.members.length - 1;
+    const idx = branch.members.findIndex((m) => m.memberNodeKey === sel.selectedRunId);
+    return idx === -1 ? branch.members.length - 1 : idx;
   }
 
   /**
-   * Resolve the branch point anchored at `codecMessageId`, if any.
-   *
-   * Returns the resolved group `kind` along with the sibling list so the
-   * caller can update the correct selection map without re-entering the
-   * runId-based `select()` dispatch (which biases to fork-of first and
-   * would mis-route a regen-anchor codec-message-id when the owning Run is in
-   * BOTH groups — e.g. R1 owns both a user prompt that got edited and
-   * an assistant that got regenerated).
-   *
-   * Two anchor cases:
-   * - **fork-of** — `codecMessageId` is the first message of a Run in a fork-of
-   *   sibling group (edit-style branch point anchored at the user prompt).
-   * - **regen** — `codecMessageId` is the regen-anchor itself (in the owner Run)
-   *   or content of a regenerator Run (regen-style branch point anchored
-   *   at the assistant slot).
+   * 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 kind + sibling list + group key (runId for fork-of,
-   *   anchor codec-message-id for regen), or undefined when `codecMessageId` is not an
-   *   anchor in either group type.
+   * @returns The resolved branch point, or undefined when `codecMessageId`
+   *   anchors no group.
    */
-  private _resolveMessageBranchPoint(codecMessageId: string): MessageBranchPoint<TProjection> | undefined {
+  private _resolveMessageBranchPoint(codecMessageId: string): MessageBranchPoint | undefined {
     const node = this._tree.getNodeByCodecMessageId(codecMessageId);
     if (!node) return undefined;
 
@@ -668,26 +881,122 @@ export class DefaultView<
     if (node.kind === 'input') {
       const siblings = this._tree.getSiblingNodes(node.codecMessageId);
       if (siblings.length > 1) {
-        return { kind: 'fork-of', groupRoot: this._tree.getGroupRoot(node.codecMessageId), siblings };
+        return {
+          kind: 'fork-of',
+          groupRoot: this._tree.getGroupRoot(node.codecMessageId),
+          members: this._nodeHeadMembers(siblings),
+        };
       }
       return undefined;
     }
 
+    // Non-head regenerate branch point: `codecMessageId` is the rendered slot for
+    // a regenerate that replaced a non-head message inside a multi-message reply
+    // run. Resolved BEFORE the same-parent `regen` group below: several non-head
+    // regenerators of one anchor share a parent (the anchor's predecessor), so
+    // the Tree files them as their own sibling group excluding the owner run; the
+    // non-head resolver instead gathers the owner plus every regenerator into one
+    // anchor-keyed group.
+    const ownMessages = this._codec.getMessages(node.projection);
+    const nonHead = this._resolveNonHeadBranchPoint(node, ownMessages, codecMessageId);
+    if (nonHead) return nonHead;
+
     // Regenerate branch point: `codecMessageId` is owned by a reply run that has
     // sibling reply runs (the original reply + its regenerators, all parented at
     // the same input node). Anchor on the head message of the run so arrows
     // appear once per variant, not on every follow-up message.
     const siblings = this._tree.getSiblingNodes(node.runId);
-    if (siblings.length > 1) {
-      const firstMsg = this._codec.getMessages(node.projection).at(0);
-      if (firstMsg?.codecMessageId === codecMessageId) {
-        return { kind: 'regen', groupRoot: this._tree.getGroupRoot(node.runId), siblings };
-      }
+    if (siblings.length > 1 && ownMessages.at(0)?.codecMessageId === codecMessageId) {
+      return {
+        kind: 'regen',
+        groupRoot: this._tree.getGroupRoot(node.runId),
+        members: this._nodeHeadMembers(siblings),
+      };
     }
 
     return undefined;
   }
 
+  /**
+   * 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(
+    node: RunNode<TProjection>,
+    ownMessages: CodecMessage<TMessage>[],
+    codecMessageId: string,
+  ): MessageBranchPoint | undefined {
+    // Case (b): `codecMessageId` is a regenerator run's head. Re-anchor on the
+    // message it regenerates and resolve from the owner run's perspective.
+    const isHead = ownMessages.at(0)?.codecMessageId === codecMessageId;
+    if (isHead && node.regeneratesCodecMessageId !== undefined) {
+      const anchorId = node.regeneratesCodecMessageId;
+      const owner = this._runByCodecMessageId(anchorId);
+      if (owner) {
+        const ownerMsgs = this._codec.getMessages(owner.projection);
+        const idx = ownerMsgs.findIndex((mm) => mm.codecMessageId === anchorId);
+        const predecessor = idx > 0 ? ownerMsgs[idx - 1]?.codecMessageId : undefined;
+        if (predecessor !== undefined) {
+          return this._buildNonHeadGroup(anchorId, owner.runId, predecessor);
+        }
+      }
+      return undefined;
+    }
+
+    // Case (a): `codecMessageId` is a non-head message of its owner run.
+    const idx = ownMessages.findIndex((mm) => mm.codecMessageId === codecMessageId);
+    const predecessor = idx > 0 ? ownMessages[idx - 1]?.codecMessageId : undefined;
+    if (predecessor === undefined) return undefined;
+    return this._buildNonHeadGroup(codecMessageId, node.runId, predecessor);
+  }
+
+  /**
+   * 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(
+    anchorCodecMessageId: string,
+    ownerRunId: string,
+    predecessorCodecMessageId: string,
+  ): MessageBranchPoint | undefined {
+    const regenerators = this._nonHeadRegenerators(anchorCodecMessageId, predecessorCodecMessageId);
+    if (regenerators.length === 0) return undefined;
+    const members: BranchMember[] = [{ memberNodeKey: ownerRunId, representativeCodecMessageId: anchorCodecMessageId }];
+    for (const r of regenerators) {
+      const head = this._codec.getMessages(r.projection).at(0);
+      if (head) members.push({ memberNodeKey: r.runId, representativeCodecMessageId: head.codecMessageId });
+    }
+    return { kind: 'non-head-regen', groupRoot: anchorCodecMessageId, members };
+  }
+
+  /**
+   * 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(nodes: ConversationNode<TProjection>[]): BranchMember[] {
+    const members: BranchMember[] = [];
+    for (const n of nodes) {
+      const head = this._codec.getMessages(n.projection).at(0);
+      if (head) members.push({ memberNodeKey: nodeKey(n), representativeCodecMessageId: head.codecMessageId });
+    }
+    return members;
+  }
+
   // -------------------------------------------------------------------------
   // Write operations
   // -------------------------------------------------------------------------
@@ -752,6 +1061,26 @@ export class DefaultView<
     // (`result.inputCodecMessageId`) so we can promote when the new reply run lands.
     const anchorRun = this._runByCodecMessageId(anchorCodecMessageId);
     if (!anchorRun) return;
+
+    // Non-head regenerate: the anchor is a non-head message of its owner run, so
+    // the new run won't be a same-parent sibling — it parents at the anchor's
+    // predecessor. Defer in the dedicated non-head map (keyed by the anchor
+    // message), not the sibling-group regen map.
+    const anchorMsgs = this._codec.getMessages(anchorRun.projection);
+    if (anchorMsgs.at(0)?.codecMessageId !== anchorCodecMessageId) {
+      this._nonHeadRegenSelections.set(anchorCodecMessageId, {
+        kind: 'pending',
+        carrierCodecMessageId: result.inputCodecMessageId,
+      });
+      this._logger.debug('DefaultView._applyRegenerateAutoSelect(); deferring non-head regenerate selection', {
+        anchorCodecMessageId,
+        carrier: result.inputCodecMessageId,
+      });
+      this._resolvePendingNonHeadRegenSelections();
+      this._recomputeAndEmitIfChanged();
+      return;
+    }
+
     const groupRoot = this._tree.getGroupRoot(anchorRun.runId);
 
     this._regenSelections.set(groupRoot, {
@@ -940,8 +1269,10 @@ export class DefaultView<
     this._emitter.off();
     this._branchSelections.clear();
     this._regenSelections.clear();
+    this._nonHeadRegenSelections.clear();
     this._withheldRunIds.clear();
     this._withheldBuffer.length = 0;
+    this._hiddenMessageCount = 0;
     this._onClose?.();
   }
 
@@ -949,57 +1280,45 @@ export class DefaultView<
   // Private: history loading
   // -------------------------------------------------------------------------
 
-  private async _loadFirstPage(limit: number): Promise<void> {
-    // loadHistory's limit counts complete domain messages per page (not
-    // Runs); see `_RUN_TO_MESSAGE_FETCH_FACTOR` for the scaling rationale.
-    const messageLimit = limit * _RUN_TO_MESSAGE_FETCH_FACTOR;
-    const firstPage = await loadHistory(this._channel, { limit: messageLimit }, this._logger);
+  private async _loadFirstPage(target: number): Promise<void> {
+    // `loadHistory`'s limit and this view's reveal target both count complete
+    // domain messages (codecMessages), so the target passes straight through.
+    const firstPage = await loadHistory(this._channel, { limit: target }, this._logger);
     if (this._closed) return;
-    await this._revealFromPage(firstPage, limit);
+    await this._revealFromPage(firstPage, target);
   }
 
   /**
-   * Walk channel history from `page` until at least `limit` new Runs are
-   * observed (or the channel is exhausted), then reveal the newest batch and
-   * withhold the rest. Snapshots the already-visible nodes up front so only
-   * newly-observed Runs count toward `limit`. No-op if the view closed during
-   * the page walk.
+   * 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 limit - Max Runs to reveal in this batch.
+   * @param target - Minimum codecMessages to reveal in this batch.
    */
-  private async _revealFromPage(page: HistoryPage, limit: number): Promise<void> {
+  private async _revealFromPage(page: HistoryPage, target: number): Promise<void> {
     // Snapshot before loading: every node already in the tree stays visible.
     const beforeRunIds = new Set(this._treeVisibleNodes().map((n) => nodeKey(n)));
 
-    const { newVisible, lastPage } = await this._loadUntilVisible(page, limit, beforeRunIds);
+    const { newVisible, lastPage } = await this._loadUntilVisible(page, target, beforeRunIds);
     if (this._closed) return;
     this._lastHistoryPage = lastPage;
     this._hasMoreHistory = lastPage.hasNext();
-    this._splitReveal(newVisible, limit);
+    this._splitReveal(newVisible, target);
   }
 
   /**
-   * Reveal the newest `limit` Runs from `newVisible` and withhold the rest
-   * so subsequent `loadOlder` calls can drain them. Called by
-   * {@link _revealFromPage} to enforce the Run-unit pagination contract.
-   * @param newVisible - Newly observed Runs from the history fetch.
-   * @param limit - Max Runs to reveal in this batch.
+   * 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(newVisible: ConversationNode<TProjection>[], limit: number): void {
-    // Reveal granularity is the reply RUN; an input node travels with the reply
-    // run it precedes. Walk newest-first, counting reply runs toward `limit`,
-    // and split the union list at the resulting boundary so an input + its reply
-    // are revealed or withheld together.
-    let runs = 0;
-    let splitIdx = newVisible.length; // index of first revealed node
-    for (let i = newVisible.length - 1; i >= 0; i--) {
-      const node = newVisible[i];
-      if (node?.kind === 'run') {
-        if (runs === limit) break;
-        runs++;
-      }
-      splitIdx = i;
-    }
+  private _splitReveal(newVisible: ConversationNode<TProjection>[], target: number): void {
+    const splitIdx = this._messageTailSplitIndex(newVisible, target);
     const batch = newVisible.slice(splitIdx);
     const withheld = newVisible.slice(0, splitIdx);
     for (const n of withheld) {
@@ -1010,20 +1329,20 @@ export class DefaultView<
   }
 
   /**
-   * Replay a history page's raw messages into the Tree. Dispatches by Ably
-   * message name to run-lifecycle vs. regular wire messages, mirroring the
-   * live `client-session._handleMessage` decode loop. Uses a fresh decoder
-   * since the session's live decoder maintains its own stream-tracker state.
+   * 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(page: HistoryPage): void {
     this._processingHistory = true;
     try {
-      // Reconstruct the tree via the shared decode-fold engine — the same path
-      // the client's live loop uses, so history replay can't drift from it.
-      const decoder = this._codec.createDecoder();
       for (const rawMsg of page.rawMessages) {
-        applyWireMessage(this._tree, decoder, rawMsg);
+        this._applier.apply(rawMsg);
       }
 
       // Emit ably-message in a batch AFTER the whole page is applied, so a
@@ -1047,9 +1366,9 @@ export class DefaultView<
     const newVisibleCount = (): number => {
       let count = 0;
       for (const n of this._treeVisibleNodes()) {
-        // Pagination counts reply RUNS toward the target (an input node travels
-        // with the reply run it precedes — see `_splitReveal`).
-        if (n.kind === 'run' && !beforeRunIds.has(nodeKey(n))) count++;
+        // Count newly-visible codecMessages toward the target (whole runs are
+        // revealed; the caller trims to the exact message count).
+        if (!beforeRunIds.has(nodeKey(n))) count += this._codec.getMessages(n.projection).length;
       }
       return count;
     };
@@ -1086,7 +1405,10 @@ export class DefaultView<
     this._lastVisibleNodeKeys = resolved.map((n) => nodeKey(n));
     this._lastVisibleNodeKeySet = new Set(this._lastVisibleNodeKeys);
     this._lastVisibleProjections = resolved.map((n) => n.projection);
-    this._lastVisibleMessagePairs = this._extractMessages(resolved);
+    // Run-level reveal, message-level trim: drop the oldest `_hiddenMessageCount`
+    // messages so a `loadOlder` page lands on exactly `limit` messages even
+    // though whole runs were revealed.
+    this._lastVisibleMessagePairs = this._extractMessages(resolved).slice(this._hiddenMessageCount);
   }
 
   private _onTreeUpdate(): void {
@@ -1109,6 +1431,7 @@ export class DefaultView<
     // shifting this view to a branch the user didn't navigate to.
     this._pinBranchSelections();
     this._resolvePendingRegenSelections();
+    this._resolvePendingNonHeadRegenSelections();
 
     this._recomputeAndEmitIfChanged();
   }
@@ -1191,6 +1514,31 @@ export class DefaultView<
     }
   }
 
+  /**
+   * 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 _resolvePendingNonHeadRegenSelections(): void {
+    for (const [anchorId, sel] of this._nonHeadRegenSelections) {
+      if (sel.kind === 'user') continue;
+      const owner = this._runByCodecMessageId(anchorId);
+      if (!owner) continue;
+      const ownerMsgs = this._codec.getMessages(owner.projection);
+      const idx = ownerMsgs.findIndex((m) => m.codecMessageId === anchorId);
+      const predecessor = idx > 0 ? ownerMsgs[idx - 1]?.codecMessageId : undefined;
+      if (predecessor === undefined) continue;
+      const newest = this._nonHeadRegenerators(anchorId, predecessor).at(-1);
+      if (!newest) continue;
+      this._nonHeadRegenSelections.set(anchorId, { kind: 'auto', selectedRunId: newest.runId });
+    }
+  }
+
   private _onTreeAblyMessage(msg: Ably.InboundMessage): void {
     // Re-emit only if the message corresponds to a visible Run
     const headers = getTransportHeaders(msg);