@dxos/plugin-deck 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/capabilities/react-root.tsx

@@ -2,39 +2,51 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React, { useCallback } from 'react';
 
-import { Capabilities, contributes } from '@dxos/app-framework';
-import { useCapability } from '@dxos/app-framework/react';
+import { Capabilities, Capability } from '@dxos/app-framework';
 
-import { DeckLayout } from '../components';
-import { meta } from '../meta';
+import { DeckLayout } from '#containers';
+import { useDeckState } from '#hooks';
+import { meta } from '#meta';
 
-import { DeckCapabilities } from './capabilities';
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactRoot, {
+      id: meta.id,
+      root: () => {
+        const { state, updateEphemeral } = useDeckState();
 
-export default () =>
-  contributes(Capabilities.ReactRoot, {
-    id: meta.id,
-    root: () => {
-      const layout = useCapability(DeckCapabilities.MutableDeckState);
-
-      const handleDismissToast = useCallback(
-        (id: string) => {
-          const index = layout.toasts.findIndex((toast) => toast.id === id);
-          if (index !== -1) {
-            // Allow time for the toast to animate out.
+        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(() => {
-              if (layout.toasts[index].id === layout.currentUndoId) {
-                layout.currentUndoId = undefined;
-              }
-              layout.toasts.splice(index, 1);
-            }, 1_000);
-          }
-        },
-        [layout.toasts],
-      );
+              // 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} />;
-    },
-  });
+        return <DeckLayout onDismissToast={handleDismissToast} />;
+      },
+    }),
+  ),
+);

package/src/capabilities/react-surface.tsx

@@ -2,29 +2,35 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
-import { SettingsStore } from '@dxos/local-storage';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface, useSettingsState } from '@dxos/app-framework/ui';
+import { NOT_FOUND_PATH } from '@dxos/app-toolkit';
+import { AppSurface, NotFoundArticle } from '@dxos/app-toolkit/ui';
 
-import { Banner, DeckSettings } from '../components';
-import { meta } from '../meta';
-import { type DeckSettingsProps } from '../types';
+import { DeckSettings } from '#components';
+import { meta } from '#meta';
+import { type Settings } from '#types';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: `${meta.id}/plugin-settings`,
-      role: 'article',
-      filter: (data): data is { subject: SettingsStore<DeckSettingsProps> } =>
-        data.subject instanceof SettingsStore && data.subject.prefix === meta.id,
-      component: ({ data: { subject } }) => <DeckSettings settings={subject.value} />,
-    }),
-    createSurface({
-      id: `${meta.id}/banner`,
-      role: 'banner',
-      component: ({ data }) => {
-        return <Banner variant={data.variant} />;
-      },
-    }),
-  ]);
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'pluginSettings',
+        filter: AppSurface.settings(AppSurface.Article, meta.id),
+        component: ({ data: { subject } }) => {
+          const { settings, updateSettings } = useSettingsState<Settings.Settings>(subject.atom);
+          return <DeckSettings settings={settings} onSettingsChange={updateSettings} />;
+        },
+      }),
+      Surface.create({
+        id: 'notFound',
+        role: 'article',
+        filter: (data): data is { attendableId: string } => data.attendableId === NOT_FOUND_PATH,
+        component: () => <NotFoundArticle />,
+      }),
+    ]),
+  ),
+);

package/src/capabilities/settings.ts

@@ -2,26 +2,35 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, contributes } from '@dxos/app-framework';
-import { live } from '@dxos/live-object';
+import * as Effect from 'effect/Effect';
 
-import { meta } from '../meta';
-import { type DeckSettingsProps, DeckSettingsSchema } from '../types';
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { createKvsStore } from '@dxos/effect';
 
-export default () => {
-  const settings = live<DeckSettingsProps>({
-    showHints: false,
-    enableDeck: false,
-    enableStatusbar: false,
-    enableNativeRedirect: false,
-    newPlankPositioning: 'start',
-    overscroll: 'none',
-    encapsulatedPlanks: false,
-  });
+import { meta } from '#meta';
+import { DeckCapabilities, Settings } from '#types';
 
-  return contributes(Capabilities.Settings, {
-    prefix: meta.id,
-    schema: DeckSettingsSchema,
-    value: settings,
-  });
-};
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.id,
+      schema: Settings.Settings,
+      defaultValue: () => ({
+        showHints: false,
+        enableDeck: false,
+        enableNativeRedirect: false,
+        encapsulatedPlanks: false,
+      }),
+    });
+
+    return [
+      Capability.contributes(DeckCapabilities.Settings, settingsAtom),
+      Capability.contributes(AppCapabilities.Settings, {
+        prefix: meta.id,
+        schema: Settings.Settings,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/capabilities/state.ts

@@ -2,112 +2,90 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, contributes } from '@dxos/app-framework';
-import { invariant } from '@dxos/invariant';
-import { live } from '@dxos/live-object';
-import { LocalStorageStore } from '@dxos/local-storage';
-import { type SidebarState } from '@dxos/react-ui';
-
-import { meta } from '../meta';
-import { type DeckPluginState, type DeckState, defaultDeck, getMode } from '../types';
+import { Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
 
-import { DeckCapabilities } from './capabilities';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { createKvsStore } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
 
-const boolean = /true|false/;
+import { meta } from '#meta';
+import { DeckCapabilities, type EphemeralDeckState, StoredDeckState, defaultDeck, getMode } from '#types';
 
-// TODO(thure, 18 Feb 2025): Remove after the next release.
+import { sanitizePersistedState } from '../util';
 
-const migrateSidebarStateDefaults = {
-  [`${meta.id}/complementary-sidebar-state`]: 'expanded',
-  [`${meta.id}/sidebar-state`]: 'collapsed',
+/** Default persisted state. */
+const defaultDeckState: StoredDeckState = {
+  sidebarState: 'expanded',
+  complementarySidebarState: 'collapsed',
+  complementarySidebarPanel: undefined,
+  activeDeck: 'default',
+  previousDeck: 'default',
+  decks: {
+    default: { ...defaultDeck },
+  },
+  previousMode: {},
 };
 
-const migrateSidebarState = () => {
-  Object.entries(migrateSidebarStateDefaults).forEach(([key, defaultValue]) => {
-    if (boolean.test(localStorage.getItem(key) ?? 'never')) {
-      localStorage.setItem(key, defaultValue);
-    }
-  });
+/** Default ephemeral state. */
+const defaultDeckEphemeralState: EphemeralDeckState = {
+  dialogContent: null,
+  dialogOpen: false,
+  dialogBlockAlign: undefined,
+  dialogType: undefined,
+  popoverContent: null,
+  popoverAnchor: undefined,
+  popoverAnchorId: undefined,
+  popoverOpen: false,
+  toasts: [],
+  currentUndoId: undefined,
+  scrollIntoView: undefined,
 };
 
-/**
- * @deprecated
- */
-export const DeckStateFactory = () => {
-  migrateSidebarState();
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
 
-  const state = new LocalStorageStore<DeckPluginState>(meta.id, {
-    sidebarState: 'expanded',
-    complementarySidebarState: 'collapsed',
-    complementarySidebarPanel: undefined,
-    dialogContent: null,
-    dialogOpen: false,
-    dialogBlockAlign: undefined,
-    dialogType: undefined,
-    popoverContent: null,
-    popoverAnchor: undefined,
-    popoverAnchorId: undefined,
-    popoverOpen: false,
-    toasts: [],
-    currentUndoId: undefined,
-    activeDeck: 'default',
-    previousDeck: 'default',
-    decks: {
-      default: { ...defaultDeck },
-    },
-    get deck() {
-      const deck = this.decks[this.activeDeck];
-      invariant(deck, `Deck not found: ${this.activeDeck}`);
-      return deck;
-    },
-    previousMode: {},
-    scrollIntoView: undefined,
-  });
+    // Persisted state using KVS store.
+    const stateAtom = createKvsStore({
+      key: `${meta.id}.state`,
+      schema: StoredDeckState,
+      defaultValue: () => ({ ...defaultDeckState }),
+    });
 
-  state
-    .prop({ key: 'sidebarState', type: LocalStorageStore.enum<SidebarState>() })
-    .prop({ key: 'complementarySidebarState', type: LocalStorageStore.enum<SidebarState>() })
-    .prop({ key: 'complementarySidebarPanel', type: LocalStorageStore.string({ allowUndefined: true }) })
-    .prop({ key: 'decks', type: LocalStorageStore.json<Record<string, DeckState>>() })
-    .prop({ key: 'activeDeck', type: LocalStorageStore.string() })
-    .prop({ key: 'previousDeck', type: LocalStorageStore.string() });
+    // Ephemeral state (not persisted, but kept alive to prevent GC resets).
+    const ephemeralAtom = Atom.make<EphemeralDeckState>({ ...defaultDeckEphemeralState }).pipe(Atom.keepAlive);
 
-  // Don't allow fullscreen mode to be persisted to prevent getting stuck in it.
-  if (state.values.deck.fullscreen) {
-    state.values.deck.fullscreen = false;
-  }
-
-  const layout = live<Capabilities.Layout>({
-    get mode() {
-      return getMode(state.values.deck);
-    },
-    get dialogOpen() {
-      return state.values.dialogOpen;
-    },
-    get sidebarOpen() {
-      return state.values.sidebarState === 'expanded';
-    },
-    get complementarySidebarOpen() {
-      return state.values.complementarySidebarState === 'expanded';
-    },
-    get workspace() {
-      return state.values.activeDeck;
-    },
-    get active() {
-      return state.values.deck.solo ? [state.values.deck.solo] : state.values.deck.active;
-    },
-    get inactive() {
-      return state.values.deck.inactive;
-    },
-    get scrollIntoView() {
-      return state.values.scrollIntoView;
-    },
-  });
+    // Sanitize persisted state on startup (see sanitizePersistedState for details).
+    const currentState = registry.get(stateAtom);
+    const sanitizedState = sanitizePersistedState(currentState);
+    if (sanitizedState !== currentState) {
+      registry.set(stateAtom, sanitizedState);
+    }
 
-  return [
-    contributes(DeckCapabilities.DeckState, state.values, () => state.close()),
-    contributes(Capabilities.Layout, layout),
-  ];
-};
+    // Create derived layout atom (read-only) from both state atoms.
+    const layoutAtom = Atom.make((get) => {
+      const state = get(stateAtom);
+      const ephemeral = get(ephemeralAtom);
+      const deck = state.decks[state.activeDeck];
+      invariant(deck, `Deck not found: ${state.activeDeck}`);
+      return {
+        mode: getMode(deck),
+        dialogOpen: ephemeral.dialogOpen,
+        sidebarOpen: state.sidebarState === 'expanded',
+        complementarySidebarOpen: state.complementarySidebarState === 'expanded',
+        workspace: state.activeDeck,
+        active: deck.solo ? [deck.solo] : deck.active,
+        inactive: deck.inactive,
+        scrollIntoView: ephemeral.scrollIntoView,
+      } satisfies AppCapabilities.Layout;
+    }).pipe(Atom.keepAlive);
 
-export default DeckStateFactory;
+    return [
+      Capability.contributes(DeckCapabilities.State, stateAtom),
+      Capability.contributes(DeckCapabilities.EphemeralState, ephemeralAtom),
+      Capability.contributes(AppCapabilities.Layout, layoutAtom),
+    ];
+  }),
+);

package/src/capabilities/tools.ts

@@ -5,80 +5,87 @@
 // ISSUE(burdon): tools
 // @ts-nocheck
 
+import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
 import {
   Capabilities,
+  Capability,
   LayoutAction,
   type PromiseIntentDispatcher,
-  contributes,
   createIntent,
 } from '@dxos/app-framework';
+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 { DeckAction } from '../types';
+import { meta } from '#meta';
 
 // TODO(burdon): Factor out.
 declare global {
   interface ToolContextExtensions {
     dispatch?: PromiseIntentDispatcher;
     pivotId?: string;
-    part?: 'deck' | 'dialog';
+    part?: 'multi' | 'dialog';
   }
 }
 
-export default () =>
-  contributes(Capabilities.Tools, [
-    createTool(meta.id, {
-      name: 'show',
-      description: trim`
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.Tools, [
+      createTool(meta.id, {
+        name: 'show',
+        description: trim`
         Show an item as a companion to an existing plank. 
         When supplying IDs, they must be fully qualified like this: space-key:object-id
       `,
-      caption: 'Showing item...',
-      // TODO(wittjosiah): Refactor Layout/Navigation/Deck actions so that they can be used directly.
-      schema: Schema.Struct({
-        id: Schema.String.annotations({
-          description: 'The ID of the item to show.',
+        caption: 'Showing item...',
+        // TODO(wittjosiah): Refactor Layout/Navigation/Deck actions so that they can be used directly.
+        schema: Schema.Struct({
+          id: Schema.String.annotations({
+            description: 'The ID of the item to show.',
+          }),
         }),
-      }),
-      execute: async ({ id }, { extensions }) => {
-        invariant(extensions);
-        const { pivotId, dispatch, part } = extensions;
-        invariant(pivotId, 'No pivot ID');
-        invariant(dispatch, 'No intent dispatcher');
+        execute: async ({ id }, { extensions }) => {
+          invariant(extensions);
+          const { pivotId, dispatch, invokePromise, part } = extensions as {
+            pivotId: string;
+            dispatch: PromiseIntentDispatcher;
+            invokePromise: OperationInvoker['invokePromise'];
+            part: string;
+          };
+          invariant(pivotId, 'No pivot ID');
+          invariant(invokePromise, 'No operation invoker');
 
-        if (part === 'deck') {
-          const { data, error } = await dispatch(
-            createIntent(DeckAction.ChangeCompanion, {
-              primary: pivotId,
-              companion: id,
-            }),
-          );
-          if (error) {
-            return ToolResult.Error(error.message);
-          }
+          if (part === 'multi') {
+            const { error } = await invokePromise(LayoutOperation.UpdateCompanion, {
+              subject: id,
+            });
+            if (error) {
+              return ToolResult.Error(error.message);
+            }
 
-          return ToolResult.Success(data);
-        } else {
-          const { data, error } = await dispatch(
-            createIntent(LayoutAction.Open, {
-              subject: [id],
-              part: 'main',
-              options: {
-                pivotId,
-                positioning: 'end',
-              },
-            }),
-          );
-          if (error) {
-            return ToolResult.Error(error.message);
-          }
+            return ToolResult.Success({});
+          } else {
+            const { data, error } = await dispatch(
+              createIntent(LayoutAction.Open, {
+                subject: [id],
+                part: 'main',
+                options: {
+                  pivotId,
+                  positioning: 'end',
+                },
+              }),
+            );
+            if (error) {
+              return ToolResult.Error(error.message);
+            }
 
-          return ToolResult.Success(data);
-        }
-      },
-    }),
-  ]);
+            return ToolResult.Success(data);
+          }
+        },
+      }),
+    ]),
+  ),
+);