@dxos/react-ui-trace 0.11.1

package/src/components/Timeline/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Timeline.tsx';
+export * from './timeline-options.ts';
+export { renderTimelineAscii } from './timeline-printer.ts';

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

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// Kept out of `Timeline.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so constants exported beside them force a full page reload on every edit.
+
+export type TimelineOptions = {
+  lineHeight: number;
+  columnWidth: number;
+  nodeRadius: number;
+  lineStyle: string;
+};
+
+export const defaultOptions: TimelineOptions = {
+  lineHeight: 24,
+  columnWidth: 14,
+  nodeRadius: 5,
+  lineStyle: 'stroke-1',
+};
+
+export const compactOptions: TimelineOptions = {
+  lineHeight: 20,
+  columnWidth: 12,
+  nodeRadius: 4,
+  lineStyle: 'stroke-1',
+};

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

@@ -0,0 +1,76 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { renderTimelineAscii } from './timeline-printer.ts';
+import { type Commit } from './Timeline.tsx';
+
+describe('renderTimelineAscii', () => {
+  test('linear single branch', () => {
+    const commits: Commit[] = [
+      { id: 'c1', branch: 'main', message: 'first', parents: [] },
+      { id: 'c2', branch: 'main', message: 'second', parents: ['c1'] },
+      { id: 'c3', branch: 'main', message: 'third', parents: ['c2'] },
+    ];
+    expect(`\n${renderTimelineAscii(commits, ['main'])}\n`).toMatchInlineSnapshot(`
+      "
+      ●  first
+      ●  second
+      ●  third
+      "
+    `);
+  });
+
+  test('fork from main, merge back', () => {
+    const commits: Commit[] = [
+      { id: 'b', branch: 'main', message: 'baseline on main', parents: [] },
+      { id: 'f0', branch: 'feature', message: 'start feature', parents: ['b'] },
+      { id: 'f1', branch: 'feature', message: 'implement', parents: ['f0'] },
+      { id: 'f2', branch: 'feature', message: 'polish', parents: ['f1'] },
+      {
+        id: 'm',
+        branch: 'main',
+        message: 'merge feature into main',
+        parents: ['f2', 'b'],
+      },
+    ];
+    expect(`\n${renderTimelineAscii(commits, ['main', 'feature'])}\n`).toMatchInlineSnapshot(`
+      "
+      ●     baseline on main
+      ├──●  start feature
+      │  ●  implement
+      │  ●  polish
+      ◆──╯  merge feature into main
+      "
+    `);
+  });
+
+  test('two interleaved feature branches', () => {
+    const commits: Commit[] = [
+      { id: 'b', branch: 'main', message: 'baseline', parents: [] },
+      { id: 'a1', branch: 'alpha', message: 'alpha start', parents: ['b'] },
+      { id: 'b1', branch: 'beta', message: 'beta start', parents: ['b'] },
+      { id: 'a2', branch: 'alpha', message: 'alpha work', parents: ['a1'] },
+      { id: 'b2', branch: 'beta', message: 'beta work', parents: ['b1'] },
+      { id: 'a3', branch: 'alpha', message: 'alpha done', parents: ['a2'] },
+      { id: 'ma', branch: 'main', message: 'merge alpha', parents: ['a3', 'b'] },
+      { id: 'b3', branch: 'beta', message: 'beta done', parents: ['b2'] },
+      { id: 'mb', branch: 'main', message: 'merge beta', parents: ['b3', 'ma'] },
+    ];
+    expect(`\n${renderTimelineAscii(commits, ['main', 'alpha', 'beta'])}\n`).toMatchInlineSnapshot(`
+      "
+      ●        baseline
+      ├──●     alpha start
+      ├──┼──●  beta start
+      │  ●  │  alpha work
+      │  │  ●  beta work
+      │  ●  │  alpha done
+      ◆──╯  │  merge alpha
+      │     ●  beta done
+      ◆─────╯  merge beta
+      "
+    `);
+  });
+});

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

@@ -0,0 +1,223 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Commit } from './Timeline.tsx';
+
+const NODE = '●';
+const MERGE_NODE = '◆';
+const RAIL = '│';
+const HORIZ = '─';
+const COL_WIDTH = 3;
+
+/**
+ * Renders commits as a monospace ASCII graph with rounded box-drawing arcs and vertical rails.
+ * Commits must be ordered chronologically (oldest first, newest last). Parents must refer to older commits.
+ */
+export const renderTimelineAscii = (commits: Commit[], branches: string[]): string => {
+  if (commits.length === 0) {
+    return '';
+  }
+
+  const laneById = assignLanes(commits, branches);
+  const lanes = commits.map((commit) => laneById.get(commit.id)!);
+  const maxLane = Math.max(...lanes);
+
+  if (maxLane === 0) {
+    return commits.map((commit) => `${NODE}  ${formatLabel(commit)}`).join('\n');
+  }
+
+  const active = computeActiveColumns(commits, lanes, laneById);
+
+  const graphParts = commits.map((commit, row) => renderRow(commit, lanes[row]!, maxLane, active[row]!, laneById));
+
+  const maxGraphWidth = Math.max(...graphParts.map((part) => part.length));
+  return commits.map((commit, row) => `${graphParts[row]!.padEnd(maxGraphWidth)}  ${formatLabel(commit)}`).join('\n');
+};
+
+const renderRow = (
+  commit: Commit,
+  commitLane: number,
+  maxLane: number,
+  activeRow: boolean[],
+  laneById: Map<string, number>,
+): string => {
+  const totalChars = (maxLane + 1) * COL_WIDTH;
+  const chars: string[] = Array(totalChars).fill(' ');
+
+  const merge = isMergeCommit(commit);
+  const fork = !merge && isForkCommit(commit, laneById, commitLane);
+
+  let connectLane = -1;
+  if (fork) {
+    const parentLane = laneById.get(commit.parents![0]!);
+    if (parentLane !== undefined) {
+      connectLane = parentLane;
+    }
+  } else if (merge) {
+    for (const parentId of commit.parents ?? []) {
+      const parentLane = laneById.get(parentId);
+      if (parentLane !== undefined && parentLane !== commitLane) {
+        connectLane = parentLane;
+        break;
+      }
+    }
+  }
+
+  for (let col = 0; col <= maxLane; col++) {
+    if (col === commitLane) {
+      continue;
+    }
+    if (activeRow[col]) {
+      chars[col * COL_WIDTH] = RAIL;
+    }
+  }
+
+  chars[commitLane * COL_WIDTH] = merge ? MERGE_NODE : NODE;
+  if (connectLane >= 0) {
+    const connectPos = connectLane * COL_WIDTH;
+    if (fork) {
+      chars[connectPos] = connectLane < commitLane ? '├' : '┤';
+    } else {
+      chars[connectPos] = connectLane > commitLane ? '╯' : '╰';
+    }
+
+    const minCol = Math.min(commitLane, connectLane);
+    const maxCol = Math.max(commitLane, connectLane);
+    for (let pos = minCol * COL_WIDTH + 1; pos < maxCol * COL_WIDTH; pos++) {
+      if (pos % COL_WIDTH === 0) {
+        const col = pos / COL_WIDTH;
+        if (activeRow[col]) {
+          chars[pos] = '┼';
+        } else {
+          chars[pos] = HORIZ;
+        }
+      } else {
+        chars[pos] = HORIZ;
+      }
+    }
+  }
+
+  return chars.join('').trimEnd();
+};
+
+const formatLabel = (commit: Commit): string => {
+  const icon = commit.icon
+    ?.replace(/^ph--/, '')
+    .replace(/--regular$/, '')
+    .replace(/--bold$/, '')
+    .replace(/--fill$/, '');
+  return icon ? `[${icon}] ${commit.message}` : commit.message;
+};
+
+/**
+ * Assigns each commit to a lane (column), reusing lanes once a branch has been merged.
+ * A branch is considered "merged" when a commit on another branch references it as a parent.
+ * Unmerged branches keep their lane active (they may still be in progress).
+ * Lane 0 is reserved for the first branch (typically 'main').
+ */
+const assignLanes = (commits: Commit[], branches: string[]): Map<string, number> => {
+  // Build commit-id to branch lookup.
+  const commitBranch = new Map<string, string>();
+  for (const commit of commits) {
+    commitBranch.set(commit.id, commit.branch);
+  }
+
+  // Find the row at which each branch is merged (closed) by another branch.
+  const mergeRow = new Map<string, number>();
+  for (let row = 0; row < commits.length; row++) {
+    const commit = commits[row]!;
+    for (const parentId of commit.parents ?? []) {
+      const parentBranch = commitBranch.get(parentId);
+      if (parentBranch && parentBranch !== commit.branch) {
+        mergeRow.set(parentBranch, Math.max(mergeRow.get(parentBranch) ?? row, row));
+      }
+    }
+  }
+
+  const branchLane = new Map<string, number>();
+  if (branches.length > 0) {
+    branchLane.set(branches[0]!, 0);
+  }
+
+  const activeLanes = new Set<number>([0]);
+  const laneById = new Map<string, number>();
+
+  for (let row = 0; row < commits.length; row++) {
+    const commit = commits[row]!;
+
+    if (!branchLane.has(commit.branch)) {
+      let lane = 1;
+      while (activeLanes.has(lane)) {
+        lane++;
+      }
+      branchLane.set(commit.branch, lane);
+      activeLanes.add(lane);
+    }
+
+    laneById.set(commit.id, branchLane.get(commit.branch)!);
+
+    // Release lanes for branches that have been merged at this row.
+    for (const [branch, endRow] of mergeRow) {
+      if (endRow === row && branch !== branches[0] && branchLane.has(branch)) {
+        activeLanes.delete(branchLane.get(branch)!);
+      }
+    }
+  }
+
+  return laneById;
+};
+
+const isMergeCommit = (commit: Commit): boolean => (commit.parents?.length ?? 0) > 1;
+
+const isForkCommit = (commit: Commit, laneById: Map<string, number>, lane: number): boolean => {
+  const parents = commit.parents;
+  if (!parents || parents.length !== 1) {
+    return false;
+  }
+  const parentLane = laneById.get(parents[0]!);
+  return parentLane !== undefined && parentLane !== lane;
+};
+
+/**
+ * Column `col` is active on `row` when `row` falls inside the vertical span
+ * of that column (the range of rows that include commits on that lane plus
+ * merge rows referencing parents on that lane) AND the row's own commit
+ * is not on that column.
+ */
+const computeActiveColumns = (commits: Commit[], lanes: number[], laneById: Map<string, number>): boolean[][] => {
+  const rows = commits.length;
+  const cols = Math.max(...lanes, 0) + 1;
+  const rowIndicesByCol: number[][] = Array.from({ length: cols }, () => []);
+
+  for (let row = 0; row < rows; row++) {
+    rowIndicesByCol[lanes[row]!]!.push(row);
+  }
+
+  for (let row = 0; row < rows; row++) {
+    for (const parentId of commits[row]?.parents ?? []) {
+      const parentLane = laneById.get(parentId);
+      if (parentLane === undefined) {
+        continue;
+      }
+      rowIndicesByCol[parentLane]!.push(row);
+    }
+  }
+
+  const active: boolean[][] = Array.from({ length: rows }, () => Array(cols).fill(false));
+  for (let col = 0; col < cols; col++) {
+    const indices = rowIndicesByCol[col]!;
+    if (indices.length === 0) {
+      continue;
+    }
+    const minR = Math.min(...indices);
+    const maxR = Math.max(...indices);
+    for (let row = minR; row <= maxR; row++) {
+      if (lanes[row] !== col) {
+        active[row]![col] = true;
+      }
+    }
+  }
+
+  return active;
+};

package/src/components/TracePanel/TracePanel.tsx

@@ -0,0 +1,248 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback, useDeferredValue, useMemo, useState } from 'react';
+
+import type * as Process from '@dxos/compute/Process';
+import {
+  Accordion,
+  Panel,
+  ScrollContainer,
+  type ThemedClassName,
+  composable,
+  composableProps,
+  useTranslation,
+} from '@dxos/react-ui';
+import { ActionToolbar } from '@dxos/react-ui-menu';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { mx } from '@dxos/ui-theme';
+
+import { type ExecutionGraph } from '../../execution-graph/index.ts';
+import { translationKey } from '../../translations.ts';
+import { ProcessTree, type ProcessTreeProps } from '../ProcessTree/index.ts';
+import { type Commit, Timeline } from '../Timeline/index.ts';
+
+import { type ProcessEnvironment, filterProcesses } from './trace-filter.ts';
+import { useTraceMenu } from './useTraceMenu.ts';
+
+export type TracePanelProps = ThemedClassName<
+  Pick<ProcessTreeProps, 'resolveLabel' | 'selected' | 'onSelectedChange' | 'onProcessTerminate'> & {
+    /** The live process tree; narrowed here by `environments`. */
+    processes: readonly Process.Info[];
+    /** The trace as a commit graph, built by `useExecutionGraph` (already narrowed to `selected`). */
+    graph: ExecutionGraph;
+    /** Process environments shown; the toolbar's funnel edits it. */
+    environments: readonly ProcessEnvironment[];
+    onEnvironmentsChange: (environments: ProcessEnvironment[]) => void;
+    /** Shows the span tree as JSON in place of the timeline. */
+    debug?: boolean;
+    /** A commit whose message links an object was picked; the host decides what opening it means. */
+    onOpenLink?: (uri: string) => void;
+  }
+>;
+
+/**
+ * A space's runtime: its processes as a tree, its trace as a commit graph, and the picked commit's
+ * event. Presentation only — the host resolves the process monitor, the trace feed, settings and
+ * navigation and hands them in as props.
+ */
+export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
+  (
+    {
+      classNames,
+      processes,
+      graph,
+      environments,
+      onEnvironmentsChange,
+      debug = false,
+      resolveLabel,
+      selected = NO_SELECTION,
+      onSelectedChange,
+      onProcessTerminate,
+      onOpenLink,
+      ...props
+    },
+    forwardedRef,
+  ) => {
+    const { t } = useTranslation(translationKey);
+    const handleClearSelection = useCallback(() => onSelectedChange?.([]), [onSelectedChange]);
+    const menu = useTraceMenu({
+      selected: environments,
+      onSelectedChange: onEnvironmentsChange,
+      selectionCount: selected.length,
+      onClearSelection: handleClearSelection,
+    });
+
+    // `useDeferredValue` batches update bursts, works together with `React.memo`.
+    // See the comment in `ProcessTreeContainer` for more details.
+    const { branches, commits, spanTree, details } = useDeferredValue(graph);
+
+    const [selectedCommit, setSelectedCommit] = useState<Commit | undefined>();
+    // Remembered across selections, so collapsing a section once keeps it collapsed.
+    const [openSections, setOpenSections] = useState<string[]>(SECTIONS.map((section) => section.id));
+    const handleCommitSelect = useCallback(
+      (commit: Commit | undefined) => {
+        setSelectedCommit(commit);
+        if (commit?.link) {
+          onOpenLink?.(commit.link);
+        }
+      },
+      [onOpenLink],
+    );
+
+    // The most recently picked process is the highlighted branch, while it is still picked.
+    const currentBranch = useMemo(() => {
+      const last = selected.at(-1);
+      return last !== undefined && branches.includes(last) ? last : null;
+    }, [selected, branches]);
+
+    return (
+      <Panel.Root {...composableProps(props, { classNames: ['h-full', classNames] })} ref={forwardedRef}>
+        <Panel.Toolbar asChild>
+          <ActionToolbar {...menu} alwaysActive classNames='justify-end' />
+        </Panel.Toolbar>
+
+        <Panel.Content>
+          <Accordion.Root<TraceSection>
+            items={SECTIONS}
+            value={openSections}
+            onValueChange={setOpenSections}
+            classNames='h-full min-h-0 rounded-none border-y-0'
+          >
+            {({ items }) =>
+              items.map((section) => {
+                switch (section.id) {
+                  case 'processes':
+                    return (
+                      <Accordion.Item key={section.id} item={section} classNames='border-x-0'>
+                        <Accordion.ItemHeader hover>
+                          <span className='text-sm text-description'>{t('trace-processes.label')}</span>
+                        </Accordion.ItemHeader>
+                        <Accordion.ItemBody classNames='p-0'>
+                          <ProcessTreeContainer
+                            classNames='max-h-[8lh]'
+                            processes={processes}
+                            environments={environments}
+                            resolveLabel={resolveLabel}
+                            selected={selected}
+                            onSelectedChange={onSelectedChange}
+                            onProcessTerminate={onProcessTerminate}
+                          />
+                        </Accordion.ItemBody>
+                      </Accordion.Item>
+                    );
+                  case 'trace':
+                    return (
+                      // The trace takes the slack: item and body are flex columns so the scroll
+                      // container inside gets a definite height to scroll within. The body's slide
+                      // animation is off here — it ramps to a measured height, and this body's height
+                      // comes from the flex slack, not its content.
+                      <Accordion.Item
+                        key={section.id}
+                        item={section}
+                        classNames={mx(
+                          'border-x-0 dx-grow flex flex-col',
+                          '[&>[data-part=item-content]]:dx-grow [&>[data-part=item-content]]:flex [&>[data-part=item-content]]:flex-col [&>[data-part=item-content]]:animate-none',
+                        )}
+                      >
+                        <Accordion.ItemHeader hover>
+                          <span className='text-sm text-description'>{t('trace.label')}</span>
+                        </Accordion.ItemHeader>
+                        <Accordion.ItemBody classNames='dx-grow grid grid-rows-[minmax(0,1fr)]'>
+                          <ScrollContainer.Root pin>
+                            <ScrollContainer.Content thin>
+                              <ScrollContainer.Fade />
+                              <ScrollContainer.Viewport>
+                                {debug ? (
+                                  <JsonHighlighter data={spanTree} classNames='text-xs' />
+                                ) : (
+                                  <Timeline
+                                    branches={branches}
+                                    branch={currentBranch}
+                                    commits={commits}
+                                    showTimestamp
+                                    onSelect={handleCommitSelect}
+                                  />
+                                )}
+                              </ScrollContainer.Viewport>
+                              <ScrollContainer.ScrollDownButton />
+                            </ScrollContainer.Content>
+                          </ScrollContainer.Root>
+                        </Accordion.ItemBody>
+                      </Accordion.Item>
+                    );
+                  case 'details': {
+                    const commit = debug ? undefined : selectedCommit;
+                    return (
+                      // With nothing selected the section stays as a plain, closed row.
+                      <Accordion.Item key={section.id} item={section} disabled={!commit} classNames='border-x-0'>
+                        <Accordion.ItemHeader hover>
+                          <span className='block truncate text-sm text-description'>
+                            {commit?.message ?? t('trace-details.label')}
+                          </span>
+                        </Accordion.ItemHeader>
+                        {commit && (
+                          <Accordion.ItemBody classNames='p-0'>
+                            <JsonHighlighter data={details[commit.id] ?? commit} classNames='max-h-[20lh] text-xs' />
+                          </Accordion.ItemBody>
+                        )}
+                      </Accordion.Item>
+                    );
+                  }
+                }
+              })
+            }
+          </Accordion.Root>
+        </Panel.Content>
+      </Panel.Root>
+    );
+  },
+);
+
+TracePanel.displayName = 'TracePanel';
+
+type TraceSection = { id: 'processes' | 'trace' | 'details' };
+
+const SECTIONS: TraceSection[] = [{ id: 'processes' }, { id: 'trace' }, { id: 'details' }];
+
+const NO_SELECTION: readonly string[] = [];
+
+type ProcessTreeContainerProps = ThemedClassName<
+  Pick<ProcessTreeProps, 'resolveLabel' | 'selected' | 'onSelectedChange' | 'onProcessTerminate'> & {
+    processes: readonly Process.Info[];
+    environments: readonly ProcessEnvironment[];
+  }
+>;
+
+// Isolate `ProcessTree` updates from the rest of the panel.
+const ProcessTreeContainer = ({
+  classNames,
+  processes,
+  environments,
+  resolveLabel,
+  selected,
+  onSelectedChange,
+  onProcessTerminate,
+}: ProcessTreeContainerProps) => {
+  // `processes` updates in bursts (about 14 updates per navigation).
+  // `useDeferredValue` will debounce update propagation, returning stale value for short periods.
+  // NOTE: `ProcessTree` MUST use `React.memo`, otherwise this will not work.
+  const processesDeferred = useDeferredValue(processes);
+  const visibleProcesses = useMemo(
+    () => filterProcesses(processesDeferred, environments),
+    [processesDeferred, environments],
+  );
+
+  return (
+    <ProcessTree
+      classNames={classNames}
+      depth={3}
+      processes={visibleProcesses}
+      resolveLabel={resolveLabel}
+      selected={selected}
+      onSelectedChange={onSelectedChange}
+      onProcessTerminate={onProcessTerminate}
+    />
+  );
+};