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

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

@@ -12,48 +12,99 @@ import * as AppNode from '@dxos/app-toolkit/AppNode';
 import * as AppNodeMatcher from '@dxos/app-toolkit/AppNodeMatcher';
 import * as GraphPath from '@dxos/app-toolkit/GraphPath';
 import * as GraphNodeMatcher from '@dxos/graph/GraphNodeMatcher';
-import { type Space } from '@dxos/react-client/echo';
-import { Position } from '@dxos/util';
+import * as Position from '@dxos/util/Position';
 
 import { meta } from '#meta';
 import { DebugNodes } from '#types';
 
-export default Capability.makeModule(
-  Effect.fnUntraced(function* () {
-    const extensions = yield* Effect.all([
-      // Top-level Debug node (sibling of DevTools under SYSTEM); only present when a space is active.
-      AppGraphBuilder.createExtension({
-        id: 'debug',
-        match: AppNodeMatcher.whenNavTreeGroup(GraphPath.GroupTypes.system),
-        connector: (space: Space) =>
-          Effect.succeed([
+/** The hidden category every developer tool hangs off: a root child the main navtree filters out. */
+export const createDebugRootExtension = () =>
+  AppGraphBuilder.createExtension({
+    id: 'debugRoot',
+    match: GraphNodeMatcher.whenRoot,
+    connector: () =>
+      Effect.succeed([
+        AppGraphNode.make({
+          id: GraphPath.GroupSegments.debug,
+          type: GraphPath.GroupTypes.debug,
+          data: null,
+          properties: {
+            label: ['debug-panel.title', { ns: meta.profile.key }],
+            icon: 'ph--bug--regular',
+            disposition: 'hidden',
+            draggable: false,
+            droppable: false,
+          },
+        }),
+      ]),
+  });
+
+/** The Debug node: the console and log viewer first (what the panel opened on as tabs), then the generator. */
+export const createDebugExtension = () =>
+  AppGraphBuilder.createExtension({
+    id: 'debug',
+    match: AppNodeMatcher.whenDebugGroup,
+    connector: () =>
+      Effect.succeed([
+        AppGraphNode.make({
+          id: DebugNodes.nodeId(DebugNodes.id),
+          data: null,
+          type: DebugNodes.id,
+          properties: {
+            label: ['debug.label', { ns: meta.profile.key }],
+            icon: 'ph--bug--regular',
+            // Before DevTools (10), whichever plugin registers first: the panel's own pages lead the tree.
+            position: 0,
+          },
+          nodes: [
             AppGraphNode.make({
-              id: DebugNodes.nodeId(DebugNodes.id),
-              data: null,
-              type: DebugNodes.id,
+              id: DebugNodes.nodeId(DebugNodes.Console),
+              type: DebugNodes.Console,
+              data: DebugNodes.Console,
               properties: {
-                label: ['debug.label', { ns: meta.profile.key }],
-                icon: 'ph--bug--regular',
-                position: Position.last,
+                label: ['console.tab.label', { ns: meta.profile.key }],
+                icon: 'ph--terminal-window--regular',
+                // Explicit (not Position.first): -Infinity + 1 collapses back to -Infinity, tying with logs.
+                position: 0,
               },
-              nodes: [
-                AppGraphNode.make({
-                  id: DebugNodes.nodeId(DebugNodes.SpaceType),
-                  type: DebugNodes.SpaceType,
-                  data: { space, type: DebugNodes.SpaceType },
-                  properties: {
-                    label: ['generate-objects.label', { ns: meta.profile.key }],
-                    icon: 'ph--dice-five--regular',
-                  },
-                }),
-              ],
             }),
-          ]),
-      }),
+            AppGraphNode.make({
+              id: DebugNodes.nodeId(DebugNodes.Logs),
+              type: DebugNodes.Logs,
+              data: DebugNodes.Logs,
+              properties: {
+                label: ['logs.tab.label', { ns: meta.profile.key }],
+                icon: 'ph--list-bullets--regular',
+                position: 1,
+              },
+            }),
+            AppGraphNode.make({
+              id: DebugNodes.nodeId(DebugNodes.SpaceType),
+              type: DebugNodes.SpaceType,
+              data: DebugNodes.SpaceType,
+              properties: {
+                label: ['generate-objects.label', { ns: meta.profile.key }],
+                icon: 'ph--dice-five--regular',
+                position: 2,
+              },
+            }),
+          ],
+        }),
+      ]),
+  });
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const extensions = yield* Effect.all([
+      // The hidden root/debug category.
+      createDebugRootExtension(),
 
+      // The Debug node, under the debug category: the panel's own pages, then the generator.
+      createDebugExtension(),
       // Debug object companion.
       AppGraphBuilder.createExtension({
         id: 'debugObject',
+        relation: AppNode.companion,
         match: AppNodeMatcher.whenEchoObject,
         connector: () =>
           Effect.succeed([
@@ -70,6 +121,7 @@ export default Capability.makeModule(
       // Object explorer deck companion.
       AppGraphBuilder.createExtension({
         id: 'spaceObjects',
+        relation: AppNode.companion,
         match: GraphNodeMatcher.whenRoot,
         connector: () =>
           Effect.succeed([
@@ -79,22 +131,7 @@ export default Capability.makeModule(
               icon: 'ph--cube--regular',
               data: 'space-objects' as const,
               position: Position.last,
-            }),
-          ]),
-      }),
-
-      // Log panel deck companion.
-      AppGraphBuilder.createExtension({
-        id: 'logs',
-        match: GraphNodeMatcher.whenRoot,
-        connector: () =>
-          Effect.succeed([
-            AppNode.makeDeckCompanion({
-              id: 'logs',
-              label: ['logs.label', { ns: meta.profile.key }],
-              icon: 'ph--list-magnifying-glass--regular',
-              data: 'logs' as const,
-              position: Position.last,
+              mount: 'open',
             }),
           ]),
       }),

package/src/capabilities/gen/browser.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// GENERATED by dx-plugin — do not edit. Sliced from ../index.ts for the 'browser' condition.
+
+import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as AppCapability from '@dxos/app-toolkit/AppCapability';
+import * as MarkdownCapabilities from '@dxos/plugin-markdown/MarkdownCapabilities';
+
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { Debug, DebugEvents } from '#types';
+
+import pluginSpec from '../../../PLUGIN.mdl?raw';
+
+export const AppGraphBuilder = AppCapability.appGraphBuilder(() => import('../app-graph-builder.ts'), {
+  environments: ['browser', 'node', 'tauri'],
+});
+
+export const ReactSurface = AppCapability.surface(() => import('../react-surface.ts'), {
+  roles: [
+    'org.dxos.plugin.debug.surface.page',
+    'org.dxos.plugin.debug.surface.stats',
+    'org.dxos.role.article',
+    'org.dxos.role.deckCompanion.spaceObjects',
+    'org.dxos.role.devtoolsOverview',
+    'org.dxos.role.drawer',
+    'org.dxos.role.section',
+    'org.dxos.role.statusIndicator',
+  ],
+  requires: [Capabilities.AtomRegistry, Debug.DebugCapabilities.Settings, AppCapabilities.FileUploader],
+  props: ({ logStore }: Debug.DebugPluginOptions) => ({ logStore }),
+});
+
+export const DebugSettings = AppCapability.settings(() => import('../settings.ts'), {
+  activatesOn: ActivationEvents.Idle,
+  provides: [Debug.DebugCapabilities.Settings],
+  environments: ['browser', 'node', 'tauri'],
+});
+
+export const GraphRetention = Capability.lazyModule(
+  'GraphRetention',
+  { provides: [AppCapabilities.AppGraphRetention] },
+  () => import('../graph-retention.ts'),
+);
+
+export const StatsPanel = Capability.lazyModule(
+  'StatsPanel',
+  {
+    requires: [Capabilities.AtomRegistry],
+    provides: [AppCapabilities.StatsPanel],
+    props: ({ persistStats }: Debug.DebugPluginOptions) => ({ persist: persistStats ?? true }),
+    activatesOn: DebugEvents.Start,
+  },
+  () => import('../stats-panel.ts'),
+);
+
+export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler.ts'));
+
+export const MarkdownMenu = Capability.lazyModule(
+  'MarkdownMenu',
+  { provides: [MarkdownCapabilities.MenuExtension], activatesOn: DebugEvents.Start },
+  () => import('../markdown-menu.ts'),
+);
+
+export const SpaceTemplates = AppCapability.spaceTemplates(() => import('../space-templates.ts'));
+
+export const LogRecording = Capability.lazyModule(
+  'LogRecording',
+  { provides: [], activatesOn: DebugEvents.Start },
+  () => import('../log-recording.ts'),
+);
+
+export const Translations = AppCapability.translations(translations);
+
+export const PluginAsset = AppCapability.pluginAsset({
+  pluginId: meta.profile.key,
+  path: 'PLUGIN.mdl',
+  content: pluginSpec,
+  mimeType: 'application/x-mdl',
+});

package/src/capabilities/gen/node.ts

@@ -14,16 +14,22 @@ import * as MarkdownCapabilities from '@dxos/plugin-markdown/MarkdownCapabilitie
 import { translations } from '#translations';
 import { Debug, DebugEvents } from '#types';
 
-export const AppGraphBuilder = AppCapability.appGraphBuilder(() => import('../app-graph-builder'), {
-  environments: ['node'],
+export const AppGraphBuilder = AppCapability.appGraphBuilder(() => import('../app-graph-builder.ts'), {
+  environments: ['browser', 'node', 'tauri'],
 });
 
-export const DebugSettings = AppCapability.settings(() => import('../settings'), {
+export const DebugSettings = AppCapability.settings(() => import('../settings.ts'), {
   activatesOn: ActivationEvents.Idle,
   provides: [Debug.DebugCapabilities.Settings],
-  environments: ['node'],
+  environments: ['browser', 'node', 'tauri'],
 });
 
+export const GraphRetention = Capability.lazyModule(
+  'GraphRetention',
+  { provides: [AppCapabilities.AppGraphRetention] },
+  () => import('../graph-retention.ts'),
+);
+
 export const StatsPanel = Capability.lazyModule(
   'StatsPanel',
   {
@@ -32,24 +38,25 @@ export const StatsPanel = Capability.lazyModule(
     props: ({ persistStats }: Debug.DebugPluginOptions) => ({ persist: persistStats ?? true }),
     activatesOn: DebugEvents.Start,
   },
-  () => import('../stats-panel'),
+  () => import('../stats-panel.ts'),
 );
 
-export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler'));
+export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler.ts'));
 
 export const MarkdownMenu = Capability.lazyModule(
   'MarkdownMenu',
   { provides: [MarkdownCapabilities.MenuExtension], activatesOn: DebugEvents.Start },
-  () => import('../markdown-menu'),
+  () => import('../markdown-menu.ts'),
 );
 
 export const LogRecording = Capability.lazyModule(
   'LogRecording',
   { provides: [], activatesOn: DebugEvents.Start },
-  () => import('../log-recording'),
+  () => import('../log-recording.ts'),
 );
 
 export const Translations = AppCapability.translations(translations);
 
 export const PluginAsset = undefined;
 export const ReactSurface = undefined;
+export const SpaceTemplates = undefined;

package/src/capabilities/gen/tauri.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// GENERATED by dx-plugin — do not edit. Sliced from ../index.ts for the 'tauri' condition.
+
+import * as ActivationEvents from '@dxos/app-framework/ActivationEvents';
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+import * as AppCapability from '@dxos/app-toolkit/AppCapability';
+import * as MarkdownCapabilities from '@dxos/plugin-markdown/MarkdownCapabilities';
+
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { Debug, DebugEvents } from '#types';
+
+import pluginSpec from '../../../PLUGIN.mdl?raw';
+
+export const AppGraphBuilder = AppCapability.appGraphBuilder(() => import('../app-graph-builder.ts'), {
+  environments: ['browser', 'node', 'tauri'],
+});
+
+export const ReactSurface = AppCapability.surface(() => import('../react-surface.ts'), {
+  roles: [
+    'org.dxos.plugin.debug.surface.page',
+    'org.dxos.plugin.debug.surface.stats',
+    'org.dxos.role.article',
+    'org.dxos.role.deckCompanion.spaceObjects',
+    'org.dxos.role.devtoolsOverview',
+    'org.dxos.role.drawer',
+    'org.dxos.role.section',
+    'org.dxos.role.statusIndicator',
+  ],
+  requires: [Capabilities.AtomRegistry, Debug.DebugCapabilities.Settings, AppCapabilities.FileUploader],
+  props: ({ logStore }: Debug.DebugPluginOptions) => ({ logStore }),
+});
+
+export const DebugSettings = AppCapability.settings(() => import('../settings.ts'), {
+  activatesOn: ActivationEvents.Idle,
+  provides: [Debug.DebugCapabilities.Settings],
+  environments: ['browser', 'node', 'tauri'],
+});
+
+export const GraphRetention = Capability.lazyModule(
+  'GraphRetention',
+  { provides: [AppCapabilities.AppGraphRetention] },
+  () => import('../graph-retention.ts'),
+);
+
+export const StatsPanel = Capability.lazyModule(
+  'StatsPanel',
+  {
+    requires: [Capabilities.AtomRegistry],
+    provides: [AppCapabilities.StatsPanel],
+    props: ({ persistStats }: Debug.DebugPluginOptions) => ({ persist: persistStats ?? true }),
+    activatesOn: DebugEvents.Start,
+  },
+  () => import('../stats-panel.ts'),
+);
+
+export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler.ts'));
+
+export const MarkdownMenu = Capability.lazyModule(
+  'MarkdownMenu',
+  { provides: [MarkdownCapabilities.MenuExtension], activatesOn: DebugEvents.Start },
+  () => import('../markdown-menu.ts'),
+);
+
+export const SpaceTemplates = AppCapability.spaceTemplates(() => import('../space-templates.ts'));
+
+export const LogRecording = Capability.lazyModule(
+  'LogRecording',
+  { provides: [], activatesOn: DebugEvents.Start },
+  () => import('../log-recording.ts'),
+);
+
+export const Translations = AppCapability.translations(translations);
+
+export const PluginAsset = AppCapability.pluginAsset({
+  pluginId: meta.profile.key,
+  path: 'PLUGIN.mdl',
+  content: pluginSpec,
+  mimeType: 'application/x-mdl',
+});

package/src/capabilities/gen/workerd.ts

@@ -13,6 +13,12 @@ import * as MarkdownCapabilities from '@dxos/plugin-markdown/MarkdownCapabilitie
 import { translations } from '#translations';
 import { Debug, DebugEvents } from '#types';
 
+export const GraphRetention = Capability.lazyModule(
+  'GraphRetention',
+  { provides: [AppCapabilities.AppGraphRetention] },
+  () => import('../graph-retention.ts'),
+);
+
 export const StatsPanel = Capability.lazyModule(
   'StatsPanel',
   {
@@ -21,21 +27,21 @@ export const StatsPanel = Capability.lazyModule(
     props: ({ persistStats }: Debug.DebugPluginOptions) => ({ persist: persistStats ?? true }),
     activatesOn: DebugEvents.Start,
   },
-  () => import('../stats-panel'),
+  () => import('../stats-panel.ts'),
 );
 
-export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler'));
+export const OperationHandler = AppCapability.operationHandler(() => import('../operation-handler.ts'));
 
 export const MarkdownMenu = Capability.lazyModule(
   'MarkdownMenu',
   { provides: [MarkdownCapabilities.MenuExtension], activatesOn: DebugEvents.Start },
-  () => import('../markdown-menu'),
+  () => import('../markdown-menu.ts'),
 );
 
 export const LogRecording = Capability.lazyModule(
   'LogRecording',
   { provides: [], activatesOn: DebugEvents.Start },
-  () => import('../log-recording'),
+  () => import('../log-recording.ts'),
 );
 
 export const Translations = AppCapability.translations(translations);
@@ -44,3 +50,4 @@ export const AppGraphBuilder = undefined;
 export const DebugSettings = undefined;
 export const PluginAsset = undefined;
 export const ReactSurface = undefined;
+export const SpaceTemplates = undefined;

package/src/capabilities/graph-retention.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Atom from 'effect/reactivity/Atom';
+
+import * as Capability from '@dxos/app-framework/Capability';
+import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
+
+import { DebugNodes } from '#types';
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    // Neither host of the panel — the deck's drawer nor the floating window — owns this subtree.
+    // TODO(wittjosiah): Release it when no host is showing it.
+    const retention: AppCapabilities.AppGraphRetention = {
+      retained: Atom.make([{ id: DebugNodes.DEBUG_ROOT_ID }]),
+    };
+
+    return Capability.contribute(AppCapabilities.AppGraphRetention, retention);
+  }),
+);

package/src/capabilities/index.ts

@@ -16,26 +16,33 @@ import { Debug, DebugEvents } from '#types';
 // eslint-disable-next-line import/no-relative-packages
 import pluginSpec from '../../PLUGIN.mdl?raw';
 
-export const AppGraphBuilder = AppCapability.appGraphBuilder(() => import('./app-graph-builder'), {
-  environments: ['node'],
+export const AppGraphBuilder = AppCapability.appGraphBuilder(() => import('./app-graph-builder.ts'), {
+  environments: ['browser', 'node', 'tauri'],
 });
-export const ReactSurface = AppCapability.surface(() => import('./react-surface'), {
+export const ReactSurface = AppCapability.surface(() => import('./react-surface.ts'), {
   roles: [
+    'org.dxos.plugin.debug.surface.page',
     'org.dxos.plugin.debug.surface.stats',
     'org.dxos.role.article',
-    'org.dxos.role.deckCompanion.logs',
     'org.dxos.role.deckCompanion.spaceObjects',
+    'org.dxos.role.devtoolsOverview',
+    'org.dxos.role.drawer',
     'org.dxos.role.section',
     'org.dxos.role.statusIndicator',
   ],
   requires: [Capabilities.AtomRegistry, Debug.DebugCapabilities.Settings, AppCapabilities.FileUploader],
   props: ({ logStore }: Debug.DebugPluginOptions) => ({ logStore }),
 });
-export const DebugSettings = AppCapability.settings(() => import('./settings'), {
+export const DebugSettings = AppCapability.settings(() => import('./settings.ts'), {
   activatesOn: ActivationEvents.Idle,
   provides: [Debug.DebugCapabilities.Settings],
-  environments: ['node'],
+  environments: ['browser', 'node', 'tauri'],
 });
+export const GraphRetention = Capability.lazyModule(
+  'GraphRetention',
+  { provides: [AppCapabilities.AppGraphRetention] },
+  () => import('./graph-retention.ts'),
+);
 export const StatsPanel = Capability.lazyModule(
   'StatsPanel',
   {
@@ -44,18 +51,19 @@ export const StatsPanel = Capability.lazyModule(
     props: ({ persistStats }: Debug.DebugPluginOptions) => ({ persist: persistStats ?? true }),
     activatesOn: DebugEvents.Start,
   },
-  () => import('./stats-panel'),
+  () => import('./stats-panel.ts'),
 );
-export const OperationHandler = AppCapability.operationHandler(() => import('./operation-handler'));
+export const OperationHandler = AppCapability.operationHandler(() => import('./operation-handler.ts'));
 export const MarkdownMenu = Capability.lazyModule(
   'MarkdownMenu',
   { provides: [MarkdownCapabilities.MenuExtension], activatesOn: DebugEvents.Start },
-  () => import('./markdown-menu'),
+  () => import('./markdown-menu.ts'),
 );
+export const SpaceTemplates = AppCapability.spaceTemplates(() => import('./space-templates.ts'));
 export const LogRecording = Capability.lazyModule(
   'LogRecording',
   { provides: [], activatesOn: DebugEvents.Start },
-  () => import('./log-recording'),
+  () => import('./log-recording.ts'),
 );
 export const Translations = AppCapability.translations(translations);
 export const PluginAsset = AppCapability.pluginAsset({

package/src/capabilities/log-recording.ts

@@ -5,6 +5,7 @@
 import * as Effect from 'effect/Effect';
 
 import * as Capability from '@dxos/app-framework/Capability';
+import { log } from '@dxos/log';
 // UI-free subpath: the root barrel reaches the panel components, which would pull React into the
 // headless barrels this module is carried into.
 import { logBuffer } from '@dxos/react-ui-debug/log-buffer';
@@ -13,11 +14,29 @@ import { logBuffer } from '@dxos/react-ui-debug/log-buffer';
  * Start recording into the process-wide log buffer at startup, so the log companion shows what
  * happened before it was opened. Recording deliberately does not follow the panel's mount: the
  * entries worth reading are usually the ones from before you went looking.
+ *
+ * Uncaught errors and unhandled rejections bypass the log pipeline, so they are forwarded into it
+ * here: the buffer, and the snapshot operation reading it, are then the one record of what went
+ * wrong in the page.
  */
 export default Capability.makeModule(
   Effect.fnUntraced(function* () {
     logBuffer.start();
-    yield* Effect.addFinalizer(() => Effect.sync(() => logBuffer.stop()));
+    const onError = (event: ErrorEvent) => log.error('uncaught error', { error: event.error ?? event.message });
+    const onRejection = (event: PromiseRejectionEvent) => log.error('unhandled rejection', { error: event.reason });
+    if (typeof window !== 'undefined') {
+      window.addEventListener('error', onError);
+      window.addEventListener('unhandledrejection', onRejection);
+    }
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        if (typeof window !== 'undefined') {
+          window.removeEventListener('error', onError);
+          window.removeEventListener('unhandledrejection', onRejection);
+        }
+        logBuffer.stop();
+      }),
+    );
     return [];
   }),
 );

package/src/capabilities/operation-handler.ts

@@ -6,11 +6,20 @@ import * as Effect from 'effect/Effect';
 
 import * as Capabilities from '@dxos/app-framework/Capabilities';
 import * as Capability from '@dxos/app-framework/Capability';
+import type * as Devtools from '@dxos/app-framework/Devtools';
 
 import { DebugOperationHandlerSet } from '#operations';
 
 export default Capability.makeModule(
   Effect.fnUntraced(function* () {
+    setupDevtools();
     return Capability.contribute(Capabilities.OperationHandler, DebugOperationHandlerSet.handlers);
   }),
 );
+
+// Console sugar for the snapshot operation (see app-framework/docs/INTROSPECTION.md §3.1).
+const setupDevtools = () => {
+  const composer: Devtools.ComposerDevtools = (globalThis.composer ??= {});
+  // `input` passes through, so a caller can scope the error window (`{ since }`).
+  composer.snapshot = (input: { since?: number } = {}) => composer.invoke?.('org.dxos.operation.debug.snapshot', input);
+};