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

package/src/core/manager.ts

@@ -4,16 +4,23 @@
 
 import { Registry } from '@effect-rx/rx-react';
 import { untracked } from '@preact/signals-core';
-import { Array as A, Effect, Either, Match, pipe } from 'effect';
+import * as Array from 'effect/Array';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Function from 'effect/Function';
+import * as HashSet from 'effect/HashSet';
+import * as Match from 'effect/Match';
+import * as Ref from 'effect/Ref';
 
 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 +59,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 +84,8 @@ export class PluginManager {
       enabled,
       modules: [],
       active: [],
-      pendingReset: [],
       eventsFired: [],
+      pendingReset: [],
     });
     plugins.forEach((plugin) => this._addPlugin(plugin));
     core.forEach((id) => this.enable(id));
@@ -268,6 +278,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 +298,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 +341,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 +355,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 +402,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* Function.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* Function.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* Function.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* Function.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 +461,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 +538,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 +587,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/core/plugin.ts

@@ -110,6 +110,11 @@ export type PluginMeta = {
    * A grep-able symbol string which can be resolved to an icon asset by @ch-ui/icons, via @ch-ui/vite-plugin-icons.
    */
   icon?: string;
+
+  /**
+   * Icon hue (ChromaticPalette).
+   */
+  iconHue?: string;
 };
 
 /**
@@ -124,9 +129,15 @@ export class Plugin {
   ) {}
 }
 
+export type PluginFactory<T = void> = ((args: T) => Plugin) & { meta: PluginMeta };
+
 /**
  * Helper to define a plugin.
  */
-export const definePlugin = (meta: PluginMeta, modules: PluginModule[]) => {
-  return new Plugin(meta, modules);
+export const definePlugin = <T = void>(meta: PluginMeta, provider: (args: T) => PluginModule[]): PluginFactory<T> => {
+  const factory = (args: T) => {
+    return new Plugin(meta, provider(args));
+  };
+
+  return Object.assign(factory, { meta });
 };

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/debug/plugin.ts

@@ -7,11 +7,10 @@ import { defineModule, definePlugin, lazy } from '../../core';
 
 const Debug = lazy(() => import('./Debug'));
 
-export const DebugPlugin = () =>
-  definePlugin({ id: 'dxos.org/test/plugin-debug', name: 'Debug' }, [
-    defineModule({
-      id: 'dxos.org/test/debug/main',
-      activatesOn: Events.Startup,
-      activate: Debug,
-    }),
-  ]);
+export const DebugPlugin = definePlugin({ id: 'dxos.org/test/plugin-debug', name: 'Debug' }, () => [
+  defineModule({
+    id: 'dxos.org/test/debug/main',
+    activatesOn: Events.Startup,
+    activate: Debug,
+  }),
+]);

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

@@ -2,11 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 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');
 
@@ -26,7 +26,7 @@ export const createGeneratorIntent = (id: string) => {
 export const createNumberPlugin = (id: string) => {
   const number = Math.floor(Math.random() * 100);
 
-  return definePlugin({ id, name: `Plugin ${id}` }, [
+  return definePlugin({ id, name: `Plugin ${id}` }, () => [
     defineModule({
       id: `${id}/main`,
       activatesOn: CountEvent,

package/src/playground/generator/plugin.ts

@@ -8,16 +8,15 @@ import { defineModule, definePlugin, lazy } from '../../core';
 const Main = lazy(() => import('./Main'));
 const Toolbar = lazy(() => import('./Toolbar'));
 
-export const GeneratorPlugin = () =>
-  definePlugin({ id: 'dxos.org/test/generator', name: 'Generator' }, [
-    defineModule({
-      id: 'dxos.org/test/generator/main',
-      activatesOn: Events.Startup,
-      activate: Main,
-    }),
-    defineModule({
-      id: 'dxos.org/test/generator/toolbar',
-      activatesOn: Events.Startup,
-      activate: Toolbar,
-    }),
-  ]);
+export const GeneratorPlugin = definePlugin({ id: 'dxos.org/test/generator', name: 'Generator' }, () => [
+  defineModule({
+    id: 'dxos.org/test/generator/main',
+    activatesOn: Events.Startup,
+    activate: Main,
+  }),
+  defineModule({
+    id: 'dxos.org/test/generator/toolbar',
+    activatesOn: Events.Startup,
+    activate: Toolbar,
+  }),
+]);

package/src/playground/layout/plugin.ts

@@ -3,15 +3,16 @@
 //
 
 import { Events } from '../../common';
-import { definePlugin, lazy, defineModule } from '../../core';
+import { defineModule, definePlugin, lazy } from '../../core';
 
 const Layout = lazy(() => import('./Layout'));
 
-export const LayoutPlugin = () =>
-  definePlugin({ id: 'dxos.org/test/layout', name: 'Layout' }, [
-    defineModule({
-      id: 'dxos.org/test/layout/root',
-      activatesOn: Events.Startup,
-      activate: Layout,
-    }),
-  ]);
+const meta = { id: 'dxos.org/test/layout', name: 'Layout' };
+
+export const LayoutPlugin = definePlugin(meta, () => [
+  defineModule({
+    id: 'dxos.org/test/layout/root',
+    activatesOn: Events.Startup,
+    activate: 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,33 +4,38 @@
 
 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 = () =>
-  definePlugin({ id: 'dxos.org/test/logger', name: 'Logger' }, [
-    defineModule({
-      id: 'dxos.org/test/logger/intents',
-      activatesOn: Events.SetupIntentResolver,
-      activate: () => [
-        contributes(
-          Capabilities.IntentResolver,
-          createResolver({
-            intent: Log,
-            resolve: ({ message }) => {
-              log.info(message);
-            },
-          }),
-        ),
-      ],
-    }),
-    defineModule({
-      id: 'dxos.org/test/logger/surfaces',
-      activatesOn: Events.Startup,
-      activate: Toolbar,
-    }),
-  ]);
+const meta = {
+  id: 'dxos.org/test/logger',
+  name: 'Logger',
+};
+
+export const LoggerPlugin = definePlugin(meta, () => [
+  defineModule({
+    id: 'dxos.org/test/logger/intents',
+    activatesOn: Events.SetupIntentResolver,
+    activate: () => [
+      contributes(
+        Capabilities.IntentResolver,
+        createResolver({
+          intent: Log,
+          resolve: ({ message }) => {
+            log.info(message);
+          },
+        }),
+      ),
+    ],
+  }),
+  defineModule({
+    id: 'dxos.org/test/logger/surfaces',
+    activatesOn: Events.Startup,
+    activate: Toolbar,
+  }),
+]);

package/src/playground/logger/schema.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 
 export class Log extends Schema.TaggedClass<Log>()('dxos.org/test/logger/log', {
   input: Schema.Struct({

package/src/playground/playground.stories.tsx

@@ -2,41 +2,45 @@
 // Copyright 2025 DXOS.org
 //
 
-import '@dxos-theme';
-
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
+
+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()];
+const pluginFactories = [IntentPlugin, LayoutPlugin, DebugPlugin(), LoggerPlugin(), GeneratorPlugin()];
+const plugins = pluginFactories.map((factory) => (typeof factory === 'function' ? factory() : factory));
 
 const Placeholder = () => {
   return <div>Loading...</div>;
 };
 
-const Story = () => {
+const DefaultStory = () => {
   const App = useApp({
-    pluginLoader: (id) => createNumberPlugin(id),
+    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,
-  decorators: [withTheme, withLayout()],
-};
+  render: DefaultStory,
+  decorators: [withTheme],
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {};