@dxos/app-framework 0.8.4-main.f5c0578 → 0.8.4-main.fcfe5033a5

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.') {}

package/src/plugin-operation/history/history-tracker.test.ts

@@ -0,0 +1,373 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { it } from '@effect/vitest';
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Layer from 'effect/Layer';
+import * as ManagedRuntime from 'effect/ManagedRuntime';
+import * as TestClock from 'effect/TestClock';
+import { describe, expect } from 'vitest';
+
+import { Operation, OperationInvoker } from '@dxos/operation';
+
+const testRuntime = ManagedRuntime.make(Layer.empty) as unknown as ManagedRuntime.ManagedRuntime<any, any>;
+
+import { UndoOperation } from '../../common';
+import {
+  Compute,
+  HalveCompute,
+  ToString,
+  computeHandler,
+  createEventCollector,
+  halveComputeHandler,
+  toStringHandler,
+  waitUntil,
+} from '../testing';
+import * as HistoryTracker from './history-tracker';
+import * as UndoMapping from './undo-mapping';
+import * as UndoRegistry from './undo-registry';
+
+describe('HistoryTracker', () => {
+  it.effect('tracks undoable operations', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Fork compute operation and advance clock.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      expect(tracker.canUndo()).toBe(true);
+    }),
+  );
+
+  it.effect('does not track operations without undo mapping', () =>
+    Effect.gen(function* () {
+      const invoker = OperationInvoker.make(() => Effect.succeed([toStringHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => []);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      yield* invoker.invoke(ToString, { value: 42 });
+
+      // Wait for event to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Without an undo mapping, canUndo should remain false.
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('undo invokes inverse operation', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      let halveWasCalled = false;
+      const trackingHalveHandler = Operation.withHandler(HalveCompute, (data) => {
+        halveWasCalled = true;
+        return Effect.succeed({ value: data.value / 2 });
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, trackingHalveHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      // Fork compute operation: 2 * 2 = 4.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+      expect(tracker.canUndo()).toBe(true);
+
+      // Undo should invoke halve with { value: 4 }.
+      yield* tracker.undo();
+      expect(halveWasCalled).toBe(true);
+      expect(tracker.canUndo()).toBe(false);
+    }),
+  );
+
+  it.effect('undo uses _invokeCore to skip event emission', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      // Fork compute operation (should emit event).
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      yield* collector.waitForEvents(1);
+      expect(collector.events.length).toBe(1);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // Undo (should NOT emit event because it uses _invokeCore).
+      yield* tracker.undo();
+
+      // Verify no new events were emitted.
+      expect(collector.events.length).toBe(1);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('multiple undos work in LIFO order', () =>
+    Effect.gen(function* () {
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+      });
+
+      const halveInputs: number[] = [];
+      const trackingHalveHandler = Operation.withHandler(HalveCompute, (data) => {
+        halveInputs.push(data.value);
+        return Effect.succeed({ value: data.value / 2 });
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, trackingHalveHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      // Fork compute with 2 → 4.
+      const fiber1 = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber1);
+
+      // Fork compute with 3 → 6.
+      const fiber2 = yield* Effect.fork(invoker.invoke(Compute, { value: 3 }));
+      yield* TestClock.adjust('30 millis');
+      yield* Fiber.join(fiber2);
+
+      // Wait for both events to be collected.
+      yield* collector.waitForEvents(2);
+
+      // First undo should halve 6 (the output of the second compute).
+      yield* tracker.undo();
+      expect(halveInputs[0]).toBe(6);
+
+      // Second undo should halve 4 (the output of the first compute).
+      yield* tracker.undo();
+      expect(halveInputs[1]).toBe(4);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('undo on empty history returns error', () =>
+    Effect.gen(function* () {
+      const invoker = OperationInvoker.make(() => Effect.succeed([]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => []);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      const result = yield* tracker.undo().pipe(Effect.either);
+      expect(result._tag).toBe('Left');
+      if (result._tag === 'Left') {
+        expect(result.left.message).toContain('empty');
+      }
+    }),
+  );
+
+  it.effect('fires ShowUndo operation when undoable operation is tracked', () =>
+    Effect.gen(function* () {
+      const testMessage: [string, { ns: string }] = ['test-undo.message', { ns: 'test' }];
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+        message: testMessage,
+      });
+
+      let showUndoWasCalled = false;
+      let showUndoMessage: unknown = undefined;
+      const showUndoHandler = Operation.withHandler(UndoOperation.ShowUndo, (input) => {
+        showUndoWasCalled = true;
+        showUndoMessage = input.message;
+        return Effect.succeed(undefined);
+      });
+
+      const invoker = OperationInvoker.make(
+        () => Effect.succeed([computeHandler, halveComputeHandler, showUndoHandler]),
+        testRuntime,
+      );
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      expect(showUndoWasCalled).toBe(false);
+
+      // Fork compute operation and advance clock.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // ShowUndo should have been called with the message from the undo mapping.
+      yield* waitUntil(() => showUndoWasCalled);
+      expect(showUndoWasCalled).toBe(true);
+      expect(showUndoMessage).toEqual(testMessage);
+    }),
+  );
+
+  it.effect('ShowUndo message can be derived from input and output', () =>
+    Effect.gen(function* () {
+      // Dynamic message that depends on input/output.
+      const dynamicMessage = (input: { value: number }, output: { value: number }): [string, { ns: string }] => [
+        `computed-${input.value}-to-${output.value}`,
+        { ns: 'test' },
+      ];
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => ({ value: output.value }),
+        message: dynamicMessage,
+      });
+
+      let showUndoWasCalled = false;
+      let showUndoMessage: unknown = undefined;
+      const showUndoHandler = Operation.withHandler(UndoOperation.ShowUndo, (input) => {
+        showUndoWasCalled = true;
+        showUndoMessage = input.message;
+        return Effect.succeed(undefined);
+      });
+
+      const invoker = OperationInvoker.make(
+        () => Effect.succeed([computeHandler, halveComputeHandler, showUndoHandler]),
+        testRuntime,
+      );
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+
+      expect(showUndoWasCalled).toBe(false);
+
+      // Fork compute operation and advance clock (same as passing test).
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // ShowUndo should have been called with the derived message.
+      yield* waitUntil(() => showUndoWasCalled);
+      expect(showUndoWasCalled).toBe(true);
+      // Compute 2 * 2 = 4, so message should be 'computed 2 to 4'.
+      expect(showUndoMessage).toEqual(['computed-2-to-4', { ns: 'test' }]);
+    }),
+  );
+
+  it.effect('does not track operations when deriveContext returns undefined', () =>
+    Effect.gen(function* () {
+      // Undo mapping that conditionally returns undefined to indicate not undoable.
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => {
+          // Return undefined for values less than 10 to indicate not undoable.
+          if (output.value < 10) {
+            return undefined;
+          }
+          return { value: output.value };
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Compute 2 * 2 = 4, which is < 10, so deriveContext returns undefined.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 2 }));
+      yield* TestClock.adjust('20 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait for event to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Even though there's an undo mapping, deriveContext returned undefined,
+      // so this operation should not be tracked as undoable.
+      expect(tracker.canUndo()).toBe(false);
+
+      yield* collector.dispose;
+    }),
+  );
+
+  it.effect('tracks operations when deriveContext returns a value', () =>
+    Effect.gen(function* () {
+      // Undo mapping that conditionally returns undefined to indicate not undoable.
+      const undoMapping = UndoMapping.make({
+        operation: Compute,
+        inverse: HalveCompute,
+        deriveContext: (_input, output) => {
+          // Return undefined for values less than 10 to indicate not undoable.
+          if (output.value < 10) {
+            return undefined;
+          }
+          return { value: output.value };
+        },
+      });
+
+      const invoker = OperationInvoker.make(() => Effect.succeed([computeHandler, halveComputeHandler]), testRuntime);
+      const undoRegistry = UndoRegistry.make(() => [undoMapping]);
+      const tracker = HistoryTracker.make(invoker, undoRegistry);
+      const collector = yield* createEventCollector(invoker);
+
+      expect(tracker.canUndo()).toBe(false);
+
+      // Compute 5 * 2 = 10, which is >= 10, so deriveContext returns a value.
+      // Handler sleeps for value * 10 = 50ms.
+      const fiber = yield* Effect.fork(invoker.invoke(Compute, { value: 5 }));
+      yield* TestClock.adjust('50 millis');
+      yield* Fiber.join(fiber);
+
+      // Wait for event to be processed.
+      yield* collector.waitForEvents(1);
+
+      // Wait until the tracker has processed the event.
+      yield* waitUntil(() => tracker.canUndo());
+
+      // This operation should be tracked as undoable.
+      expect(tracker.canUndo()).toBe(true);
+
+      yield* collector.dispose;
+    }),
+  );
+});

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

@@ -0,0 +1,128 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Stream from 'effect/Stream';
+
+import { runAndForwardErrors } from '@dxos/effect';
+import { log } from '@dxos/log';
+import { type OperationInvoker } from '@dxos/operation';
+
+import { UndoOperation } from '../../common';
+import { EmptyHistoryError } from './errors';
+import type { HistoryEntry } from './types';
+import { resolveMessage } from './undo-mapping';
+import type { UndoRegistry } from './undo-registry';
+
+const HISTORY_LIMIT = 100;
+
+//
+// Public Interface
+//
+
+/**
+ * HistoryTracker interface - tracks operation history and provides undo.
+ */
+export interface HistoryTracker {
+  undo: () => Effect.Effect<void, Error>;
+  undoPromise: () => Promise<{ error?: Error }>;
+  canUndo: () => boolean;
+}
+
+//
+// Factory
+//
+
+/**
+ * Creates a HistoryTracker that subscribes to invocation events and provides undo.
+ */
+export const make = (
+  invoker: OperationInvoker.OperationInvokerInternal,
+  undoRegistry: UndoRegistry,
+): HistoryTracker => {
+  const history: HistoryEntry[] = [];
+
+  // Subscribe to invocation stream.
+  const handleInvocation = (event: OperationInvoker.InvocationEvent) => {
+    const mapping = undoRegistry.lookup(event.operation);
+    if (!mapping) {
+      // Operation is not undoable, skip.
+      return;
+    }
+
+    const inverseInput = mapping.deriveContext(event.input, event.output);
+    if (inverseInput === undefined) {
+      // Operation is conditionally not undoable (deriveContext returned undefined).
+      log('operation not undoable', { key: event.operation.meta.key });
+      return;
+    }
+
+    const entry: HistoryEntry = {
+      operation: event.operation,
+      input: event.input,
+      output: event.output,
+      inverse: mapping.inverse,
+      inverseInput,
+      timestamp: event.timestamp,
+    };
+
+    history.push(entry);
+    log('history entry added', { key: event.operation.meta.key, historyLength: history.length });
+
+    // Trim history if it exceeds limit.
+    if (history.length > HISTORY_LIMIT) {
+      history.splice(0, history.length - HISTORY_LIMIT);
+    }
+
+    // Show undo toast (resolve message if it's a function).
+    const resolvedMessage = resolveMessage(mapping.message, event.input, event.output);
+    Effect.runFork(
+      invoker.invoke(UndoOperation.ShowUndo, {
+        message: resolvedMessage,
+      }),
+    );
+  };
+
+  // Fork a fiber to consume the invocation stream.
+  Effect.runFork(
+    Stream.fromPubSub(invoker.invocations).pipe(
+      Stream.runForEach((event) => Effect.sync(() => handleInvocation(event))),
+    ),
+  );
+
+  const undo = (): Effect.Effect<void, Error> => {
+    return Effect.gen(function* () {
+      const entry = history.pop();
+      if (!entry) {
+        return yield* Effect.fail(new EmptyHistoryError());
+      }
+
+      log('undoing operation', { key: entry.operation.meta.key, inverseKey: entry.inverse.meta.key });
+
+      // Use _invokeCore to skip event emission (avoid undo-of-undo loops).
+      yield* invoker._invokeCore(entry.inverse, entry.inverseInput);
+
+      log('undo completed', { key: entry.operation.meta.key });
+    });
+  };
+
+  const undoPromise = async (): Promise<{ error?: Error }> => {
+    return runAndForwardErrors(undo())
+      .then(() => ({}))
+      .catch((error) => {
+        log.catch(error);
+        return { error };
+      });
+  };
+
+  const canUndo = (): boolean => {
+    return history.length > 0;
+  };
+
+  return {
+    undo,
+    undoPromise,
+    canUndo,
+  };
+};

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

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './errors';
+export * from './types';
+export * as UndoMapping from './undo-mapping';
+export * as UndoRegistry from './undo-registry';
+export * as HistoryTracker from './history-tracker';

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

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type { Operation } from '@dxos/operation';
+
+/**
+ * History entry stored by HistoryTracker.
+ */
+export type HistoryEntry = {
+  operation: Operation.Definition<any, any>;
+  input: any;
+  output: any;
+  inverse: Operation.Definition<any, any>;
+  inverseInput: any;
+  timestamp: number;
+};