@dxos/app-framework 0.8.4-main.69d29f4 → 0.8.4-main.6fa680abb7

package/src/testing/withPluginManager.stories.tsx

@@ -7,9 +7,9 @@ import React from 'react';
 
 import { withTheme } from '@dxos/react-ui/testing';
 
-import * as Common from '../common';
+import { Capabilities } from '../common';
 import { Capability } from '../core';
-import { Surface } from '../react';
+import { Surface } from '../ui';
 
 import { withPluginManager } from './withPluginManager';
 
@@ -18,7 +18,7 @@ const DefaultStory = () => {
   return (
     <div>
       <div>Hello</div>
-      <Surface role='main' />
+      <Surface.Surface role='main' />
     </div>
   );
 };
@@ -27,12 +27,12 @@ const meta = {
   title: 'sdk/app-framework/withPluginManager',
   render: DefaultStory,
   decorators: [
-    withTheme,
+    withTheme(),
     withPluginManager({
       capabilities: [
         Capability.contributes(
-          Common.Capability.ReactSurface,
-          Common.createSurface({
+          Capabilities.ReactSurface,
+          Surface.create({
             id: 'test',
             role: 'main',
             component: ({ role }) => <span>{JSON.stringify({ role })}</span>,

package/src/testing/withPluginManager.tsx

@@ -10,9 +10,9 @@ import { raise } from '@dxos/debug';
 import { useAsyncEffect } from '@dxos/react-hooks';
 import { type MaybeProvider, getProviderValue } from '@dxos/util';
 
-import * as Common from '../common';
+import { ActivationEvents, Capabilities } from '../common';
 import { type ActivationEvent, Capability, type CapabilityManager, Plugin, PluginManager } from '../core';
-import { type UseAppOptions, useApp } from '../react';
+import { type UseAppOptions, useApp } from '../ui';
 
 /**
  * @internal
@@ -61,18 +61,21 @@ export type WithPluginManagerInitializer<Args = void> =
 export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args> = {}): Decorator => {
   return (Story, context) => {
     const options = typeof init === 'function' ? init(context as any) : init;
-    const pluginManager = useMemo(() => setupPluginManager(options), [init]);
+    const { pluginManager, setupEvents } = useMemo(
+      () => ({ pluginManager: setupPluginManager(options), setupEvents: options.setupEvents }),
+      [init],
+    );
 
     // Set-up root capability.
     useEffect(() => {
-      const capability = Capability.contributes(Common.Capability.ReactRoot, {
+      const capability = Capability.contributes(Capabilities.ReactRoot, {
         id: context.id,
         root: () => <Story />,
       });
 
       pluginManager.capabilities.contribute({
         ...capability,
-        module: 'dxos.org/app-framework/withPluginManager',
+        module: 'org.dxos.app-framework.with-plugin-manager',
       });
 
       return () => {
@@ -86,14 +89,14 @@ export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args
     }, [pluginManager]);
 
     // Create app.
-    const App = useApp({ pluginManager });
+    const App = useApp({ pluginManager, setupEvents });
 
     return <App />;
   };
 };
 
 const storyMeta = {
-  id: 'dxos.org/app-framework/story',
+  id: 'org.dxos.app-framework.story',
   name: 'Story',
 };
 
@@ -102,7 +105,7 @@ const storyMeta = {
 const StoryPlugin = Plugin.define(storyMeta).pipe(
   Plugin.addModule({
     id: 'Story',
-    activatesOn: Common.ActivationEvent.Startup,
+    activatesOn: ActivationEvents.Startup,
     activate: () => Effect.succeed([]),
   }),
   Plugin.make,

package/src/ui/components/App/App.stories.tsx

@@ -0,0 +1,92 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { useEffect } from 'react';
+
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { ActivationEvents, Capabilities } from '../../../common';
+import { Capability, Plugin } from '../../../core';
+import { useApp } from '../../hooks';
+
+// Minimal plugin that contributes a ReactRoot.
+const TestPlugin = Plugin.define<{ error?: boolean }>({
+  id: 'org.dxos.plugin.test',
+  name: 'Test Plugin',
+}).pipe(
+  Plugin.addModule(({ error }) => ({
+    id: 'TestMain',
+    activatesOn: ActivationEvents.Startup,
+    activate: () =>
+      Effect.succeed([
+        Capability.contributes(Capabilities.ReactRoot, {
+          id: 'org.dxos.plugin.test.root',
+          root: () => {
+            useEffect(() => {
+              let t: NodeJS.Timeout;
+              if (error) {
+                console.log('Ticking...');
+                t = setTimeout(() => {
+                  console.log('Bang!');
+                  throw new Error('Runtime error');
+                }, 3_000);
+              }
+
+              return () => clearTimeout(t);
+            }, [error]);
+
+            return <h1 className='text-lg'>App Started</h1>;
+          },
+        }),
+      ]),
+  })),
+  Plugin.make,
+);
+
+const core = [TestPlugin.meta.id];
+
+type StoryProps = { plugins?: Plugin.Plugin[] };
+
+const DefaultStory = ({ plugins }: StoryProps) => {
+  const App = useApp({
+    plugins,
+    core,
+    placeholder: () => {
+      return (
+        <div role='none' className='text-description'>
+          Loading...
+        </div>
+      );
+    },
+  });
+
+  return <App />;
+};
+
+const meta = {
+  title: 'sdk/app-framework/App',
+  render: DefaultStory,
+  decorators: [withTheme()],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    plugins: [TestPlugin({})],
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    plugins: [TestPlugin({ error: true })],
+  },
+};

package/src/{react → ui/components/App}/App.tsx

@@ -4,12 +4,9 @@
 
 import React, { type PropsWithChildren } from 'react';
 
-import * as Common from '../common';
-import { topologicalSort } from '../helpers';
-
-import { type UseAppOptions } from './useApp';
-import { useCapabilities } from './useCapabilities';
-import { LoadingState, useLoading } from './useLoading';
+import { Capabilities } from '../../../common';
+import { topologicalSort } from '../../../helpers';
+import { LoadingState, type UseAppOptions, useCapabilities, useLoading } from '../../hooks';
 
 export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
   ready: boolean;
@@ -17,8 +14,8 @@ export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
 };
 
 export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppProps) => {
-  const reactContexts = useCapabilities(Common.Capability.ReactContext);
-  const reactRoots = useCapabilities(Common.Capability.ReactRoot);
+  const reactContexts = useCapabilities(Capabilities.ReactContext);
+  const reactRoots = useCapabilities(Capabilities.ReactRoot);
   const stage = useLoading(ready, debounce);
 
   if (error) {
@@ -45,7 +42,7 @@ export const App = ({ placeholder: Placeholder, ready, error, debounce }: AppPro
   );
 };
 
-const composeContexts = (contexts: Common.Capability.ReactContext[]) => {
+const composeContexts = (contexts: Capabilities.ReactContext[]) => {
   if (contexts.length === 0) {
     return ({ children }: PropsWithChildren) => <>{children}</>;
   }

package/src/{playground/layout → ui/components/App}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './plugin';
+export * from './App';

package/src/{react → ui/components/PluginManager}/PluginManagerContext.stories.tsx

@@ -7,14 +7,13 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
 import React, { useEffect, useMemo, useState } from 'react';
 
-import { withTheme } from '@dxos/react-ui/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { useWebComponentContext } from '@dxos/web-context-react';
 
-import * as Common from '../common';
-import { PluginManagerContext } from '../context';
-import { Capability, Plugin } from '../core';
-
-import { useApp } from './useApp';
+import { ActivationEvents, Capabilities } from '../../../common';
+import { PluginManagerContext } from '../../../context';
+import { Capability, Plugin } from '../../../core';
+import { useApp } from '../../hooks';
 
 // Define the Counter capability
 const Counter = Capability.make<{ count: number; increment: () => void }>('example/counter');
@@ -79,7 +78,7 @@ const CounterComponent = () => {
   }, [counter]);
 
   if (!manager) {
-    return <div className='p-4 text-red-500'>Error: Context not found</div>;
+    return <div className='p-4 text-error-text'>Error: Context not found</div>;
   }
 
   return (
@@ -105,7 +104,7 @@ const CounterComponent = () => {
           <CountStatus />
         </div>
 
-        <div className='mt-8 pt-4 border-bs border-neutral-200 dark:border-neutral-700 text-center'>
+        <div className='mt-8 pt-4 border-t border-neutral-200 dark:border-neutral-700 text-center'>
           <p className='text-sm text-neutral-500 dark:text-neutral-400'>
             This component accesses the <code>PluginManager</code> via <code>useWebComponentContext</code>.
           </p>
@@ -117,12 +116,12 @@ const CounterComponent = () => {
 
 // Plugin that provides the Counter capability and renders the UI
 const CounterPlugin = Plugin.define({
-  id: 'dxos.org/plugin/counter',
+  id: 'org.dxos.plugin.counter',
   name: 'Counter Plugin',
 }).pipe(
   Plugin.addModule({
     id: 'CounterMain',
-    activatesOn: Common.ActivationEvent.Startup,
+    activatesOn: ActivationEvents.Startup,
     activate: () => {
       const listeners = new Set<() => void>();
       const counter = {
@@ -142,8 +141,8 @@ const CounterPlugin = Plugin.define({
         Capability.contributes(Counter, counter),
 
         // Contribute the UI
-        Capability.contributes(Common.Capability.ReactRoot, {
-          id: 'dxos.org/plugin/counter/root',
+        Capability.contributes(Capabilities.ReactRoot, {
+          id: 'org.dxos.plugin.counter.root',
           root: CounterComponent,
         }),
       ]);
@@ -153,7 +152,7 @@ const CounterPlugin = Plugin.define({
 )();
 
 const plugins = [CounterPlugin];
-const core = ['dxos.org/plugin/counter'];
+const core = ['org.dxos.plugin.counter'];
 const placeholder = () => (
   <div className='flex h-screen items-center justify-center p-4 text-lg text-neutral-500'>
     Initializing Application...
@@ -173,7 +172,7 @@ const DefaultStory = () => {
 const meta = {
   title: 'sdk/app-framework/PluginManagerContext',
   render: DefaultStory,
-  decorators: [withTheme],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
   parameters: {
     layout: 'fullscreen',
   },

package/src/{react → ui/components/PluginManager}/PluginManagerProvider.ts

@@ -6,7 +6,7 @@ import { createContext, useContext } from 'react';
 
 import { raise } from '@dxos/debug';
 
-import { type PluginManager } from '../core';
+import { type PluginManager } from '../../../core';
 
 const PluginManagerContext = createContext<PluginManager.PluginManager | undefined>(undefined);
 

package/src/ui/components/PluginManager/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './PluginManagerProvider';

package/src/{react/Surface.stories.tsx → ui/components/Surface/SurfaceComponent.stories.tsx}

@@ -7,14 +7,15 @@ import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'rea
 
 import { faker } from '@dxos/random';
 import { List, ListItem, Toolbar } from '@dxos/react-ui';
-import { withTheme } from '@dxos/react-ui/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { type ColorStyles, getHashStyles, mx } from '@dxos/ui-theme';
 
-import * as Common from '../common';
-import { withPluginManager } from '../testing';
+import { Capabilities } from '../../../common';
+import { withPluginManager } from '../../../testing';
+import { usePluginManager } from '../PluginManager';
 
-import { usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
+import { SurfaceComponent, useSurfaces } from './SurfaceComponent';
+import { create } from './types';
 
 type TestComponentProps = {
   id: string;
@@ -24,7 +25,7 @@ type TestComponentProps = {
 const TestComponent = forwardRef<HTMLDivElement, TestComponentProps>(({ styles, id }, forwardedRef) => {
   return (
     <div
-      className={mx('flex justify-center items-center border rounded', styles.surface, styles.border)}
+      className={mx('flex justify-center items-center border rounded-sm', styles.surface, styles.border)}
       ref={forwardedRef}
     >
       <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
@@ -40,10 +41,11 @@ const DefaultStory = () => {
   const handleAdd = useCallback(() => {
     const id = `test-${faker.number.int({ min: 0, max: 1_000 })}`;
     const styles = getHashStyles(id);
+
     manager.capabilities.contribute({
       module: 'test',
-      interface: Common.Capability.ReactSurface,
-      implementation: Common.createSurface({
+      interface: Capabilities.ReactSurface,
+      implementation: create({
         id,
         role: 'item',
         filter: (data): data is any => (data as any)?.id === id,
@@ -61,8 +63,8 @@ const DefaultStory = () => {
   const handleError = useCallback(() => {
     manager.capabilities.contribute({
       module: 'error',
-      interface: Common.Capability.ReactSurface,
-      implementation: Common.createSurface({
+      interface: Capabilities.ReactSurface,
+      implementation: create({
         id: 'error',
         role: 'item',
         filter: (data): data is any => (data as any)?.id === 'error',
@@ -86,7 +88,7 @@ const DefaultStory = () => {
           }
 
           return (
-            <div className='flex justify-center items-center border border-roseFill rounded'>
+            <div className='flex justify-center items-center border border-rose-fill rounded-sm'>
               <span className='font-mono'>Ticking... {count}</span>
             </div>
           );
@@ -103,15 +105,15 @@ const DefaultStory = () => {
   }, [ref]);
 
   return (
-    <div className='flex flex-col bs-full overflow-hidden'>
+    <div className='flex flex-col h-full overflow-hidden'>
       <Toolbar.Root>
         <Toolbar.Button onClick={handleAdd}>Add</Toolbar.Button>
         <Toolbar.Button onClick={handleSelect}>Pick</Toolbar.Button>
         <Toolbar.Button onClick={handleError}>Error</Toolbar.Button>
       </Toolbar.Root>
-      <div className='grid grid-cols-2 bs-full gap-4 overflow-hidden'>
-        <Surface role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
-        <div className='overflow-y-auto bs-full'>
+      <div className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
+        <SurfaceComponent role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
+        <div className='overflow-y-auto h-full'>
           <List>
             {surfaces.map((surface) => (
               <ListItem.Root key={surface.id} id={surface.id}>
@@ -128,7 +130,7 @@ const DefaultStory = () => {
 const meta = {
   title: 'sdk/app-framework/Surface',
   render: DefaultStory,
-  decorators: [withTheme, withPluginManager({ capabilities: [] })],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withPluginManager({ capabilities: [] })],
   parameters: {
     layout: 'fullscreen',
   },

package/src/{react/Surface.tsx → ui/components/Surface/SurfaceComponent.tsx}

@@ -3,47 +3,40 @@
 //
 
 import React, {
-  type Context,
   Fragment,
   type NamedExoticComponent,
   type RefAttributes,
   Suspense,
-  createContext,
   forwardRef,
   memo,
-  useContext,
   useEffect,
   useMemo,
   useRef,
 } from 'react';
 
-import { raise } from '@dxos/debug';
 import { log } from '@dxos/log';
+import { ErrorBoundary } from '@dxos/react-error-boundary';
 import { useDefaultValue } from '@dxos/react-hooks';
 import { byPosition } from '@dxos/util';
 
-import * as Common from '../common';
-import { type CapabilityManager } from '../core';
+import { Capabilities } from '../../../common';
+import { type CapabilityManager } from '../../../core';
+import { useCapabilities } from '../../hooks';
 
-import { ErrorBoundary } from './ErrorBoundary';
+import { SurfaceContext } from './context';
 import { SurfaceInfo } from './SurfaceInfo';
-import { useCapabilities } from './useCapabilities';
+import { type Definition, type Props, type WebComponentDefinition } from './types';
 
 const DEFAULT_PLACEHOLDER = <Fragment />;
 
 const DEBUG = import.meta.env.VITE_DEBUG;
 
-export type SurfaceContext = Pick<Common.SurfaceProps, 'id' | 'role' | 'data'>;
-
-// TODO(burdon): Use @radix-ui/react-context
-const SurfaceContext: Context<SurfaceContext | undefined> = createContext<SurfaceContext | undefined>(undefined);
-
 /**
  * Wrapper component for rendering Web Component surfaces.
  * Handles creation, prop setting, and cleanup of Web Components.
  */
 const WebComponentWrapper = memo(
-  forwardRef<HTMLElement, Common.SurfaceProps & { definition: Common.WebComponentSurfaceDefinition }>(
+  forwardRef<HTMLElement, Props & { definition: WebComponentDefinition }>(
     ({ id, role, data, limit, definition, ...rest }, forwardedRef) => {
       const containerRef = useRef<HTMLDivElement>(null);
       const elementRef = useRef<HTMLElement | null>(null);
@@ -54,7 +47,9 @@ const WebComponentWrapper = memo(
 
       // Create element only once
       useEffect(() => {
-        if (!containerRef.current || elementRef.current) return;
+        if (!containerRef.current || elementRef.current) {
+          return;
+        }
 
         // Create the Web Component
         const element = document.createElement(definition.tagName);
@@ -91,7 +86,9 @@ const WebComponentWrapper = memo(
       // This runs on every render to ensure all props (including those in `rest`) are kept up to date
       useEffect(() => {
         const element = elementRef.current;
-        if (!element) return;
+        if (!element) {
+          return;
+        }
 
         // Update properties on the existing Web Component
         Object.assign(element, propsRef.current);
@@ -107,15 +104,16 @@ WebComponentWrapper.displayName = 'WebComponentWrapper';
 /**
  * Wrapper component that provides context for a surface.
  */
+// TODO(burdon): Allow DebugPlugin to provide different fallback using react-ui ErrorFallback.
 const SurfaceContextProvider = memo(
-  forwardRef<HTMLElement, Common.SurfaceProps & { definition: Common.SurfaceDefinition }>(
-    ({ id, role, data, limit, fallback = DefaultFallback, definition, ...rest }, forwardedRef) => {
+  forwardRef<HTMLElement, Props & { definition: Definition }>(
+    ({ id, role, data, limit, fallback = ErrorFallback, definition, ...rest }, forwardedRef) => {
       const contextValue = useMemo(() => ({ id, role, data }), [id, role, data]);
 
       // Handle Web Component surfaces
       if (definition.kind === 'web-component') {
         return (
-          <ErrorBoundary data={data} fallback={fallback}>
+          <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={fallback}>
             <SurfaceContext.Provider value={contextValue}>
               <WebComponentWrapper
                 id={id}
@@ -138,7 +136,7 @@ const SurfaceContextProvider = memo(
       const debug = DEBUG || '__DX_DEBUG__' in window;
       if (debug) {
         return (
-          <ErrorBoundary data={data} fallback={fallback}>
+          <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={fallback}>
             <div role='none' className='contents' data-id={id} data-role={role}>
               <SurfaceContext.Provider value={contextValue}>
                 <SurfaceInfo ref={forwardedRef}>
@@ -151,7 +149,7 @@ const SurfaceContextProvider = memo(
       }
 
       return (
-        <ErrorBoundary data={data} fallback={fallback}>
+        <ErrorBoundary name='surface' resetKeys={[data]} FallbackComponent={fallback}>
           <div role='none' className='contents' data-id={id} data-role={role}>
             <SurfaceContext.Provider value={contextValue}>
               <Component id={id} role={role} data={data} limit={limit} {...rest} ref={forwardedRef} />
@@ -165,15 +163,11 @@ const SurfaceContextProvider = memo(
 
 SurfaceContextProvider.displayName = 'SurfaceContextProvider';
 
-export const useSurface = (): SurfaceContext => {
-  const context = useContext(SurfaceContext) ?? raise(new Error('Missing SurfaceContext'));
-  return context;
-};
-
 /**
  * A surface is a named region of the screen that can be populated by plugins.
  */
-export const Surface: NamedExoticComponent<Common.SurfaceProps & RefAttributes<HTMLElement>> = memo(
+// TODO(burdon): Remove `ref` since relying on this would be error prone.
+export const SurfaceComponent: NamedExoticComponent<Props & RefAttributes<HTMLElement>> = memo(
   forwardRef(({ id: _id, role, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
     const data = useDefaultValue(dataProp, () => ({}));
 
@@ -211,12 +205,19 @@ export const Surface: NamedExoticComponent<Common.SurfaceProps & RefAttributes<H
   }),
 );
 
-Surface.displayName = 'Surface';
+SurfaceComponent.displayName = 'Surface';
 
-const findCandidates = (
-  surfaces: Common.SurfaceDefinition[],
-  { role, data }: Pick<Common.SurfaceProps, 'role' | 'data'>,
-) => {
+// TODO(burdon): Make user facing, with telemetry.
+const ErrorFallback = ({ error }: Props) => {
+  const { message } = error instanceof Error ? error : { message: String(error) };
+  return (
+    <div role='alert' data-testid='error-boundary-fallback'>
+      <h1 className='flex gap-2 text-sm mt-2 text-info-text'>{message}</h1>
+    </div>
+  );
+};
+
+const findCandidates = (surfaces: Definition[], { role, data }: Pick<Props, 'role' | 'data'>) => {
   return Object.values(surfaces)
     .filter((definition) =>
       Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
@@ -225,32 +226,11 @@ const findCandidates = (
     .toSorted(byPosition);
 };
 
-// TODO(burdon): Make user facing, with telemetry.
-// TODO(burdon): Change based on dev/prod mode; infer subject type, id.
-const DefaultFallback = ({ data, error, dev }: { data: any; error: Error; dev?: boolean }) => {
-  if (dev) {
-    return (
-      <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto'>
-        <h1 className='flex gap-2 text-sm mbs-2'>{error.message}</h1>
-        <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
-      </div>
-    );
-  }
-
-  return (
-    <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto border border-roseFill'>
-      <h1 className='flex gap-2 text-sm mbs-2 text-rose-500'>{error.message}</h1>
-      <pre className='overflow-auto text-xs text-description'>{error.stack}</pre>
-      <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
-    </div>
-  );
-};
-
 /**
  * @internal
  */
 export const useSurfaces = () => {
-  const surfaces = useCapabilities(Common.Capability.ReactSurface);
+  const surfaces = useCapabilities(Capabilities.ReactSurface);
   return useMemo(() => surfaces.flat(), [surfaces]);
 };
 
@@ -259,9 +239,9 @@ export const useSurfaces = () => {
  */
 export const isSurfaceAvailable = (
   capabilityManager: CapabilityManager.CapabilityManager,
-  { role, data }: Pick<Common.SurfaceProps, 'role' | 'data'>,
+  { role, data }: Pick<Props, 'role' | 'data'>,
 ) => {
-  const surfaces = capabilityManager.getAll(Common.Capability.ReactSurface);
+  const surfaces = capabilityManager.getAll(Capabilities.ReactSurface);
   const candidates = findCandidates(surfaces.flat(), { role, data });
   return candidates.length > 0;
 };

package/src/{react → ui/components/Surface}/SurfaceInfo.tsx

@@ -16,7 +16,7 @@ import { createPortal } from 'react-dom';
 import { addEventListener, combine } from '@dxos/async';
 import { useMergeRefs } from '@dxos/react-hooks';
 
-import { useSurface } from './Surface';
+import { useSurface } from '../../hooks';
 
 export type SurfaceInfoProps = {
   children: ReactElement<{ ref?: Ref<HTMLElement> }>;
@@ -76,7 +76,7 @@ export const SurfaceInfo = forwardRef<HTMLElement, SurfaceInfoProps>(({ children
           >
             {expand ? (
               <div
-                className='absolute inset-0 bg-deckSurface border border-green-500 cursor-pointer pointer-events-auto overflow-auto'
+                className='absolute inset-0 bg-deck-surface border border-green-500 cursor-pointer pointer-events-auto overflow-auto'
                 onPointerDown={(ev) => ev.stopPropagation()}
                 onClick={(ev) => {
                   ev.stopPropagation();

package/src/ui/components/Surface/context.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Context, createContext } from 'react';
+
+import { type Props } from './types';
+
+export type SurfaceContext = Pick<Props, 'id' | 'role' | 'data'>;
+
+// TODO(burdon): Use @radix-ui/react-context
+export const SurfaceContext: Context<SurfaceContext | undefined> = createContext<SurfaceContext | undefined>(undefined);