@dxos/react-ui-trace 0.11.1 → 0.13.0

package/src/components/TracePanel/TracePanel.tsx

@@ -5,31 +5,27 @@
 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 * as Accordion from '@dxos/react-ui/Accordion';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import * as Panel from '@dxos/react-ui/Panel';
+import * as ScrollContainer from '@dxos/react-ui/ScrollContainer';
+import * as Util from '@dxos/react-ui/Util';
 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 { SpanTreeView } from './SpanTreeView.tsx';
 import { type ProcessEnvironment, filterProcesses } from './trace-filter.ts';
 import { useTraceMenu } from './useTraceMenu.ts';
 
-export type TracePanelProps = ThemedClassName<
+export type TracePanelProps = Util.ThemedClassName<
   Pick<ProcessTreeProps, 'resolveLabel' | 'selected' | 'onSelectedChange' | 'onProcessTerminate'> & {
     /** The live process tree; narrowed here by `environments`. */
-    processes: readonly Process.Info[];
+    processes: readonly Process.Process[];
     /** The trace as a commit graph, built by `useExecutionGraph` (already narrowed to `selected`). */
     graph: ExecutionGraph;
     /** Process environments shown; the toolbar's funnel edits it. */
@@ -47,7 +43,7 @@ export type TracePanelProps = ThemedClassName<
  * 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>(
+export const TracePanel = Util.composable<HTMLDivElement, TracePanelProps>(
   (
     {
       classNames,
@@ -65,7 +61,7 @@ export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
     },
     forwardedRef,
   ) => {
-    const { t } = useTranslation(translationKey);
+    const { t } = Hooks.useTranslation(translationKey);
     const handleClearSelection = useCallback(() => onSelectedChange?.([]), [onSelectedChange]);
     const menu = useTraceMenu({
       selected: environments,
@@ -78,9 +74,16 @@ export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
     // See the comment in `ProcessTreeContainer` for more details.
     const { branches, commits, spanTree, details } = useDeferredValue(graph);
 
-    const [selectedCommit, setSelectedCommit] = useState<Commit | undefined>();
+    // A commit the graph no longer holds (the process selection moved) is no longer picked.
+    const [pickedCommit, setSelectedCommit] = useState<Commit | undefined>();
+    const selectedCommit = useMemo(
+      () => (pickedCommit && commits.some((commit) => commit.id === pickedCommit.id) ? pickedCommit : undefined),
+      [pickedCommit, commits],
+    );
     // Remembered across selections, so collapsing a section once keeps it collapsed.
     const [openSections, setOpenSections] = useState<string[]>(SECTIONS.map((section) => section.id));
+    // The timeline windows its rows against this scroller.
+    const [traceViewport, setTraceViewport] = useState<HTMLDivElement | null>(null);
     const handleCommitSelect = useCallback(
       (commit: Commit | undefined) => {
         setSelectedCommit(commit);
@@ -98,103 +101,107 @@ export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
     }, [selected, branches]);
 
     return (
-      <Panel.Root {...composableProps(props, { classNames: ['h-full', classNames] })} ref={forwardedRef}>
-        <Panel.Toolbar asChild>
+      <Panel.Root {...Util.composableProps(props, { classNames: ['h-full', classNames] })} ref={forwardedRef}>
+        <Panel.Header>
           <ActionToolbar {...menu} alwaysActive classNames='justify-end' />
-        </Panel.Toolbar>
+        </Panel.Header>
 
-        <Panel.Content>
-          <Accordion.Root<TraceSection>
-            items={SECTIONS}
+        <Panel.Body>
+          <Accordion.Root
             value={openSections}
             onValueChange={setOpenSections}
-            classNames='h-full min-h-0 rounded-none border-y-0'
+            classNames='h-full min-h-0'
+            border={false}
           >
-            {({ 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}
+            {SECTIONS.map((section) => {
+              switch (section.id) {
+                case 'processes':
+                  return (
+                    <Accordion.Item key={section.id} value={section.id}>
+                      <Accordion.ItemTrigger>
+                        <span className='text-sm text-fg-muted'>{t('trace-processes.label')}</span>
+                      </Accordion.ItemTrigger>
+                      <Accordion.ItemContent classNames='p-0'>
+                        <ProcessTreeContainer
+                          classNames='max-h-[8lh]'
+                          processes={processes}
+                          environments={environments}
+                          resolveLabel={resolveLabel}
+                          selected={selected}
+                          onSelectedChange={onSelectedChange}
+                          onProcessTerminate={onProcessTerminate}
+                        />
+                      </Accordion.ItemContent>
+                    </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}
+                      value={section.id}
+                      disabled
+                      classNames={mx(
+                        '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.ItemTrigger>
+                        <span className='text-sm text-fg-muted'>{t('trace.label')}</span>
+                      </Accordion.ItemTrigger>
+                      <Accordion.ItemContent classNames='dx-grow grid grid-rows-[minmax(0,1fr)]'>
+                        {/* Opens at the tail and follows new entries while pinned; scrolling up unpins. */}
+                        <ScrollContainer.Root pin>
+                          <ScrollContainer.Content width='thin'>
+                            <ScrollContainer.Fade classNames='h-8' />
+                            <ScrollContainer.Viewport ref={setTraceViewport}>
+                              {debug ? (
+                                <SpanTreeView spanTree={spanTree} />
+                              ) : (
+                                <Timeline
+                                  branches={branches}
+                                  branch={currentBranch}
+                                  commits={commits}
+                                  showTimestamp
+                                  scroller={traceViewport}
+                                  onSelect={handleCommitSelect}
+                                />
+                              )}
+                            </ScrollContainer.Viewport>
+                            <ScrollContainer.ScrollDownButton />
+                          </ScrollContainer.Content>
+                        </ScrollContainer.Root>
+                      </Accordion.ItemContent>
+                    </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} value={section.id} disabled={!commit}>
+                      <Accordion.ItemTrigger>
+                        <span className='flex items-center truncate text-sm text-fg-muted'>
+                          {t('trace-details.label')}
+                        </span>
+                      </Accordion.ItemTrigger>
+                      {commit && (
+                        <Accordion.ItemContent classNames='p-0'>
+                          <JsonHighlighter
+                            data={details[commit.id] ?? commit}
+                            classNames='max-h-[20lh] text-xs p-1.5'
                           />
-                        </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.ItemContent>
+                      )}
+                    </Accordion.Item>
+                  );
                 }
-              })
-            }
+              }
+            })}
           </Accordion.Root>
-        </Panel.Content>
+        </Panel.Body>
       </Panel.Root>
     );
   },
@@ -208,9 +215,9 @@ const SECTIONS: TraceSection[] = [{ id: 'processes' }, { id: 'trace' }, { id: 'd
 
 const NO_SELECTION: readonly string[] = [];
 
-type ProcessTreeContainerProps = ThemedClassName<
+type ProcessTreeContainerProps = Util.ThemedClassName<
   Pick<ProcessTreeProps, 'resolveLabel' | 'selected' | 'onSelectedChange' | 'onProcessTerminate'> & {
-    processes: readonly Process.Info[];
+    processes: readonly Process.Process[];
     environments: readonly ProcessEnvironment[];
   }
 >;

package/src/components/TracePanel/trace-filter.test.ts

@@ -10,12 +10,12 @@ import { Obj } from '@dxos/echo';
 import { SpaceId, URI } from '@dxos/keys';
 
 import { makeProcess } from '../../testing/index.ts';
-
 import {
   ALL_PROCESS_ENVIRONMENTS,
   DEFAULT_PROCESS_ENVIRONMENTS,
   ProcessEnvironment,
   filterProcesses,
+  filterProcessesBySelection,
   filterTraceMessages,
   parseProcessEnvironments,
   processEnvironment,
@@ -99,7 +99,7 @@ describe('parseProcessEnvironments', () => {
   });
 });
 
-const makeInfo = (name: string, environment: Process.Environment): Process.Info =>
+const makeInfo = (name: string, environment: Process.Environment): Process.Process =>
   makeProcess({ pid: Process.ID.make(name), name, state: Process.State.RUNNING, environment });
 
 describe('filterTraceMessages', () => {
@@ -135,3 +135,32 @@ describe('filterTraceMessages', () => {
     expect(filterTraceMessages(messages, ['z'])).toEqual([]);
   });
 });
+
+describe('filterProcessesBySelection', () => {
+  const process = (pid: string, parentPid?: string): Process.Process =>
+    makeProcess({
+      pid: Process.ID.make(pid),
+      parentPid: parentPid === undefined ? null : Process.ID.make(parentPid),
+      name: pid,
+      state: Process.State.RUNNING,
+    });
+
+  test('an empty selection is no filter', ({ expect }) => {
+    const processes = [process('a'), process('b')];
+    expect(filterProcessesBySelection(processes, [])).toBe(processes);
+  });
+
+  test('a selected process keeps its descendants and drops the rest', ({ expect }) => {
+    const processes = [process('agent'), process('tool', 'agent'), process('nested', 'tool'), process('other')];
+    expect(filterProcessesBySelection(processes, ['agent']).map((info) => info.pid)).toEqual([
+      'agent',
+      'tool',
+      'nested',
+    ]);
+  });
+
+  test('a cyclic parent chain terminates', ({ expect }) => {
+    const processes = [process('a', 'b'), process('b', 'a')];
+    expect(filterProcessesBySelection(processes, ['z'])).toEqual([]);
+  });
+});

package/src/components/TracePanel/trace-filter.ts

@@ -10,6 +10,7 @@ import type * as Trace from '@dxos/compute/Trace';
  *
  * Bucketed from the inherited {@link Process.Environment}, so filtering keeps whole subtrees together.
  */
+// TODO(burdon): Factor out.
 export const ProcessEnvironment = {
   /** Not scoped to a space: layout, navigation, identity, settings, space lifecycle. */
   App: 'app',
@@ -43,7 +44,7 @@ const ENVIRONMENT_ICONS: Record<ProcessEnvironment, string> = {
 export const environmentIcon = (environment: ProcessEnvironment): string => ENVIRONMENT_ICONS[environment];
 
 /** `conversation` outranks `space`, since a conversation always runs inside one. */
-export const processEnvironment = (process: Process.Info): ProcessEnvironment => {
+export const processEnvironment = (process: Process.Process): ProcessEnvironment => {
   if (process.environment.conversation !== undefined) {
     return ProcessEnvironment.Conversation;
   }
@@ -54,9 +55,9 @@ export const processEnvironment = (process: Process.Info): ProcessEnvironment =>
 };
 
 export const filterProcesses = (
-  processes: readonly Process.Info[],
+  processes: readonly Process.Process[],
   selected: readonly ProcessEnvironment[],
-): readonly Process.Info[] => {
+): readonly Process.Process[] => {
   // Identity when nothing is excluded, so `ProcessTree`'s `React.memo` still holds.
   if (selected.length === ALL_PROCESS_ENVIRONMENTS.length) {
     return processes;
@@ -89,6 +90,30 @@ export const parseProcessEnvironments = (selected: readonly string[] | undefined
  * runs as a child of the process it serves, so its events are that process's work. An empty
  * selection is no filter.
  */
+/**
+ * Narrows the process tree to the selected processes and their descendants, the process-side twin of
+ * {@link filterTraceMessages}: a running child of a picked process is that process's live work.
+ */
+export const filterProcessesBySelection = (
+  processes: readonly Process.Process[],
+  selected: readonly string[],
+): readonly Process.Process[] => {
+  if (selected.length === 0) {
+    return processes;
+  }
+  const parentByPid = new Map<string, string | null>(processes.map((process) => [process.pid, process.parentPid]));
+  const selection = new Set(selected);
+  const isSelected = (pid: string, depth = 0): boolean => {
+    if (selection.has(pid)) {
+      return true;
+    }
+    const parent = parentByPid.get(pid);
+    // Bounded so a cyclic parent chain (a corrupt tree) terminates.
+    return parent !== null && parent !== undefined && depth < processes.length && isSelected(parent, depth + 1);
+  };
+  return processes.filter((process) => isSelected(process.pid));
+};
+
 export const filterTraceMessages = (
   messages: readonly Trace.Message[],
   selected: readonly string[],

package/src/components/TracePanel/useTraceMenu.ts

@@ -7,7 +7,6 @@ import { useCallback } from 'react';
 import { MenuBuilder, useMenuBuilder } from '@dxos/react-ui-menu';
 
 import { translationKey } from '../../translations.ts';
-
 import {
   ALL_PROCESS_ENVIRONMENTS,
   type ProcessEnvironment,

package/src/execution-graph/SPEC.md

@@ -1,13 +1,13 @@
 # Trace Execution Graph — Specification
 
 This document specifies the pure-data layer that powers the `TracePanel` Timeline view.
-Source: `packages/plugins/plugin-assistant/src/execution-graph/`.
+Source: `packages/ui/react-ui-trace/src/execution-graph/`.
 
 ## 1. Purpose & scope
 
 The module converts a flat list of `Trace.Message` records (and a snapshot of active
 processes) into a Mercurial/Git-style commit graph consumable by the
-`@dxos/react-ui-components` `Timeline` component.
+`Timeline` component (`../components/Timeline`).
 
 In scope:
 
@@ -25,7 +25,7 @@ Out of scope:
 - Filtering / search of commits.
 - Mutating, ack-ing, or replaying trace events.
 
-Inputs: `traceMessages: Trace.Message[]`, `activeProcesses?: Process.Info[]`, `eventLimit?: number`,
+Inputs: `traceMessages: Trace.Message[]`, `activeProcesses?: Process.Process[]`, `eventLimit?: number`,
 `spanTimeoutMs?: number`, `now?: number`.
 Output: `ExecutionGraph = { branches, commits, spanTree, details }`.
 
@@ -57,7 +57,7 @@ forwarded as `SpanMeta` for downstream display but never branch or anchor logic.
 `isEphemeral` is preserved on `FlatEvent` but is not consulted; ephemeral events
 participate exactly like persistent events.
 
-### 2.2 `Process.Info` (active processes)
+### 2.2 `Process.Process` (active processes)
 
 Defined in `packages/core/compute/compute/src/Process.ts#L365`.
 Optional input via `activeProcesses` (defaults to `[]`). Fields the builder reads:
@@ -106,7 +106,7 @@ export type ExecutionGraphDetailsMap = Record<string, Trace.FlatEvent | undefine
 
 ### 3.2 `Commit` (set fields only)
 
-From `packages/ui/react-ui-components/src/components/Timeline/Timeline.tsx#L40`. The
+From `packages/ui/react-ui-trace/src/components/Timeline/Timeline.tsx#L40`. The
 builder sets:
 
 - `id` — see §9.
@@ -681,13 +681,13 @@ Each entry: **scenario → expected output → rationale**.
 
 | Symbol                                                  | File                                                                         | Line        |
 | ------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------- |
-| `buildSpanTree`                                         | `packages/plugins/plugin-assistant/src/execution-graph/span-tree.ts`         | L112        |
+| `buildSpanTree`                                         | `packages/ui/react-ui-trace/src/execution-graph/span-tree.ts`                | L112        |
 | `applyEventLimit`                                       | same                                                                         | L211        |
 | `makeTimeoutEndEvent` / `DEFAULT_SPAN_TIMEOUT_MS`       | same                                                                         | L252 / L13  |
 | `ROOT_SPAN_ID`                                          | same                                                                         | L12         |
 | `BEGIN_EVENT_TYPES`/`END_EVENT_TYPES`                   | same                                                                         | L47         |
 | `walkSpanTree`/`flattenSpanTree`                        | same                                                                         | L245        |
-| `buildExecutionGraph`                                   | `packages/plugins/plugin-assistant/src/execution-graph/execution-graph.ts`   | L91         |
+| `buildExecutionGraph`                                   | `packages/ui/react-ui-trace/src/execution-graph/execution-graph.ts`          | L91         |
 | `presentEvent`                                          | same                                                                         | L118        |
 | `isCollapsibleSpan`                                     | same                                                                         | L206        |
 | `spanTreeToCommits`                                     | same                                                                         | L239        |
@@ -696,10 +696,10 @@ Each entry: **scenario → expected output → rationale**.
 | `CommitSelector`                                        | same                                                                         | L446        |
 | `GraphBuilder` / `doctor`                               | same                                                                         | L579 / L610 |
 | `Trace.Meta` / `Trace.flatten`                          | `packages/core/compute/compute/src/Trace.ts`                                 | L102 / L178 |
-| `Process.Info` / `Process.State`                        | `packages/core/compute/compute/src/Process.ts`                               | L365 / L321 |
+| `Process.Process` / `Process.State`                     | `packages/core/compute/compute/src/Process.ts`                               | L365 / L321 |
 | `AGENT_PROCESS_KEY`                                     | `packages/core/compute/functions-runtime/src/agent-service/agent-process.ts` | L54         |
-| `Commit` type                                           | `packages/ui/react-ui-components/src/components/Timeline/Timeline.tsx`       | L40         |
-| `TracePanel` `useExecutionGraph` / default `eventLimit` | `packages/plugins/plugin-assistant/src/containers/TracePanel/TracePanel.tsx` | L138 / L153 |
+| `Commit` type                                           | `packages/ui/react-ui-trace/src/components/Timeline/Timeline.tsx`            | L40         |
+| `TracePanel` `useExecutionGraph` / default `eventLimit` | `packages/ui/react-ui-trace/src/hooks/useExecutionGraph.ts`                  | L138 / L153 |
 
 ## Appendix B: Visual contract examples
 

package/src/execution-graph/execution-graph.test.ts

@@ -6,14 +6,13 @@ import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
 import { describe, test } from 'vitest';
 
-import { RUN_AGAIN_ERROR_CODE, RUN_AGAIN_MESSAGE } from '@dxos/compute';
 import * as Process from '@dxos/compute/Process';
 import * as Trace from '@dxos/compute/Trace';
 import { Annotation } from '@dxos/echo';
 import { EntityId, URI } from '@dxos/keys';
 import { LogLevel } from '@dxos/log';
-import { type Commit, renderTimelineAscii } from '../components/Timeline/index.ts';
 
+import { type Commit, renderTimelineAscii } from '../components/Timeline/index.ts';
 import { CommitSelector, buildExecutionGraph } from './execution-graph.ts';
 import { collectTraceEvents, withMeta } from './testing/index.ts';
 
@@ -189,8 +188,8 @@ const MESSAGE_ID = '01HQ0000000000000000000000';
 const SHIMMER_EFFECT_TAG = 'effect:shimmer';
 
 const makeActiveProcess = (
-  overrides: Partial<Process.Info> & Pick<Process.Info, 'pid' | 'key' | 'state'>,
-): Process.Info => ({
+  overrides: Partial<Process.Process> & Pick<Process.Process, 'pid' | 'key' | 'state'>,
+): Process.Process => ({
   parentPid: null,
   params: { name: null, annotations: {} },
   environment: {},
@@ -930,7 +929,7 @@ describe('buildExecutionGraph scenarios', () => {
             name: 'Sync Google Mail',
             outcome: 'failure',
             error: 'Run again',
-            errorCode: RUN_AGAIN_ERROR_CODE,
+            errorCode: Process.RUN_AGAIN_ERROR_CODE,
           });
         }),
       ),
@@ -956,7 +955,7 @@ describe('buildExecutionGraph scenarios', () => {
             key: 'sync',
             name: 'Sync Google Mail',
             outcome: 'failure',
-            error: RUN_AGAIN_MESSAGE,
+            error: Process.RUN_AGAIN_MESSAGE,
           });
         }),
       ),