@dxos/plugin-debug 0.7.4 → 0.7.5-labs.401163d

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

@@ -0,0 +1,175 @@
+//
+// 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 }],
+            disposition: 'navigation',
+            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.requestCapabilities(Capabilities.AppGraph);
+        if (!graph) {
+          return;
+        }
+
+        return [
+          {
+            id: 'dxos.org/plugin/debug/debug',
+            type: 'dxos.org/plugin/debug/debug',
+            data: { graph },
+            properties: {
+              label: ['debug label', { ns: DEBUG_PLUGIN }],
+              disposition: 'navigation',
+              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 }) => {
+        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, 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,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
+export const ReactSurface = lazy(() => import('./react-surface'));
+export const DebugSettings = lazy(() => import('./settings'));

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,130 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Capabilities, contributes, createIntent, createSurface, type PluginsContext } from '@dxos/app-framework';
+import { Devtools } from '@dxos/devtools';
+import { SettingsStore } from '@dxos/local-storage';
+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: 'article',
+      filter: (data): data is { subject: SettingsStore<DebugSettingsProps> } =>
+        data.subject instanceof SettingsStore && data.subject.prefix === DEBUG_PLUGIN,
+      component: ({ data: { subject } }) => <DebugSettings settings={subject.value} />,
+    }),
+    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'],
+      position: '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

@@ -2,16 +2,14 @@
 // Copyright 2023 DXOS.org
 //
 
-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';
-import { useTranslation, Button, Toast, Input, useFileDownload, Select } from '@dxos/react-ui';
-import { DeprecatedFormInput } from '@dxos/react-ui-form';
-import { getSize, mx } from '@dxos/react-ui-theme';
+import { useTranslation, Button, Toast, Input, useFileDownload, Select, Icon } from '@dxos/react-ui';
+import { DeprecatedFormContainer, DeprecatedFormInput } from '@dxos/react-ui-form';
 import { setDeep } from '@dxos/util';
 
 import { DEBUG_PLUGIN } from '../meta';
@@ -34,7 +32,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 +50,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;
@@ -79,7 +77,7 @@ export const DebugSettings = ({ settings }: { settings: DebugSettingsProps }) =>
   };
 
   return (
-    <>
+    <DeprecatedFormContainer>
       <DeprecatedFormInput label={t('settings show debug panel')}>
         <Input.Switch checked={settings.debug} onCheckedChange={(checked) => (settings.debug = !!checked)} />
       </DeprecatedFormInput>
@@ -91,12 +89,12 @@ export const DebugSettings = ({ settings }: { settings: DebugSettingsProps }) =>
       </DeprecatedFormInput>
       <DeprecatedFormInput label={t('settings download diagnostics')}>
         <Button onClick={handleDownload}>
-          <DownloadSimple className={getSize(5)} />
+          <Icon icon='ph--download-simple--regular' size={5} />
         </Button>
       </DeprecatedFormInput>
       <DeprecatedFormInput label={t('settings repair')}>
         <Button onClick={handleRepair}>
-          <FirstAidKit className={getSize(5)} />
+          <Icon icon='ph--first-aid-kit--regular' size={5} />
         </Button>
       </DeprecatedFormInput>
 
@@ -105,7 +103,7 @@ export const DebugSettings = ({ settings }: { settings: DebugSettingsProps }) =>
         <Toast.Root>
           <Toast.Body>
             <Toast.Title>
-              <Gift className={mx(getSize(5), 'inline mr-1')} weight='duotone' />
+              <Icon icon='ph--gift--duotone' size={5} classNames='inline mr-1' />
               <span>{toast.title}</span>
             </Toast.Title>
             {toast.description && <Toast.Description>{toast.description}</Toast.Description>}
@@ -145,7 +143,7 @@ export const DebugSettings = ({ settings }: { settings: DebugSettingsProps }) =>
           </Select.Portal>
         </Select.Root>
       </DeprecatedFormInput>
-    </>
+    </DeprecatedFormContainer>
   );
 };
 

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,16 +4,14 @@
 
 import React, { useEffect, useRef, useState } from 'react';
 
-import { firstIdInPart, parseGraphPlugin, parseNavigationPlugin, useResolvePlugin } from '@dxos/app-framework';
+import { useAppGraph, useLayout } 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';
 import { useNetworkStatus } from '@dxos/react-client/mesh';
-import { Icon } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { Icon, Popover } from '@dxos/react-ui';
 
 const styles = {
   success: 'text-sky-300 dark:text-green-700',
@@ -67,10 +65,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,11 +135,9 @@ 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 _space = location && graph ? getActiveSpace(graph, firstIdInPart(location.active, 'main')) : undefined;
+  const layout = useLayout();
+  const { graph } = useAppGraph();
+  const _space = graph ? getActiveSpace(graph, layout.active[0]) : undefined;
   // TODO(dmaretskyi): Fix this when we have save status for automerge.
   // useEffect(() => {
   //   if (!space) {
@@ -192,22 +185,19 @@ const PerformanceIndicator = () => {
   const [stats, refreshStats] = useStats();
 
   return (
-    <>
-      <StatusBar.Button onClick={() => setVisible((visible) => !visible)} title='Performance panels'>
-        <Icon icon='ph--chart-bar--regular' size={4} />
-      </StatusBar.Button>
-      {visible && (
-        <div
-          className={mx(
-            'z-20 absolute bottom-[--statusbar-size] right-4 w-[450px]',
-            'overflow-x-hidden overflow-y-auto scrollbar-thin',
-            'border-x border-y border-separator',
-          )}
-        >
+    <Popover.Root open={visible} onOpenChange={setVisible}>
+      <Popover.Trigger asChild>
+        <StatusBar.Button onClick={() => setVisible((visible) => !visible)} title='Performance panels'>
+          <Icon icon='ph--chart-bar--regular' size={4} />
+        </StatusBar.Button>
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Content classNames='max-is-[min(var(--radix-popover-content-available-width),300px)] max-bs-[--radix-popover-content-available-height]'>
           <StatsPanel stats={stats} onRefresh={refreshStats} />
-        </div>
-      )}
-    </>
+          <Popover.Arrow />
+        </Popover.Content>
+      </Popover.Portal>
+    </Popover.Root>
   );
 };