@dxos/plugin-deck 0.8.4-main.d05673bc65 → 0.8.4-main.d9fc60f731

package/src/capabilities/notification-tracker.ts

@@ -0,0 +1,132 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Fiber from 'effect/Fiber';
+import * as Stream from 'effect/Stream';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { type LayoutOperation } from '@dxos/app-toolkit';
+import { Process } from '@dxos/compute';
+
+import { meta } from '#meta';
+import { DeckCapabilities } from '#types';
+
+const NOTIFY_TOAST_DURATION = 5_000;
+const ERROR_TOAST_DURATION = 10_000;
+const UNDO_TOAST_DURATION = 10_000;
+
+/**
+ * The single producer of toasts driven by operation invocations:
+ * - Per-invoke notifications ride the process monitor: each invocation spawns a process carrying the
+ *   caller's `notify` config on its params; this tracker watches process state transitions and toasts
+ *   on start / success / failure.
+ * - Undo toasts come from the history tracker's `undoable` stream (it owns the undo registry lookup);
+ *   the toast action triggers `historyTracker.undoPromise()`.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+    const ephemeralAtom = yield* Capability.get(DeckCapabilities.EphemeralState);
+    const monitor = yield* Capability.get(Capabilities.ProcessMonitor);
+
+    const addToast = (toast: LayoutOperation.Toast) => {
+      const state = registry.get(ephemeralAtom);
+      registry.set(ephemeralAtom, { ...state, toasts: [...state.toasts, toast] });
+    };
+
+    //
+    // Notifications — driven by the process monitor.
+    //
+
+    // Tracks the last-seen state per process so we only toast on transitions.
+    const lastState = new Map<Process.ID, Process.State>();
+
+    const handleProcesses = (processes: readonly Process.Info[]) => {
+      const seen = new Set<Process.ID>();
+      for (const process of processes) {
+        seen.add(process.pid);
+        const previous = lastState.get(process.pid);
+        lastState.set(process.pid, process.state);
+        if (previous === process.state) {
+          continue;
+        }
+
+        const notify = process.params.notify;
+        if (!notify) {
+          continue;
+        }
+
+        // Transition into RUNNING (the first snapshot may be a pre-RUNNING state like IDLE/HYBERNATING).
+        if (previous !== Process.State.RUNNING && process.state === Process.State.RUNNING && notify.start) {
+          addToast({ id: `notify-start-${process.pid}`, title: notify.start, duration: NOTIFY_TOAST_DURATION });
+        } else if (process.state === Process.State.SUCCEEDED && notify.success) {
+          addToast({ id: `notify-success-${process.pid}`, title: notify.success, duration: NOTIFY_TOAST_DURATION });
+        } else if (process.state === Process.State.FAILED && notify.error) {
+          addToast({
+            id: `notify-error-${process.pid}`,
+            title: notify.error,
+            ...(process.error ? { description: process.error } : {}),
+            icon: 'ph--warning--regular',
+            duration: ERROR_TOAST_DURATION,
+          });
+        }
+      }
+
+      // Drop bookkeeping for processes that have left the tree.
+      for (const pid of lastState.keys()) {
+        if (!seen.has(pid)) {
+          lastState.delete(pid);
+        }
+      }
+    };
+
+    const unsubscribeMonitor = registry.subscribe(monitor.processTreeAtom, handleProcesses);
+
+    //
+    // Undo — driven by the history tracker's `undoable` stream (it owns the registry lookup).
+    //
+
+    const showUndoToast = (message: LayoutOperation.Toast['title'], onUndo: () => void) => {
+      const undoId = `notify-undo-${crypto.randomUUID()}`;
+      const state = registry.get(ephemeralAtom);
+      // Replace the previous undo toast (only the most recent action can be undone).
+      const toasts = state.currentUndoId
+        ? state.toasts.filter((toast) => toast.id !== state.currentUndoId)
+        : state.toasts;
+      const toast: LayoutOperation.Toast = {
+        id: undoId,
+        title: message ?? ['undo-available.label', { ns: meta.id }],
+        duration: UNDO_TOAST_DURATION,
+        actionLabel: ['undo-action.label', { ns: meta.id }],
+        actionAlt: ['undo-action.alt', { ns: meta.id }],
+        closeLabel: ['undo-close.label', { ns: meta.id }],
+        onAction: onUndo,
+      };
+      registry.set(ephemeralAtom, { ...state, currentUndoId: undoId, toasts: [...toasts, toast] });
+    };
+
+    // The history tracker is contributed on ProcessManagerReady, possibly after this module activates;
+    // `waitFor` resolves it once available, then we observe its undoable stream.
+    const undoFiber = Effect.runFork(
+      Effect.gen(function* () {
+        const historyTracker = yield* Capability.waitFor(Capabilities.HistoryTracker);
+        yield* Stream.fromPubSub(historyTracker.undoable).pipe(
+          Stream.runForEach((event) =>
+            Effect.sync(() => showUndoToast(event.message, () => void historyTracker.undoPromise())),
+          ),
+        );
+      }).pipe(Effect.provideService(Capability.Service, capabilities)),
+    );
+
+    // Track both subscriptions so they are torn down when the module deactivates.
+    return Capability.contributes(Capabilities.Null, null, () =>
+      Effect.gen(function* () {
+        unsubscribeMonitor();
+        yield* Fiber.interrupt(undoFiber);
+      }),
+    );
+  }),
+);

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { DeckOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, DeckOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-root.tsx

@@ -0,0 +1,52 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import React, { useCallback } from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+
+import { DeckLayout } from '#containers';
+import { useDeckState } from '#hooks';
+import { meta } from '#meta';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactRoot, {
+      id: meta.id,
+      root: () => {
+        const { state, updateEphemeral } = useDeckState();
+
+        const handleDismissToast = useCallback(
+          (id: string) => {
+            if (!state.toasts.some((toast) => toast.id === id)) {
+              return;
+            }
+            // Allow time for the toast exit animation (animate-toast-hide, 100ms) before unmounting.
+            // TODO(burdon): Factor out and unregister timeout.
+            setTimeout(() => {
+              // Re-resolve the toast by id inside the update: the toast list may have changed during
+              // the delay, so a captured index would point at the wrong (or a missing) entry.
+              updateEphemeral((s) => {
+                const toastToRemove = s.toasts.find((toast) => toast.id === id);
+                if (!toastToRemove) {
+                  return s;
+                }
+                const newCurrentUndoId = toastToRemove.id === s.currentUndoId ? undefined : s.currentUndoId;
+                return {
+                  ...s,
+                  currentUndoId: newCurrentUndoId,
+                  toasts: s.toasts.filter((toast) => toast.id !== id),
+                };
+              });
+            }, 150);
+          },
+          [state.toasts, updateEphemeral],
+        );
+
+        return <DeckLayout onDismissToast={handleDismissToast} />;
+      },
+    }),
+  ),
+);

package/src/capabilities/{react-surface/react-surface.tsx → react-surface.tsx}

@@ -7,31 +7,29 @@ import React from 'react';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
 import { Surface, useSettingsState } from '@dxos/app-framework/ui';
-import { AppCapabilities } from '@dxos/app-toolkit';
+import { NOT_FOUND_PATH } from '@dxos/app-toolkit';
+import { AppSurface, NotFoundArticle } from '@dxos/app-toolkit/ui';
 
-import { Banner, DeckSettings } from '../../containers';
-import { meta } from '../../meta';
-import { type DeckSettingsProps } from '../../types';
+import { DeckSettings } from '#components';
+import { meta } from '#meta';
+import { type Settings } from '#types';
 
 export default Capability.makeModule(() =>
   Effect.succeed(
     Capability.contributes(Capabilities.ReactSurface, [
       Surface.create({
-        id: `${meta.id}.plugin-settings`,
-        role: 'article',
-        filter: (data): data is { subject: AppCapabilities.Settings } =>
-          AppCapabilities.isSettings(data.subject) && data.subject.prefix === meta.id,
+        id: 'pluginSettings',
+        filter: AppSurface.settings(AppSurface.Article, meta.id),
         component: ({ data: { subject } }) => {
-          const { settings, updateSettings } = useSettingsState<DeckSettingsProps>(subject.atom);
+          const { settings, updateSettings } = useSettingsState<Settings.Settings>(subject.atom);
           return <DeckSettings settings={settings} onSettingsChange={updateSettings} />;
         },
       }),
       Surface.create({
-        id: `${meta.id}.banner`,
-        role: 'banner',
-        component: ({ data }: { data: { variant?: 'topbar' | 'sidebar' } }) => {
-          return <Banner variant={data.variant} />;
-        },
+        id: 'notFound',
+        role: 'article',
+        filter: (data): data is { attendableId: string } => data.attendableId === NOT_FOUND_PATH,
+        component: () => <NotFoundArticle />,
       }),
     ]),
   ),

package/src/capabilities/{settings/settings.ts → settings.ts}

@@ -8,21 +8,18 @@ import { Capability } from '@dxos/app-framework';
 import { AppCapabilities } from '@dxos/app-toolkit';
 import { createKvsStore } from '@dxos/effect';
 
-import { meta } from '../../meta';
-import { DeckCapabilities, DeckSettingsSchema } from '../../types';
+import { meta } from '#meta';
+import { DeckCapabilities, Settings } from '#types';
 
 export default Capability.makeModule(() =>
   Effect.sync(() => {
     const settingsAtom = createKvsStore({
       key: meta.id,
-      schema: DeckSettingsSchema,
+      schema: Settings.Settings,
       defaultValue: () => ({
         showHints: false,
         enableDeck: false,
-        enableStatusbar: false,
         enableNativeRedirect: false,
-        newPlankPositioning: 'start' as const,
-        overscroll: 'none' as const,
         encapsulatedPlanks: false,
       }),
     });
@@ -31,7 +28,7 @@ export default Capability.makeModule(() =>
       Capability.contributes(DeckCapabilities.Settings, settingsAtom),
       Capability.contributes(AppCapabilities.Settings, {
         prefix: meta.id,
-        schema: DeckSettingsSchema,
+        schema: Settings.Settings,
         atom: settingsAtom,
       }),
     ];

package/src/capabilities/{state/state.ts → state.ts}

@@ -10,18 +10,13 @@ import { AppCapabilities } from '@dxos/app-toolkit';
 import { createKvsStore } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
 
-import { meta } from '../../meta';
-import {
-  DeckCapabilities,
-  type DeckEphemeralStateProps,
-  type DeckStateProps,
-  DeckStateSchema,
-  defaultDeck,
-  getMode,
-} from '../../types';
+import { meta } from '#meta';
+import { DeckCapabilities, type EphemeralDeckState, StoredDeckState, defaultDeck, getMode } from '#types';
+
+import { sanitizePersistedState } from '../util';
 
 /** Default persisted state. */
-const defaultDeckState: DeckStateProps = {
+const defaultDeckState: StoredDeckState = {
   sidebarState: 'expanded',
   complementarySidebarState: 'collapsed',
   complementarySidebarPanel: undefined,
@@ -34,7 +29,7 @@ const defaultDeckState: DeckStateProps = {
 };
 
 /** Default ephemeral state. */
-const defaultDeckEphemeralState: DeckEphemeralStateProps = {
+const defaultDeckEphemeralState: EphemeralDeckState = {
   dialogContent: null,
   dialogOpen: false,
   dialogBlockAlign: undefined,
@@ -55,27 +50,18 @@ export default Capability.makeModule(
     // Persisted state using KVS store.
     const stateAtom = createKvsStore({
       key: `${meta.id}.state`,
-      schema: DeckStateSchema,
+      schema: StoredDeckState,
       defaultValue: () => ({ ...defaultDeckState }),
     });
 
     // Ephemeral state (not persisted, but kept alive to prevent GC resets).
-    const ephemeralAtom = Atom.make<DeckEphemeralStateProps>({ ...defaultDeckEphemeralState }).pipe(Atom.keepAlive);
+    const ephemeralAtom = Atom.make<EphemeralDeckState>({ ...defaultDeckEphemeralState }).pipe(Atom.keepAlive);
 
-    // Don't allow fullscreen mode to be persisted to prevent getting stuck in it.
+    // Sanitize persisted state on startup (see sanitizePersistedState for details).
     const currentState = registry.get(stateAtom);
-    const currentDeck = currentState.decks[currentState.activeDeck];
-    if (currentDeck?.fullscreen) {
-      registry.set(stateAtom, {
-        ...currentState,
-        decks: {
-          ...currentState.decks,
-          [currentState.activeDeck]: {
-            ...currentDeck,
-            fullscreen: false,
-          },
-        },
-      });
+    const sanitizedState = sanitizePersistedState(currentState);
+    if (sanitizedState !== currentState) {
+      registry.set(stateAtom, sanitizedState);
     }
 
     // Create derived layout atom (read-only) from both state atoms.

package/src/capabilities/{tools/tools.ts → tools.ts}

@@ -15,19 +15,19 @@ import {
   type PromiseIntentDispatcher,
   createIntent,
 } from '@dxos/app-framework';
-import { type OperationInvoker } from '@dxos/app-framework/plugin-operation/invoker';
+import { LayoutOperation } from '@dxos/app-toolkit';
 import { invariant } from '@dxos/invariant';
+import { type OperationInvoker } from '@dxos/operation';
 import { trim } from '@dxos/util';
 
-import { meta } from '../../meta';
-import { DeckOperation } from '../../types';
+import { meta } from '#meta';
 
 // TODO(burdon): Factor out.
 declare global {
   interface ToolContextExtensions {
     dispatch?: PromiseIntentDispatcher;
     pivotId?: string;
-    part?: 'deck' | 'dialog';
+    part?: 'multi' | 'dialog';
   }
 }
 
@@ -58,9 +58,9 @@ export default Capability.makeModule(() =>
           invariant(pivotId, 'No pivot ID');
           invariant(invokePromise, 'No operation invoker');
 
-          if (part === 'deck') {
-            const { error } = await invokePromise(DeckOperation.ChangeCompanion, {
-              companion: id,
+          if (part === 'multi') {
+            const { error } = await invokePromise(LayoutOperation.UpdateCompanion, {
+              subject: id,
             });
             if (error) {
               return ToolResult.Error(error.message);