@dxos/plugin-deck 0.8.4-main.b97322e → 0.8.4-main.bc674ce

package/src/components/Sidebar/ComplementarySidebar.tsx

@@ -12,29 +12,38 @@ import React, {
   useState,
 } from 'react';
 
-import { LayoutAction, Surface, createIntent, useCapability, useIntentDispatcher } from '@dxos/app-framework';
-import { Main, useTranslation, toLocalizedString, IconButton, type Label } from '@dxos/react-ui';
+import { Common } from '@dxos/app-framework';
+import { Surface, useOperationInvoker } from '@dxos/app-framework/react';
+import { IconButton, type Label, Main, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { Tabs } from '@dxos/react-ui-tabs';
-
-import { ToggleComplementarySidebarButton } from './SidebarButton';
-import { DeckCapabilities } from '../../capabilities';
-import { type DeckCompanion, getCompanionId, useDeckCompanions, useBreakpoints, useHoistStatusbar } from '../../hooks';
-import { DECK_PLUGIN } from '../../meta';
+import { mx } from '@dxos/ui-theme';
+
+import {
+  type DeckCompanion,
+  getCompanionId,
+  useBreakpoints,
+  useDeckCompanions,
+  useDeckState,
+  useHoistStatusbar,
+} from '../../hooks';
+import { meta } from '../../meta';
 import { getMode } from '../../types';
 import { layoutAppliesTopbar } from '../../util';
 import { PlankContentError, PlankLoading } from '../Plank';
 
-const label = ['complementary sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
+import { ToggleComplementarySidebarButton } from './SidebarButton';
+
+const label = ['complementary sidebar title', { ns: meta.id }] satisfies Label;
 
 export type ComplementarySidebarProps = {
   current?: string;
 };
 
 export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) => {
-  const { t } = useTranslation(DECK_PLUGIN);
-  const { dispatchPromise: dispatch } = useIntentDispatcher();
-  const layout = useCapability(DeckCapabilities.MutableDeckState);
-  const layoutMode = getMode(layout.deck);
+  const { t } = useTranslation(meta.id);
+  const { invokeSync } = useOperationInvoker();
+  const { state, deck, updateState } = useDeckState();
+  const layoutMode = getMode(deck);
   const breakpoint = useBreakpoints();
   const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
   const hoistStatusbar = useHoistStatusbar(breakpoint, layoutMode);
@@ -52,14 +61,17 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
     (event: MouseEvent) => {
       const nextValue = event.currentTarget.getAttribute('data-value') as string;
       if (nextValue === activeId) {
-        layout.complementarySidebarState = layout.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded';
+        updateState((s) => ({
+          ...s,
+          complementarySidebarState: s.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded',
+        }));
       } else {
         setInternalValue(nextValue);
-        layout.complementarySidebarState = 'expanded';
-        void dispatch(createIntent(LayoutAction.UpdateComplementary, { part: 'complementary', subject: nextValue }));
+        updateState((s) => ({ ...s, complementarySidebarState: 'expanded' }));
+        invokeSync(Common.LayoutOperation.UpdateComplementary, { subject: nextValue });
       }
     },
-    [layout, activeId, dispatch],
+    [state.complementarySidebarState, activeId, invokeSync, updateState],
   );
 
   const data = useMemo(
@@ -73,11 +85,9 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
 
   useEffect(() => {
     if (!activeId) {
-      void dispatch(
-        createIntent(LayoutAction.UpdateComplementary, { part: 'complementary', options: { state: 'collapsed' } }),
-      );
+      invokeSync(Common.LayoutOperation.UpdateComplementary, { state: 'collapsed' });
     }
-  }, [activeId, dispatch]);
+  }, [activeId, invokeSync]);
 
   return (
     <Main.ComplementarySidebar
@@ -90,7 +100,11 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
       <Tabs.Root orientation='vertical' verticalVariant='stateless' value={internalValue} classNames='contents'>
         <div
           role='none'
-          className='absolute z-[1] inset-block-0 inline-end-0 !is-[--r0-size] pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)] border-is border-subduedSeparator grid grid-cols-1 grid-rows-[1fr_min-content] bg-baseSurface contain-layout app-drag'
+          className={mx(
+            'absolute z-[1] inset-block-0 inline-end-0 !is-[--r0-size]',
+            'pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)] border-is border-subduedSeparator',
+            'grid grid-cols-1 grid-rows-[1fr_min-content] bg-baseSurface contain-layout app-drag',
+          )}
         >
           <Tabs.Tablist classNames='grid grid-cols-1 auto-rows-[--rail-action] p-1 gap-1 !overflow-y-auto'>
             {companions.map((companion) => (
@@ -98,13 +112,12 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
                 <IconButton
                   label={toLocalizedString(companion.properties.label, t)}
                   icon={companion.properties.icon}
-                  size={5}
                   iconOnly
                   tooltipSide='left'
                   data-value={getCompanionId(companion.id)}
                   variant={
                     activeId === getCompanionId(companion.id)
-                      ? layout.complementarySidebarState === 'expanded'
+                      ? state.complementarySidebarState === 'expanded'
                         ? 'primary'
                         : 'default'
                       : 'ghost'
@@ -128,8 +141,12 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
             <Tabs.Tabpanel
               key={getCompanionId(companion.id)}
               value={getCompanionId(companion.id)}
-              classNames='absolute data-[state="inactive"]:-z-[1] inset-block-0 inline-start-0 is-[calc(100%-var(--r0-size))] lg:is-[--r1-size] grid grid-cols-1 grid-rows-[var(--rail-size)_1fr_min-content] pbs-[env(safe-area-inset-top)]'
-              {...(layout.complementarySidebarState !== 'expanded' && { inert: 'true' })}
+              classNames={[
+                'absolute data-[state="inactive"]:-z-[1] overflow-hidden',
+                'inset-block-0 inline-start-0 is-[calc(100%-var(--r0-size))] lg:is-[--r1-size]',
+                'grid grid-cols-1 grid-rows-[var(--rail-size)_1fr_min-content] pbs-[env(safe-area-inset-top)]',
+              ]}
+              {...(state.complementarySidebarState !== 'expanded' && { inert: true })}
             >
               <ComplementarySidebarPanel
                 companion={companion}
@@ -154,12 +171,8 @@ type ComplementarySidebarPanelProps = {
   hoistStatusbar: boolean;
 };
 
-const ScrollArea = ({ children }: PropsWithChildren) => {
-  return <div className='flex flex-col grow overflow-x-hidden overflow-y-auto scrollbar-thin'>{children}</div>;
-};
-
 const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }: ComplementarySidebarPanelProps) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { t } = useTranslation(meta.id);
 
   if (getCompanionId(companion.id) !== activeId && !data) {
     return null;
@@ -169,9 +182,20 @@ const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }
 
   return (
     <>
-      <h2 className='flex items-center pli-2 border-subduedSeparator border-be font-medium'>
-        {toLocalizedString(companion.properties.label, t)}
-      </h2>
+      <div role='none' className='flex items-center p-1 gap-1 border-be border-subduedSeparator'>
+        <IconButton
+          label={toLocalizedString(companion.properties.label, t)}
+          icon={companion.properties.icon}
+          iconOnly
+          tooltipSide='left'
+          data-value={getCompanionId(companion.id)}
+          classNames='bs-10 is-10'
+          variant='default'
+        />
+        <div role='none' className='pli-1'>
+          {toLocalizedString(companion.properties.label, t)}
+        </div>
+      </div>
       <Wrapper>
         <Surface
           role={`deck-companion--${getCompanionId(companion.id)}`}
@@ -191,3 +215,7 @@ const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }
     </>
   );
 };
+
+const ScrollArea = ({ children }: PropsWithChildren) => {
+  return <div className='flex flex-col grow overflow-x-hidden overflow-y-auto scrollbar-thin'>{children}</div>;
+};

package/src/components/Sidebar/Sidebar.tsx

@@ -4,19 +4,19 @@
 
 import React, { useMemo } from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/react';
 import { type Label, Main } from '@dxos/react-ui';
 
-import { DeckCapabilities } from '../../capabilities';
-import { useBreakpoints, useHoistStatusbar } from '../../hooks';
-import { DECK_PLUGIN } from '../../meta';
+import { useBreakpoints, useDeckState, useHoistStatusbar } from '../../hooks';
+import { meta } from '../../meta';
 import { getMode } from '../../types';
 import { layoutAppliesTopbar } from '../../util';
 
-const label = ['sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
+const label = ['sidebar title', { ns: meta.id }] satisfies Label;
 
 export const Sidebar = () => {
-  const { popoverAnchorId, activeDeck: current, deck } = useCapability(DeckCapabilities.DeckState);
+  const { state, deck } = useDeckState();
+  const { popoverAnchorId, activeDeck: current } = state;
   const breakpoint = useBreakpoints();
   const layoutMode = getMode(deck);
   const topbar = layoutAppliesTopbar(breakpoint, layoutMode);

package/src/components/Sidebar/SidebarButton.tsx

@@ -4,45 +4,56 @@
 
 import React, { useCallback } from 'react';
 
-import { createIntent, LayoutAction, useCapability, useIntentDispatcher } from '@dxos/app-framework';
+import { Common } from '@dxos/app-framework';
+import { useOperationInvoker } from '@dxos/app-framework/react';
 import { IconButton, type IconButtonProps, type ThemedClassName, useTranslation } from '@dxos/react-ui';
 
-import { DeckCapabilities } from '../../capabilities';
-import { useDeckCompanions, getCompanionId } from '../../hooks';
-import { DECK_PLUGIN } from '../../meta';
+import { getCompanionId, useDeckCompanions, useDeckState } from '../../hooks';
+import { meta } from '../../meta';
 
 export const ToggleSidebarButton = ({
   classNames,
   variant = 'ghost',
 }: ThemedClassName<Pick<IconButtonProps, 'variant'>>) => {
-  const layoutContext = useCapability(DeckCapabilities.MutableDeckState);
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { state, updateState } = useDeckState();
+  const { t } = useTranslation(meta.id);
+
+  const handleClick = useCallback(() => {
+    updateState((s) => ({
+      ...s,
+      sidebarState: s.sidebarState === 'expanded' ? 'collapsed' : 'expanded',
+    }));
+  }, [updateState]);
+
   return (
     <IconButton
       variant={variant}
-      iconOnly
       icon='ph--sidebar--regular'
+      iconOnly
       size={4}
       label={t('open navigation sidebar label')}
-      onClick={() =>
-        (layoutContext.sidebarState = layoutContext.sidebarState === 'expanded' ? 'collapsed' : 'expanded')
-      }
+      onClick={handleClick}
       classNames={classNames}
     />
   );
 };
 
 export const CloseSidebarButton = () => {
-  const layoutContext = useCapability(DeckCapabilities.MutableDeckState);
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { updateState } = useDeckState();
+  const { t } = useTranslation(meta.id);
+
+  const handleClick = useCallback(() => {
+    updateState((s) => ({ ...s, sidebarState: 'collapsed' }));
+  }, [updateState]);
+
   return (
     <IconButton
       variant='ghost'
-      iconOnly
       icon='ph--caret-line-left--regular'
+      iconOnly
       size={4}
       label={t('close navigation sidebar label')}
-      onClick={() => (layoutContext.sidebarState = 'collapsed')}
+      onClick={handleClick}
       classNames='rounded-none pli-1 dx-focus-ring-inset pie-[max(.5rem,env(safe-area-inset-left))]'
     />
   );
@@ -53,35 +64,31 @@ export const ToggleComplementarySidebarButton = ({
   classNames,
   current,
 }: ThemedClassName<{ inR0?: boolean; current?: string }>) => {
-  const { dispatchPromise: dispatch } = useIntentDispatcher();
-  const layoutContext = useCapability(DeckCapabilities.MutableDeckState);
-  const { t } = useTranslation(DECK_PLUGIN);
+  const { invokeSync } = useOperationInvoker();
+  const { state, updateState } = useDeckState();
+  const { t } = useTranslation(meta.id);
 
   const companions = useDeckCompanions();
-  const handleClick = useCallback(async () => {
-    layoutContext.complementarySidebarState =
-      layoutContext.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded';
-    const firstCompanion = companions[0];
-    if (layoutContext.complementarySidebarState === 'expanded' && !current && firstCompanion) {
-      await dispatch(
-        createIntent(LayoutAction.UpdateComplementary, {
-          part: 'complementary',
-          subject: getCompanionId(firstCompanion.id),
-        }),
-      );
+  const handleClick = useCallback(() => {
+    const nextState = state.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded';
+    updateState((s) => ({ ...s, complementarySidebarState: nextState }));
+
+    const subject = state.complementarySidebarPanel ?? (companions[0] && getCompanionId(companions[0].id));
+    if (nextState === 'expanded' && !current && subject) {
+      invokeSync(Common.LayoutOperation.UpdateComplementary, { subject });
     }
-  }, [layoutContext, current, companions, dispatch]);
+  }, [state, updateState, current, companions, invokeSync]);
 
   return (
     <IconButton
-      iconOnly
-      onClick={handleClick}
       variant='ghost'
-      label={t('open complementary sidebar label')}
       classNames={['[&>svg]:-scale-x-100', classNames]}
       icon='ph--sidebar-simple--regular'
+      iconOnly
+      label={t('open complementary sidebar label')}
       size={inR0 ? 5 : 4}
       tooltipSide={inR0 ? 'left' : undefined}
+      onClick={handleClick}
     />
   );
 };

package/src/components/fragments.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 export const soloInlinePadding =
   'pis-[calc(env(safe-area-inset-left)+.25rem)] pie-[calc(env(safe-area-inset-left)+.25rem)]';

package/src/hooks/index.ts

@@ -5,6 +5,7 @@
 export * from './useBreakpoints';
 export * from './useCompanions';
 export * from './useDeckCompanions';
+export * from './useDeckState';
 export * from './useHoistStatusbar';
 export * from './useMainSize';
 export * from './useNodeActionExpander';

package/src/hooks/useCompanions.ts

@@ -4,7 +4,7 @@
 
 import { useMemo } from 'react';
 
-import { useAppGraph } from '@dxos/app-framework';
+import { useAppGraph } from '@dxos/app-framework/react';
 import { useConnections } from '@dxos/plugin-graph';
 import { byPosition } from '@dxos/util';
 

package/src/hooks/useDeckCompanions.ts

@@ -2,9 +2,11 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type Label, useAppGraph } from '@dxos/app-framework';
-import { ROOT_ID, useConnections, type Node } from '@dxos/plugin-graph';
-import { byPosition, type Position } from '@dxos/util';
+import { useAppGraph } from '@dxos/app-framework/react';
+import { Node, type Node as NodeType } from '@dxos/plugin-graph';
+import { useConnections } from '@dxos/plugin-graph';
+import { type Label } from '@dxos/ui-types';
+import { type Position, byPosition } from '@dxos/util';
 
 import { ATTENDABLE_PATH_SEPARATOR, DECK_COMPANION_TYPE } from '../types';
 
@@ -13,7 +15,7 @@ export const getCompanionId = (id: string) => {
   return companionId ?? 'never';
 };
 
-export type DeckCompanion = Node<
+export type DeckCompanion = NodeType.Node<
   any,
   {
     label: Label;
@@ -27,7 +29,7 @@ export type DeckCompanion = Node<
 
 export const useDeckCompanions = (): DeckCompanion[] => {
   const { graph } = useAppGraph();
-  const connections = useConnections(graph, ROOT_ID);
+  const connections = useConnections(graph, Node.RootId);
   const companions = connections.filter((node) => node.type === DECK_COMPANION_TYPE) as DeckCompanion[];
   return companions.toSorted((a, b) => byPosition(a.properties, b.properties));
 };

package/src/hooks/useDeckState.ts

@@ -0,0 +1,82 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useAtomValue } from '@effect-atom/atom-react';
+import { useCallback, useMemo } from 'react';
+
+import { Common } from '@dxos/app-framework';
+import { useCapability } from '@dxos/app-framework/react';
+import { invariant } from '@dxos/invariant';
+
+import {
+  DeckCapabilities,
+  type DeckEphemeralStateProps,
+  type DeckPluginState,
+  type DeckState,
+  type DeckStateProps,
+} from '../types';
+
+export type DeckStateHook = {
+  /** Combined state value (reactive). Includes both persisted and ephemeral state. */
+  state: DeckPluginState;
+  /** The active deck, computed from decks[activeDeck]. */
+  deck: DeckState;
+  /** Update persisted state. */
+  updateState: (fn: (current: DeckStateProps) => DeckStateProps) => void;
+  /** Update ephemeral state. */
+  updateEphemeral: (fn: (current: DeckEphemeralStateProps) => DeckEphemeralStateProps) => void;
+};
+
+/**
+ * Hook to access the deck plugin state reactively.
+ * Returns the combined state, the active deck, and update functions for each atom.
+ */
+export const useDeckState = (): DeckStateHook => {
+  const registry = useCapability(Common.Capability.AtomRegistry);
+  const stateAtom = useCapability(DeckCapabilities.State);
+  const ephemeralAtom = useCapability(DeckCapabilities.EphemeralState);
+
+  const persistedState = useAtomValue(stateAtom);
+  const ephemeralState = useAtomValue(ephemeralAtom);
+
+  // Compute deck from decks[activeDeck] to ensure it's always current.
+  const deck = useMemo(() => {
+    const d = persistedState.decks[persistedState.activeDeck];
+    invariant(d, `Deck not found: ${persistedState.activeDeck}`);
+    return d;
+  }, [persistedState.decks, persistedState.activeDeck]);
+
+  // Combine persisted and ephemeral state into a unified view.
+  const state = useMemo(
+    (): DeckPluginState => ({
+      ...persistedState,
+      ...ephemeralState,
+    }),
+    [persistedState, ephemeralState],
+  );
+
+  const updateState = useCallback(
+    (fn: (current: DeckStateProps) => DeckStateProps) => {
+      registry.set(stateAtom, fn(registry.get(stateAtom)));
+    },
+    [registry, stateAtom],
+  );
+
+  const updateEphemeral = useCallback(
+    (fn: (current: DeckEphemeralStateProps) => DeckEphemeralStateProps) => {
+      registry.set(ephemeralAtom, fn(registry.get(ephemeralAtom)));
+    },
+    [registry, ephemeralAtom],
+  );
+
+  return useMemo(
+    () => ({
+      state,
+      deck,
+      updateState,
+      updateEphemeral,
+    }),
+    [state, deck, updateState, updateEphemeral],
+  );
+};

package/src/hooks/useHoistStatusbar.ts

@@ -4,16 +4,15 @@
 
 import { useMemo } from 'react';
 
-import { Capabilities, useCapability } from '@dxos/app-framework';
+import { useAtomCapability } from '@dxos/app-framework/react';
 import { useThemeContext } from '@dxos/react-ui';
 
-import { DECK_PLUGIN } from '../meta';
-import type { DeckSettingsProps, LayoutMode } from '../types';
+import { DeckCapabilities, type LayoutMode } from '../types';
 
 export const useHoistStatusbar = (breakpoint: string, layoutMode?: LayoutMode): boolean => {
-  const enableStatusbar = useCapability(Capabilities.SettingsStore).getStore<DeckSettingsProps>(DECK_PLUGIN)!.value
-    .enableStatusbar;
   const { safeAreaPadding } = useThemeContext();
+  const enableStatusbar = useAtomCapability(DeckCapabilities.Settings).enableStatusbar;
+
   return useMemo(() => {
     return (
       breakpoint === 'desktop' &&

package/src/hooks/useNodeActionExpander.ts

@@ -4,14 +4,14 @@
 
 import { useEffect } from 'react';
 
-import { getGraph, type Node } from '@dxos/plugin-graph';
+import { Graph, type Node } from '@dxos/plugin-graph';
 
-export const useNodeActionExpander = (node?: Node) => {
+export const useNodeActionExpander = (node?: Node.Node) => {
   useEffect(() => {
     if (node) {
       const frame = requestAnimationFrame(() => {
-        const graph = getGraph(node);
-        void graph.expand(node.id);
+        const graph = Graph.getGraph(node);
+        void Graph.expand(graph, node.id);
       });
       return () => cancelAnimationFrame(frame);
     }

package/src/index.ts

@@ -2,8 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export { DeckCapabilities } from './capabilities';
-export { DeckEvents } from './events';
+export { DeckCapabilities, DeckEvents } from './types';
 export * from './DeckPlugin';
 export * from './meta';
 export { useCompanions } from './hooks';

package/src/meta.ts

@@ -2,12 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-export const DECK_PLUGIN = 'dxos.org/plugin/deck' as const;
-
-export const meta: PluginMeta = {
-  id: DECK_PLUGIN,
+export const meta: Plugin.Meta = {
+  id: 'dxos.org/plugin/deck',
   name: 'Layout',
+  description: trim`
+    Flexible layout system for arranging workspace views in tabs, splits, and panels.
+    Customize your workspace organization with drag-and-drop layout management.
+  `,
   icon: 'ph--layout--regular',
 };

package/src/translations.ts

@@ -11,6 +11,7 @@ export const translations = [
     'en-US': {
       [meta.id]: {
         'plugin name': 'Deck',
+        'settings title': 'Deck settings',
         'main header label': 'Main header',
         'open navigation sidebar label': 'Open sidebar',
         'collapse navigation sidebar label': 'Minimize sidebar',
@@ -33,7 +34,7 @@ export const translations = [
         'undo action label': 'Undo',
         'undo action alt': 'Undo previous action',
         'undo close label': 'Dismiss',
-        'error fallback message': 'Unable to open this item',
+        'error fallback message': 'Unable to open this object',
         'plank heading fallback label': 'Untitled',
         'actions menu label': 'Options',
         'settings deck label': 'Disable deck',
@@ -58,6 +59,7 @@ export const translations = [
         'settings overscroll none label': 'None',
         'settings enable statusbar label': 'Show status bar',
         'settings enable deck label': 'Enable Deck',
+        'settings encapsulated planks label': 'Encapsulated planks',
         'close current label': 'Close current plank',
         'close others label': 'Close other planks',
         'close all label': 'Close all planks',

package/src/types/capabilities.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { Capability, Common } from '@dxos/app-framework';
+import { invariant } from '@dxos/invariant';
+
+import { meta } from '../meta';
+import { type DeckEphemeralStateProps, type DeckSettingsProps, type DeckState, type DeckStateProps } from '../types';
+
+export namespace DeckCapabilities {
+  export const Settings = Capability.make<Atom.Writable<DeckSettingsProps>>(`${meta.id}/capability/settings`);
+
+  /** Persisted state (stored in KVS/localStorage). */
+  export const State = Capability.make<Atom.Writable<DeckStateProps>>(`${meta.id}/capability/state`);
+
+  /** Transient/ephemeral state (not persisted). */
+  export const EphemeralState = Capability.make<Atom.Writable<DeckEphemeralStateProps>>(
+    `${meta.id}/capability/ephemeral-state`,
+  );
+
+  /** Get the current active deck from state. */
+  export const getDeck = (): Effect.Effect<DeckState, Error, Capability.Service> =>
+    Effect.gen(function* () {
+      const state = yield* Common.Capability.getAtomValue(State);
+      const deck = state.decks[state.activeDeck];
+      invariant(deck, `Deck not found: ${state.activeDeck}`);
+      return deck;
+    });
+}

package/src/types/events.ts

@@ -0,0 +1,20 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ActivationEvent, Common } from '@dxos/app-framework';
+
+import { meta } from '../meta';
+
+import { DeckCapabilities } from './capabilities';
+
+export namespace DeckEvents {
+  export const StateReady: ActivationEvent.ActivationEvent = Common.ActivationEvent.createStateEvent(
+    `${meta.id}/state-ready`,
+  );
+
+  /** Fired when DeckSettings capability is ready. */
+  export const SettingsReady: ActivationEvent.ActivationEvent = Common.ActivationEvent.createSettingsEvent(
+    DeckCapabilities.Settings.identifier,
+  );
+}

package/src/types/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './capabilities';
+export * from './events';
 export * from './schema';