@dxos/plugin-deck 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/src/capabilities/tools.ts

@@ -2,80 +2,90 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Schema } from 'effect';
+// ISSUE(burdon): tools
+// @ts-nocheck
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
 
-import { createTool, ToolResult } from '@dxos/ai';
 import {
-  contributes,
-  createIntent,
   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 { DeckAction } from '../types';
+import { meta } from '#meta';
+import { DeckOperation } from '#operations';
 
 // 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: `
-        Show an item as a companion to an existing plank. This will make the item appear alongside the primary content.
-        When supplying IDs, they must be fully qualified like space:object.
+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,
+          if (part === 'multi') {
+            const { error } = await invokePromise(DeckOperation.ChangeCompanion, {
               companion: id,
-            }),
-          );
-          if (error) {
-            return ToolResult.Error(error.message);
-          }
+            });
+            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);
+          }
+        },
+      }),
+    ]),
+  ),
+);

package/src/capabilities/url-handler.ts

@@ -2,58 +2,230 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, contributes, createIntent, LayoutAction, type PluginContext } from '@dxos/app-framework';
-import { scheduledEffect } from '@dxos/echo-signals/core';
-
-import { DeckCapabilities } from './capabilities';
-import { defaultDeck } from '../types';
-
-// TODO(wittjosiah): Cleanup the url handling. May justify introducing routing capabilities.
-export default async (context: PluginContext) => {
-  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-  const state = context.getCapability(DeckCapabilities.MutableDeckState);
-
-  const handleNavigation = async () => {
-    const pathname = window.location.pathname;
-    if (pathname === '/reset') {
-      state.activeDeck = 'default';
-      state.decks = {
-        default: { ...defaultDeck },
-      };
-      window.location.pathname = '/';
-      return;
-    }
+import * as Effect from 'effect/Effect';
 
-    const [_, nextDeck, nextSolo] = pathname.split('/');
-    if (nextDeck && nextDeck !== state.activeDeck) {
-      await dispatch(createIntent(LayoutAction.SwitchWorkspace, { part: 'workspace', subject: nextDeck }));
-    }
+import { Capabilities, Capability } from '@dxos/app-framework';
+import {
+  AppCapabilities,
+  LayoutOperation,
+  NOT_FOUND_PATH,
+  expandPath,
+  fromUrlPath,
+  getWorkspaceFromPath,
+  toUrlPath,
+} from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { Operation } from '@dxos/operation';
+import { Node } from '@dxos/plugin-graph';
+import { isTauri } from '@dxos/util';
+
+import { DeckCapabilities, type StoredDeckState, defaultDeck } from '#types';
+
+import { updateActiveDeck } from '../operations/helpers';
+import { deserializePlanks, serializePlanks, stripPlanks } from '../util';
+import { shouldDeferNavigationHandlers } from './check-app-scheme';
+
+/** Dispatch all NavigationHandler contributions with a given URL. */
+const dispatchNavigationHandlers = Effect.fn(function* (url: URL) {
+  const handlers = yield* Capability.getAll(AppCapabilities.NavigationHandler);
+  yield* Effect.all(
+    handlers.map((handler) => handler(url)),
+    { concurrency: 'unbounded' },
+  );
+});
+
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const operationService = yield* Capability.get(Capabilities.OperationInvoker);
+    const capabilities = yield* Capability.Service;
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
+    const stateAtom = yield* Capability.get(DeckCapabilities.State);
+    const settingsAtom = yield* Capability.get(DeckCapabilities.Settings);
+
+    const provideServices = <A, E>(effect: Effect.Effect<A, E, Capability.Service | Operation.Service>) =>
+      effect.pipe(
+        Effect.provideService(Capability.Service, capabilities),
+        Effect.provideService(Operation.Service, operationService),
+      );
+
+    // 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: StoredDeckState) => StoredDeckState) => {
+      registry.set(stateAtom, fn(getState()));
+    };
+
+    const handleNavigation = Effect.fn(function* (url?: URL) {
+      const { graph } = yield* Capability.get(AppCapabilities.AppGraph);
+      const resolvedUrl = url ?? new URL(window.location.href);
+      // When native redirect is active, check-app-scheme owns the initial dispatch
+      // to prevent one-time tokens from being consumed before the native app can use them.
+      const settings = registry.get(settingsAtom);
+      const deferHandlers = settings?.enableNativeRedirect && shouldDeferNavigationHandlers();
+      if (!deferHandlers) {
+        yield* dispatchNavigationHandlers(resolvedUrl);
+      }
+
+      const pathname = resolvedUrl.pathname;
+      const state = getState();
+      if (pathname === '/reset') {
+        updateState((s) => ({
+          ...s,
+          activeDeck: 'default',
+          decks: {
+            default: { ...defaultDeck },
+          },
+        }));
+        window.location.pathname = '/';
+        return;
+      }
+
+      const qualifiedId = fromUrlPath(pathname);
+      const workspace = getWorkspaceFromPath(qualifiedId);
+      if (workspace !== Node.RootId && workspace !== state.activeDeck) {
+        yield* Operation.invoke(LayoutOperation.SwitchWorkspace, { subject: workspace });
+      }
 
-    if (nextSolo && nextSolo !== state.deck.solo) {
-      await dispatch(
-        createIntent(LayoutAction.SetLayoutMode, { part: 'mode', subject: nextSolo, options: { mode: 'solo' } }),
+      const deck = getDeck();
+      const activeId = qualifiedId !== workspace ? qualifiedId : undefined;
+      if (activeId) {
+        // Ensure the object referenced by the URL is open in the deck.
+        // Open validates the target and may redirect to 404, returning the resolved IDs.
+        const resolvedIds = yield* Operation.invoke(LayoutOperation.Open, { subject: [activeId] });
+        // If not already in solo mode, switch to solo for the resolved target.
+        if (!deck.solo) {
+          yield* Operation.invoke(LayoutOperation.SetLayoutMode, {
+            subject: resolvedIds?.[0] ?? activeId,
+            mode: 'solo',
+          });
+        }
+      } else if (deck.solo && deck.solo !== NOT_FOUND_PATH) {
+        // Stay in solo mode; redirect URL to reflect the current solo item.
+        // Do not switch to deck mode here — only explicit user action should change layout mode.
+        const path = toUrlPath(deck.solo);
+        if (window.location.pathname !== path) {
+          history.replaceState(null, '', `${path}${stripPlanks(window.location.search)}`);
+        }
+      } else if (!activeId && !deck.solo) {
+        // Multi-mode: restore planks from query params.
+        const plankIds = deserializePlanks(resolvedUrl);
+        if (plankIds.length > 0) {
+          for (const plankId of plankIds) {
+            expandPath(graph, plankId);
+          }
+          updateState((state) => updateActiveDeck(state, { active: plankIds, initialized: true }));
+        }
+      }
+    });
+
+    const onPopState = () => void runAndForwardErrors(provideServices(handleNavigation()));
+
+    // Initial navigation.
+    yield* provideServices(handleNavigation());
+    window.addEventListener('popstate', onPopState);
+
+    // Tauri deep link support.
+    let unlistenDeepLink: (() => void) | undefined;
+    if (isTauri()) {
+      yield* Effect.gen(function* () {
+        const { getCurrent, onOpenUrl } = yield* Effect.promise(() => import('@tauri-apps/plugin-deep-link'));
+
+        const launchUrls = yield* Effect.promise(() => getCurrent());
+        if (launchUrls && launchUrls.length > 0) {
+          log('app launched with deep links', { urls: launchUrls });
+          for (const urlString of launchUrls) {
+            yield* provideServices(handleDeepLink(urlString, handleNavigation));
+          }
+        }
+
+        unlistenDeepLink = yield* Effect.promise(() =>
+          onOpenUrl((urls) => {
+            for (const urlString of urls) {
+              void runAndForwardErrors(provideServices(handleDeepLink(urlString, handleNavigation)));
+            }
+          }),
+        );
+      }).pipe(
+        Effect.catchAll((error) => Effect.sync(() => log.warn('failed to initialize deep link listener', { error }))),
       );
-    } else if (!nextSolo && state.deck.solo) {
-      await dispatch(createIntent(LayoutAction.SetLayoutMode, { part: 'mode', options: { mode: 'deck' } }));
     }
-  };
-
-  await handleNavigation();
-  window.addEventListener('popstate', handleNavigation);
-
-  const unsubscribe = scheduledEffect(
-    () => ({ solo: state.deck.solo, activeDeck: state.activeDeck }),
-    ({ solo, 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}`);
+
+    // Sync URL with layout state changes.
+    let lastSolo: string | undefined;
+    let lastActiveDeck: string | undefined;
+    let lastActiveKey: string | undefined;
+    const unsubscribe = registry.subscribe(stateAtom, () => {
+      const state = getState();
+      const deck = getDeck();
+      const solo = deck.solo;
+      const activeDeck = state.activeDeck;
+      const activeKey = solo ? undefined : JSON.stringify(deck.active);
+
+      if (solo !== lastSolo || activeDeck !== lastActiveDeck || activeKey !== lastActiveKey) {
+        lastSolo = solo;
+        lastActiveDeck = activeDeck;
+        lastActiveKey = activeKey;
+
+        const path = solo && solo !== NOT_FOUND_PATH ? toUrlPath(solo) : toUrlPath(activeDeck);
+        const search = !solo
+          ? serializePlanks(deck.active, window.location.search)
+          : stripPlanks(window.location.search);
+        const newUrl = `${path}${search}`;
+
+        if (`${window.location.pathname}${window.location.search}` !== newUrl) {
+          history.pushState(null, '', newUrl);
+        }
       }
-    },
-  );
+    });
+
+    return Capability.contributes(Capabilities.Null, null, () =>
+      Effect.sync(() => {
+        window.removeEventListener('popstate', onPopState);
+        unsubscribe();
+        unlistenDeepLink?.();
+      }),
+    );
+  }),
+);
+
+/** Check if a path is a redirect path handled elsewhere (e.g., OAuth). */
+const isRedirectPath = (pathname: string): boolean => pathname.startsWith('/redirect/');
+
+/** Handle a deep link URL string. Merges query params into window.location and navigates. */
+const handleDeepLink = Effect.fn(function* (urlString: string, navigate: (url?: URL) => Effect.Effect<void, any, any>) {
+  log('deep link received', { url: urlString });
+
+  const deepLinkUrl = new URL(urlString);
+
+  // For custom schemes (e.g., composer://a/b/c), new URL() treats the first segment as the
+  // hostname. Reconstruct the full path from hostname + pathname.
+  const fullPath =
+    deepLinkUrl.protocol !== 'https:' && deepLinkUrl.protocol !== 'http:' && deepLinkUrl.hostname
+      ? '/' + deepLinkUrl.hostname + deepLinkUrl.pathname
+      : deepLinkUrl.pathname;
+
+  if (isRedirectPath(fullPath)) {
+    return;
+  }
+
+  // Merge deep link query params into the current window URL so handlers can read them.
+  const current = new URL(window.location.href);
+  if (deepLinkUrl.search) {
+    deepLinkUrl.searchParams.forEach((value, key) => current.searchParams.set(key, value));
+  }
+  current.pathname = fullPath;
+  history.replaceState(null, '', current.pathname + current.search);
 
-  return contributes(Capabilities.Null, null, () => {
-    window.removeEventListener('popstate', handleNavigation);
-    unsubscribe();
-  });
-};
+  yield* navigate(current);
+});

package/src/components/DeckSettings/DeckSettings.stories.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '../../translations';
+import { DeckSettings } from './DeckSettings';
+
+const meta = {
+  title: 'plugins/plugin-deck/components/DeckSettings',
+  tags: ['settings'],
+  component: DeckSettings,
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DeckSettings>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    settings: {
+      enableDeck: true,
+      encapsulatedPlanks: false,
+      enableStatusbar: true,
+      showHints: true,
+      enableNativeRedirect: false,
+    },
+  },
+};

package/src/components/DeckSettings/DeckSettings.tsx

@@ -4,85 +4,70 @@
 
 import React from 'react';
 
-import { Input, Select, useTranslation } from '@dxos/react-ui';
-import { DeprecatedFormContainer, DeprecatedFormInput } from '@dxos/react-ui-form';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Input, useTranslation } from '@dxos/react-ui';
+import { Settings as SettingsForm } from '@dxos/react-ui-form';
 
-import { DECK_PLUGIN } from '../../meta';
-import {
-  type DeckSettingsProps,
-  type NewPlankPositioning,
-  NewPlankPositions,
-  type Overscroll,
-  OverscrollOptions,
-} from '../../types';
+import { meta } from '#meta';
+import { Settings } from '#types';
 
 const isSocket = !!(globalThis as any).__args;
 
-export const DeckSettings = ({ settings }: { settings: DeckSettingsProps }) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+export type DeckSettingsProps = AppSurface.SettingsArticleProps<Settings.Settings>;
+
+export const DeckSettings = ({ settings, onSettingsChange }: DeckSettingsProps) => {
+  const { t } = useTranslation(meta.id);
 
   return (
-    <DeprecatedFormContainer>
-      <DeprecatedFormInput label={t('settings enable deck label')}>
-        <Input.Switch checked={settings.enableDeck} onCheckedChange={(checked) => (settings.enableDeck = checked)} />
-      </DeprecatedFormInput>
-      <DeprecatedFormInput label={t('select new plank positioning label')}>
-        <Select.Root
-          disabled={!settings.enableDeck}
-          value={settings.newPlankPositioning ?? 'start'}
-          onValueChange={(value) => (settings.newPlankPositioning = value as NewPlankPositioning)}
+    <SettingsForm.Viewport>
+      <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
+        <SettingsForm.Item title={t('settings.enable-deck.label')} description={t('settings.enable-deck.description')}>
+          <Input.Switch
+            disabled={!onSettingsChange}
+            checked={settings.enableDeck}
+            onCheckedChange={(checked) => onSettingsChange?.((s) => ({ ...s, enableDeck: checked }))}
+          />
+        </SettingsForm.Item>
+        <SettingsForm.Item
+          title={t('settings.encapsulated-planks.label')}
+          description={t('settings.encapsulated-planks.description')}
         >
-          <Select.TriggerButton placeholder={t('select new plank positioning placeholder')} />
-          <Select.Portal>
-            <Select.Content>
-              <Select.Viewport>
-                {NewPlankPositions.map((position) => (
-                  <Select.Option key={position} value={position}>
-                    {t(`settings new plank position ${position} label`)}
-                  </Select.Option>
-                ))}
-              </Select.Viewport>
-            </Select.Content>
-          </Select.Portal>
-        </Select.Root>
-      </DeprecatedFormInput>
-      <DeprecatedFormInput label={t('settings overscroll label')}>
-        <Select.Root
-          disabled={!settings.enableDeck}
-          value={settings.overscroll ?? 'none'}
-          onValueChange={(value) => (settings.overscroll = value as Overscroll)}
+          <Input.Switch
+            disabled={!onSettingsChange}
+            checked={settings.encapsulatedPlanks ?? false}
+            onCheckedChange={(checked) => onSettingsChange?.((s) => ({ ...s, encapsulatedPlanks: checked }))}
+          />
+        </SettingsForm.Item>
+        <SettingsForm.Item
+          title={t('settings.enable-statusbar.label')}
+          description={t('settings.enable-statusbar.description')}
         >
-          <Select.TriggerButton placeholder={t('select overscroll placeholder')} />
-          <Select.Portal>
-            <Select.Content>
-              <Select.Viewport>
-                {OverscrollOptions.map((option) => (
-                  <Select.Option key={option} value={option}>
-                    {t(`settings overscroll ${option} label`)}
-                  </Select.Option>
-                ))}
-              </Select.Viewport>
-            </Select.Content>
-          </Select.Portal>
-        </Select.Root>
-      </DeprecatedFormInput>
-      <DeprecatedFormInput label={t('settings enable statusbar label')}>
-        <Input.Switch
-          checked={settings.enableStatusbar}
-          onCheckedChange={(checked) => (settings.enableStatusbar = checked)}
-        />
-      </DeprecatedFormInput>
-      <DeprecatedFormInput label={t('settings show hints label')}>
-        <Input.Switch checked={settings.showHints} onCheckedChange={(checked) => (settings.showHints = checked)} />
-      </DeprecatedFormInput>
-      {!isSocket && (
-        <DeprecatedFormInput label={t('settings native redirect label')}>
           <Input.Switch
-            checked={settings.enableNativeRedirect}
-            onCheckedChange={(checked) => (settings.enableNativeRedirect = checked)}
+            disabled={!onSettingsChange}
+            checked={settings.enableStatusbar}
+            onCheckedChange={(checked) => onSettingsChange?.((s) => ({ ...s, enableStatusbar: checked }))}
+          />
+        </SettingsForm.Item>
+        <SettingsForm.Item title={t('settings.show-hints.label')} description={t('settings.show-hints.description')}>
+          <Input.Switch
+            disabled={!onSettingsChange}
+            checked={settings.showHints}
+            onCheckedChange={(checked) => onSettingsChange?.((s) => ({ ...s, showHints: checked }))}
           />
-        </DeprecatedFormInput>
-      )}
-    </DeprecatedFormContainer>
+        </SettingsForm.Item>
+        {!isSocket && (
+          <SettingsForm.Item
+            title={t('settings.native-redirect.label')}
+            description={t('settings.native-redirect.description')}
+          >
+            <Input.Switch
+              disabled={!onSettingsChange}
+              checked={settings.enableNativeRedirect}
+              onCheckedChange={(checked) => onSettingsChange?.((s) => ({ ...s, enableNativeRedirect: checked }))}
+            />
+          </SettingsForm.Item>
+        )}
+      </SettingsForm.Section>
+    </SettingsForm.Viewport>
   );
 };

package/src/components/DeckSettings/index.ts

@@ -1,5 +1,5 @@
 //
-// Copyright 2025 DXOS.org
+// Copyright 2024 DXOS.org
 //
 
-export * from './DeckSettings';
+export { DeckSettings as default } from './DeckSettings';