@dxos/app-framework 0.8.4-main.bc674ce → 0.8.4-main.bcb3aa67d6

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

@@ -6,15 +6,16 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { forwardRef, useCallback, useEffect, useRef, useState } from 'react';
 
 import { faker } from '@dxos/random';
-import { List, ListItem, Toolbar } from '@dxos/react-ui';
-import { withTheme } from '@dxos/react-ui/testing';
+import { List, ListItem, Panel, Toolbar } from '@dxos/react-ui';
+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,17 @@ const DefaultStory = () => {
   }, [ref]);
 
   return (
-    <div className='flex flex-col bs-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'>
+    <Panel.Root>
+      <Panel.Toolbar asChild>
+        <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>
+      </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} />
+        <div className='overflow-y-auto h-full'>
           <List>
             {surfaces.map((surface) => (
               <ListItem.Root key={surface.id} id={surface.id}>
@@ -120,15 +124,15 @@ const DefaultStory = () => {
             ))}
           </List>
         </div>
-      </div>
-    </div>
+      </Panel.Content>
+    </Panel.Root>
   );
 };
 
 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,42 @@
 //
 
 import React, {
-  type Context,
   Fragment,
   type NamedExoticComponent,
+  Profiler,
   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';
-
-const DEFAULT_PLACEHOLDER = <Fragment />;
+import { useSurfaceProfilerCallback } from './SurfaceProfilerContext';
+import { type Definition, type Props, type WebComponentDefinition } from './types';
 
 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);
+const DEFAULT_PLACEHOLDER = <Fragment />;
 
 /**
  * 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 +49,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 +88,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 +106,18 @@ 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]);
+      const onProfilerRender = useSurfaceProfilerCallback();
+      const profilerId = `surface/${id}/${role}`;
 
       // 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,11 +140,17 @@ 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}>
-                  <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                  {onProfilerRender && !profilerId.includes('org.dxos.plugin.debug') ? (
+                    <Profiler id={profilerId} onRender={onProfilerRender}>
+                      <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                    </Profiler>
+                  ) : (
+                    <Component id={id} role={role} data={data} limit={limit} {...rest} />
+                  )}
                 </SurfaceInfo>
               </SurfaceContext.Provider>
             </div>
@@ -151,7 +159,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 +173,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 +215,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 +236,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 +249,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/SurfaceProfilerContext.tsx

@@ -0,0 +1,207 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, {
+  type Context,
+  type PropsWithChildren,
+  type ProfilerOnRenderCallback,
+  createContext,
+  useContext,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+} from 'react';
+
+const MAX_ENTRIES = 500;
+
+/**
+ * Single profiler record captured from React Profiler onRender callback.
+ */
+export type SurfaceProfilerEntry = {
+  id: string;
+  phase: 'mount' | 'update' | 'nested-update';
+  actualDuration: number;
+  baseDuration: number;
+  startTime: number;
+  commitTime: number;
+  timestamp: number;
+};
+
+/**
+ * Aggregated stats for a single profiled surface.
+ */
+export type SurfaceProfilerStats = {
+  id: string;
+  mountCount: number;
+  updateCount: number;
+  totalRenders: number;
+  avgActualDuration: number;
+  maxActualDuration: number;
+  avgBaseDuration: number;
+  lastActualDuration: number;
+  lastCommitTime: number;
+};
+
+/**
+ * Store that collects profiler entries and notifies subscribers.
+ */
+class SurfaceProfilerStore {
+  private _entries: SurfaceProfilerEntry[] = [];
+  private _listeners = new Set<() => void>();
+  private _snapshot: readonly SurfaceProfilerEntry[] = [];
+  private _pendingNotify = false;
+
+  /** Records an entry and schedules a deferred notification to avoid re-render loops. */
+  record(entry: SurfaceProfilerEntry) {
+    this._entries.push(entry);
+    if (this._entries.length > MAX_ENTRIES) {
+      this._entries = this._entries.slice(-MAX_ENTRIES);
+    }
+    this._snapshot = [...this._entries];
+    this._scheduleNotify();
+  }
+
+  clear() {
+    this._entries = [];
+    this._snapshot = [];
+    this._notifySync();
+  }
+
+  subscribe = (listener: () => void) => {
+    this._listeners.add(listener);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  };
+
+  getSnapshot = (): readonly SurfaceProfilerEntry[] => {
+    return this._snapshot;
+  };
+
+  /**
+   * Defers notification to the next animation frame to break the
+   * Profiler onRender → record → notify → re-render → onRender loop.
+   */
+  private _scheduleNotify() {
+    if (!this._pendingNotify) {
+      this._pendingNotify = true;
+      requestAnimationFrame(() => {
+        this._pendingNotify = false;
+        this._notifySync();
+      });
+    }
+  }
+
+  private _notifySync() {
+    for (const listener of this._listeners) {
+      listener();
+    }
+  }
+}
+
+type SurfaceProfilerContextValue = {
+  store: SurfaceProfilerStore;
+};
+
+const SurfaceProfilerContext: Context<SurfaceProfilerContextValue | undefined> = createContext<
+  SurfaceProfilerContextValue | undefined
+>(undefined);
+
+/**
+ * Provider that collects React Profiler data from Surface components.
+ */
+export const SurfaceProfilerProvider = ({ children }: PropsWithChildren) => {
+  const storeRef = useRef<SurfaceProfilerStore>(null);
+  if (!storeRef.current) {
+    storeRef.current = new SurfaceProfilerStore();
+  }
+  return (
+    <SurfaceProfilerContext.Provider value={{ store: storeRef.current }}>{children}</SurfaceProfilerContext.Provider>
+  );
+};
+
+/**
+ * Returns a stable onRender callback for use with React Profiler.
+ */
+export const useSurfaceProfilerCallback = (): ProfilerOnRenderCallback | undefined => {
+  const store = useContext(SurfaceProfilerContext)?.store;
+  return useMemo<ProfilerOnRenderCallback | undefined>(() => {
+    if (!store) {
+      return undefined;
+    }
+    return (id, phase, actualDuration, baseDuration, startTime, commitTime) => {
+      store.record({
+        id,
+        phase,
+        actualDuration,
+        baseDuration,
+        startTime,
+        commitTime,
+        timestamp: Date.now(),
+      });
+    };
+  }, [store]);
+};
+
+/**
+ * Returns all profiler entries reactively.
+ */
+export const useSurfaceProfilerEntries = (): readonly SurfaceProfilerEntry[] => {
+  const context = useContext(SurfaceProfilerContext);
+  return useSyncExternalStore(context?.store.subscribe ?? noop, context?.store.getSnapshot ?? emptySnapshot);
+};
+
+/**
+ * Returns aggregated stats grouped by surface id.
+ */
+export const useSurfaceProfilerStats = (): SurfaceProfilerStats[] => {
+  const entries = useSurfaceProfilerEntries();
+  const statsMap = new Map<string, SurfaceProfilerStats>();
+
+  for (const entry of entries) {
+    let stats = statsMap.get(entry.id);
+    if (!stats) {
+      stats = {
+        id: entry.id,
+        mountCount: 0,
+        updateCount: 0,
+        totalRenders: 0,
+        avgActualDuration: 0,
+        maxActualDuration: 0,
+        avgBaseDuration: 0,
+        lastActualDuration: 0,
+        lastCommitTime: 0,
+      };
+      statsMap.set(entry.id, stats);
+    }
+
+    if (entry.phase === 'mount') {
+      stats.mountCount++;
+    } else {
+      stats.updateCount++;
+    }
+    stats.totalRenders++;
+    stats.avgActualDuration =
+      (stats.avgActualDuration * (stats.totalRenders - 1) + entry.actualDuration) / stats.totalRenders;
+    stats.avgBaseDuration =
+      (stats.avgBaseDuration * (stats.totalRenders - 1) + entry.baseDuration) / stats.totalRenders;
+    stats.maxActualDuration = Math.max(stats.maxActualDuration, entry.actualDuration);
+    stats.lastActualDuration = entry.actualDuration;
+    stats.lastCommitTime = entry.commitTime;
+  }
+
+  return [...statsMap.values()].sort((a, b) => b.maxActualDuration - a.maxActualDuration);
+};
+
+/**
+ * Clears all collected profiler entries.
+ */
+export const useSurfaceProfilerClear = (): (() => void) | undefined => {
+  const store = useContext(SurfaceProfilerContext)?.store;
+  return useMemo(() => (store ? () => store.clear() : undefined), [store]);
+};
+
+const noop = () => () => {};
+const EMPTY_SNAPSHOT: readonly SurfaceProfilerEntry[] = [];
+const emptySnapshot = () => EMPTY_SNAPSHOT;

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);

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

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// TODO(wittjosiah): Cleanup to avoid re-naming.
+import { SurfaceContext } from './context';
+import { SurfaceComponent, isSurfaceAvailable } from './SurfaceComponent';
+import {
+  SurfaceProfilerProvider,
+  useSurfaceProfilerCallback,
+  useSurfaceProfilerClear,
+  useSurfaceProfilerEntries,
+  useSurfaceProfilerStats,
+} from './SurfaceProfilerContext';
+import { type Definition as SurfaceDefinition, create as createSurface, createWeb as createWebSurface } from './types';
+
+export namespace Surface {
+  export type Definition = SurfaceDefinition;
+  export const create = createSurface;
+  export const createWeb = createWebSurface;
+
+  export type Context = SurfaceContext;
+  export const Context = SurfaceContext;
+
+  export const Surface = SurfaceComponent;
+  export const isAvailable = isSurfaceAvailable;
+
+  export const ProfilerProvider = SurfaceProfilerProvider;
+  export const useProfilerCallback = useSurfaceProfilerCallback;
+  export const useProfilerEntries = useSurfaceProfilerEntries;
+  export const useProfilerStats = useSurfaceProfilerStats;
+  export const useProfilerClear = useSurfaceProfilerClear;
+}
+
+export type { SurfaceProfilerEntry, SurfaceProfilerStats } from './SurfaceProfilerContext';