@dxos/app-framework 0.8.4-main.84f28bd → 0.8.4-main.ae835ea

package/src/{App.tsx → components/useApp.tsx}

@@ -4,20 +4,22 @@
 
 import { RegistryContext } from '@effect-rx/rx-react';
 import { effect } from '@preact/signals-core';
-import React, { useCallback, useEffect, useMemo, useState, type FC, type PropsWithChildren } from 'react';
+import React, { type FC, useCallback, useEffect, useMemo } from 'react';
 
 import { invariant } from '@dxos/invariant';
 import { live } from '@dxos/live-object';
-import { useDefaultValue } from '@dxos/react-hooks';
+import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
 
-import { Capabilities, Events } from './common';
-import { PluginManager, type PluginManagerOptions, type Plugin } from './core';
-import { topologicalSort } from './helpers';
-import { ErrorBoundary, PluginManagerProvider, useCapabilities } from './react';
+import { Capabilities, Events } from '../common';
+import { type Plugin, PluginManager, type PluginManagerOptions } from '../core';
+import { ErrorBoundary, PluginManagerProvider } from '../react';
+
+import { App } from './App';
+import { DefaultFallback } from './DefaultFallback';
 
 const ENABLED_KEY = 'dxos.org/app-framework/enabled';
 
-export type CreateAppOptions = {
+export type UseAppOptions = {
   pluginManager?: PluginManager;
   pluginLoader?: PluginManagerOptions['pluginLoader'];
   plugins?: Plugin[];
@@ -27,6 +29,7 @@ export type CreateAppOptions = {
   fallback?: ErrorBoundary['props']['fallback'];
   cacheEnabled?: boolean;
   safeMode?: boolean;
+  debounce?: number;
 };
 
 /**
@@ -38,7 +41,7 @@ export type CreateAppOptions = {
  * const core = [LayoutPluginId];
  * const default = [MyPluginId];
  * const fallback = <div>Initializing Plugins...</div>;
- * const App = createApp({ plugins, core, default, fallback });
+ * const App = useApp({ plugins, core, default, fallback });
  * createRoot(document.getElementById('root')!).render(
  *   <StrictMode>
  *     <App />
@@ -64,7 +67,8 @@ export const useApp = ({
   fallback = DefaultFallback,
   cacheEnabled = false,
   safeMode = false,
-}: CreateAppOptions) => {
+  debounce = 0,
+}: UseAppOptions) => {
   const plugins = useDefaultValue(_plugins, () => []);
   const core = useDefaultValue(_core, () => plugins.map(({ meta }) => meta.id));
   const defaults = useDefaultValue(_defaults, () => []);
@@ -112,6 +116,10 @@ export const useApp = ({
   }, [cacheEnabled, manager]);
 
   useEffect(() => {
+    setupDevtools(manager);
+  }, [manager]);
+
+  useAsyncEffect(async () => {
     manager.context.contributeCapability({
       interface: Capabilities.PluginManager,
       implementation: manager,
@@ -124,34 +132,24 @@ export const useApp = ({
       module: 'dxos.org/app-framework/rx-registry',
     });
 
+    await Promise.all([
+      // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
+      manager.activate(Events.SetupReactSurface),
+      manager.activate(Events.Startup),
+    ]);
+
     return () => {
       manager.context.removeCapability(Capabilities.PluginManager, manager);
       manager.context.removeCapability(Capabilities.RxRegistry, manager.registry);
     };
   }, [manager]);
 
-  useEffect(() => {
-    setupDevtools(manager);
-  }, [manager]);
-
-  useEffect(() => {
-    const timeout = setTimeout(async () => {
-      await Promise.all([
-        // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
-        manager.activate(Events.SetupReactSurface),
-        manager.activate(Events.Startup),
-      ]);
-    });
-
-    return () => clearTimeout(timeout);
-  }, [manager]);
-
   return useCallback(
     () => (
       <ErrorBoundary fallback={fallback}>
         <PluginManagerProvider value={manager}>
           <RegistryContext.Provider value={manager.registry}>
-            <App placeholder={placeholder} state={state} />
+            <App placeholder={placeholder} state={state} debounce={debounce} />
           </RegistryContext.Provider>
         </PluginManagerProvider>
       </ErrorBoundary>
@@ -160,116 +158,6 @@ export const useApp = ({
   );
 };
 
-const DELAY_PLACEHOLDER = 2_000;
-
-enum LoadingState {
-  Loading = 0,
-  FadeIn = 1,
-  FadeOut = 2,
-  Done = 3,
-}
-
-/**
- * To avoid "flashing" the placeholder, we wait a period of time before starting the loading animation.
- * If loading completes during this time the placehoder is not shown, otherwise is it displayed for a minimum period of time.
- *
- * States:
- * 0: Loading   - Wait for a period of time before starting the loading animation.
- * 1: Fade-in   - Display a loading animation.
- * 2: Fade-out  - Fade out the loading animation.
- * 3: Done      - Remove the placeholder.
- */
-const useLoading = (state: AppProps['state']) => {
-  const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
-  useEffect(() => {
-    const i = setInterval(() => {
-      setStage((tick) => {
-        switch (tick) {
-          case LoadingState.Loading:
-            if (!state.ready) {
-              return LoadingState.FadeIn;
-            } else {
-              clearInterval(i);
-              return LoadingState.Done;
-            }
-          case LoadingState.FadeIn:
-            if (state.ready) {
-              return LoadingState.FadeOut;
-            }
-            break;
-          case LoadingState.FadeOut:
-            clearInterval(i);
-            return LoadingState.Done;
-        }
-
-        return tick;
-      });
-    }, DELAY_PLACEHOLDER);
-
-    return () => clearInterval(i);
-  }, []);
-
-  return stage;
-};
-
-type AppProps = Pick<CreateAppOptions, 'placeholder'> & {
-  state: { ready: boolean; error: unknown };
-};
-
-const App = ({ placeholder: Placeholder, state }: AppProps) => {
-  const reactContexts = useCapabilities(Capabilities.ReactContext);
-  const reactRoots = useCapabilities(Capabilities.ReactRoot);
-  const stage = useLoading(state);
-
-  if (state.error) {
-    // This triggers the error boundary to provide UI feedback for the startup error.
-    throw state.error;
-  }
-
-  // TODO(wittjosiah): Consider using Suspense instead?
-  if (stage < LoadingState.Done) {
-    if (!Placeholder) {
-      return null;
-    }
-
-    return <Placeholder stage={stage} />;
-  }
-
-  const ComposedContext = composeContexts(reactContexts);
-  return (
-    <ComposedContext>
-      {reactRoots.map(({ id, root: Component }) => (
-        <Component key={id} />
-      ))}
-    </ComposedContext>
-  );
-};
-
-// Default fallback does not use tailwind or theme.
-const DefaultFallback = ({ error }: { error: Error }) => {
-  return (
-    <div style={{ margin: '0.5rem', padding: '1rem', overflow: 'hidden', border: '1px solid red' }}>
-      {/* TODO(wittjosiah): Link to docs for replacing default. */}
-      <h1 style={{ margin: '0.5rem 0', fontSize: '1.2rem' }}>[ERROR]: {error.message}</h1>
-      <pre style={{ overflow: 'auto', fontSize: '1rem' }}>{error.stack}</pre>
-    </div>
-  );
-};
-
-const composeContexts = (contexts: Capabilities.ReactContext[]) => {
-  if (contexts.length === 0) {
-    return ({ children }: PropsWithChildren) => <>{children}</>;
-  }
-
-  return topologicalSort(contexts)
-    .map(({ context }) => context)
-    .reduce((Acc, Next) => ({ children }) => (
-      <Acc>
-        <Next>{children}</Next>
-      </Acc>
-    ));
-};
-
 const setupDevtools = (manager: PluginManager) => {
   (globalThis as any).composer ??= {};
   (globalThis as any).composer.manager = manager;

package/src/components/useLoading.tsx

@@ -0,0 +1,70 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useState } from 'react';
+
+import { type AppProps } from './App';
+
+export enum LoadingState {
+  Loading = 0,
+  FadeIn = 1,
+  FadeOut = 2,
+  Done = 3,
+}
+
+/**
+ * To avoid "flashing" the placeholder, we wait a period of time before starting the loading animation.
+ * If loading completes during this time the placehoder is not shown, otherwise is it displayed for a minimum period of time.
+ *
+ * States:
+ * 0: Loading   - Wait for a period of time before starting the loading animation.
+ * 1: Fade-in   - Display a loading animation.
+ * 2: Fade-out  - Fade out the loading animation.
+ * 3: Done      - Remove the placeholder.
+ */
+export const useLoading = (state: AppProps['state'], debounce = 0) => {
+  const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
+  useEffect(() => {
+    if (!debounce) {
+      return;
+    }
+
+    const i = setInterval(() => {
+      setStage((stage) => {
+        switch (stage) {
+          case LoadingState.Loading: {
+            if (!state.ready) {
+              return LoadingState.FadeIn;
+            } else {
+              clearInterval(i);
+              return LoadingState.Done;
+            }
+          }
+
+          case LoadingState.FadeIn: {
+            if (state.ready) {
+              return LoadingState.FadeOut;
+            }
+            break;
+          }
+
+          case LoadingState.FadeOut: {
+            clearInterval(i);
+            return LoadingState.Done;
+          }
+        }
+
+        return stage;
+      });
+    }, debounce);
+
+    return () => clearInterval(i);
+  }, [debounce]);
+
+  if (!debounce) {
+    return state.ready ? LoadingState.Done : LoadingState.Loading;
+  }
+
+  return stage;
+};

package/src/core/capabilities.test.ts

@@ -3,10 +3,10 @@
 //
 
 import { Registry } from '@effect-rx/rx-react';
-import { Effect } from 'effect';
+import * as Effect from 'effect/Effect';
 import { describe, expect, it, onTestFinished } from 'vitest';
 
-import { defineCapability, PluginContext } from './capabilities';
+import { PluginContext, defineCapability } from './capabilities';
 
 const defaultOptions = {
   activate: () => Effect.succeed(false),

package/src/core/capabilities.ts

@@ -3,7 +3,7 @@
 //
 
 import { type Registry, Rx } from '@effect-rx/rx-react';
-import { Effect } from 'effect';
+import * as Effect from 'effect/Effect';
 
 import { Trigger } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
@@ -22,6 +22,10 @@ export type InterfaceDef<T> = {
   identifier: string;
 };
 
+export namespace InterfaceDef {
+  export type Implementation<I extends InterfaceDef<any>> = I extends InterfaceDef<infer T> ? T : never;
+}
+
 /**
  * Helper to define the interface of a capability.
  */
@@ -37,12 +41,12 @@ export type Capability<T> = {
   /**
    * The interface definition of the capability.
    */
-  interface: InterfaceDef<T>;
+  readonly interface: InterfaceDef<T>;
 
   /**
    * The implementation of the capability.
    */
-  implementation: T;
+  readonly implementation: T;
 
   /**
    * Called when the capability is deactivated.
@@ -69,16 +73,21 @@ class CapabilityImpl<T> {
 /**
  * Helper to define the implementation of a capability.
  */
-export const contributes = <T>(
-  interfaceDef: Capability<T>['interface'],
-  implementation: Capability<T>['implementation'],
-  deactivate?: Capability<T>['deactivate'],
-): Capability<T> => {
-  return { interface: interfaceDef, implementation, deactivate } satisfies Capability<T>;
+export const contributes = <I extends InterfaceDef<any>, T = InterfaceDef.Implementation<I>>(
+  interfaceDef: I,
+  implementation: T,
+  deactivate?: Capability<InterfaceDef.Implementation<I>>['deactivate'],
+): Capability<I> => {
+  return {
+    interface: interfaceDef,
+    implementation: implementation as any, // NOTE: Added to allow providing readonly implementation.
+    deactivate,
+  } satisfies Capability<I>;
 };
 
 type LoadCapability<T, U> = () => Promise<{ default: (props: T) => MaybePromise<Capability<U>> }>;
 type LoadCapabilities<T> = () => Promise<{ default: (props: T) => MaybePromise<AnyCapability[]> }>;
+
 // TODO(wittjosiah): Not having the array be `any` causes type errors when using the lazy capability.
 type LazyCapability<T, U> = (props?: T) => Promise<() => Promise<Capability<U> | AnyCapability[]>>;
 

package/src/core/manager.test.ts

@@ -7,16 +7,17 @@ import { afterEach, describe, expect, it } from 'vitest';
 
 import { Trigger } from '@dxos/async';
 import { raise } from '@dxos/debug';
-import { updateCounter } from '@dxos/echo-schema/testing';
+import { updateCounter } from '@dxos/echo/testing';
 import { registerSignalsRuntime } from '@dxos/echo-signals';
 import { invariant } from '@dxos/invariant';
 import { live } from '@dxos/live-object';
 
-import { contributes, defineCapability, type PluginContext } from './capabilities';
+import { Events } from '../common';
+
+import { type PluginContext, contributes, defineCapability } from './capabilities';
 import { allOf, defineEvent, oneOf } from './events';
 import { PluginManager } from './manager';
-import { definePlugin, defineModule, type Plugin } from './plugin';
-import { Events } from '../common';
+import { Plugin, defineModule } from './plugin';
 
 registerSignalsRuntime();
 
@@ -42,7 +43,7 @@ describe('PluginManager', () => {
   });
 
   it('should be able to add and remove plugins', async () => {
-    const Test = definePlugin(testMeta, []);
+    const Test = new Plugin(testMeta, []);
     plugins = [Test];
 
     const manager = new PluginManager({ pluginLoader });
@@ -58,7 +59,7 @@ describe('PluginManager', () => {
       activatesOn: Events.Startup,
       activate: () => contributes(String, { string: 'hello' }),
     });
-    const Test = definePlugin(testMeta, [Hello]);
+    const Test = new Plugin(testMeta, [Hello]);
 
     const manager = new PluginManager({ plugins: [Test], core: [], pluginLoader });
     await manager.enable(testMeta.id);
@@ -75,7 +76,7 @@ describe('PluginManager', () => {
       activatesOn: Events.Startup,
       activate: () => contributes(String, { string: 'hello' }),
     });
-    const Test = definePlugin(testMeta, [Hello]);
+    const Test = new Plugin(testMeta, [Hello]);
 
     const manager = new PluginManager({ plugins: [Test], enabled: [Test.meta.id], pluginLoader });
     expect(manager.plugins).toEqual([Test]);
@@ -94,7 +95,7 @@ describe('PluginManager', () => {
       activatesOn: FailEvent,
       activate: async () => raise(new Error('test')),
     });
-    plugins = [definePlugin(testMeta, [Fail])];
+    plugins = [new Plugin(testMeta, [Fail])];
 
     const manager = new PluginManager({ pluginLoader });
     await manager.add(testMeta.id);
@@ -113,7 +114,7 @@ describe('PluginManager', () => {
       // TODO(wittjosiah): Test and catch more failure modes.
       activate: async () => async () => raise(new Error('test')),
     });
-    plugins = [definePlugin(testMeta, [Hello, Fail])];
+    plugins = [new Plugin(testMeta, [Hello, Fail])];
 
     const manager = new PluginManager({ pluginLoader });
     const activating = new Trigger<boolean>();
@@ -148,7 +149,7 @@ describe('PluginManager', () => {
         return contributes(String, { string: 'hello' });
       },
     });
-    plugins = [definePlugin(testMeta, [Hello])];
+    plugins = [new Plugin(testMeta, [Hello])];
 
     const manager = new PluginManager({ pluginLoader });
 
@@ -179,21 +180,21 @@ describe('PluginManager', () => {
   });
 
   it('should be able to fire custom activation events', async () => {
-    const Plugin1 = definePlugin({ id: 'dxos.org/test/plugin-1', name: 'Plugin 1' }, [
+    const Plugin1 = new Plugin({ id: 'dxos.org/test/plugin-1', name: 'Plugin 1' }, [
       defineModule({
         id: 'dxos.org/test/plugin-1',
         activatesOn: CountEvent,
         activate: () => [contributes(Number, { number: 1 })],
       }),
     ]);
-    const Plugin2 = definePlugin({ id: 'dxos.org/test/plugin-2', name: 'Plugin 2' }, [
+    const Plugin2 = new Plugin({ id: 'dxos.org/test/plugin-2', name: 'Plugin 2' }, [
       defineModule({
         id: 'dxos.org/test/plugin-2',
         activatesOn: CountEvent,
         activate: () => [contributes(Number, { number: 2 })],
       }),
     ]);
-    const Plugin3 = definePlugin({ id: 'dxos.org/test/plugin-3', name: 'Plugin 3' }, [
+    const Plugin3 = new Plugin({ id: 'dxos.org/test/plugin-3', name: 'Plugin 3' }, [
       defineModule({
         id: 'dxos.org/test/plugin-3',
         activatesOn: CountEvent,
@@ -230,7 +231,7 @@ describe('PluginManager', () => {
         return contributes(String, { string: 'hello' });
       },
     });
-    plugins = [definePlugin(testMeta, [Hello])];
+    plugins = [new Plugin(testMeta, [Hello])];
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
@@ -256,7 +257,7 @@ describe('PluginManager', () => {
         return contributes(String, { string: 'hello' });
       },
     });
-    plugins = [definePlugin(testMeta, [Hello])];
+    plugins = [new Plugin(testMeta, [Hello])];
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
@@ -282,7 +283,7 @@ describe('PluginManager', () => {
       state.total = numbers.reduce((acc, n) => acc + n.number, 0);
     };
 
-    const Count = definePlugin({ id: 'dxos.org/test/count', name: 'Count' }, [
+    const Count = new Plugin({ id: 'dxos.org/test/count', name: 'Count' }, [
       defineModule({
         id: 'dxos.org/test/count',
         activatesOn: Events.Startup,
@@ -294,7 +295,7 @@ describe('PluginManager', () => {
       }),
     ]);
 
-    const Test = definePlugin(testMeta, [
+    const Test = new Plugin(testMeta, [
       defineModule({
         id: 'dxos.org/test/plugin-1',
         activatesOn: CountEvent,
@@ -352,7 +353,7 @@ describe('PluginManager', () => {
     const id = 'dxos.org/test/counter';
     const stateEvent = Events.createStateEvent(id);
 
-    const Test = definePlugin(testMeta, [
+    const Test = new Plugin(testMeta, [
       defineModule({
         id,
         activatesOn: Events.Startup,
@@ -389,21 +390,21 @@ describe('PluginManager', () => {
   });
 
   it('should be reactive', async () => {
-    const Plugin1 = definePlugin({ id: 'dxos.org/test/plugin-1', name: 'Plugin 1' }, [
+    const Plugin1 = new Plugin({ id: 'dxos.org/test/plugin-1', name: 'Plugin 1' }, [
       defineModule({
         id: 'dxos.org/test/plugin-1',
         activatesOn: CountEvent,
         activate: () => [contributes(Number, { number: 1 })],
       }),
     ]);
-    const Plugin2 = definePlugin({ id: 'dxos.org/test/plugin-2', name: 'Plugin 2' }, [
+    const Plugin2 = new Plugin({ id: 'dxos.org/test/plugin-2', name: 'Plugin 2' }, [
       defineModule({
         id: 'dxos.org/test/plugin-2',
         activatesOn: CountEvent,
         activate: () => [contributes(Number, { number: 2 })],
       }),
     ]);
-    const Plugin3 = definePlugin({ id: 'dxos.org/test/plugin-3', name: 'Plugin 3' }, [
+    const Plugin3 = new Plugin({ id: 'dxos.org/test/plugin-3', name: 'Plugin 3' }, [
       defineModule({
         id: 'dxos.org/test/plugin-3',
         activatesOn: CountEvent,