@dxos/app-framework 0.8.2-main.f11618f → 0.8.2-staging.42af850

package/src/core/capabilities.ts

@@ -1,16 +1,12 @@
-/**
- * Interface definition for a capability.
- */
 //
 // Copyright 2025 DXOS.org
 //
 
-import { effect, untracked } from '@preact/signals-core';
+import { type Registry, Rx } from '@effect-rx/rx-react';
 import { Effect } from 'effect';
 
 import { Trigger } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
-import { live } from '@dxos/live-object';
 import { log } from '@dxos/log';
 import { type MaybePromise } from '@dxos/util';
 
@@ -57,6 +53,7 @@ export type Capability<T> = {
 export type AnyCapability = Capability<any>;
 
 type PluginsContextOptions = {
+  registry: Registry.Registry;
   activate: (event: ActivationEvent) => Effect.Effect<boolean, Error>;
   reset: (event: ActivationEvent) => Effect.Effect<boolean, Error>;
 };
@@ -100,9 +97,27 @@ export const lazy =
  * It tracks the capabilities that are contributed in an in-memory live object.
  * This allows the application to subscribe to this state and incorporate plugins which are added dynamically.
  */
-// TOOD(burdon): Rename PluginContext.
-export class PluginsContext {
-  private readonly _definedCapabilities = new Map<string, CapabilityImpl<unknown>[]>();
+export class PluginContext {
+  private readonly _registry: Registry.Registry;
+
+  private readonly _capabilityImpls = Rx.family<string, Rx.Writable<CapabilityImpl<unknown>[]>>(() => {
+    return Rx.make<CapabilityImpl<unknown>[]>([]).pipe(Rx.keepAlive);
+  });
+
+  readonly _capabilities = Rx.family<string, Rx.Rx<unknown[]>>((id: string) => {
+    return Rx.make((get) => {
+      const current = get(this._capabilityImpls(id));
+      return current.map((c) => c.implementation);
+    });
+  });
+
+  readonly _capability = Rx.family<string, Rx.Rx<unknown>>((id: string) => {
+    return Rx.make((get) => {
+      const current = get(this._capabilities(id));
+      invariant(current.length > 0, `No capability found for ${id}`);
+      return current[0];
+    });
+  });
 
   /**
    * Activates plugins based on the activation event.
@@ -118,7 +133,8 @@ export class PluginsContext {
    */
   readonly reset: PluginsContextOptions['reset'];
 
-  constructor({ activate, reset }: PluginsContextOptions) {
+  constructor({ registry, activate, reset }: PluginsContextOptions) {
+    this._registry = registry;
     this.activate = activate;
     this.reset = reset;
   }
@@ -134,94 +150,98 @@ export class PluginsContext {
     module: string;
     interface: InterfaceDef<T>;
     implementation: T;
-  }) {
-    let current = this._definedCapabilities.get(interfaceDef.identifier);
-    if (!current) {
-      const object = live<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
-      current = untracked(() => object.value);
-      this._definedCapabilities.set(interfaceDef.identifier, current);
+  }): void {
+    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
+    const capability = new CapabilityImpl(moduleId, implementation);
+    if (current.includes(capability)) {
+      return;
     }
 
-    current.push(new CapabilityImpl(moduleId, implementation));
+    this._registry.set(this._capabilityImpls(interfaceDef.identifier), [...current, capability]);
     log('capability contributed', {
       id: interfaceDef.identifier,
       moduleId,
-      count: untracked(() => current.length),
+      count: current.length,
     });
   }
 
   /**
    * @internal
    */
-  removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T) {
-    const current = this._definedCapabilities.get(interfaceDef.identifier);
-    if (!current) {
+  removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T): void {
+    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
+    if (current.length === 0) {
       return;
     }
 
-    const index = current.findIndex((i) => i.implementation === implementation);
-    if (index !== -1) {
-      current.splice(index, 1);
-      log('capability removed', { id: interfaceDef.identifier, count: untracked(() => current.length) });
+    const next = current.filter((c) => c.implementation !== implementation);
+    if (next.length !== current.length) {
+      this._registry.set(this._capabilityImpls(interfaceDef.identifier), next);
+      log('capability removed', { id: interfaceDef.identifier, count: current.length });
     } else {
       log.warn('capability not removed', { id: interfaceDef.identifier });
     }
   }
 
   /**
-   * Requests capabilities from the plugin context.
-   * @returns An array of capabilities.
-   * @reactive
+   * Get the Rx reference to the available capabilities for a given interface.
+   * Primarily useful for deriving other Rx values based on the capabilities or
+   * for subscribing to changes in the capabilities.
+   * @returns An Rx reference to the available capabilities.
    */
-  requestCapabilities<T, U extends T = T>(
-    interfaceDef: InterfaceDef<T>,
-    filter?: (capability: T, moduleId: string) => capability is U,
-  ): U[] {
-    let current = this._definedCapabilities.get(interfaceDef.identifier);
-    if (!current) {
-      const object = live<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
-      current = untracked(() => object.value);
-      this._definedCapabilities.set(interfaceDef.identifier, current);
-    }
+  capabilities<T>(interfaceDef: InterfaceDef<T>): Rx.Rx<T[]> {
+    // NOTE: This the type-checking for capabilities is done at the time of contribution.
+    return this._capabilities(interfaceDef.identifier) as Rx.Rx<T[]>;
+  }
 
+  /**
+   * Get the Rx reference to the available capabilities for a given interface.
+   * Primarily useful for deriving other Rx values based on the capability or
+   * for subscribing to changes in the capability.
+   * @returns An Rx reference to the available capability.
+   * @throws If no capability is found.
+   */
+  capability<T>(interfaceDef: InterfaceDef<T>): Rx.Rx<T> {
     // NOTE: This the type-checking for capabilities is done at the time of contribution.
-    const capabilities = filter ? current.filter((c) => filter(c.implementation as T, c.moduleId)) : current;
-    return capabilities.map((c) => c.implementation) as U[];
+    return this._capability(interfaceDef.identifier) as Rx.Rx<T>;
+  }
+
+  /**
+   * Get capabilities from the plugin context.
+   * @returns An array of capabilities.
+   */
+  getCapabilities<T>(interfaceDef: InterfaceDef<T>): T[] {
+    return this._registry.get(this.capabilities(interfaceDef));
   }
 
   /**
    * Requests a single capability from the plugin context.
    * @returns The capability.
    * @throws If no capability is found.
-   * @reactive
    */
-  requestCapability<T, U extends T = T>(
-    interfaceDef: InterfaceDef<T>,
-    filter?: (capability: T, moduleId: string) => capability is U,
-  ): U {
-    const capability = this.requestCapabilities(interfaceDef, filter)[0];
-    invariant(capability, `No capability found for ${interfaceDef.identifier}`);
-    return capability;
+  getCapability<T>(interfaceDef: InterfaceDef<T>): T {
+    return this._registry.get(this.capability(interfaceDef));
   }
 
   /**
-   * Waits for a capability to be contributed.
+   * Waits for a capability to be available.
    * @returns The capability.
    */
-  async waitForCapability<T, U extends T = T>(
-    interfaceDef: InterfaceDef<T>,
-    filter?: (capability: T) => capability is U,
-  ): Promise<U> {
-    const trigger = new Trigger<U>();
-    const unsubscribe = effect(() => {
-      const capabilities = this.requestCapabilities(interfaceDef, filter);
-      if (capabilities[0]) {
+  async waitForCapability<T>(interfaceDef: InterfaceDef<T>): Promise<T> {
+    const [capability] = this.getCapabilities(interfaceDef);
+    if (capability) {
+      return capability;
+    }
+
+    const trigger = new Trigger<T>();
+    const cancel = this._registry.subscribe(this.capabilities(interfaceDef), (capabilities) => {
+      if (capabilities.length > 0) {
         trigger.wake(capabilities[0]);
       }
     });
-    const capability = await trigger.wait();
-    unsubscribe();
-    return capability;
+    const result = await trigger.wait();
+    cancel();
+    return result;
   }
 
   async activatePromise(event: ActivationEvent): Promise<boolean> {

package/src/core/manager.test.ts

@@ -13,7 +13,7 @@ import { registerSignalsRuntime } from '@dxos/echo-signals';
 import { invariant } from '@dxos/invariant';
 import { live } from '@dxos/live-object';
 
-import { contributes, defineCapability, type PluginsContext } from './capabilities';
+import { contributes, defineCapability, type PluginContext } from './capabilities';
 import { allOf, defineEvent, oneOf } from './events';
 import { PluginManager } from './manager';
 import { definePlugin, defineModule, type Plugin } from './plugin';
@@ -205,22 +205,22 @@ describe('PluginManager', () => {
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(0);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(0);
 
     await manager.add(Plugin1.meta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Plugin1.meta.id]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(1);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(1);
 
     await manager.add(Plugin2.meta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Plugin1.meta.id, Plugin2.meta.id]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(2);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(2);
 
     await manager.add(Plugin3.meta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Plugin1.meta.id, Plugin2.meta.id, Plugin3.meta.id]);
-    expect(manager.context.requestCapabilities(Number)).toHaveLength(3);
+    expect(manager.context.getCapabilities(Number)).toHaveLength(3);
   });
 
   it('should only activate modules after all activatation events have been fired', async () => {
@@ -235,16 +235,16 @@ describe('PluginManager', () => {
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
+    expect(manager.context.getCapabilities(String)).toHaveLength(0);
 
     await manager.add(testMeta.id);
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
+    expect(manager.context.getCapabilities(String)).toHaveLength(0);
 
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(1);
+    expect(manager.context.getCapabilities(String)).toHaveLength(1);
   });
 
   it('should only activate modules once when multiple activatation events have been fired', async () => {
@@ -261,25 +261,25 @@ describe('PluginManager', () => {
 
     const manager = new PluginManager({ pluginLoader });
     expect(manager.active).toEqual([]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
+    expect(manager.context.getCapabilities(String)).toHaveLength(0);
     expect(count).toEqual(0);
 
     await manager.add(testMeta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(1);
+    expect(manager.context.getCapabilities(String)).toHaveLength(1);
     expect(count).toEqual(1);
 
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.requestCapabilities(String)).toHaveLength(1);
+    expect(manager.context.getCapabilities(String)).toHaveLength(1);
     expect(count).toEqual(1);
   });
 
   it('should be able to disable and re-enable an active plugin', async () => {
     const state = { total: 0 };
-    const computeTotal = (context: PluginsContext) => {
-      const numbers = context.requestCapabilities(Number);
+    const computeTotal = (context: PluginContext) => {
+      const numbers = context.getCapabilities(Number);
       state.total = numbers.reduce((acc, n) => acc + n.number, 0);
     };
 
@@ -322,7 +322,7 @@ describe('PluginManager', () => {
       expect(manager.active).toEqual([...Test.modules.map((m) => m.id), Count.meta.id]);
       expect(manager.pendingReset).toEqual([]);
 
-      const totals = manager.context.requestCapabilities(Total);
+      const totals = manager.context.getCapabilities(Total);
       expect(totals).toHaveLength(1);
       expect(totals[0].total).toEqual(6);
     }
@@ -332,7 +332,7 @@ describe('PluginManager', () => {
       expect(manager.active).toEqual([Count.meta.id]);
       expect(manager.pendingReset).toEqual([]);
 
-      const totals = manager.context.requestCapabilities(Total);
+      const totals = manager.context.getCapabilities(Total);
       expect(totals).toHaveLength(1);
       // Total doesn't change because it is not reactive.
       expect(totals[0].total).toEqual(6);
@@ -343,7 +343,7 @@ describe('PluginManager', () => {
       expect(manager.active).toEqual([Count.meta.id, ...Test.modules.map((m) => m.id)]);
       expect(manager.pendingReset).toEqual([]);
 
-      const totals = manager.context.requestCapabilities(Total);
+      const totals = manager.context.getCapabilities(Total);
       expect(totals).toHaveLength(1);
       expect(totals[0].total).toEqual(6);
     }
@@ -364,7 +364,7 @@ describe('PluginManager', () => {
         id: 'dxos.org/test/doubler',
         activatesOn: stateEvent,
         activate: (context) => {
-          const counter = context.requestCapability(Number);
+          const counter = context.getCapability(Number);
           const state = live({ total: counter.number * 2 });
           const unsubscribe = effect(() => {
             state.total = counter.number * 2;
@@ -380,8 +380,8 @@ describe('PluginManager', () => {
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual(Test.modules.map((m) => m.id));
 
-    const counter = manager.context.requestCapability(Number);
-    const doubler = manager.context.requestCapability(Total);
+    const counter = manager.context.getCapability(Number);
+    const doubler = manager.context.getCapability(Total);
     expect(counter.number).toEqual(1);
     expect(doubler.total).toEqual(2);
 

package/src/core/manager.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Registry } from '@effect-rx/rx-react';
 import { untracked } from '@preact/signals-core';
 import { Array as A, Effect, Either, Match, pipe } from 'effect';
 
@@ -10,7 +11,7 @@ import { live, type Live } from '@dxos/live-object';
 import { log } from '@dxos/log';
 import { type MaybePromise } from '@dxos/util';
 
-import { type AnyCapability, PluginsContext } from './capabilities';
+import { type AnyCapability, PluginContext } from './capabilities';
 import { type ActivationEvent, eventKey, getEvents, isAllOf } from './events';
 import { type PluginModule, type Plugin } from './plugin';
 
@@ -24,6 +25,7 @@ export type PluginManagerOptions = {
   plugins?: Plugin[];
   core?: string[];
   enabled?: string[];
+  registry?: Registry.Registry;
 };
 
 type PluginManagerState = {
@@ -43,12 +45,10 @@ type PluginManagerState = {
 
 export class PluginManager {
   readonly activation = new Event<{ event: string; state: 'activating' | 'activated' | 'error'; error?: any }>();
+  readonly context: PluginContext;
+  readonly registry: Registry.Registry;
 
-  readonly context = new PluginsContext({
-    activate: (event) => this._activate(event),
-    reset: (id) => this._reset(id),
-  });
-
+  // TODO(wittjosiah): Replace with Rx.
   private readonly _state: Live<PluginManagerState>;
   private readonly _pluginLoader: PluginManagerOptions['pluginLoader'];
   private readonly _capabilities = new Map<string, AnyCapability[]>();
@@ -58,7 +58,15 @@ export class PluginManager {
     plugins = [],
     core = plugins.map(({ meta }) => meta.id),
     enabled = [],
+    registry,
   }: PluginManagerOptions) {
+    this.registry = registry ?? Registry.make();
+    this.context = new PluginContext({
+      registry: this.registry,
+      activate: (event) => this._activate(event),
+      reset: (id) => this._reset(id),
+    });
+
     this._pluginLoader = pluginLoader;
     this._state = live({
       plugins,
@@ -257,7 +265,7 @@ export class PluginManager {
     return untracked(() => Effect.runPromise(this._reset(event)));
   }
 
-  private _addPlugin(plugin: Plugin) {
+  private _addPlugin(plugin: Plugin): void {
     untracked(() => {
       log('add plugin', { id: plugin.meta.id });
       if (!this._state.plugins.includes(plugin)) {
@@ -266,7 +274,7 @@ export class PluginManager {
     });
   }
 
-  private _removePlugin(id: string) {
+  private _removePlugin(id: string): void {
     untracked(() => {
       log('remove plugin', { id });
       const pluginIndex = this._state.plugins.findIndex((plugin) => plugin.meta.id === id);
@@ -276,7 +284,7 @@ export class PluginManager {
     });
   }
 
-  private _addModule(module: PluginModule) {
+  private _addModule(module: PluginModule): void {
     untracked(() => {
       log('add module', { id: module.id });
       if (!this._state.modules.includes(module)) {
@@ -285,7 +293,7 @@ export class PluginManager {
     });
   }
 
-  private _removeModule(id: string) {
+  private _removeModule(id: string): void {
     untracked(() => {
       log('remove module', { id });
       const moduleIndex = this._state.modules.findIndex((module) => module.id === id);
@@ -295,27 +303,27 @@ export class PluginManager {
     });
   }
 
-  private _getPlugin(id: string) {
+  private _getPlugin(id: string): Plugin | undefined {
     return this._state.plugins.find((plugin) => plugin.meta.id === id);
   }
 
-  private _getActiveModules() {
+  private _getActiveModules(): PluginModule[] {
     return this._state.modules.filter((module) => this._state.active.includes(module.id));
   }
 
-  private _getInactiveModules() {
+  private _getInactiveModules(): PluginModule[] {
     return this._state.modules.filter((module) => !this._state.active.includes(module.id));
   }
 
-  private _getActiveModulesByEvent(key: string) {
+  private _getActiveModulesByEvent(key: string): PluginModule[] {
     return this._getActiveModules().filter((module) => getEvents(module.activatesOn).map(eventKey).includes(key));
   }
 
-  private _getInactiveModulesByEvent(key: string) {
+  private _getInactiveModulesByEvent(key: string): PluginModule[] {
     return this._getInactiveModules().filter((module) => getEvents(module.activatesOn).map(eventKey).includes(key));
   }
 
-  private _setPendingResetByModule(module: PluginModule) {
+  private _setPendingResetByModule(module: PluginModule): void {
     return untracked(() => {
       const activationEvents = getEvents(module.activatesOn)
         .map(eventKey)

package/src/core/plugin.ts

@@ -4,7 +4,7 @@
 
 import { type MaybePromise } from '@dxos/util';
 
-import { type AnyCapability, type PluginsContext } from './capabilities';
+import { type AnyCapability, type PluginContext } from './capabilities';
 import { type ActivationEvent, type ActivationEvents } from './events';
 
 interface PluginModuleInterface {
@@ -36,7 +36,7 @@ interface PluginModuleInterface {
    * @returns The capabilities of the module.
    */
   activate: (
-    context: PluginsContext,
+    context: PluginContext,
   ) => MaybePromise<AnyCapability | AnyCapability[]> | Promise<() => Promise<AnyCapability | AnyCapability[]>>;
 }
 

package/src/playground/generator/generator.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema as S } from 'effect';
+import { Schema } from 'effect';
 
 import { Capabilities, Events } from '../../common';
 import { contributes, defineEvent, defineCapability, defineModule, definePlugin } from '../../core';
@@ -15,9 +15,9 @@ export const CountEvent = defineEvent('dxos.org/test/generator/count');
 export const createPluginId = (id: string) => `dxos.org/test/generator/${id}`;
 
 export const createGeneratorIntent = (id: string) => {
-  class Alert extends S.TaggedClass<Alert>()(`${createPluginId(id)}/action/alert`, {
-    input: S.Void,
-    output: S.Void,
+  class Alert extends Schema.TaggedClass<Alert>()(`${createPluginId(id)}/action/alert`, {
+    input: Schema.Void,
+    output: Schema.Void,
   }) {}
 
   return Alert as unknown as IntentSchema<any, any>;

package/src/playground/logger/schema.ts

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

package/src/playground/playground.stories.tsx

@@ -12,7 +12,7 @@ import { DebugPlugin } from './debug';
 import { createNumberPlugin, GeneratorPlugin } from './generator';
 import { LayoutPlugin } from './layout';
 import { LoggerPlugin } from './logger';
-import { createApp } from '../App';
+import { useApp } from '../App';
 import { IntentPlugin } from '../plugin-intent';
 
 const plugins = [IntentPlugin(), LayoutPlugin(), DebugPlugin(), LoggerPlugin(), GeneratorPlugin()];
@@ -21,18 +21,22 @@ const Placeholder = () => {
   return <div>Loading...</div>;
 };
 
-const Story = createApp({
-  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,
-});
+const Story = () => {
+  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 {
   title: 'sdk/app-framework/playground',
   render: Story,
-  decorators: [withTheme, withLayout({ tooltips: true })],
+  decorators: [withTheme, withLayout()],
 };

package/src/plugin-intent/actions.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema as S } from 'effect';
+import { Schema } from 'effect';
 
 import { Label } from './intent';
 
@@ -13,21 +13,21 @@ export namespace IntentAction {
   /**
    * Log an intent.
    */
-  export class Track extends S.TaggedClass<Track>()(`${INTENT_ACTION}/track`, {
-    input: S.Struct({
-      intents: S.Array(S.String),
-      error: S.optional(S.String),
+  export class Track extends Schema.TaggedClass<Track>()(`${INTENT_ACTION}/track`, {
+    input: Schema.Struct({
+      intents: Schema.Array(Schema.String),
+      error: Schema.optional(Schema.String),
     }),
-    output: S.Void,
+    output: Schema.Void,
   }) {}
 
   /**
    * Fired after an intent is dispatched if the intent is undoable.
    */
-  export class ShowUndo extends S.TaggedClass<ShowUndo>()(`${INTENT_ACTION}/show-undo`, {
-    input: S.Struct({
+  export class ShowUndo extends Schema.TaggedClass<ShowUndo>()(`${INTENT_ACTION}/show-undo`, {
+    input: Schema.Struct({
       message: Label,
     }),
-    output: S.Void,
+    output: Schema.Void,
   }) {}
 }