@dxos/app-framework 0.9.0 → 0.9.1-main.c7dcc2e112

package/src/core/url-loader.ts

@@ -59,7 +59,7 @@ export type PreloadOptions = Options & {
  *
  * `url` is the URL of the plugin manifest (`plugin.json`), not the entry module.
  */
-export type RemotePluginEntry = {
+export type RemotePluginView = {
   id: string;
   url: string;
   /** Installed version string, e.g. `v1.0.0`. Populated after install from a community catalog entry. */
@@ -71,22 +71,26 @@ const defaultStorage = (): Storage => ({
   set: (key, value) => localStorage.setItem(key, value),
 });
 
-const getPersistedRemotePlugins = (storage: Storage, key: string): RemotePluginEntry[] => {
+const getPersistedRemotePlugins = (storage: Storage, key: string): RemotePluginView[] => {
   try {
     const parsed: unknown = JSON.parse(storage.get(key) ?? '[]');
     if (!Array.isArray(parsed)) {
       return [];
     }
     return parsed.filter(
-      (entry): entry is RemotePluginEntry =>
-        typeof entry === 'object' && entry !== null && typeof entry.id === 'string' && typeof entry.url === 'string',
+      (entry): entry is RemotePluginView =>
+        typeof entry === 'object' &&
+        entry !== null &&
+        typeof entry.id === 'string' &&
+        typeof entry.url === 'string' &&
+        (entry.version === undefined || typeof entry.version === 'string'),
     );
   } catch {
     return [];
   }
 };
 
-const persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginEntry): void => {
+const persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginView): void => {
   try {
     const entries = getPersistedRemotePlugins(storage, key).filter((existing) => existing.id !== entry.id);
     entries.push(entry);
@@ -132,7 +136,7 @@ export const isLocalUrl = (locator: string): boolean => {
  * Useful for UI code that needs to know which loaded plugins were installed from a URL
  * (e.g. to surface a tag on remote or localhost-hosted plugins).
  */
-export const getRemoteEntries = (options: Options = {}): readonly RemotePluginEntry[] => {
+export const getRemoteEntries = (options: Options = {}): readonly RemotePluginView[] => {
   const storage = options.storage ?? defaultStorage();
   const key = options.key ?? DEFAULT_KEY;
   return getPersistedRemotePlugins(storage, key);
@@ -196,14 +200,14 @@ const loadStylesheets = (
     }
     const cssUrls = manifest.assetUrls.filter((url) => url.endsWith('.css'));
     for (const url of cssUrls) {
-      const resolved = yield* cache.resolve(manifest.id, url);
-      if (document.querySelector(`link[data-dxos-plugin-id="${manifest.id}"][href="${resolved}"]`)) {
+      const resolved = yield* cache.resolve(manifest.key, url);
+      if (document.querySelector(`link[data-dxos-plugin-id="${manifest.key}"][href="${resolved}"]`)) {
         continue;
       }
       const link = document.createElement('link');
       link.rel = 'stylesheet';
       link.href = resolved;
-      link.dataset.dxosPluginId = manifest.id;
+      link.dataset.dxosPluginId = manifest.key;
       document.head.appendChild(link);
     }
   });
@@ -233,30 +237,30 @@ const loadFromManifest = (
       // plugin's host is offline, dropping the plugin from the runtime.
       const cachedUrls =
         manifest.assetUrls.indexOf(manifestUrl) === -1 ? [manifestUrl, ...manifest.assetUrls] : manifest.assetUrls;
-      yield* cache.cache(manifest.id, cachedUrls).pipe(wrapCacheError);
+      yield* cache.cache(manifest.key, cachedUrls).pipe(wrapCacheError);
     }
     const entryUrl = manifest.dev
       ? manifest.entryUrl
-      : yield* cache.resolve(manifest.id, manifest.entryUrl).pipe(wrapCacheError);
+      : yield* cache.resolve(manifest.key, manifest.entryUrl).pipe(wrapCacheError);
     const mod = yield* Effect.tryPromise({
       try: () => import(/* @vite-ignore */ entryUrl),
       catch: (cause) =>
         new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'import-failed' }, cause }),
     });
     const plugin = normalizePluginExport(mod);
-    if (!plugin.meta.id || !plugin.meta.name) {
+    if (!plugin.meta.profile.key || !plugin.meta.profile.name) {
       return yield* Effect.fail(
         new RemotePluginLoadError({ context: { locator: manifestUrl, reason: 'meta-missing' } }),
       );
     }
-    if (plugin.meta.id !== manifest.id) {
+    if (plugin.meta.profile.key !== manifest.key) {
       return yield* Effect.fail(
         new RemotePluginLoadError({
           context: {
             locator: manifestUrl,
             reason: 'meta-mismatch',
-            metaId: plugin.meta.id,
-            manifestId: manifest.id,
+            metaId: plugin.meta.profile.key,
+            manifestId: manifest.key,
           },
         }),
       );
@@ -337,7 +341,7 @@ export const make = (builtinPlugins: Plugin.Plugin[], options: Options = {}) =>
 
   return (locator: string): Effect.Effect<{ plugin: Plugin.Plugin; dev?: boolean }, RemotePluginLoadError> =>
     Effect.gen(function* () {
-      const builtin = builtinPlugins.find((plugin) => plugin.meta.id === locator);
+      const builtin = builtinPlugins.find((plugin) => plugin.meta.profile.key === locator);
       if (builtin) {
         return { plugin: builtin };
       }
@@ -351,13 +355,13 @@ export const make = (builtinPlugins: Plugin.Plugin[], options: Options = {}) =>
       // overlap (dev plugin takes the id slot for the session, original is
       // restored on uninstall or page reload).
       if (!manifest.dev) {
-        const duplicate = builtinPlugins.find((existing) => existing.meta.id === plugin.meta.id);
+        const duplicate = builtinPlugins.find((existing) => existing.meta.profile.key === plugin.meta.profile.key);
         if (duplicate) {
           return yield* Effect.fail(
-            new RemotePluginLoadError({ context: { locator, reason: 'duplicate-id', id: plugin.meta.id } }),
+            new RemotePluginLoadError({ context: { locator, reason: 'duplicate-id', id: plugin.meta.profile.key } }),
           );
         }
-        persistRemotePlugin(storage, key, { id: plugin.meta.id, url: locator });
+        persistRemotePlugin(storage, key, { id: plugin.meta.profile.key, url: locator });
       }
       return { plugin, dev: manifest.dev };
     });

package/src/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './common';
+export * from './config';
 export * from './context';
 export * from './core';
 export * from './plugin-process-manager';

package/src/testing/harness.ts

@@ -17,7 +17,7 @@ import { ActivationEvent, type Capability, type CapabilityManager, type Plugin,
 
 export type TestAppOptions = {
   /**
-   * Plugins to register. Plugins whose `meta.tags` includes `'system'` are treated as core
+   * Plugins to register. Plugins whose `meta.profile.tags` includes `'system'` are treated as core
    * (force-enabled). For test convenience, plugins without a `'system'` tag are enabled by
    * default unless `enabled` is provided.
    */
@@ -97,7 +97,9 @@ const DEFAULT_TIMEOUT_MS = 5_000;
 export const createTestApp = async (opts: TestAppOptions): Promise<TestHarness> => {
   const {
     plugins,
-    enabled = plugins.filter(({ meta }) => !meta.tags?.includes('system')).map((plugin) => plugin.meta.id),
+    enabled = plugins
+      .filter(({ meta }) => !meta.profile.tags?.includes('system'))
+      .map((plugin) => plugin.meta.profile.key),
     setupEvents = [],
     autoStart = true,
     registerFrameworkCapabilities = true,
@@ -105,7 +107,7 @@ export const createTestApp = async (opts: TestAppOptions): Promise<TestHarness>
 
   const pluginLoader = (id: string) =>
     Effect.sync(() => {
-      const plugin = plugins.find((plugin) => plugin.meta.id === id);
+      const plugin = plugins.find((plugin) => plugin.meta.profile.key === id);
       invariant(plugin, `Plugin not found: ${id}`);
       return { plugin };
     });

package/src/testing/react.test.tsx

@@ -16,6 +16,8 @@ import { render, renderSurface } from './react';
 
 const testMeta = Plugin.makeMeta({ key: DXN.make('org.dxos.plugin.test.reactHarness'), name: 'ReactHarnessTest' });
 
+const GreetingRole = Surface.makeType<{ message: string }>('org.dxos.test.role.greeting');
+
 const TestPlugin = Plugin.define(testMeta).pipe(
   Plugin.addModule({
     id: 'surfaces',
@@ -25,7 +27,7 @@ const TestPlugin = Plugin.define(testMeta).pipe(
         Capability.contributes(Capabilities.ReactSurface, [
           Surface.create<{ message: string }>({
             id: 'greeting',
-            role: 'greeting',
+            filter: Surface.makeFilter(GreetingRole),
             component: ({ data }) => <span data-testid='greeting'>hello {data.message}</span>,
           }),
         ]),
@@ -43,7 +45,7 @@ describe('testing/react', () => {
 
   test('renderSurface mounts a surface registered by a plugin', async ({ expect }) => {
     await using harness = await createTestApp({ plugins: [TestPlugin()] });
-    const view = renderSurface(harness, { role: 'greeting', data: { message: 'plugins' } });
+    const view = renderSurface(harness, { type: GreetingRole, data: { message: 'plugins' } });
     const node = await view.findByTestId('greeting');
     expect(node.textContent).toBe('hello plugins');
   });

package/src/testing/react.tsx

@@ -13,6 +13,7 @@ import { PluginManagerContext } from '../context';
 import { topologicalSort } from '../helpers';
 import { PluginManagerProvider } from '../ui/components/PluginManager/PluginManagerProvider';
 import { SurfaceComponent } from '../ui/components/Surface/SurfaceComponent';
+import { type RoleToken } from '../ui/components/Surface/types';
 import { type TestHarness } from './harness';
 
 export type HarnessRenderOptions = Omit<RenderOptions, 'wrapper'> & {
@@ -34,26 +35,26 @@ export const render = (harness: TestHarness, ui: ReactNode, options?: HarnessRen
   return rtlRender(<>{ui}</>, { ...rest, wrapper: Wrapper });
 };
 
-export type RenderSurfaceProps = {
-  role: string;
-  data?: unknown;
+export type RenderSurfaceProps<TToken extends RoleToken<any>> = {
+  type: TToken;
+  data?: TToken extends RoleToken<infer D> ? D : never;
   limit?: number;
   fallback?: FC<{ error: Error; data?: any }>;
   placeholder?: ReactNode;
 };
 
 /**
- * Renders a `Surface` with the given role/data inside the harness provider tree.
+ * Renders a `Surface` with the given role token/data inside the harness provider tree.
  */
-export const renderSurface = (
+export const renderSurface = <TToken extends RoleToken<any>>(
   harness: TestHarness,
-  props: RenderSurfaceProps,
+  props: RenderSurfaceProps<TToken>,
   options?: HarnessRenderOptions,
 ): RenderResult => {
-  const { role, data, limit, fallback, placeholder } = props;
+  const { type, data, limit, fallback, placeholder } = props;
   return render(
     harness,
-    <SurfaceComponent role={role} data={data as any} limit={limit} fallback={fallback} placeholder={placeholder} />,
+    <SurfaceComponent type={type} data={data as any} limit={limit} fallback={fallback} placeholder={placeholder} />,
     options,
   );
 };

package/src/testing/service.ts

@@ -22,7 +22,7 @@ export const fromPlugins = (plugins: Plugin.Plugin[]) =>
 
       const pluginLoader = (id: string) =>
         Effect.sync(() => {
-          const plugin = plugins.find((plugin) => plugin.meta.id === id);
+          const plugin = plugins.find((plugin) => plugin.meta.profile.key === id);
           invariant(plugin, `Plugin not found: ${id}`);
           return { plugin };
         });
@@ -30,7 +30,7 @@ export const fromPlugins = (plugins: Plugin.Plugin[]) =>
       const manager = PluginManager.make({
         pluginLoader,
         plugins,
-        enabled: plugins.map((plugin) => plugin.meta.id),
+        enabled: plugins.map((plugin) => plugin.meta.profile.key),
       });
 
       manager.capabilities.contribute({

package/src/testing/withPluginManager.stories.tsx

@@ -12,12 +12,14 @@ import { Capability } from '../core';
 import { Surface } from '../ui';
 import { withPluginManager } from './withPluginManager';
 
+const MainRole = Surface.makeType<Record<string, never>>('org.dxos.test.role.main');
+
 const DefaultStory = () => {
   console.log('Render');
   return (
     <div>
       <div>Hello</div>
-      <Surface.Surface role='main' />
+      <Surface.Surface type={MainRole} />
     </div>
   );
 };
@@ -33,7 +35,7 @@ const meta = {
           Capabilities.ReactSurface,
           Surface.create({
             id: 'test',
-            role: 'main',
+            filter: Surface.makeFilter(MainRole),
             component: ({ role }) => <span>{JSON.stringify({ role })}</span>,
           }),
         ),

package/src/testing/withPluginManager.tsx

@@ -26,7 +26,9 @@ export const setupPluginManager = ({
 }: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
   // Auto-enable every non-system plugin so stories don't have to spell out
   // enablement. System-tagged plugins are force-enabled by the manager.
-  const enabled = plugins.filter(({ meta }) => !meta.tags?.includes('system')).map(({ meta }) => meta.id);
+  const enabled = plugins
+    .filter(({ meta }) => !meta.profile.tags?.includes('system'))
+    .map(({ meta }) => meta.profile.key);
   const pluginManager = PluginManager.make({
     pluginLoader: () => raise(new Error('Not implemented')),
     plugins: [StoryPlugin, ...plugins],

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

@@ -16,6 +16,13 @@ const PluginManagerContext = createContext<PluginManager.PluginManager | undefin
 export const usePluginManager = (): PluginManager.PluginManager =>
   useContext(PluginManagerContext) ?? raise(new Error('Missing PluginManagerContext'));
 
+/**
+ * Get the plugin manager if present, or `undefined` when rendered outside a {@link PluginManagerProvider}
+ * (e.g. a standalone component story). Lets components treat plugin capabilities as a progressive
+ * enhancement rather than a hard requirement.
+ */
+export const useOptionalPluginManager = (): PluginManager.PluginManager | undefined => useContext(PluginManagerContext);
+
 /**
  * Context provider for a plugin manager.
  */

package/src/ui/components/Surface/SurfaceComponent.stories.tsx

@@ -3,7 +3,7 @@
 //
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 
 import { random } from '@dxos/random';
 import { List, ListItem, Panel, Toolbar } from '@dxos/react-ui';
@@ -14,23 +14,22 @@ import { Capabilities } from '../../../common';
 import { withPluginManager } from '../../../testing';
 import { usePluginManager } from '../PluginManager';
 import { SurfaceComponent, useSurfaces } from './SurfaceComponent';
-import { create } from './types';
+import { create, makeFilter, makeType } from './types';
+
+const ItemRole = makeType<{ id: string }>('org.dxos.test.role.item');
 
 type TestComponentProps = {
   id: string;
   styles: ColorStyles;
 };
 
-const TestComponent = forwardRef<HTMLDivElement, TestComponentProps>(({ styles, id }, forwardedRef) => {
+const TestComponent = ({ styles, id }: TestComponentProps) => {
   return (
-    <div
-      className={mx('flex justify-center items-center border rounded-sm', styles.surface, styles.border)}
-      ref={forwardedRef}
-    >
+    <div className={mx('flex justify-center items-center border rounded-sm', styles.surface, styles.border)}>
       <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
     </div>
   );
-});
+};
 
 const DefaultStory = () => {
   const manager = usePluginManager();
@@ -46,9 +45,8 @@ const DefaultStory = () => {
       interface: Capabilities.ReactSurface,
       implementation: create({
         id,
-        role: 'item',
-        filter: (data): data is any => (data as any)?.id === id,
-        component: ({ ref }) => <TestComponent id={id} styles={styles} ref={ref} />,
+        filter: makeFilter(ItemRole, (data) => data.id === id),
+        component: () => <TestComponent id={id} styles={styles} />,
       }),
     });
 
@@ -65,8 +63,7 @@ const DefaultStory = () => {
       interface: Capabilities.ReactSurface,
       implementation: create({
         id: 'error',
-        role: 'item',
-        filter: (data): data is any => (data as any)?.id === 'error',
+        filter: makeFilter(ItemRole, (data) => data.id === 'error'),
         component: () => {
           const [count, setCount] = useState(3);
           useEffect(() => {
@@ -113,7 +110,7 @@ const DefaultStory = () => {
         </Toolbar.Root>
       </Panel.Toolbar>
       <Panel.Content className='grid grid-cols-2 h-full gap-4 overflow-hidden'>
-        <SurfaceComponent role='item' data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
+        <SurfaceComponent type={ItemRole} data={selected ? { id: selected } : undefined} limit={1} ref={ref} />
         <div className='overflow-y-auto h-full'>
           <List>
             {surfaces.map((surface) => (

package/src/ui/components/Surface/SurfaceComponent.tsx

@@ -4,6 +4,7 @@
 
 import { useAtomValue } from '@effect-atom/atom-react';
 import React, {
+  type FC,
   Fragment,
   type NamedExoticComponent,
   Profiler,
@@ -44,78 +45,95 @@ const DEFAULT_PLACEHOLDER = <Fragment />;
  * Wrapper component for rendering Web Component surfaces.
  * Handles creation, prop setting, and cleanup of Web Components.
  */
+type WebComponentWrapperProps = {
+  id?: string;
+  role: string;
+  data?: Record<string, any>;
+  limit?: number;
+  definition: WebComponentDefinition;
+  [key: string]: any;
+};
+
 const WebComponentWrapper = memo(
-  forwardRef<HTMLElement, Omit<Props, 'role'> & { role: string; definition: WebComponentDefinition }>(
-    ({ id, role, data, limit, definition, ...rest }, forwardedRef) => {
-      const containerRef = useRef<HTMLDivElement>(null);
-      const elementRef = useRef<HTMLElement | null>(null);
-      const propsRef = useRef({ id, role, data, limit, ...rest });
-
-      // Update props ref on every render
-      propsRef.current = { id, role, data, limit, ...rest };
-
-      // Create element only once
-      useEffect(() => {
-        if (!containerRef.current || elementRef.current) {
-          return;
-        }
+  forwardRef<HTMLElement, WebComponentWrapperProps>(({ id, role, data, limit, definition, ...rest }, forwardedRef) => {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const elementRef = useRef<HTMLElement | null>(null);
+    const propsRef = useRef({ id, role, data, limit, ...rest });
+
+    // Update props ref on every render
+    propsRef.current = { id, role, data, limit, ...rest };
+
+    // Create element only once
+    useEffect(() => {
+      if (!containerRef.current || elementRef.current) {
+        return;
+      }
 
-        // Create the Web Component
-        const element = document.createElement(definition.tagName);
-        elementRef.current = element;
+      // Create the Web Component
+      const element = document.createElement(definition.tagName);
+      elementRef.current = element;
 
-        // Set initial properties on the Web Component
-        Object.assign(element, propsRef.current);
+      // Set initial properties on the Web Component
+      Object.assign(element, propsRef.current);
 
-        // Append to container
-        containerRef.current.appendChild(element);
+      // Append to container
+      containerRef.current.appendChild(element);
 
-        // Setup ref forwarding if provided
+      // Setup ref forwarding if provided
+      if (typeof forwardedRef === 'function') {
+        forwardedRef(element);
+      } else if (forwardedRef) {
+        forwardedRef.current = element;
+      }
+
+      // Cleanup on unmount to prevent memory leaks
+      return () => {
+        if (elementRef.current && containerRef.current?.contains(elementRef.current)) {
+          containerRef.current.removeChild(elementRef.current);
+        }
         if (typeof forwardedRef === 'function') {
-          forwardedRef(element);
+          forwardedRef(null);
         } else if (forwardedRef) {
-          forwardedRef.current = element;
-        }
-
-        // Cleanup on unmount to prevent memory leaks
-        return () => {
-          if (elementRef.current && containerRef.current?.contains(elementRef.current)) {
-            containerRef.current.removeChild(elementRef.current);
-          }
-          if (typeof forwardedRef === 'function') {
-            forwardedRef(null);
-          } else if (forwardedRef) {
-            forwardedRef.current = null;
-          }
-          elementRef.current = null;
-        };
-      }, [definition.tagName, forwardedRef]);
-
-      // Update props on existing element without recreating it
-      // 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;
+          forwardedRef.current = null;
         }
+        elementRef.current = null;
+      };
+    }, [definition.tagName, forwardedRef]);
+
+    // Update props on existing element without recreating it
+    // 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;
+      }
 
-        // Update properties on the existing Web Component
-        Object.assign(element, propsRef.current);
-      });
+      // Update properties on the existing Web Component
+      Object.assign(element, propsRef.current);
+    });
 
-      return <div ref={containerRef} />;
-    },
-  ),
+    return <div ref={containerRef} />;
+  }),
 );
 
 WebComponentWrapper.displayName = 'WebComponentWrapper';
 
+type SurfaceContextProviderProps = {
+  id: string;
+  role: string;
+  data?: Record<string, any>;
+  limit?: number;
+  fallback?: FC<{ error: Error; data?: any }>;
+  definition: Definition;
+  [key: string]: any;
+};
+
 /**
  * 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, Omit<Props, 'role'> & { role: string; definition: Definition }>(
+  forwardRef<HTMLElement, SurfaceContextProviderProps>(
     ({ id, role, data, limit, fallback = ErrorFallback, definition, ...rest }, forwardedRef) => {
       const contextValue = useMemo(() => ({ id, role, data }), [id, role, data]);
       const onProfilerRender = useSurfaceProfilerCallback();
@@ -182,11 +200,13 @@ SurfaceContextProvider.displayName = 'SurfaceContextProvider';
 
 /**
  * A surface is a named region of the screen that can be populated by plugins.
+ * The `type` prop is a {@link RoleToken} that defines which region and its
+ * associated data contract.
  */
 // TODO(burdon): Remove `ref` since relying on this would be error prone.
 export const SurfaceComponent = memo(
-  forwardRef<HTMLElement, Props & { type?: RoleToken<any> }>(
-    ({ id: _id, role, type, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
+  forwardRef<HTMLElement, TypedProps<RoleToken<any>>>(
+    ({ id: _id, type, data: dataProp, limit, placeholder = DEFAULT_PLACEHOLDER, ...rest }, forwardedRef) => {
       const data = useDefaultValue(dataProp, () => ({}));
       // TODO(wittjosiah): This will make all surfaces depend on a single signal.
       //   This isn't ideal because it means that any change to the data will cause all surfaces to re-render.
@@ -195,10 +215,10 @@ export const SurfaceComponent = memo(
       //   In the future, it would be nice to be able to bucket the surface contributions by role.
       const surfaces = useSurfaces();
 
-      const effectiveRole = role ?? type?.role;
+      const effectiveRole = type?.role;
       if (effectiveRole == null) {
         if (DEBUG) {
-          log.warn('Surface has neither `role` nor `type` prop', { id: _id });
+          log.warn('Surface is missing required `type` prop', { id: _id });
         }
         return null;
       }
@@ -230,12 +250,12 @@ export const SurfaceComponent = memo(
     },
   ),
 ) as (<TToken extends RoleToken<any>>(props: TypedProps<TToken> & RefAttributes<HTMLElement>) => React.ReactNode) &
-  NamedExoticComponent<Props & RefAttributes<HTMLElement>>;
+  NamedExoticComponent<TypedProps<RoleToken<any>> & RefAttributes<HTMLElement>>;
 
 SurfaceComponent.displayName = 'Surface';
 
 // TODO(burdon): Make user facing, with telemetry.
-const ErrorFallback = ({ error }: Props) => {
+const ErrorFallback = ({ error }: { error: Error }) => {
   const { message } = error instanceof Error ? error : { message: String(error) };
   return (
     <div role='alert' data-testid='error-boundary-fallback'>
@@ -273,31 +293,21 @@ export const useSurfaces = () => {
 /**
  * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
  *
- * Two overloads:
- * - Typed: pass a `type` role token and `data` is constrained to the token's
- *   declared contract (e.g. `AppSurface.Section` requires `attendableId`).
- * - Legacy: pass a string `role` and `data` is untyped.
+ * Typed: pass a `type` role token and `data` is constrained to the token's
+ * declared contract (e.g. `AppSurface.Section` requires `attendableId`).
  */
 export function isSurfaceAvailable<TToken extends RoleToken<any>>(
   capabilityManager: CapabilityManager.CapabilityManager,
-  args: { type: TToken; data?: TokenData<TToken>; role?: never },
-): boolean;
-export function isSurfaceAvailable(
-  capabilityManager: CapabilityManager.CapabilityManager,
-  args: Pick<Props, 'role' | 'data'> & { type?: undefined },
-): boolean;
-export function isSurfaceAvailable(
-  capabilityManager: CapabilityManager.CapabilityManager,
-  { role, type, data }: { role?: string; type?: RoleToken<any>; data?: unknown },
+  args: { type: TToken; data?: TokenData<TToken> },
 ): boolean {
-  const effectiveRole = role ?? type?.role;
+  const effectiveRole = args.type?.role;
   if (effectiveRole == null) {
     return false;
   }
   const surfaces = capabilityManager.getAll(Capabilities.ReactSurface);
   const candidates = findCandidates(surfaces.flat(), {
     role: effectiveRole,
-    data: data as Props['data'],
+    data: args.data as Props['data'],
   });
   return candidates.length > 0;
 }

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

@@ -4,9 +4,12 @@
 
 import { type Context, createContext } from 'react';
 
-import { type Props } from './types';
-
-export type SurfaceContext = Pick<Props, 'id' | 'role' | 'data'>;
+export type SurfaceContext = {
+  id?: string;
+  /** The resolved role NSID (e.g. `org.dxos.role.article`). */
+  role: string;
+  data?: Record<string, any>;
+};
 
 // TODO(burdon): Use @radix-ui/react-context
 export const SurfaceContext: Context<SurfaceContext | undefined> = createContext<SurfaceContext | undefined>(undefined);