@aleph-alpha/chat-kit 5.4.0 → 5.6.0

package/src/adapters/responses-api.ts

@@ -599,6 +599,10 @@ interface TreeBuildState {
   // point for any future child response that chains onto it. Empty responses
   // fall back to their parent's attachment point so the chain stays connected.
   tailMessageByResponse: Map<string, string | null>;
+  // For each response, the id of its first user node (if any). Lets the arena
+  // collapse pass resolve a response's echoed user turn in O(1) instead of
+  // scanning every node; responses with no user input have no entry.
+  userMessageByResponse: Map<string, string>;
   rootMessageId: string | null;
 }
 
@@ -606,7 +610,7 @@ interface TreeBuildState {
 // continuations fold onto the turn they extend; everything else appends under
 // the chain parent resolved from `previous_response_id`.
 function linkResponse(state: TreeBuildState, resp: StoredResponse): void {
-  const { treeNodes, tailMessageByResponse } = state;
+  const { treeNodes, tailMessageByResponse, userMessageByResponse } = state;
   const parentResponseId =
     resp.previous_response_id &&
     tailMessageByResponse.has(resp.previous_response_id)
@@ -636,6 +640,11 @@ function linkResponse(state: TreeBuildState, resp: StoredResponse): void {
   for (const node of messageNodes) {
     appendNode(treeNodes, node, chainParent);
     if (firstId === null) firstId = node.id;
+    // Record the first user node so the arena collapse pass can resolve this
+    // response's echoed user turn without scanning the node map.
+    if (node.role === 'user' && !userMessageByResponse.has(resp.id)) {
+      userMessageByResponse.set(resp.id, node.id);
+    }
     chainParent = node.id;
   }
 
@@ -667,6 +676,7 @@ function linkResponse(state: TreeBuildState, resp: StoredResponse): void {
  */
 export function responsesToTree(
   responses: StoredResponse[],
+  opts?: { arenaWinners?: Record<string, string> },
 ): ResponseConversationTree {
   if (responses.length === 0) {
     return { nodes: {}, rootId: null };
@@ -675,6 +685,7 @@ export function responsesToTree(
   const state: TreeBuildState = {
     treeNodes: {},
     tailMessageByResponse: new Map<string, string | null>(),
+    userMessageByResponse: new Map<string, string>(),
     rootMessageId: null,
   };
 
@@ -682,5 +693,268 @@ export function responsesToTree(
     linkResponse(state, resp);
   }
 
-  return { nodes: state.treeNodes, rootId: state.rootMessageId };
+  const rootId = collapseArenaComparisons(
+    state.treeNodes,
+    responses,
+    opts?.arenaWinners ?? {},
+    state.rootMessageId,
+    state.userMessageByResponse,
+  );
+
+  return { nodes: state.treeNodes, rootId };
+}
+
+interface ParsedArena {
+  matchupId: string;
+  modelId?: string;
+  slot?: string;
+  slotSeed?: string;
+  variant?: string;
+}
+
+/** Parse a stored response's `metadata.arena` (JSON string or dict). */
+function parseArenaMeta(resp: StoredResponse): ParsedArena | null {
+  const raw = resp.metadata?.arena;
+  let arena: unknown = raw;
+  if (typeof raw === 'string') {
+    try {
+      arena = JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  if (!arena || typeof arena !== 'object') return null;
+  const a = arena as {
+    matchup_id?: unknown;
+    model_id?: unknown;
+    slot?: unknown;
+    slot_seed?: unknown;
+    variant?: unknown;
+  };
+  if (typeof a.matchup_id !== 'string') return null;
+  return {
+    matchupId: a.matchup_id,
+    modelId: typeof a.model_id === 'string' ? a.model_id : undefined,
+    slot: typeof a.slot === 'string' ? a.slot : undefined,
+    slotSeed: typeof a.slot_seed === 'string' ? a.slot_seed : undefined,
+    variant: typeof a.variant === 'string' ? a.variant : undefined,
+  };
+}
+
+/**
+ * Fold arena sibling responses (same `metadata.arena.matchup_id`) into one
+ * comparison node: a single user turn with the pair's assistant answers as
+ * children, marked `comparing`. Each stored arena response carries its own
+ * echoed user input, so the naive tree has one user node per response — this
+ * collapses those duplicates so reload matches the live shape (one prompt, N
+ * lanes) that {@link projectActivePath} renders.
+ *
+ * Only pairs still present as ≥2 responses are folded: once a comparison is
+ * voted-and-continued the backend drops the loser (Decision 7-Discard), so a
+ * single surviving response is left as an ordinary linear turn. `arenaWinners`
+ * (matchup id → winning response id) marks the resolved winner so the reloaded
+ * comparison renders revealed rather than blind.
+ *
+ * Returns the (possibly updated) root id. Best-effort per group.
+ */
+function collapseArenaComparisons(
+  nodes: Record<string, ResponseTreeMessage>,
+  responses: StoredResponse[],
+  arenaWinners: Record<string, string>,
+  rootMessageId: string | null,
+  userMessageByResponse: Map<string, string>,
+): string | null {
+  const userNodeFor = (responseId: string): ResponseTreeMessage | undefined => {
+    const id = userMessageByResponse.get(responseId);
+    return id ? nodes[id] : undefined;
+  };
+
+  let root = rootMessageId;
+  for (const [matchupId, group] of groupResponsesByMatchup(responses)) {
+    // Fewer than two survivors is no comparison: a lone response left after a
+    // vote-and-continue (7-Discard) stays an ordinary linear turn.
+    if (group.length < 2) continue;
+    try {
+      root = foldArenaGroup(
+        nodes,
+        group,
+        arenaWinners[matchupId],
+        userNodeFor,
+        root,
+      );
+    } catch {
+      // Leave this group as-is on any structural surprise.
+    }
+  }
+  return root;
+}
+
+/** Bucket the responses that carry arena metadata by their `matchup_id`. */
+function groupResponsesByMatchup(
+  responses: StoredResponse[],
+): Map<string, StoredResponse[]> {
+  const groups = new Map<string, StoredResponse[]>();
+  for (const resp of responses) {
+    const meta = parseArenaMeta(resp);
+    if (!meta) continue;
+    const group = groups.get(meta.matchupId) ?? [];
+    group.push(resp);
+    groups.set(meta.matchupId, group);
+  }
+  return groups;
+}
+
+/** The lane slot ('a' / 'b') stamped on an assistant node, or '' when absent. */
+function laneSlot(node: ResponseTreeMessage | undefined): string {
+  return (node?.metadata.arena as { slot?: string } | undefined)?.slot ?? '';
+}
+
+// Order comparison lanes by slot ('a' before 'b') for stable column placement.
+function compareLaneSlots(
+  nodes: Record<string, ResponseTreeMessage>,
+  x: string,
+  y: string,
+): number {
+  const sx = laneSlot(nodes[x]);
+  const sy = laneSlot(nodes[y]);
+  if (sx < sy) return -1;
+  if (sx > sy) return 1;
+  return 0;
+}
+
+// Stamp a lane's model/slot onto its assistant node so the FE can resolve a
+// column label. No-op when the assistant node or arena meta is missing.
+function stampLaneAssistant(
+  nodes: Record<string, ResponseTreeMessage>,
+  resp: StoredResponse,
+): void {
+  const meta = parseArenaMeta(resp);
+  const assistant = nodes[getAssistantNodeId(resp)];
+  if (assistant && meta) {
+    assistant.metadata.arena = { modelId: meta.modelId, slot: meta.slot };
+  }
+}
+
+// Re-parent a lane's assistant under the shared fork parent, without a duplicate
+// child link.
+function attachLane(
+  canonicalUser: ResponseTreeMessage,
+  assistant: ResponseTreeMessage,
+): void {
+  assistant.parentId = canonicalUser.id;
+  if (!canonicalUser.childrenIds.includes(assistant.id)) {
+    canonicalUser.childrenIds.push(assistant.id);
+  }
+}
+
+// Drop a lane's duplicate echoed-user node, splicing it out of its original
+// parent and clamping that parent's active index. Returns the root id, redirected
+// onto the canonical user when the removed duplicate was itself the root.
+function removeDuplicateUser(
+  nodes: Record<string, ResponseTreeMessage>,
+  dupUser: ResponseTreeMessage,
+  sharedParentId: string | null,
+  canonicalUserId: string,
+  root: string | null,
+): string | null {
+  const parent = sharedParentId !== null ? nodes[sharedParentId] : undefined;
+  if (parent) {
+    parent.childrenIds = parent.childrenIds.filter((c) => c !== dupUser.id);
+    if (parent.activeChildIndex >= parent.childrenIds.length) {
+      parent.activeChildIndex = Math.max(0, parent.childrenIds.length - 1);
+    }
+  }
+  delete nodes[dupUser.id];
+  return root === dupUser.id ? canonicalUserId : root;
+}
+
+// Put the collapsed comparison node on the active path: at the root it becomes
+// the new root, otherwise its parent's active child points at it. Returns the
+// (possibly updated) root id.
+function activateForkNode(
+  nodes: Record<string, ResponseTreeMessage>,
+  canonicalUser: ResponseTreeMessage,
+  sharedParentId: string | null,
+  root: string | null,
+): string | null {
+  if (sharedParentId === null) return canonicalUser.id;
+  const parent = nodes[sharedParentId];
+  if (parent) {
+    const idx = parent.childrenIds.indexOf(canonicalUser.id);
+    if (idx !== -1) parent.activeChildIndex = idx;
+  }
+  return root;
+}
+
+// Reveal the recorded winner lane: mark it and make it the active child. No-op
+// when no winner is recorded or its assistant is not among the lanes.
+function applyArenaWinner(
+  canonicalUser: ResponseTreeMessage,
+  group: StoredResponse[],
+  winnerRespId: string | undefined,
+): void {
+  if (!winnerRespId) return;
+  const winnerResp = group.find((r) => r.id === winnerRespId);
+  if (!winnerResp) return;
+  const winnerAssistantId = getAssistantNodeId(winnerResp);
+  const idx = canonicalUser.childrenIds.indexOf(winnerAssistantId);
+  if (idx === -1) return;
+  canonicalUser.comparisonWinnerId = winnerAssistantId;
+  canonicalUser.activeChildIndex = idx;
+}
+
+// Fold one matchup's sibling responses onto a single comparison node: the first
+// lane's user turn becomes the shared fork parent, every lane's assistant becomes
+// a child, and the duplicate echoed-user turns are dropped. The first lane's
+// assistant already sits under the canonical user, so only later lanes are
+// re-parented. Returns the (possibly updated) root id.
+function foldArenaGroup(
+  nodes: Record<string, ResponseTreeMessage>,
+  group: StoredResponse[],
+  winnerRespId: string | undefined,
+  userNodeFor: (responseId: string) => ResponseTreeMessage | undefined,
+  root: string | null,
+): string | null {
+  const first = group[0];
+  if (!first) return root;
+  const canonicalUser = userNodeFor(first.id);
+  if (!canonicalUser) return root;
+  const sharedParentId = canonicalUser.parentId;
+
+  // Stamp matchup context on the fork parent so a reloaded comparison can be
+  // voted on (the host reconstructs the preference payload from here).
+  const forkMeta = parseArenaMeta(first);
+  if (forkMeta) {
+    canonicalUser.metadata.arena = {
+      matchupId: forkMeta.matchupId,
+      slotSeed: forkMeta.slotSeed,
+      variant: forkMeta.variant,
+    };
+  }
+
+  let newRoot = root;
+  for (const [i, resp] of group.entries()) {
+    stampLaneAssistant(nodes, resp);
+    if (i === 0) continue;
+    const assistant = nodes[getAssistantNodeId(resp)];
+    if (!assistant) continue;
+    attachLane(canonicalUser, assistant);
+    const dupUser = userNodeFor(resp.id);
+    if (dupUser && dupUser.id !== canonicalUser.id) {
+      newRoot = removeDuplicateUser(
+        nodes,
+        dupUser,
+        sharedParentId,
+        canonicalUser.id,
+        newRoot,
+      );
+    }
+  }
+
+  canonicalUser.childrenIds.sort((x, y) => compareLaneSlots(nodes, x, y));
+
+  canonicalUser.comparing = true;
+  newRoot = activateForkNode(nodes, canonicalUser, sharedParentId, newRoot);
+  applyArenaWinner(canonicalUser, group, winnerRespId);
+  return newRoot;
 }

package/src/components/base/CkConversationLayout/CkConversationLayout.vue

@@ -7,9 +7,15 @@ const props = defineProps<{
   messages: T[];
 }>();
 
-defineSlots<{
+const slots = defineSlots<{
   'user-message': (props: { message: T }) => void;
   'agent-message': (props: { message: T }) => void;
+  /**
+   * Extra content appended after the last message, inside the scroll flow and
+   * aligned like an agent turn. Use for a trailing element that continues the
+   * thread but isn't a tree message (e.g. an in-progress preference comparison).
+   */
+  'thread-footer': () => void;
 }>();
 
 const scrollContainerRef = ref<HTMLElement | null>(null);
@@ -188,12 +194,23 @@ watch(
 
 // Follow agent content: handles both new agent messages and streaming updates.
 // First shrinks the spacer to match the growing content, then scrolls when it overflows.
+//
+// The trailing content can also be the `thread-footer` slot (e.g. streaming
+// preference-comparison lanes), which continues the thread after a trunk whose
+// last message is the shared *user* prompt. That case must run the same
+// spacer-shrink/follow pass — otherwise the full-viewport spacer set by
+// `scrollUserMessageToTop` is never reduced, leaving a viewport-sized gap that
+// pushes the prompt and answers out of view. `updateSpacerHeight` already
+// measures the footer (it carries `data-message-row="agent"`, so it is the
+// `lastRow`); it just needs to be invoked here. The watch fires on every tree
+// mutation because the messages array is recreated per projection.
 watch(
   () => props.messages,
   () => {
     if (props.messages.length === 0) return;
     const lastMessage = props.messages[props.messages.length - 1];
-    if (lastMessage && lastMessage.role !== 'user') {
+    const hasFooter = Boolean(slots['thread-footer']);
+    if ((lastMessage && lastMessage.role !== 'user') || hasFooter) {
       nextTick(() => {
         updateSpacerHeight();
         if (isAutoScrollEnabled.value) {
@@ -212,7 +229,7 @@ watch(
     <!-- Top fade: hints that there is more content above the viewport -->
     <div
       aria-hidden="true"
-      class="pointer-events-none absolute inset-x-0 top-0 z-10 h-8 bg-gradient-to-b from-background-surface-primary to-transparent transition-opacity duration-200"
+      class="pointer-events-none absolute inset-x-0 top-0 z-10 h-8 bg-gradient-to-b from-background-surface-secondary to-transparent transition-opacity duration-200"
       :class="showTopFade ? 'opacity-100' : 'opacity-0'"
     />
     <div
@@ -233,6 +250,15 @@ watch(
           <slot name="agent-message" :message="message" />
         </div>
       </div>
+      <!-- Trailing non-message content (e.g. an open comparison), rendered as
+           the continuation of the thread inside the scroll flow. -->
+      <div
+        v-if="$slots['thread-footer']"
+        data-message-row="agent"
+        class="flex min-w-0 justify-start"
+      >
+        <slot name="thread-footer" />
+      </div>
       <!-- Bottom spacer: shrinks as agent content grows to keep viewport stable -->
       <div
         v-if="hasBottomSpacer"
@@ -243,7 +269,7 @@ watch(
     <!-- Bottom fade: hints that there is more content below the viewport -->
     <div
       aria-hidden="true"
-      class="pointer-events-none absolute inset-x-0 bottom-0 z-10 h-8 bg-gradient-to-t from-background-surface-primary to-transparent transition-opacity duration-200"
+      class="pointer-events-none absolute inset-x-0 bottom-0 z-10 h-8 bg-gradient-to-t from-background-surface-secondary to-transparent transition-opacity duration-200"
       :class="showBottomFade ? 'opacity-100' : 'opacity-0'"
     />
   </div>

package/src/components/composed/CkConversation/CkConversation.vue

@@ -58,6 +58,12 @@ const slots = defineSlots<{
     code: string;
     language: string;
   }) => void;
+  /**
+   * Trailing content appended after the last message, inside the scroll flow
+   * and aligned like an agent turn — e.g. an in-progress preference comparison
+   * that continues the thread but isn't a tree message.
+   */
+  'thread-footer': () => void;
 }>();
 
 const labels = useChatKitLabels();
@@ -229,5 +235,9 @@ function hasHeaderActivity(message: BaseMessage): boolean {
         </CkAgentMessage>
       </slot>
     </template>
+
+    <template v-if="$slots['thread-footer']" #thread-footer>
+      <slot name="thread-footer" />
+    </template>
   </CkConversationLayout>
 </template>

package/src/composables/useConversations.spec.ts

@@ -80,6 +80,7 @@ describe('useConversations', () => {
         title: 'hey again',
         createdAt: new Date(1_777_456_746 * 1000),
         updatedAt: new Date(1_777_456_750 * 1000),
+        metadata: { title: 'hey again' },
       });
     });
 
@@ -290,6 +291,7 @@ describe('useConversations', () => {
         title: 'far away',
         createdAt: new Date(1_777_456_700 * 1000),
         updatedAt: new Date(1_777_456_701 * 1000),
+        metadata: { title: 'far away' },
       });
     });
 

package/src/composables/useConversations.ts

@@ -332,6 +332,7 @@ function mapConversation(raw: RawConversation): ConversationSummary {
     title: raw.metadata?.title ?? '',
     createdAt: secondsToDate(raw.created_at),
     updatedAt: secondsToDate(raw.updated_at),
+    metadata: raw.metadata ?? null,
   };
 }
 

package/src/handlers/useMessageHandler.ts

@@ -4,12 +4,15 @@ import {
   createEmptyTree,
   cutBranchAfter as treeCutBranchAfter,
   cutBranchAt as treeCutBranchAt,
-  getLinearPath,
+  markComparison as treeMarkComparison,
   navigate as treeNavigate,
+  projectActivePath,
   updateNode,
   updateNodeId,
+  voteComparison as treeVoteComparison,
 } from '../helpers';
 import type {
+  ActiveComparison,
   BaseMessage,
   ConversationTree,
   MessageContent,
@@ -24,10 +27,20 @@ export const useMessageHandler = () => {
   const tree = reactive<ConversationTree>(createEmptyTree());
   const currentUserMessage = ref('');
 
-  const messages = computed<BaseMessage[]>(() => getLinearPath(tree));
+  // One walk produces the linear trunk and (at most) one active comparison, so
+  // the two projections can never drift.
+  const projection = computed(() => projectActivePath(tree));
+  const messages = computed<BaseMessage[]>(() => projection.value.trunk);
+  const activeComparison = computed<ActiveComparison | null>(
+    () => projection.value.activeComparison,
+  );
 
   const currentLeafId = computed<string | null>(() => {
-    const list = messages.value;
+    // No single leaf while a comparison is open at the tail — sending is gated
+    // on `activeComparison` and "continue with winner" passes an explicit
+    // parentId (the winner branch).
+    if (projection.value.activeComparison) return null;
+    const list = projection.value.trunk;
     return list.length > 0 ? list[list.length - 1].id : null;
   });
 
@@ -114,10 +127,18 @@ export const useMessageHandler = () => {
     status: MessageStatus;
     metadata?: MessageMetadata;
     parentId?: string;
+    comparing?: boolean;
   }) {
     const existing = tree.nodes[message.id];
 
     if (existing) {
+      // `parentId` is ignored for an already-present node (it is never
+      // re-linked), so resolve it only to mark a comparison — and use the node's
+      // *actual* parent, so a stale/unknown `parentId` on the patch is a safe
+      // no-op rather than an `Unknown parent message id` throw.
+      if (message.comparing && existing.parentId) {
+        treeMarkComparison(tree, existing.parentId);
+      }
       updateNode(tree, message.id, {
         content: message.content,
         role: message.role,
@@ -127,9 +148,13 @@ export const useMessageHandler = () => {
           : {}),
       });
     } else {
+      const parentId = resolveParentId(message.parentId);
+      if (message.comparing && parentId) {
+        treeMarkComparison(tree, parentId);
+      }
       const node: TreeMessage = {
         id: message.id,
-        parentId: resolveParentId(message.parentId),
+        parentId,
         childrenIds: [],
         activeChildIndex: 0,
         role: message.role,
@@ -187,9 +212,13 @@ export const useMessageHandler = () => {
   /**
    * Drop every message that comes after `messageId` on every branch beneath
    * it. The target message is kept and becomes the new leaf of its branch.
+   *
+   * Pass `keepChildId` (a direct child of `messageId`) to spare one branch: it
+   * survives as the target's sole, active child while its siblings are dropped
+   * — e.g. keeping a chosen comparison winner and discarding the rest.
    */
-  function cutBranchAfter(messageId: string) {
-    treeCutBranchAfter(tree, messageId);
+  function cutBranchAfter(messageId: string, keepChildId?: string) {
+    treeCutBranchAfter(tree, messageId, keepChildId);
   }
 
   /**
@@ -205,8 +234,18 @@ export const useMessageHandler = () => {
     return readonly(tree);
   }
 
+  /**
+   * Record the winner of the comparison rooted at `parentId` and reveal it.
+   * Does not collapse the comparison — it stays a labelled, revealed view
+   * until the user continues past the winner (appends a turn under it).
+   */
+  function voteComparison(parentId: string, winnerBranchId: string) {
+    treeVoteComparison(tree, parentId, winnerBranchId);
+  }
+
   return {
     messages: messages as Ref<BaseMessage[]>,
+    activeComparison,
     currentUserMessage: readonly(currentUserMessage),
     currentLeafId,
     updateMessage,
@@ -220,6 +259,7 @@ export const useMessageHandler = () => {
     navigate,
     cutBranchAfter,
     cutBranchAt,
+    voteComparison,
     getTree,
   };
 };

package/src/helpers/comparison.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  addNode,
+  createEmptyTree,
+  markComparison,
+  projectActivePath,
+  voteComparison,
+} from './conversationTree';
+import type { ConversationTree, MessageContent, TreeMessage } from '../types';
+
+function node(
+  id: string,
+  parentId: string | null,
+  role: TreeMessage['role'],
+  text = id,
+): TreeMessage {
+  const content: MessageContent[] = [
+    { type: 'text', id: `${id}-t`, text, status: 'completed' },
+  ];
+  return {
+    id,
+    parentId,
+    childrenIds: [],
+    activeChildIndex: 0,
+    role,
+    content,
+    status: 'completed',
+    createdAt: new Date(0),
+  };
+}
+
+/** user U with two assistant children A/B, marked as a comparison. */
+function comparisonTree(): ConversationTree {
+  const tree = createEmptyTree();
+  addNode(tree, node('U', null, 'user', 'prompt'));
+  addNode(tree, node('A', 'U', 'assistant', 'answer A'), { activate: false });
+  addNode(tree, node('B', 'U', 'assistant', 'answer B'), { activate: false });
+  markComparison(tree, 'U');
+  return tree;
+}
+
+describe('projectActivePath', () => {
+  it('surfaces an unresolved comparison as blind lanes at the trunk tail', () => {
+    const { trunk, activeComparison } = projectActivePath(comparisonTree());
+
+    expect(trunk.map((m) => m.id)).toEqual(['U']);
+    expect(activeComparison).not.toBeNull();
+    expect(activeComparison!.resolved).toBe(false);
+    expect(activeComparison!.winnerBranchId).toBeNull();
+    expect(activeComparison!.lanes.map((l) => l.branchId)).toEqual(['A', 'B']);
+    expect(activeComparison!.lanes[0]!.path.map((m) => m.id)).toEqual(['A']);
+  });
+
+  it('keeps the comparison active + revealed after a vote (not yet continued)', () => {
+    const tree = comparisonTree();
+    voteComparison(tree, 'U', 'A');
+
+    const { trunk, activeComparison } = projectActivePath(tree);
+    expect(trunk.map((m) => m.id)).toEqual(['U']);
+    expect(activeComparison).not.toBeNull();
+    expect(activeComparison!.resolved).toBe(true);
+    expect(activeComparison!.winnerBranchId).toBe('A');
+  });
+
+  it('collapses to a linear winner chain once the winner is continued', () => {
+    const tree = comparisonTree();
+    voteComparison(tree, 'U', 'A');
+    // Continue past the winner: a follow-up turn under A.
+    addNode(tree, node('U2', 'A', 'user', 'follow up'));
+
+    const { trunk, activeComparison } = projectActivePath(tree);
+    expect(activeComparison).toBeNull();
+    // History: the fork is transparent, trunk flows through the winner.
+    expect(trunk.map((m) => m.id)).toEqual(['U', 'A', 'U2']);
+  });
+
+  it('does not treat ordinary regenerate siblings as a comparison', () => {
+    const tree = createEmptyTree();
+    addNode(tree, node('U', null, 'user'));
+    addNode(tree, node('A1', 'U', 'assistant'));
+    addNode(tree, node('A2', 'U', 'assistant')); // regenerate: latest active
+    const { trunk, activeComparison } = projectActivePath(tree);
+    expect(activeComparison).toBeNull();
+    expect(trunk.map((m) => m.id)).toEqual(['U', 'A2']);
+  });
+});
+
+describe('addNode activate flag', () => {
+  it('does not move activeChildIndex when activate:false', () => {
+    const tree = createEmptyTree();
+    addNode(tree, node('U', null, 'user'));
+    addNode(tree, node('A', 'U', 'assistant'), { activate: false });
+    addNode(tree, node('B', 'U', 'assistant'), { activate: false });
+    expect(tree.nodes['U']!.activeChildIndex).toBe(0);
+    expect(tree.nodes['U']!.childrenIds).toEqual(['A', 'B']);
+  });
+});
+
+describe('voteComparison', () => {
+  it('records the winner and points activeChildIndex at it', () => {
+    const tree = comparisonTree();
+    voteComparison(tree, 'U', 'B');
+    expect(tree.nodes['U']!.comparisonWinnerId).toBe('B');
+    expect(tree.nodes['U']!.activeChildIndex).toBe(1);
+    expect(tree.nodes['U']!.comparing).toBe(true); // stays a comparison
+  });
+
+  it('is a no-op for an unknown winner id', () => {
+    const tree = comparisonTree();
+    voteComparison(tree, 'U', 'nope');
+    expect(tree.nodes['U']!.comparisonWinnerId).toBeUndefined();
+  });
+});