@dxos/app-framework 0.8.3-staging.0fa589b → 0.8.4-main.03d5cd7b56

package/src/plugin-operation/history/undo-registry.test.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { Compute, HalveCompute } from '../testing';
+import * as UndoMapping from './undo-mapping';
+import * as UndoRegistry from './undo-registry';
+
+describe('UndoRegistry', () => {
+  test('looks up undo mapping by operation key', ({ expect }) => {
+    const undoMapping = UndoMapping.make({
+      operation: Compute,
+      inverse: HalveCompute,
+      deriveContext: (_input, output) => ({ value: output.value }),
+    });
+    const registry = UndoRegistry.make(() => [undoMapping]);
+
+    const result = registry.lookup(Compute);
+    expect(result).not.toBe(undefined);
+    expect(result?.inverse.meta.key).toBe('test.halve-compute');
+  });
+
+  test('returns undefined for unmapped operations', ({ expect }) => {
+    const registry = UndoRegistry.make(() => []);
+
+    const result = registry.lookup(Compute);
+    expect(result).toBe(undefined);
+  });
+
+  test('deriveContext extracts correct undo input', ({ expect }) => {
+    const undoMapping = UndoMapping.make({
+      operation: Compute,
+      inverse: HalveCompute,
+      // Note: This tests that input and output types are inferred correctly.
+      deriveContext: (input, output) => ({ value: output.value + input.value }),
+    });
+    const registry = UndoRegistry.make(() => [undoMapping]);
+
+    const result = registry.lookup(Compute);
+    const context = result?.deriveContext({ value: 5 }, { value: 10 });
+    expect(context).toEqual({ value: 15 });
+  });
+});
+
+describe('resolveMessage', () => {
+  test('returns undefined for undefined message', ({ expect }) => {
+    const result = UndoMapping.resolveMessage(undefined, { value: 1 }, { value: 2 });
+    expect(result).toBe(undefined);
+  });
+
+  test('returns static label as-is', ({ expect }) => {
+    const staticMessage: [string, { ns: string }] = ['test.message', { ns: 'test' }];
+    const result = UndoMapping.resolveMessage(staticMessage, { value: 1 }, { value: 2 });
+    expect(result).toEqual(staticMessage);
+  });
+
+  test('calls function message with input and output', ({ expect }) => {
+    const messageFunc = (input: { value: number }, output: { value: number }): [string, { ns: string }] => [
+      `input-${input.value}-output-${output.value}`,
+      { ns: 'test' },
+    ];
+    const result = UndoMapping.resolveMessage(messageFunc, { value: 5 }, { value: 10 });
+    expect(result).toEqual(['input-5-output-10', { ns: 'test' }]);
+  });
+
+  test('returns string label as-is', ({ expect }) => {
+    const result = UndoMapping.resolveMessage('simple string', { value: 1 }, { value: 2 });
+    expect(result).toBe('simple string');
+  });
+});

package/src/plugin-operation/history/undo-registry.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Operation } from '@dxos/compute';
+
+import type * as UndoMapping from './undo-mapping';
+
+//
+// Public Interface
+//
+
+/**
+ * Lookup result from UndoRegistry.
+ */
+export type UndoMappingResult = {
+  inverse: Operation.Definition<any, any>;
+  /** Returns undefined to indicate the operation is not undoable. */
+  deriveContext: (input: any, output: any) => any | undefined;
+  /** Message provider - may be a static Label or a function. */
+  message?: UndoMapping.MessageProvider<Operation.Definition<any, any>>;
+};
+
+/**
+ * UndoRegistry interface - looks up inverse operations.
+ */
+export interface UndoRegistry {
+  lookup: (operation: Operation.Definition<any, any>) => UndoMappingResult | undefined;
+}
+
+//
+// Factory
+//
+
+/**
+ * Creates an UndoRegistry that looks up inverse operations.
+ */
+export const make = (getMappings: () => UndoMapping.UndoMapping[]): UndoRegistry => {
+  const lookup = (operation: Operation.Definition<any, any>): UndoMappingResult | undefined => {
+    const mappings = getMappings();
+    const mapping = mappings.find((m) => m.operation.meta.key === operation.meta.key);
+    if (!mapping) {
+      return undefined;
+    }
+
+    return {
+      inverse: mapping.inverse,
+      deriveContext: mapping.deriveContext,
+      message: mapping.message,
+    };
+  };
+
+  return { lookup };
+};

package/src/plugin-operation/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './history';
+export * from './OperationPlugin';

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

@@ -0,0 +1,55 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { OperationHandlerSet } from '@dxos/compute';
+import { OperationInvoker } from '@dxos/operation';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { Capability, Plugin } from '../core';
+
+//
+// Capability Module
+//
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    // Get the services for synchronous access in callbacks.
+    const capabilityManager = yield* Capability.Service;
+    const pluginManager = yield* Plugin.Service;
+
+    // Get the ManagedRuntime capability (should be available since we activate after ManagedRuntimeReady).
+    const managedRuntime = yield* Capability.get(Capabilities.ManagedRuntime);
+
+    // Cache the merged handler promise to prevent concurrent module loading.
+    // Multiple Effects can invoke getHandlers simultaneously; without caching each
+    // creates a new merge() which triggers parallel dynamic imports that race in
+    // WebKit's module evaluator, causing TDZ errors on export default bindings.
+    let cachedSets: readonly OperationHandlerSet.OperationHandlerSet[] | undefined;
+    let cachedHandlers: ReturnType<OperationHandlerSet.OperationHandlerSet['getHandlers']> | undefined;
+
+    const invoker = OperationInvoker.make(
+      () =>
+        Effect.gen(function* () {
+          yield* Plugin.activate(ActivationEvents.SetupOperationHandler);
+          const sets = yield* Capability.getAll(Capabilities.OperationHandler);
+
+          if (sets !== cachedSets) {
+            cachedSets = sets;
+            cachedHandlers = OperationHandlerSet.merge(...sets).getHandlers();
+          }
+
+          return yield* Effect.promise(() => cachedHandlers!);
+        }).pipe(
+          Effect.provideService(Capability.Service, capabilityManager),
+          Effect.provideService(Plugin.Service, pluginManager),
+          Effect.orDie,
+        ),
+      managedRuntime,
+    );
+
+    return Capability.contributes(Capabilities.OperationInvoker, invoker);
+  }),
+);

package/src/plugin-operation/meta.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Plugin } from '../core';
+
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.operation',
+  name: 'Operation Plugin',
+  description: 'Provides operation invocation, undo registry, and history tracking.',
+  tags: ['system'],
+};

package/src/plugin-operation/testing.ts

@@ -0,0 +1,155 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Ref from 'effect/Ref';
+import * as Schema from 'effect/Schema';
+import * as Stream from 'effect/Stream';
+
+import { Operation } from '@dxos/compute';
+import { OperationInvoker } from '@dxos/operation';
+
+//
+// Test Operations
+//
+
+export const Compute = Operation.make({
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
+  meta: { key: 'test.compute' },
+});
+
+export const HalveCompute = Operation.make({
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ value: Schema.Number }),
+  meta: { key: 'test.halve-compute' },
+});
+
+export const ToString = Operation.make({
+  input: Schema.Struct({ value: Schema.Number }),
+  output: Schema.Struct({ string: Schema.String }),
+  meta: { key: 'test.to-string' },
+});
+
+export const Add = Operation.make({
+  input: Schema.Tuple(Schema.Number, Schema.Number),
+  output: Schema.Number,
+  meta: { key: 'test.add' },
+});
+
+export const SideEffect = Operation.make({
+  input: Schema.Void,
+  output: Schema.Void,
+  meta: { key: 'test.side-effect' },
+});
+
+//
+// Test Handlers
+//
+
+export const computeHandler = Operation.withHandler(Compute, (data) =>
+  Effect.gen(function* () {
+    yield* Effect.sleep(data.value * 10);
+    return { value: data.value * 2 };
+  }),
+);
+
+export const halveComputeHandler = Operation.withHandler(HalveCompute, (data) =>
+  Effect.succeed({ value: data.value / 2 }),
+);
+
+export const toStringHandler = Operation.withHandler(ToString, (data) =>
+  Effect.succeed({ string: data.value.toString() }),
+);
+
+export const addHandler = Operation.withHandler(Add, (data) => Effect.succeed(data[0] + data[1]));
+
+export const sideEffectHandler = Operation.withHandler(SideEffect, () => Effect.succeed(undefined));
+
+//
+// Test Utilities
+//
+
+/**
+ * Event collector for testing - provides deterministic event collection using Effect primitives.
+ */
+export interface EventCollector {
+  /** All collected events. */
+  readonly events: OperationInvoker.InvocationEvent[];
+  /** Wait until N events have been collected. */
+  waitForEvents: (count: number) => Effect.Effect<void>;
+  /** Clean up the subscription fiber. */
+  dispose: Effect.Effect<void>;
+}
+
+/**
+ * Creates an event collector that subscribes to invoker events.
+ * Uses Effect primitives for synchronization.
+ */
+export const createEventCollector = (invoker: OperationInvoker.OperationInvoker): Effect.Effect<EventCollector> =>
+  Effect.gen(function* () {
+    const events: OperationInvoker.InvocationEvent[] = [];
+
+    // Ref to track current waiter (waiting for N events).
+    const waiterRef = yield* Ref.make<{ count: number; deferred: Deferred.Deferred<void> } | null>(null);
+
+    // Deferred to signal when subscription is ready.
+    const subscriptionReady = yield* Deferred.make<void>();
+
+    const checkWaiter = Effect.gen(function* () {
+      const waiter = yield* Ref.get(waiterRef);
+      if (waiter && events.length >= waiter.count) {
+        yield* Deferred.succeed(waiter.deferred, undefined);
+        yield* Ref.set(waiterRef, null);
+      }
+    });
+
+    // Fork a fiber to consume the invocation stream.
+    const fiber = yield* Effect.fork(
+      Effect.gen(function* () {
+        // Signal that subscription is about to start.
+        yield* Deferred.succeed(subscriptionReady, undefined);
+        yield* Stream.fromPubSub(invoker.invocations).pipe(
+          Stream.runForEach((event) =>
+            Effect.gen(function* () {
+              events.push(event);
+              yield* checkWaiter;
+            }),
+          ),
+        );
+      }),
+    );
+
+    // Wait for the subscription to be established.
+    yield* Deferred.await(subscriptionReady);
+    // Additional yield to ensure PubSub subscription is fully registered.
+    yield* Effect.yieldNow();
+
+    const waitForEvents = (count: number): Effect.Effect<void> =>
+      Effect.gen(function* () {
+        if (events.length >= count) {
+          return;
+        }
+        const deferred = yield* Deferred.make<void>();
+        yield* Ref.set(waiterRef, { count, deferred });
+        yield* Deferred.await(deferred);
+      });
+
+    const dispose = Fiber.interrupt(fiber);
+
+    return { events, waitForEvents, dispose };
+  });
+
+/**
+ * Waits until a condition is true, yielding to the JS event loop between checks.
+ * Uses setImmediate to allow other async work to complete.
+ */
+export const waitUntil = (condition: () => boolean): Effect.Effect<void> =>
+  Effect.gen(function* () {
+    while (!condition()) {
+      yield* Effect.promise(() => new Promise((r) => setImmediate(r)));
+    }
+  });

package/src/plugin-runtime/RuntimePlugin.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { ActivationEvents } from '../common';
+import { Capability, Plugin } from '../core';
+import { meta } from './meta';
+
+const ManagedRuntimeCapability = Capability.lazy('ManagedRuntime', () => import('./capability'));
+
+export const RuntimePlugin = Plugin.define(meta).pipe(
+  Plugin.addModule({
+    activatesOn: ActivationEvents.Startup,
+    firesBeforeActivation: [ActivationEvents.SetupLayer],
+    firesAfterActivation: [ActivationEvents.ManagedRuntimeReady],
+    activate: ManagedRuntimeCapability,
+  }),
+  Plugin.make,
+);

package/src/plugin-runtime/capability.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { Capability, Plugin } from '../core';
+
+//
+// Capability Module
+//
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    // Get the CapabilityManager to create a layer for it.
+    const capabilityManager = yield* Capability.Service;
+
+    // Get the PluginManager to create a layer for it.
+    const pluginManager = yield* Plugin.Service;
+
+    // Trigger setup event so plugins can contribute their layers.
+    yield* Plugin.activate(ActivationEvents.SetupLayer);
+
+    // Gather all contributed layers.
+    const layers = yield* Capability.getAll(Capabilities.Layer);
+
+    // Create layers that provide Capability.Service and Plugin.Service.
+    const capabilityServiceLayer = Layer.succeed(Capability.Service, capabilityManager);
+    const pluginServiceLayer = Layer.succeed(Plugin.Service, pluginManager);
+
+    // Merge all layers including service layers.
+    // Layer.mergeAll requires a tuple type, so we use a cast for dynamic arrays.
+    const composedLayer =
+      layers.length > 0
+        ? (Layer.mergeAll as (...args: Layer.Layer<any, any, any>[]) => Layer.Layer<any, any, never>)(
+            capabilityServiceLayer,
+            pluginServiceLayer,
+            ...layers,
+          )
+        : (Layer.mergeAll as (...args: Layer.Layer<any, any, any>[]) => Layer.Layer<any, any, never>)(
+            capabilityServiceLayer,
+            pluginServiceLayer,
+          );
+
+    // Create the managed runtime from the composed layer.
+    const runtime = ManagedRuntime.make(composedLayer) as Capabilities.ManagedRuntime;
+
+    return Capability.contributes(Capabilities.ManagedRuntime, runtime);
+  }),
+);

package/src/plugin-runtime/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './RuntimePlugin';

package/src/plugin-runtime/meta.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Plugin } from '../core';
+
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.runtime',
+  name: 'Runtime Plugin',
+  description: 'Provides a managed Effect runtime by composing contributed layers.',
+  tags: ['system'],
+};

package/src/testing/harness.ts

@@ -0,0 +1,229 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Registry } from '@effect-atom/atom-react';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as PubSub from 'effect/PubSub';
+import * as Queue from 'effect/Queue';
+
+import { type Operation } from '@dxos/compute';
+import { runAndForwardErrors } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+
+import { ActivationEvents, Capabilities } from '../common';
+import { ActivationEvent, type Capability, type CapabilityManager, type Plugin, PluginManager } from '../core';
+
+export type TestAppOptions = {
+  /** Plugins to register. */
+  plugins: Plugin.Plugin[];
+  /** Plugin ids that are always enabled. Defaults to all provided plugin ids. */
+  core?: string[];
+  /** Plugin ids that are enabled by default in addition to core. */
+  enabled?: string[];
+  /** Additional activation events fired alongside SetupReactSurface. */
+  setupEvents?: ActivationEvent.ActivationEvent[];
+  /**
+   * Whether to automatically fire SetupReactSurface + Startup during setup.
+   * Defaults to true.
+   */
+  autoStart?: boolean;
+  /**
+   * Whether to register the PluginManager + AtomRegistry framework capabilities.
+   * Defaults to true.
+   */
+  registerFrameworkCapabilities?: boolean;
+};
+
+/**
+ * A running plugin manager plus helpers for driving it in tests.
+ */
+export interface TestHarness {
+  readonly manager: PluginManager.PluginManager;
+  readonly capabilities: CapabilityManager.CapabilityManager;
+  readonly registry: Registry.Registry;
+
+  /** Activate the given event. Equivalent to `manager.activate(event)`. */
+  fire(event: ActivationEvent.ActivationEvent | string): Promise<boolean>;
+  /** Re-activate all modules that were activated by the given event. */
+  reset(event: ActivationEvent.ActivationEvent | string): Promise<boolean>;
+
+  /** Returns the first contributed capability for the given interface. Throws if none are present. */
+  get<T>(iface: Capability.InterfaceDef<T>): T;
+  /** Returns all contributed capabilities for the given interface. */
+  getAll<T>(iface: Capability.InterfaceDef<T>): T[];
+  /** Waits until at least one capability is contributed for the given interface. */
+  waitForCapability<T>(iface: Capability.InterfaceDef<T>, opts?: { timeout?: number }): Promise<T>;
+  /** Waits until the given activation event has completed. */
+  waitForEvent(event: ActivationEvent.ActivationEvent | string, opts?: { timeout?: number }): Promise<void>;
+
+  /** Invokes an operation through the `Capabilities.OperationInvoker` capability. */
+  invoke<I, O>(op: Operation.Definition<I, O>, ...args: void extends I ? [input?: I] : [input: I]): Promise<O>;
+
+  enable(id: string): Promise<boolean>;
+  disable(id: string): Promise<boolean>;
+
+  /** Shuts down the underlying plugin manager. */
+  dispose(): Promise<void>;
+
+  /** Async-disposable support so tests can use `await using harness = ...`. */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+/**
+ * Creates a TestHarness with the same bootstrap sequence that `useApp` performs,
+ * minus the React provider tree.
+ *
+ * For Node-only tests, this is enough to fire activation events, read
+ * capabilities, and invoke operations.
+ *
+ * For React tests, pass the returned harness to `render` or `renderSurface`
+ * from `@dxos/app-framework/testing-react`.
+ */
+export const createTestApp = async (opts: TestAppOptions): Promise<TestHarness> => {
+  const {
+    plugins,
+    core = plugins.map((plugin) => plugin.meta.id),
+    enabled,
+    setupEvents = [],
+    autoStart = true,
+    registerFrameworkCapabilities = true,
+  } = opts;
+
+  const pluginLoader = (id: string) =>
+    Effect.sync(() => {
+      const plugin = plugins.find((plugin) => plugin.meta.id === id);
+      invariant(plugin, `Plugin not found: ${id}`);
+      return { plugin };
+    });
+
+  const manager = PluginManager.make({ pluginLoader, plugins, core, enabled });
+
+  if (registerFrameworkCapabilities) {
+    manager.capabilities.contribute({
+      interface: Capabilities.PluginManager,
+      implementation: manager,
+      module: 'org.dxos.app-framework.plugin-manager',
+    });
+    manager.capabilities.contribute({
+      interface: Capabilities.AtomRegistry,
+      implementation: manager.registry,
+      module: 'org.dxos.app-framework.atom-registry',
+    });
+  }
+
+  if (autoStart) {
+    try {
+      await runAndForwardErrors(
+        Effect.all([
+          ...setupEvents.map((event) => manager.activate(event)),
+          manager.activate(ActivationEvents.SetupReactSurface),
+          manager.activate(ActivationEvents.Startup),
+        ]),
+      );
+    } catch (err) {
+      await runAndForwardErrors(manager.shutdown()).catch(() => undefined);
+      throw err;
+    }
+  }
+
+  return new TestHarnessImpl(manager);
+};
+
+class TestHarnessImpl implements TestHarness {
+  constructor(readonly manager: PluginManager.PluginManager) {}
+
+  get capabilities(): CapabilityManager.CapabilityManager {
+    return this.manager.capabilities;
+  }
+
+  get registry(): Registry.Registry {
+    return this.manager.registry;
+  }
+
+  fire(event: ActivationEvent.ActivationEvent | string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.activate(event));
+  }
+
+  reset(event: ActivationEvent.ActivationEvent | string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.reset(event));
+  }
+
+  get<T>(iface: Capability.InterfaceDef<T>): T {
+    return this.manager.capabilities.get(iface);
+  }
+
+  getAll<T>(iface: Capability.InterfaceDef<T>): T[] {
+    return this.manager.capabilities.getAll(iface);
+  }
+
+  waitForCapability<T>(iface: Capability.InterfaceDef<T>, opts?: { timeout?: number }): Promise<T> {
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+    return runAndForwardErrors(
+      this.manager.capabilities.waitFor(iface).pipe(
+        Effect.timeoutFail({
+          duration: Duration.millis(timeout),
+          onTimeout: () => timeoutError(iface.identifier),
+        }),
+      ),
+    );
+  }
+
+  waitForEvent(event: ActivationEvent.ActivationEvent | string, opts?: { timeout?: number }): Promise<void> {
+    const key = typeof event === 'string' ? event : ActivationEvent.eventKey(event);
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+
+    const program = Effect.gen(this, function* () {
+      const queue = yield* PubSub.subscribe(this.manager.activation);
+      // Re-check after subscribing to avoid a race where the event fires
+      // between the caller invoking this and the subscription being installed.
+      if (this.manager.getEventsFired().includes(key)) {
+        return;
+      }
+      while (true) {
+        const message = yield* Queue.take(queue);
+        if (message.event === key && message.state === 'activated') {
+          return;
+        }
+      }
+    }).pipe(
+      Effect.scoped,
+      Effect.timeoutFail({
+        duration: Duration.millis(timeout),
+        onTimeout: () => timeoutError(key),
+      }),
+    );
+
+    return runAndForwardErrors(program);
+  }
+
+  async invoke<I, O>(op: Operation.Definition<I, O>, ...args: [input?: I]): Promise<O> {
+    const invoker = await this.waitForCapability(Capabilities.OperationInvoker);
+    const result = await invoker.invokePromise(op as any, ...(args as [any]));
+    if (result.error) {
+      throw result.error;
+    }
+    return result.data as O;
+  }
+
+  enable(id: string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.enable(id));
+  }
+
+  disable(id: string): Promise<boolean> {
+    return runAndForwardErrors(this.manager.disable(id));
+  }
+
+  async dispose(): Promise<void> {
+    await runAndForwardErrors(this.manager.shutdown());
+  }
+
+  [Symbol.asyncDispose](): Promise<void> {
+    return this.dispose();
+  }
+}
+
+const timeoutError = (id: string) => new Error(`Timed out waiting for ${id}`);

package/src/testing/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './harness';
+export * from './service';
 export * from './withPluginManager';