@dxos/app-framework 0.8.4-main.b97322e → 0.8.4-main.dedc0f3

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

@@ -6,7 +6,7 @@ import { Registry } from '@effect-rx/rx-react';
 import { Effect } from '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

@@ -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.
  */
@@ -69,16 +73,17 @@ 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>>(
+  interfaceDef: I,
+  implementation: Capability<InterfaceDef.Implementation<I>>['implementation'],
+  deactivate?: Capability<InterfaceDef.Implementation<I>>['deactivate'],
+): Capability<I> => {
+  return { interface: interfaceDef, 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

@@ -12,11 +12,12 @@ 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 { type Plugin, defineModule, definePlugin } from './plugin';
 
 registerSignalsRuntime();
 

package/src/core/manager.ts

@@ -4,16 +4,16 @@
 
 import { Registry } from '@effect-rx/rx-react';
 import { untracked } from '@preact/signals-core';
-import { Array as A, Effect, Either, Match, pipe } from 'effect';
+import { Array, Duration, Effect, Fiber, HashSet, Match, Ref, pipe } from 'effect';
 
 import { Event } from '@dxos/async';
-import { live, type Live } from '@dxos/live-object';
+import { type Live, live } from '@dxos/live-object';
 import { log } from '@dxos/log';
 import { type MaybePromise } from '@dxos/util';
 
 import { type AnyCapability, PluginContext } from './capabilities';
 import { type ActivationEvent, eventKey, getEvents, isAllOf } from './events';
-import { type PluginModule, type Plugin } from './plugin';
+import { type Plugin, type PluginModule } from './plugin';
 
 // TODO(wittjosiah): Factor out?
 const isPromise = (value: unknown): value is Promise<unknown> => {
@@ -52,6 +52,9 @@ export class PluginManager {
   private readonly _state: Live<PluginManagerState>;
   private readonly _pluginLoader: PluginManagerOptions['pluginLoader'];
   private readonly _capabilities = new Map<string, AnyCapability[]>();
+  private readonly _moduleMemoMap = new Map<PluginModule['id'], Promise<AnyCapability[]>>();
+  private readonly _activatingEvents = Effect.runSync(Ref.make<string[]>([]));
+  private readonly _activatingModules = Effect.runSync(Ref.make<string[]>([]));
 
   constructor({
     pluginLoader,
@@ -74,8 +77,8 @@ export class PluginManager {
       enabled,
       modules: [],
       active: [],
-      pendingReset: [],
       eventsFired: [],
+      pendingReset: [],
     });
     plugins.forEach((plugin) => this._addPlugin(plugin));
     core.forEach((id) => this.enable(id));
@@ -268,6 +271,7 @@ export class PluginManager {
   private _addPlugin(plugin: Plugin): void {
     untracked(() => {
       log('add plugin', { id: plugin.meta.id });
+      // TODO(wittjosiah): Find a way to add a warning for duplicate plugins that doesn't cause log spam.
       if (!this._state.plugins.includes(plugin)) {
         this._state.plugins.push(plugin);
       }
@@ -287,6 +291,7 @@ export class PluginManager {
   private _addModule(module: PluginModule): void {
     untracked(() => {
       log('add module', { id: module.id });
+      // TODO(wittjosiah): Find a way to add a warning for duplicate modules that doesn't cause log spam.
       if (!this._state.modules.includes(module)) {
         this._state.modules.push(module);
       }
@@ -329,7 +334,7 @@ export class PluginManager {
         .map(eventKey)
         .filter((key) => this._state.eventsFired.includes(key));
 
-      const pendingReset = Array.from(new Set(activationEvents)).filter(
+      const pendingReset = Array.fromIterable(new Set(activationEvents)).filter(
         (event) => !this._state.pendingReset.includes(event),
       );
       if (pendingReset.length > 0) {
@@ -343,24 +348,42 @@ export class PluginManager {
    * @internal
    */
   // TODO(wittjosiah): Improve error typing.
-  _activate(event: ActivationEvent | string): Effect.Effect<boolean, Error> {
+  _activate(
+    event: ActivationEvent | string,
+    params?: { before?: string; after?: string },
+  ): Effect.Effect<boolean, Error> {
     return Effect.gen(this, function* () {
       const key = typeof event === 'string' ? event : eventKey(event);
-      log('activating', { key });
+      log('activating', { key, ...params });
+      yield* Ref.update(this._activatingEvents, (activating) => Array.append(activating, key));
       const pendingIndex = this._state.pendingReset.findIndex((event) => event === key);
       if (pendingIndex !== -1) {
         this._state.pendingReset.splice(pendingIndex, 1);
       }
 
+      const activatingEvents = yield* this._activatingEvents;
+      const activatingModules = yield* this._activatingModules;
       const modules = this._getInactiveModulesByEvent(key).filter((module) => {
         const allOf = isAllOf(module.activatesOn);
         if (!allOf) {
           return true;
         }
 
+        // Check to see if all of the events in the `allOf` have been fired.
+        // An event can be considered "fired" if it is in the `eventsFired` list or if it is currently being activated.
         const events = module.activatesOn.events.filter((event) => eventKey(event) !== key);
-        return events.every((event) => this._state.eventsFired.includes(eventKey(event)));
+        return (
+          events.every(
+            (event) => this._state.eventsFired.includes(eventKey(event)) || activatingEvents.includes(eventKey(event)),
+          ) && !activatingModules.includes(module.id)
+        );
       });
+      yield* Ref.update(this._activatingModules, (activating) =>
+        Array.appendAll(
+          activating,
+          modules.map((module) => module.id),
+        ),
+      );
       if (modules.length === 0) {
         log('no modules to activate', { key });
         if (!this._state.eventsFired.includes(key)) {
@@ -372,31 +395,53 @@ export class PluginManager {
       log('activating modules', { key, modules: modules.map((module) => module.id) });
       this.activation.emit({ event: key, state: 'activating' });
 
+      // Fire activatesBefore events.
+      yield* pipe(
+        modules,
+        Array.flatMap((module) => module.activatesBefore ?? []),
+        HashSet.fromIterable,
+        HashSet.toValues,
+        Array.filter((event) => !activatingEvents.includes(eventKey(event))),
+        Array.map((event) => this._activate(event, { before: key })),
+        Effect.allWith({ concurrency: 'unbounded' }),
+      );
+
       // Concurrently triggers loading of lazy capabilities.
-      const getCapabilities = yield* Effect.all(
-        modules.map(({ activate }) =>
-          Effect.tryPromise({
-            try: async () => activate(this.context),
-            catch: (error) => error as Error,
-          }),
-        ),
-        { concurrency: 'unbounded' },
+      const getCapabilities = yield* pipe(
+        modules,
+        Array.map((mod) => this._loadModule(mod)),
+        Effect.allWith({ concurrency: 'unbounded' }),
+        Effect.catchAll((error) => {
+          this.activation.emit({ event: key, state: 'error', error });
+          return Effect.fail(error);
+        }),
       );
 
-      const result = yield* pipe(
+      // Contribute the capabilities from the activated modules.
+      yield* pipe(
         modules,
-        A.zip(getCapabilities),
-        A.map(([module, getCapabilities]) => this._activateModule(module, getCapabilities)),
+        Array.zip(getCapabilities),
+        Array.map(([module, capabilities]) => this._contributeCapabilities(module, capabilities)),
         // TODO(wittjosiah): This currently can't be run in parallel.
         //   Running this with concurrency causes races with `allOf` activation events.
         Effect.all,
-        Effect.either,
       );
 
-      if (Either.isLeft(result)) {
-        this.activation.emit({ event: key, state: 'error', error: result.left });
-        yield* Effect.fail(result.left);
-      }
+      // Fire activatesAfter events.
+      yield* pipe(
+        modules,
+        Array.flatMap((module) => module.activatesAfter ?? []),
+        HashSet.fromIterable,
+        HashSet.toValues,
+        Array.filter((event) => !activatingEvents.includes(eventKey(event))),
+        Array.map((event) => this._activate(event, { after: key })),
+        Effect.allWith({ concurrency: 'unbounded' }),
+      );
+
+      yield* Ref.update(this._activatingEvents, (activating) => Array.filter(activating, (event) => event !== key));
+      yield* Ref.update(this._activatingModules, (activating) =>
+        Array.filter(activating, (module) => !modules.map((module) => module.id).includes(module)),
+      );
 
       if (!this._state.eventsFired.includes(key)) {
         this._state.eventsFired.push(key);
@@ -409,43 +454,60 @@ export class PluginManager {
     });
   }
 
-  private _activateModule(
-    module: PluginModule,
-    getCapabilities: AnyCapability | AnyCapability[] | (() => Promise<AnyCapability | AnyCapability[]>),
-  ): Effect.Effect<void, Error> {
-    return Effect.gen(this, function* () {
-      yield* Effect.all(module.activatesBefore?.map((event) => this._activate(event)) ?? [], {
-        concurrency: 'unbounded',
-      });
+  // Memoized with _moduleMemoMap
+  private _loadModule = (mod: PluginModule): Effect.Effect<AnyCapability[], Error> =>
+    Effect.tryPromise({
+      try: async () => {
+        const entry = this._moduleMemoMap.get(mod.id);
+        if (entry) {
+          return entry;
+        }
 
-      log('activating module...', { module: module.id });
-      // TODO(wittjosiah): This is not handling errors thrown if this is synchronous.
-      const maybeCapabilities = typeof getCapabilities === 'function' ? getCapabilities() : getCapabilities;
-      const resolvedCapabilities = yield* Match.value(maybeCapabilities).pipe(
-        // TODO(wittjosiah): Activate with an effect?
-        // Match.when(Effect.isEffect, (effect) => effect),
-        Match.when(isPromise, (promise) =>
-          Effect.tryPromise({
-            try: () => promise,
-            catch: (error) => error as Error,
-          }),
+        const promise = (async () => {
+          const start = performance.now();
+          let failed = false;
+          try {
+            log('loading module', { module: mod.id });
+            // TODO(wittjosiah): Support activation with an effect.
+            let activationResult = await mod.activate(this.context);
+            if (typeof activationResult === 'function') {
+              activationResult = await activationResult();
+            }
+            return Array.isArray(activationResult) ? activationResult : [activationResult];
+          } catch (error) {
+            failed = true;
+            throw error;
+          } finally {
+            performance.measure('activate-module', {
+              start,
+              end: performance.now(),
+              detail: {
+                module: mod.id,
+              },
+            });
+            log('loaded module', { module: mod.id, elapsed: performance.now() - start, failed });
+          }
+        })();
+        this._moduleMemoMap.set(mod.id, promise);
+        return promise;
+      },
+      catch: (error) => error as Error,
+    }).pipe(
+      Effect.withSpan('PluginManager._loadModule'),
+      together(
+        Effect.sleep(Duration.seconds(10)).pipe(
+          Effect.andThen(Effect.sync(() => log.warn(`module is taking a long time to activate`, { module: mod.id }))),
         ),
-        Match.orElse((program) => Effect.succeed(program)),
-      );
-      const capabilities = Match.value(resolvedCapabilities).pipe(
-        Match.when(Array.isArray, (array) => array),
-        Match.orElse((value) => [value]),
-      );
+      ),
+    );
+
+  private _contributeCapabilities(module: PluginModule, capabilities: AnyCapability[]): Effect.Effect<void, Error> {
+    return Effect.gen(this, function* () {
       capabilities.forEach((capability) => {
         this.context.contributeCapability({ module: module.id, ...capability });
       });
       this._state.active.push(module.id);
       this._capabilities.set(module.id, capabilities);
-      log('activated module', { module: module.id });
-
-      yield* Effect.all(module.activatesAfter?.map((event) => this._activate(event)) ?? [], {
-        concurrency: 'unbounded',
-      });
     });
   }
 
@@ -469,6 +531,7 @@ export class PluginManager {
     return Effect.gen(this, function* () {
       const id = module.id;
       log('deactivating', { id });
+      this._moduleMemoMap.delete(id);
 
       const capabilities = this._capabilities.get(id);
       if (capabilities) {
@@ -517,3 +580,18 @@ export class PluginManager {
     });
   }
 }
+
+/**
+ * Runs an effect concurrently with another effect.
+ * If the first effect completes, the second effect is interrupted.
+ */
+// TODO(dmaretskyi): Effect.race > Effect.asVoid
+const together =
+  <R1>(togetherEffect: Effect.Effect<void, never, R1>) =>
+  <A, E, R2>(effect: Effect.Effect<A, E, R2>): Effect.Effect<A, E, R1 | R2> =>
+    Effect.gen(function* () {
+      const togetherFiber = yield* Effect.fork(togetherEffect);
+      const result = yield* effect;
+      yield* Fiber.interrupt(togetherFiber);
+      return result;
+    });

package/src/helpers.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { describe, it, expect } from 'vitest';
+import { describe, expect, it } from 'vitest';
 
 import { topologicalSort } from './helpers';
 

package/src/index.ts

@@ -2,8 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './App';
 export * from './common';
+export * from './components';
 export * from './core';
 export * from './plugin-intent';
 export * from './plugin-settings';

package/src/playground/debug/Debug.tsx

@@ -22,7 +22,7 @@ export const Debug = () => {
   };
 
   return (
-    <SyntaxHighlighter language='json' classNames='flex w-full text-xs opacity-75 rounded'>
+    <SyntaxHighlighter language='json' classNames='text-xs opacity-75 rounded'>
       {JSON.stringify(object, undefined, 2)}
     </SyntaxHighlighter>
   );

package/src/playground/generator/Toolbar.tsx

@@ -6,12 +6,13 @@ import React, { useCallback } from 'react';
 
 import { Button } from '@dxos/react-ui';
 
-import { createGeneratorIntent, createPluginId, Number } from './generator';
 import { Capabilities } from '../../common';
 import { contributes } from '../../core';
 import { createIntent } from '../../plugin-intent';
 import { useCapabilities, useIntentDispatcher, usePluginManager } from '../../react';
 
+import { Number, createGeneratorIntent, createPluginId } from './generator';
+
 export const Toolbar = () => {
   const manager = usePluginManager();
   const { dispatchPromise: dispatch } = useIntentDispatcher();

package/src/playground/generator/generator.ts

@@ -5,8 +5,8 @@
 import { Schema } from 'effect';
 
 import { Capabilities, Events } from '../../common';
-import { contributes, defineEvent, defineCapability, defineModule, definePlugin } from '../../core';
-import { createResolver, type IntentSchema } from '../../plugin-intent';
+import { contributes, defineCapability, defineEvent, defineModule, definePlugin } from '../../core';
+import { type IntentSchema, createResolver } from '../../plugin-intent';
 
 export const Number = defineCapability<number>('dxos.org/test/generator/number');
 

package/src/playground/layout/plugin.ts

@@ -3,7 +3,7 @@
 //
 
 import { Events } from '../../common';
-import { definePlugin, lazy, defineModule } from '../../core';
+import { defineModule, definePlugin, lazy } from '../../core';
 
 const Layout = lazy(() => import('./Layout'));
 

package/src/playground/logger/Toolbar.tsx

@@ -6,12 +6,13 @@ import React, { useCallback } from 'react';
 
 import { Button } from '@dxos/react-ui';
 
-import { Log } from './schema';
 import { Capabilities, createSurface } from '../../common';
 import { contributes } from '../../core';
 import { createIntent } from '../../plugin-intent';
 import { useIntentDispatcher } from '../../react';
 
+import { Log } from './schema';
+
 export const Logger = () => {
   const { dispatchPromise } = useIntentDispatcher();
   const handleClick = useCallback(() => dispatchPromise(createIntent(Log, { message: 'Hello, world!' })), []);

package/src/playground/logger/plugin.ts

@@ -4,11 +4,12 @@
 
 import { log } from '@dxos/log';
 
-import { Log } from './schema';
 import { Capabilities, Events } from '../../common';
-import { contributes, defineModule, lazy, definePlugin } from '../../core';
+import { contributes, defineModule, definePlugin, lazy } from '../../core';
 import { createResolver } from '../../plugin-intent';
 
+import { Log } from './schema';
+
 const Toolbar = lazy(() => import('./Toolbar'));
 
 export const LoggerPlugin = () =>

package/src/playground/playground.stories.tsx

@@ -4,16 +4,18 @@
 
 import '@dxos-theme';
 
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
 import { withLayout, withTheme } from '@dxos/storybook-utils';
 
+import { useApp } from '../components';
+import { IntentPlugin } from '../plugin-intent';
+
 import { DebugPlugin } from './debug';
-import { createNumberPlugin, GeneratorPlugin } from './generator';
+import { GeneratorPlugin, createNumberPlugin } from './generator';
 import { LayoutPlugin } from './layout';
 import { LoggerPlugin } from './logger';
-import { useApp } from '../App';
-import { IntentPlugin } from '../plugin-intent';
 
 const plugins = [IntentPlugin(), LayoutPlugin(), DebugPlugin(), LoggerPlugin(), GeneratorPlugin()];
 
@@ -21,22 +23,25 @@ const Placeholder = () => {
   return <div>Loading...</div>;
 };
 
-const Story = () => {
+const DefaultStory = () => {
   const App = useApp({
     pluginLoader: (id) => createNumberPlugin(id),
     plugins,
     core: plugins.map((plugin) => plugin.meta.id),
-    // Having a non-empty placeholder makes it clear if it's taking a while to load.
     placeholder: Placeholder,
   });
 
   return <App />;
 };
 
-export const Playground = {};
-
-export default {
+const meta = {
   title: 'sdk/app-framework/playground',
-  render: Story,
+  render: DefaultStory,
   decorators: [withTheme, withLayout()],
-};
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {};

package/src/plugin-intent/IntentPlugin.ts

@@ -2,10 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import { INTENT_PLUGIN } from './actions';
 import { Events } from '../common';
 import { defineModule, definePlugin, lazy } from '../core';
 
+import { INTENT_PLUGIN } from './actions';
+
 export const IntentPlugin = () =>
   definePlugin({ id: INTENT_PLUGIN, name: 'Intent' }, [
     defineModule({

package/src/plugin-intent/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './actions';
+export * from './errors';
 export * from './intent';
 export * from './intent-dispatcher';
 export * from './IntentPlugin';

package/src/plugin-intent/intent-dispatcher.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { Schema, Effect, Fiber, pipe } from 'effect';
+import { Effect, Fiber, Schema, pipe } from 'effect';
 import { describe, expect, test } from 'vitest';
 
 import { chain, createIntent } from './intent';