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

package/src/common/plugin.ts

@@ -0,0 +1,364 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Command$ from '@effect/cli/Command';
+import * as Effect from 'effect/Effect';
+
+import { type Type } from '@dxos/echo';
+
+import { Capability as Capability$, Plugin as Plugin$ } from '../core';
+
+import { ActivationEvent } from './activation-event';
+import { Capability } from './capability';
+import { type Resource } from './translations';
+
+type PluginModuleOptions = Partial<
+  Pick<Plugin$.PluginModuleOptions, 'id' | 'activatesOn' | 'activatesBefore' | 'activatesAfter'>
+> &
+  Pick<Plugin$.PluginModuleOptions, 'activate'>;
+
+/**
+ * Helper functions for creating common plugin module patterns.
+ */
+export namespace Plugin {
+  // TODO(wittjosiah): Restrict type to only allow operation handlers.
+  export type OperationResolverModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes operation handlers.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addOperationResolverModule({
+   *     activate: (context) =>
+   *       Capability.contributes(Common.Capability.OperationResolver, [{
+   *         operation: MyOperation,
+   *         handler: (input) => Effect.succeed(...)
+   *       }])
+   *   })
+   * )
+   * ```
+   */
+  export function addOperationResolverModule<T = void>(
+    options: OperationResolverModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'operation-resolver',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupOperationResolver,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow surfaces.
+  export type SurfaceModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes React surfaces.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addSurfaceModule({
+   *     activate: (context) =>
+   *       Capability.contributes(Common.Capability.ReactSurface, [
+   *         Common.createSurface({ id: `${meta.id}/my-surface`, ... })
+   *       ])
+   *   })
+   * )
+   * ```
+   */
+  export function addSurfaceModule<T = void>(
+    options: SurfaceModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'surfaces',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupReactSurface,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow react roots.
+  export type ReactRootModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes a React root.
+   */
+  export function addReactRootModule<T = void>(
+    options: ReactRootModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'react-root',
+      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow react contexts.
+  export type ReactContextModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes a React context.
+   */
+  export function addReactContextModule<T = void>(
+    options: ReactContextModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'react-context',
+      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow app graph builders.
+  export type AppGraphModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes app graph builder extensions.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addAppGraphModule({
+   *     activate: Effect.fnUntraced(function* () {
+   *       const extensions = yield* GraphBuilder.createExtension({
+   *         id: meta.id,
+   *         match: NodeMatcher.whenRoot,
+   *         // All callbacks must return Effects.
+   *         actions: () => Effect.succeed([{
+   *           id: 'my-action',
+   *           // Action data returns Effect for automatic context access.
+   *           data: Effect.fnUntraced(function* () {
+   *             yield* Operation.invoke(MyOperation, { ... });
+   *           }),
+   *           properties: { label: 'My Action', icon: 'ph--icon' },
+   *         }]),
+   *         connector: (node, get) => Effect.succeed([{ id: 'child', ... }]),
+   *       });
+   *       return Capability.contributes(Common.Capability.AppGraphBuilder, extensions);
+   *     })
+   *   })
+   * )
+   * ```
+   */
+  export function addAppGraphModule<T = void>(
+    options: AppGraphModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'app-graph-builder',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupAppGraph,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  export type TranslationsModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    translations: Resource | Resource[];
+  };
+
+  /**
+   * Creates a module that contributes translations.
+   *
+   * @param options Module options including translations and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addTranslationsModule({
+   *     translations: translations
+   *   })
+   * )
+   * ```
+   */
+  export function addTranslationsModule<T = void>(
+    options: TranslationsModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options?.id ?? 'translations',
+      activatesOn: options?.activatesOn ?? ActivationEvent.SetupTranslations,
+      activatesBefore: options?.activatesBefore,
+      activatesAfter: options?.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return Capability$.contributes(
+          Capability.Translations,
+          Array.isArray(options.translations) ? options.translations : ([options.translations] as Resource[]),
+        );
+      }),
+    });
+  }
+
+  export type MetadataModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    metadata: Capability.Metadata | Capability.Metadata[];
+  };
+
+  /**
+   * Creates a module that contributes metadata.
+   *
+   * @param options Module options including metadata and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addMetadataModule({
+   *     metadata: {
+   *       id: MyType.typename,
+   *       metadata: { icon: 'ph--icon', ... }
+   *     }
+   *   })
+   * )
+   * ```
+   */
+  export function addMetadataModule<T = void>(
+    options: MetadataModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options.id ?? 'metadata',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupMetadata,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return (Array.isArray(options.metadata) ? options.metadata : [options.metadata]).map((m) =>
+          Capability$.contributes(Capability.Metadata, m),
+        );
+      }),
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow settings.
+  export type SettingsModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes settings.
+   */
+  export function addSettingsModule<T = void>(
+    options: SettingsModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'settings',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupSettings,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  // TODO(wittjosiah): Restrict type to only allow blueprint definitions.
+  export type BlueprintDefinitionModuleOptions = PluginModuleOptions;
+
+  /**
+   * Creates a module that contributes blueprint definitions.
+   *
+   * @param options Module options including the activate function and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addBlueprintDefinitionModule({
+   *     activate: (context) =>
+   *       Capability.contributes(Common.Capability.BlueprintDefinition, [
+   *         BlueprintDefinition.make({ key: 'my-blueprint', ... })
+   *       ])
+   *   })
+   * )
+   * ```
+   */
+  export function addBlueprintDefinitionModule<T = void>(
+    options: BlueprintDefinitionModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: Capability$.getModuleTag(options.activate) ?? options.id ?? 'blueprint-definition',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupArtifactDefinition,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: options.activate,
+    });
+  }
+
+  export type SchemaModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    schema: ReadonlyArray<Type.Entity.Any>;
+  };
+
+  /**
+   * Creates a module that contributes schemas.
+   *
+   * @param options Module options including schema array and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addSchemaModule({
+   *     schema: [MyType.Type, AnotherType.Type]
+   *   })
+   * )
+   * ```
+   */
+  export function addSchemaModule<T = void>(
+    options: SchemaModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options.id ?? 'schema',
+      activatesOn: options.activatesOn ?? ActivationEvent.SetupSchema,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return Capability$.contributes(Capability.Schema, options.schema);
+      }),
+    });
+  }
+
+  export type CommandModuleOptions = Omit<PluginModuleOptions, 'activate'> & {
+    commands: ReadonlyArray<Command$.Command<any, any, any, any>>;
+  };
+
+  /**
+   * Creates a module that contributes CLI commands.
+   *
+   * @param options Module options including commands and optional configuration
+   * @returns A function that can be used with Plugin.addModule() in a pipe chain
+   *
+   * @example
+   * ```ts
+   * Plugin.define(meta).pipe(
+   *   Common.Plugin.addCommandModule({
+   *     commands: [myCommand, anotherCommand]
+   *   })
+   * )
+   * ```
+   */
+  export function addCommandModule<T = void>(
+    options: CommandModuleOptions,
+  ): (builder: Plugin$.PluginBuilder<T>) => Plugin$.PluginBuilder<T> {
+    return Plugin$.addModule({
+      id: options.id ?? 'cli-commands',
+      activatesOn: options.activatesOn ?? ActivationEvent.Startup,
+      activatesBefore: options.activatesBefore,
+      activatesAfter: options.activatesAfter,
+      activate: Effect.fnUntraced(function* () {
+        return options.commands.map((cmd) => Capability$.contributes(Capability.Command, cmd));
+      }),
+    });
+  }
+}

package/src/common/surface.ts

@@ -2,11 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
-import type { ComponentType, PropsWithChildren, ReactNode } from 'react';
+import type { PropsWithChildren, ReactNode, RefCallback } from 'react';
 
-import { type MakeOptional, type Position } from '@dxos/util';
+import type { MakeOptional, Position } from '@dxos/util';
 
-import { type ErrorBoundary } from '../react';
+import type { ErrorBoundary } from '../react';
 
 /**
  * SurfaceProps are the props that are passed to the Surface component.
@@ -59,20 +59,22 @@ export type CoreSurfaceProps<T extends Record<string, any> = Record<string, unkn
   limit?: number | undefined;
 }>;
 
-export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> &
-  Record<string, any>;
+export type SurfaceComponentProps<T extends Record<string, any> = Record<string, any>> = CoreSurfaceProps<T> & {
+  ref?: RefCallback<HTMLElement>;
+} & Record<string, any>;
 
 /**
  * React component used to render a surface once is has matched.
  */
-export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = ComponentType<
-  SurfaceComponentProps<T>
->;
+export type SurfaceComponent<T extends Record<string, any> = Record<string, any>> = (
+  props: SurfaceComponentProps<T>,
+) => ReactNode;
 
 /**
- * Definition of when a SurfaceComponent should be rendered.
+ * Definition of when a React SurfaceComponent should be rendered.
  */
-export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+export type ReactSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'react';
   id: string;
   role: string | string[];
   position?: Position;
@@ -81,8 +83,38 @@ export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
 }>;
 
 /**
- * Creates a surface definition.
+ * Definition of when a Web Component surface should be rendered.
+ */
+export type WebComponentSurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
+  kind: 'web-component';
+  id: string;
+  role: string | string[];
+  position?: Position;
+  /**
+   * The tag name of the Web Component to render.
+   * The Web Component will receive the same props as React surfaces via properties/attributes.
+   */
+  tagName: string;
+  filter?: (data: Record<string, unknown>) => data is T;
+}>;
+
+/**
+ * Definition of when a surface (React or Web Component) should be rendered.
+ */
+export type SurfaceDefinition<T extends Record<string, any> = any> =
+  | ReactSurfaceDefinition<T>
+  | WebComponentSurfaceDefinition<T>;
+
+/**
+ * Creates a React surface definition.
  */
 export const createSurface = <T extends Record<string, any> = any>(
-  definition: SurfaceDefinition<T>,
-): SurfaceDefinition<T> => definition;
+  definition: Omit<ReactSurfaceDefinition<T>, 'kind'>,
+): ReactSurfaceDefinition<T> => ({ ...definition, kind: 'react' });
+
+/**
+ * Creates a Web Component surface definition.
+ */
+export const createWebSurface = <T extends Record<string, any> = any>(
+  definition: Omit<WebComponentSurfaceDefinition<T>, 'kind'>,
+): WebComponentSurfaceDefinition<T> => ({ ...definition, kind: 'web-component' });

package/src/common/translations.ts

@@ -4,6 +4,26 @@
 
 import * as Schema from 'effect/Schema';
 
+/**
+ * A Label represents translatable text - either a simple string or a tuple of [key, options].
+ */
+export const Label = Schema.Union(
+  Schema.String,
+  Schema.mutable(
+    Schema.Tuple(
+      Schema.String,
+      Schema.mutable(
+        Schema.Struct({
+          ns: Schema.String,
+          count: Schema.optional(Schema.Number),
+          defaultValue: Schema.optional(Schema.String),
+        }),
+      ),
+    ),
+  ),
+);
+export type Label = Schema.Schema.Type<typeof Label>;
+
 export const ResourceKey = Schema.Union(Schema.String, Schema.Record({ key: Schema.String, value: Schema.Any }));
 export type ResourceKey = Schema.Schema.Type<typeof ResourceKey>;
 

package/src/context.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@dxos/web-context';
+
+import { type PluginManager } from './core';
+
+export const PluginManagerContext = createContext<PluginManager.PluginManager>('dxos.org/app-framework/plugin-manager');

package/src/core/{events.ts → activation-event.ts}

@@ -16,7 +16,7 @@ export type ActivationEvent = {
 /**
  * An activation event that can be a single event, or a combination of events.
  */
-export type ActivationEvents =
+export type Events =
   | ActivationEvent
   | { type: 'one-of'; events: ActivationEvent[] }
   | { type: 'all-of'; events: ActivationEvent[] };
@@ -24,7 +24,7 @@ export type ActivationEvents =
 /**
  * Helper to define an activation event.
  */
-export const defineEvent = (id: string, specifier?: string) => {
+export const make = (id: string, specifier?: string) => {
   return { id, specifier } as ActivationEvent;
 };
 
@@ -46,16 +46,16 @@ export const allOf = (...events: ActivationEvent[]) => ({ type: 'all-of' as cons
 /**
  * Helper to check if an activation event is a one-of event.
  */
-export const isOneOf = (events: ActivationEvents): events is { type: 'one-of'; events: ActivationEvent[] } =>
+export const isOneOf = (events: Events): events is { type: 'one-of'; events: ActivationEvent[] } =>
   'type' in events && events.type === 'one-of';
 
 /**
  * Helper to check if an activation event is an all-of event.
  */
-export const isAllOf = (events: ActivationEvents): events is { type: 'all-of'; events: ActivationEvent[] } =>
+export const isAllOf = (events: Events): events is { type: 'all-of'; events: ActivationEvent[] } =>
   'type' in events && events.type === 'all-of';
 
 /**
  * Helper to get the events from an activation event.
  */
-export const getEvents = (events: ActivationEvents) => ('type' in events ? events.events : [events]);
+export const getEvents = (events: Events) => ('type' in events ? events.events : [events]);

package/src/core/capability-manager.test.ts

@@ -0,0 +1,151 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it, onTestFinished } from '@effect/vitest';
+import { Registry } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import * as Capability from './capability';
+import * as CapabilityManager from './capability-manager';
+
+describe('CapabilityManager', () => {
+  it('should return empty array if no capabilities are contributed', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+    expect(capabilityManager.getAll(interfaceDef)).toEqual([]);
+  });
+
+  it('should throw when getCapability is called and no capability exists', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+    expect(() => capabilityManager.get(interfaceDef)).toThrow('No capability found');
+  });
+
+  it.effect('Capability.get should fail when no capability exists', () =>
+    Effect.gen(function* () {
+      const registry = Registry.make();
+      const capabilityManager = CapabilityManager.make({ registry });
+      const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+
+      const result = yield* Capability.get(interfaceDef).pipe(
+        Effect.provideService(Capability.Service, capabilityManager),
+        Effect.either,
+      );
+
+      expect(result._tag).toEqual('Left');
+    }),
+  );
+
+  it('should be able to contribute and request capabilities', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    capabilityManager.contribute({ interface: interfaceDef, implementation, module: 'test' });
+    expect(capabilityManager.getAll(interfaceDef)).toEqual([implementation]);
+  });
+
+  it('should be able to remove capabilities', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    capabilityManager.contribute({ interface: interfaceDef, implementation, module: 'test' });
+    expect(capabilityManager.getAll(interfaceDef)).toEqual([implementation]);
+    capabilityManager.remove(interfaceDef, implementation);
+    expect(capabilityManager.getAll(interfaceDef)).toEqual([]);
+  });
+
+  it('should be able to contribute and request multiple implementations', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation1 = { example: 'first' };
+    const implementation2 = { example: 'second' };
+    capabilityManager.contribute({ interface: interfaceDef, implementation: implementation1, module: 'test' });
+    capabilityManager.contribute({ interface: interfaceDef, implementation: implementation2, module: 'test' });
+    expect(capabilityManager.getAll(interfaceDef)).toEqual([implementation1, implementation2]);
+  });
+
+  it('should be able to request multiple capabilities', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef1 = Capability.make<{ one: number }>('@dxos/app-framework/test/one');
+    const interfaceDef2 = Capability.make<{ two: number }>('@dxos/app-framework/test/two');
+    const implementation1 = { one: 1 };
+    const implementation2 = { two: 2 };
+    capabilityManager.contribute({ interface: interfaceDef1, implementation: implementation1, module: 'test' });
+    capabilityManager.contribute({ interface: interfaceDef2, implementation: implementation2, module: 'test' });
+    expect(capabilityManager.getAll(interfaceDef1)).toEqual([implementation1]);
+    expect(capabilityManager.getAll(interfaceDef2)).toEqual([implementation2]);
+  });
+
+  it('should be reactive', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+
+    let count = 0;
+    const cancel = registry.subscribe(capabilityManager.atom(interfaceDef), () => {
+      count++;
+    });
+    onTestFinished(() => cancel());
+    expect(count).toEqual(0);
+
+    registry.get(capabilityManager.atom(interfaceDef));
+    expect(count).toEqual(1);
+
+    const implementation = { example: 'identifier' };
+    capabilityManager.contribute({ interface: interfaceDef, implementation, module: 'test' });
+    expect(count).toEqual(2);
+
+    capabilityManager.remove(interfaceDef, implementation);
+    expect(count).toEqual(3);
+  });
+
+  it('should not be reactive to changes within the implementation', () => {
+    const registry = Registry.make();
+    const capabilityManager = CapabilityManager.make({ registry });
+    const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+
+    let count = 0;
+    const cancel = registry.subscribe(capabilityManager.atom(interfaceDef), () => {
+      count++;
+    });
+    onTestFinished(() => cancel());
+    expect(count).toEqual(0);
+
+    registry.get(capabilityManager.atom(interfaceDef));
+    expect(count).toEqual(1);
+
+    const implementation = { example: 'identifier' };
+    capabilityManager.contribute({ interface: interfaceDef, implementation, module: 'test' });
+    expect(count).toEqual(2);
+
+    implementation.example = 'updated';
+    expect(count).toEqual(2);
+
+    const capabilities = capabilityManager.getAll(interfaceDef);
+    expect(capabilities).toEqual([implementation]);
+    expect(capabilities[0].example).toEqual('updated');
+    expect(count).toEqual(2);
+  });
+
+  it.effect('should be able to wait for a capability', () =>
+    Effect.gen(function* () {
+      const registry = Registry.make();
+      const capabilityManager = CapabilityManager.make({ registry });
+      const interfaceDef = Capability.make<{ example: string }>('@dxos/app-framework/test/example');
+
+      expect(capabilityManager.getAll(interfaceDef)).toHaveLength(0);
+      const capability = capabilityManager.waitFor(interfaceDef);
+
+      const implementation = { example: 'identifier' };
+      capabilityManager.contribute({ interface: interfaceDef, implementation, module: 'test' });
+      expect(yield* capability).toEqual(implementation);
+    }),
+  );
+});