@dxos/plugin-deck 0.9.1-main.c7dcc2e112 → 0.9.1-staging.ee54ba693a

package/src/containers/Deck/useDeckPlank.ts

@@ -0,0 +1,219 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback, useEffect, useMemo } from 'react';
+
+import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { type AttentionSigilAction } from '@dxos/app-toolkit/ui';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { Graph, type Node, useActionRunner, useActions, useNode } from '@dxos/plugin-graph';
+import { getLinkedVariant, useAttention } from '@dxos/react-ui-attention';
+
+import { useBreakpoints, useCompanions, useDeckState, useSelectedCompanion, useSelectedCompanionVariant } from '#hooks';
+import { meta } from '#meta';
+import { DeckOperation, type LayoutMode, PLANK_COMPANION_TYPE, type ResolvedPart } from '#types';
+
+/** Sigil-menu dispositions surfaced as plank actions. */
+const PLANK_ACTION_DISPOSITIONS = ['list-item', 'list-item-primary', 'heading-list-item'];
+
+/** Capability flags that gate the plank toolbar controls. */
+export type PlankCapabilities = {
+  deck?: boolean;
+  solo?: boolean;
+  incrementStart?: boolean;
+  incrementEnd?: boolean;
+  fullscreen?: boolean;
+  companion?: boolean;
+};
+
+export type UseDeckPlankOptions = {
+  id: string;
+  /** Resolved part for the primary plank (`solo` | `multi` | `complementary`). */
+  part: ResolvedPart;
+  layoutMode: LayoutMode;
+  /** Ordered active planks (multi mode); enables increment/close-range semantics. */
+  active?: string[];
+  /** Whether the companion pane should be shown for this plank (gated further by attention in multi-mode). */
+  companionShown?: boolean;
+  deckEnabled?: boolean;
+};
+
+export type DeckPlank = {
+  node: Node.Node | undefined;
+  companions: Node.Node[];
+  resolvedCompanionId: string | undefined;
+  currentCompanion: Node.Node | undefined;
+  hasCompanion: boolean;
+  /** Splitter orientation for the companion pane (defaults to `horizontal`). */
+  companionOrientation: 'horizontal' | 'vertical';
+  capabilities: PlankCapabilities;
+  /** Grouped sigil-menu actions, or `undefined` when the node is unresolved. */
+  sigilActions: AttentionSigilAction[][] | undefined;
+  popoverAnchorId?: string;
+  scrollIntoView?: string;
+  onAction: (action: AttentionSigilAction) => void;
+  onAdjust: (type: DeckOperation.PartAdjustment) => void;
+  onResize: (size: number) => void;
+  onScrollIntoView: (subject?: string) => void;
+  onUpdateCompanion: (companion: string | null) => void;
+};
+
+/**
+ * Resolves the graph node, companions, capabilities and sigil actions for a deck plank, and exposes the
+ * operation dispatchers that mutate deck layout state. This re-homes the framework wiring that the legacy
+ * `PlankContainer`/`PlankHeading` bundled, so the presentational components stay free of capabilities.
+ */
+export const useDeckPlank = ({
+  id,
+  part,
+  layoutMode,
+  active,
+  companionShown,
+  deckEnabled,
+}: UseDeckPlankOptions): DeckPlank => {
+  const { graph } = useAppGraph();
+  const { invokePromise } = useOperationInvoker();
+  const { state, deck } = useDeckState();
+  const runAction = useActionRunner();
+  const breakpoint = useBreakpoints();
+  const node = useNode(graph, id);
+  // Subscribe reactively to the node's actions: they are loaded asynchronously by `Graph.expand`
+  // below, and the node atom does not re-emit when action edges arrive, so a one-shot read would
+  // leave a freshly-created plank's sigil menu empty until an unrelated re-render.
+  const actions = useActions(graph, node?.id);
+  const companions = useCompanions(id);
+  const { hasAttention } = useAttention(id);
+  const selectedVariant = useSelectedCompanionVariant();
+
+  // The companion is shown when open; in multi mode it attaches only to the attended plank (hidden until
+  // a plank gains attention). Which companion shows follows the globally-selected variant (view state),
+  // falling back to the first when none is stored.
+  const showCompanion = !!companionShown && (layoutMode !== 'multi' || hasAttention);
+  const { companionId } = useSelectedCompanion(companions, showCompanion ? selectedVariant : undefined);
+  const resolvedCompanionId = showCompanion ? companionId : undefined;
+  const currentCompanion = companions.find((companion) => companion.id === resolvedCompanionId);
+  const hasCompanion = !!(resolvedCompanionId && currentCompanion);
+  const companionOrientation = deck.companionOrientation ?? 'horizontal';
+
+  // Ordering within the active stack drives the increment-start/end affordances.
+  const index = active ? active.findIndex((entryId) => entryId === id) : -1;
+  const isOrdered = !!active && index >= 0;
+  const canIncrementStart = isOrdered && index > 0;
+  const canIncrementEnd = isOrdered && index < (active?.length ?? 1) - 1;
+
+  const isCompanionNode = node?.type === PLANK_COMPANION_TYPE;
+  const capabilities = useMemo<PlankCapabilities>(
+    () => ({
+      deck: deckEnabled ?? true,
+      solo: breakpoint !== 'mobile' && (part === 'solo' || part === 'multi'),
+      incrementStart: canIncrementStart,
+      incrementEnd: canIncrementEnd,
+      fullscreen: !isCompanionNode,
+      // Offer to open the companion (solo, or the attended plank in multi) when one exists and isn't shown.
+      companion: !isCompanionNode && companions.length > 0 && !hasCompanion && (layoutMode !== 'multi' || hasAttention),
+    }),
+    [
+      deckEnabled,
+      breakpoint,
+      part,
+      canIncrementStart,
+      canIncrementEnd,
+      isCompanionNode,
+      layoutMode,
+      companions.length,
+      hasCompanion,
+      hasAttention,
+    ],
+  );
+
+  // Load the node's child actions so the sigil menu is populated.
+  useEffect(() => {
+    const frame = requestAnimationFrame(() => {
+      if (node) {
+        void Graph.expand(graph, node.id, 'child');
+      }
+    });
+
+    return () => cancelAnimationFrame(frame);
+  }, [graph, node]);
+
+  const variant = isCompanionNode ? getLinkedVariant(id) : undefined;
+  const sigilActions = useMemo<AttentionSigilAction[][] | undefined>(() => {
+    if (!node) {
+      return undefined;
+    }
+    if (variant) {
+      return [];
+    }
+
+    return [actions.filter((action) => PLANK_ACTION_DISPOSITIONS.includes(action.properties.disposition))].filter(
+      (group) => group.length > 0,
+    );
+  }, [actions, node, variant]);
+
+  const onAction = useCallback(
+    (action: AttentionSigilAction) => {
+      // Only actions whose `data` is a function are runnable graph actions; the menu-action view type
+      // (AttentionSigilAction) is widened, so narrow at this runtime-checked boundary.
+      if (typeof action.data === 'function') {
+        void runAction(action as Node.Action, { parent: node, caller: meta.profile.key });
+      }
+    },
+    [node, runAction],
+  );
+
+  const onAdjust = useCallback(
+    (type: DeckOperation.PartAdjustment) => {
+      if (type === 'close') {
+        if (part === 'complementary') {
+          return invokePromise(LayoutOperation.UpdateComplementary, { state: 'collapsed' });
+        }
+        if (active) {
+          // Close the plank and everything to its right (stack pop).
+          const closeIndex = active.indexOf(id);
+          const toClose = closeIndex !== -1 ? active.slice(closeIndex) : [id];
+          return invokePromise(LayoutOperation.Close, { subject: toClose });
+        }
+        return invokePromise(LayoutOperation.Close, { subject: [id] });
+      }
+
+      return invokePromise(DeckOperation.Adjust, { type, id });
+    },
+    [invokePromise, part, active, id],
+  );
+
+  const onResize = useCallback(
+    (size: number) => invokePromise(DeckOperation.UpdatePlankSize, { id, size }),
+    [invokePromise, id],
+  );
+
+  const onScrollIntoView = useCallback(
+    (subject?: string) => invokePromise(LayoutOperation.ScrollIntoView, { subject }),
+    [invokePromise],
+  );
+
+  const onUpdateCompanion = useCallback(
+    (companion: string | null) => invokePromise(LayoutOperation.UpdateCompanion, { subject: companion }),
+    [invokePromise],
+  );
+
+  return {
+    node,
+    companions,
+    resolvedCompanionId,
+    currentCompanion,
+    hasCompanion,
+    companionOrientation,
+    capabilities,
+    sigilActions,
+    popoverAnchorId: state.popoverAnchorId,
+    scrollIntoView: state.scrollIntoView,
+    onAction,
+    onAdjust,
+    onResize,
+    onScrollIntoView,
+    onUpdateCompanion,
+  };
+};

package/src/containers/DeckLayout/DeckLayout.stories.tsx

@@ -17,10 +17,12 @@ import { GraphBuilder, Node, NodeMatcher, useConnections } from '@dxos/plugin-gr
 import { corePlugins } from '@dxos/plugin-testing';
 import { random } from '@dxos/random';
 import { useAsyncEffect } from '@dxos/react-hooks';
-import { Icon, List, ListItem, Panel } from '@dxos/react-ui';
+import { Panel } from '@dxos/react-ui';
 import { linkedSegment } from '@dxos/react-ui-attention';
+import { Listbox } from '@dxos/react-ui-list';
 import { Syntax } from '@dxos/react-ui-syntax-highlighter';
 import { Loading, withLayout } from '@dxos/react-ui/testing';
+import { Position } from '@dxos/util';
 
 import { OperationHandler } from '#capabilities';
 import { meta as pluginMeta } from '#meta';
@@ -28,11 +30,11 @@ import { translations } from '#translations';
 import {
   DeckCapabilities,
   type EphemeralDeckState,
+  PLANK_COMPANION_TYPE,
   type Settings,
   type StoredDeckState,
   defaultDeck,
   getMode,
-  PLANK_COMPANION_TYPE,
 } from '#types';
 
 import { DeckLayout } from './DeckLayout';
@@ -245,7 +247,7 @@ const TestPlugin = Plugin.define(pluginMeta).pipe(
                 label: 'Companion Alpha',
                 icon: 'ph--sidebar--regular',
                 data: { variant: 'alpha', parentId: node.id },
-                position: 'first',
+                position: Position.first,
               }),
               AppNode.makeCompanion({
                 id: linkedSegment('beta'),
@@ -276,24 +278,23 @@ const NavContainer = forwardRef<HTMLDivElement, NavContainerProps>((_props, forw
 
   return (
     <div className='dx-container overflow-y-auto p-2' ref={forwardedRef}>
-      <List>
-        {items.map((node) => (
-          <ListItem.Root
-            key={node.id}
-            classNames={activeSet.has(node.id) ? 'bg-current-surface' : undefined}
-            onClick={() => void invokePromise(LayoutOperation.Set, { subject: [node.id] })}
-          >
-            {node.properties.icon && (
-              <ListItem.Endcap>
-                <Icon icon={node.properties.icon} />
-              </ListItem.Endcap>
-            )}
-            <ListItem.Heading classNames='cursor-pointer'>
-              {typeof node.properties.label === 'string' ? node.properties.label : node.id}
-            </ListItem.Heading>
-          </ListItem.Root>
-        ))}
-      </List>
+      <Listbox.Root>
+        <Listbox.Content aria-label='Navigation'>
+          {items.map((node) => (
+            <Listbox.Item
+              key={node.id}
+              id={node.id}
+              classNames={activeSet.has(node.id) ? 'bg-current-surface' : undefined}
+              onClick={() => void invokePromise(LayoutOperation.Set, { subject: [node.id] })}
+            >
+              <Listbox.ItemContent
+                icon={node.properties.icon}
+                title={typeof node.properties.label === 'string' ? node.properties.label : node.id}
+              />
+            </Listbox.Item>
+          ))}
+        </Listbox.Content>
+      </Listbox.Root>
     </div>
   );
 });
@@ -312,36 +313,22 @@ const ItemComponent = ({ id }: ItemComponentProps) => {
   );
 
   return (
-    <List>
-      {items.map((node) => {
-        const open = () =>
-          void invokePromise(LayoutOperation.Open, { subject: [node.id], pivotId: id, navigation: 'immediate' });
-        return (
-          <ListItem.Root
-            key={node.id}
-            classNames='dx-hover cursor-pointer'
-            role='button'
-            tabIndex={0}
-            onClick={open}
-            onKeyDown={(event) => {
-              if (event.key === 'Enter' || event.key === ' ') {
-                event.preventDefault();
-                open();
-              }
-            }}
-          >
-            {node.properties.icon && (
-              <ListItem.Endcap>
-                <Icon icon={node.properties.icon} size={4} />
-              </ListItem.Endcap>
-            )}
-            <ListItem.Heading classNames='truncate'>
-              {typeof node.properties.label === 'string' ? node.properties.label : node.id}
-            </ListItem.Heading>
-          </ListItem.Root>
-        );
-      })}
-    </List>
+    <Listbox.Root>
+      <Listbox.Content aria-label='Items'>
+        {items.map((node) => {
+          const open = () =>
+            void invokePromise(LayoutOperation.Open, { subject: [node.id], pivotId: id, navigation: 'immediate' });
+          return (
+            <Listbox.Item key={node.id} id={node.id} classNames='dx-hover cursor-pointer' onClick={open}>
+              <Listbox.ItemContent
+                icon={node.properties.icon}
+                title={typeof node.properties.label === 'string' ? node.properties.label : node.id}
+              />
+            </Listbox.Item>
+          );
+        })}
+      </Listbox.Content>
+    </Listbox.Root>
   );
 };
 

package/src/containers/DeckLayout/Dialog.tsx

@@ -10,7 +10,7 @@ import { AlertDialog, Dialog as NaturalDialog } from '@dxos/react-ui';
 
 import { useDeckState } from '#hooks';
 
-import { PlankErrorFallback } from '../Plank';
+import { PlankErrorFallback } from '../Deck/PlankFallback';
 
 export const Dialog = () => {
   const { state, updateEphemeral } = useDeckState();

package/src/{components → containers}/DeckSettings/DeckSettings.stories.tsx

@@ -11,7 +11,7 @@ import { translations } from '#translations';
 import { DeckSettings } from './DeckSettings';
 
 const meta = {
-  title: 'plugins/plugin-deck/components/DeckSettings',
+  title: 'plugins/plugin-deck/containers/DeckSettings',
   tags: ['settings'],
   component: DeckSettings,
   decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],

package/src/containers/DeckSettings/DeckSettings.tsx

@@ -0,0 +1,42 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { useTranslation } from '@dxos/react-ui';
+import { Form } from '@dxos/react-ui-form';
+
+import { meta } from '#meta';
+import { Settings } from '#types';
+
+const isSocket = !!(globalThis as any).__args;
+
+export type DeckSettingsProps = AppSurface.SettingsProps<Settings.Settings>;
+
+export const DeckSettings = ({ settings, onSettingsChange }: DeckSettingsProps) => {
+  const { t } = useTranslation(meta.profile.key);
+
+  return (
+    <Form.Root
+      variant='settings'
+      schema={Settings.Settings}
+      values={settings}
+      readonly={!onSettingsChange}
+      onValuesChanged={(values) => onSettingsChange?.((current) => ({ ...current, ...values }))}
+    >
+      <Form.Viewport scroll>
+        <Form.Content>
+          <Form.Section title={meta.profile.name ?? meta.profile.key}>
+            <Form.FieldSet
+              filter={(properties) =>
+                isSocket ? properties.filter((property) => property.name !== 'enableNativeRedirect') : properties
+              }
+            />
+          </Form.Section>
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};

package/src/containers/Sidebar/ComplementarySidebar.tsx

@@ -7,7 +7,7 @@ import React, { type MouseEvent, useCallback, useEffect, useMemo, useState } fro
 import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
 import { LayoutOperation } from '@dxos/app-toolkit';
 import { AppSurface } from '@dxos/app-toolkit/ui';
-import { IconButton, type Label, Main, Panel, toLocalizedString, Toolbar, useTranslation } from '@dxos/react-ui';
+import { IconButton, type Label, Main, Panel, Toolbar, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { getLinkedVariant } from '@dxos/react-ui-attention';
 import { Tabs } from '@dxos/react-ui-tabs';
 import { iconSize, mx } from '@dxos/ui-theme';
@@ -17,7 +17,7 @@ import { meta } from '#meta';
 import { getMode } from '#types';
 
 import { layoutAppliesTopbar } from '../../util';
-import { PlankErrorFallback, PlankLoading } from '../Plank';
+import { PlankErrorFallback, PlankLoading } from '../Deck/PlankFallback';
 import { ToggleComplementarySidebarButton } from './SidebarButton';
 
 const label = ['complementary-sidebar.title', { ns: meta.profile.key }] satisfies Label;

package/src/containers/index.ts

@@ -5,7 +5,7 @@
 import { type ComponentType, lazy } from 'react';
 
 export * from './Deck';
-export * from './Plank';
 export * from './Sidebar';
 
 export const DeckLayout: ComponentType<any> = lazy(() => import('./DeckLayout'));
+export const DeckSettings: ComponentType<any> = lazy(() => import('./DeckSettings'));

package/src/hooks/index.ts

@@ -4,8 +4,10 @@
 
 export * from './useBreakpoints';
 export * from './useCompanions';
+export * from './useCompanionSplit';
 export * from './useDeckCompanions';
 export * from './useDeckState';
 export * from './useMainSize';
 export * from './useNodeActionExpander';
 export * from './useSelectedCompanion';
+export * from './useSelectedCompanionVariant';

package/src/hooks/useCompanionSplit.ts

@@ -0,0 +1,78 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { type SplitterOrientation } from '@dxos/react-ui';
+import { type AspectDef, defineViewState, useViewState, useViewStateActions } from '@dxos/react-ui-attention';
+
+import { COMPANION_VIEW_STATE_CONTEXT } from '../util';
+
+/** Companion split point (rem) used until the user resizes a given orientation. */
+export const DEFAULT_COMPANION_SIZE = 30;
+
+/** Trailing delay before a resize is committed to storage (drags fire continuously). */
+const PERSIST_DELAY = 250;
+
+const CompanionSplitSchema = Schema.Struct({
+  horizontal: Schema.optional(Schema.Number),
+  vertical: Schema.optional(Schema.Number),
+}).pipe(Schema.mutable);
+
+export type CompanionSplit = Schema.Schema.Type<typeof CompanionSplitSchema>;
+
+/**
+ * Companion splitter sizes (rem), memoized separately for each orientation so toggling the companion
+ * between side-by-side and stacked restores that orientation's last split point. Stored in the `local`
+ * backend (localStorage, persisted across reloads) via react-ui-attention view state.
+ */
+export const companionSplitAspect: AspectDef<CompanionSplit> = defineViewState<CompanionSplit>({
+  key: 'deck-companion-split',
+  backend: 'local',
+  schema: CompanionSplitSchema,
+  defaultValue: () => ({}),
+});
+
+export type UseCompanionSplit = {
+  /** The remembered split point for the current orientation (or the default). */
+  size: number;
+  onSizeChange: (size: number) => void;
+};
+
+/**
+ * Reads and writes the global companion splitter size keyed by `orientation`. A live size keeps dragging
+ * smooth while the persisted write is debounced (and flushed on unmount) to avoid per-frame storage writes.
+ */
+export const useCompanionSplit = (orientation: SplitterOrientation): UseCompanionSplit => {
+  const split = useViewState(companionSplitAspect, COMPANION_VIEW_STATE_CONTEXT);
+  const { update } = useViewStateActions(companionSplitAspect, COMPANION_VIEW_STATE_CONTEXT);
+  const storedSize = split[orientation] ?? DEFAULT_COMPANION_SIZE;
+
+  // Drive the controlled Splitter from local state so a drag tracks the pointer without a storage
+  // round-trip per frame; reseed when the orientation switches (recall) or storage changes externally.
+  const [liveSize, setLiveSize] = useState(storedSize);
+  useEffect(() => setLiveSize(storedSize), [storedSize, orientation]);
+
+  // Flush the trailing write on unmount so the final size is not dropped inside the debounce window.
+  const pending = useRef<{ timer: ReturnType<typeof setTimeout>; flush: () => void } | undefined>(undefined);
+  useEffect(() => () => pending.current?.flush(), []);
+
+  const onSizeChange = useCallback(
+    (next: number) => {
+      setLiveSize(next);
+      if (pending.current) {
+        clearTimeout(pending.current.timer);
+      }
+      const flush = () => {
+        pending.current = undefined;
+        update((prev) => ({ ...prev, [orientation]: next }));
+      };
+      pending.current = { timer: setTimeout(flush, PERSIST_DELAY), flush };
+    },
+    [update, orientation],
+  );
+
+  return useMemo(() => ({ size: liveSize, onSizeChange }), [liveSize, onSizeChange]);
+};

package/src/hooks/useCompanions.ts

@@ -2,17 +2,49 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useMemo } from 'react';
+import { RegistryContext } from '@effect-atom/atom-react';
+import { useContext, useEffect, useState } from 'react';
 
 import { useAppGraph } from '@dxos/app-toolkit/ui';
-import { useConnections } from '@dxos/plugin-graph';
-import { byPosition } from '@dxos/util';
+import { type Node } from '@dxos/plugin-graph';
+import { Position } from '@dxos/util';
 
 import { PLANK_COMPANION_TYPE } from '#types';
 
-export const useCompanions = (id?: string) => {
+/**
+ * Companion (child) nodes for a plank.
+ *
+ * The node's child-connections atom is read in a commit-phase effect rather than during render.
+ * Subscribing to it during render (via `useConnections`/`useAtomValue`) recomputes the shared atom and
+ * synchronously notifies its other subscribers — notably navtree items rendering the same node — which
+ * surfaces as a React "cannot update a component while rendering a different component" warning. Reading
+ * it from an effect defers that notification to the commit phase where cross-component updates are allowed.
+ */
+export const useCompanions = (id?: string): Node.Node[] => {
   const { graph } = useAppGraph();
-  const nodes = useConnections(graph, id, 'child');
-  const companions = nodes.filter((node) => node.type === PLANK_COMPANION_TYPE);
-  return useMemo(() => companions.toSorted((a, b) => byPosition(a.properties, b.properties)), [companions]);
+  const registry = useContext(RegistryContext);
+  const [companions, setCompanions] = useState<Node.Node[]>([]);
+
+  useEffect(() => {
+    if (!id) {
+      setCompanions([]);
+      return;
+    }
+
+    const atom = graph.connections(id, 'child');
+    const update = () => {
+      const next = registry
+        .get(atom)
+        .filter((node) => node.type === PLANK_COMPANION_TYPE)
+        .toSorted((a, b) => Position.compare(a.properties, b.properties));
+      setCompanions((prev) =>
+        prev.length === next.length && prev.every((node, index) => node === next[index]) ? prev : next,
+      );
+    };
+
+    update();
+    return registry.subscribe(atom, update);
+  }, [graph, registry, id]);
+
+  return companions;
 };

package/src/hooks/useDeckCompanions.ts

@@ -6,7 +6,7 @@ import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { Node, type Node as NodeType } from '@dxos/plugin-graph';
 import { useConnections } from '@dxos/plugin-graph';
 import { type Label } from '@dxos/ui-types/translations';
-import { type Position, byPosition } from '@dxos/util';
+import { Position } from '@dxos/util';
 
 import { DECK_COMPANION_TYPE } from '#types';
 
@@ -18,7 +18,7 @@ export type DeckCompanion = NodeType.Node<
     // TODO(burdon): Scroll area should be controlled by surface.
     /** If true, the panel will not be wrapped in a scroll area. */
     fixed?: boolean;
-    position?: Position;
+    position?: Position.Position;
     joyride?: string;
   }
 >;
@@ -27,5 +27,5 @@ export const useDeckCompanions = (): DeckCompanion[] => {
   const { graph } = useAppGraph();
   const connections = useConnections(graph, Node.RootId, 'child');
   const companions = connections.filter((node) => node.type === DECK_COMPANION_TYPE) as DeckCompanion[];
-  return companions.toSorted((a, b) => byPosition(a.properties, b.properties));
+  return companions.toSorted((a, b) => Position.compare(a.properties, b.properties));
 };

package/src/hooks/useDeckState.ts

@@ -11,9 +11,9 @@ import { invariant } from '@dxos/invariant';
 
 import {
   DeckCapabilities,
-  type EphemeralDeckState,
   type DeckPluginState,
   type DeckState,
+  type EphemeralDeckState,
   type StoredDeckState,
 } from '#types';
 

package/src/hooks/useSelectedCompanionVariant.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useViewState } from '@dxos/react-ui-attention';
+
+import { COMPANION_VIEW_STATE_CONTEXT, companionVariantAspect } from '../util';
+
+/**
+ * Reads the globally-selected companion variant (persisted via view state) so reopening the companion
+ * restores the last-selected tab rather than resetting to the first.
+ */
+export const useSelectedCompanionVariant = (): string | undefined =>
+  useViewState(companionVariantAspect, COMPANION_VIEW_STATE_CONTEXT).variant;

package/src/index.ts

@@ -4,3 +4,10 @@
 
 export * from './meta';
 export * from './types';
+// Companion selection view-state aspect — public so consumers (e.g. plugin-assistant) can read the
+// globally-selected companion variant that used to live on `DeckState.companionVariant`.
+export {
+  COMPANION_VIEW_STATE_CONTEXT,
+  type CompanionSelection,
+  companionVariantAspect,
+} from './util/companion-view-state';