@dxos/app-framework 0.7.5-main.499c70c → 0.7.5-main.5ae2ba8

package/src/common/layout.ts

@@ -0,0 +1,238 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema as S } from '@effect/schema';
+
+import { Label } from '../plugin-intent';
+
+export const LAYOUT_PLUGIN = 'dxos.org/plugin/layout';
+export const LAYOUT_ACTION = `${LAYOUT_PLUGIN}/action`;
+
+/**
+ * Expected payload for layout actions.
+ */
+export namespace LayoutAction {
+  export const UPDATE_LAYOUT = `${LAYOUT_ACTION}/update-layout`;
+
+  /**
+   * Generic layout action.
+   */
+  export class UpdateLayout extends S.TaggedClass<UpdateLayout>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.String.annotations({ description: 'The part of the layout to mutate.' }),
+      subject: S.optional(S.Any.annotations({ description: 'The subject of the layout update.' })),
+      options: S.optional(
+        S.Record({ key: S.String, value: S.Any }).annotations({
+          description: 'Additional options for the layout action.',
+        }),
+      ),
+    }),
+    output: S.Void,
+  }) {}
+
+  //
+  // Common layout actions.
+  //
+
+  // NOTE: These are layout actions which are currently in common use.
+  //  They constrain the generic layout action types to provide additional type safety.
+  //  However, they all follow the same generic structure and intent id.
+  //  This allows for plugins to update the layout without depending on a specific layout plugin.
+  //  The expectation is that other norms other than these will emerge over time.
+
+  export class SetLayoutMode extends S.TaggedClass<SetLayoutMode>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('mode').annotations({ description: 'Setting the layout mode.' }),
+      subject: S.optional(S.String.annotations({ description: 'Item which is the subject of the new layout mode.' })),
+      options: S.Union(
+        S.Struct({ mode: S.String.annotations({ description: 'The new layout mode.' }) }),
+        S.Struct({ revert: S.Boolean.annotations({ description: 'Revert to the previous layout mode.' }) }),
+      ),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class UpdateSidebar extends S.TaggedClass<UpdateSidebar>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('sidebar').annotations({ description: 'Updating the sidebar.' }),
+      subject: S.optional(S.String.annotations({ description: 'URI of the component to display in the sidebar.' })),
+      options: S.optional(
+        S.Struct({
+          state: S.Literal('closed', 'collapsed', 'expanded').annotations({
+            description: 'Whether the sidebar is closed, collapsed, or expanded.',
+          }),
+        }),
+      ),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class UpdateComplementary extends S.TaggedClass<UpdateComplementary>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('complementary').annotations({ description: 'Updating the complementary sidebar.' }),
+      subject: S.optional(
+        S.String.annotations({ description: 'URI of the component to display in the complementary area.' }),
+      ),
+      options: S.optional(
+        S.Struct({
+          state: S.Literal('closed', 'collapsed', 'expanded').annotations({
+            description: 'Whether the complementary sidebar is closed, collapsed, or expanded.',
+          }),
+        }),
+      ),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class UpdateDialog extends S.TaggedClass<UpdateDialog>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('dialog').annotations({ description: 'Updating the dialog.' }),
+      subject: S.optional(S.String.annotations({ description: 'URI of the component to display in the dialog.' })),
+      options: S.Struct({
+        state: S.optional(S.Boolean.annotations({ description: 'Whether the dialog is open or closed.' })),
+        blockAlign: S.optional(
+          S.Literal('start', 'center', 'end').annotations({ description: 'The alignment of the dialog.' }),
+        ),
+        type: S.optional(S.Literal('default', 'alert').annotations({ description: 'The type of dialog.' })),
+        props: S.optional(
+          S.Record({ key: S.String, value: S.Any }).annotations({
+            description: 'Additional props for the dialog.',
+          }),
+        ),
+      }),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class UpdatePopover extends S.TaggedClass<UpdatePopover>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('popover').annotations({ description: 'Updating the popover.' }),
+      subject: S.optional(S.String.annotations({ description: 'URI of the component to display in the popover.' })),
+      options: S.Struct({
+        anchorId: S.String.annotations({ description: 'The id of the element to anchor the popover to.' }),
+        side: S.optional(
+          S.Literal('top', 'right', 'bottom', 'left').annotations({ description: 'The side of the anchor.' }),
+        ),
+        state: S.optional(S.Boolean.annotations({ description: 'Whether the popover is open or closed.' })),
+        props: S.optional(
+          S.Record({ key: S.String, value: S.Any }).annotations({
+            description: 'Additional props for the popover.',
+          }),
+        ),
+      }),
+    }),
+    output: S.Void,
+  }) {}
+
+  export const Toast = S.Struct({
+    id: S.String.annotations({ description: 'The id of the toast.' }),
+    title: S.optional(Label.annotations({ description: 'The title of the toast.' })),
+    description: S.optional(Label.annotations({ description: 'The description of the toast.' })),
+    icon: S.optional(S.String.annotations({ description: 'The icon of the toast.' })),
+    duration: S.optional(S.Number.annotations({ description: 'The duration of the toast.' })),
+    closeLabel: S.optional(Label.annotations({ description: 'The label of the close button.' })),
+    actionLabel: S.optional(Label.annotations({ description: 'The label of the action button.' })),
+    actionAlt: S.optional(Label.annotations({ description: 'The alt text of the action button.' })),
+    onAction: S.optional(
+      S.Any.annotations({ description: 'The action to perform when the action button is clicked.' }),
+    ),
+  });
+
+  export interface Toast extends Omit<S.Schema.Type<typeof Toast>, 'onAction'> {
+    onAction?: () => void;
+  }
+
+  export class AddToast extends S.TaggedClass<AddToast>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('toast').annotations({ description: 'Adding a toast.' }),
+      subject: Toast.annotations({ description: 'The toast to add.' }),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class SwitchWorkspace extends S.TaggedClass<SwitchWorkspace>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('workspace').annotations({ description: 'Switching the workspace.' }),
+      subject: S.String.annotations({ description: 'The id of the workspace to switch to.' }),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class RevertWorkspace extends S.TaggedClass<RevertWorkspace>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('workspace').annotations({ description: 'Switching the workspace.' }),
+      options: S.Struct({
+        revert: S.Literal(true).annotations({ description: 'Revert to the previous workspace.' }),
+      }),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class Open extends S.TaggedClass<Open>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('main').annotations({ description: 'Opening an item in the main content area.' }),
+      subject: S.Array(S.String.annotations({ description: 'Ids of the items to open.' })),
+      options: S.optional(
+        S.Struct({
+          state: S.optional(S.Literal(true).annotations({ description: 'The items are being added.' })),
+          key: S.optional(
+            S.String.annotations({ description: 'If provided, will replace item with a matching key (id prefix).' }),
+          ),
+          scrollIntoView: S.optional(S.Boolean.annotations({ description: 'Scroll the items into view.' })),
+          pivotId: S.optional(S.String.annotations({ description: 'The id of the item to place new items next to.' })),
+          positioning: S.optional(
+            S.Union(
+              S.Literal('start').annotations({ description: 'The items are being added before the pivot item.' }),
+              S.Literal('end').annotations({ description: 'The items are being added after the pivot item.' }),
+            ),
+          ),
+        }),
+      ),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class Set extends S.TaggedClass<Set>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('main').annotations({ description: 'Setting items in the main content area.' }),
+      subject: S.Array(S.String.annotations({ description: 'Ids of the items to set.' })),
+      options: S.Struct({
+        override: S.Literal(true).annotations({ description: 'Override the current items in the main content area.' }),
+      }),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class Close extends S.TaggedClass<Close>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('main').annotations({ description: 'Closing items in the main content area.' }),
+      subject: S.Array(S.String.annotations({ description: 'Ids of the items to close.' })),
+      options: S.Struct({
+        state: S.Literal(false).annotations({ description: 'The items are being removed.' }),
+      }),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class ScrollIntoView extends S.TaggedClass<ScrollIntoView>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('current').annotations({ description: 'Setting the current item' }),
+      subject: S.optional(S.String.annotations({ description: 'The id of the item to set as current.' })),
+      options: S.optional(
+        S.Record({ key: S.String, value: S.Any }).annotations({
+          description: 'Additional options for the scroll into view.',
+        }),
+      ),
+    }),
+    output: S.Void,
+  }) {}
+
+  export class Expose extends S.TaggedClass<Expose>()(UPDATE_LAYOUT, {
+    input: S.Struct({
+      part: S.Literal('navigation').annotations({ description: 'Exposing an item in the navigation area.' }),
+      subject: S.String.annotations({ description: 'The id of the item to expose.' }),
+    }),
+    output: S.Void,
+  }) {}
+}

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 Position } 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;
+  position?: Position;
   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,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Schema as S } from '@effect/schema';
+
+export const ResourceKey = S.Union(S.String, S.Record({ key: S.String, value: S.Any }));
+export type ResourceKey = S.Schema.Type<typeof ResourceKey>;
+
+export const ResourceLanguage = S.Record({ key: S.String, value: ResourceKey });
+export type ResourceLanguage = S.Schema.Type<typeof ResourceLanguage>;
+
+/**
+ * A resource is a collection of translations for a language.
+ */
+export const Resource = S.Record({ key: S.String, value: ResourceLanguage });
+export type Resource = S.Schema.Type<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);
+  });
+});

package/src/core/capabilities.ts

@@ -0,0 +1,222 @@
+/**
+ * Interface definition for a capability.
+ */
+//
+// Copyright 2025 DXOS.org
+//
+
+import { effect, untracked } from '@preact/signals-core';
+import { type 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';
+
+import { type ActivationEvent } from './events';
+
+const InterfaceDefTypeId: unique symbol = Symbol.for('InterfaceDefTypeId');
+
+/**
+ * The interface definition of a capability.
+ */
+export type InterfaceDef<T> = {
+  [InterfaceDefTypeId]: T;
+  identifier: string;
+};
+
+/**
+ * Helper to define the interface of a capability.
+ */
+export const defineCapability = <T>(identifier: string) => {
+  return { identifier } as InterfaceDef<T>;
+};
+
+/**
+ * Functionality contributed to the application by a plugin module.
+ */
+export type Capability<T> = {
+  /**
+   * The interface definition of the capability.
+   */
+  interface: InterfaceDef<T>;
+
+  /**
+   * The implementation of the capability.
+   */
+  implementation: T;
+
+  /**
+   * Called when the capability is deactivated.
+   */
+  deactivate?: () => MaybePromise<void> | Effect.Effect<void, Error>;
+};
+
+export type AnyCapability = Capability<any>;
+
+type PluginsContextOptions = {
+  activate: (event: ActivationEvent) => MaybePromise<boolean>;
+  reset: (event: ActivationEvent) => MaybePromise<boolean>;
+};
+
+// NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
+class CapabilityImpl<T> {
+  constructor(
+    readonly moduleId: string,
+    readonly implementation: T,
+  ) {}
+}
+
+/**
+ * Helper to define the implementation of a capability.
+ */
+export const contributes = <T>(
+  interfaceDef: Capability<T>['interface'],
+  implementation: Capability<T>['implementation'],
+  deactivate?: Capability<T>['deactivate'],
+): Capability<T> => {
+  return { interface: interfaceDef, implementation, deactivate } satisfies Capability<T>;
+};
+
+type LoadCapability<T, U> = () => Promise<{ default: (props: T) => MaybePromise<Capability<U>> }>;
+type LoadCapabilities<T> = () => Promise<{ default: (props: T) => MaybePromise<AnyCapability[]> }>;
+// TODO(wittjosiah): Not having the array be `any` causes type errors when using the lazy capability.
+type LazyCapability<T, U> = (props?: T) => Promise<() => Promise<Capability<U> | AnyCapability[]>>;
+
+/**
+ * Helper to define a lazily loaded implementation of a capability.
+ */
+export const lazy =
+  <T, U>(c: LoadCapability<T, U> | LoadCapabilities<T>): LazyCapability<T, U> =>
+  async (props?: T) => {
+    const { default: getCapability } = await c();
+    return async () => getCapability(props as T);
+  };
+
+/**
+ * Context which is passed to plugins, allowing them to interact with each other.
+ */
+export class PluginsContext {
+  private readonly _definedCapabilities = new Map<string, CapabilityImpl<unknown>[]>();
+
+  /**
+   * Activates plugins based on the activation event.
+   * @param event The activation event.
+   * @returns Whether the activation was successful.
+   */
+  readonly activate: PluginsContextOptions['activate'];
+
+  /**
+   * Re-activates the modules that were activated by the event.
+   * @param event The activation event.
+   * @returns Whether the reset was successful.
+   */
+  readonly reset: PluginsContextOptions['reset'];
+
+  constructor({ activate, reset }: PluginsContextOptions) {
+    this.activate = activate;
+    this.reset = reset;
+  }
+
+  /**
+   * @internal
+   */
+  contributeCapability<T>({
+    module: moduleId,
+    interface: interfaceDef,
+    implementation,
+  }: {
+    module: string;
+    interface: InterfaceDef<T>;
+    implementation: T;
+  }) {
+    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);
+    }
+
+    current.push(new CapabilityImpl(moduleId, implementation));
+    log('capability contributed', {
+      id: interfaceDef.identifier,
+      moduleId,
+      count: untracked(() => current.length),
+    });
+  }
+
+  /**
+   * @internal
+   */
+  removeCapability<T>(interfaceDef: InterfaceDef<T>, implementation: T) {
+    const current = this._definedCapabilities.get(interfaceDef.identifier);
+    if (!current) {
+      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) });
+    } else {
+      log.warn('capability not removed', { id: interfaceDef.identifier });
+    }
+  }
+
+  /**
+   * Requests capabilities from the plugin context.
+   * @returns An array of capabilities.
+   * @reactive
+   */
+  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);
+    }
+
+    // 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[];
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Waits for a capability to be contributed.
+   * @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]) {
+        trigger.wake(capabilities[0]);
+      }
+    });
+    const capability = await trigger.wait();
+    unsubscribe();
+    return capability;
+  }
+}