From 1c723c56fa942ec45f662abb1367a8d789acf071 Mon Sep 17 00:00:00 2001 From: James Long Date: Thu, 10 Sep 2026 21:40:23 -0400 Subject: [PATCH] feat(tui): add recursive grouping tree (#48394) --- .../tui/src/routes/session/grouping/tree.ts | 111 ++++++++++++++++++ .../tui/test/cli/tui/grouping-tree.test.ts | 82 +++++++++++++ 2 files changed, 193 insertions(+) create mode 100644 packages/tui/src/routes/session/grouping/tree.ts create mode 100644 packages/tui/test/cli/tui/grouping-tree.test.ts diff --git a/packages/tui/src/routes/session/grouping/tree.ts b/packages/tui/src/routes/session/grouping/tree.ts new file mode 100644 index 00000000000..d836a7a434a --- /dev/null +++ b/packages/tui/src/routes/session/grouping/tree.ts @@ -0,0 +1,111 @@ +export type GroupNode = + | { readonly type: "entry"; readonly entry: Entry; readonly size: 1 } + | { + readonly type: "group" + readonly kind: Kind + readonly children: readonly GroupNode[] + /** Number of descendant leaves, independent of disclosure state. */ + readonly size: number + } + +/** + * Group adjacent entries by their configured nesting paths. For example, a read + * can use ["exploration"] today or ["activity", "exploration"] in Low. + * Entries are opaque: message/part identity, visibility and live state remain + * owned by the session projection. A path of [] creates a standalone leaf. + */ +export function groupEntries( + entries: readonly Entry[], + path: (entry: Entry) => readonly Kind[], +): readonly GroupNode[] { + const result: BuildingNode[] = [] + entries.forEach((entry) => { + appendEntry(result, entry, path(entry)) + }) + return result +} + +// Only freshly constructed nodes are writable; the published tree is readonly. +type BuildingNode = + | { type: "entry"; entry: Entry; size: 1 } + | { type: "group"; kind: Kind; children: BuildingNode[]; size: number } + +function appendEntry( + nodes: BuildingNode[], + entry: Entry, + path: readonly Kind[], + depth = 0, +) { + const kind = path[depth] + if (kind === undefined) { + nodes.push({ type: "entry", entry, size: 1 }) + return + } + const previous = nodes.at(-1) + if (previous?.type === "group" && previous.kind === kind) { + previous.size++ + appendEntry(previous.children, entry, path, depth + 1) + return + } + const children: BuildingNode[] = [] + appendEntry(children, entry, path, depth + 1) + nodes.push({ type: "group", kind, children, size: 1 }) +} + +/** + * Concatenate ordered, disjoint chunks, recursively merging compatible groups + * at their seam. Untouched subtrees retain their object identity. + * + * This is concatenation, not ingestion: callers must reconcile overlapping + * pages/replayed message IDs before merging. Equal payloads may be distinct + * entries and must not be silently deduplicated here. + */ +export function mergeGroups( + left: readonly GroupNode[], + right: readonly GroupNode[], +): readonly GroupNode[] { + if (!left.length) return right + if (!right.length) return left + const a = left[left.length - 1] + const b = right[0] + if (a.type !== "group" || b.type !== "group" || a.kind !== b.kind) return [...left, ...right] + return [ + ...left.slice(0, -1), + { + type: "group", + kind: a.kind, + size: a.size + b.size, + children: mergeGroups(a.children, b.children), + }, + ...right.slice(1), + ] +} + +/** + * Split at a depth-first leaf offset. Group headers count as zero. Cached sizes + * skip whole subtrees; only the ancestors crossing the cut are reconstructed. + * The returned halves can be seam-merged again without changing their meaning. + */ +export function splitGroups( + nodes: readonly GroupNode[], + count: number, +): readonly [readonly GroupNode[], readonly GroupNode[]] { + if (!Number.isInteger(count) || count < 0) throw new RangeError("Group split requires a non-negative integer") + if (count === 0) return [[], nodes] + let offset = 0 + for (const [index, node] of nodes.entries()) { + const end = offset + node.size + if (count === end) return [nodes.slice(0, index + 1), nodes.slice(index + 1)] + if (count < end) { + if (node.type !== "group") throw new RangeError("Cannot split inside an entry") + const size = count - offset + const [left, right] = splitGroups(node.children, size) + return [ + [...nodes.slice(0, index), { ...node, children: left, size }], + [{ ...node, children: right, size: node.size - size }, ...nodes.slice(index + 1)], + ] + } + offset = end + } + throw new RangeError("Group split exceeds entry count") +} diff --git a/packages/tui/test/cli/tui/grouping-tree.test.ts b/packages/tui/test/cli/tui/grouping-tree.test.ts new file mode 100644 index 00000000000..8972088ecf2 --- /dev/null +++ b/packages/tui/test/cli/tui/grouping-tree.test.ts @@ -0,0 +1,82 @@ +import { expect, test } from "bun:test" +import { groupEntries, mergeGroups, splitGroups } from "../../../src/routes/session/grouping/tree" + +const path = (entry: { path: string[] }) => entry.path +const read = { id: "read", path: ["activity", "exploration"] } +const search = { id: "search", path: ["activity", "exploration"] } +const thought = { id: "thought", path: ["activity", "reasoning"] } +const text = { id: "text", path: [] } +const leaf = (entry: typeof read) => ({ type: "entry" as const, entry, size: 1 as const }) + +test("groups adjacent entries by path and counts leaves, not wrappers", () => { + expect(groupEntries([read, search, thought, text, read], path)).toEqual([ + { + type: "group", + kind: "activity", + size: 3, + children: [ + { type: "group", kind: "exploration", size: 2, children: [leaf(read), leaf(search)] }, + { type: "group", kind: "reasoning", size: 1, children: [leaf(thought)] }, + ], + }, + leaf(text), + { + type: "group", + kind: "activity", + size: 1, + children: [{ type: "group", kind: "exploration", size: 1, children: [leaf(read)] }], + }, + ]) +}) + +test("a direct child breaks a subgroup without ending the outer group", () => { + const shell = { id: "shell", path: ["activity"] } + expect(groupEntries([read, shell, search], path)).toEqual([ + { + type: "group", + kind: "activity", + size: 3, + children: [ + { type: "group", kind: "exploration", size: 1, children: [leaf(read)] }, + leaf(shell), + { type: "group", kind: "exploration", size: 1, children: [leaf(search)] }, + ], + }, + ]) +}) + +test("merges both grouping levels at a page seam without changing the inputs", () => { + const left = groupEntries([text, read], path) + const right = groupEntries([search, thought], path) + const saved = structuredClone([left, right]) + const merged = mergeGroups(left, right) + expect(merged).toEqual(groupEntries([text, read, search, thought], path)) + expect([left, right]).toEqual(saved) + expect(merged[0]).toBe(left[0]) +}) + +test("splits at each leaf boundary and merges back to the original tree", () => { + const entries = [read, search, thought, text] + const tree = groupEntries(entries, path) + for (let count = 0; count <= entries.length; count++) { + const [left, right] = splitGroups(tree, count) + expect(left).toEqual(groupEntries(entries.slice(0, count), path)) + expect(right).toEqual(groupEntries(entries.slice(count), path)) + expect(mergeGroups(left, right)).toEqual(tree) + } +}) + +test("handles empty chunks", () => { + const tree = groupEntries([read], path) + expect(groupEntries([], path)).toEqual([]) + expect(mergeGroups([], tree)).toBe(tree) + expect(mergeGroups(tree, [])).toBe(tree) + expect(splitGroups([], 0)).toEqual([[], []]) +}) + +test("rejects invalid split offsets", () => { + const tree = groupEntries([read], path) + for (const count of [-1, 0.5, 2, NaN]) { + expect(() => splitGroups(tree, count)).toThrow(RangeError) + } +})