@dxos/app-framework 0.8.3 → 0.8.4-main.1068cf700f

package/src/common/capabilities.ts

@@ -2,111 +2,177 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Registry } from '@effect-rx/rx-react';
-import { type Schema } from 'effect';
-import { type FC, type PropsWithChildren } from 'react';
-
-import { type ExecutableTool } from '@dxos/ai';
-import { type GraphBuilder, type BuilderExtensions } from '@dxos/app-graph';
-import { type ArtifactDefinition } from '@dxos/artifact';
-import { type Space } from '@dxos/client-protocol';
-import { type RootSettingsStore } from '@dxos/local-storage';
-import { type AnchoredTo } from '@dxos/schema';
-
-import { type FileInfo } from './file';
-import { type NodeSerializer } from './graph';
-import { type SurfaceDefinition } from './surface';
-import { type Resource } from './translations';
-import { type PluginManager, defineCapability } 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 const RxRegistry = defineCapability<Registry.Registry>('dxos.org/app-framework/capability/rx-registry');
-
-  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 type Layout = Readonly<{
-    mode: string;
-    dialogOpen: boolean;
-    sidebarOpen: boolean;
-    complementarySidebarOpen: boolean;
-    /**
-     * The id of the active workspace, where a workspace is a set of active items.
-     */
-    workspace: string;
-    /**
-     * Identifiers of items which are currently active in the application.
-     */
-    active: string[];
-    /**
-     * Identifiers of items which were previously active in the application.
-     */
-    inactive: string[];
-    /**
-     * Identifier of the item which should be scrolled into view.
-     */
-    scrollIntoView: string | undefined;
-  }>;
-  export const Layout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
-
-  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<BuilderExtensions>(
-    '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 = {
-    prefix: string;
-    schema: Schema.Schema.All;
-    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 const Tools = defineCapability<ExecutableTool[]>('dxos.org/app-framework/capability/tools');
-  export const ArtifactDefinition = defineCapability<ArtifactDefinition>(
-    'dxos.org/app-framework/capability/artifact-definition',
-  );
-
-  export type FileUploader = (file: File, space: Space) => Promise<FileInfo | undefined>;
-  export const FileUploader = defineCapability<FileUploader>('dxos.org/app-framework/capability/file-uploader');
-
-  type AnchorSort = {
-    key: string;
-    sort: (anchorA: AnchoredTo, anchorB: AnchoredTo) => number;
-  };
-  export const AnchorSort = defineCapability<AnchorSort>('dxos.org/app-framework/capability/anchor-sort');
-}
+import type * as Command$ from '@effect/cli/Command';
+import { type Atom, type Registry } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+import type * as Layer$ from 'effect/Layer';
+import type * as ManagedRuntime$ from 'effect/ManagedRuntime';
+import type { FC, PropsWithChildren } from 'react';
+
+import type { OperationInvoker as OperationInvoker$, OperationResolver as OperationResolver$ } from '@dxos/operation';
+
+import { Capability as Capability$, type PluginManager as PluginManager$ } from '../core';
+import type {
+  HistoryTracker as HistoryTracker$,
+  UndoMapping as UndoMapping$,
+  UndoRegistry as UndoRegistry$,
+} from '../plugin-operation';
+import type { Surface } from '../ui';
+
+/**
+ * Null capability.
+ * @category Capability
+ */
+export const Null = Capability$.make<null>('dxos.org/app-framework/capability/null');
+
+/**
+ * @category Capability
+ */
+export const PluginManager = Capability$.make<PluginManager$.PluginManager>(
+  'dxos.org/app-framework/capability/plugin-manager',
+);
+
+/**
+ * @category Capability
+ */
+export const AtomRegistry = Capability$.make<Registry.Registry>('dxos.org/app-framework/capability/atom-registry');
+
+export type ReactContext = Readonly<{
+  id: string;
+  dependsOn?: string[];
+  context: FC<PropsWithChildren>;
+}>;
+
+/**
+ * @category Capability
+ */
+export const ReactContext = Capability$.make<ReactContext>('dxos.org/app-framework/capability/react-context');
+
+export type ReactRoot = Readonly<{ id: string; root: FC<PropsWithChildren> }>;
+
+/**
+ * @category Capability
+ */
+export const ReactRoot = Capability$.make<ReactRoot>('dxos.org/app-framework/capability/react-root');
+
+/**
+ * Surface definitions that can be either React components or Web Components.
+ */
+export type ReactSurface = Surface.Definition | readonly Surface.Definition[];
+
+/**
+ * @category Capability
+ */
+export const ReactSurface = Capability$.make<ReactSurface>('dxos.org/app-framework/common/react-surface');
+
+export type AnyCommand = Command$.Command<any, any, any, any>;
+
+/**
+ * @category Capability
+ */
+export const Command = Capability$.make<AnyCommand>('dxos.org/app-framework/capability/command');
+
+/**
+ * @category Capability
+ */
+export const Layer = Capability$.make<Layer$.Layer<any, any, any>>('dxos.org/app-framework/capability/layer');
+
+export type ManagedRuntime = ManagedRuntime$.ManagedRuntime<any, any>;
+
+/**
+ * @category Capability
+ */
+export const ManagedRuntime = Capability$.make<ManagedRuntime>('dxos.org/app-framework/capability/managed-runtime');
+
+//
+// Operation System Capabilities
+//
+
+export type OperationResolver = OperationResolver$.OperationResolver<any, any, any, any>;
+
+/**
+ * Handler registration for operations - contributed by plugins.
+ * @category Capability
+ */
+export const OperationResolver = Capability$.make<OperationResolver[]>(
+  'dxos.org/app-framework/capability/operation-resolver',
+);
+
+export type UndoMapping = UndoMapping$.UndoMapping;
+
+/**
+ * Undo mapping registration - contributed by plugins.
+ * @category Capability
+ */
+export const UndoMapping = Capability$.make<UndoMapping[]>('dxos.org/app-framework/capability/undo-mapping');
+
+export type OperationInvoker = OperationInvoker$.OperationInvoker;
+
+/**
+ * Operation invoker - provided by OperationPlugin.
+ * @category Capability
+ */
+export const OperationInvoker = Capability$.make<OperationInvoker>(
+  'dxos.org/app-framework/capability/operation-invoker',
+);
+
+export type UndoRegistry = UndoRegistry$.UndoRegistry;
+
+/**
+ * Undo registry - provided by OperationPlugin.
+ * @category Capability
+ */
+export const UndoRegistry = Capability$.make<UndoRegistry>('dxos.org/app-framework/capability/undo-registry');
+
+export type HistoryTracker = HistoryTracker$.HistoryTracker;
+
+/**
+ * History tracker - provided by OperationPlugin.
+ * @category Capability
+ */
+export const HistoryTracker = Capability$.make<HistoryTracker>('dxos.org/app-framework/capability/history-tracker');
+
+//
+// Atom Capability Helpers
+//
+
+/**
+ * Get the current value of an atom capability.
+ * @example const settings = yield* Capabilities.getAtomValue(ThreadCapabilities.Settings);
+ */
+export const getAtomValue = <T>(
+  atomCapability: Capability$.InterfaceDef<Atom.Atom<T>>,
+): Effect.Effect<T, Error, Capability$.Service> =>
+  Effect.gen(function* () {
+    const registry = yield* Capability$.get(AtomRegistry);
+    const atom = yield* Capability$.get(atomCapability);
+    return registry.get(atom);
+  });
+
+/**
+ * Update an atom capability value (requires writable atom).
+ * @example yield* Capabilities.updateAtomValue(ThreadCapabilities.Settings, (s) => ({ ...s, foo: true }));
+ */
+export const updateAtomValue = <T>(
+  atomCapability: Capability$.InterfaceDef<Atom.Writable<T>>,
+  fn: (current: T) => T,
+): Effect.Effect<void, Error, Capability$.Service> =>
+  Effect.gen(function* () {
+    const registry = yield* Capability$.get(AtomRegistry);
+    const atom = yield* Capability$.get(atomCapability);
+    registry.set(atom, fn(registry.get(atom)));
+  });
+
+/**
+ * Subscribe to an atom capability.
+ * @example const unsubscribe = yield* Capabilities.subscribeAtom(ThreadCapabilities.Settings, (value) => ...);
+ */
+export const subscribeAtom = <T>(
+  atomCapability: Capability$.InterfaceDef<Atom.Atom<T>>,
+  callback: (value: T) => void,
+): Effect.Effect<() => void, Error, Capability$.Service> =>
+  Effect.gen(function* () {
+    const registry = yield* Capability$.get(AtomRegistry);
+    const atom = yield* Capability$.get(atomCapability);
+    return registry.subscribe(atom, () => callback(registry.get(atom)));
+  });

package/src/common/index.ts

@@ -2,11 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './capabilities';
-export * from './collaboration';
-export * from './events';
-export * from './file';
-export * from './graph';
-export * from './layout';
-export * from './surface';
-export * from './translations';
+export * as Capabilities from './capabilities';
+export * as ActivationEvents from './activation-events';
+export { UndoOperation } from './operations';
+export { Label } from './translations';

package/src/common/operations.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/operation';
+
+import { Capability } from '../core';
+
+import { Label } from './translations';
+
+const UNDO_NAMESPACE = 'dxos.org/app-framework/undo';
+
+/**
+ * Operations related to undo/history functionality.
+ */
+export namespace UndoOperation {
+  /**
+   * Show an undo toast notification.
+   * Fired by HistoryTracker when an undoable operation is tracked.
+   */
+  export const ShowUndo = Operation.make({
+    meta: {
+      key: `${UNDO_NAMESPACE}/operation/show-undo`,
+      name: 'Show Undo',
+      description: 'Show an undo toast notification.',
+    },
+    executionMode: 'sync',
+    services: [Capability.Service],
+    schema: {
+      input: Schema.Struct({
+        message: Schema.optional(Label.annotations({ description: 'The message to display in the undo toast.' })),
+      }),
+      output: Schema.Void,
+    },
+  });
+}

package/src/common/translations.ts

@@ -2,16 +2,24 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema } from 'effect';
-
-export const ResourceKey = Schema.Union(Schema.String, Schema.Record({ key: Schema.String, value: Schema.Any }));
-export type ResourceKey = Schema.Schema.Type<typeof ResourceKey>;
-
-export const ResourceLanguage = Schema.Record({ key: Schema.String, value: ResourceKey });
-export type ResourceLanguage = Schema.Schema.Type<typeof ResourceLanguage>;
+import * as Schema from 'effect/Schema';
 
 /**
- * A resource is a collection of translations for a language.
+ * A Label represents translatable text - either a simple string or a tuple of [key, options].
  */
-export const Resource = Schema.Record({ key: Schema.String, value: ResourceLanguage });
-export type Resource = Schema.Schema.Type<typeof Resource>;
+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>;

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);
+    }),
+  );
+});