@dxos/app-framework 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/common/capabilities.ts

@@ -2,213 +2,172 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Tool, type Toolkit } from '@effect/ai';
-import { type Registry } from '@effect-rx/rx-react';
-import { type Layer, type Schema } from 'effect';
-import { type FC, type PropsWithChildren } from 'react';
-
-import { type AiService, type AiServiceRouter } from '@dxos/ai';
-import { type BuilderExtensions, type GraphBuilder } from '@dxos/app-graph';
-import { type Blueprint } from '@dxos/blueprints';
-import { type Space } from '@dxos/client-protocol';
-import { type FunctionDefinition } from '@dxos/functions';
-import { type RootSettingsStore } from '@dxos/local-storage';
-import { type AnchoredTo } from '@dxos/schema';
-
-import { type PluginManager, defineCapability } from '../core';
-import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
-
-import { type FileInfo } from './file';
-import { type NodeSerializer } from './graph';
-import { type SurfaceDefinition } from './surface';
-import { type Resource } from './translations';
-
-// TODO(burdon): Sort.
-export namespace Capabilities {
-  /**
-   * @category Capability
-   */
-  export const Null = defineCapability<null>('dxos.org/app-framework/capability/null');
-
-  /**
-   * @category Capability
-   */
-  export const PluginManager = defineCapability<PluginManager>('dxos.org/app-framework/capability/plugin-manager');
-
-  /**
-   * @category Capability
-   */
-  export const RxRegistry = defineCapability<Registry.Registry>('dxos.org/app-framework/capability/rx-registry');
-
-  export type ReactContext = Readonly<{ id: string; dependsOn?: string[]; context: FC<PropsWithChildren> }>;
-
-  /**
-   * @category Capability
-   */
-  export const ReactContext = defineCapability<ReactContext>('dxos.org/app-framework/capability/react-context');
-
-  export type ReactRoot = Readonly<{ id: string; root: FC<PropsWithChildren> }>;
-
-  /**
-   * @category Capability
-   */
-  export const ReactRoot = defineCapability<ReactRoot>('dxos.org/app-framework/capability/react-root');
-
-  export type ReactSurface = SurfaceDefinition | readonly SurfaceDefinition[];
-
-  /**
-   * @category Capability
-   */
-  export const ReactSurface = defineCapability<ReactSurface>('dxos.org/app-framework/common/react-surface');
-
-  export type IntentResolver = AnyIntentResolver | readonly AnyIntentResolver[];
-
-  /**
-   * @category Capability
-   */
-  export const IntentResolver = defineCapability<IntentResolver>('dxos.org/app-framework/capability/intent-resolver');
-
-  /**
-   * @category Capability
-   */
-  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;
-  }>;
-
-  /**
-   * @category Capability
-   */
-  export const Layout = defineCapability<Layout>('dxos.org/app-framework/capability/layout');
-
-  /**
-   * @category Capability
-   */
-  export const Translations = defineCapability<Readonly<Resource[]>>('dxos.org/app-framework/capability/translations');
-
-  /**
-   * @category Capability
-   */
-  export const AppGraph = defineCapability<Readonly<Pick<GraphBuilder, 'graph' | 'explore'>>>(
-    'dxos.org/app-framework/capability/app-graph',
-  );
-
-  /**
-   * @category Capability
-   */
-  export const AppGraphBuilder = defineCapability<BuilderExtensions>(
-    'dxos.org/app-framework/capability/app-graph-builder',
-  );
-
-  /**
-   * @category Capability
-   */
-  export const AppGraphSerializer = defineCapability<NodeSerializer[]>(
-    'dxos.org/app-framework/capability/app-graph-serializer',
-  );
-
-  /**
-   * @category Capability
-   */
-  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>;
-  };
-
-  /**
-   * @category Capability
-   */
-  export const Settings = defineCapability<Settings>('dxos.org/app-framework/capability/settings');
-
-  export type Metadata = Readonly<{ id: string; metadata: Record<string, any> }>;
-
-  /**
-   * @category Capability
-   */
-  export const Metadata = defineCapability<Metadata>('dxos.org/app-framework/capability/metadata');
-
-  // TODO(dmaretskyi): Consider combining Toolkit and ToolkitHandler for type-safe context.
-
-  /**
-   * @category Capability
-   */
-  export const Toolkit = defineCapability<Toolkit.Any>('dxos.org/app-framework/capability/ai-toolkit');
-
-  /**
-   * @category Capability
-   */
-  export const ToolkitHandler = defineCapability<Layer.Layer<Tool.Handler<any>, never, never>>(
-    'dxos.org/app-framework/capability/ai-toolkit-handler',
-  );
-
-  /**
-   * @category Capability
-   */
-  export const BlueprintDefinition = defineCapability<Blueprint.Blueprint>(
-    'dxos.org/app-framework/capability/blueprint-definition',
-  );
-
-  export type AiServiceLayer = Layer.Layer<AiService.AiService>;
-  export const AiServiceLayer = defineCapability<AiServiceLayer>(
-    'dxos.org/app-framework/capability/ai-service-factory',
-  );
-
-  /**
-   * Plugins can contribute them to provide model resolvers.
-   */
-  export const AiModelResolver = defineCapability<Layer.Layer<AiServiceRouter.AiModelResolver>>(
-    'dxos.org/app-framework/capability/ai-model-resolver',
-  );
-
-  /**
-   * @category Capability
-   */
-  export const Functions = defineCapability<FunctionDefinition<any, any>[]>(
-    'dxos.org/app-framework/capability/functions',
-  );
-
-  export type FileUploader = (file: File, space: Space) => Promise<FileInfo | undefined>;
-
-  /**
-   * @category Capability
-   */
-  export const FileUploader = defineCapability<FileUploader>('dxos.org/app-framework/capability/file-uploader');
-
-  type AnchorSort = {
-    key: string;
-    sort: (anchorA: AnchoredTo, anchorB: AnchoredTo) => number;
-  };
-
-  /**
-   * @category Capability
-   */
-  export const AnchorSort = defineCapability<AnchorSort>('dxos.org/app-framework/capability/anchor-sort');
-}
+import { type Atom, type Registry } from '@effect-atom/atom-react';
+import type * as Command$ from '@effect/cli/Command';
+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 { OperationHandlerSet } from '@dxos/compute';
+import { OperationInvoker as OperationInvoker$ } 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>('org.dxos.app-framework.capability.null');
+
+/**
+ * @category Capability
+ */
+export const PluginManager = Capability$.make<PluginManager$.PluginManager>(
+  'org.dxos.app-framework.capability.plugin-manager',
+);
+
+/**
+ * @category Capability
+ */
+export const AtomRegistry = Capability$.make<Registry.Registry>('org.dxos.app-framework.capability.atom-registry');
+
+export type ReactContext = Readonly<{
+  id: string;
+  dependsOn?: string[];
+  context: FC<PropsWithChildren>;
+}>;
+
+/**
+ * @category Capability
+ */
+export const ReactContext = Capability$.make<ReactContext>('org.dxos.app-framework.capability.react-context');
+
+export type ReactRoot = Readonly<{ id: string; root: FC<PropsWithChildren> }>;
+
+/**
+ * @category Capability
+ */
+export const ReactRoot = Capability$.make<ReactRoot>('org.dxos.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>('org.dxos.app-framework.common.react-surface');
+
+export type AnyCommand = Command$.Command<any, any, any, any>;
+
+/**
+ * @category Capability
+ */
+export const Command = Capability$.make<AnyCommand>('org.dxos.app-framework.capability.command');
+
+/**
+ * @category Capability
+ */
+export const Layer = Capability$.make<Layer$.Layer<any, any, any>>('org.dxos.app-framework.capability.layer');
+
+export type ManagedRuntime = ManagedRuntime$.ManagedRuntime<any, any>;
+
+/**
+ * @category Capability
+ */
+export const ManagedRuntime = Capability$.make<ManagedRuntime>('org.dxos.app-framework.capability.managed-runtime');
+
+//
+// Operation System Capabilities
+//
+
+export const OperationHandler = Capability$.make<OperationHandlerSet.OperationHandlerSet>(
+  'org.dxos.app-framework.capability.operation-handler',
+);
+
+export type UndoMapping = UndoMapping$.UndoMapping;
+
+/**
+ * Undo mapping registration - contributed by plugins.
+ * @category Capability
+ */
+export const UndoMapping = Capability$.make<UndoMapping[]>('org.dxos.app-framework.capability.undo-mapping');
+
+export type OperationInvoker = OperationInvoker$.OperationInvoker;
+
+/**
+ * Operation invoker - provided by OperationPlugin.
+ * @category Capability
+ */
+export const OperationInvoker = Capability$.make<OperationInvoker>(
+  'org.dxos.app-framework.capability.operation-invoker',
+);
+
+export type UndoRegistry = UndoRegistry$.UndoRegistry;
+
+/**
+ * Undo registry - provided by OperationPlugin.
+ * @category Capability
+ */
+export const UndoRegistry = Capability$.make<UndoRegistry>('org.dxos.app-framework.capability.undo-registry');
+
+export type HistoryTracker = HistoryTracker$.HistoryTracker;
+
+/**
+ * History tracker - provided by OperationPlugin.
+ * @category Capability
+ */
+export const HistoryTracker = Capability$.make<HistoryTracker>('org.dxos.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,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Operation } from '@dxos/compute';
+
+import { Capability } from '../core';
+import { Label } from './translations';
+
+const UNDO_NAMESPACE = 'org.dxos.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],
+    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>('org.dxos.app-framework.plugin-manager');

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

@@ -2,11 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
+import { compositeKey } from '@dxos/util';
+
 /**
  * A unique string identifier representing an event.
  * This is expected to be a URI, where initial parts are often the id of the plugin whose package defines the event.
  *
- * @example dxos.org/plugin/example/event/ready
+ * @example org.dxos.plugin.example.event.ready
  */
 export type ActivationEvent = {
   id: string;
@@ -16,7 +18,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,14 +26,15 @@ 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;
 };
 
 /**
  * Helper to create an activation event key.
  */
-export const eventKey = (event: ActivationEvent) => (event.specifier ? `${event.id}:${event.specifier}` : event.id);
+export const eventKey = (event: ActivationEvent) =>
+  event.specifier ? compositeKey(event.id, event.specifier) : event.id;
 
 /**
  * Helper to create an activation event that triggers when any of the given events are activated.
@@ -46,16 +49,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]);