@dxos/react-ui-trace 0.11.1 → 0.13.0

package/src/components/Timeline/timeline-layout.test.ts

@@ -0,0 +1,177 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Trace from '@dxos/compute/Trace';
+
+import { buildExecutionGraph } from '../../execution-graph/execution-graph.ts';
+import subAgentFixture from '../../execution-graph/testing/sub-agent-delegation.json';
+import { type TimelineLayout, layoutTimeline } from './timeline-layout.ts';
+import { type Commit } from './Timeline.tsx';
+
+describe('layoutTimeline', () => {
+  test('linear history keeps every commit in lane 0', ({ expect }) => {
+    const commits: Commit[] = [
+      { id: 'c1', branch: 'main', message: 'first' },
+      { id: 'c2', branch: 'main', message: 'second', parents: ['c1'] },
+      { id: 'c3', branch: 'main', message: 'third', parents: ['c2'] },
+    ];
+    expect(`\n${format(layoutTimeline(commits, ['main']))}\n`).toMatchInlineSnapshot(`
+      "
+      0: lane 0  first
+      1: lane 0  second
+      2: lane 0  third
+      lanes (1): main -> 0
+      spans: main: 0..2
+      "
+    `);
+  });
+
+  test('a fork takes its own lane and the merge closes its span', ({ expect }) => {
+    const commits: Commit[] = [
+      { id: 'b', branch: 'main', message: 'baseline' },
+      { id: 'f0', branch: 'feature', message: 'start feature', parents: ['b'] },
+      { id: 'f1', branch: 'feature', message: 'implement', parents: ['f0'] },
+      { id: 'm', branch: 'main', message: 'merge feature', parents: ['f1', 'b'] },
+    ];
+    expect(`\n${format(layoutTimeline(commits, ['main', 'feature']))}\n`).toMatchInlineSnapshot(`
+      "
+      0: lane 0  baseline
+      1: lane 1  start feature
+      2: lane 1  implement
+      3: lane 0  merge feature
+      lanes (2): main -> 0, feature -> 1
+      spans: main: 0..3, feature: 0..3
+      "
+    `);
+  });
+
+  test('a lane is reused once its branch has merged', ({ expect }) => {
+    const commits: Commit[] = [
+      { id: 'b', branch: 'main', message: 'baseline' },
+      { id: 'x0', branch: 'first', message: 'first work', parents: ['b'] },
+      { id: 'm0', branch: 'main', message: 'merge first', parents: ['x0', 'b'] },
+      { id: 'y0', branch: 'second', message: 'second work', parents: ['m0'] },
+      { id: 'm1', branch: 'main', message: 'merge second', parents: ['y0', 'm0'] },
+    ];
+    expect(`\n${format(layoutTimeline(commits, ['main', 'first', 'second']))}\n`).toMatchInlineSnapshot(`
+      "
+      0: lane 0  baseline
+      1: lane 1  first work
+      2: lane 0  merge first
+      3: lane 1  second work
+      4: lane 0  merge second
+      lanes (2): main -> 0, first -> 1, second -> 1
+      spans: main: 0..4, first: 0..2, second: 2..4
+      "
+    `);
+  });
+
+  test('two branches open at once take separate lanes', ({ expect }) => {
+    const commits: Commit[] = [
+      { id: 'b', branch: 'main', message: 'baseline' },
+      { id: 'x0', branch: 'first', message: 'first work', parents: ['b'] },
+      { id: 'y0', branch: 'second', message: 'second work', parents: ['b'] },
+      { id: 'm0', branch: 'main', message: 'merge first', parents: ['x0', 'b'] },
+      { id: 'm1', branch: 'main', message: 'merge second', parents: ['y0', 'm0'] },
+    ];
+    expect(`\n${format(layoutTimeline(commits, ['main', 'first', 'second']))}\n`).toMatchInlineSnapshot(`
+      "
+      0: lane 0  baseline
+      1: lane 1  first work
+      2: lane 2  second work
+      3: lane 0  merge first
+      4: lane 0  merge second
+      lanes (3): main -> 0, first -> 1, second -> 2
+      spans: main: 0..4, first: 0..3, second: 0..4
+      "
+    `);
+  });
+
+  test('a branch outside the whitelist gets no lane and no row', ({ expect }) => {
+    const commits: Commit[] = [
+      { id: 'b', branch: 'main', message: 'baseline' },
+      { id: 'h0', branch: 'hidden', message: 'hidden work', parents: ['b'] },
+      { id: 'c1', branch: 'main', message: 'more', parents: ['b'] },
+    ];
+    const layout = layoutTimeline(commits, ['main']);
+    expect(`\n${format(layout)}\n`).toMatchInlineSnapshot(`
+      "
+      0: lane 0  baseline
+      2: lane 0  more
+      lanes (1): main -> 0
+      spans: main: 0..2, hidden: 0..1
+      "
+    `);
+    // The keyboard navigates in commit indices, so the hidden commit maps to no row.
+    expect([...layout.rowByCommitIndex.entries()]).toEqual([
+      [0, 0],
+      [2, 1],
+    ]);
+  });
+
+  test('a parent that is not in the list is ignored', ({ expect }) => {
+    const commits: Commit[] = [
+      { id: 'c1', branch: 'main', message: 'first', parents: ['pruned'] },
+      { id: 'f0', branch: 'feature', message: 'fork', parents: ['c1', 'pruned'] },
+    ];
+    expect(`\n${format(layoutTimeline(commits, ['main', 'feature']))}\n`).toMatchInlineSnapshot(`
+      "
+      0: lane 0  first
+      1: lane 1  fork
+      lanes (2): main -> 0, feature -> 1
+      spans: main: 0..1, feature: 0..1
+      "
+    `);
+  });
+
+  test('the sub-agent delegation fixture', ({ expect }) => {
+    // External JSON → typed at this boundary; `buildExecutionGraph` reads only `meta`/`events`.
+    const messages = (subAgentFixture as unknown as Trace.Message[])
+      .slice()
+      .sort((left, right) => (left.events[0]?.timestamp ?? 0) - (right.events[0]?.timestamp ?? 0));
+    const { commits, branches } = buildExecutionGraph({ traceMessages: messages });
+    const layout = layoutTimeline(commits, branches);
+
+    expect(layout.rows).toHaveLength(commits.length);
+    expect(`\n${layout.rows.map(({ commit }) => `lane ${layout.branchLane.get(commit.branch)}`).join('\n')}\n`)
+      .toMatchInlineSnapshot(`
+        "
+        lane 0
+        lane 1
+        lane 1
+        lane 1
+        lane 1
+        lane 1
+        lane 1
+        lane 2
+        lane 2
+        lane 2
+        lane 2
+        lane 2
+        lane 2
+        lane 2
+        lane 2
+        lane 2
+        lane 2
+        lane 0
+        lane 1
+        lane 0
+        lane 0
+        "
+      `);
+  });
+});
+
+/** One line per row (`lane message`), then the lanes and spans the pass assigned. */
+const format = (layout: TimelineLayout): string => {
+  const rows = layout.rows.map(({ commit, index }) => {
+    const lane = layout.branchLane.get(commit.branch) ?? -1;
+    return `${index}: lane ${lane}  ${commit.message}`;
+  });
+  const lanes = [...layout.branchLane.entries()].map(([branch, lane]) => `${branch} -> ${lane}`);
+  const spans = [...layout.spans.entries()].map(([branch, span]) => `${branch}: ${span.start}..${span.end}`);
+  return [...rows, `lanes (${layout.laneCount}): ${lanes.join(', ')}`, `spans: ${spans.join(', ')}`].join('\n');
+};

package/src/components/Timeline/timeline-layout.ts

@@ -0,0 +1,153 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Commit } from './Timeline.tsx';
+
+/** The row range a branch's line covers, in commit indices. */
+export type TimelineSpan = {
+  start: number;
+  end: number;
+};
+
+export type TimelineRow = {
+  commit: Commit;
+  /** Index into the commit list the layout was built from; `spans` share these coordinates. */
+  index: number;
+};
+
+export type TimelineLayout = {
+  /** One row per commit on a whitelisted branch, in commit order. */
+  rows: TimelineRow[];
+  /** Lane per branch; a branch outside the whitelist gets none, and so gets no rows. */
+  branchLane: Map<string, number>;
+  /** Lanes the row graphic has to be wide enough for. */
+  laneCount: number;
+  /** The span each branch's line covers. */
+  spans: Map<string, TimelineSpan>;
+  /** Row index per commit index — the keyboard navigates in commit indices but scrolls rows. */
+  rowByCommitIndex: Map<number, number>;
+  /** Commit index per commit id — a click names a commit, everything else speaks in indices. */
+  commitIndexById: Map<string, number>;
+};
+
+/**
+ * Lays a commit graph out into rows: which lane each branch draws in, how far each branch's line
+ * runs, and which commits get a row at all.
+ *
+ * Pure and linear in the number of commits: every lookup a commit makes about a parent, and every
+ * lane release, is served from an index built in one pass. Commits are assumed to be in topological
+ * order — a parent always precedes its children.
+ */
+export const layoutTimeline = (commits: readonly Commit[], branches: readonly string[]): TimelineLayout => {
+  const visibleBranches = new Set(branches);
+  const firstBranch = branches[0];
+
+  const commitIndexById = new Map<string, number>();
+  commits.forEach((commit, index) => {
+    if (!commitIndexById.has(commit.id)) {
+      commitIndexById.set(commit.id, index);
+    }
+  });
+
+  const positionOf = (commitId: string): { index: number; branch: string } | undefined => {
+    const index = commitIndexById.get(commitId);
+    return index === undefined ? undefined : { index, branch: commits[index].branch };
+  };
+
+  // The row at which each branch is merged by another branch, and so may hand its lane back.
+  const mergeRow = new Map<string, number>();
+  commits.forEach((commit, row) => {
+    for (const parentId of commit.parents ?? []) {
+      const parent = positionOf(parentId);
+      if (parent && parent.branch !== commit.branch && visibleBranches.has(parent.branch)) {
+        mergeRow.set(parent.branch, row);
+      }
+    }
+  });
+
+  // Inverted so a row releases lanes with one lookup instead of a scan of every merge.
+  const releasedAtRow = new Map<number, string[]>();
+  for (const [branch, endRow] of mergeRow) {
+    if (branch === firstBranch) {
+      continue;
+    }
+    const released = releasedAtRow.get(endRow);
+    if (released) {
+      released.push(branch);
+    } else {
+      releasedAtRow.set(endRow, [branch]);
+    }
+  }
+
+  // Assign branches to lanes, reusing a lane once its branch has been merged. Unmerged branches
+  // keep their lane active — they may still be in progress.
+  const branchLane = new Map<string, number>();
+  if (firstBranch !== undefined) {
+    branchLane.set(firstBranch, 0);
+  }
+
+  const activeLanes = new Set<number>([0]);
+  let maxLane = 0;
+
+  commits.forEach((commit, row) => {
+    if (visibleBranches.has(commit.branch) && !branchLane.has(commit.branch)) {
+      let lane = 1;
+      while (activeLanes.has(lane)) {
+        lane++;
+      }
+      branchLane.set(commit.branch, lane);
+      activeLanes.add(lane);
+      maxLane = Math.max(maxLane, lane);
+    }
+
+    for (const branch of releasedAtRow.get(row) ?? []) {
+      const lane = branchLane.get(branch);
+      if (lane !== undefined) {
+        activeLanes.delete(lane);
+      }
+    }
+  });
+
+  // How far each branch's line runs: from its first commit (or the fork it came off) to its last
+  // commit (or the merge that absorbed it).
+  const spans = new Map<string, TimelineSpan>();
+  commits.forEach((commit, index) => {
+    let span = spans.get(commit.branch);
+    if (span) {
+      span.end = index;
+    } else {
+      span = { start: index, end: index };
+      spans.set(commit.branch, span);
+    }
+
+    const parents = commit.parents ?? [];
+    for (const parentId of parents) {
+      const parent = positionOf(parentId);
+      if (!parent || parent.branch === commit.branch) {
+        continue;
+      }
+
+      span.start = Math.min(span.start, parent.index);
+
+      // A merge extends the branch being merged in, down to this row.
+      if (parents.length > 1) {
+        const parentSpan = spans.get(parent.branch);
+        if (parentSpan) {
+          parentSpan.end = Math.max(parentSpan.end, index);
+        }
+      }
+    }
+  });
+
+  const rows: TimelineRow[] = [];
+  const rowByCommitIndex = new Map<number, number>();
+  commits.forEach((commit, index) => {
+    if (branchLane.has(commit.branch)) {
+      rowByCommitIndex.set(index, rows.length);
+      rows.push({ commit, index });
+    }
+  });
+
+  return { rows, branchLane, laneCount: maxLane + 1, spans, rowByCommitIndex, commitIndexById };
+};

package/src/components/TracePanel/SpanTreeView.tsx

@@ -0,0 +1,39 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { TextEditor } from '@dxos/react-ui-editor';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import type * as Util from '@dxos/react-ui/Util';
+import { createBasicExtensions, createThemeExtensions, folding, json } from '@dxos/ui-editor';
+import { safeStringify } from '@dxos/util';
+
+export type SpanTreeViewProps = Util.ThemedClassName<{
+  spanTree: unknown;
+}>;
+
+/**
+ * The trace's span tree as read-only JSON.
+ *
+ * CodeMirror puts only the lines in view into the DOM and parses the rest in time-sliced chunks, so
+ * showing a tree stops costing what the tree is worth — a highlighter renders every one of its lines
+ * in one synchronous pass. `TextEditor` rather than `Editor.View`: this pane has no toolbar, so the
+ * compound component's context would only be wiring nothing reads.
+ */
+export const SpanTreeView = ({ classNames, spanTree }: SpanTreeViewProps) => {
+  const themeMode = Hooks.useThemeMode();
+  const value = useMemo(() => safeStringify(spanTree, undefined, 2), [spanTree]);
+  const extensions = useMemo(
+    () => [
+      createBasicExtensions({ readOnly: true, lineWrapping: false, search: true }),
+      createThemeExtensions({ themeMode, syntaxHighlighting: true }),
+      json(),
+      folding(),
+    ],
+    [themeMode],
+  );
+
+  return <TextEditor classNames={['text-xs', classNames]} value={value} extensions={extensions} />;
+};

package/src/components/TracePanel/TracePanel.stories.tsx

@@ -0,0 +1,106 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Option from 'effect/Option';
+import React, { useMemo, useState } from 'react';
+
+import * as Process from '@dxos/compute/Process';
+import type * as Trace from '@dxos/compute/Trace';
+import { Annotation } from '@dxos/echo';
+import { URI } from '@dxos/keys';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { buildExecutionGraph } from '../../execution-graph/index.ts';
+import { makeProcess, subAgentDelegationFixture } from '../../testing/index.ts';
+import { translations } from '../../translations.ts';
+import { ALL_PROCESS_ENVIRONMENTS, type ProcessEnvironment, filterTraceMessages } from './trace-filter.ts';
+import { TracePanel, type TracePanelProps } from './TracePanel.tsx';
+
+// Raw Trace.Message[] captured from a live sub-agent delegation via `dxosDumpTrace()`. External
+// JSON → typed at this boundary; `buildExecutionGraph` only reads `meta`/`events`.
+const messages = (subAgentDelegationFixture as unknown as Trace.Message[])
+  .slice()
+  .sort((a, b) => (a.events[0]?.timestamp ?? 0) - (b.events[0]?.timestamp ?? 0));
+
+/** One process per top-level pid in the fixture, so the tree has something to pick. */
+const processes: Process.Process[] = [...new Set(messages.map((message) => message.meta.pid))]
+  .filter((pid): pid is string => pid !== undefined)
+  .map((pid, index) => {
+    const own = messages.filter((message) => message.meta.pid === pid);
+    const parentPid = own[0]?.meta.parentPid;
+    const name = own[0]?.meta.processName ?? `Process ${index + 1}`;
+    // The fixture's one agent: the other top-level pid is the chat-naming operation the UI ran.
+    const isAgent = parentPid === undefined && name === 'Agent';
+    return makeProcess({
+      pid: Process.ID.make(pid),
+      parentPid: parentPid === undefined ? null : Process.ID.make(parentPid),
+      name,
+      state: Process.State.SUCCEEDED,
+      startedAt: own[0]?.events[0]?.timestamp ?? 0,
+      completedAt: Option.some(own.at(-1)?.events.at(-1)?.timestamp ?? 0),
+      metrics: { wallTime: 1_200 * (index + 1), inputCount: 1, outputCount: 1 },
+      params: {
+        name,
+        annotations: Annotation.buildDictionary((dictionary) => {
+          if (isAgent) {
+            Annotation.setDictionary(dictionary, Process.HarnessHostAnnotation, true);
+            Annotation.setDictionary(dictionary, Process.TargetAnnotation, URI.make('dxn:echo:@:chat'));
+          }
+        }),
+      },
+    });
+  });
+
+type StoryProps = Pick<TracePanelProps, 'debug'>;
+
+/** The story holds what the app's container would: the selection, the environment filter, the graph. */
+const DefaultStory = ({ debug }: StoryProps) => {
+  const [selected, setSelected] = useState<readonly string[]>([]);
+  const [environments, setEnvironments] = useState<readonly ProcessEnvironment[]>(ALL_PROCESS_ENVIRONMENTS);
+  const graph = useMemo(
+    () => buildExecutionGraph({ traceMessages: filterTraceMessages(messages, selected), activeProcesses: [] }),
+    [selected],
+  );
+
+  return (
+    <TracePanel
+      processes={processes}
+      graph={graph}
+      environments={environments}
+      onEnvironmentsChange={setEnvironments}
+      debug={debug}
+      selected={selected}
+      onSelectedChange={setSelected}
+      resolveLabel={(process) => (Process.isHarnessHost(process) ? 'Agent (sub-agent delegation)' : undefined)}
+      onProcessTerminate={() => {}}
+      onOpenLink={(uri) => {
+        // eslint-disable-next-line no-console
+        console.log('open', uri);
+      }}
+    />
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-trace/TracePanel',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-(--dx-complementary-sidebar-size)' })],
+  parameters: { layout: 'fullscreen', translations },
+} satisfies Meta<StoryProps>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * A captured sub-agent delegation: the supervisor, its tool calls and the spawned sub-agent, as the
+ * process tree and the commit graph. Click a process to narrow the trace to it; ⌘-click adds one.
+ */
+export const Default: Story = { args: {} };
+
+/** The span tree the graph was built from, in place of the timeline. */
+export const Debug: Story = {
+  args: { debug: true },
+};