@dxos/plugin-devtools 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/dx.config.ts

@@ -11,8 +11,8 @@ export default Config2.make({
     name: 'Devtools',
     author: 'DXOS',
     description: trim`
-      DevtoolsPlugin is the developer inspector for DXOS Composer. It adds a structured Devtools node
-      to the navigation graph — grouped into Client, HALO, ECHO, Mesh, and EDGE sub-sections —
+      DevtoolsPlugin is the developer inspector for DXOS Composer. It adds a structured DevTools tree
+      to the floating debug panel — grouped into Client, HALO, ECHO, Mesh, and EDGE sub-sections —
       exposing panel views for config, storage, logs, diagnostics, identity, devices, feeds,
       objects, schemas, automerge internals, network topology, EDGE workflows, and invocation
       traces, all driven by the @dxos/devtools component library.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-devtools",
-  "version": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
+  "version": "0.13.0",
   "description": "DXOS developer inspector plugin.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -10,19 +10,21 @@
   },
   "license": "FSL-1.1-Apache-2.0",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "imports": {
     "#capabilities": {
       "source": {
         "workerd": "./src/capabilities/gen/workerd.ts",
         "node": "./src/capabilities/gen/node.ts",
-        "default": "./src/capabilities/index.ts"
+        "tauri": "./src/capabilities/gen/tauri.ts",
+        "browser": "./src/capabilities/gen/browser.ts"
       },
       "types": "./dist/types/src/capabilities/index.d.ts",
       "workerd": "./dist/lib/capabilities.workerd.mjs",
       "node": "./dist/lib/capabilities.node.mjs",
-      "default": "./dist/lib/capabilities.mjs"
+      "tauri": "./dist/lib/capabilities.tauri.mjs",
+      "browser": "./dist/lib/capabilities.browser.mjs"
     },
     "#containers": {
       "source": "./src/containers/index.ts",
@@ -98,51 +100,53 @@
   ],
   "dependencies": {
     "@bufbuild/protobuf": "2.11.0",
-    "@dxos/app-framework": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/app-graph": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/app-toolkit": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/async": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/cli-util": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/client": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/client-services": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/compute": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/config": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/devtools": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/echo": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/effect": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/graph": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/keys": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/log": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/plugin-script": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/plugin-space": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/protocols": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/react-client": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/react-ui-introspect": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/react-ui-terminal": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/util": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/react-ui-table": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264"
+    "@dxos/app-framework": "0.13.0",
+    "@dxos/app-graph": "0.13.0",
+    "@dxos/app-toolkit": "0.13.0",
+    "@dxos/async": "0.13.0",
+    "@dxos/cli-util": "0.13.0",
+    "@dxos/client": "0.13.0",
+    "@dxos/compute": "0.13.0",
+    "@dxos/client-services": "0.13.0",
+    "@dxos/devtools": "0.13.0",
+    "@dxos/echo": "0.13.0",
+    "@dxos/config": "0.13.0",
+    "@dxos/echo-react": "0.13.0",
+    "@dxos/effect": "0.13.0",
+    "@dxos/graph": "0.13.0",
+    "@dxos/log": "0.13.0",
+    "@dxos/plugin-debug": "0.13.0",
+    "@dxos/keys": "0.13.0",
+    "@dxos/plugin-script": "0.13.0",
+    "@dxos/protocols": "0.13.0",
+    "@dxos/react-client": "0.13.0",
+    "@dxos/react-ui-table": "0.13.0",
+    "@dxos/react-ui-terminal": "0.13.0",
+    "@dxos/react-ui-introspect": "0.13.0",
+    "@dxos/plugin-space": "0.13.0",
+    "@dxos/util": "0.13.0"
   },
   "devDependencies": {
-    "@effect/atom-react": "4.0.0-rc.108",
-    "@storybook/react-vite": "^10.5.8",
+    "@effect/atom-react": "4.0.0",
+    "@storybook/react-vite": "^10.6.0",
     "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "effect": "4.0.0-rc.108",
+    "effect": "4.0.0",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "vite": "^8.2.1",
-    "@dxos/plugin-client": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/ui-theme": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/plugin-testing": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/react-ui": "0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264"
+    "vite": "^8.2.2",
+    "@dxos/plugin-client": "0.13.0",
+    "@dxos/react-ui": "0.13.0",
+    "@dxos/plugin-testing": "0.13.0",
+    "@dxos/ui-theme": "0.13.0"
   },
   "peerDependencies": {
-    "@effect/atom-react": "4.0.0-rc.108",
-    "effect": "4.0.0-rc.108",
+    "@effect/atom-react": "4.0.0",
+    "effect": "4.0.0",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/ui-theme": "^0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264",
-    "@dxos/react-ui": "^0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264"
+    "@dxos/react-ui": "^0.13.0",
+    "@dxos/ui-theme": "^0.13.0"
   },
   "publishConfig": {
     "access": "public"

package/src/capabilities/DevtoolsCards.tsx

@@ -0,0 +1,140 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Card surfaces whose data comes from a hook rather than the stack's `DevtoolsCardData`.
+
+import React, { useCallback, useMemo, useState } from 'react';
+
+import * as Hooks from '@dxos/app-framework/Hooks';
+import * as Surface from '@dxos/app-framework/Surface';
+import * as AppSurface from '@dxos/app-toolkit/AppSurface';
+import {
+  EdgeCard,
+  IndexerCard,
+  QueriesCard,
+  type Stats,
+  SurfaceProfilerCard,
+  type SurfaceProfilerStats,
+  SwarmTraceCard,
+  SyncCard,
+  useEdgeStatus,
+  useIndexerRows,
+  useQueryMetrics,
+  useSwarmTrace,
+  useSyncRows,
+} from '@dxos/devtools';
+import * as DebugOperation from '@dxos/plugin-debug/DebugOperation';
+import { SpaceState, useSpaces } from '@dxos/react-client/echo';
+
+import { Devtools } from '#types';
+
+/** Surfaces hosting the debug tooling; they and everything rendered inside them are not listed. */
+const DEBUG_HOSTS = new Set(['devtoolsOverview', 'debugDrawer']);
+
+/** Whether a mounted surface is part of the debug tooling rather than the app being inspected. */
+export const isDebugSurface = ({ id, role, ancestors }: Surface.Mounted): boolean =>
+  role.endsWith('.devtoolsOverview') ||
+  (id !== undefined && DEBUG_HOSTS.has(id)) ||
+  ancestors.some((ancestor) => DEBUG_HOSTS.has(ancestor));
+
+/** Data the stats stack passes to every `AppSurface.DevtoolsOverview` card. */
+export type DevtoolsCardData = {
+  stats: Stats;
+  surfaceProfilerStats: SurfaceProfilerStats[];
+  onClearSurfaceProfiler?: () => void;
+};
+
+export const isDevtoolsCardData = (data: unknown): data is DevtoolsCardData =>
+  typeof data === 'object' && data !== null && 'stats' in data && 'surfaceProfilerStats' in data;
+
+/**
+ * The card role narrowed to the stack's data. `Surface.makeFilter` types its data by the token, so
+ * the binding is built directly, as `AppSurface.subject` does.
+ */
+export const devtoolsCard: Surface.Filter<DevtoolsCardData> = {
+  bindings: [{ role: AppSurface.DevtoolsOverview.role, guard: isDevtoolsCardData }],
+};
+
+export type EdgeCardSurfaceProps = Pick<DevtoolsCardData, 'stats'>;
+
+export const EdgeCardSurface = ({ stats }: EdgeCardSurfaceProps) => {
+  const { status, refresh, copy } = useEdgeStatus();
+  const spaces = useSpaces({ all: true });
+  const spaceNames = useMemo(() => {
+    const names: Record<string, string> = {};
+    for (const space of spaces) {
+      const name = space.state.get() === SpaceState.SPACE_READY ? space.properties.name : undefined;
+      if (typeof name === 'string') {
+        names[space.id] = name;
+      }
+    }
+    return names;
+  }, [spaces]);
+  return <EdgeCard edge={stats.edge} status={status} spaceNames={spaceNames} onRefresh={refresh} onCopy={copy} />;
+};
+
+export type SurfaceProfilerCardSurfaceProps = Pick<DevtoolsCardData, 'surfaceProfilerStats' | 'onClearSurfaceProfiler'>;
+
+/** The profiler card with the surface highlight overlay's flag, which lives on `window`, mirrored in state. */
+export const SurfaceProfilerCardSurface = ({
+  surfaceProfilerStats,
+  onClearSurfaceProfiler,
+}: SurfaceProfilerCardSurfaceProps) => {
+  const [debug, setDebug] = useState(() => Surface.isDebugEnabled());
+  const handleDebugChange = useCallback((enabled: boolean) => {
+    Surface.setDebug(enabled);
+    setDebug(enabled);
+  }, []);
+
+  // The selected role's surfaces with their data and dispatch metrics, following mounts and unmounts.
+  const selected = Surface.useSelected();
+  const mounted = Surface.useMounted();
+  const detail = useMemo(() => {
+    if (!selected) {
+      return undefined;
+    }
+    const metrics = new Map(Surface.getMetrics().map((metric) => [metric.id, metric]));
+    return mounted
+      .filter((surface) => surface.role === selected && !isDebugSurface(surface))
+      .map(({ id, role, data }) => ({ id, data, metric: metrics.get(`surface/${id}/${role}`) }));
+  }, [selected, mounted]);
+
+  return (
+    <SurfaceProfilerCard
+      stats={surfaceProfilerStats}
+      debug={debug}
+      onDebugChange={handleDebugChange}
+      onClear={onClearSurfaceProfiler}
+      selected={selected}
+      onSelect={Surface.select}
+      detail={detail}
+    />
+  );
+};
+
+export const SwarmTraceCardSurface = () => {
+  const { messages, spaceCount, available, clear } = useSwarmTrace();
+  return <SwarmTraceCard messages={messages} spaceCount={spaceCount} available={available} onClear={clear} />;
+};
+
+export const SyncCardSurface = () => {
+  const { spaces, copy } = useSyncRows();
+  return <SyncCard spaces={spaces} onCopy={copy} />;
+};
+
+export const IndexerCardSurface = () => {
+  const { spaces, refresh, copy } = useIndexerRows();
+  return <IndexerCard spaces={spaces} onRefresh={refresh} onCopy={copy} />;
+};
+
+/** The slowest queries; the header button shows every query on the devtools Queries page. */
+export const QueriesCardSurface = () => {
+  const { queries } = useQueryMetrics();
+  const { invokePromise } = Hooks.useOperationInvoker();
+  const handleOpen = useCallback(
+    () => void invokePromise(DebugOperation.OpenPage, { nodeId: Devtools.getNodePath(Devtools.Echo.Queries) }),
+    [invokePromise],
+  );
+  return <QueriesCard queries={queries} onOpen={handleOpen} />;
+};

package/src/capabilities/DevtoolsSurfaces.tsx

@@ -6,13 +6,15 @@
 
 import React, { type ComponentType, useCallback } from 'react';
 
-import { useOperationInvoker } from '@dxos/app-framework/ui';
+import * as Hooks from '@dxos/app-framework/Hooks';
 import * as GraphPath from '@dxos/app-toolkit/GraphPath';
+import * as ToolkitHooks from '@dxos/app-toolkit/Hooks';
 import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
-import { useActiveSpace } from '@dxos/app-toolkit/ui';
-import { InvocationTraceContainer, SpaceInfoPanel, SpaceListPanel, TestingPanel } from '@dxos/devtools';
+import { InvocationTraceContainer, SpaceInfoArticle, SpaceListArticle, TestingArticle } from '@dxos/devtools';
 import { Feed } from '@dxos/echo';
+import { useResolveRef } from '@dxos/echo-react';
 import { log } from '@dxos/log';
+import * as DebugSurface from '@dxos/plugin-debug/DebugSurface';
 import * as ScriptOperation from '@dxos/plugin-script/ScriptOperation';
 import * as SpaceOperation from '@dxos/plugin-space/SpaceOperation';
 import { type Space } from '@dxos/react-client/echo';
@@ -20,66 +22,58 @@ import { type Space } from '@dxos/react-client/echo';
 import { Devtools } from '#types';
 
 export type ActiveSpacePanelProps = {
-  /** Stable module-level panel component; the surface passes it through its `props` mapper. */
-  Panel: ComponentType<{ space: Space }>;
+  role?: string;
+  /** Stable module-level article component; the surface passes it through its `props` mapper. */
+  Panel: ComponentType<{ role?: string; space: Space }>;
 };
 
 /**
  * Most devtools panels take the active space and render nothing without one. A mapper cannot read
  * the active space (it is a hook) nor decline to render, so they share this wrapper.
  */
-export const ActiveSpacePanel = ({ Panel }: ActiveSpacePanelProps) => {
-  const space = useActiveSpace();
+export const ActiveSpacePanel = ({ role, Panel }: ActiveSpacePanelProps) => {
+  const space = ToolkitHooks.useActiveSpace();
 
-  return space ? <Panel space={space} /> : null;
+  return space ? <Panel role={role} space={space} /> : null;
 };
 
-export const SpaceListSurface = () => {
-  const { invokePromise } = useOperationInvoker();
-  const handleSelect = useCallback(
-    () => invokePromise(LayoutOperation.Open, { subject: [Devtools.Echo.Space] }),
-    [invokePromise],
-  );
+export type NavigableSurfaceProps = {
+  role?: string;
+  onNavigate: DebugSurface.PageData['onNavigate'];
+};
 
-  return <SpaceListPanel onSelect={handleSelect} />;
+/** The space list; selecting a space shows its page in the debug panel. */
+export const SpaceListSurface = ({ role, onNavigate }: NavigableSurfaceProps) => {
+  const handleSelect = useCallback(() => onNavigate(Devtools.getNodePath(Devtools.Echo.Space)), [onNavigate]);
+
+  return <SpaceListArticle role={role} onSelect={handleSelect} />;
 };
 
-export const SpaceInfoSurface = () => {
-  const space = useActiveSpace();
-  const { invokePromise } = useOperationInvoker();
-  const handleSelect = useCallback(
-    () => invokePromise(LayoutOperation.Open, { subject: [Devtools.Echo.Feeds] }),
-    [invokePromise],
-  );
+/** The active space; selecting a feed or pipeline shows the feeds page in the debug panel. */
+export const SpaceInfoSurface = ({ role, onNavigate }: NavigableSurfaceProps) => {
+  const space = ToolkitHooks.useActiveSpace();
+  const handleSelect = useCallback(() => onNavigate(Devtools.getNodePath(Devtools.Echo.Feeds)), [onNavigate]);
   if (!space) {
     return null;
   }
 
-  return <SpaceInfoPanel space={space} onSelectFeed={handleSelect} onSelectPipeline={handleSelect} />;
+  return <SpaceInfoArticle role={role} space={space} onSelectFeed={handleSelect} onSelectPipeline={handleSelect} />;
 };
 
-export const EdgeTracesSurface = () => {
-  const space = useActiveSpace();
+export const EdgeTracesSurface = ({ role }: { role?: string }) => {
+  const space = ToolkitHooks.useActiveSpace();
+  const feed = useResolveRef(space?.properties.invocationTraceFeed);
   if (!space) {
     return null;
   }
 
-  const feed = space.properties.invocationTraceFeed?.target;
   const feedDXN = feed ? Feed.getFeedUri(feed) : undefined;
 
-  return <InvocationTraceContainer db={space.db} feedDXN={feedDXN} detailAxis='block' />;
+  return <InvocationTraceContainer role={role} db={space.db} feedDXN={feedDXN} detailAxis='block' />;
 };
 
-export const EdgeTestingSurface = () => {
-  const { invokePromise } = useOperationInvoker();
-  const onSpaceCreate = useCallback(
-    async (space: Space) => {
-      await space.waitUntilReady();
-      await invokePromise(SpaceOperation.Migrate, { space });
-      await space.db.flush();
-    },
-    [invokePromise],
-  );
+export const EdgeTestingSurface = ({ role }: { role?: string }) => {
+  const { invokePromise } = Hooks.useOperationInvoker();
   const onScriptPluginOpen = useCallback(
     async (space: Space) => {
       await space.waitUntilReady();
@@ -101,5 +95,5 @@ export const EdgeTestingSurface = () => {
     [invokePromise],
   );
 
-  return <TestingPanel onSpaceCreate={onSpaceCreate} onScriptPluginOpen={onScriptPluginOpen} />;
+  return <TestingArticle role={role} onScriptPluginOpen={onScriptPluginOpen} />;
 };

package/src/capabilities/app-graph-builder.test.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Atom from 'effect/reactivity/Atom';
+import { describe, test } from 'vitest';
+
+import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
+import * as PathResolution from '@dxos/app-graph/PathResolution';
+import { setupGraphBuilder } from '@dxos/app-graph/testing';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as GraphPath from '@dxos/app-toolkit/GraphPath';
+import * as EffectEx from '@dxos/effect/EffectEx';
+import * as GraphNode from '@dxos/graph/GraphNode';
+import * as GraphNodeMatcher from '@dxos/graph/GraphNodeMatcher';
+
+import { Devtools } from '#types';
+
+import { createDevtoolsExtension } from './app-graph-builder.ts';
+
+describe('devtools graph extension', () => {
+  const setup = async () => {
+    // Stand-in for plugin-debug's root extension: root -> hidden debug category.
+    const rootExtensions = await EffectEx.runPromise(
+      AppGraphBuilder.createExtension({
+        id: 'testRoot',
+        match: GraphNodeMatcher.whenRoot,
+        connector: () =>
+          Effect.succeed([
+            {
+              id: GraphPath.GroupSegments.debug,
+              type: GraphPath.GroupTypes.debug,
+              data: null,
+              properties: { disposition: 'hidden' },
+            },
+          ]),
+      }),
+    );
+    const devtoolsExtensions = await EffectEx.runPromise(
+      createDevtoolsExtension(Atom.make<AppCapabilities.AppGraph[]>([])),
+    );
+    const context = setupGraphBuilder({ extensions: [...rootExtensions, ...devtoolsExtensions] });
+    const debugRootId = `${GraphNode.RootId}/${GraphPath.GroupSegments.debug}`;
+    const devtoolsNodeId = GraphNode.qualifyId(debugRootId, Devtools.nodeId(Devtools.id));
+    await context.expand(GraphNode.RootId);
+    await context.expand(debugRootId);
+    await context.expand(devtoolsNodeId);
+
+    return { ...context, devtoolsNodeId };
+  };
+
+  test('the devtools tree hangs off the debug category', async ({ expect }) => {
+    const { getConnections, devtoolsNodeId } = await setup();
+    const ids = getConnections(devtoolsNodeId).map((node) => node.id);
+    expect(ids).toContain(GraphNode.qualifyId(devtoolsNodeId, Devtools.nodeId(Devtools.AppGraph)));
+    expect(ids).toContain(GraphNode.qualifyId(devtoolsNodeId, Devtools.nodeId(Devtools.Client.id)));
+  });
+
+  test('getNodePath names the node the tree builds', async ({ expect }) => {
+    const { expand, getNode, devtoolsNodeId } = await setup();
+    expect(Devtools.getNodePath(Devtools.id)).toBe(devtoolsNodeId);
+    await expand(Devtools.getNodePath(Devtools.Echo.id));
+    for (const id of [Devtools.AppGraph, Devtools.Echo.id, Devtools.Echo.Space, Devtools.Echo.Feeds]) {
+      expect(getNode(Devtools.getNodePath(id))).not.toBeNull();
+    }
+  });
+
+  test('devtools pages have no URL representation', async ({ expect }) => {
+    const { builder, devtoolsNodeId } = await setup();
+    const pageId = GraphNode.qualifyId(devtoolsNodeId, Devtools.nodeId(Devtools.AppGraph));
+    expect(Option.isNone(PathResolution.representNode(builder, pageId))).toBe(true);
+  });
+});