@dxos/app-framework 0.8.4-main.72ec0f3 → 0.8.4-main.74a063c4e0

package/src/core/plugin.ts

@@ -2,12 +2,82 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type MaybePromise } from '@dxos/util';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Pipeable from 'effect/Pipeable';
 
-import { type AnyCapability, type PluginContext } from './capabilities';
-import { type ActivationEvent, type ActivationEvents } from './events';
+import { invariant } from '@dxos/invariant';
 
-interface PluginModuleInterface {
+import type * as ActivationEvent from './activation-event';
+import * as Capability from './capability';
+import type * as PluginManager from './plugin-manager';
+
+//
+// Plugin Service Layer
+//
+
+/**
+ * Effect Context.Tag for accessing PluginManager via the Effect layer system.
+ * This allows lifecycle operations to access the plugin manager without having it passed as an argument.
+ */
+export class Service extends Context.Tag('@dxos/app-framework/PluginManager')<Service, PluginManager.PluginManager>() {}
+
+//
+// Lifecycle Functions
+//
+
+/**
+ * Activates plugins based on the activation event.
+ * Accesses the PluginManager via the Effect layer system.
+ * @param event The activation event.
+ * @returns Whether the activation was successful.
+ */
+export const activate = (event: ActivationEvent.ActivationEvent): Effect.Effect<boolean, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.activate(event));
+
+/**
+ * Re-activates the modules that were activated by the event.
+ * Accesses the PluginManager via the Effect layer system.
+ * @param event The activation event.
+ * @returns Whether the reset was successful.
+ */
+export const reset = (event: ActivationEvent.ActivationEvent): Effect.Effect<boolean, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.reset(event));
+
+/**
+ * Shuts down the plugin manager, deactivating all active modules and clearing lifecycle state.
+ * Accesses the PluginManager via the Effect layer system.
+ */
+export const shutdown = (): Effect.Effect<boolean, Error, Service> =>
+  Effect.flatMap(Service, (manager) => manager.shutdown());
+
+/**
+ * Computes a module ID from plugin ID and export name.
+ */
+const computeModuleId = (pluginId: string, moduleName: string): string => {
+  return `${pluginId}.module.${moduleName}`;
+};
+
+/**
+ * Identifier denoting a PluginModule.
+ */
+export const PluginModuleTypeId: unique symbol = Symbol.for('@dxos/app-framework/PluginModule');
+export type PluginModuleTypeId = typeof PluginModuleTypeId;
+
+/**
+ * Type guard to check if a value is a PluginModule.
+ */
+export const isPluginModule = (value: unknown): value is PluginModule => {
+  return typeof value === 'object' && value !== null && PluginModuleTypeId in value;
+};
+
+/**
+ * A unit of containment of modular functionality that can be provided to an application.
+ * Activation of a module is async allowing for code to split and loaded lazily.
+ */
+export interface PluginModule {
+  readonly [PluginModuleTypeId]: PluginModuleTypeId;
   /**
    * Unique id of the module.
    */
@@ -16,43 +86,41 @@ interface PluginModuleInterface {
   /**
    * Events for which the module will be activated.
    */
-  activatesOn: ActivationEvents;
+  activatesOn: ActivationEvent.Events;
 
   /**
    * Events which the plugin depends on being activated.
    * Plugin is marked as needing reset a plugin activated by a dependent event is removed.
    * Events are automatically activated before activation of the plugin.
    */
-  activatesBefore?: ActivationEvent[];
+  activatesBefore?: ActivationEvent.ActivationEvent[];
 
   /**
    * Events which this plugin triggers upon activation.
    */
-  activatesAfter?: ActivationEvent[];
+  activatesAfter?: ActivationEvent.ActivationEvent[];
 
   /**
    * Called when the module is activated.
-   * @param context The plugin context.
+   * CapabilityManager is accessed via the Effect layer system (Capability.Service).
+   * PluginManager is accessed via Plugin.Service.
+   * @param props Optional props passed to the module.
    * @returns The capabilities of the module.
    */
-  activate: (
-    context: PluginContext,
-  ) => MaybePromise<AnyCapability | AnyCapability[]> | Promise<() => Promise<AnyCapability | AnyCapability[]>>;
+  activate: (props?: any) => Effect.Effect<Capability.ModuleReturn, Error, Capability.Service | Service | never>;
 }
 
-/**
- * A unit of containment of modular functionality that can be provided to an application.
- * Activation of a module is async allowing for code to split and loaded lazily.
- */
-// NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
-export class PluginModule implements PluginModuleInterface {
-  readonly id: PluginModuleInterface['id'];
-  readonly activatesOn: PluginModuleInterface['activatesOn'];
-  readonly activatesBefore?: PluginModuleInterface['activatesBefore'];
-  readonly activatesAfter?: PluginModuleInterface['activatesAfter'];
-  readonly activate: PluginModuleInterface['activate'];
+export type PluginModuleOptions = Omit<PluginModule, 'id' | typeof PluginModuleTypeId> & { id?: string };
+
+class PluginModuleImpl implements PluginModule {
+  readonly [PluginModuleTypeId]: PluginModuleTypeId = PluginModuleTypeId;
+  readonly id: PluginModule['id'];
+  readonly activatesOn: PluginModule['activatesOn'];
+  readonly activatesBefore?: PluginModule['activatesBefore'];
+  readonly activatesAfter?: PluginModule['activatesAfter'];
+  readonly activate: PluginModule['activate'];
 
-  constructor(options: PluginModuleInterface) {
+  constructor(options: Omit<PluginModule, typeof PluginModuleTypeId>) {
     this.id = options.id;
     this.activatesOn = options.activatesOn;
     this.activatesBefore = options.activatesBefore;
@@ -61,18 +129,13 @@ export class PluginModule implements PluginModuleInterface {
   }
 }
 
-/**
- * Helper to define a module.
- */
-export const defineModule = (options: PluginModuleInterface) => new PluginModule(options);
-
-export type PluginMeta = {
+export type Meta = {
   /**
    * Globally unique ID.
    *
    * Expected to be in the form of a valid URL.
    *
-   * @example dxos.org/plugin/example
+   * @example org.dxos.plugin.example
    */
   id: string;
 
@@ -117,27 +180,154 @@ export type PluginMeta = {
   iconHue?: string;
 };
 
+/**
+ * Identifier denoting a Plugin.
+ */
+export const PluginTypeId: unique symbol = Symbol.for('@dxos/app-framework/Plugin');
+export type PluginTypeId = typeof PluginTypeId;
+
+/**
+ * Type guard to check if a value is a Plugin.
+ */
+export const isPlugin = (value: unknown): value is Plugin => {
+  return typeof value === 'object' && value !== null && PluginTypeId in value;
+};
+
 /**
  * A collection of modules that are be enabled/disabled as a unit.
  * Plugins provide things such as components, state, actions, etc. to the application.
  */
-// NOTE: This is implemented as a class to prevent it from being proxied by PluginManager state.
-export class Plugin {
+// TODO(burdon): Convert to ECHO schema.
+export interface Plugin {
+  readonly [PluginTypeId]: PluginTypeId;
+  readonly meta: Readonly<Meta>;
+  readonly modules: ReadonlyArray<PluginModule>;
+}
+
+/**
+ * Internal implementation of Plugin.
+ * @internal
+ */
+class PluginImpl implements Plugin {
+  readonly [PluginTypeId]: PluginTypeId = PluginTypeId;
+
   constructor(
-    readonly meta: PluginMeta,
-    readonly modules: PluginModule[],
+    private readonly _meta: Meta,
+    private readonly _modules: PluginModule[],
   ) {}
+
+  get meta(): Readonly<Meta> {
+    return this._meta;
+  }
+
+  get modules(): ReadonlyArray<PluginModule> {
+    return this._modules;
+  }
+}
+
+/**
+ * Builder interface for creating plugins incrementally.
+ */
+export interface PluginBuilder<T = void> extends Pipeable.Pipeable {
+  readonly meta: Meta;
+  readonly modules: ReadonlyArray<PluginModuleOptions | ((options: T) => PluginModuleOptions)>;
+  addModule(moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions)): PluginBuilder<T>;
+}
+
+/**
+ * Builder implementation for creating plugins incrementally.
+ */
+class PluginBuilderImpl<T = void> implements PluginBuilder<T> {
+  readonly meta: Meta;
+  private readonly _modules: Array<PluginModuleOptions | ((options: T) => PluginModuleOptions)> = [];
+
+  constructor(meta: Meta) {
+    this.meta = meta;
+  }
+
+  get modules(): ReadonlyArray<PluginModuleOptions | ((options: T) => PluginModuleOptions)> {
+    return this._modules;
+  }
+
+  addModule(moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions)): PluginBuilder<T> {
+    this._modules.push(moduleOptions);
+    return this;
+  }
+
+  pipe() {
+    // eslint-disable-next-line prefer-rest-params
+    return Pipeable.pipeArguments(this, arguments);
+  }
+}
+
+/**
+ * Creates a new PluginBuilder to start building a plugin.
+ */
+export const define = <T = void>(meta: Meta): PluginBuilder<T> => new PluginBuilderImpl<T>(meta);
+
+/**
+ * Adds a module to a plugin builder.
+ * Supports both pipeline and direct call styles.
+ * Modules can be either PluginModuleOptions or functions that receive options.
+ */
+export function addModule<T>(
+  moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions),
+): (builder: PluginBuilder<T>) => PluginBuilder<T>;
+export function addModule<T>(
+  builder: PluginBuilder<T>,
+  moduleOptions: PluginModuleOptions | ((options: T) => PluginModuleOptions),
+): PluginBuilder<T>;
+export function addModule<T>(
+  moduleOptionsOrBuilder: PluginModuleOptions | ((options: T) => PluginModuleOptions) | PluginBuilder<T>,
+  moduleOptions?: PluginModuleOptions | ((options: T) => PluginModuleOptions),
+): ((builder: PluginBuilder<T>) => PluginBuilder<T>) | PluginBuilder<T> {
+  // If second arg is provided, it's the direct call style: addModule(builder, moduleOptions)
+  if (moduleOptions !== undefined) {
+    return (moduleOptionsOrBuilder as PluginBuilder<T>).addModule(moduleOptions);
+  }
+  // Otherwise it's pipeline style: addModule(moduleOptions) returns a function
+  const moduleOpts = moduleOptionsOrBuilder as PluginModuleOptions | ((options: T) => PluginModuleOptions);
+  return (builder: PluginBuilder<T>) => builder.addModule(moduleOpts);
 }
 
-export type PluginFactory<T = void> = ((args: T) => Plugin) & { meta: PluginMeta };
+export type PluginFactory<T = void> = ((options: T) => Plugin) & { meta: Meta };
 
 /**
- * Helper to define a plugin.
+ * Resolves a module from either PluginModuleOptions or a function that returns PluginModuleOptions.
  */
-export const definePlugin = <T = void>(meta: PluginMeta, provider: (args: T) => PluginModule[]): PluginFactory<T> => {
-  const factory = (args: T) => {
-    return new Plugin(meta, provider(args));
+const resolveModule = (
+  meta: Meta,
+  module: PluginModuleOptions | ((options: any) => PluginModuleOptions),
+  options?: any,
+): PluginModuleImpl => {
+  const moduleOptions = typeof module === 'function' ? module(options) : module;
+  const id = Option.fromNullable(moduleOptions.id).pipe(
+    Option.match({
+      onNone: () => {
+        const exportName = Capability.getModuleTag(moduleOptions.activate);
+        invariant(exportName, `Plugin module missing name. Plugin: ${meta.id}`);
+        return computeModuleId(meta.id, exportName);
+      },
+      onSome: (id) => computeModuleId(meta.id, id),
+    }),
+  );
+  return new PluginModuleImpl({ ...moduleOptions, id });
+};
+
+/**
+ * Creates a Plugin from a builder.
+ * Supports both pipeline and direct call styles.
+ * Always returns a factory function (options: T) => Plugin.
+ * When T is void, the function takes no arguments: () => Plugin.
+ */
+export function make<T>(builder: PluginBuilder<T>): PluginFactory<T>;
+export function make<T>(builder: PluginBuilder<T>): PluginFactory<T> {
+  const meta = builder.meta;
+
+  const factory = (options: T) => {
+    const modules = builder.modules.map((module) => resolveModule(meta, module, options));
+    return new PluginImpl(meta, modules);
   };
 
   return Object.assign(factory, { meta });
-};
+}

package/src/core/url-loader.test.ts

@@ -0,0 +1,79 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { assert, describe, it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+
+import * as Plugin from './plugin';
+import * as UrlLoader from './url-loader';
+
+const testMeta = { id: 'org.dxos.plugin.test', name: 'Test' };
+
+describe('UrlLoader', () => {
+  describe('make', () => {
+    it.effect('resolves built-in plugins by meta.id', () =>
+      Effect.gen(function* () {
+        const testPlugin = Plugin.make(Plugin.define(testMeta))();
+        const loader = UrlLoader.make([testPlugin]);
+        const result = yield* loader(testMeta.id);
+        assert.strictEqual(result.meta.id, testMeta.id);
+      }),
+    );
+
+    it.effect('fails for unknown non-URL locator', () =>
+      Effect.gen(function* () {
+        const loader = UrlLoader.make([]);
+        const exit = yield* Effect.exit(loader('not-a-url'));
+        assert.isTrue(exit._tag === 'Failure');
+      }),
+    );
+  });
+
+  describe('preload', () => {
+    it('returns empty array when storage has no entries', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => null,
+        set: () => {},
+      };
+      const result = await UrlLoader.preload({ storage });
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage has invalid JSON', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '{{invalid json',
+        set: () => {},
+      };
+      const result = await UrlLoader.preload({ storage });
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage contains null', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => 'null',
+        set: () => {},
+      };
+      const result = await UrlLoader.preload({ storage });
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when storage contains an object', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '{}',
+        set: () => {},
+      };
+      const result = await UrlLoader.preload({ storage });
+      expect(result).toEqual([]);
+    });
+
+    it('returns empty array when entries are missing required fields', async ({ expect }) => {
+      const storage: UrlLoader.Storage = {
+        get: () => '[{"title":"no url"}]',
+        set: () => {},
+      };
+      const result = await UrlLoader.preload({ storage });
+      expect(result).toEqual([]);
+    });
+  });
+});

package/src/core/url-loader.ts

@@ -0,0 +1,148 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { log } from '@dxos/log';
+
+import * as Plugin from './plugin';
+
+const DEFAULT_KEY = 'org.dxos.composer.remote-plugins';
+
+/**
+ * Abstraction over key-value storage (defaults to localStorage).
+ */
+export type Storage = {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+};
+
+/**
+ * Options for configuring the URL loader.
+ */
+export type Options = {
+  storage?: Storage;
+  key?: string;
+};
+
+type RemotePluginEntry = { id: string; url: string };
+
+const defaultStorage = (): Storage => ({
+  get: (key) => localStorage.getItem(key),
+  set: (key, value) => localStorage.setItem(key, value),
+});
+
+const getPersistedRemotePlugins = (storage: Storage, key: string): RemotePluginEntry[] => {
+  try {
+    const parsed: unknown = JSON.parse(storage.get(key) ?? '[]');
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(
+      (entry): entry is RemotePluginEntry =>
+        typeof entry === 'object' && entry !== null && typeof entry.id === 'string' && typeof entry.url === 'string',
+    );
+  } catch {
+    return [];
+  }
+};
+
+const persistRemotePlugin = (storage: Storage, key: string, entry: RemotePluginEntry): void => {
+  try {
+    const entries = getPersistedRemotePlugins(storage, key).filter((existing) => existing.id !== entry.id);
+    entries.push(entry);
+    storage.set(key, JSON.stringify(entries));
+  } catch (error) {
+    log.warn('failed to persist remote plugin entry', { entry, error });
+  }
+};
+
+const isUrl = (locator: string): boolean => {
+  try {
+    const url = new URL(locator);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+};
+
+const normalizePluginExport = (mod: Record<string, unknown>): Plugin.Plugin => {
+  const exported = mod.default;
+  if (Plugin.isPlugin(exported)) {
+    return exported;
+  }
+  if (typeof exported === 'function') {
+    const result = (exported as () => unknown)();
+    if (Plugin.isPlugin(result)) {
+      return result;
+    }
+  }
+  throw new Error('Remote module default export is not a Plugin or a zero-arg plugin factory.');
+};
+
+const loadRemotePlugin = async (url: string): Promise<Plugin.Plugin> => {
+  log.info('loading remote plugin', { url });
+  const mod = await import(/* @vite-ignore */ url);
+  const plugin = normalizePluginExport(mod);
+  if (!plugin.meta.id || !plugin.meta.name) {
+    throw new Error(`Remote plugin at ${url} is missing required meta.id or meta.name.`);
+  }
+  return plugin;
+};
+
+/**
+ * Preloads previously persisted remote plugins from storage.
+ */
+export const preload = async (options: Options = {}): Promise<Plugin.Plugin[]> => {
+  const storage = options.storage ?? defaultStorage();
+  const key = options.key ?? DEFAULT_KEY;
+
+  const entries = getPersistedRemotePlugins(storage, key);
+  if (entries.length === 0) {
+    return [];
+  }
+  log.info('preloading remote plugins', { count: entries.length });
+  const results = await Promise.allSettled(entries.map((entry) => loadRemotePlugin(entry.url)));
+  const plugins: Plugin.Plugin[] = [];
+  for (let index = 0; index < results.length; index++) {
+    const result = results[index];
+    if (result.status === 'fulfilled') {
+      plugins.push(result.value);
+    } else {
+      log.warn('failed to preload remote plugin', { entry: entries[index], error: result.reason });
+    }
+  }
+  return plugins;
+};
+
+/**
+ * Creates a plugin loader that resolves built-in plugins by ID or loads remote plugins from URLs.
+ */
+export const make = (builtinPlugins: Plugin.Plugin[], options: Options = {}) => {
+  const storage = options.storage ?? defaultStorage();
+  const key = options.key ?? DEFAULT_KEY;
+
+  return (locator: string): Effect.Effect<Plugin.Plugin, Error> =>
+    Effect.gen(function* () {
+      const builtin = builtinPlugins.find((plugin) => plugin.meta.id === locator);
+      if (builtin) {
+        return builtin;
+      }
+      if (!isUrl(locator)) {
+        return yield* Effect.fail(new Error(`Plugin not found and locator is not a URL: ${locator}`));
+      }
+      const plugin = yield* Effect.tryPromise({
+        try: () => loadRemotePlugin(locator),
+        catch: (error) => new Error(`Failed to load remote plugin from ${locator}: ${error}`),
+      });
+      const duplicate = builtinPlugins.find((existing) => existing.meta.id === plugin.meta.id);
+      if (duplicate) {
+        return yield* Effect.fail(
+          new Error(`Remote plugin ${plugin.meta.id} conflicts with built-in plugin of the same id.`),
+        );
+      }
+      persistRemotePlugin(storage, key, { id: plugin.meta.id, url: locator });
+      return plugin;
+    });
+};

package/src/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './common';
+export * from './context';
 export * from './core';
-export * from './plugin-intent';
-export * from './plugin-settings';
+export * from './plugin-operation';
+export * from './plugin-runtime';

package/src/plugin-operation/OperationPlugin.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ActivationEvents } from '../common';
+import { Capability, Plugin } from '../core';
+import { meta } from './meta';
+
+const OperationInvoker = Capability.lazy('OperationInvoker', () => import('./invoker-capability'));
+const HistoryCapabilities = Capability.lazy('HistoryCapabilities', () => import('./history/capability'));
+
+export const OperationPlugin = Plugin.define(meta).pipe(
+  Plugin.addModule({
+    activatesOn: ActivationEvents.ManagedRuntimeReady,
+    activatesBefore: [ActivationEvents.SetupOperationHandler],
+    activatesAfter: [ActivationEvents.OperationInvokerReady],
+    activate: OperationInvoker,
+  }),
+  Plugin.addModule({
+    activatesOn: ActivationEvents.OperationInvokerReady,
+    activate: HistoryCapabilities,
+  }),
+  Plugin.make,
+);

package/src/plugin-operation/history/capability.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { type OperationInvoker } from '@dxos/operation';
+
+import { Capabilities } from '../../common';
+import { Capability } from '../../core';
+import * as HistoryTracker from './history-tracker';
+import * as UndoRegistry from './undo-registry';
+
+//
+// Capability Module - contributes both UndoRegistry and HistoryTracker.
+//
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    // Get the context for synchronous access in callbacks.
+    const capabilities = yield* Capability.Service;
+
+    // Create UndoRegistry.
+    const undoRegistry = UndoRegistry.make(() => capabilities.getAll(Capabilities.UndoMapping).flat());
+
+    // Create HistoryTracker (depends on UndoRegistry and OperationInvoker).
+    const invoker = yield* Capability.get(Capabilities.OperationInvoker);
+    // Cast to internal type - the factory always returns OperationInvokerInternal.
+    const historyTracker = HistoryTracker.make(invoker as OperationInvoker.OperationInvokerInternal, undoRegistry);
+
+    return [
+      Capability.contributes(Capabilities.UndoRegistry, undoRegistry),
+      Capability.contributes(Capabilities.HistoryTracker, historyTracker),
+    ];
+  }),
+);

package/src/plugin-operation/history/errors.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { BaseError } from '@dxos/errors';
+
+export class EmptyHistoryError extends BaseError.extend('EmptyHistoryError', 'Cannot undo: history is empty.') {}