@dxos/app-framework 0.8.2-main.fbd8ed0 → 0.8.2-staging.7ac8446

package/src/core/capabilities.ts

@@ -1,12 +1,16 @@
+/**
+ * Interface definition for a capability.
+ */
 //
 // Copyright 2025 DXOS.org
 //
 
-import { type Registry, Rx } from '@effect-rx/rx-react';
+import { effect, untracked } from '@preact/signals-core';
 import { Effect } from 'effect';
 
 import { Trigger } from '@dxos/async';
 import { invariant } from '@dxos/invariant';
+import { create } from '@dxos/live-object';
 import { log } from '@dxos/log';
 import { type MaybePromise } from '@dxos/util';
 
@@ -30,8 +34,7 @@ export const defineCapability = <T>(identifier: string) => {
 };
 
 /**
- * A unique string identifier with a Typescript type associated with it.
- * When a capability is contributed to the application an implementation of the interface is provided.
+ * Functionality contributed to the application by a plugin module.
  */
 export type Capability<T> = {
   /**
@@ -53,7 +56,6 @@ 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>;
 };
@@ -93,31 +95,10 @@ export const lazy =
   };
 
 /**
- * Facilitates the dependency injection between [plugin modules](#pluginmodule) by allowing them contribute and request capabilities from each other.
- * 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.
+ * Context which is passed to plugins, allowing them to interact with each other.
  */
-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];
-    });
-  });
+export class PluginsContext {
+  private readonly _definedCapabilities = new Map<string, CapabilityImpl<unknown>[]>();
 
   /**
    * Activates plugins based on the activation event.
@@ -133,8 +114,7 @@ export class PluginContext {
    */
   readonly reset: PluginsContextOptions['reset'];
 
-  constructor({ registry, activate, reset }: PluginsContextOptions) {
-    this._registry = registry;
+  constructor({ activate, reset }: PluginsContextOptions) {
     this.activate = activate;
     this.reset = reset;
   }
@@ -151,17 +131,18 @@ export class PluginContext {
     interface: InterfaceDef<T>;
     implementation: T;
   }) {
-    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
-    const capability = new CapabilityImpl(moduleId, implementation);
-    if (current.includes(capability)) {
-      return;
+    let current = this._definedCapabilities.get(interfaceDef.identifier);
+    if (!current) {
+      const object = create<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
+      current = untracked(() => object.value);
+      this._definedCapabilities.set(interfaceDef.identifier, current);
     }
 
-    this._registry.set(this._capabilityImpls(interfaceDef.identifier), [...current, capability]);
+    current.push(new CapabilityImpl(moduleId, implementation));
     log('capability contributed', {
       id: interfaceDef.identifier,
       moduleId,
-      count: current.length,
+      count: untracked(() => current.length),
     });
   }
 
@@ -169,79 +150,74 @@ export class PluginContext {
    * @internal
    */
   removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T) {
-    const current = this._registry.get(this._capabilityImpls(interfaceDef.identifier));
-    if (current.length === 0) {
+    const current = this._definedCapabilities.get(interfaceDef.identifier);
+    if (!current) {
       return;
     }
 
-    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 });
+    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) });
     } else {
       log.warn('capability not removed', { id: interfaceDef.identifier });
     }
   }
 
   /**
-   * 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.
+   * Requests capabilities from the plugin context.
+   * @returns An array of capabilities.
+   * @reactive
    */
-  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[]>;
-  }
+  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 = create<{ value: CapabilityImpl<unknown>[] }>({ value: [] });
+      current = untracked(() => object.value);
+      this._definedCapabilities.set(interfaceDef.identifier, current);
+    }
 
-  /**
-   * 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.
-    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));
+    const capabilities = filter ? current.filter((c) => filter(c.implementation as T, c.moduleId)) : current;
+    return capabilities.map((c) => c.implementation) as U[];
   }
 
   /**
    * Requests a single capability from the plugin context.
    * @returns The capability.
    * @throws If no capability is found.
+   * @reactive
    */
-  getCapability<T>(interfaceDef: InterfaceDef<T>): T {
-    return this._registry.get(this.capability(interfaceDef));
+  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;
   }
 
   /**
-   * Waits for a capability to be available.
+   * Waits for a capability to be contributed.
    * @returns The capability.
    */
-  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) {
+  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]) {
         trigger.wake(capabilities[0]);
       }
     });
-    const result = await trigger.wait();
-    cancel();
-    return result;
+    const capability = await trigger.wait();
+    unsubscribe();
+    return capability;
   }
 
   async activatePromise(event: ActivationEvent): Promise<boolean> {

package/src/core/events.ts

@@ -3,10 +3,7 @@
 //
 
 /**
- * A unique string identifier representing an event.
- * This is expected to be a URI, where initial parts are often the id of the plugin whose package defines the event.
- *
- * @example dxos.org/plugin/example/event/ready
+ * An event which activates a plugin module.
  */
 export type ActivationEvent = {
   id: string;

package/src/core/manager.test.ts

@@ -11,9 +11,9 @@ import { raise } from '@dxos/debug';
 import { updateCounter } from '@dxos/echo-schema/testing';
 import { registerSignalsRuntime } from '@dxos/echo-signals';
 import { invariant } from '@dxos/invariant';
-import { live } from '@dxos/live-object';
+import { create } from '@dxos/live-object';
 
-import { contributes, defineCapability, type PluginContext } from './capabilities';
+import { contributes, defineCapability, type PluginsContext } 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.getCapabilities(Number)).toHaveLength(0);
+    expect(manager.context.requestCapabilities(Number)).toHaveLength(0);
 
     await manager.add(Plugin1.meta.id);
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Plugin1.meta.id]);
-    expect(manager.context.getCapabilities(Number)).toHaveLength(1);
+    expect(manager.context.requestCapabilities(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.getCapabilities(Number)).toHaveLength(2);
+    expect(manager.context.requestCapabilities(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.getCapabilities(Number)).toHaveLength(3);
+    expect(manager.context.requestCapabilities(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.getCapabilities(String)).toHaveLength(0);
+    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
 
     await manager.add(testMeta.id);
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual([]);
-    expect(manager.context.getCapabilities(String)).toHaveLength(0);
+    expect(manager.context.requestCapabilities(String)).toHaveLength(0);
 
     await manager.activate(CountEvent);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.getCapabilities(String)).toHaveLength(1);
+    expect(manager.context.requestCapabilities(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.getCapabilities(String)).toHaveLength(0);
+    expect(manager.context.requestCapabilities(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.getCapabilities(String)).toHaveLength(1);
+    expect(manager.context.requestCapabilities(String)).toHaveLength(1);
     expect(count).toEqual(1);
 
     await manager.activate(Events.Startup);
     expect(manager.active).toEqual([Hello.id]);
-    expect(manager.context.getCapabilities(String)).toHaveLength(1);
+    expect(manager.context.requestCapabilities(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: PluginContext) => {
-      const numbers = context.getCapabilities(Number);
+    const computeTotal = (context: PluginsContext) => {
+      const numbers = context.requestCapabilities(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.getCapabilities(Total);
+      const totals = manager.context.requestCapabilities(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.getCapabilities(Total);
+      const totals = manager.context.requestCapabilities(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.getCapabilities(Total);
+      const totals = manager.context.requestCapabilities(Total);
       expect(totals).toHaveLength(1);
       expect(totals[0].total).toEqual(6);
     }
@@ -358,14 +358,14 @@ describe('PluginManager', () => {
         id,
         activatesOn: Events.Startup,
         activatesAfter: [stateEvent],
-        activate: () => contributes(Number, live({ number: 1 })),
+        activate: () => contributes(Number, create({ number: 1 })),
       }),
       defineModule({
         id: 'dxos.org/test/doubler',
         activatesOn: stateEvent,
         activate: (context) => {
-          const counter = context.getCapability(Number);
-          const state = live({ total: counter.number * 2 });
+          const counter = context.requestCapability(Number);
+          const state = create({ 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.getCapability(Number);
-    const doubler = manager.context.getCapability(Total);
+    const counter = manager.context.requestCapability(Number);
+    const doubler = manager.context.requestCapability(Total);
     expect(counter.number).toEqual(1);
     expect(doubler.total).toEqual(2);
 

package/src/core/manager.ts

@@ -2,16 +2,15 @@
 // 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';
 
 import { Event } from '@dxos/async';
-import { live, type Live } from '@dxos/live-object';
+import { create, type ReactiveObject } from '@dxos/live-object';
 import { log } from '@dxos/log';
 import { type MaybePromise } from '@dxos/util';
 
-import { type AnyCapability, PluginContext } from './capabilities';
+import { type AnyCapability, PluginsContext } from './capabilities';
 import { type ActivationEvent, eventKey, getEvents, isAllOf } from './events';
 import { type PluginModule, type Plugin } from './plugin';
 
@@ -25,7 +24,6 @@ export type PluginManagerOptions = {
   plugins?: Plugin[];
   core?: string[];
   enabled?: string[];
-  registry?: Registry.Registry;
 };
 
 type PluginManagerState = {
@@ -45,11 +43,13 @@ type PluginManagerState = {
 
 export class PluginManager {
   readonly activation = new Event<{ event: string; state: 'activating' | 'activated' | 'error'; error?: any }>();
-  readonly context: PluginContext;
-  readonly registry: Registry.Registry;
 
-  // TODO(wittjosiah): Replace with Rx.
-  private readonly _state: Live<PluginManagerState>;
+  readonly context = new PluginsContext({
+    activate: (event) => this._activate(event),
+    reset: (id) => this._reset(id),
+  });
+
+  private readonly _state: ReactiveObject<PluginManagerState>;
   private readonly _pluginLoader: PluginManagerOptions['pluginLoader'];
   private readonly _capabilities = new Map<string, AnyCapability[]>();
 
@@ -58,17 +58,9 @@ 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({
+    this._state = create({
       plugins,
       core,
       enabled,
@@ -87,7 +79,7 @@ export class PluginManager {
    *
    * @reactive
    */
-  get plugins(): Live<readonly Plugin[]> {
+  get plugins(): ReactiveObject<readonly Plugin[]> {
     return this._state.plugins;
   }
 
@@ -96,7 +88,7 @@ export class PluginManager {
    *
    * @reactive
    */
-  get core(): Live<readonly string[]> {
+  get core(): ReactiveObject<readonly string[]> {
     return this._state.core;
   }
 
@@ -105,7 +97,7 @@ export class PluginManager {
    *
    * @reactive
    */
-  get enabled(): Live<readonly string[]> {
+  get enabled(): ReactiveObject<readonly string[]> {
     return this._state.enabled;
   }
 
@@ -114,7 +106,7 @@ export class PluginManager {
    *
    * @reactive
    */
-  get modules(): Live<readonly PluginModule[]> {
+  get modules(): ReactiveObject<readonly PluginModule[]> {
     return this._state.modules;
   }
 
@@ -123,7 +115,7 @@ export class PluginManager {
    *
    * @reactive
    */
-  get active(): Live<readonly string[]> {
+  get active(): ReactiveObject<readonly string[]> {
     return this._state.active;
   }
 
@@ -132,7 +124,7 @@ export class PluginManager {
    *
    * @reactive
    */
-  get eventsFired(): Live<readonly string[]> {
+  get eventsFired(): ReactiveObject<readonly string[]> {
     return this._state.eventsFired;
   }
 
@@ -141,7 +133,7 @@ export class PluginManager {
    *
    * @reactive
    */
-  get pendingReset(): Live<readonly string[]> {
+  get pendingReset(): ReactiveObject<readonly string[]> {
     return this._state.pendingReset;
   }
 

package/src/core/plugin.ts

@@ -4,7 +4,7 @@
 
 import { type MaybePromise } from '@dxos/util';
 
-import { type AnyCapability, type PluginContext } from './capabilities';
+import { type AnyCapability, type PluginsContext } from './capabilities';
 import { type ActivationEvent, type ActivationEvents } from './events';
 
 interface PluginModuleInterface {
@@ -36,13 +36,13 @@ interface PluginModuleInterface {
    * @returns The capabilities of the module.
    */
   activate: (
-    context: PluginContext,
+    context: PluginsContext,
   ) => MaybePromise<AnyCapability | AnyCapability[]> | Promise<() => Promise<AnyCapability | AnyCapability[]>>;
 }
 
 /**
  * A unit of containment of modular functionality that can be provided to an application.
- * Activation of a module is async allowing for code to split and loaded lazily.
+ * Plugins provide things like components, state, actions, etc. to the application.
  */
 // NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
 export class PluginModule implements PluginModuleInterface {
@@ -114,7 +114,6 @@ export type PluginMeta = {
 
 /**
  * A collection of modules that are be enabled/disabled as a unit.
- * Plugins provide things such as components, state, actions, etc. to the application.
  */
 // NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
 export class Plugin {

package/src/playground/generator/generator.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+import { Schema as S } 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 Schema.TaggedClass<Alert>()(`${createPluginId(id)}/action/alert`, {
-    input: Schema.Void,
-    output: Schema.Void,
+  class Alert extends S.TaggedClass<Alert>()(`${createPluginId(id)}/action/alert`, {
+    input: S.Void,
+    output: S.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 } from 'effect';
+import { Schema as S } from 'effect';
 
-export class Log extends Schema.TaggedClass<Log>()('dxos.org/test/logger/log', {
-  input: Schema.Struct({
-    message: Schema.String,
+export class Log extends S.TaggedClass<Log>()('dxos.org/test/logger/log', {
+  input: S.Struct({
+    message: S.String,
   }),
-  output: Schema.Void,
+  output: S.Void,
 }) {}

package/src/playground/playground.stories.tsx

@@ -34,5 +34,5 @@ export const Playground = {};
 export default {
   title: 'sdk/app-framework/playground',
   render: Story,
-  decorators: [withTheme, withLayout()],
+  decorators: [withTheme, withLayout({ tooltips: true })],
 };

package/src/plugin-intent/actions.ts

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