@dxos/plugin-deck 0.8.4-main.3c1ae3b → 0.8.4-main.3eb6e50203

package/src/capabilities/settings/settings.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+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';
+
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = createKvsStore({
+      key: meta.id,
+      schema: DeckSettingsSchema,
+      defaultValue: () => ({
+        showHints: false,
+        enableDeck: false,
+        enableStatusbar: false,
+        enableNativeRedirect: false,
+        newPlankPositioning: 'start' as const,
+        overscroll: 'none' as const,
+        encapsulatedPlanks: false,
+      }),
+    });
+
+    return [
+      Capability.contributes(DeckCapabilities.Settings, settingsAtom),
+      Capability.contributes(AppCapabilities.Settings, {
+        prefix: meta.id,
+        schema: DeckSettingsSchema,
+        atom: settingsAtom,
+      }),
+    ];
+  }),
+);

package/src/capabilities/state/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const DeckState = Capability.lazy('DeckState', () => import('./state'));

package/src/capabilities/state/state.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+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';
+
+/** Default persisted state. */
+const defaultDeckState: DeckStateProps = {
+  sidebarState: 'expanded',
+  complementarySidebarState: 'collapsed',
+  complementarySidebarPanel: undefined,
+  activeDeck: 'default',
+  previousDeck: 'default',
+  decks: {
+    default: { ...defaultDeck },
+  },
+  previousMode: {},
+};
+
+/** Default ephemeral state. */
+const defaultDeckEphemeralState: DeckEphemeralStateProps = {
+  dialogContent: null,
+  dialogOpen: false,
+  dialogBlockAlign: undefined,
+  dialogType: undefined,
+  popoverContent: null,
+  popoverAnchor: undefined,
+  popoverAnchorId: undefined,
+  popoverOpen: false,
+  toasts: [],
+  currentUndoId: undefined,
+  scrollIntoView: undefined,
+};
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+
+    // Persisted state using KVS store.
+    const stateAtom = createKvsStore({
+      key: `${meta.id}/state`,
+      schema: DeckStateSchema,
+      defaultValue: () => ({ ...defaultDeckState }),
+    });
+
+    // Ephemeral state (not persisted, but kept alive to prevent GC resets).
+    const ephemeralAtom = Atom.make<DeckEphemeralStateProps>({ ...defaultDeckEphemeralState }).pipe(Atom.keepAlive);
+
+    // Don't allow fullscreen mode to be persisted to prevent getting stuck in it.
+    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,
+          },
+        },
+      });
+    }
+
+    // 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);
+
+    return [
+      Capability.contributes(DeckCapabilities.State, stateAtom),
+      Capability.contributes(DeckCapabilities.EphemeralState, ephemeralAtom),
+      Capability.contributes(AppCapabilities.Layout, layoutAtom),
+    ];
+  }),
+);

package/src/capabilities/toolkit/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const Toolkit = Capability.lazy('Toolkit', () => import('./toolkit'));

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

@@ -7,20 +7,14 @@ import * as Toolkit from '@effect/ai/Toolkit';
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
 
-import {
-  Capabilities,
-  type Capability,
-  LayoutAction,
-  type PluginContext,
-  contributes,
-  createIntent,
-} from '@dxos/app-framework';
+import { Capabilities, Capability, type CapabilityManager } from '@dxos/app-framework';
+import { AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
 import { GenericToolkit } from '@dxos/assistant';
 import { ArtifactId } from '@dxos/assistant';
 import { type SpaceId } from '@dxos/keys';
 import { trim } from '@dxos/util';
 
-import { DeckCapabilities } from './capabilities';
+import { DeckCapabilities } from '../../types';
 
 const Toolkit$ = Toolkit.make(
   Tool.make('open-item', {
@@ -38,11 +32,13 @@ const Toolkit$ = Toolkit.make(
 export namespace DeckToolkit {
   export const Toolkit = Toolkit$;
 
-  export const createLayer = (context: PluginContext) =>
+  export const createLayer = (capabilityManager: CapabilityManager.CapabilityManager) =>
     Toolkit$.toLayer({
       'open-item': ({ id }) =>
         Effect.gen(function* () {
-          const state = context.getCapability(DeckCapabilities.DeckState);
+          const registry = capabilityManager.get(Capabilities.AtomRegistry);
+          const stateAtom = capabilityManager.get(DeckCapabilities.State);
+          const state = registry.get(stateAtom);
           const dxn = ArtifactId.toDXN(id, state.activeDeck as SpaceId).asEchoDXN();
           if (!dxn) {
             // TODO(wittjosiah): Support other variants.
@@ -50,17 +46,19 @@ export namespace DeckToolkit {
           }
 
           // TODO(wittjosiah): Get capabilities via layers.
-          const { dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-          yield* dispatch(
-            createIntent(LayoutAction.Open, {
-              subject: [`${dxn.spaceId!}:${dxn.echoId}`],
-              part: 'main',
-            }),
-          );
+          const { invoke } = capabilityManager.get(Capabilities.OperationInvoker);
+          yield* invoke(LayoutOperation.Open, { subject: [`${dxn.spaceId!}:${dxn.echoId}`] });
         }).pipe(Effect.orDie),
     });
 }
 
-export default (context: PluginContext): Capability<any>[] => [
-  contributes(Capabilities.Toolkit, GenericToolkit.make(DeckToolkit.Toolkit, DeckToolkit.createLayer(context))),
-];
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilityManager = yield* Capability.Service;
+
+    return Capability.contributes(
+      AppCapabilities.Toolkit,
+      GenericToolkit.make(DeckToolkit.Toolkit, DeckToolkit.createLayer(capabilityManager)),
+    );
+  }),
+);

package/src/capabilities/tools/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const Tools = Capability.lazy('Tools', () => import('./tools'));

package/src/capabilities/tools/tools.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// ISSUE(burdon): tools
+// @ts-nocheck
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import {
+  Capabilities,
+  Capability,
+  LayoutAction,
+  type PromiseIntentDispatcher,
+  createIntent,
+} from '@dxos/app-framework';
+import { type OperationInvoker } from '@dxos/app-framework/plugin-operation/invoker';
+import { invariant } from '@dxos/invariant';
+import { trim } from '@dxos/util';
+
+import { meta } from '../../meta';
+import { DeckOperation } from '../../types';
+
+// TODO(burdon): Factor out.
+declare global {
+  interface ToolContextExtensions {
+    dispatch?: PromiseIntentDispatcher;
+    pivotId?: string;
+    part?: 'deck' | 'dialog';
+  }
+}
+
+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.',
+          }),
+        }),
+        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 { error } = await invokePromise(DeckOperation.ChangeCompanion, {
+              primary: pivotId,
+              companion: id,
+            });
+            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);
+          }
+        },
+      }),
+    ]),
+  ),
+);

package/src/capabilities/url-handler/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capability } from '@dxos/app-framework';
+
+export const UrlHandler = Capability.lazy('UrlHandler', () => import('./url-handler'));

package/src/capabilities/url-handler/url-handler.ts

@@ -0,0 +1,96 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { invariant } from '@dxos/invariant';
+
+import { DeckCapabilities, type DeckStateProps, defaultDeck } from '../../types';
+
+// TODO(wittjosiah): Cleanup the url handling. May justify introducing routing capabilities.
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const { invokeSync } = yield* Capability.get(Capabilities.OperationInvoker);
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+    const stateAtom = yield* Capability.get(DeckCapabilities.State);
+
+    // Helper to get state.
+    const getState = () => registry.get(stateAtom);
+
+    // Helper to get computed deck from state.
+    const getDeck = () => {
+      const state = getState();
+      const deck = state.decks[state.activeDeck];
+      invariant(deck, `Deck not found: ${state.activeDeck}`);
+      return deck;
+    };
+
+    // Helper to update state.
+    const updateState = (fn: (current: DeckStateProps) => DeckStateProps) => {
+      registry.set(stateAtom, fn(getState()));
+    };
+
+    const handleNavigation = () => {
+      const pathname = window.location.pathname;
+      const state = getState();
+      if (pathname === '/reset') {
+        updateState((s) => ({
+          ...s,
+          activeDeck: 'default',
+          decks: {
+            default: { ...defaultDeck },
+          },
+        }));
+        window.location.pathname = '/';
+        return;
+      }
+
+      const [_, nextDeck, nextSolo] = pathname.split('/');
+      if (nextDeck && nextDeck !== state.activeDeck) {
+        invokeSync(LayoutOperation.SwitchWorkspace, { subject: nextDeck });
+      }
+
+      const deck = getDeck();
+      if (nextSolo && nextSolo !== deck.solo) {
+        invokeSync(LayoutOperation.SetLayoutMode, { subject: nextSolo, mode: 'solo' });
+      } else if (!nextSolo && deck.solo) {
+        invokeSync(LayoutOperation.SetLayoutMode, { mode: 'deck' });
+      }
+    };
+
+    yield* Effect.sync(() => handleNavigation());
+    window.addEventListener('popstate', handleNavigation);
+
+    // Subscribe to state changes to update the URL.
+    let lastSolo: string | undefined;
+    let lastActiveDeck: string | undefined;
+    const unsubscribe = registry.subscribe(stateAtom, () => {
+      const state = getState();
+      const deck = getDeck();
+      const solo = deck.solo;
+      const activeDeck = state.activeDeck;
+
+      // Only update URL if relevant state changed.
+      if (solo !== lastSolo || activeDeck !== lastActiveDeck) {
+        lastSolo = solo;
+        lastActiveDeck = activeDeck;
+
+        const path = solo ? `/${activeDeck}/${solo}` : `/${activeDeck}`;
+        if (window.location.pathname !== path) {
+          // TODO(thure): In some browsers, this only preserves the most recent state change, even though this is not `history.replace`…
+          history.pushState(null, '', `${path}${window.location.search}`);
+        }
+      }
+    });
+
+    return Capability.contributes(Capabilities.Null, null, () =>
+      Effect.sync(() => {
+        window.removeEventListener('popstate', handleNavigation);
+        unsubscribe();
+      }),
+    );
+  }),
+);

package/src/components/DeckLayout/ActiveNode.tsx

@@ -4,7 +4,8 @@
 
 import React from 'react';
 
-import { Surface, useAppGraph } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { useNode } from '@dxos/plugin-graph';
 import { useAttended } from '@dxos/react-ui-attention';
 
@@ -21,7 +22,7 @@ export const ActiveNode = () => {
     <div role='none' className='sr-only'>
       {/* TODO(wittjosiah): Weird that this is a surface, feel like it's not really render logic.
             Probably this lives in React-land currently in order to access translations? */}
-      <Surface role='document-title' data={{ subject: activeNode }} limit={1} />
+      <Surface.Surface role='document-title' data={{ subject: activeNode }} limit={1} />
     </div>
   );
 };

package/src/components/DeckLayout/Banner.tsx

@@ -4,9 +4,9 @@
 
 import React from 'react';
 
-import { Surface } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
 import { type ThemedClassName, useTranslation } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx, osTranslations } from '@dxos/ui-theme';
 
 import { meta } from '../../meta';
 import { CloseSidebarButton, ToggleSidebarButton } from '../Sidebar';
@@ -23,17 +23,17 @@ export const Banner = ({ variant, classNames }: ThemedClassName<{ variant?: 'top
       )}
     >
       {variant === 'sidebar' ? <CloseSidebarButton /> : <ToggleSidebarButton />}
-      <span className='self-center grow mis-1'>{t('current app name', { ns: 'appkit' })}</span>
+      <span className='self-center grow mis-1'>{t('current app name', { ns: osTranslations })}</span>
       {variant === 'topbar' && (
         <div role='none' className='absolute inset-0 pointer-events-none'>
           <div role='none' className='grid bs-full pointer-fine:p-1 max-is-md mli-auto pointer-events-auto'>
-            <Surface role='search-input' limit={1} />
+            <Surface.Surface role='search-input' limit={1} />
           </div>
         </div>
       )}
       <span role='none' className='grow' />
-      <Surface role='header-end' limit={1} />
-      <Surface role='notch-start' limit={1} />
+      <Surface.Surface role='header-end' limit={1} />
+      <Surface.Surface role='notch-start' limit={1} />
     </header>
   );
 };

package/src/components/DeckLayout/ContentEmpty.tsx

@@ -4,10 +4,9 @@
 
 import React from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
 
-import { DeckCapabilities } from '../../capabilities';
-import { useBreakpoints } from '../../hooks';
+import { useBreakpoints, useDeckState } from '../../hooks';
 import { getMode } from '../../types';
 import { layoutAppliesTopbar } from '../../util';
 import { fixedSidebarToggleStyles } from '../fragments';
@@ -15,7 +14,7 @@ import { ToggleSidebarButton } from '../Sidebar';
 
 export const ContentEmpty = () => {
   const breakpoint = useBreakpoints();
-  const { deck } = useCapability(DeckCapabilities.MutableDeckState);
+  const { deck } = useDeckState();
   const layoutMode = getMode(deck);
   const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
   return (
@@ -24,7 +23,7 @@ export const ContentEmpty = () => {
       className='grid place-items-center p-8 relative bg-deckSurface'
       data-testid='layoutPlugin.firstRunMessage'
     >
-      <Surface role='keyshortcuts' />
+      <Surface.Surface role='keyshortcuts' />
       {!topbar && <ToggleSidebarButton variant='default' classNames={fixedSidebarToggleStyles} />}
     </div>
   );

package/src/components/DeckLayout/DeckLayout.stories.tsx

@@ -5,49 +5,38 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React from 'react';
 
-import { Events, IntentPlugin, SettingsPlugin, defineModule, definePlugin } from '@dxos/app-framework';
+import { Capability, Plugin } from '@dxos/app-framework';
 import { withPluginManager } from '@dxos/app-framework/testing';
-import { AttentionPlugin } from '@dxos/plugin-attention';
-import { GraphPlugin } from '@dxos/plugin-graph';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { corePlugins } from '@dxos/plugin-testing';
 import { withTheme } from '@dxos/react-ui/testing';
 
-import { DeckStateFactory, LayoutIntentResolver } from '../../capabilities';
+import { DeckState, LayoutOperationResolver } from '../../capabilities';
 import { meta as pluginMeta } from '../../meta';
 import { translations } from '../../translations';
 
 import { DeckLayout } from './DeckLayout';
 
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  AppPlugin.addOperationResolverModule({
+    activate: LayoutOperationResolver,
+  }),
+  Plugin.make,
+);
+
 const meta = {
   title: 'plugins/plugin-deck/DeckLayout',
   component: DeckLayout,
   render: (args) => <DeckLayout {...args} />,
   decorators: [
-    withTheme,
+    withTheme(),
     withPluginManager({
-      plugins: [
-        AttentionPlugin(),
-        SettingsPlugin(),
-        IntentPlugin(),
-        GraphPlugin(),
-        definePlugin(
-          {
-            id: 'example.com/plutin/testing',
-            name: 'Testing',
-          },
-          () => [
-            defineModule({
-              id: `${pluginMeta.id}/module/deck-state`,
-              activatesOn: Events.AppGraphReady,
-              activate: () => DeckStateFactory(),
-            }),
-            defineModule({
-              id: `${pluginMeta.id}/module/layout-intent-resolver`,
-              activatesOn: Events.SetupIntentResolver,
-              activate: LayoutIntentResolver,
-            }),
-          ],
-        )(),
-      ],
+      plugins: [...corePlugins(), TestPlugin()],
     }),
   ],
   parameters: {

package/src/components/DeckLayout/DeckLayout.tsx

@@ -4,9 +4,9 @@
 
 import React from 'react';
 
-import { useCapability } from '@dxos/app-framework/react';
+import { Mosaic } from '@dxos/react-ui-mosaic';
 
-import { DeckCapabilities } from '../../capabilities';
+import { useDeckState } from '../../hooks';
 
 import { ActiveNode } from './ActiveNode';
 import { DeckMain } from './DeckMain';
@@ -17,16 +17,18 @@ import { Toaster, type ToasterProps } from './Toast';
 export type DeckLayoutProps = Pick<ToasterProps, 'onDismissToast'>;
 
 export const DeckLayout = ({ onDismissToast }: DeckLayoutProps) => {
-  const context = useCapability(DeckCapabilities.MutableDeckState);
-  const { toasts } = context;
+  const { state } = useDeckState();
+  const { toasts } = state;
 
   return (
-    <PopoverRoot>
-      <ActiveNode />
-      <DeckMain />
-      <PopoverContent />
-      <Dialog />
-      <Toaster toasts={toasts} onDismissToast={onDismissToast} />
-    </PopoverRoot>
+    <Mosaic.Root>
+      <PopoverRoot>
+        <ActiveNode />
+        <DeckMain />
+        <PopoverContent />
+        <Dialog />
+        <Toaster toasts={toasts} onDismissToast={onDismissToast} />
+      </PopoverRoot>
+    </Mosaic.Root>
   );
 };