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

package/src/capabilities/check-app-scheme.ts

@@ -2,39 +2,138 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Capabilities, type PluginContext, contributes } from '@dxos/app-framework';
+import * as Effect from 'effect/Effect';
 
-import { DECK_PLUGIN } from '../meta';
-import { type DeckSettingsProps } from '../types';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { APP_SCHEME, AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
+import { runAndForwardErrors } from '@dxos/effect';
+import { isTauri } from '@dxos/util';
 
-const isSocket = !!(globalThis as any).__args;
+import { DeckCapabilities } from '#types';
 
-// TODO(mjamesderocher): Can we get this directly from Socket?
-const appScheme = 'composer://';
+/** Identifier for the native redirect dialog surface (defined in welcome plugin). */
+const NATIVE_REDIRECT_DIALOG = 'org.dxos.plugin.welcome.component.native-redirect-dialog';
 
-// TODO(mjamesderocher): Factor out as part of NavigationPlugin.
-const checkAppScheme = (url: string) => {
-  const iframe = document.createElement('iframe');
-  iframe.style.display = 'none';
-  document.body.appendChild(iframe);
+const SCHEME_TIMEOUT_MS = 500;
 
-  iframe.src = url + window.location.pathname.replace(/^\/+/, '') + window.location.search;
+const isSafari = (): boolean => {
+  const ua = navigator.userAgent;
+  return ua.includes('Safari') && !ua.includes('Chrome') && !ua.includes('Chromium');
+};
+
+/** Check if the current page URL can be converted to a valid custom scheme URL. */
+const canRedirectToScheme = (): boolean => {
+  try {
+    const schemeUrl = APP_SCHEME + window.location.pathname.replace(/^\/+/, '') + window.location.search;
+    new URL(schemeUrl);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Try to open the native app via custom scheme.
+ * Resolves `true` if the app opened (page lost focus), `false` if it didn't within the timeout.
+ */
+const tryOpenNativeApp = (): Promise<boolean> => {
+  return new Promise((resolve) => {
+    let resolved = false;
+
+    const onBlur = () => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(true);
+      }
+    };
+
+    const cleanup = () => {
+      window.removeEventListener('blur', onBlur);
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+    };
 
-  const timer = setTimeout(() => {
-    document.body.removeChild(iframe);
-  }, 3000);
+    const onVisibilityChange = () => {
+      if (document.hidden) {
+        onBlur();
+      }
+    };
 
-  window.addEventListener('pagehide', (event) => {
-    clearTimeout(timer);
-    document.body.removeChild(iframe);
+    window.addEventListener('blur', onBlur);
+    document.addEventListener('visibilitychange', onVisibilityChange);
+
+    // Try the scheme via hidden iframe.
+    const schemeUrl = APP_SCHEME + window.location.pathname.replace(/^\/+/, '') + window.location.search;
+    const iframe = document.createElement('iframe');
+    iframe.style.display = 'none';
+    iframe.src = schemeUrl;
+    document.body.appendChild(iframe);
+    setTimeout(() => iframe.remove(), 3000);
+
+    // If no blur within timeout, the app isn't running.
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        cleanup();
+        resolve(false);
+      }
+    }, SCHEME_TIMEOUT_MS);
   });
 };
 
-export default async (context: PluginContext) => {
-  const settings = context.getCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(DECK_PLUGIN)?.value;
-  if (!isSocket && settings?.enableNativeRedirect) {
-    checkAppScheme(appScheme);
-  }
+/** Dispatch all NavigationHandler contributions with the current page URL. */
+const dispatchNavigationHandlers = Effect.fn(function* () {
+  const url = new URL(window.location.href);
+  const handlers = yield* Capability.getAll(AppCapabilities.NavigationHandler);
+  yield* Effect.all(
+    handlers.map((handler) => handler(url)),
+    { concurrency: 'unbounded' },
+  );
+});
 
-  return contributes(Capabilities.Null, null);
+/**
+ * Checks whether the native redirect setting is enabled and the redirect should be attempted.
+ * Exported for the URL handler to decide whether to defer NavigationHandler dispatch.
+ */
+export const shouldDeferNavigationHandlers = (): boolean => {
+  return !isTauri() && !isSafari() && !import.meta.env.DEV && canRedirectToScheme();
 };
+
+/**
+ * When running in a web browser (not Tauri) with native redirect enabled,
+ * tries to open the native app via custom scheme. Defers NavigationHandlers
+ * to prevent the web app from consuming one-time tokens before the native app.
+ *
+ * If the app opens: shows dialog with "Open here" callback that dispatches handlers.
+ * If the app doesn't open: dispatches handlers immediately.
+ * In Safari: universal links handle this natively, so the check is skipped.
+ */
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const capabilities = yield* Capability.Service;
+    const { invoke } = yield* Capability.get(Capabilities.OperationInvoker);
+    const settings = yield* Capabilities.getAtomValue(DeckCapabilities.Settings);
+
+    if (!settings?.enableNativeRedirect || !shouldDeferNavigationHandlers()) {
+      return;
+    }
+
+    const appOpened = yield* Effect.promise(() => tryOpenNativeApp());
+    if (appOpened) {
+      const onOpenHere = () =>
+        Effect.gen(function* () {
+          yield* dispatchNavigationHandlers();
+          yield* invoke(LayoutOperation.UpdateDialog, { state: false });
+        }).pipe(Effect.provideService(Capability.Service, capabilities), runAndForwardErrors);
+
+      yield* invoke(LayoutOperation.UpdateDialog, {
+        subject: NATIVE_REDIRECT_DIALOG,
+        type: 'alert',
+        overlayClasses: 'dark bg-neutral-950!',
+        props: { onOpenHere },
+      });
+    } else {
+      yield* dispatchNavigationHandlers();
+    }
+  }),
+);

package/src/capabilities/index.ts

@@ -2,18 +2,17 @@
 // Copyright 2025 DXOS.org
 //
 
-import { lazy } from '@dxos/app-framework';
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/operation';
 
-export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
-export const CheckAppScheme = lazy(() => import('./check-app-scheme'));
-export const DeckSettings = lazy(() => import('./settings'));
-export const DeckState = lazy(() => import('./state'));
-export const LayoutIntentResolver = lazy(() => import('./intent-resolver'));
-export const ReactRoot = lazy(() => import('./react-root'));
-export const ReactSurface = lazy(() => import('./react-surface'));
-// export const Tools = lazy(() => import('./tools'));
-export const Toolkit = lazy(() => import('./toolkit'));
-export const UrlHandler = lazy(() => import('./url-handler'));
-
-export * from './capabilities';
-export * from './state';
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));
+export const CheckAppScheme = Capability.lazy('CheckAppScheme', () => import('./check-app-scheme'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactRoot = Capability.lazy('ReactRoot', () => import('./react-root'));
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const DeckSettings = Capability.lazy('DeckSettings', () => import('./settings'));
+export const DeckState = Capability.lazy('DeckState', () => import('./state'));
+export const UrlHandler = Capability.lazy('UrlHandler', () => import('./url-handler'));

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/operation';
+
+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

@@ -2,38 +2,46 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React, { useCallback } from 'react';
 
-import { Capabilities, contributes, useCapability } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
 
-import { DeckLayout } from '../components';
-import { DECK_PLUGIN } 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: DECK_PLUGIN,
-    root: () => {
-      const layout = useCapability(DeckCapabilities.MutableDeckState);
+        const handleDismissToast = useCallback(
+          (id: string) => {
+            const index = state.toasts.findIndex((toast) => toast.id === id);
+            if (index !== -1) {
+              // Allow time for the toast to animate out.
+              // TODO(burdon): Factor out and unregister timeout.
+              setTimeout(() => {
+                updateEphemeral((s) => {
+                  const toastToRemove = s.toasts[index];
+                  const newCurrentUndoId = toastToRemove?.id === s.currentUndoId ? undefined : s.currentUndoId;
+                  return {
+                    ...s,
+                    currentUndoId: newCurrentUndoId,
+                    toasts: s.toasts.filter((_, i) => i !== index),
+                  };
+                });
+              }, 1_000);
+            }
+          },
+          [state.toasts, updateEphemeral],
+        );
 
-      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.
-            // 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],
-      );
-
-      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 { DECK_PLUGIN } 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: `${DECK_PLUGIN}/plugin-settings`,
-      role: 'article',
-      filter: (data): data is { subject: SettingsStore<DeckSettingsProps> } =>
-        data.subject instanceof SettingsStore && data.subject.prefix === DECK_PLUGIN,
-      component: ({ data: { subject } }) => <DeckSettings settings={subject.value} />,
-    }),
-    createSurface({
-      id: `${DECK_PLUGIN}/banner`,
-      role: 'banner',
-      component: ({ data }) => {
-        return <Banner variant={data.variant} />;
-      },
-    }),
-  ]);
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'plugin-settings',
+        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: 'not-found',
+        role: 'article',
+        filter: (data): data is { attendableId: string } => data.attendableId === NOT_FOUND_PATH,
+        component: () => <NotFoundArticle />,
+      }),
+    ]),
+  ),
+);

package/src/capabilities/settings.ts

@@ -2,25 +2,36 @@
 // 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',
-  });
+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,
+        enableStatusbar: false,
+        enableNativeRedirect: !import.meta.env.DEV,
+        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,104 +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 { DECK_PLUGIN } 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 = {
-  [`${DECK_PLUGIN}/complementary-sidebar-state`]: 'expanded',
-  [`${DECK_PLUGIN}/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,
 };
 
-export const DeckStateFactory = () => {
-  migrateSidebarState();
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
 
-  const state = new LocalStorageStore<DeckPluginState>(DECK_PLUGIN, {
-    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);
 
-  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),
+    ];
+  }),
+);