@dxos/app-framework 0.8.4-main.7ace549 → 0.8.4-main.937b3ca

package/src/react/useApp.tsx

@@ -3,15 +3,21 @@
 //
 
 import { RegistryContext } from '@effect-atom/atom-react';
-import { effect } from '@preact/signals-core';
-import React, { type FC, useCallback, useEffect, useMemo } from 'react';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
+import React, { type FC, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
+import { runAndForwardErrors } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
-import { live } from '@dxos/live-object';
+import { log } from '@dxos/log';
 import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
+import { ContextProtocolProvider } from '@dxos/web-context-react';
 
-import { Capabilities, Events } from '../common';
-import { type Plugin, PluginManager, type PluginManagerOptions } from '../core';
+import * as Common from '../common';
+import { PluginManagerContext } from '../context';
+import { type Plugin, PluginManager } from '../core';
 
 import { App } from './App';
 import { DefaultFallback } from './DefaultFallback';
@@ -21,9 +27,9 @@ import { PluginManagerProvider } from './PluginManagerProvider';
 const ENABLED_KEY = 'dxos.org/app-framework/enabled';
 
 export type UseAppOptions = {
-  pluginManager?: PluginManager;
-  pluginLoader?: PluginManagerOptions['pluginLoader'];
-  plugins?: Plugin[];
+  pluginManager?: PluginManager.PluginManager;
+  pluginLoader?: PluginManager.ManagerOptions['pluginLoader'];
+  plugins?: Plugin.Plugin[];
   core?: string[];
   defaults?: string[];
   placeholder?: FC<{ stage: number }>;
@@ -31,6 +37,7 @@ export type UseAppOptions = {
   cacheEnabled?: boolean;
   safeMode?: boolean;
   debounce?: number;
+  timeout?: number;
 };
 
 /**
@@ -60,59 +67,55 @@ export type UseAppOptions = {
  */
 export const useApp = ({
   pluginManager,
-  pluginLoader: pluginLoaderParam,
-  plugins: pluginsParam,
-  core: coreParam,
-  defaults: defaultsParam,
+  pluginLoader: pluginLoaderProp,
+  plugins: pluginsProp,
+  core: coreProp,
+  defaults: defaultsProp,
   placeholder,
   fallback = DefaultFallback,
   cacheEnabled = false,
   safeMode = false,
   debounce = 0,
+  timeout = 30_000,
 }: UseAppOptions) => {
-  const plugins = useDefaultValue(pluginsParam, () => []);
-  const core = useDefaultValue(coreParam, () => plugins.map(({ meta }) => meta.id));
-  const defaults = useDefaultValue(defaultsParam, () => []);
+  const plugins = useDefaultValue(pluginsProp, () => []);
+  const core = useDefaultValue(coreProp, () => plugins.map(({ meta }) => meta.id));
+  const defaults = useDefaultValue(defaultsProp, () => []);
 
   // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
   const pluginLoader = useMemo(
     () =>
-      pluginLoaderParam ??
-      ((id: string) => {
-        const plugin = plugins.find((plugin) => plugin.meta.id === id);
-        invariant(plugin, `Plugin not found: ${id}`);
-        return plugin;
-      }),
-    [pluginLoaderParam, plugins],
+      pluginLoaderProp ??
+      ((id: string) =>
+        Effect.sync(() => {
+          const plugin = plugins.find((plugin) => plugin.meta.id === id);
+          invariant(plugin, `Plugin not found: ${id}`);
+          return plugin;
+        })),
+    [pluginLoaderProp, plugins],
   );
 
-  const state = useMemo(() => live({ ready: false, error: null }), []);
+  const readyRef = useRef(false);
+  const [ready, setReady] = useState(false);
+  const errorRef = useRef<unknown>(null);
+  const [error, setError] = useState<unknown>(null);
+  // 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 ?? new PluginManager({ pluginLoader, plugins, core, enabled }),
+    () => pluginManager ?? PluginManager.make({ pluginLoader, plugins, core, enabled }),
     [pluginManager, pluginLoader, plugins, core, enabled],
   );
 
   useEffect(() => {
-    return manager.activation.on(({ event, state: _state, error }) => {
-      // Once the app is ready the first time, don't show the fallback again.
-      if (!state.ready && event === Events.Startup.id) {
-        state.ready = _state === 'activated';
-      }
-
-      if (error && !state.ready && !state.error) {
-        state.error = error;
-      }
-    });
-  }, [manager, state]);
-
-  useEffect(() => {
-    effect(() => {
-      cacheEnabled && localStorage.setItem(ENABLED_KEY, JSON.stringify(manager.enabled));
+    if (!cacheEnabled) {
+      return;
+    }
+    return manager.registry.subscribe(manager.enabled, (value) => {
+      localStorage.setItem(ENABLED_KEY, JSON.stringify(value));
     });
   }, [cacheEnabled, manager]);
 
@@ -121,27 +124,66 @@ export const useApp = ({
   }, [manager]);
 
   useAsyncEffect(async () => {
-    manager.context.contributeCapability({
-      interface: Capabilities.PluginManager,
+    manager.capabilities.contribute({
+      interface: Common.Capability.PluginManager,
       implementation: manager,
       module: 'dxos.org/app-framework/plugin-manager',
     });
 
-    manager.context.contributeCapability({
-      interface: Capabilities.AtomRegistry,
+    manager.capabilities.contribute({
+      interface: Common.Capability.AtomRegistry,
       implementation: manager.registry,
       module: 'dxos.org/app-framework/atom-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),
-    ]);
+    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') {
+                clearTimeout(timeoutId);
+                setReady(true);
+                readyRef.current = true;
+              }
+              if (error$ && !readyRef.current) {
+                setError(error$);
+                errorRef.current = error$;
+              }
+            }),
+          ),
+          Effect.forever,
+        ),
+      );
+
+      yield* Effect.all([
+        manager.activate(Common.ActivationEvent.SetupSettings),
+        manager.activate(Common.ActivationEvent.SetupReactSurface),
+        manager.activate(Common.ActivationEvent.Startup),
+      ]);
+
+      return yield* Fiber.join(listener);
+    }).pipe(Effect.scoped, Effect.runFork);
+
+    // Set up a timeout for startup.
+    const timeoutId = setTimeout(() => {
+      if (!readyRef.current && !errorRef.current) {
+        log.warn('startup timeout diagnostic', {
+          eventsFired: manager.getEventsFired(),
+          activeModules: manager.getActive(),
+          pendingReset: manager.getPendingReset(),
+        });
+        void runAndForwardErrors(Fiber.interrupt(fiber));
+        setError(new Error(`Startup timed out after ${timeout}ms`));
+      }
+    }, timeout);
 
     return () => {
-      manager.context.removeCapability(Capabilities.PluginManager, manager);
-      manager.context.removeCapability(Capabilities.AtomRegistry, manager.registry);
+      clearTimeout(timeoutId);
+      void runAndForwardErrors(Fiber.interrupt(fiber));
+      manager.capabilities.remove(Common.Capability.PluginManager, manager);
+      manager.capabilities.remove(Common.Capability.AtomRegistry, manager.registry);
     };
   }, [manager]);
 
@@ -149,17 +191,19 @@ export const useApp = ({
     () => (
       <ErrorBoundary fallback={fallback}>
         <PluginManagerProvider value={manager}>
-          <RegistryContext.Provider value={manager.registry}>
-            <App placeholder={placeholder} state={state} debounce={debounce} />
-          </RegistryContext.Provider>
+          <ContextProtocolProvider value={manager} context={PluginManagerContext}>
+            <RegistryContext.Provider value={manager.registry}>
+              <App placeholder={placeholder} ready={ready} error={error} debounce={debounce} />
+            </RegistryContext.Provider>
+          </ContextProtocolProvider>
         </PluginManagerProvider>
       </ErrorBoundary>
     ),
-    [fallback, manager, placeholder, state],
+    [fallback, manager, placeholder, ready, error],
   );
 };
 
-const setupDevtools = (manager: PluginManager) => {
+const setupDevtools = (manager: PluginManager.PluginManager) => {
   (globalThis as any).composer ??= {};
   (globalThis as any).composer.manager = manager;
 };

package/src/react/useCapabilities.ts

@@ -2,11 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useAtomValue } from '@effect-atom/atom-react';
+import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import { useCallback } from 'react';
 
 import { invariant } from '@dxos/invariant';
 
-import { type InterfaceDef } from '../core';
+import * as Common from '../common';
+import { type Capability } from '../core';
 
 import { usePluginManager } from './PluginManagerProvider';
 
@@ -14,9 +16,9 @@ import { usePluginManager } from './PluginManagerProvider';
  * Hook to request capabilities from the plugin context.
  * @returns An array of capabilities.
  */
-export const useCapabilities = <T>(interfaceDef: InterfaceDef<T>) => {
+export const useCapabilities = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
   const manager = usePluginManager();
-  return useAtomValue(manager.context.capabilities(interfaceDef));
+  return useAtomValue(manager.capabilities.atom(interfaceDef));
 };
 
 /**
@@ -24,8 +26,38 @@ export const useCapabilities = <T>(interfaceDef: InterfaceDef<T>) => {
  * @returns The capability.
  * @throws If no capability is found.
  */
-export const useCapability = <T>(interfaceDef: InterfaceDef<T>) => {
+export const useCapability = <T>(interfaceDef: Capability.InterfaceDef<T>) => {
   const capabilities = useCapabilities(interfaceDef);
   invariant(capabilities.length > 0, `No capability found for ${interfaceDef.identifier}`);
   return capabilities[0];
 };
+
+/**
+ * Hook to get the current value of an atom capability.
+ * Automatically subscribes to changes.
+ * @example const settings = useAtomCapability(ThreadCapabilities.Settings);
+ */
+export const useAtomCapability = <T>(atomCapability: Capability.InterfaceDef<Atom.Atom<T>>): T => {
+  const atom = useCapability(atomCapability);
+  return useAtomValue(atom);
+};
+
+/**
+ * Hook to get value and updater for an atom capability.
+ * Returns [currentValue, updateFn] similar to useState.
+ * @example const [settings, updateSettings] = useAtomCapabilityState(ThreadCapabilities.Settings);
+ */
+export const useAtomCapabilityState = <T>(
+  atomCapability: Capability.InterfaceDef<Atom.Writable<T>>,
+): [T, (fn: (current: T) => T) => void] => {
+  const registry = useCapability(Common.Capability.AtomRegistry);
+  const atom = useCapability(atomCapability);
+  const value = useAtomValue(atom);
+  const update = useCallback(
+    (fn: (current: T) => T) => {
+      registry.set(atom, fn(registry.get(atom)));
+    },
+    [registry, atom],
+  );
+  return [value, update];
+};

package/src/react/useLoading.tsx

@@ -4,8 +4,6 @@
 
 import { useEffect, useState } from 'react';
 
-import { type AppProps } from './App';
-
 export enum LoadingState {
   Loading = 0,
   FadeIn = 1,
@@ -23,7 +21,7 @@ export enum LoadingState {
  * 2: Fade-out  - Fade out the loading animation.
  * 3: Done      - Remove the placeholder.
  */
-export const useLoading = (state: AppProps['state'], debounce = 0) => {
+export const useLoading = (ready: boolean, debounce = 0) => {
   const [stage, setStage] = useState<LoadingState>(LoadingState.Loading);
   useEffect(() => {
     if (!debounce) {
@@ -34,7 +32,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
       setStage((stage) => {
         switch (stage) {
           case LoadingState.Loading: {
-            if (!state.ready) {
+            if (!ready) {
               return LoadingState.FadeIn;
             } else {
               clearInterval(i);
@@ -43,7 +41,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
           }
 
           case LoadingState.FadeIn: {
-            if (state.ready) {
+            if (ready) {
               return LoadingState.FadeOut;
             }
             break;
@@ -63,7 +61,7 @@ export const useLoading = (state: AppProps['state'], debounce = 0) => {
   }, [debounce]);
 
   if (!debounce) {
-    return state.ready ? LoadingState.Done : LoadingState.Loading;
+    return ready ? LoadingState.Done : LoadingState.Loading;
   }
 
   return stage;

package/src/react/useOperationResolver.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useMemo } from 'react';
+
+import * as Common from '../common';
+import { usePluginManager } from '../react';
+
+/**
+ * Hook to dynamically register an operation resolver (handler) within a React component.
+ * The resolver is added when the component mounts and removed when it unmounts.
+ *
+ * @example
+ * ```tsx
+ * const scrollHandler = useMemo(() => OperationResolver.make({
+ *   operation: LayoutOperation.ScrollIntoView,
+ *   handler: (input) => Effect.sync(() => {
+ *     // Handle scroll
+ *   }),
+ * }), [deps]);
+ *
+ * useOperationResolver(meta.id, scrollHandler);
+ * ```
+ */
+export const useOperationResolver = (module: string, resolver: Common.Capability.OperationResolver) => {
+  const manager = usePluginManager();
+  // Wrap single resolver in array as the capability expects an array.
+  const resolverArray = useMemo(() => [resolver], [resolver]);
+
+  useEffect(() => {
+    manager.capabilities.contribute({
+      module,
+      interface: Common.Capability.OperationResolver,
+      implementation: resolverArray,
+    });
+
+    return () => manager.capabilities.remove(Common.Capability.OperationResolver, resolverArray);
+  }, [module, resolverArray]);
+};

package/src/testing/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './service';
 export * from './withPluginManager';

package/src/testing/service.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { invariant } from '@dxos/invariant';
+
+import * as Common from '../common';
+import { Plugin, PluginManager } from '../core';
+
+/**
+ * Creates a Plugin.Service layer from a list of plugins.
+ * This is primarily used for testing.
+ */
+export const fromPlugins = (plugins: Plugin.Plugin[]) =>
+  Layer.effect(
+    Plugin.Service,
+    Effect.gen(function* () {
+      // TODO(wittjosiah): Try to dedupe logic between here, createCliApp and useApp.
+
+      const pluginLoader = (id: string) =>
+        Effect.sync(() => {
+          const plugin = plugins.find((plugin) => plugin.meta.id === id);
+          invariant(plugin, `Plugin not found: ${id}`);
+          return plugin;
+        });
+
+      const manager = PluginManager.make({
+        pluginLoader,
+        plugins,
+        core: plugins.map((plugin) => plugin.meta.id),
+      });
+
+      manager.capabilities.contribute({
+        interface: Common.Capability.PluginManager,
+        implementation: manager,
+        module: 'dxos.org/app-framework/plugin-manager',
+      });
+
+      manager.capabilities.contribute({
+        interface: Common.Capability.AtomRegistry,
+        implementation: manager.registry,
+        module: 'dxos.org/app-framework/atom-registry',
+      });
+
+      yield* manager.activate(Common.ActivationEvent.Startup);
+
+      return manager;
+    }),
+  );

package/src/testing/withPluginManager.stories.tsx

@@ -7,8 +7,8 @@ import React from 'react';
 
 import { withTheme } from '@dxos/react-ui/testing';
 
-import { Capabilities, createSurface } from '../common';
-import { contributes } from '../core';
+import * as Common from '../common';
+import { Capability } from '../core';
 import { Surface } from '../react';
 
 import { withPluginManager } from './withPluginManager';
@@ -30,9 +30,9 @@ const meta = {
     withTheme,
     withPluginManager({
       capabilities: [
-        contributes(
-          Capabilities.ReactSurface,
-          createSurface({
+        Capability.contributes(
+          Common.Capability.ReactSurface,
+          Common.createSurface({
             id: 'test',
             role: 'main',
             component: ({ role }) => <span>{JSON.stringify({ role })}</span>,

package/src/testing/withPluginManager.tsx

@@ -3,22 +3,15 @@
 //
 
 import { type Decorator, type StoryContext } from '@storybook/react';
+import * as Effect from 'effect/Effect';
 import React, { useEffect, useMemo } from 'react';
 
 import { raise } from '@dxos/debug';
 import { useAsyncEffect } from '@dxos/react-hooks';
 import { type MaybeProvider, getProviderValue } from '@dxos/util';
 
-import { Capabilities, Events } from '../common';
-import {
-  type ActivationEvent,
-  type AnyCapability,
-  type PluginContext,
-  PluginManager,
-  contributes,
-  defineModule,
-  definePlugin,
-} from '../core';
+import * as Common from '../common';
+import { type ActivationEvent, Capability, type CapabilityManager, Plugin, PluginManager } from '../core';
 import { type UseAppOptions, useApp } from '../react';
 
 /**
@@ -30,16 +23,16 @@ export const setupPluginManager = ({
   core = plugins.map(({ meta }) => meta.id),
   ...options
 }: UseAppOptions & Pick<WithPluginManagerOptions, 'capabilities'> = {}) => {
-  const pluginManager = new PluginManager({
+  const pluginManager = PluginManager.make({
     pluginLoader: () => raise(new Error('Not implemented')),
-    plugins: [StoryPlugin(), ...plugins],
+    plugins: [StoryPlugin, ...plugins],
     core: [StoryPlugin.meta.id, ...core],
     ...options,
   });
 
   if (capabilities) {
-    getProviderValue(capabilities, pluginManager.context).forEach((capability) => {
-      pluginManager.context.contributeCapability({
+    getProviderValue(capabilities, pluginManager.capabilities).forEach((capability) => {
+      pluginManager.capabilities.contribute({
         interface: capability.interface,
         implementation: capability.implementation,
         module: 'story',
@@ -52,9 +45,9 @@ export const setupPluginManager = ({
 
 export type WithPluginManagerOptions = UseAppOptions & {
   /** @deprecated */
-  capabilities?: MaybeProvider<AnyCapability[], PluginContext>;
+  capabilities?: MaybeProvider<Capability.Any[], CapabilityManager.CapabilityManager>;
   /** @deprecated */
-  fireEvents?: (ActivationEvent | string)[];
+  fireEvents?: (ActivationEvent.ActivationEvent | string)[];
 };
 
 export type WithPluginManagerInitializer<Args = void> =
@@ -72,18 +65,18 @@ export const withPluginManager = <Args,>(init: WithPluginManagerInitializer<Args
 
     // Set-up root capability.
     useEffect(() => {
-      const capability = contributes(Capabilities.ReactRoot, {
+      const capability = Capability.contributes(Common.Capability.ReactRoot, {
         id: context.id,
         root: () => <Story />,
       });
 
-      pluginManager.context.contributeCapability({
+      pluginManager.capabilities.contribute({
         ...capability,
         module: 'dxos.org/app-framework/withPluginManager',
       });
 
       return () => {
-        pluginManager.context.removeCapability(capability.interface, capability.implementation);
+        pluginManager.capabilities.remove(capability.interface, capability.implementation);
       };
     }, [pluginManager, context]);
 
@@ -106,6 +99,11 @@ const storyMeta = {
 
 // No-op plugin to ensure there exists at least one plugin for the startup event.
 // This is necessary because `createApp` expects the startup event to complete before the app is ready.
-const StoryPlugin = definePlugin(storyMeta, () => [
-  defineModule({ id: storyMeta.id, activatesOn: Events.Startup, activate: () => [] }),
-]);
+const StoryPlugin = Plugin.define(storyMeta).pipe(
+  Plugin.addModule({
+    id: 'Story',
+    activatesOn: Common.ActivationEvent.Startup,
+    activate: () => Effect.succeed([]),
+  }),
+  Plugin.make,
+)();

package/tsconfig.json

@@ -15,13 +15,13 @@
       "path": "../../common/debug"
     },
     {
-      "path": "../../common/invariant"
+      "path": "../../common/effect"
     },
     {
-      "path": "../../common/keys"
+      "path": "../../common/invariant"
     },
     {
-      "path": "../../common/local-storage"
+      "path": "../../common/keys"
     },
     {
       "path": "../../common/log"
@@ -32,9 +32,18 @@
     {
       "path": "../../common/storybook-utils"
     },
+    {
+      "path": "../../common/test-utils"
+    },
     {
       "path": "../../common/util"
     },
+    {
+      "path": "../../common/web-context"
+    },
+    {
+      "path": "../../common/web-context-react"
+    },
     {
       "path": "../../core/ai"
     },
@@ -48,16 +57,16 @@
       "path": "../../core/echo/echo"
     },
     {
-      "path": "../../core/echo/echo-signals"
+      "path": "../../core/echo/echo-db"
     },
     {
-      "path": "../../core/echo/live-object"
+      "path": "../../core/functions"
     },
     {
-      "path": "../../core/functions"
+      "path": "../../core/operation"
     },
     {
-      "path": "../../ui/primitives/react-hooks"
+      "path": "../../ui/react-primitives/react-hooks"
     },
     {
       "path": "../../ui/react-ui"
@@ -66,7 +75,7 @@
       "path": "../../ui/react-ui-syntax-highlighter"
     },
     {
-      "path": "../../ui/react-ui-theme"
+      "path": "../../ui/ui-theme"
     },
     {
       "path": "../app-graph"