@dxos/react-ui-trace 0.11.1

package/src/components/TracePanel/dxn-extractor.test.ts

@@ -0,0 +1,153 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import {
+  extractDxnFromString,
+  extractDxnsFromObject,
+  extractFirstDxnFromToolInput,
+  extractFirstDxnFromToolResult,
+} from './dxn-extractor.ts';
+
+describe('dxn-extractor', () => {
+  describe('extractDxnFromString', () => {
+    test('extracts plain DXN from string', ({ expect }) => {
+      const result = extractDxnFromString('Found object echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts @-prefixed reference from string', ({ expect }) => {
+      const result = extractDxnFromString('Reference to @echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4 in text');
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts multiple references from string', ({ expect }) => {
+      const result = extractDxnFromString(
+        'Objects: echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and @echo://BBBBBBBBBBBBBBBBBBBBBBBBBB/01KG7R1ZXWFMWQ4DA1Q6TN1DG5',
+      );
+      expect(result).toHaveLength(2);
+    });
+
+    test('deduplicates DXNs', ({ expect }) => {
+      const result = extractDxnFromString(
+        'Same object echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4 and echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      );
+      expect(result).toHaveLength(1);
+    });
+
+    test('returns empty array for string without DXNs', ({ expect }) => {
+      const result = extractDxnFromString('No DXNs here');
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe('extractDxnsFromObject', () => {
+    test('extracts IPLD-style reference { "/": "echo:..." }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts @uri key reference { "@uri": "echo:..." }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        '@uri': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+        'name': 'Test',
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts reference block { _tag: "reference", reference: { uri: ... } }', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        _tag: 'reference',
+        reference: {
+          uri: 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+        },
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0].toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts DXN from nested object', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        data: {
+          items: [
+            {
+              ref: { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+            },
+          ],
+        },
+      });
+      expect(result).toHaveLength(1);
+    });
+
+    test('extracts DXN from string property', ({ expect }) => {
+      const result = extractDxnsFromObject({
+        message: 'Created object echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4',
+      });
+      expect(result).toHaveLength(1);
+    });
+
+    test('extracts DXN from array', ({ expect }) => {
+      const result = extractDxnsFromObject([
+        { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+        { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG5' },
+      ]);
+      expect(result).toHaveLength(2);
+    });
+
+    test('handles null and undefined', ({ expect }) => {
+      expect(extractDxnsFromObject(null)).toHaveLength(0);
+      expect(extractDxnsFromObject(undefined)).toHaveLength(0);
+    });
+  });
+
+  describe('extractFirstDxnFromToolInput', () => {
+    test('extracts DXN from JSON tool input', ({ expect }) => {
+      const input = JSON.stringify({
+        objectRef: { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+      });
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result?.toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('extracts DXN from invalid JSON string', ({ expect }) => {
+      const input = 'Invalid JSON but contains echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4';
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result?.toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('returns undefined for input without DXNs', ({ expect }) => {
+      const input = JSON.stringify({ name: 'Test' });
+      const result = extractFirstDxnFromToolInput(input);
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('extractFirstDxnFromToolResult', () => {
+    test('extracts DXN from JSON tool result', ({ expect }) => {
+      const result = JSON.stringify({
+        created: { '/': 'echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4' },
+      });
+      const dxn = extractFirstDxnFromToolResult(result);
+      expect(dxn?.toString()).toBe('echo:/01KG7R1ZXWFMWQ4DA1Q6TN1DG4');
+    });
+
+    test('returns undefined for undefined result', ({ expect }) => {
+      const dxn = extractFirstDxnFromToolResult(undefined);
+      expect(dxn).toBeUndefined();
+    });
+
+    test('returns undefined for result without DXNs', ({ expect }) => {
+      const result = JSON.stringify({ success: true });
+      const dxn = extractFirstDxnFromToolResult(result);
+      expect(dxn).toBeUndefined();
+    });
+  });
+});

package/src/components/TracePanel/dxn-extractor.ts

@@ -0,0 +1,166 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { URI } from '@dxos/keys';
+
+/**
+ * Patterns for extracting references from tool call params/results.
+ *
+ * Supported formats:
+ * - `{ "/": "echo:…" | "dxn:…" }` - IPLD-style encoded references
+ * - `{ "@uri": "echo:…" }` - Self URI key
+ * - `@echo:…` / `@dxn:…` - In-text references (with @ prefix)
+ * - `echo:…` / `dxn:…` - Plain URI strings
+ */
+
+/**
+ * Regex matching a canonical reference URI: an `echo:` EID or a `dxn:<nsid>[:<version>]` type DXN.
+ */
+const URI_PATTERN = /(?:echo:\/{1,3}[A-Za-z0-9/]+|dxn:[a-zA-Z][a-zA-Z0-9-]*(?:\.[a-zA-Z0-9-]+)+(?::\d+\.\d+\.\d+)?)/g;
+
+/**
+ * Regex matching an `@`-prefixed reference URI in text.
+ */
+const AT_URI_PATTERN = new RegExp(`@(${URI_PATTERN.source})`, 'g');
+
+/**
+ * Extracts all reference URIs from a string.
+ */
+export const extractDxnFromString = (text: string): URI.URI[] => {
+  const dxns: URI.URI[] = [];
+  const seen = new Set<string>();
+
+  const add = (uri: string) => {
+    if (!seen.has(uri)) {
+      dxns.push(URI.make(uri));
+      seen.add(uri);
+    }
+  };
+
+  // Match @-prefixed references.
+  let match;
+  while ((match = AT_URI_PATTERN.exec(text)) !== null) {
+    add(match[1]);
+  }
+
+  // Match plain URI strings.
+  while ((match = URI_PATTERN.exec(text)) !== null) {
+    add(match[0]);
+  }
+
+  return dxns;
+};
+
+/**
+ * Extracts DXN references from a JSON object.
+ * Handles IPLD-style references `{ "/": "dxn:..." }` and `{ "@dxn": "dxn:..." }`.
+ */
+export const extractDxnsFromObject = (obj: unknown): URI.URI[] => {
+  const dxns: URI.URI[] = [];
+  const seen = new Set<string>();
+
+  const addDxn = (dxnStr: string) => {
+    if (!seen.has(dxnStr)) {
+      dxns.push(URI.make(dxnStr));
+      seen.add(dxnStr);
+    }
+  };
+
+  const traverse = (value: unknown): void => {
+    if (value === null || value === undefined) {
+      return;
+    }
+
+    if (typeof value === 'string') {
+      // Check if the string itself is a reference URI.
+      if (value.startsWith('echo:') || value.startsWith('dxn:')) {
+        addDxn(value);
+      } else if (value.startsWith('@echo:') || value.startsWith('@dxn:')) {
+        addDxn(value.slice(1));
+      }
+      // Also extract references from within the string.
+      const extracted = extractDxnFromString(value);
+      for (const dxn of extracted) {
+        addDxn(dxn);
+      }
+      return;
+    }
+
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        traverse(item);
+      }
+      return;
+    }
+
+    if (typeof value === 'object') {
+      const record = value as Record<string, unknown>;
+
+      // Check for IPLD-style reference: { "/": "echo:…" | "dxn:…" }
+      if ('/' in record && typeof record['/'] === 'string') {
+        const refStr = record['/'];
+        if (typeof refStr === 'string' && (refStr.startsWith('echo:') || refStr.startsWith('dxn:'))) {
+          addDxn(refStr);
+        }
+      }
+
+      // Check for self URI key: { "@uri": "echo:…" }
+      const selfUri = record['@uri'];
+      if (typeof selfUri === 'string' && (selfUri.startsWith('dxn:') || selfUri.startsWith('echo:'))) {
+        addDxn(selfUri);
+      }
+
+      // Check for reference blocks: { _tag: 'reference', reference: { uri: ... } }
+      if (record._tag === 'reference' && record.reference && typeof record.reference === 'object') {
+        const ref = record.reference as Record<string, unknown>;
+        const refUri = ref.uri;
+        if (typeof refUri === 'string' && (refUri.startsWith('echo:') || refUri.startsWith('dxn:'))) {
+          addDxn(refUri);
+        }
+      }
+
+      // Recursively traverse all properties.
+      for (const key of Object.keys(record)) {
+        traverse(record[key]);
+      }
+    }
+  };
+
+  traverse(obj);
+  return dxns;
+};
+
+/**
+ * Extracts the first DXN from a tool call input string (JSON).
+ */
+export const extractFirstDxnFromToolInput = (input: string): URI.URI | undefined => {
+  try {
+    const parsed = JSON.parse(input);
+    const dxns = extractDxnsFromObject(parsed);
+    return dxns[0];
+  } catch {
+    // If JSON parsing fails, try to extract from the raw string.
+    const dxns = extractDxnFromString(input);
+    return dxns[0];
+  }
+};
+
+/**
+ * Extracts the first DXN from a tool result string (JSON).
+ */
+export const extractFirstDxnFromToolResult = (result: string | undefined): URI.URI | undefined => {
+  if (!result) {
+    return undefined;
+  }
+
+  try {
+    const parsed = JSON.parse(result);
+    const dxns = extractDxnsFromObject(parsed);
+    return dxns[0];
+  } catch {
+    // If JSON parsing fails, try to extract from the raw string.
+    const dxns = extractDxnFromString(result);
+    return dxns[0];
+  }
+};

package/src/components/TracePanel/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './TracePanel.tsx';
+export * from './trace-filter.ts';
+export * from './useTraceMenu.ts';

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

@@ -0,0 +1,137 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import * as Process from '@dxos/compute/Process';
+import * as Trace from '@dxos/compute/Trace';
+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,
+  filterTraceMessages,
+  parseProcessEnvironments,
+  processEnvironment,
+  toggleProcessEnvironment,
+} from './trace-filter.ts';
+
+const SPACE_ID = SpaceId.random();
+const CONVERSATION = URI.make('eid:BA25QRC2FWNUGWENQZ26MK5W6C64ZQPTC:01J00000000000000000000000');
+
+describe('processEnvironment', () => {
+  test('an unscoped process is app-level', ({ expect }) => {
+    expect(processEnvironment(makeInfo('layout', {}))).toBe(ProcessEnvironment.App);
+  });
+
+  test('a space-scoped process is space-level', ({ expect }) => {
+    expect(processEnvironment(makeInfo('sync', { space: SPACE_ID }))).toBe(ProcessEnvironment.Space);
+  });
+
+  test('a conversation outranks its space', ({ expect }) => {
+    expect(processEnvironment(makeInfo('agent', { space: SPACE_ID, conversation: CONVERSATION }))).toBe(
+      ProcessEnvironment.Conversation,
+    );
+  });
+});
+
+describe('filterProcesses', () => {
+  const processes = [
+    makeInfo('layout', {}),
+    makeInfo('sync', { space: SPACE_ID }),
+    makeInfo('agent', { space: SPACE_ID, conversation: CONVERSATION }),
+  ];
+
+  test('keeps only the selected environments', ({ expect }) => {
+    const visible = filterProcesses(processes, [ProcessEnvironment.Conversation]);
+    expect(visible.map((process) => process.params.name)).toEqual(['agent']);
+  });
+
+  test('an empty selection hides everything', ({ expect }) => {
+    expect(filterProcesses(processes, [])).toEqual([]);
+  });
+
+  test('selecting every environment passes the list through unchanged', ({ expect }) => {
+    expect(filterProcesses(processes, ALL_PROCESS_ENVIRONMENTS)).toBe(processes);
+  });
+
+  test('the default selection hides app-level processes', ({ expect }) => {
+    const visible = filterProcesses(processes, DEFAULT_PROCESS_ENVIRONMENTS);
+    expect(visible.map((process) => process.params.name)).toEqual(['sync', 'agent']);
+  });
+});
+
+describe('toggleProcessEnvironment', () => {
+  test('adds in canonical order rather than at the end', ({ expect }) => {
+    expect(toggleProcessEnvironment([ProcessEnvironment.Conversation], ProcessEnvironment.App)).toEqual([
+      ProcessEnvironment.App,
+      ProcessEnvironment.Conversation,
+    ]);
+  });
+
+  test('removes a selected environment', ({ expect }) => {
+    expect(
+      toggleProcessEnvironment([ProcessEnvironment.App, ProcessEnvironment.Conversation], ProcessEnvironment.App),
+    ).toEqual([ProcessEnvironment.Conversation]);
+  });
+});
+
+describe('parseProcessEnvironments', () => {
+  test('unset settings fall back to the default selection', ({ expect }) => {
+    expect(parseProcessEnvironments(undefined)).toEqual(DEFAULT_PROCESS_ENVIRONMENTS);
+  });
+
+  test('an empty selection is preserved, not treated as unset', ({ expect }) => {
+    expect(parseProcessEnvironments([])).toEqual([]);
+  });
+
+  test('drops values outside the vocabulary and restores canonical order', ({ expect }) => {
+    expect(parseProcessEnvironments([ProcessEnvironment.Conversation, 'retired', ProcessEnvironment.App])).toEqual([
+      ProcessEnvironment.App,
+      ProcessEnvironment.Conversation,
+    ]);
+  });
+});
+
+const makeInfo = (name: string, environment: Process.Environment): Process.Info =>
+  makeProcess({ pid: Process.ID.make(name), name, state: Process.State.RUNNING, environment });
+
+describe('filterTraceMessages', () => {
+  const message = (pid: string, parentPid?: string): Trace.Message =>
+    Obj.make(Trace.Message, {
+      meta: { pid, ...(parentPid ? { parentPid } : {}) },
+      isEphemeral: false,
+      events: [{ type: 'test', timestamp: 0, data: {} }],
+    });
+
+  test('an empty selection is no filter', ({ expect }) => {
+    const messages = [message('a'), message('b')];
+    expect(filterTraceMessages(messages, [])).toBe(messages);
+  });
+
+  test("a selected process keeps its own messages and its descendants'", ({ expect }) => {
+    const messages = [message('agent'), message('tool', 'agent'), message('nested', 'tool'), message('other')];
+    expect(filterTraceMessages(messages, ['agent']).map((m) => m.meta.pid)).toEqual(['agent', 'tool', 'nested']);
+  });
+
+  test('several selected processes are unioned', ({ expect }) => {
+    const messages = [message('a'), message('b'), message('c')];
+    expect(filterTraceMessages(messages, ['a', 'c']).map((m) => m.meta.pid)).toEqual(['a', 'c']);
+  });
+
+  test('a message with no pid is dropped once anything is selected', ({ expect }) => {
+    const orphan = Obj.make(Trace.Message, { meta: {}, isEphemeral: false, events: [] });
+    expect(filterTraceMessages([orphan, message('a')], ['a']).map((m) => m.meta.pid)).toEqual(['a']);
+  });
+
+  test('a cyclic parent chain terminates', ({ expect }) => {
+    const messages = [message('a', 'b'), message('b', 'a')];
+    expect(filterTraceMessages(messages, ['z'])).toEqual([]);
+  });
+});

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

@@ -0,0 +1,120 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as Process from '@dxos/compute/Process';
+import type * as Trace from '@dxos/compute/Trace';
+
+/**
+ * What a running process is working on behalf of, as a single bucket.
+ *
+ * Bucketed from the inherited {@link Process.Environment}, so filtering keeps whole subtrees together.
+ */
+export const ProcessEnvironment = {
+  /** Not scoped to a space: layout, navigation, identity, settings, space lifecycle. */
+  App: 'app',
+  /** Scoped to a space, but not to a conversation within it. */
+  Space: 'space',
+  /** Serving a conversation: an agent's turn and every tool call it spawns. */
+  Conversation: 'conversation',
+} as const;
+
+export type ProcessEnvironment = (typeof ProcessEnvironment)[keyof typeof ProcessEnvironment];
+
+/** Every environment, in menu order — widening scope, so the filter reads the same on every trace. */
+export const ALL_PROCESS_ENVIRONMENTS: readonly ProcessEnvironment[] = [
+  ProcessEnvironment.App,
+  ProcessEnvironment.Space,
+  ProcessEnvironment.Conversation,
+];
+
+/** App-level processes start hidden: that bucket fires on every click, whatever the user is watching. */
+export const DEFAULT_PROCESS_ENVIRONMENTS: readonly ProcessEnvironment[] = [
+  ProcessEnvironment.Space,
+  ProcessEnvironment.Conversation,
+];
+
+const ENVIRONMENT_ICONS: Record<ProcessEnvironment, string> = {
+  [ProcessEnvironment.App]: 'ph--app-window--regular',
+  [ProcessEnvironment.Space]: 'ph--planet--regular',
+  [ProcessEnvironment.Conversation]: 'ph--chat-teardrop-text--regular',
+};
+
+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 => {
+  if (process.environment.conversation !== undefined) {
+    return ProcessEnvironment.Conversation;
+  }
+  if (process.environment.space !== undefined) {
+    return ProcessEnvironment.Space;
+  }
+  return ProcessEnvironment.App;
+};
+
+export const filterProcesses = (
+  processes: readonly Process.Info[],
+  selected: readonly ProcessEnvironment[],
+): readonly Process.Info[] => {
+  // Identity when nothing is excluded, so `ProcessTree`'s `React.memo` still holds.
+  if (selected.length === ALL_PROCESS_ENVIRONMENTS.length) {
+    return processes;
+  }
+  const selection = new Set(selected);
+  return processes.filter((process) => selection.has(processEnvironment(process)));
+};
+
+/** Toggles an environment, preserving the canonical order. */
+export const toggleProcessEnvironment = (
+  selected: readonly ProcessEnvironment[],
+  environment: ProcessEnvironment,
+): ProcessEnvironment[] =>
+  ALL_PROCESS_ENVIRONMENTS.filter((candidate) =>
+    candidate === environment ? !selected.includes(environment) : selected.includes(candidate),
+  );
+
+/**
+ * Narrows a persisted selection to the known environments, in canonical order.
+ *
+ * Settings outlive the vocabulary that wrote them; an unrecognized value would filter the panel to nothing.
+ */
+export const parseProcessEnvironments = (selected: readonly string[] | undefined): readonly ProcessEnvironment[] =>
+  selected === undefined
+    ? DEFAULT_PROCESS_ENVIRONMENTS
+    : ALL_PROCESS_ENVIRONMENTS.filter((environment) => selected.includes(environment));
+
+/**
+ * Narrows trace messages to the selected processes and their descendants: a tool call or sub-agent
+ * runs as a child of the process it serves, so its events are that process's work. An empty
+ * selection is no filter.
+ */
+export const filterTraceMessages = (
+  messages: readonly Trace.Message[],
+  selected: readonly string[],
+): readonly Trace.Message[] => {
+  if (selected.length === 0) {
+    return messages;
+  }
+  const parentByPid = new Map<string, string | undefined>();
+  for (const message of messages) {
+    if (message.meta.pid !== undefined) {
+      parentByPid.set(message.meta.pid, message.meta.parentPid);
+    }
+  }
+  const selection = new Set(selected);
+  const matches = new Map<string, boolean>();
+  const isSelected = (pid: string): boolean => {
+    const known = matches.get(pid);
+    if (known !== undefined) {
+      return known;
+    }
+    // Pinned before the walk so a cyclic parent chain (a corrupt trace) terminates.
+    matches.set(pid, false);
+    const parent = parentByPid.get(pid);
+    const result = selection.has(pid) || (parent !== undefined && isSelected(parent));
+    matches.set(pid, result);
+    return result;
+  };
+  return messages.filter((message) => message.meta.pid !== undefined && isSelected(message.meta.pid));
+};

package/src/components/TracePanel/useTraceMenu.ts

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback } from 'react';
+
+import { MenuBuilder, useMenuBuilder } from '@dxos/react-ui-menu';
+
+import { translationKey } from '../../translations.ts';
+
+import {
+  ALL_PROCESS_ENVIRONMENTS,
+  type ProcessEnvironment,
+  environmentIcon,
+  toggleProcessEnvironment,
+} from './trace-filter.ts';
+
+export type UseTraceMenuOptions = {
+  /** Process environments currently shown. */
+  selected: readonly ProcessEnvironment[];
+  onSelectedChange: (environments: ProcessEnvironment[]) => void;
+  /** How many processes are picked; the clear action shows only while there are some. */
+  selectionCount?: number;
+  onClearSelection?: () => void;
+};
+
+/**
+ * Environment filter menu for the trace panel's toolbar.
+ * The group collapses to a funnel trigger, so the panel's own rows keep the width.
+ */
+export const useTraceMenu = ({
+  selected,
+  onSelectedChange,
+  selectionCount = 0,
+  onClearSelection,
+}: UseTraceMenuOptions) => {
+  const handleToggle = useCallback(
+    (environment: ProcessEnvironment) => onSelectedChange(toggleProcessEnvironment(selected, environment)),
+    [selected, onSelectedChange],
+  );
+
+  return useMenuBuilder(
+    () =>
+      MenuBuilder.make()
+        .action(
+          'clearSelection',
+          {
+            label: ['trace-clear-selection.label', { ns: translationKey }],
+            icon: 'ph--selection-slash--regular',
+            iconOnly: true,
+            hidden: selectionCount === 0,
+            testId: 'tracePanel.clearSelection',
+          },
+          () => onClearSelection?.(),
+        )
+        .group(
+          'processEnvironments',
+          {
+            label: ['trace-filter.menu', { ns: translationKey }],
+            icon: 'ph--funnel--regular',
+            iconOnly: true,
+            variant: 'dropdownMenu',
+            selectCardinality: 'multiple',
+            value: [...selected],
+            testId: 'tracePanel.filter',
+          },
+          (group) => {
+            for (const environment of ALL_PROCESS_ENVIRONMENTS) {
+              group.action(
+                environment,
+                {
+                  label: [`trace-environment-${environment}.label`, { ns: translationKey }],
+                  icon: environmentIcon(environment),
+                  checked: selected.includes(environment),
+                },
+                () => handleToggle(environment),
+              );
+            }
+            group.separator('line');
+            group.action(
+              'all',
+              { label: ['trace-filter-all.label', { ns: translationKey }], icon: 'ph--list-checks--regular' },
+              () => onSelectedChange([...ALL_PROCESS_ENVIRONMENTS]),
+            );
+            group.action(
+              'none',
+              { label: ['trace-filter-none.label', { ns: translationKey }], icon: 'ph--prohibit--regular' },
+              () => onSelectedChange([]),
+            );
+          },
+        )
+        .build(),
+    [handleToggle, selected, onSelectedChange, selectionCount, onClearSelection],
+  );
+};

package/src/components/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Gantt/index.ts';
+export * from './ProcessTree/index.ts';
+export * from './Timeline/index.ts';
+export * from './TracePanel/index.ts';