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

package/src/{common/surface.ts → ui/components/Surface/types.ts}

@@ -2,41 +2,39 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { PropsWithChildren, ReactNode, RefCallback } from 'react';
+import type { FC, PropsWithChildren, ReactNode, RefCallback } from 'react';
 
 import type { MakeOptional, Position } from '@dxos/util';
 
-import type { ErrorBoundary } from '../react';
-
 /**
- * SurfaceProps are the props that are passed to the Surface component.
+ * Props that are passed to the Surface component.
  */
-export type SurfaceProps<T extends Record<string, any> = Record<string, unknown>> = {
+export type Props<T extends Record<string, any> = Record<string, unknown>> = {
   /**
    * If specified, the Surface will be wrapped in an error boundary.
    * The fallback component will be rendered if an error occurs.
    */
-  fallback?: ErrorBoundary['props']['fallback'];
+  fallback?: FC<{ error: Error; data?: any }>;
 
   /**
    * If specified, the Surface will be wrapped in a suspense boundary.
    * The placeholder component will be rendered while the surface component is loading.
    */
   placeholder?: ReactNode;
-} & MakeOptional<CoreSurfaceProps<T>, 'id' | 'data'> &
+} & MakeOptional<CoreProps<T>, 'id' | 'data'> &
   /**
    * Additional props to pass to the component.
    * These props are not used by Surface itself but may be used by components which resolve the surface.
    * Exclude known prop names to prevent overriding well-defined props.
    */
   {
-    [K in keyof Record<string, any>]: K extends keyof CoreSurfaceProps<T> | 'fallback' | 'placeholder' ? never : any;
+    [K in keyof Record<string, any>]: K extends keyof CoreProps<T> | 'fallback' | 'placeholder' ? never : any;
   };
 
 /**
  * NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
  */
-export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
+export type CoreProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
   /**
    * ID for debugging.
    */
@@ -59,33 +57,34 @@ export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unkn
   limit?: number | undefined;
 }>;
 
-export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> & {
+// TODO(burdon): Remove ref since relying on this would be error prone.
+export type ComponentProps<T extends Record<string, any> = Record<string, any>> = CoreProps<T> & {
   ref?: RefCallback<HTMLElement>;
 } & Record<string, any>;
 
 /**
  * React component used to render a surface once is has matched.
  */
-export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = (
-  props: SurfaceComponentProps<T>,
+export type ComponentFunction<T extends Record<string, any> = Record<string, any>> = (
+  props: ComponentProps<T>,
 ) => ReactNode;
 
 /**
- * Definition of when a React SurfaceComponent should be rendered.
+ * Definition of when a React component surface should be rendered.
  */
-export type ReactSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+export type ReactDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'react';
   id: string;
   role: string | string[];
   position?: Position;
-  component: SurfaceComponent<T>;
+  component: ComponentFunction<T>;
   filter?: (data: Record<string, unknown>) => data is T;
 }>;
 
 /**
  * Definition of when a Web Component surface should be rendered.
  */
-export type WebComponentSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+export type WebComponentDefinition<T extends Record<string, any> = any> = Readonly<{
   kind: 'web-component';
   id: string;
   role: string | string[];
@@ -101,20 +100,18 @@ export type WebComponentSurfaceDefinition<T extends Record<string, any> = any> =
 /**
  * Definition of when a surface (React or Web Component) should be rendered.
  */
-export type SurfaceDefinition<T extends Record<string, any> = any> =
-  | ReactSurfaceDefinition<T>
-  | WebComponentSurfaceDefinition<T>;
+export type Definition<T extends Record<string, any> = any> = ReactDefinition<T> | WebComponentDefinition<T>;
 
 /**
  * Creates a React surface definition.
  */
-export const createSurface = <T extends Record<string, any> = any>(
-  definition: Omit<ReactSurfaceDefinition<T>, 'kind'>,
-): ReactSurfaceDefinition<T> => ({ ...definition, kind: 'react' });
+export const create = <T extends Record<string, any> = any>(
+  definition: Omit<ReactDefinition<T>, 'kind'>,
+): ReactDefinition<T> => ({ ...definition, kind: 'react' });
 
 /**
  * Creates a Web Component surface definition.
  */
-export const createWebSurface = <T extends Record<string, any> = any>(
-  definition: Omit<WebComponentSurfaceDefinition<T>, 'kind'>,
-): WebComponentSurfaceDefinition<T> => ({ ...definition, kind: 'web-component' });
+export const createWeb = <T extends Record<string, any> = any>(
+  definition: Omit<WebComponentDefinition<T>, 'kind'>,
+): WebComponentDefinition<T> => ({ ...definition, kind: 'web-component' });

package/src/ui/components/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './App';
+export * from './PluginManager';
+export * from './Surface';

package/src/ui/hooks/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useApp';
+export * from './useCapabilities';
+export * from './useLoading';
+export * from './useSettingsState';
+export * from './useSurface';

package/src/ui/hooks/useApp.test.tsx

@@ -0,0 +1,159 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { assert, describe, it } from '@effect/vitest';
+import { render, waitFor } from '@testing-library/react';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { ActivationEvents, Capabilities } from '../../common';
+import { Capability, Plugin, PluginManager } from '../../core';
+import { useApp } from './useApp';
+
+const String = Capability.make<{ string: string }>('org.dxos.test.string');
+const testMeta = { id: 'org.dxos.plugin.test', name: 'Test' };
+
+const pluginLoader = (plugins: Plugin.Plugin[]) =>
+  Effect.fn(function* (id: string) {
+    const plugin = plugins.find((plugin) => plugin.meta.id === id);
+    if (!plugin) {
+      return yield* Effect.fail(new Error(`Plugin not found: ${id}`));
+    }
+    return plugin;
+  });
+
+const TestHost = ({ manager }: { manager: PluginManager.PluginManager }) => {
+  const App = useApp({ pluginManager: manager });
+  return <App />;
+};
+
+describe('useApp cleanup integration', () => {
+  it.effect('external manager is not shut down when useApp does not own it', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      manager.capabilities.contribute({
+        interface: Capabilities.AtomRegistry,
+        implementation: manager.registry,
+        module: 'org.dxos.app-framework.atom-registry',
+      });
+
+      const view = yield* Effect.promise(() => Promise.resolve(render(<TestHost manager={manager} />)));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* Effect.promise(() => Promise.resolve(view.unmount()));
+      yield* Effect.promise(() =>
+        waitFor(() => {
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+          assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+          assert.isTrue(manager.getActive().length > 0);
+        }),
+      );
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.PluginManager).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(Capabilities.AtomRegistry).length, 1);
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+
+  it.effect('shutdown deactivates modules and clears bookkeeping', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      manager.capabilities.contribute({
+        interface: Capabilities.AtomRegistry,
+        implementation: manager.registry,
+        module: 'org.dxos.app-framework.atom-registry',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 1);
+      assert.isTrue(manager.getActive().length > 0);
+
+      yield* manager.shutdown();
+
+      assert.strictEqual(manager.capabilities.getAll(String).length, 0);
+      assert.deepStrictEqual(manager.getActive(), []);
+      assert.deepStrictEqual(manager.getEventsFired(), []);
+    }),
+  );
+
+  it.effect('shutdown is idempotent when called multiple times', () =>
+    Effect.gen(function* () {
+      const plugin = Plugin.define(testMeta).pipe(
+        Plugin.addModule({
+          id: 'Hello',
+          activatesOn: ActivationEvents.Startup,
+          activate: () => Effect.succeed(Capability.contributes(String, { string: 'hello' })),
+        }),
+        Plugin.make,
+      )();
+
+      const manager = PluginManager.make({
+        pluginLoader: pluginLoader([plugin]),
+        plugins: [plugin],
+      });
+
+      manager.capabilities.contribute({
+        interface: Capabilities.PluginManager,
+        implementation: manager,
+        module: 'org.dxos.app-framework.plugin-manager',
+      });
+      yield* manager.activate(ActivationEvents.Startup);
+
+      yield* manager.shutdown();
+      assert.deepStrictEqual(manager.getActive(), []);
+
+      // Second shutdown should succeed without error.
+      const result = yield* manager.shutdown();
+      assert.isTrue(result);
+      assert.deepStrictEqual(manager.getActive(), []);
+    }),
+  );
+});

package/src/{react → ui/hooks}/useApp.tsx

@@ -12,19 +12,32 @@ import React, { type FC, useCallback, useEffect, useMemo, useRef, useState } fro
 import { runAndForwardErrors } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
+import { ErrorBoundary, ErrorFallback, type FallbackProps } from '@dxos/react-error-boundary';
 import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
 import { ContextProtocolProvider } from '@dxos/web-context-react';
 
-import * as Common from '../common';
-import { PluginManagerContext } from '../context';
-import { type Plugin, PluginManager } from '../core';
+import { ActivationEvents, Capabilities } from '../../common';
+import { PluginManagerContext } from '../../context';
+import { type ActivationEvent, type Plugin, PluginManager } from '../../core';
+import { App, PluginManagerProvider } from '../components';
 
-import { App } from './App';
-import { DefaultFallback } from './DefaultFallback';
-import { ErrorBoundary } from './ErrorBoundary';
-import { PluginManagerProvider } from './PluginManagerProvider';
+const ENABLED_KEY = 'org.dxos.app-framework.enabled';
 
-const ENABLED_KEY = 'dxos.org/app-framework/enabled';
+export type StartupProgress = {
+  /** Number of modules that have been activated. */
+  activated: number;
+  /** Total number of modules registered. */
+  total: number;
+  /** Fractional progress (0-1). */
+  progress: number;
+  /** Human-readable label for the currently activating module. */
+  status?: string;
+};
+
+export type PlaceholderProps = {
+  stage?: number;
+  progress?: StartupProgress;
+};
 
 export type UseAppOptions = {
   pluginManager?: PluginManager.PluginManager;
@@ -32,12 +45,17 @@ export type UseAppOptions = {
   plugins?: Plugin.Plugin[];
   core?: string[];
   defaults?: string[];
-  placeholder?: FC<{ stage: number }>;
-  fallback?: ErrorBoundary['props']['fallback'];
+  /**
+   * Additional activation events to fire before startup.
+   * These are fired alongside SetupReactSurface before the Startup event.
+   */
+  setupEvents?: ActivationEvent.ActivationEvent[];
   cacheEnabled?: boolean;
   safeMode?: boolean;
   debounce?: number;
   timeout?: number;
+  fallback?: FC<FallbackProps>;
+  placeholder?: FC<PlaceholderProps>;
 };
 
 /**
@@ -60,10 +78,10 @@ export type UseAppOptions = {
  * @param params.plugins All plugins available to the application.
  * @param params.core Core plugins which will always be enabled.
  * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
- * @param params.placeholder Placeholder component to render during startup.
- * @param params.fallback Fallback component to render if an error occurs during startup.
  * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
  * @param params.safeMode Whether to enable safe mode, which disables optional plugins.
+ * @param params.fallback Fallback component to render if an error occurs during startup.
+ * @param params.placeholder Placeholder component to render during startup.
  */
 export const useApp = ({
   pluginManager,
@@ -71,8 +89,9 @@ export const useApp = ({
   plugins: pluginsProp,
   core: coreProp,
   defaults: defaultsProp,
+  setupEvents: setupEventsProp,
   placeholder,
-  fallback = DefaultFallback,
+  fallback = ErrorFallback,
   cacheEnabled = false,
   safeMode = false,
   debounce = 0,
@@ -81,8 +100,8 @@ export const useApp = ({
   const plugins = useDefaultValue(pluginsProp, () => []);
   const core = useDefaultValue(coreProp, () => plugins.map(({ meta }) => meta.id));
   const defaults = useDefaultValue(defaultsProp, () => []);
+  const setupEvents = useDefaultValue(setupEventsProp, () => []);
 
-  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
   const pluginLoader = useMemo(
     () =>
       pluginLoaderProp ??
@@ -99,16 +118,23 @@ export const useApp = ({
   const [ready, setReady] = useState(false);
   const errorRef = useRef<unknown>(null);
   const [error, setError] = useState<unknown>(null);
+  const [startupProgress, setStartupProgress] = useState<StartupProgress>({
+    activated: 0,
+    total: 0,
+    progress: 0,
+  });
   // TODO(wittjosiah): Migrate to Atom.kvs for isomorphic storage.
   const cached: string[] = useMemo(() => JSON.parse(localStorage.getItem(ENABLED_KEY) ?? '[]'), []);
   const enabled = useMemo(
     () => (safeMode ? [] : cacheEnabled && cached.length > 0 ? cached : defaults),
     [safeMode, cacheEnabled, cached, defaults],
   );
-  const manager = useMemo(
-    () => pluginManager ?? PluginManager.make({ pluginLoader, plugins, core, enabled }),
-    [pluginManager, pluginLoader, plugins, core, enabled],
-  );
+  const isExternalManager = !!pluginManager;
+  const manager = useMemo(() => {
+    const mgr = pluginManager ?? PluginManager.make({ pluginLoader, plugins, core, enabled });
+    log('useApp: useMemo created/reused manager', { provided: !!pluginManager });
+    return mgr;
+  }, [pluginManager, pluginLoader, plugins, core, enabled]);
 
   useEffect(() => {
     if (!cacheEnabled) {
@@ -124,28 +150,52 @@ export const useApp = ({
   }, [manager]);
 
   useAsyncEffect(async () => {
+    log('useApp: effect mount');
+
     manager.capabilities.contribute({
-      interface: Common.Capability.PluginManager,
+      interface: Capabilities.PluginManager,
       implementation: manager,
-      module: 'dxos.org/app-framework/plugin-manager',
+      module: 'org.dxos.app-framework.plugin-manager',
     });
 
     manager.capabilities.contribute({
-      interface: Common.Capability.AtomRegistry,
+      interface: Capabilities.AtomRegistry,
       implementation: manager.registry,
-      module: 'dxos.org/app-framework/atom-registry',
+      module: 'org.dxos.app-framework.atom-registry',
     });
 
+    // Poll manager atoms for progress (avoids PubSub subscription race).
+    const progressInterval = setInterval(() => {
+      if (readyRef.current) {
+        clearInterval(progressInterval);
+        return;
+      }
+      const active = manager.getActive();
+      const modules = manager.getModules();
+      const total = modules.length;
+      const activated = active.length;
+      const lastModule = active.length > 0 ? active[active.length - 1] : undefined;
+      setStartupProgress({
+        activated,
+        total,
+        progress: total > 0 ? activated / total : 0,
+        status: lastModule ? humanizeModuleId(lastModule) : undefined,
+      });
+    }, 100);
+
     const fiber = Effect.gen(function* () {
       const queue = yield* PubSub.subscribe(manager.activation);
       const listener = yield* Effect.forkDaemon(
         Queue.take(queue).pipe(
           Effect.tap(({ event, state, error: error$ }) =>
             Effect.sync(() => {
-              if (event === Common.ActivationEvent.Startup.id && state === 'activated') {
+              if (event === ActivationEvents.Startup.id && state === 'activated') {
                 clearTimeout(timeoutId);
+                clearInterval(progressInterval);
                 setReady(true);
                 readyRef.current = true;
+                // Trigger startup profiler dump if available.
+                (globalThis as any).composer?.profiler?.dump();
               }
               if (error$ && !readyRef.current) {
                 setError(error$);
@@ -158,9 +208,9 @@ export const useApp = ({
       );
 
       yield* Effect.all([
-        manager.activate(Common.ActivationEvent.SetupSettings),
-        manager.activate(Common.ActivationEvent.SetupReactSurface),
-        manager.activate(Common.ActivationEvent.Startup),
+        ...setupEvents.map((event) => manager.activate(event)),
+        manager.activate(ActivationEvents.SetupReactSurface),
+        manager.activate(ActivationEvents.Startup),
       ]);
 
       return yield* Fiber.join(listener);
@@ -180,20 +230,29 @@ export const useApp = ({
     }, timeout);
 
     return () => {
+      log('useApp: effect cleanup');
       clearTimeout(timeoutId);
+      clearInterval(progressInterval);
       void runAndForwardErrors(Fiber.interrupt(fiber));
-      manager.capabilities.remove(Common.Capability.PluginManager, manager);
-      manager.capabilities.remove(Common.Capability.AtomRegistry, manager.registry);
+      if (!isExternalManager) {
+        void runAndForwardErrors(manager.shutdown());
+      }
     };
   }, [manager]);
 
   return useCallback(
     () => (
-      <ErrorBoundary fallback={fallback}>
+      <ErrorBoundary name='app' FallbackComponent={fallback}>
         <PluginManagerProvider value={manager}>
           <ContextProtocolProvider value={manager} context={PluginManagerContext}>
             <RegistryContext.Provider value={manager.registry}>
-              <App placeholder={placeholder} ready={ready} error={error} debounce={debounce} />
+              <App
+                placeholder={placeholder}
+                ready={ready}
+                error={error}
+                debounce={debounce}
+                progress={startupProgress}
+              />
             </RegistryContext.Provider>
           </ContextProtocolProvider>
         </PluginManagerProvider>
@@ -207,3 +266,24 @@ const setupDevtools = (manager: PluginManager.PluginManager) => {
   (globalThis as any).composer ??= {};
   (globalThis as any).composer.manager = manager;
 };
+
+/**
+ * Extracts a human-readable label from a module ID.
+ * E.g., "org.dxos.plugin.markdown.module.ReactSurface" → "Markdown".
+ */
+const humanizeModuleId = (moduleId: string): string => {
+  // Extract plugin name from pattern: org.dxos.plugin.<name>.module.<capability>
+  const pluginMatch = moduleId.match(/\.plugin\.([^.]+)\./);
+  if (pluginMatch) {
+    const name = pluginMatch[1];
+    // Convert kebab-case to title case.
+    return name
+      .split('-')
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join(' ');
+  }
+
+  // Fallback: use the last segment.
+  const parts = moduleId.split('.');
+  return parts[parts.length - 1];
+};

package/src/{react → ui/hooks}/useCapabilities.ts

@@ -7,10 +7,9 @@ import { useCallback } from 'react';
 
 import { invariant } from '@dxos/invariant';
 
-import * as Common from '../common';
-import { type Capability } from '../core';
-
-import { usePluginManager } from './PluginManagerProvider';
+import { Capabilities } from '../../common';
+import { type Capability } from '../../core';
+import { usePluginManager } from '../components';
 
 /**
  * Hook to request capabilities from the plugin context.
@@ -50,7 +49,7 @@ export const useAtomCapability = <T>(atomCapability: Capability.InterfaceDef<Ato
 export const useAtomCapabilityState = <T>(
   atomCapability: Capability.InterfaceDef<Atom.Writable<T>>,
 ): [T, (fn: (current: T) => T) => void] => {
-  const registry = useCapability(Common.Capability.AtomRegistry);
+  const registry = useCapability(Capabilities.AtomRegistry);
   const atom = useCapability(atomCapability);
   const value = useAtomValue(atom);
   const update = useCallback(
@@ -61,3 +60,8 @@ export const useAtomCapabilityState = <T>(
   );
   return [value, update];
 };
+
+/**
+ * Hook to get the operation invoker capability.
+ */
+export const useOperationInvoker = (): Capabilities.OperationInvoker => useCapability(Capabilities.OperationInvoker);

package/src/{react/common.ts → ui/hooks/useSettingsState.ts}

@@ -5,17 +5,6 @@
 import { type Atom, RegistryContext, useAtomValue } from '@effect-atom/atom-react';
 import { useCallback, useContext } from 'react';
 
-import * as Common from '../common';
-
-import { useAtomCapability, useCapability } from './useCapabilities';
-
-export const useOperationInvoker = (): Common.Capability.OperationInvoker =>
-  useCapability(Common.Capability.OperationInvoker);
-
-export const useAppGraph = (): Common.Capability.AppGraph => useCapability(Common.Capability.AppGraph);
-
-export const useLayout = (): Common.Capability.Layout => useAtomCapability(Common.Capability.Layout);
-
 /**
  * Hook to read and update a settings atom.
  * Returns the current value and an update function.

package/src/ui/hooks/useSurface.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { Surface } from '../components';
+
+export const useSurface = (): Surface.Context => {
+  return useContext(Surface.Context) ?? raise(new Error('Missing SurfaceContext'));
+};

package/src/ui/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './components';
+export * from './hooks';