@dxos/plugin-debug 0.7.4 → 0.7.5-labs.a279d8c

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

@@ -0,0 +1,177 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { contributes, Capabilities, type PluginsContext } from '@dxos/app-framework';
+import { ClientCapabilities } from '@dxos/plugin-client';
+import { createExtension, toSignal, type Node } from '@dxos/plugin-graph';
+import { memoizeQuery } from '@dxos/plugin-space';
+import { CollectionType } from '@dxos/plugin-space/types';
+import { getTypename, parseId, SpaceState } from '@dxos/react-client/echo';
+import { isSpace, type Space } from '@dxos/react-client/echo';
+
+import { DEBUG_PLUGIN } from '../meta';
+import { type DebugSettingsProps } from '../types';
+
+export default (context: PluginsContext) => {
+  const resolve = (typename: string) =>
+    context.requestCapabilities(Capabilities.Metadata).find(({ id }) => id === typename)?.metadata ?? {};
+
+  return contributes(Capabilities.AppGraphBuilder, [
+    // Devtools node.
+    createExtension({
+      id: 'dxos.org/plugin/debug/devtools',
+      filter: (node): node is Node<null> => {
+        const settings = context
+          .requestCapabilities(Capabilities.SettingsStore)[0]
+          ?.getStore<DebugSettingsProps>(DEBUG_PLUGIN)?.value;
+        return !!settings?.devtools && node.id === 'root';
+      },
+      connector: () => [
+        {
+          // TODO(zan): Removed `/` because it breaks deck layout reload. Fix?
+          id: 'dxos.org.plugin.debug.devtools',
+          data: 'devtools',
+          type: 'dxos.org/plugin/debug/devtools',
+          properties: {
+            label: ['devtools label', { ns: DEBUG_PLUGIN }],
+            icon: 'ph--hammer--regular',
+          },
+        },
+      ],
+    }),
+
+    // Debug node.
+    createExtension({
+      id: 'dxos.org/plugin/debug/debug',
+      filter: (node): node is Node<null> => {
+        const settings = context
+          .requestCapabilities(Capabilities.SettingsStore)[0]
+          ?.getStore<DebugSettingsProps>(DEBUG_PLUGIN)?.value;
+        return !!settings?.debug && node.id === 'root';
+      },
+      connector: () => {
+        const graph = context.requestCapability(Capabilities.AppGraph);
+
+        return [
+          {
+            id: 'dxos.org/plugin/debug/debug',
+            type: 'dxos.org/plugin/debug/debug',
+            data: { graph },
+            properties: {
+              label: ['debug label', { ns: DEBUG_PLUGIN }],
+              icon: 'ph--bug--regular',
+            },
+          },
+        ];
+      },
+    }),
+
+    // Space debug nodes.
+    createExtension({
+      id: 'dxos.org/plugin/debug/spaces',
+      filter: (node): node is Node<Space> => {
+        const settings = context
+          .requestCapabilities(Capabilities.SettingsStore)[0]
+          ?.getStore<DebugSettingsProps>(DEBUG_PLUGIN)?.value;
+        return !!settings?.debug && isSpace(node.data);
+      },
+      connector: ({ node }) => {
+        const space = node.data;
+        const state = toSignal(
+          (onChange) => space.state.subscribe(() => onChange()).unsubscribe,
+          () => space.state.get(),
+          space.id,
+        );
+        if (state !== SpaceState.SPACE_READY) {
+          return;
+        }
+
+        // Not adding the debug node until the root collection is available aligns the behaviour of this
+        // extension with that of the space plugin adding objects. This ensures that the debug node is added at
+        // the same time as objects and prevents order from changing as the nodes are added.
+        const collection = space.properties[CollectionType.typename]?.target as CollectionType | undefined;
+        if (!collection) {
+          return;
+        }
+
+        return [
+          {
+            id: `${space.id}-debug`, // TODO(burdon): Change to slashes consistently.
+            type: 'dxos.org/plugin/debug/space',
+            data: { space, type: 'dxos.org/plugin/debug/space' },
+            properties: {
+              label: ['debug label', { ns: DEBUG_PLUGIN }],
+              icon: 'ph--bug--regular',
+            },
+          },
+        ];
+      },
+    }),
+
+    // Create nodes for debug sidebar.
+    createExtension({
+      id: `${DEBUG_PLUGIN}/debug-for-subject`,
+      resolver: ({ id }) => {
+        // TODO(Zan): Find util (or make one).
+        if (!id.endsWith('~debug')) {
+          return;
+        }
+
+        const type = 'orphan-settings-for-subject';
+        const icon = 'ph--bug--regular';
+
+        const client = context.requestCapability(ClientCapabilities.Client);
+        const [subjectId] = id.split('~');
+        const { spaceId, objectId } = parseId(subjectId);
+        const spaces = toSignal(
+          (onChange) => client.spaces.subscribe(() => onChange()).unsubscribe,
+          () => client.spaces.get(),
+        );
+        const space = spaces?.find((space) => space.state.get() === SpaceState.SPACE_READY && space.id === spaceId);
+        if (!objectId) {
+          // TODO(burdon): Ref SPACE_PLUGIN ns.
+          const label = space
+            ? space.properties.name || ['unnamed space label', { ns: DEBUG_PLUGIN }]
+            : ['unnamed object settings label', { ns: DEBUG_PLUGIN }];
+
+          // TODO(wittjosiah): Support comments for arbitrary subjects.
+          //   This is to ensure that the comments panel is not stuck on an old object.
+          return {
+            id,
+            type,
+            data: null,
+            properties: {
+              icon,
+              label,
+              showResolvedThreads: false,
+              object: null,
+              space,
+            },
+          };
+        }
+
+        const [object] = memoizeQuery(space, { id: objectId });
+        if (!object || !subjectId) {
+          return;
+        }
+
+        const meta = resolve(getTypename(object) ?? '');
+        const label = meta.label?.(object) ||
+          object.name ||
+          meta.placeholder || ['unnamed object settings label', { ns: DEBUG_PLUGIN }];
+
+        return {
+          id,
+          type,
+          data: null,
+          properties: {
+            icon,
+            label,
+            object,
+          },
+        };
+      },
+    }),
+  ]);
+};

package/src/capabilities/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
+export const ReactContext = lazy(() => import('./react-context'));
+export const ReactSurface = lazy(() => import('./react-surface'));
+export const DebugSettings = lazy(() => import('./settings'));

package/src/capabilities/react-context.tsx

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useEffect, useState } from 'react';
+
+import { Capabilities, contributes } from '@dxos/app-framework';
+import { Timer } from '@dxos/async';
+
+import { DEBUG_PLUGIN } from '../meta';
+import { DebugContext } from '../types';
+
+export default () =>
+  contributes(Capabilities.ReactContext, {
+    id: DEBUG_PLUGIN,
+    context: ({ children }) => {
+      const [timer, setTimer] = useState<Timer>();
+      useEffect(() => timer?.state.on((value) => !value && setTimer(undefined)), [timer]);
+      useEffect(() => {
+        timer?.stop();
+      }, []);
+
+      return (
+        <DebugContext.Provider
+          value={{
+            running: !!timer,
+            start: (cb, options) => {
+              timer?.stop();
+              setTimer(new Timer(cb).start(options));
+            },
+            stop: () => timer?.stop(),
+          }}
+        >
+          {children}
+        </DebugContext.Provider>
+      );
+    },
+  });

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,138 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import {
+  Capabilities,
+  contributes,
+  createIntent,
+  createSurface,
+  useCapability,
+  type PluginsContext,
+} from '@dxos/app-framework';
+import { Devtools } from '@dxos/devtools';
+import { Graph } from '@dxos/plugin-graph';
+import { SpaceAction, CollectionType } from '@dxos/plugin-space/types';
+import {
+  SpaceState,
+  isSpace,
+  isEchoObject,
+  type ReactiveEchoObject,
+  type ReactiveObject,
+  type Space,
+} from '@dxos/react-client/echo';
+
+import {
+  DebugApp,
+  DebugObjectPanel,
+  DebugSettings,
+  DebugSpace,
+  DebugStatus,
+  SpaceGenerator,
+  Wireframe,
+} from '../components';
+import { DEBUG_PLUGIN } from '../meta';
+import { type DebugSettingsProps } from '../types';
+
+type SpaceDebug = {
+  type: string;
+  space: Space;
+};
+
+type GraphDebug = {
+  graph: Graph;
+};
+
+const isSpaceDebug = (data: any): data is SpaceDebug => data.type === `${DEBUG_PLUGIN}/space` && isSpace(data.space);
+const isGraphDebug = (data: any): data is GraphDebug => data.graph instanceof Graph;
+
+export default (context: PluginsContext) =>
+  contributes(Capabilities.ReactSurface, [
+    createSurface({
+      id: `${DEBUG_PLUGIN}/settings`,
+      role: 'settings',
+      filter: (data): data is any => data.subject === DEBUG_PLUGIN,
+      component: () => {
+        const settings = useCapability(Capabilities.SettingsStore).getStore<DebugSettingsProps>(DEBUG_PLUGIN)!.value;
+        return <DebugSettings settings={settings} />;
+      },
+    }),
+    createSurface({
+      id: `${DEBUG_PLUGIN}/status`,
+      role: 'status',
+      component: () => <DebugStatus />,
+    }),
+    createSurface({
+      id: `${DEBUG_PLUGIN}/complementary`,
+      role: 'complementary--debug',
+      filter: (data): data is { subject: ReactiveEchoObject<any> } => isEchoObject(data.subject),
+      component: ({ data }) => <DebugObjectPanel object={data.subject} />,
+    }),
+    createSurface({
+      id: `${DEBUG_PLUGIN}/devtools`,
+      role: 'article',
+      filter: (data): data is any => {
+        const settings = context
+          .requestCapability(Capabilities.SettingsStore)
+          .getStore<DebugSettingsProps>(DEBUG_PLUGIN)!.value;
+        return data.subject === 'devtools' && !!settings.devtools;
+      },
+      component: () => <Devtools />,
+    }),
+    createSurface({
+      id: `${DEBUG_PLUGIN}/space`,
+      role: 'article',
+      filter: (data): data is { subject: SpaceDebug } => isSpaceDebug(data.subject),
+      component: ({ data }) => {
+        const handleCreateObject = useCallback(
+          (objects: ReactiveObject<any>[]) => {
+            if (!isSpace(data.subject.space)) {
+              return;
+            }
+
+            const collection =
+              data.subject.space.state.get() === SpaceState.SPACE_READY &&
+              data.subject.space.properties[CollectionType.typename]?.target;
+            if (!(collection instanceof CollectionType)) {
+              return;
+            }
+
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            objects.forEach((object) => {
+              void dispatch(createIntent(SpaceAction.AddObject, { target: collection, object }));
+            });
+          },
+          [data.subject.space],
+        );
+
+        const deprecated = false;
+        return deprecated ? (
+          <DebugSpace space={data.subject.space} onAddObjects={handleCreateObject} />
+        ) : (
+          <SpaceGenerator space={data.subject.space} onCreateObjects={handleCreateObject} />
+        );
+      },
+    }),
+    createSurface({
+      id: `${DEBUG_PLUGIN}/graph`,
+      role: 'article',
+      filter: (data): data is { subject: GraphDebug } => isGraphDebug(data.subject),
+      component: ({ data }) => <DebugApp graph={data.subject.graph} />,
+    }),
+    createSurface({
+      id: `${DEBUG_PLUGIN}/wireframe`,
+      role: ['article', 'section'],
+      disposition: 'hoist',
+      filter: (data): data is { subject: ReactiveEchoObject<any> } => {
+        const settings = context
+          .requestCapability(Capabilities.SettingsStore)
+          .getStore<DebugSettingsProps>(DEBUG_PLUGIN)!.value;
+        return isEchoObject(data.subject) && !!settings.wireframe;
+      },
+      component: ({ data, role }) => (
+        <Wireframe label={`${role}:${name}`} object={data.subject} classNames='row-span-2 overflow-hidden' />
+      ),
+    }),
+  ]);

package/src/capabilities/settings.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes } from '@dxos/app-framework';
+import { create } from '@dxos/react-client/echo';
+
+import { DEBUG_PLUGIN } from '../meta';
+import { type DebugSettingsProps, DebugSettingsSchema } from '../types';
+
+export default () => {
+  const settings = create<DebugSettingsProps>({
+    debug: true,
+    devtools: true,
+  });
+
+  return contributes(Capabilities.Settings, { schema: DebugSettingsSchema, prefix: DEBUG_PLUGIN, value: settings });
+};

package/src/components/DebugApp/DebugApp.tsx

@@ -59,7 +59,7 @@ export const DebugApp: FC<{ graph: Graph }> = ({ graph }) => {
             </ToggleGroupItem>
           </ToggleGroup>
 
-          <Toolbar.Expander />
+          <Toolbar.Separator variant='gap' />
           <Button onClick={(event) => handleResetClient(event.shiftKey)} title='Reset client'>
             <Warning className={mx(getSize(5), 'text-red-700')} />
           </Button>

package/src/components/DebugObjectPanel.tsx

@@ -5,6 +5,7 @@
 import React from 'react';
 
 import { type ReactiveEchoObject } from '@dxos/client/echo';
+import { Clipboard, Input } from '@dxos/react-ui';
 import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
 
 export type DebugObjectPanelProps = {
@@ -13,11 +14,22 @@ export type DebugObjectPanelProps = {
 
 // TODO(burdon): Get schema and traverse references.
 export const DebugObjectPanel = ({ object }: DebugObjectPanelProps) => {
+  const dxn = `dxn:echo:@:${object.id}`;
   return (
-    <div className='flex flex-col'>
-      <SyntaxHighlighter classNames='flex text-xs' language='json'>
-        {JSON.stringify(object, null, 2)}
-      </SyntaxHighlighter>
-    </div>
+    <Clipboard.Provider>
+      <div className='flex flex-col'>
+        <Input.Root>
+          <div role='none' className='flex flex-col gap-1'>
+            <div role='none' className='flex gap-1'>
+              <Input.TextInput disabled value={dxn} />
+              <Clipboard.IconButton value={dxn} />
+            </div>
+          </div>
+        </Input.Root>
+        <SyntaxHighlighter classNames='flex text-xs' language='json'>
+          {JSON.stringify(object, null, 2)}
+        </SyntaxHighlighter>
+      </div>
+    </Clipboard.Provider>
   );
 };

package/src/components/DebugSettings.tsx

@@ -5,7 +5,7 @@
 import { Gift, DownloadSimple, FirstAidKit } from '@phosphor-icons/react';
 import React, { useEffect, useState } from 'react';
 
-import { parseFileManagerPlugin, useResolvePlugin } from '@dxos/app-framework';
+import { Capabilities, useCapabilities } from '@dxos/app-framework';
 import { type ConfigProto, defs, SaveConfig, Storage } from '@dxos/config';
 import { log } from '@dxos/log';
 import { useClient } from '@dxos/react-client';
@@ -34,7 +34,7 @@ export const DebugSettings = ({ settings }: { settings: DebugSettingsProps }) =>
   const download = useFileDownload();
   // TODO(mykola): Get updates from other places that change Config.
   const [storageConfig, setStorageConfig] = useState<ConfigProto>({});
-  const fileManagerPlugin = useResolvePlugin(parseFileManagerPlugin);
+  const [upload] = useCapabilities(Capabilities.FileUploader);
 
   useEffect(() => {
     void Storage().then((config) => setStorageConfig(config));
@@ -52,8 +52,8 @@ export const DebugSettings = ({ settings }: { settings: DebugSettingsProps }) =>
     const fileName = `composer-${new Date().toISOString().replace(/\W/g, '-')}.json`;
     download(file, fileName);
 
-    if (fileManagerPlugin?.provides.file.upload) {
-      const info = await fileManagerPlugin.provides.file.upload(new File([file], fileName), client.spaces.default);
+    if (upload) {
+      const info = await upload(new File([file], fileName), client.spaces.default);
       if (!info) {
         log.error('diagnostics failed to upload to IPFS');
         return;

package/src/components/DebugSpace/DebugSpace.stories.tsx

@@ -5,21 +5,22 @@
 import '@dxos-theme';
 
 import { type Meta } from '@storybook/react';
-import React, { useEffect } from 'react';
+import React from 'react';
 
 import { createSpaceObjectGenerator } from '@dxos/echo-generator';
 import { useSpaces } from '@dxos/react-client/echo';
 import { withClientProvider } from '@dxos/react-client/testing';
+import { useAsyncEffect } from '@dxos/react-hooks';
 import { render, withLayout, withTheme } from '@dxos/storybook-utils';
 
 import { DebugSpace } from './DebugSpace';
 
 const DefaultStory = () => {
   const [space] = useSpaces();
-  useEffect(() => {
+  useAsyncEffect(async () => {
     if (space) {
       const generator = createSpaceObjectGenerator(space);
-      generator.addSchemas();
+      await generator.addSchemas();
     }
   }, [space]);
 

package/src/components/DebugSpace/DebugSpace.tsx

@@ -158,7 +158,7 @@ export const DebugSpace: FC<{
           <IconButton icon='ph--arrow-clockwise--regular' iconOnly label='Refresh' size={5} onClick={handleUpdate} />
           <IconButton icon='ph--download-simple--regular' iconOnly label='Download' size={5} onClick={handleDownload} />
 
-          <Toolbar.Expander />
+          <Toolbar.Separator variant='gap' />
           <IconButton
             icon='ph--flag-pennant--regular'
             iconOnly

package/src/components/DebugSpace/ObjectCreator.stories.tsx

@@ -5,22 +5,23 @@
 import '@dxos-theme';
 
 import { type Meta } from '@storybook/react';
-import React, { useEffect } from 'react';
+import React from 'react';
 
 import { createSpaceObjectGenerator } from '@dxos/echo-generator';
 import { log } from '@dxos/log';
 import { useSpaces } from '@dxos/react-client/echo';
 import { withClientProvider } from '@dxos/react-client/testing';
+import { useAsyncEffect } from '@dxos/react-hooks';
 import { render, withLayout, withTheme } from '@dxos/storybook-utils';
 
 import { ObjectCreator, type ObjectCreatorProps } from './ObjectCreator';
 
 const DefaultStory = () => {
   const [space] = useSpaces();
-  useEffect(() => {
+  useAsyncEffect(async () => {
     if (space) {
       const generator = createSpaceObjectGenerator(space);
-      generator.addSchemas();
+      await generator.addSchemas();
     }
   }, [space]);
 

package/src/components/DebugStatus.tsx

@@ -4,10 +4,9 @@
 
 import React, { useEffect, useRef, useState } from 'react';
 
-import { firstIdInPart, parseGraphPlugin, parseNavigationPlugin, useResolvePlugin } from '@dxos/app-framework';
+import { Capabilities, firstIdInPart, useCapability } from '@dxos/app-framework';
 import { TimeoutError } from '@dxos/async';
 import { StatsPanel, useStats } from '@dxos/devtools';
-import { log } from '@dxos/log';
 import { getActiveSpace } from '@dxos/plugin-space';
 import { StatusBar } from '@dxos/plugin-status-bar';
 import { ConnectionState } from '@dxos/protocols/proto/dxos/client/services';
@@ -67,10 +66,7 @@ const ErrorIndicator = () => {
   useEffect(() => {
     const errorListener = (event: any) => {
       const error: Error = event.error ?? event.reason;
-      // event.preventDefault();
       if (errorRef.current !== error) {
-        // eslint-disable-next-line no-console
-        log.error('onError', { event });
         errorRef.current = error;
         forceUpdate({});
       }
@@ -140,10 +136,8 @@ const SwarmIndicator = () => {
 // TODO(burdon): Merge with SaveStatus.
 const SavingIndicator = () => {
   const [state, _setState] = useState(0);
-  const navigationPlugin = useResolvePlugin(parseNavigationPlugin);
-  const graphPlugin = useResolvePlugin(parseGraphPlugin);
-  const location = navigationPlugin?.provides.location;
-  const graph = graphPlugin?.provides.graph;
+  const location = useCapability(Capabilities.Location);
+  const { graph } = useCapability(Capabilities.AppGraph);
   const _space = location && graph ? getActiveSpace(graph, firstIdInPart(location.active, 'main')) : undefined;
   // TODO(dmaretskyi): Fix this when we have save status for automerge.
   // useEffect(() => {