@dxos/plugin-deck 0.8.4-main.4a85c3132b → 0.8.4-main.51f1e5ca51

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,
@@ -54,28 +49,19 @@ export default Capability.makeModule(
 
     // Persisted state using KVS store.
     const stateAtom = createKvsStore({
-      key: `${meta.id}/state`,
-      schema: DeckStateSchema,
+      key: `${meta.id}.state`,
+      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}

@@ -16,18 +16,18 @@ import {
   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 { 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);

package/src/capabilities/url-handler.ts

@@ -0,0 +1,231 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import {
+  AppCapabilities,
+  LayoutOperation,
+  NOT_FOUND_PATH,
+  expandPath,
+  fromUrlPath,
+  getWorkspaceFromPath,
+  toUrlPath,
+} from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { runAndForwardErrors } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+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 });
+      }
+
+      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 }))),
+      );
+    }
+
+    // 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);
+
+  yield* navigate(current);
+});

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

@@ -0,0 +1,38 @@
+//
+// 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

@@ -0,0 +1,34 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { useTranslation } from '@dxos/react-ui';
+import { Settings as SettingsForm } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { Settings } from '#types';
+
+const isSocket = !!(globalThis as any).__args;
+
+export type DeckSettingsProps = AppSurface.SettingsArticleProps<Settings.Settings>;
+
+export const DeckSettings = ({ settings, onSettingsChange }: DeckSettingsProps) => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <SettingsForm.Viewport>
+      <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
+        <SettingsForm.FieldSet
+          readonly={!onSettingsChange}
+          schema={Settings.Settings}
+          visible={(path) => path !== 'enableNativeRedirect' || !isSocket}
+          values={settings}
+          onValuesChanged={(values) => onSettingsChange?.(() => values)}
+        />
+      </SettingsForm.Section>
+    </SettingsForm.Viewport>
+  );
+};

package/src/components/DeckSettings/index.ts

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

package/src/components/Matrix/Matrix.stories.tsx

@@ -0,0 +1,220 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Surface } from '@dxos/app-framework/ui';
+import { Graph } from '@dxos/app-graph';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { Obj } from '@dxos/echo';
+import { corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { Focus, Panel, Toolbar } from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+import { withAttention } from '@dxos/react-ui-attention/testing';
+import { type MosaicTileProps, Mosaic } from '@dxos/react-ui-mosaic';
+import { StackContext } from '@dxos/react-ui-stack';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Text } from '@dxos/schema';
+import { Organization, Person } from '@dxos/types';
+
+import { DeckState, OperationHandler } from '#capabilities';
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+
+import { Plank } from '../../containers/Plank';
+import { Matrix, type MatrixController, type MatrixRootProps } from './Matrix';
+
+random.seed(123);
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  AppPlugin.addOperationHandlerModule({
+    activate: OperationHandler,
+  }),
+  Plugin.make,
+);
+
+/**
+ * Simple tile with JSON display and attention tracking.
+ */
+const StoryTile = (props: MosaicTileProps<Obj.Any>) => {
+  const attentionAttrs = useAttentionAttributes(props.data.id);
+  return (
+    <Mosaic.Tile {...props} asChild>
+      <Focus.Item asChild border current={props.current}>
+        <Panel.Root classNames='dx-current dx-hover w-full md:w-[50rem] snap-start shrink-0' {...attentionAttrs}>
+          <Panel.Toolbar asChild>
+            <Toolbar.Root>
+              <p>{Obj.getLabel(props.data)}</p>
+            </Toolbar.Root>
+          </Panel.Toolbar>
+          <Syntax.Root data={props.data}>
+            <Panel.Content asChild>
+              <Syntax.Content>
+                <Syntax.Viewport>
+                  <Syntax.Code />
+                </Syntax.Viewport>
+              </Syntax.Content>
+            </Panel.Content>
+          </Syntax.Root>
+        </Panel.Root>
+      </Focus.Item>
+    </Mosaic.Tile>
+  );
+};
+
+/**
+ * Tile that wraps a Plank for content rendering.
+ */
+const PlankTile = (props: MosaicTileProps<Obj.Any>) => {
+  const graph = useMemo(() => Graph.make(), []);
+  return (
+    <StackContext.Provider value={{ orientation: 'horizontal', size: 'contain', rail: true }}>
+      <Plank.Root layoutMode='multi' part='multi' graph={graph}>
+        <Mosaic.Tile {...props} asChild>
+          <Plank.Content solo={false} companion={false} encapsulate={false}>
+            <Plank.Component
+              id={props.data.id}
+              part='multi'
+              node={{
+                id: props.data.id,
+                data: props.data,
+                type: 'test',
+                properties: {},
+              }}
+            />
+          </Plank.Content>
+        </Mosaic.Tile>
+      </Plank.Root>
+    </StackContext.Provider>
+  );
+};
+
+const TestExtension = Capability.contributes(
+  Capabilities.ReactSurface,
+  Surface.create({
+    id: 'story-article',
+    role: 'article',
+    component: ({ data: { subject } }) => {
+      if (!subject) {
+        return <Loading />;
+      }
+
+      return (
+        <Syntax.Root data={subject}>
+          <Syntax.Content>
+            <Syntax.Viewport>
+              <Syntax.Code />
+            </Syntax.Viewport>
+          </Syntax.Content>
+        </Syntax.Root>
+      );
+    },
+  }),
+);
+
+type DefaultStoryProps = Pick<MatrixRootProps, 'Tile'>;
+
+const DefaultStory = ({ Tile }: DefaultStoryProps) => {
+  const items = useMemo(
+    () => [
+      Organization.make({ name: random.company.name() }),
+      Person.make({ fullName: random.person.fullName() }),
+      Text.make({ name: 'Bio', content: random.lorem.paragraphs(10) }),
+      Text.make({ name: 'Companion', content: 'Companion panel for Bio' }),
+    ],
+    [],
+  );
+
+  const controller = useRef<MatrixController>(null);
+  const [current, setCurrent] = useState<string | undefined>(items[0]?.id);
+
+  const handleCurrentChange = useCallback((id: string | undefined) => {
+    setCurrent(id);
+  }, []);
+
+  const handlePrev = useCallback(() => {
+    const index = items.findIndex((item) => item.id === current);
+    const prev = items[Math.max(0, index - 1)];
+    if (prev) {
+      controller.current?.scrollTo(prev.id);
+    }
+  }, [items, current]);
+
+  const handleNext = useCallback(() => {
+    const index = items.findIndex((item) => item.id === current);
+    const next = items[Math.min(items.length - 1, index + 1)];
+    if (next) {
+      controller.current?.scrollTo(next.id);
+    }
+  }, [items, current]);
+
+  const currentIndex = items.findIndex((item) => item.id === current);
+
+  return (
+    <Mosaic.Root>
+      <Matrix.Root Tile={Tile} items={items} current={current} onCurrentChange={handleCurrentChange} ref={controller}>
+        <Panel.Root>
+          <Panel.Toolbar asChild>
+            <Toolbar.Root>
+              <Toolbar.IconButton icon='ph--caret-left--regular' iconOnly label='Back' onClick={handlePrev} />
+              <Toolbar.IconButton icon='ph--caret-right--regular' iconOnly label='Forward' onClick={handleNext} />
+              <Toolbar.Text>
+                {currentIndex + 1} / {items.length}
+              </Toolbar.Text>
+            </Toolbar.Root>
+          </Panel.Toolbar>
+          <Panel.Content asChild>
+            <Matrix.Content>
+              <Matrix.Viewport />
+            </Matrix.Content>
+          </Panel.Content>
+        </Panel.Root>
+      </Matrix.Root>
+    </Mosaic.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-deck/components/Matrix',
+  component: DefaultStory,
+  decorators: [withTheme(), withAttention(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<MatrixRootProps>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    Tile: StoryTile,
+  },
+};
+
+export const WithPlank: Story = {
+  decorators: [
+    withPluginManager({
+      plugins: [...corePlugins(), TestPlugin()],
+      capabilities: [TestExtension],
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+  args: {
+    Tile: PlankTile,
+  },
+};