@dxos/app-framework 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

package/src/common/capabilities.ts

@@ -2,112 +2,308 @@
 // 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');
-
-  // TODO(burdon): Why array?
-  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 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 Exit$ from 'effect/Exit';
+import type * as Fiber$ from 'effect/Fiber';
+import type * as Layer$ from 'effect/Layer';
+import type * as ManagedRuntime$ from 'effect/ManagedRuntime';
+import type * as Runtime$ from 'effect/Runtime';
+import type { FC, PropsWithChildren } from 'react';
+
+import type {
+  LayerSpec as LayerSpec$,
+  Operation as Operation$,
+  OperationHandlerSet,
+  Process as Process$,
+  ServiceResolver as ServiceResolver$,
+  Trace as Trace$,
+} from '@dxos/compute';
+import type { ProcessManager as ProcessManager$ } from '@dxos/compute-runtime';
+import { OperationInvoker as OperationInvoker$ } from '@dxos/operation';
+
+import { Capability as Capability$, Plugin as Plugin$, type PluginManager as PluginManager$ } from '../core';
+import type {
+  HistoryTracker as HistoryTracker$,
+  UndoMapping as UndoMapping$,
+  UndoRegistry as UndoRegistry$,
+} from '../plugin-process-manager';
+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');
+
+/**
+ * Layer specification contributed by plugins.
+ *
+ * Plugins contribute {@link LayerSpec.LayerSpec} entries that are collected by the
+ * process-manager module and composed into a {@link LayerStack} which backs the
+ * {@link ProcessManagerRuntime}'s service resolver.
+ *
+ * @category Capability
+ */
+export const LayerSpec = Capability$.make<LayerSpec$.LayerSpec>('org.dxos.app-framework.capability.layer-spec');
+
+/**
+ * Context passed to {@link TraceSinkFactory} implementations when the
+ * process-manager capability materialises contributed sinks.
+ */
+export interface TraceSinkFactoryContext {
+  /**
+   * Service resolver backing the shared {@link ProcessManagerRuntime}. Use it
+   * to resolve per-space (or per-process) services like `FeedTraceSink` when
+   * building a routing sink.
+   */
+  readonly resolver: ServiceResolver$.ServiceResolver;
+}
+
+/**
+ * Factory that builds a {@link Trace$.Sink} when the process-manager
+ * capability is ready. Plugins that only need a static sink can ignore the
+ * context (e.g. `() => myConsoleSink`); plugins that need per-space routing
+ * can use {@link TraceSinkFactoryContext.resolver} to look up services.
+ */
+export type TraceSinkFactory = (ctx: TraceSinkFactoryContext) => Trace$.Sink;
+
+/**
+ * Trace sink contribution.
+ *
+ * Plugins contribute {@link TraceSinkFactory} functions; the process-manager
+ * capability invokes each factory with the runtime's
+ * {@link ServiceResolver$.ServiceResolver}, collects the resulting
+ * {@link Trace$.Sink}s, merges them via {@link Trace$.mergeSinks}, and
+ * installs the merged sink as {@link Trace$.TraceSink} in the runtime layer
+ * so every process writes to every contributed sink.
+ *
+ * @category Capability
+ */
+export const TraceSink = Capability$.make<TraceSinkFactory>('org.dxos.app-framework.capability.trace-sink');
+
+/**
+ * Service resolver backing the shared {@link ProcessManagerRuntime}.
+ *
+ * Contributed by the process-manager capability module. Consumers can combine
+ * it with {@link ServiceResolver$.provide} to build space-scoped layers without
+ * having to go through the process-manager runtime:
+ *
+ * @example
+ * ```ts
+ * const resolver = yield* Capability.get(Capabilities.ServiceResolver);
+ * yield* effect.pipe(
+ *   Effect.provide(
+ *     ServiceResolver.provide({ space }, Database.Service, QueueService).pipe(
+ *       Layer.provide(Layer.succeed(ServiceResolver.ServiceResolver, resolver)),
+ *     ),
+ *   ),
+ * );
+ * ```
+ *
+ * @category Capability
+ */
+export const ServiceResolver = Capability$.make<ServiceResolver$.ServiceResolver>(
+  'org.dxos.app-framework.capability.service-resolver',
+);
+
+/**
+ * Process monitor backing the shared {@link ProcessManagerRuntime}. Exposes the
+ * live process tree (including inactive/terminated entries) via
+ * {@link Process$.Monitor#processTreeAtom}.
+ *
+ * @category Capability
+ */
+export const ProcessMonitor = Capability$.make<Process$.Monitor>('org.dxos.app-framework.capability.process-monitor');
+
+/**
+ * Services that are always available when running effects through a {@link ProcessManagerRuntime}.
+ */
+export type ProcessManagerRuntimeServices =
+  | Capability$.Service
+  | Plugin$.Service
+  | ProcessManager$.ProcessManagerService
+  | Operation$.Service
+  | ProcessManager$.ProcessOperationInvoker.Service
+  | ServiceResolver$.ServiceResolver;
+
+/**
+ * Runtime that runs effects requiring a fixed set of capability-manager and
+ * process-manager services.
+ *
+ * The shape mirrors {@link ManagedRuntime$.ManagedRuntime} but deliberately does
+ * not expose `dispose` – lifecycle is driven by the host plugin manager.
+ */
+export interface ProcessManagerRuntime {
+  runPromise<A, E>(
+    effect: Effect.Effect<A, E, ProcessManagerRuntimeServices>,
+    options?: { readonly signal?: AbortSignal },
+  ): Promise<A>;
+  runPromiseExit<A, E>(
+    effect: Effect.Effect<A, E, ProcessManagerRuntimeServices>,
+    options?: { readonly signal?: AbortSignal },
+  ): Promise<Exit$.Exit<A, E>>;
+  runFork<A, E>(
+    effect: Effect.Effect<A, E, ProcessManagerRuntimeServices>,
+    options?: Runtime$.RunForkOptions,
+  ): Fiber$.RuntimeFiber<A, E>;
+  runSync<A, E>(effect: Effect.Effect<A, E, ProcessManagerRuntimeServices>): A;
 }
+
+/**
+ * @category Capability
+ */
+export const ProcessManagerRuntime = Capability$.make<ProcessManagerRuntime>(
+  'org.dxos.app-framework.capability.process-manager-runtime',
+);
+
+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');
+
+/**
+ * Operation invoker backed by the process manager. Spawns a process per
+ * operation invocation; see {@link ProcessManager$.ProcessOperationInvoker}.
+ */
+export type OperationInvoker = OperationInvoker$.OperationInvoker;
+
+/**
+ * Operation invoker - provided by the process-manager capability.
+ * @category Capability
+ */
+export const OperationInvoker = Capability$.make<OperationInvoker>(
+  'org.dxos.app-framework.capability.operation-invoker',
+);
+
+export type UndoRegistry = UndoRegistry$.UndoRegistry;
+
+/**
+ * Undo registry - provided by ProcessManagerPlugin.
+ * @category Capability
+ */
+export const UndoRegistry = Capability$.make<UndoRegistry>('org.dxos.app-framework.capability.undo-registry');
+
+export type HistoryTracker = HistoryTracker$.HistoryTracker;
+
+/**
+ * History tracker - provided by ProcessManagerPlugin.
+ * @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]);