@dxos/plugin-deck 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/containers/Sidebar/SidebarButton.tsx

@@ -17,7 +17,7 @@ export const ToggleSidebarButton = ({
   variant = 'ghost',
 }: ThemedClassName<Pick<IconButtonProps, 'variant'>>) => {
   const { updateState } = useDeckState();
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
 
   const handleClick = useCallback(() => {
     updateState((state) => ({
@@ -41,7 +41,7 @@ export const ToggleSidebarButton = ({
 
 export const CloseSidebarButton = () => {
   const { updateState } = useDeckState();
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
 
   const handleClick = useCallback(() => {
     updateState((state) => ({ ...state, sidebarState: 'collapsed' }));
@@ -67,7 +67,7 @@ export const ToggleComplementarySidebarButton = ({
 }: ThemedClassName<{ inR0?: boolean; current?: string }>) => {
   const { invokePromise } = useOperationInvoker();
   const { state, updateState } = useDeckState();
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
 
   const companions = useDeckCompanions();
   const handleClick = useCallback(() => {

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';

package/src/meta.ts

@@ -3,32 +3,7 @@
 //
 
 import { Plugin } from '@dxos/app-framework';
-import { DXN } from '@dxos/keys';
-import { trim } from '@dxos/util';
 
-export const meta = Plugin.makeMeta({
-  key: DXN.make('org.dxos.plugin.deck'),
-  name: 'Layout',
-  author: 'DXOS',
-  spec: 'PLUGIN.mdl',
-  description: trim`
-    The Deck plugin is the core layout engine for DXOS Composer. It manages the multi-plank
-    workspace (the "deck"), sidebar panels, dialogs, popovers, and toast notifications, giving
-    users a flexible, persistent workspace they can arrange to match their workflow.
+import config from '../dx.config';
 
-    In multi mode, subjects are opened as resizable "planks" arranged side by side. Users can
-    navigate with stack semantics — opening from a pivot truncates planks to the right and
-    appends the new one — or switch to solo or fullscreen mode for focused, distraction-free
-    viewing.
-
-    Layout state (active planks, sidebar visibility, plank sizes, companion pane) is persisted
-    across sessions via KVS/localStorage. URL routing is handled by the plugin so that any
-    workspace configuration can be bookmarked or shared as a deep link.
-
-    All layout changes are expressed through typed LayoutOperations (Open, Close, SetLayoutMode,
-    UpdateSidebar, UpdateDialog, UpdatePopover, etc.) that any plugin in the system can dispatch,
-    keeping the layout logic centralised and easy to extend.
-  `,
-  icon: 'ph--layout--regular',
-  tags: ['system'],
-});
+export const meta = Plugin.getMetaFromConfig(config);

package/src/operations/adjust.ts

@@ -11,7 +11,6 @@ import { AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
 import { AttentionCapabilities } from '@dxos/plugin-attention';
 import { Graph } from '@dxos/plugin-graph';
-import { byPosition } from '@dxos/util';
 
 import { incrementPlank } from '../layout';
 import { DeckCapabilities, DeckOperation, PLANK_COMPANION_TYPE } from '../types';
@@ -60,19 +59,31 @@ const handler: Operation.WithHandler<typeof DeckOperation.Adjust> = DeckOperatio
         yield* Operation.invoke(LayoutOperation.Open, { subject: [soloOperation.entryId] });
       }
 
-      if (input.type === 'companion') {
-        const companion = Function.pipe(
-          Graph.getNode(graph, input.id),
-          Option.map((node) =>
-            Graph.getConnections(graph, node.id, 'child')
-              .filter((n) => n.type === PLANK_COMPANION_TYPE)
-              .toSorted((a, b) => byPosition(a.properties, b.properties)),
-          ),
-          Option.flatMap((companions) => (companions.length > 0 ? Option.some(companions[0]) : Option.none())),
+      if (input.type === 'companion' || input.type === 'companion-vertical') {
+        const orientation = input.type === 'companion-vertical' ? 'vertical' : 'horizontal';
+
+        // Set the orientation first so an already-open companion re-orients in place (the Splitter stays
+        // mounted and only its `orientation` prop changes — panels are never unmounted).
+        yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+          updateActiveDeck(state, { companionOrientation: orientation }),
         );
 
-        if (Option.isSome(companion)) {
-          yield* Operation.invoke(LayoutOperation.UpdateCompanion, { subject: companion.value.id });
+        // Open the companion when one is available; the selected variant lives in global view state and is
+        // resolved at render time, so opening restores the last-selected tab rather than forcing the first.
+        if (!deck.companionOpen) {
+          const hasCompanion = Function.pipe(
+            Graph.getNode(graph, input.id),
+            Option.map((node) =>
+              Graph.getConnections(graph, node.id, 'child').some((n) => n.type === PLANK_COMPANION_TYPE),
+            ),
+            Option.getOrElse(() => false),
+          );
+
+          if (hasCompanion) {
+            yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
+              updateActiveDeck(state, { companionOpen: true }),
+            );
+          }
         }
       }
     }),

package/src/operations/open.ts

@@ -6,13 +6,7 @@ import * as Effect from 'effect/Effect';
 import * as Option from 'effect/Option';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import {
-  AppCapabilities,
-  LayoutOperation,
-  createEdgeExistenceChecker,
-  expandPath,
-  validateNavigationTarget,
-} from '@dxos/app-toolkit';
+import { AppCapabilities, LayoutOperation, NotFound } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
 import { Context } from '@dxos/context';
 import { Database, EID, Obj } from '@dxos/echo';
@@ -56,13 +50,15 @@ const handler: Operation.WithHandler<typeof LayoutOperation.Open> = LayoutOperat
           }
         : undefined;
       const checkRemoteExistence = client
-        ? createEdgeExistenceChecker((spaceId, body) => client.edge.http.execQuery(new Context(), spaceId, body))
+        ? NotFound.createEdgeExistenceChecker((spaceId, body) =>
+            client.edge.http.execQuery(new Context(), spaceId, body),
+          )
         : undefined;
 
       // Immediate: skip 404 / resolver checks but still expand the path (same as validate’s first step).
       if (input.navigation === 'immediate') {
         for (const subjectId of input.subject) {
-          expandPath(graph, subjectId);
+          NotFound.expandPath(graph, subjectId);
         }
       }
 
@@ -70,7 +66,13 @@ const handler: Operation.WithHandler<typeof LayoutOperation.Open> = LayoutOperat
         input.subject.map((subjectId) =>
           input.navigation === 'immediate'
             ? Effect.succeed(subjectId)
-            : validateNavigationTarget({ graph, subjectId, pathResolvers, checkLocalExistence, checkRemoteExistence }),
+            : NotFound.validateNavigationTarget({
+                graph,
+                subjectId,
+                pathResolvers,
+                checkLocalExistence,
+                checkRemoteExistence,
+              }),
         ),
       );
       input = { ...input, subject: validatedSubjects };

package/src/operations/switch-workspace.ts

@@ -5,7 +5,7 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { AppCapabilities, isPinnedWorkspace, LayoutOperation } from '@dxos/app-toolkit';
+import { AppCapabilities, LayoutOperation, Paths } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
 import { invariant } from '@dxos/invariant';
 import { Graph, Node } from '@dxos/plugin-graph';
@@ -21,7 +21,7 @@ const handler: Operation.WithHandler<typeof LayoutOperation.SwitchWorkspace> = L
         const state = yield* Capabilities.getAtomValue(DeckCapabilities.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.
-        const shouldUpdatePrevious = !isPinnedWorkspace(state.activeDeck);
+        const shouldUpdatePrevious = !Paths.isPinnedWorkspace(state.activeDeck);
 
         yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) => {
           const newDecks = state.decks[input.subject]

package/src/operations/update-companion.ts

@@ -4,28 +4,32 @@
 
 import * as Effect from 'effect/Effect';
 
-import { Capabilities } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
 import { LayoutOperation } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
+import { AttentionCapabilities } from '@dxos/plugin-attention';
 import { getLinkedVariant } from '@dxos/react-ui-attention';
 
 import { DeckCapabilities } from '../types';
+import { COMPANION_VIEW_STATE_CONTEXT, companionVariantAspect } from '../util';
 import { updateActiveDeck } from './helpers';
 
 const handler: Operation.WithHandler<typeof LayoutOperation.UpdateCompanion> = LayoutOperation.UpdateCompanion.pipe(
   Operation.withHandler(
     Effect.fnUntraced(function* (input) {
       if (input.subject === null) {
+        // Leave the selected variant intact so reopening the companion restores the last tab.
         yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
           updateActiveDeck(state, { companionOpen: false }),
         );
       } else {
-        const variant = getLinkedVariant(input.subject);
+        // The selected variant is global view state (shared with the split point), not deck state.
+        const viewState = yield* Capability.get(AttentionCapabilities.ViewState);
+        viewState.set(companionVariantAspect, COMPANION_VIEW_STATE_CONTEXT, {
+          variant: getLinkedVariant(input.subject),
+        });
         yield* Capabilities.updateAtomValue(DeckCapabilities.State, (state) =>
-          updateActiveDeck(state, {
-            companionOpen: true,
-            companionVariant: variant,
-          }),
+          updateActiveDeck(state, { companionOpen: true }),
         );
       }
     }),

package/src/translations.ts

@@ -9,9 +9,8 @@ import { meta } from '#meta';
 export const translations = [
   {
     'en-US': {
-      [meta.id]: {
+      [meta.profile.key]: {
         'plugin.name': 'Deck',
-        'settings.title': 'Deck settings',
         'main-header.label': 'Main header',
         'open-navigation-sidebar.label': 'Open sidebar',
         'collapse-navigation-sidebar.label': 'Close sidebar',
@@ -46,7 +45,8 @@ export const translations = [
         'show-fullscreen-plank.label': 'Fullscreen',
         'close.label': 'Close',
         'minify.label': 'Minify',
-        'open-companion.label': 'Open companion',
+        'open-companion.label': 'Open companion side-by-side',
+        'open-companion-vertical.label': 'Open companion stacked',
         'close-companion.label': 'Close companion',
         'close-current.label': 'Close current plank',
         'close-others.label': 'Close other planks',

package/src/types/DeckCapabilities.ts

@@ -12,16 +12,18 @@ import { invariant } from '@dxos/invariant';
 
 import { meta } from '#meta';
 
-import { type EphemeralDeckState, type DeckState, type StoredDeckState } from './schema';
+import { type DeckState, type EphemeralDeckState, type StoredDeckState } from './schema';
 
-export const Settings = Capability.make<Atom.Writable<import('./Settings').Settings>>(`${meta.id}.capability.settings`);
+export const Settings = Capability.make<Atom.Writable<import('./Settings').Settings>>(
+  `${meta.profile.key}.capability.settings`,
+);
 
 /** Persisted state (stored in KVS/localStorage). */
-export const State = Capability.make<Atom.Writable<StoredDeckState>>(`${meta.id}.capability.state`);
+export const State = Capability.make<Atom.Writable<StoredDeckState>>(`${meta.profile.key}.capability.state`);
 
 /** Transient/ephemeral state (not persisted). */
 export const EphemeralState = Capability.make<Atom.Writable<EphemeralDeckState>>(
-  `${meta.id}.capability.ephemeral-state`,
+  `${meta.profile.key}.capability.ephemeral-state`,
 );
 
 /** Get the current active deck from state. */

package/src/types/DeckEvents.ts

@@ -12,7 +12,7 @@ import { meta } from '#meta';
 import * as DeckCapabilities from './DeckCapabilities';
 
 export const StateReady: ActivationEvent.ActivationEvent = AppActivationEvents.createStateEvent(
-  `${meta.id}.state-ready`,
+  `${meta.profile.key}.state-ready`,
 );
 
 /** Fired when DeckSettings capability is ready. */

package/src/types/DeckOperation.ts

@@ -12,11 +12,12 @@ import { DXN } from '@dxos/keys';
 
 import { meta } from '#meta';
 
-const makeKey = (name: string) => DXN.make(`${meta.id}.operation.${name}`);
+const makeKey = (name: string) => DXN.make(`${meta.profile.key}.operation.${name}`);
 
 const PartAdjustmentSchema = Schema.Union(
   Schema.Literal('close').annotations({ description: 'Close the plank.' }),
-  Schema.Literal('companion').annotations({ description: 'Open the companion plank.' }),
+  Schema.Literal('companion').annotations({ description: 'Open the companion plank side-by-side.' }),
+  Schema.Literal('companion-vertical').annotations({ description: 'Open the companion plank stacked vertically.' }),
   Schema.Literal('solo').annotations({ description: 'Solo the plank.' }),
   Schema.Literal('solo--fullscreen').annotations({ description: 'Fullscreen the plank.' }),
   Schema.Literal('increment-start').annotations({ description: 'Move the plank towards the start of the deck.' }),

package/src/types/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './schema';
+export * from './surface';
 
 export * as DeckCapabilities from './DeckCapabilities';
 export * as DeckEvents from './DeckEvents';

package/src/types/schema.ts

@@ -4,12 +4,13 @@
 
 import * as Schema from 'effect/Schema';
 
-import { Label, LayoutOperation } from '@dxos/app-toolkit';
+import { AppNode, LayoutOperation, Translations } from '@dxos/app-toolkit';
 import { type DeepReadonly } from '@dxos/util';
 
 import { meta } from '#meta';
 
-export { PLANK_COMPANION_TYPE, DECK_COMPANION_TYPE } from '@dxos/app-toolkit';
+export const PLANK_COMPANION_TYPE = AppNode.PLANK_COMPANION_TYPE;
+export const DECK_COMPANION_TYPE = AppNode.DECK_COMPANION_TYPE;
 
 export type Part = 'solo' | 'multi' | 'complementary';
 export type ResolvedPart = Part | 'solo-primary' | 'solo-companion';
@@ -32,8 +33,8 @@ export const DeckState = Schema.Struct({
   plankSizing: Schema.mutable(PlankSizing),
   /** Whether the companion pane is visible alongside the active plank(s). */
   companionOpen: Schema.Boolean,
-  /** Which companion variant to display when the companion pane is open. */
-  companionVariant: Schema.optional(Schema.String),
+  /** Orientation of the companion splitter: `horizontal` (side-by-side) or `vertical` (stacked). */
+  companionOrientation: Schema.optional(Schema.Literal('horizontal', 'vertical')),
   /** Persisted companion frame widths in rem, keyed by frame ID. */
   companionFrameSizing: Schema.mutable(PlankSizing),
 });
@@ -47,7 +48,7 @@ export const defaultDeck: DeckState = {
   fullscreen: false,
   plankSizing: {},
   companionOpen: false,
-  companionVariant: undefined,
+  companionOrientation: 'horizontal',
   companionFrameSizing: {},
 };
 
@@ -91,8 +92,8 @@ export const EphemeralDeckState = Schema.Struct({
   popoverSide: Schema.optional(Schema.Literal('top', 'right', 'bottom', 'left')),
   popoverAnchor: Schema.optional(Schema.Any),
   popoverAnchorId: Schema.optional(Schema.String),
-  popoverKind: Schema.optional(Schema.Literal('base', 'card')),
-  popoverTitle: Schema.optional(Label.annotations({ description: 'The title of the popover.' })),
+  popoverKind: Schema.optional(Schema.Literal('base', 'card', 'rename')),
+  popoverTitle: Schema.optional(Translations.Label.annotations({ description: 'The title of the popover.' })),
   /** Ref of the subject to be passed to the popover Surface. */
   popoverContentRef: Schema.optional(Schema.String),
   /** Data to be passed to the popover Surface. */
@@ -115,7 +116,8 @@ export type DeckPluginState = StoredDeckState & EphemeralDeckState;
 export namespace DeckAction {
   const PartAdjustmentSchema = Schema.Union(
     Schema.Literal('close').annotations({ description: 'Close the plank.' }),
-    Schema.Literal('companion').annotations({ description: 'Open the companion plank.' }),
+    Schema.Literal('companion').annotations({ description: 'Open the companion plank side-by-side.' }),
+    Schema.Literal('companion-vertical').annotations({ description: 'Open the companion plank stacked vertically.' }),
     Schema.Literal('solo').annotations({ description: 'Solo the plank.' }),
     Schema.Literal('solo--fullscreen').annotations({ description: 'Fullscreen the plank.' }),
     Schema.Literal('increment-start').annotations({ description: 'Move the plank towards the start of the deck.' }),
@@ -126,16 +128,19 @@ export namespace DeckAction {
   export type Adjustment = Schema.Schema.Type<typeof Adjustment>;
 
   // An atomic transaction to apply to the deck, describing which element to move to which location.
-  export class Adjust extends Schema.TaggedClass<Adjust>()(`${meta.id}.action.adjust`, {
+  export class Adjust extends Schema.TaggedClass<Adjust>()(`${meta.profile.key}.action.adjust`, {
     input: Adjustment,
     output: Schema.Void,
   }) {}
 
-  export class UpdatePlankSize extends Schema.TaggedClass<UpdatePlankSize>()(`${meta.id}.action.update-plank-size`, {
-    input: Schema.Struct({
-      id: Schema.String,
-      size: Schema.Number,
-    }),
-    output: Schema.Void,
-  }) {}
+  export class UpdatePlankSize extends Schema.TaggedClass<UpdatePlankSize>()(
+    `${meta.profile.key}.action.update-plank-size`,
+    {
+      input: Schema.Struct({
+        id: Schema.String,
+        size: Schema.Number,
+      }),
+      output: Schema.Void,
+    },
+  ) {}
 }

package/src/types/surface.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Surface } from '@dxos/app-framework/ui';
+
+/** Slot for the main status-bar container. */
+export const StatusBar: Surface.RoleToken<Record<string, unknown>> = Surface.makeType(
+  'org.dxos.plugin.statusBar.role.statusBar',
+);
+
+/** Slot for the status-bar footer region. */
+export const StatusBarFooter: Surface.RoleToken<Record<string, unknown>> = Surface.makeType(
+  'org.dxos.plugin.statusBar.role.footer',
+);
+
+/** Slot for the version-info widget in the banner. */
+export const VersionInfo: Surface.RoleToken<Record<string, unknown>> = Surface.makeType(
+  'org.dxos.plugin.statusBar.role.versionInfo',
+);
+
+/** Slot for the keyboard-shortcuts hints overlay. */
+export const Hints: Surface.RoleToken<Record<string, unknown>> = Surface.makeType('org.dxos.plugin.support.role.hints');
+
+/** Slot for the full keyboard-shortcuts list. */
+export const Keyshortcuts: Surface.RoleToken<Record<string, unknown>> = Surface.makeType(
+  'org.dxos.plugin.support.role.keyshortcuts',
+);