@dxos/app-framework 0.7.5-main.9cb18ac → 0.7.5-main.9d2a38b

package/src/App.tsx

@@ -1,63 +1,167 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-import React from 'react';
+import { effect } from '@preact/signals-core';
+import React, { type PropsWithChildren, type ReactNode } from 'react';
 
 import { invariant } from '@dxos/invariant';
+import { create } from '@dxos/live-object';
 
-import { type HostPluginParams, Plugin, HostPlugin } from './plugins';
-import IntentMeta from './plugins/plugin-intent/meta';
-import SettingsMeta from './plugins/plugin-settings/meta';
-import SurfaceMeta from './plugins/plugin-surface/meta';
+import { Capabilities, Events } from './common';
+import { PluginManager, type PluginManagerOptions, type Plugin } from './core';
+import { topologicalSort } from './helpers';
+import { ErrorBoundary, PluginManagerProvider } from './react';
+
+const ENABLED_KEY = 'dxos.org/app-framework/enabled';
+
+export type CreateAppOptions = {
+  pluginManager?: PluginManager;
+  pluginLoader?: PluginManagerOptions['pluginLoader'];
+  plugins?: Plugin[];
+  core?: string[];
+  defaults?: string[];
+  placeholder?: ReactNode;
+  fallback?: ErrorBoundary['props']['fallback'];
+  cacheEnabled?: boolean;
+};
 
 /**
  * Expected usage is for this to be the entrypoint of the application.
  * Initializes plugins and renders the root components.
  *
  * @example
- * const meta = [LayoutMeta, MyPluginMeta];
- * const plugins = {
- *  [LayoutMeta.id]: Plugin.lazy(() => import('./plugins/LayoutPlugin/plugin')),
- *  [MyPluginMeta.id]: Plugin.lazy(() => import('./plugins/MyPlugin/plugin')),
- * };
- * const core = [LayoutMeta.id];
- * const default = [MyPluginMeta.id];
+ * const plugins = [LayoutPlugin(), MyPlugin()];
+ * const core = [LayoutPluginId];
+ * const default = [MyPluginId];
  * const fallback = <div>Initializing Plugins...</div>;
- * const App = createApp({ order, plugins, core, default, fallback });
+ * const App = createApp({ plugins, core, default, fallback });
  * createRoot(document.getElementById('root')!).render(
  *   <StrictMode>
  *     <App />
  *   </StrictMode>,
  * );
  *
+ * @param params.pluginLoader A function which loads new plugins.
  * @param params.plugins All plugins available to the application.
- * @param params.meta All plugin metadata.
  * @param params.core Core plugins which will always be enabled.
  * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
- * @param params.fallback Fallback component to render while plugins are initializing.
+ * @param params.placeholder Placeholder component to render during startup.
+ * @param params.fallback Fallback component to render if an error occurs during startup.
+ * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
  */
-export const createApp = ({ meta, plugins, core, ...params }: HostPluginParams) => {
-  const hostPlugin = HostPlugin({
-    plugins: {
-      ...plugins,
-      [IntentMeta.id]: Plugin.lazy(() => import('./plugins/plugin-intent')),
-      [SettingsMeta.id]: Plugin.lazy(() => import('./plugins/plugin-settings')),
-      [SurfaceMeta.id]: Plugin.lazy(() => import('./plugins/plugin-surface')),
-    },
-    meta: [IntentMeta, SettingsMeta, SurfaceMeta, ...meta],
-    core: [IntentMeta.id, SettingsMeta.id, SurfaceMeta.id, ...core],
-    ...params,
+export const createApp = ({
+  pluginManager,
+  pluginLoader: _pluginLoader,
+  plugins = [],
+  core = plugins.map(({ meta }) => meta.id),
+  defaults = [],
+  placeholder = null,
+  fallback = DefaultFallback,
+  cacheEnabled = false,
+}: CreateAppOptions) => {
+  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
+  const pluginLoader =
+    _pluginLoader ??
+    ((id: string) => {
+      const plugin = plugins.find((plugin) => plugin.meta.id === id);
+      invariant(plugin, `Plugin not found: ${id}`);
+      return plugin;
+    });
+
+  const state = create({ ready: false, error: null });
+  const cached: string[] = JSON.parse(localStorage.getItem(ENABLED_KEY) ?? '[]');
+  const enabled = cacheEnabled && cached.length > 0 ? cached : defaults;
+  const manager = pluginManager ?? new PluginManager({ pluginLoader, plugins, core, enabled });
+
+  manager.activation.on(({ event, state: _state, error }) => {
+    if (event === Events.Startup.id) {
+      state.ready = _state === 'activated';
+    }
+
+    if (error && !state.ready && !state.error) {
+      state.error = error;
+    }
+  });
+
+  effect(() => {
+    cacheEnabled && localStorage.setItem(ENABLED_KEY, JSON.stringify(manager.enabled));
+  });
+
+  manager.context.contributeCapability({
+    interface: Capabilities.PluginManager,
+    implementation: manager,
+    module: 'dxos.org/app-framework/plugin-manager',
   });
 
-  invariant(hostPlugin.provides);
-  const { context: Context, root: Root } = hostPlugin.provides;
-  invariant(Context);
-  invariant(Root);
+  setupDevtools(manager);
+
+  void manager.activate(Events.Startup);
 
   return () => (
-    <Context>
-      <Root />
-    </Context>
+    <ErrorBoundary fallback={fallback}>
+      <App placeholder={placeholder} manager={manager} state={state} />
+    </ErrorBoundary>
   );
 };
+
+type AppProps = Required<Pick<CreateAppOptions, 'placeholder'>> & {
+  manager: PluginManager;
+  state: { ready: boolean; error: unknown };
+};
+
+const App = ({ placeholder, manager, state }: AppProps) => {
+  if (state.error) {
+    // This trigger the error boundary to provide UI feedback for the startup error.
+    throw state.error;
+  }
+
+  // TODO(wittjosiah): Consider using Suspense instead?
+  if (!state.ready) {
+    return <>{placeholder}</>;
+  }
+
+  const reactContexts = manager.context.requestCapabilities(Capabilities.ReactContext);
+  const reactRoots = manager.context.requestCapabilities(Capabilities.ReactRoot);
+
+  const ComposedContext = composeContexts(reactContexts);
+  return (
+    <PluginManagerProvider value={manager}>
+      <ComposedContext>
+        {reactRoots.map(({ id, root: Component }) => (
+          <Component key={id} />
+        ))}
+      </ComposedContext>
+    </PluginManagerProvider>
+  );
+};
+
+// Default fallback does not use tailwind or theme.
+const DefaultFallback = ({ error }: { error: Error }) => {
+  return (
+    <div style={{ padding: '1rem' }}>
+      {/* TODO(wittjosiah): Link to docs for replacing default. */}
+      <h1 style={{ fontSize: '1.2rem', fontWeight: 700, margin: '0.5rem 0' }}>{error.message}</h1>
+      <pre>{error.stack}</pre>
+    </div>
+  );
+};
+
+const composeContexts = (contexts: Capabilities.ReactContext[]) => {
+  if (contexts.length === 0) {
+    return ({ children }: PropsWithChildren) => <>{children}</>;
+  }
+
+  return topologicalSort(contexts)
+    .map(({ context }) => context)
+    .reduce((Acc, Next) => ({ children }) => (
+      <Acc>
+        <Next>{children}</Next>
+      </Acc>
+    ));
+};
+
+const setupDevtools = (manager: PluginManager) => {
+  (globalThis as any).composer ??= {};
+  (globalThis as any).composer.manager = manager;
+};

package/src/common/capabilities.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type FC, type PropsWithChildren } from 'react';
+
+import { type GraphBuilder } from '@dxos/app-graph';
+import { type Space } from '@dxos/client-protocol';
+import { type S } from '@dxos/echo-schema';
+import { type RootSettingsStore } from '@dxos/local-storage';
+import { type DeepReadonly } from '@dxos/util';
+
+import { type FileInfo } from './file';
+import { type NodeSerializer } from './graph';
+import { type Layout } from './layout';
+import { type LayoutParts } from './navigation';
+import { type SurfaceDefinition } from './surface';
+import { type Resource } from './translations';
+import { defineCapability, type PluginManager } from '../core';
+import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
+
+export namespace Capabilities {
+  export const PluginManager = defineCapability<PluginManager>('dxos.org/app-framework/capability/plugin-manager');
+
+  export const Null = defineCapability<null>('dxos.org/app-framework/capability/null');
+
+  export type ReactContext = Readonly<{ id: string; dependsOn?: string[]; context: FC<PropsWithChildren> }>;
+  export const ReactContext = defineCapability<ReactContext>('dxos.org/app-framework/capability/react-context');
+
+  export type ReactRoot = Readonly<{ id: string; root: FC<PropsWithChildren> }>;
+  export const ReactRoot = defineCapability<ReactRoot>('dxos.org/app-framework/capability/react-root');
+
+  export type ReactSurface = SurfaceDefinition | readonly SurfaceDefinition[];
+  export const ReactSurface = defineCapability<ReactSurface>('dxos.org/app-framework/common/react-surface');
+
+  export type IntentResolver = AnyIntentResolver | readonly AnyIntentResolver[];
+  export const IntentResolver = defineCapability<IntentResolver>('dxos.org/app-framework/capability/intent-resolver');
+
+  export const IntentDispatcher = defineCapability<IntentContext>(
+    'dxos.org/app-framework/capability/intent-dispatcher',
+  );
+
+  export const Layout = defineCapability<Readonly<Layout>>('dxos.org/app-framework/capability/layout');
+  export const MutableLayout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
+
+  export type MutableLocation = { active: LayoutParts; closed: string[] };
+  export type Location = DeepReadonly<MutableLocation>;
+  export const Location = defineCapability<Location>('dxos.org/app-framework/capability/location');
+  export const MutableLocation = defineCapability<MutableLocation>('dxos.org/app-framework/capability/location');
+
+  export const Translations = defineCapability<Readonly<Resource[]>>('dxos.org/app-framework/capability/translations');
+
+  export const AppGraph = defineCapability<Readonly<Pick<GraphBuilder, 'graph' | 'explore'>>>(
+    'dxos.org/app-framework/capability/app-graph',
+  );
+
+  export const AppGraphBuilder = defineCapability<Parameters<GraphBuilder['addExtension']>[0]>(
+    'dxos.org/app-framework/capability/app-graph-builder',
+  );
+
+  export const AppGraphSerializer = defineCapability<NodeSerializer[]>(
+    'dxos.org/app-framework/capability/app-graph-serializer',
+  );
+
+  export const SettingsStore = defineCapability<RootSettingsStore>('dxos.org/app-framework/capability/settings-store');
+
+  // TODO(wittjosiah): The generics caused type inference issues for schemas when contributing settings.
+  // export type Settings = Parameters<RootSettingsStore['createStore']>[0];
+  // export type Settings<T extends SettingsValue = SettingsValue> = SettingsProps<T>;
+  export type Settings = {
+    schema: S.Schema.All;
+    prefix: string;
+    value?: Record<string, any>;
+  };
+  export const Settings = defineCapability<Settings>('dxos.org/app-framework/capability/settings');
+
+  export type Metadata = Readonly<{ id: string; metadata: Record<string, any> }>;
+  export const Metadata = defineCapability<Metadata>('dxos.org/app-framework/capability/metadata');
+
+  export type FileUploader = (file: File, space: Space) => Promise<FileInfo | undefined>;
+  export const FileUploader = defineCapability<FileUploader>('dxos.org/app-framework/capability/file-uploader');
+}

package/src/common/events.ts

@@ -0,0 +1,63 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities } from './capabilities';
+import { defineEvent } from '../core';
+
+export namespace Events {
+  /**
+   * Fired when the app is started.
+   */
+  export const Startup = defineEvent('dxos.org/app-framework/event/startup');
+
+  //
+  // Dependent Events
+  //
+
+  /**
+   * Fired before the intent dispatcher is activated.
+   */
+  export const SetupIntents = defineEvent('dxos.org/app-framework/event/setup-intents');
+
+  /**
+   * Fired before the settings store is activated.
+   */
+  export const SetupSettings = defineEvent('dxos.org/app-framework/event/setup-settings');
+
+  /**
+   * Fired before the graph is created.
+   */
+  export const SetupAppGraph = defineEvent('dxos.org/app-framework/event/setup-graph');
+
+  /**
+   * Fired before the translations provider is created.
+   */
+  export const SetupTranslations = defineEvent('dxos.org/app-framework/event/setup-translations');
+
+  //
+  // Triggered Events
+  //
+
+  /**
+   * Fired after the intent dispatcher is ready.
+   */
+  export const DispatcherReady = defineEvent('dxos.org/app-framework/event/dispatcher-ready');
+
+  /**
+   * Fired after the settings store is ready.
+   */
+  export const SettingsReady = defineEvent('dxos.org/app-framework/event/settings-ready');
+
+  /**
+   * Fired when the graph is ready.
+   */
+  export const AppGraphReady = defineEvent('dxos.org/app-framework/event/graph-ready');
+
+  /**
+   * Fired when plugin state is ready.
+   */
+  export const createStateEvent = (specifier: string) => defineEvent('dxos.org/app-framework/event/state', specifier);
+  export const LayoutReady = createStateEvent(Capabilities.Layout.identifier);
+  export const LocationReady = createStateEvent(Capabilities.Location.identifier);
+}

package/src/common/file.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { S } from '@dxos/echo-schema';
+
+// TODO(burdon): See Accept attribute (uses MIME types).
+// E.g., 'image/*': ['.jpg', '.jpeg', '.png', '.gif'],
+export const defaultFileTypes = {
+  images: ['png', 'jpg', 'jpeg', 'gif'],
+  media: ['mp3', 'mp4', 'mov', 'avi'],
+  text: ['pdf', 'txt', 'md'],
+};
+
+export const FileInfoSchema = S.Struct({
+  name: S.String,
+  type: S.String,
+  url: S.optional(S.String),
+  cid: S.optional(S.String), // TODO(burdon): Meta key? Or other common properties with other file management system? (e.g., WNFS).
+});
+
+export type FileInfo = S.Schema.Type<typeof FileInfoSchema>;

package/src/common/graph.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { Node } from '@dxos/app-graph';
+import { type MaybePromise } from '@dxos/util';
+
+// TODO(wittjosiah): Factor out.
+export type SerializedNode = {
+  name: string;
+  data: string;
+  type?: string;
+};
+
+// TODO(wittjosiah): Factor out.
+export type NodeSerializer<T = any> = {
+  inputType: string;
+  outputType: string;
+  disposition?: 'hoist' | 'fallback';
+
+  /**
+   * Takes a node and serializes it into a format that can be stored.
+   */
+  serialize: (node: Node<T>) => MaybePromise<SerializedNode>;
+
+  /**
+   * Takes a serialized node and deserializes it into the application.
+   */
+  deserialize: (data: SerializedNode, ancestors: unknown[]) => MaybePromise<T>;
+};

package/src/{plugins/common → common}/index.ts

@@ -2,9 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
+export * from './capabilities';
+export * from './events';
 export * from './file';
 export * from './graph';
 export * from './layout';
-export * from './metadata';
 export * from './navigation';
+export * from './surface';
 export * from './translations';

package/src/{plugins/common → common}/layout.ts

@@ -4,7 +4,6 @@
 
 import { S } from '@dxos/echo-schema';
 
-import { type Plugin } from '../plugin-host';
 import { Label } from '../plugin-intent';
 
 //
@@ -76,21 +75,6 @@ export const Layout = S.mutable(
 
 export type Layout = S.Schema.Type<typeof Layout>;
 
-/**
- * Provides for a plugin that can manage the app layout.
- */
-export type LayoutProvides = {
-  layout: Readonly<Layout>;
-};
-
-/**
- * Type guard for layout plugins.
- */
-export const parseLayoutPlugin = (plugin: Plugin) => {
-  const success = S.is(Layout)((plugin.provides as any).layout);
-  return success ? (plugin as Plugin<LayoutProvides>) : undefined;
-};
-
 //
 // Intents
 //

package/src/{plugins/common → common}/navigation.ts

@@ -6,8 +6,6 @@ import { Schema as S } from '@effect/schema';
 
 import { pick } from '@dxos/util';
 
-import { type Plugin } from '../plugin-host';
-
 // NOTE(thure): These are chosen from RFC 1738’s `safe` characters: http://www.faqs.org/rfcs/rfc1738.html
 export const SLUG_LIST_SEPARATOR = '+';
 export const SLUG_ENTRY_SEPARATOR = '_';
@@ -84,19 +82,6 @@ export const isLayoutAdjustment = (value: unknown): value is LayoutAdjustment =>
   return S.is(LayoutAdjustmentSchema)(value);
 };
 
-export const parseNavigationPlugin = (plugin: Plugin): Plugin<LocationProvides> | undefined => {
-  const location = (plugin.provides as any)?.location;
-  if (!location) {
-    return undefined;
-  }
-
-  if (S.is(LocationProvidesSchema)({ location })) {
-    return plugin as Plugin<LocationProvides>;
-  }
-
-  return undefined;
-};
-
 /**
  * Utilities.
  */

package/src/{plugins/plugin-surface/SurfaceContext.ts → common/surface.ts}

@@ -2,12 +2,11 @@
 // Copyright 2023 DXOS.org
 //
 
-import { createContext, useContext, type JSX, type ForwardedRef, type PropsWithChildren, type ReactNode } from 'react';
+import { type JSX, type ForwardedRef, type PropsWithChildren, type ReactNode } from 'react';
 
-import { raise } from '@dxos/debug';
-import { type GuardedType, type MakeOptional } from '@dxos/util';
+import { type GuardedType, type MakeOptional, type Disposition } from '@dxos/util';
 
-import { type ErrorBoundary } from './ErrorBoundary';
+import { type ErrorBoundary } from '../react';
 
 /**
  * SurfaceProps are the props that are passed to the Surface component.
@@ -68,45 +67,15 @@ export type SurfaceComponent<T extends Record<string, any> = Record<string, unkn
   forwardedRef: ForwardedRef<HTMLElement>,
 ) => JSX.Element | null;
 
-/**
- * Determines the priority of the surface when multiple components are resolved.
- *
- * - `static` - The component is rendered in the order it was resolved.
- * - `hoist` - The component is rendered before `static` components.
- * - `fallback` - The component is rendered after `static` components.
- */
-export type SurfaceDisposition = 'static' | 'hoist' | 'fallback';
-
 /**
  * Definition of when a SurfaceComponent should be rendered.
  */
-export type SurfaceDefinition<T extends Record<string, any> = any> = {
+export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
   id: string;
   role: string | string[];
-  disposition?: SurfaceDisposition;
+  disposition?: Disposition;
   filter?: (data: Record<string, unknown>) => data is T;
   component: SurfaceComponent<GuardedType<SurfaceDefinition<T>['filter']>>;
-};
+}>;
 
 export const createSurface = <T extends Record<string, any> = any>(definition: SurfaceDefinition<T>) => definition;
-
-/**
- * Surface debug info.
- * NOTE: Short-term measure to track perf issues.
- */
-export type DebugInfo = {
-  id: string;
-  created: number;
-  renderCount: number;
-} & Pick<SurfaceProps, 'role'>;
-
-export type SurfaceContextValue = {
-  surfaces: Record<string, SurfaceDefinition>;
-  debugInfo?: Map<string, DebugInfo>;
-};
-
-const SurfaceContext = createContext<SurfaceContextValue | undefined>(undefined);
-
-export const useSurfaceRoot = () => useContext(SurfaceContext) ?? raise(new Error('Missing SurfaceContext'));
-
-export const SurfaceProvider = SurfaceContext.Provider;

package/src/common/translations.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { z } from 'zod';
+
+// TODO(burdon): Replace zod with effect.
+export const ResourceKey = z.union([z.string(), z.record(z.any())]);
+export type ResourceKey = z.infer<typeof ResourceKey>;
+
+export const ResourceLanguage = z.record(ResourceKey);
+export type ResourceLanguage = z.infer<typeof ResourceLanguage>;
+
+/**
+ * A resource is a collection of translations for a language.
+ */
+export const Resource = z.record(ResourceLanguage);
+export type Resource = z.infer<typeof Resource>;

package/src/core/capabilities.test.ts

@@ -0,0 +1,116 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, expect, it } from 'vitest';
+
+import { updateCounter } from '@dxos/echo-schema/testing';
+import { registerSignalsRuntime } from '@dxos/echo-signals';
+
+import { defineCapability, PluginsContext } from './capabilities';
+
+registerSignalsRuntime();
+
+const defaultOptions = {
+  activate: () => Promise.resolve(false),
+  reset: () => Promise.resolve(false),
+};
+
+describe('PluginsContext', () => {
+  it('should return empty array if no capabilities are contributed', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+  });
+
+  it('should be able to contribute and request capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+  });
+
+  it('should be able to remove capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation]);
+    context.removeCapability(interfaceDef, implementation);
+    expect(context.requestCapabilities(interfaceDef)).toEqual([]);
+  });
+
+  it('should be able to contribute and request multiple implementations', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation1 = { example: 'first' };
+    const implementation2 = { example: 'second' };
+    context.contributeCapability({ interface: interfaceDef, implementation: implementation1, module: 'test' });
+    context.contributeCapability({ interface: interfaceDef, implementation: implementation2, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef)).toEqual([implementation1, implementation2]);
+  });
+
+  it('should be able to request multiple capabilities', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef1 = defineCapability<{ one: number }>('@dxos/app-framework/test/one');
+    const interfaceDef2 = defineCapability<{ two: number }>('@dxos/app-framework/test/two');
+    const implementation1 = { one: 1 };
+    const implementation2 = { two: 2 };
+    context.contributeCapability({ interface: interfaceDef1, implementation: implementation1, module: 'test' });
+    context.contributeCapability({ interface: interfaceDef2, implementation: implementation2, module: 'test' });
+    expect(context.requestCapabilities(interfaceDef1)).toEqual([implementation1]);
+    expect(context.requestCapabilities(interfaceDef2)).toEqual([implementation2]);
+  });
+
+  it('should be reactive', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+
+    using updates = updateCounter(() => {
+      context.requestCapabilities(interfaceDef);
+    });
+
+    expect(updates.count).toEqual(0);
+
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(updates.count).toEqual(1);
+
+    context.removeCapability(interfaceDef, implementation);
+    expect(updates.count).toEqual(2);
+  });
+
+  it('should not be reactive to changes within the implementation', () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+
+    using updates = updateCounter(() => {
+      context.requestCapabilities(interfaceDef);
+    });
+
+    expect(updates.count).toEqual(0);
+
+    const implementation = { example: 'identifier' };
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    expect(updates.count).toEqual(1);
+
+    implementation.example = 'updated';
+    expect(updates.count).toEqual(1);
+
+    const capabilities = context.requestCapabilities(interfaceDef);
+    expect(capabilities).toEqual([implementation]);
+    expect(capabilities[0].example).toEqual('updated');
+    expect(updates.count).toEqual(1);
+  });
+
+  it('should be able to wait for a capability', async () => {
+    const context = new PluginsContext(defaultOptions);
+    const interfaceDef = defineCapability<{ example: string }>('@dxos/app-framework/test/example');
+    const implementation = { example: 'identifier' };
+    const promise = context.waitForCapability(interfaceDef);
+    context.contributeCapability({ interface: interfaceDef, implementation, module: 'test' });
+    const capability = await promise;
+    expect(capability).toEqual(implementation);
+  });
+});