@dxos/plugin-simple-layout 0.8.4-main.69d29f4 → 0.8.4-main.8360d9e660

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-simple-layout",
-  "version": "0.8.4-main.69d29f4",
+  "version": "0.8.4-main.8360d9e660",
   "description": "Simple layout plugin for minimal UI contexts like popover windows.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -15,9 +15,9 @@
   "exports": {
     ".": {
       "source": "./src/index.ts",
-      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
-      "node": "./dist/lib/node-esm/index.mjs"
+      "node": "./dist/lib/node-esm/index.mjs",
+      "types": "./dist/types/src/index.d.ts"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -26,44 +26,50 @@
     "src"
   ],
   "dependencies": {
-    "@effect-atom/atom": "^0.4.13",
-    "@effect-atom/atom-react": "^0.4.6",
+    "@effect-atom/atom": "^0.5.1",
+    "@effect-atom/atom-react": "^0.5.0",
     "@radix-ui/react-context": "1.1.1",
-    "@dxos/log": "0.8.4-main.69d29f4",
-    "@dxos/app-framework": "0.8.4-main.69d29f4",
-    "@dxos/operation": "0.8.4-main.69d29f4",
-    "@dxos/plugin-graph": "0.8.4-main.69d29f4",
-    "@dxos/react-ui-menu": "0.8.4-main.69d29f4",
-    "@dxos/react-ui-mosaic": "0.8.4-main.69d29f4",
-    "@dxos/react-ui-attention": "0.8.4-main.69d29f4",
-    "@dxos/react-ui-searchlist": "0.8.4-main.69d29f4",
-    "@dxos/react-ui-stack": "0.8.4-main.69d29f4",
-    "@dxos/schema": "0.8.4-main.69d29f4",
-    "@dxos/util": "0.8.4-main.69d29f4"
+    "@tauri-apps/plugin-deep-link": "^2.2.0",
+    "@tauri-apps/plugin-haptics": "^2.3.2",
+    "@dxos/app-toolkit": "0.8.4-main.8360d9e660",
+    "@dxos/app-framework": "0.8.4-main.8360d9e660",
+    "@dxos/echo": "0.8.4-main.8360d9e660",
+    "@dxos/async": "0.8.4-main.8360d9e660",
+    "@dxos/log": "0.8.4-main.8360d9e660",
+    "@dxos/operation": "0.8.4-main.8360d9e660",
+    "@dxos/plugin-graph": "0.8.4-main.8360d9e660",
+    "@dxos/react-ui-attention": "0.8.4-main.8360d9e660",
+    "@dxos/react-ui-menu": "0.8.4-main.8360d9e660",
+    "@dxos/react-ui-mosaic": "0.8.4-main.8360d9e660",
+    "@dxos/schema": "0.8.4-main.8360d9e660",
+    "@dxos/react-ui-searchlist": "0.8.4-main.8360d9e660",
+    "@dxos/util": "0.8.4-main.8360d9e660",
+    "@dxos/react-ui-stack": "0.8.4-main.8360d9e660"
   },
   "devDependencies": {
     "@types/react": "~19.2.7",
     "@types/react-dom": "~19.2.3",
-    "effect": "3.19.11",
+    "effect": "3.19.16",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "vite": "7.1.9",
-    "@dxos/plugin-client": "0.8.4-main.69d29f4",
-    "@dxos/plugin-preview": "0.8.4-main.69d29f4",
-    "@dxos/plugin-search": "0.8.4-main.69d29f4",
-    "@dxos/plugin-space": "0.8.4-main.69d29f4",
-    "@dxos/react-ui": "0.8.4-main.69d29f4",
-    "@dxos/plugin-testing": "0.8.4-main.69d29f4",
-    "@dxos/schema": "0.8.4-main.69d29f4",
-    "@dxos/storybook-utils": "0.8.4-main.69d29f4",
-    "@dxos/ui-theme": "0.8.4-main.69d29f4"
+    "vite": "^7.1.11",
+    "@dxos/app-graph": "0.8.4-main.8360d9e660",
+    "@dxos/plugin-client": "0.8.4-main.8360d9e660",
+    "@dxos/plugin-preview": "0.8.4-main.8360d9e660",
+    "@dxos/plugin-search": "0.8.4-main.8360d9e660",
+    "@dxos/react-ui": "0.8.4-main.8360d9e660",
+    "@dxos/schema": "0.8.4-main.8360d9e660",
+    "@dxos/plugin-testing": "0.8.4-main.8360d9e660",
+    "@dxos/plugin-space": "0.8.4-main.8360d9e660",
+    "@dxos/storybook-utils": "0.8.4-main.8360d9e660",
+    "@dxos/ui-theme": "0.8.4-main.8360d9e660"
   },
   "peerDependencies": {
-    "effect": "3.19.11",
+    "effect": "3.19.16",
     "react": "~19.2.3",
     "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.8.4-main.69d29f4",
-    "@dxos/ui-theme": "0.8.4-main.69d29f4"
+    "@dxos/react-ui": "0.8.4-main.8360d9e660",
+    "@dxos/ui-theme": "0.8.4-main.8360d9e660"
   },
   "publishConfig": {
     "access": "public"

package/src/SimpleLayoutPlugin.ts

@@ -2,7 +2,8 @@
 // Copyright 2025 DXOS.org
 //
 
-import { ActivationEvent, Capability, Common, Plugin } from '@dxos/app-framework';
+import { ActivationEvent, ActivationEvents, Capability, Plugin } from '@dxos/app-framework';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
 
 import { OperationResolver, ReactRoot, ReactSurface, SpotlightDismiss, State, UrlHandler } from './capabilities';
 import { meta } from './meta';
@@ -15,33 +16,33 @@ export type SimpleLayoutPluginOptions = {
 };
 
 export const SimpleLayoutPlugin = Plugin.define<SimpleLayoutPluginOptions>(meta).pipe(
+  AppPlugin.addOperationResolverModule({ activate: OperationResolver }),
+  AppPlugin.addTranslationsModule({ translations }),
   Plugin.addModule(({ isPopover = false }) => ({
     id: Capability.getModuleTag(State),
-    activatesOn: Common.ActivationEvent.Startup,
-    activatesAfter: [SimpleLayoutEvents.StateReady, Common.ActivationEvent.LayoutReady],
+    activatesOn: ActivationEvents.Startup,
+    activatesAfter: [SimpleLayoutEvents.StateReady, AppActivationEvents.LayoutReady],
     activate: () => State({ initialState: { isPopover } }),
   })),
   Plugin.addModule(({ isPopover = false }) => ({
     id: Capability.getModuleTag(SpotlightDismiss),
-    activatesOn: Common.ActivationEvent.Startup,
+    activatesOn: ActivationEvents.Startup,
     activate: () => SpotlightDismiss({ isPopover }),
   })),
   Plugin.addModule({
     id: Capability.getModuleTag(ReactRoot),
-    activatesOn: Common.ActivationEvent.Startup,
+    activatesOn: ActivationEvents.Startup,
     activate: ReactRoot,
   }),
   Plugin.addModule({
     id: Capability.getModuleTag(ReactSurface),
-    activatesOn: Common.ActivationEvent.Startup,
+    activatesOn: ActivationEvents.Startup,
     activate: ReactSurface,
   }),
   Plugin.addModule({
     id: Capability.getModuleTag(UrlHandler),
-    activatesOn: ActivationEvent.allOf(Common.ActivationEvent.OperationInvokerReady, SimpleLayoutEvents.StateReady),
+    activatesOn: ActivationEvent.allOf(ActivationEvents.OperationInvokerReady, SimpleLayoutEvents.StateReady),
     activate: UrlHandler,
   }),
-  Common.Plugin.addOperationResolverModule({ activate: OperationResolver }),
-  Common.Plugin.addTranslationsModule({ translations }),
   Plugin.make,
 );

package/src/capabilities/operation-resolver/operation-resolver.ts

@@ -4,7 +4,8 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Capability, Common } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { getCompanionVariant, LayoutOperation, isPinnedWorkspace } from '@dxos/app-toolkit';
 import { Operation, OperationResolver } from '@dxos/operation';
 
 import { type SimpleLayoutState, SimpleLayoutState as SimpleLayoutStateCapability } from '../../types';
@@ -14,7 +15,7 @@ const MAX_HISTORY_LENGTH = 50;
 
 export default Capability.makeModule(
   Effect.fnUntraced(function* () {
-    const registry = yield* Capability.get(Common.Capability.AtomRegistry);
+    const registry = yield* Capability.get(Capabilities.AtomRegistry);
     const stateAtom = yield* Capability.get(SimpleLayoutStateCapability);
 
     const getState = () => registry.get(stateAtom);
@@ -22,28 +23,53 @@ export default Capability.makeModule(
       registry.set(stateAtom, fn(getState()));
     };
 
-    return Capability.contributes(Common.Capability.OperationResolver, [
+    return Capability.contributes(Capabilities.OperationResolver, [
+      //
+      // SetLayoutMode
+      //
+      // TODO(burdon): No-op for to fix startup bug?
+      OperationResolver.make({
+        operation: LayoutOperation.SetLayoutMode,
+        handler: Effect.fnUntraced(function* () {}),
+      }),
+
       //
       // UpdateSidebar - No-op for simple layout.
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.UpdateSidebar,
+        operation: LayoutOperation.UpdateSidebar,
         handler: () => Effect.void,
       }),
 
       //
-      // UpdateComplementary - No-op for simple layout.
+      // UpdateComplementary - Controls companion drawer.
       //
+      // TODO(wittjosiah): Not sure if we should be using this for the drawer.
       OperationResolver.make({
-        operation: Common.LayoutOperation.UpdateComplementary,
-        handler: () => Effect.void,
+        operation: LayoutOperation.UpdateComplementary,
+        handler: Effect.fnUntraced(function* (input) {
+          if (input.state === 'closed') {
+            updateState((state) => ({
+              ...state,
+              drawerState: 'closed',
+              companionVariant: undefined,
+            }));
+          } else if (input.subject) {
+            const variant = getCompanionVariant(input.subject);
+            updateState((state) => ({
+              ...state,
+              companionVariant: variant,
+              drawerState: input.state === 'expanded' ? 'expanded' : 'open',
+            }));
+          }
+        }),
       }),
 
       //
       // UpdateDialog
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.UpdateDialog,
+        operation: LayoutOperation.UpdateDialog,
         handler: Effect.fnUntraced(function* (input) {
           updateState((state) => ({
             ...state,
@@ -61,7 +87,7 @@ export default Capability.makeModule(
       // UpdatePopover
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.UpdatePopover,
+        operation: LayoutOperation.UpdatePopover,
         handler: Effect.fnUntraced(function* (input) {
           updateState((state) => ({
             ...state,
@@ -86,13 +112,13 @@ export default Capability.makeModule(
       // SwitchWorkspace
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.SwitchWorkspace,
+        operation: LayoutOperation.SwitchWorkspace,
         handler: Effect.fnUntraced(function* (input) {
           updateState((state) => ({
             ...state,
             // TODO(wittjosiah): This is a hack to prevent the previous deck from being set for pinned items.
             //  Ideally this should be worked into the data model in a generic way.
-            previousWorkspace: !state.workspace.startsWith('!') ? state.workspace : state.previousWorkspace,
+            previousWorkspace: !isPinnedWorkspace(state.workspace) ? state.workspace : state.previousWorkspace,
             workspace: input.subject,
             active: undefined,
             // Clear history when switching workspaces.
@@ -105,10 +131,10 @@ export default Capability.makeModule(
       // RevertWorkspace
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.RevertWorkspace,
+        operation: LayoutOperation.RevertWorkspace,
         handler: Effect.fnUntraced(function* () {
           const state = getState();
-          yield* Operation.invoke(Common.LayoutOperation.SwitchWorkspace, {
+          yield* Operation.invoke(LayoutOperation.SwitchWorkspace, {
             subject: state.previousWorkspace,
           });
         }),
@@ -118,17 +144,16 @@ export default Capability.makeModule(
       // Open
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.Open,
+        operation: LayoutOperation.Open,
         handler: Effect.fnUntraced(function* (input) {
+          const id = input.subject[0];
           updateState((state) => {
-            // Push current active to history if it exists.
             const newHistory = state.active ? [...state.history, state.active] : state.history;
-            // Limit history length to prevent memory issues.
             const trimmedHistory =
               newHistory.length > MAX_HISTORY_LENGTH ? newHistory.slice(-MAX_HISTORY_LENGTH) : newHistory;
             return {
               ...state,
-              active: input.subject[0],
+              active: id,
               history: trimmedHistory,
             };
           });
@@ -139,7 +164,7 @@ export default Capability.makeModule(
       // Close
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.Close,
+        operation: LayoutOperation.Close,
         handler: Effect.fnUntraced(function* () {
           updateState((state) => {
             // Pop from history if available.
@@ -165,7 +190,7 @@ export default Capability.makeModule(
       // Set
       //
       OperationResolver.make({
-        operation: Common.LayoutOperation.Set,
+        operation: LayoutOperation.Set,
         handler: Effect.fnUntraced(function* (input) {
           updateState((state) => ({
             ...state,

package/src/capabilities/react-root/react-root.tsx

@@ -5,14 +5,14 @@
 import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capability, Common } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
 
 import { SimpleLayout } from '../../components';
 import { meta } from '../../meta';
 
 export default Capability.makeModule(() =>
   Effect.succeed(
-    Capability.contributes(Common.Capability.ReactRoot, {
+    Capability.contributes(Capabilities.ReactRoot, {
       id: meta.id,
       root: () => {
         return <SimpleLayout />;

package/src/capabilities/react-surface/react-surface.tsx

@@ -5,10 +5,11 @@
 import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capability, Common } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
 import { Node } from '@dxos/plugin-graph';
 
-import { Home, Workspace } from '../../components';
+import { Home, NavBranch } from '../../components';
 import { meta } from '../../meta';
 
 type SurfaceData = {
@@ -16,24 +17,26 @@ type SurfaceData = {
   properties: Record<string, any>;
 };
 
-const ALLOWED_DISPOSITIONS = ['workspace', 'user-account', 'pin-end'];
+const ALLOWED_DISPOSITIONS = ['workspace', 'user-account', 'pin-end', 'alternate-tree'];
 
 export default Capability.makeModule(() =>
   Effect.succeed(
-    Capability.contributes(Common.Capability.ReactSurface, [
-      Common.createSurface({
-        id: `${meta.id}/home`,
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: `${meta.id}.home`,
         role: 'article',
         filter: (data): data is SurfaceData => data.attendableId === Node.RootId,
         component: () => <Home />,
       }),
-      Common.createSurface({
-        id: `${meta.id}/workspace-article`,
+      Surface.create({
+        id: `${meta.id}.nav-branch`,
         role: 'article',
         position: 'fallback',
-        filter: (data): data is SurfaceData =>
-          ALLOWED_DISPOSITIONS.includes((data.properties as Record<string, any>)?.disposition),
-        component: ({ data }) => <Workspace id={data.attendableId} />,
+        filter: (data): data is SurfaceData => {
+          const props = data.properties as Record<string, any>;
+          return ALLOWED_DISPOSITIONS.includes(props?.disposition) || props?.role === 'branch';
+        },
+        component: ({ data }) => <NavBranch id={data.attendableId} />,
       }),
     ]),
   ),

package/src/capabilities/spotlight-dismiss/spotlight-dismiss.ts

@@ -7,7 +7,7 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Capability, Common } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
 import { log } from '@dxos/log';
 import { isTauri } from '@dxos/util';
 
@@ -76,7 +76,7 @@ export default Capability.makeModule(({ isPopover = false }: SpotlightDismissOpt
     };
     window.addEventListener('keydown', handleKeyDown);
 
-    return Capability.contributes(Common.Capability.Null, null, () =>
+    return Capability.contributes(Capabilities.Null, null, () =>
       Effect.sync(() => {
         focusCleanup?.();
         window.removeEventListener('keydown', handleKeyDown);

package/src/capabilities/state/state.tsx

@@ -5,7 +5,8 @@
 import { Atom } from '@effect-atom/atom-react';
 import * as Effect from 'effect/Effect';
 
-import { Capability, Common } from '@dxos/app-framework';
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities } from '@dxos/app-toolkit';
 import { Node } from '@dxos/plugin-graph';
 
 import { type SimpleLayoutState } from '../../types';
@@ -17,6 +18,8 @@ const defaultState: SimpleLayoutState = {
   previousWorkspace: Node.RootId,
   history: [],
   isPopover: false,
+  companionVariant: undefined,
+  drawerState: 'closed',
 };
 
 export type SimpleLayoutStateOptions = {
@@ -27,7 +30,7 @@ export default Capability.makeModule(({ initialState }: SimpleLayoutStateOptions
   Effect.sync(() => {
     const stateAtom = Atom.make<SimpleLayoutState>({ ...defaultState, ...initialState });
 
-    const layoutAtom = Atom.make((get): Common.Capability.Layout => {
+    const layoutAtom = Atom.make((get): AppCapabilities.Layout => {
       const state = get(stateAtom);
       return {
         mode: 'simple',
@@ -43,7 +46,7 @@ export default Capability.makeModule(({ initialState }: SimpleLayoutStateOptions
 
     return [
       Capability.contributes(SimpleLayoutStateCapability, stateAtom),
-      Capability.contributes(Common.Capability.Layout, layoutAtom),
+      Capability.contributes(AppCapabilities.Layout, layoutAtom),
     ];
   }),
 );

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

@@ -4,77 +4,130 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Capability, Common } from '@dxos/app-framework';
-import { Node } from '@dxos/plugin-graph';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { LayoutOperation, fromUrlPath, getWorkspaceFromPath, toUrlPath } from '@dxos/app-toolkit';
+import { log } from '@dxos/log';
+import { isTauri } from '@dxos/util';
 
 import { type SimpleLayoutState, SimpleLayoutState as SimpleLayoutStateCapability } from '../../types';
 
 /**
  * URL handler for simple layout that syncs browser URL with layout state.
- * URL format: /{workspace} or /{workspace}/{active}
- * Root is represented as / or /root.
+ * URL paths map directly to qualified graph IDs with the leading `root` segment stripped.
+ * Root is represented as `/`.
+ *
+ * On mobile Tauri, also listens for deep links via the deep-link plugin.
  */
 export default Capability.makeModule(
   Effect.fnUntraced(function* () {
-    const { invokeSync } = yield* Capability.get(Common.Capability.OperationInvoker);
+    const { invokeSync } = yield* Capability.get(Capabilities.OperationInvoker);
 
     /**
-     * Handle navigation events (initial load and popstate).
-     * Parses URL and updates state accordingly.
+     * Handle navigation from a pathname.
+     * Restores the qualified graph ID and dispatches layout operations.
      */
-    const handleNavigation = () => {
-      const pathname = window.location.pathname;
+    const handlePathNavigation = (pathname: string) => {
+      log.info('[UrlHandler] Navigating to path', { pathname });
 
-      // Parse URL segments: /{workspace}/{active}
-      const [_, nextWorkspace, nextActive] = pathname.split('/');
+      const qualifiedId = fromUrlPath(pathname);
+      const workspace = getWorkspaceFromPath(qualifiedId);
 
-      // Determine target workspace (empty or 'root' means Node.RootId).
-      const targetWorkspace = !nextWorkspace || nextWorkspace === 'root' ? Node.RootId : nextWorkspace;
+      invokeSync(LayoutOperation.SwitchWorkspace, { subject: workspace });
 
-      // Navigate via operations (they will update state accordingly).
-      invokeSync(Common.LayoutOperation.SwitchWorkspace, { subject: targetWorkspace });
-      if (nextActive) {
-        invokeSync(Common.LayoutOperation.Open, { subject: [nextActive] });
+      const activeId = qualifiedId !== workspace ? qualifiedId : undefined;
+      if (activeId) {
+        invokeSync(LayoutOperation.Open, { subject: [activeId] });
       }
     };
 
-    // Handle initial URL and listen for browser navigation.
-    yield* Effect.sync(() => handleNavigation());
-    window.addEventListener('popstate', handleNavigation);
+    const onNavigation = handleNavigation(handlePathNavigation);
+
+    yield* Effect.sync(() => onNavigation());
+    window.addEventListener('popstate', onNavigation);
+
+    let unlistenDeepLink: (() => void) | undefined;
+    if (isTauri()) {
+      yield* Effect.tryPromise({
+        try: async () => {
+          const { getCurrent, onOpenUrl } = await import('@tauri-apps/plugin-deep-link');
+
+          const launchUrls = await getCurrent();
+          if (launchUrls && launchUrls.length > 0) {
+            log.info('[UrlHandler] App launched with deep links', { urls: launchUrls });
+            for (const url of launchUrls) {
+              handleDeepLink(url, handlePathNavigation);
+            }
+          }
+
+          unlistenDeepLink = await onOpenUrl((urls) => {
+            log.info('[UrlHandler] Deep links received', { urls });
+            for (const url of urls) {
+              handleDeepLink(url, handlePathNavigation);
+            }
+          });
+
+          log.info('[UrlHandler] Deep link listener initialized');
+        },
+        catch: (error) => {
+          log.warn('[UrlHandler] Failed to initialize deep link listener', { error });
+          return error;
+        },
+      }).pipe(Effect.catchAll(() => Effect.void));
+    }
 
-    // Subscribe to state changes to update the URL.
     let lastWorkspace: string | undefined;
     let lastActive: string | undefined;
-    const unsubscribe = yield* Common.Capability.subscribeAtom(
-      SimpleLayoutStateCapability,
-      (state: SimpleLayoutState) => {
-        const { workspace, active } = state;
-
-        // Only update URL if relevant state changed.
-        if (workspace !== lastWorkspace || active !== lastActive) {
-          lastWorkspace = workspace;
-          lastActive = active;
-
-          // Build path: root is represented as /, other workspaces as /{workspace}.
-          let path: string;
-          if (workspace === Node.RootId) {
-            path = active ? `/${Node.RootId}/${active}` : '/';
-          } else {
-            path = active ? `/${workspace}/${active}` : `/${workspace}`;
-          }
+    const unsubscribe = yield* Capabilities.subscribeAtom(SimpleLayoutStateCapability, (state: SimpleLayoutState) => {
+      const { workspace, active } = state;
 
-          if (window.location.pathname !== path) {
-            history.pushState(null, '', `${path}${window.location.search}`);
-          }
+      if (workspace !== lastWorkspace || active !== lastActive) {
+        lastWorkspace = workspace;
+        lastActive = active;
+
+        const path = active ? toUrlPath(active) : toUrlPath(workspace);
+        if (window.location.pathname !== path) {
+          history.pushState(null, '', `${path}${window.location.search}`);
         }
-      },
-    );
+      }
+    });
 
-    return Capability.contributes(Common.Capability.Null, null, () =>
+    return Capability.contributes(Capabilities.Null, null, () =>
       Effect.sync(() => {
-        window.removeEventListener('popstate', handleNavigation);
+        window.removeEventListener('popstate', onNavigation);
         unsubscribe();
+        unlistenDeepLink?.();
       }),
     );
   }),
 );
+
+/**
+ * Check if a path is a special redirect path that shouldn't be navigated to.
+ * These paths are handled by other systems (e.g., OAuth).
+ */
+const isRedirectPath = (pathname: string): boolean => pathname.startsWith('/redirect/');
+
+/**
+ * Returns a handler for navigation events (initial load and popstate) that navigates to current pathname.
+ */
+const handleNavigation =
+  (navigate: (pathname: string) => void): (() => void) =>
+  () =>
+    navigate(window.location.pathname);
+
+/**
+ * Handle deep link URL from Tauri. Parses the URL and calls navigate unless it's a redirect path.
+ */
+const handleDeepLink = (urlString: string, navigate: (pathname: string) => void): void => {
+  log.info('[UrlHandler] Deep link received', { url: urlString });
+  try {
+    const url = new URL(urlString);
+    if (isRedirectPath(url.pathname)) {
+      log.info('[UrlHandler] Skipping redirect path (handled elsewhere)', { pathname: url.pathname });
+      return;
+    }
+    navigate(url.pathname);
+  } catch (error) {
+    log.warn('[UrlHandler] Failed to parse deep link URL', { urlString, error });
+  }
+};

package/src/components/ContentError.stories.tsx

@@ -4,28 +4,29 @@
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 
+import { ErrorFallback } from '@dxos/react-ui';
 import { withTheme } from '@dxos/react-ui/testing';
 
 import { translations } from '../translations';
 
-import { ContentError } from './ContentError';
-
 const meta = {
-  title: 'plugins/plugin-simple-layout/ContentError',
-  component: ContentError,
-  decorators: [withTheme],
+  title: 'plugins/plugin-simple-layout/components/ErrorFallback',
+  component: ErrorFallback,
+  decorators: [withTheme()],
   parameters: {
     layout: 'centered',
     translations,
   },
-} satisfies Meta<typeof ContentError>;
+} satisfies Meta<typeof ErrorFallback>;
 
 export default meta;
 
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  args: {},
+  args: {
+    error: new Error('An unexpected error occurred'),
+  },
 };
 
 export const WithError: Story = {

package/src/components/{ContentLoading.stories.tsx → ContentLoading/ContentLoading.stories.tsx}

@@ -9,9 +9,9 @@ import { withTheme } from '@dxos/react-ui/testing';
 import { ContentLoading } from './ContentLoading';
 
 const meta = {
-  title: 'plugins/plugin-simple-layout/ContentLoading',
+  title: 'plugins/plugin-simple-layout/components/ContentLoading',
   component: ContentLoading,
-  decorators: [withTheme],
+  decorators: [withTheme()],
   parameters: {
     layout: 'centered',
   },