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

package/dx.config.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Config2 } from '@dxos/app-framework/config';
+import { trim } from '@dxos/util';
+
+export default Config2.make({
+  plugin: {
+    key: 'org.dxos.plugin.deck',
+    name: 'Layout',
+    author: 'DXOS',
+    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.
+
+      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: { key: 'ph--layout--regular' },
+    spec: 'PLUGIN.mdl',
+    tags: ['system'],
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-deck",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "DXOS Surface plugin for the main application layout.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -86,6 +86,7 @@
   "types": "dist/types/src/index.d.ts",
   "files": [
     "dist",
+    "dx.config.ts",
     "src",
     "PLUGIN.mdl"
   ],
@@ -93,63 +94,64 @@
     "@effect-atom/atom-react": "^0.5.0",
     "@fluentui/react-tabster": "9.26.11",
     "@radix-ui/react-context": "1.1.1",
+    "@radix-ui/react-slot": "1.1.2",
     "@tauri-apps/plugin-deep-link": "^2.4.9",
     "immer": "^10.1.1",
-    "@dxos/app-framework": "0.9.0",
-    "@dxos/async": "0.9.0",
-    "@dxos/app-toolkit": "0.9.0",
-    "@dxos/context": "0.9.0",
-    "@dxos/app-graph": "0.9.0",
-    "@dxos/compute": "0.9.0",
-    "@dxos/echo": "0.9.0",
-    "@dxos/effect": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/errors": "0.9.0",
-    "@dxos/keyboard": "0.9.0",
-    "@dxos/keys": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/operation": "0.9.0",
-    "@dxos/plugin-attention": "0.9.0",
-    "@dxos/plugin-observability": "0.9.0",
-    "@dxos/plugin-graph": "0.9.0",
-    "@dxos/react-ui-attention": "0.9.0",
-    "@dxos/react-ui-form": "0.9.0",
-    "@dxos/plugin-client": "0.9.0",
-    "@dxos/react-ui-menu": "0.9.0",
-    "@dxos/react-ui-mosaic": "0.9.0",
-    "@dxos/react-ui-tabs": "0.9.0",
-    "@dxos/react-ui-text-tooltip": "0.9.0",
-    "@dxos/react-ui-stack": "0.9.0",
-    "@dxos/ui-types": "0.9.0",
-    "@dxos/util": "0.9.0"
+    "@dxos/app-toolkit": "0.9.1-staging.ee54ba693a",
+    "@dxos/app-framework": "0.9.1-staging.ee54ba693a",
+    "@dxos/app-graph": "0.9.1-staging.ee54ba693a",
+    "@dxos/context": "0.9.1-staging.ee54ba693a",
+    "@dxos/async": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo": "0.9.1-staging.ee54ba693a",
+    "@dxos/compute": "0.9.1-staging.ee54ba693a",
+    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
+    "@dxos/errors": "0.9.1-staging.ee54ba693a",
+    "@dxos/effect": "0.9.1-staging.ee54ba693a",
+    "@dxos/keyboard": "0.9.1-staging.ee54ba693a",
+    "@dxos/operation": "0.9.1-staging.ee54ba693a",
+    "@dxos/log": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-attention": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-graph": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/keys": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-observability": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-attention": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-dnd": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-form": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-list": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-mosaic": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-menu": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-tabs": "0.9.1-staging.ee54ba693a",
+    "@dxos/util": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-types": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
-    "@effect/platform": "0.96.1",
-    "@types/react": "~19.2.7",
+    "@effect/platform": "0.96.2",
+    "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
     "vite": "^8.0.16",
-    "@dxos/random": "0.9.0",
-    "@dxos/react-hooks": "0.9.0",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/plugin-testing": "0.9.0",
-    "@dxos/react-ui-syntax-highlighter": "0.9.0",
-    "@dxos/schema": "0.9.0",
-    "@dxos/storybook-utils": "0.9.0",
-    "@dxos/types": "0.9.0",
-    "@dxos/ui-theme": "0.9.0"
+    "@dxos/plugin-testing": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-hooks": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/random": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-syntax-highlighter": "0.9.1-staging.ee54ba693a",
+    "@dxos/schema": "0.9.1-staging.ee54ba693a",
+    "@dxos/storybook-utils": "0.9.1-staging.ee54ba693a",
+    "@dxos/types": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a"
   },
   "peerDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
-    "@effect/platform": "0.96.1",
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
-    "@dxos/ui-theme": "0.9.0",
-    "@dxos/react-ui": "0.9.0"
+    "@effect/platform": "0.96.2",
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a"
   },
   "publishConfig": {
     "access": "public"

package/src/DeckPlugin.test.ts

@@ -11,7 +11,7 @@ import { DeckPlugin } from '#plugin';
 
 import { meta } from './meta';
 
-const moduleId = (name: string) => `${meta.id}.module.${name}`;
+const moduleId = (name: string) => `${meta.profile.key}.module.${name}`;
 
 describe('DeckPlugin', () => {
   test('modules activate on the expected events', async ({ expect }) => {

package/src/DeckPlugin.ts

@@ -6,7 +6,6 @@ import { setAutoFreeze } from 'immer';
 
 import { ActivationEvent, ActivationEvents, Plugin } from '@dxos/app-framework';
 import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
-import { translations as stackTranslations } from '@dxos/react-ui-stack/translations';
 
 import {
   AppGraphBuilder,
@@ -35,7 +34,7 @@ export const DeckPlugin = Plugin.define(meta).pipe(
   AppPlugin.addAppGraphModule({ activate: AppGraphBuilder }),
   AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
   AppPlugin.addSurfaceModule({ activate: ReactSurface }),
-  AppPlugin.addTranslationsModule({ translations: [...translations, ...stackTranslations] }),
+  AppPlugin.addTranslationsModule({ translations }),
   Plugin.addModule({
     activatesOn: AppActivationEvents.SetupSettings,
     firesAfterActivation: [DeckEvents.SettingsReady],
@@ -70,7 +69,7 @@ export const DeckPlugin = Plugin.define(meta).pipe(
     activate: NotificationTracker,
   }),
   AppPlugin.addPluginAssetModule({
-    asset: { pluginId: meta.id, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
+    asset: { pluginId: meta.profile.key, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
   }),
   Plugin.make,
 );

package/src/capabilities/app-graph-builder.ts

@@ -9,6 +9,7 @@ import { AppCapabilities, AppNode, LayoutOperation } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
 import { AttentionCapabilities } from '@dxos/plugin-attention';
 import { GraphBuilder, NodeMatcher } from '@dxos/plugin-graph';
+import { Position } from '@dxos/util';
 
 import { meta } from '#meta';
 import { DeckCapabilities } from '#types';
@@ -57,7 +58,7 @@ export default Capability.makeModule(
                 }
               }),
               properties: {
-                label: ['close-current.label', { ns: meta.id }],
+                label: ['close-current.label', { ns: meta.profile.key }],
                 icon: 'ph--x--regular',
               },
             };
@@ -72,7 +73,7 @@ export default Capability.makeModule(
                 yield* Operation.invoke(LayoutOperation.Close, { subject: ids });
               }),
               properties: {
-                label: ['close-others.label', { ns: meta.id }],
+                label: ['close-others.label', { ns: meta.profile.key }],
                 icon: 'ph--x-square--regular',
               },
             };
@@ -84,7 +85,7 @@ export default Capability.makeModule(
                 yield* Operation.invoke(LayoutOperation.Close, { subject: deck.active });
               }),
               properties: {
-                label: ['close-all.label', { ns: meta.id }],
+                label: ['close-all.label', { ns: meta.profile.key }],
                 icon: 'ph--x-circle--regular',
               },
             };
@@ -105,20 +106,20 @@ export default Capability.makeModule(
                   state.sidebarState === 'expanded'
                     ? 'collapse-navigation-sidebar.label'
                     : 'open-navigation-sidebar.label',
-                  { ns: meta.id },
+                  { ns: meta.profile.key },
                 ],
                 icon: 'ph--sidebar--regular',
                 keyBinding: {
                   macos: "meta+'",
                 },
                 disposition: 'pin-end',
-                position: 'last',
+                position: Position.last,
                 l0Breakpoint: 'lg',
               },
             };
 
             return !deck?.solo ? [closeCurrent, closeOthers, closeAll, toggleSidebar] : [toggleSidebar];
-          }),
+          }).pipe(Effect.orDie),
       }),
     ]);
 

package/src/capabilities/check-app-scheme.ts

@@ -5,7 +5,7 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import { APP_SCHEME, AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
+import { AppCapabilities, LayoutOperation, NativePasskey } from '@dxos/app-toolkit';
 import { EffectEx } from '@dxos/effect';
 import { isTauri } from '@dxos/util';
 
@@ -24,7 +24,7 @@ const isSafari = (): boolean => {
 /** Check if the current page URL can be converted to a valid custom scheme URL. */
 const canRedirectToScheme = (): boolean => {
   try {
-    const schemeUrl = APP_SCHEME + window.location.pathname.replace(/^\/+/, '') + window.location.search;
+    const schemeUrl = NativePasskey.APP_SCHEME + window.location.pathname.replace(/^\/+/, '') + window.location.search;
     new URL(schemeUrl);
     return true;
   } catch {
@@ -63,7 +63,7 @@ const tryOpenNativeApp = (): Promise<boolean> => {
     document.addEventListener('visibilitychange', onVisibilityChange);
 
     // Try the scheme via hidden iframe.
-    const schemeUrl = APP_SCHEME + window.location.pathname.replace(/^\/+/, '') + window.location.search;
+    const schemeUrl = NativePasskey.APP_SCHEME + window.location.pathname.replace(/^\/+/, '') + window.location.search;
     const iframe = document.createElement('iframe');
     iframe.style.display = 'none';
     iframe.src = schemeUrl;

package/src/capabilities/notification-tracker.ts

@@ -4,11 +4,13 @@
 
 import * as Effect from 'effect/Effect';
 import * as Fiber from 'effect/Fiber';
+import * as Option from 'effect/Option';
 import * as Stream from 'effect/Stream';
 
 import { Capabilities, Capability, type PluginManager } from '@dxos/app-framework';
 import { type LayoutOperation, SettingsOperation } from '@dxos/app-toolkit';
 import { Process } from '@dxos/compute';
+import { Annotation } from '@dxos/echo';
 
 import { meta } from '#meta';
 import { DeckCapabilities } from '#types';
@@ -56,7 +58,7 @@ export default Capability.makeModule(
           continue;
         }
 
-        const notify = process.params.notify;
+        const notify = Option.getOrNull(Annotation.getDictionary(process.params.annotations, Process.NotifyAnnotation));
         if (!notify) {
           continue;
         }
@@ -105,12 +107,12 @@ export default Capability.makeModule(
       // Replace any stale plugin-failure toast so at most one is ever visible.
       const toast: LayoutOperation.Toast = {
         id: 'plugin-failure',
-        title: ['plugin-failure.title', { ns: meta.id }],
-        description: ['plugin-failure.description', { ns: meta.id }],
+        title: ['plugin-failure.title', { ns: meta.profile.key }],
+        description: ['plugin-failure.description', { ns: meta.profile.key }],
         icon: 'ph--warning--regular',
         duration: ERROR_TOAST_DURATION,
-        actionLabel: ['plugin-failure-action.label', { ns: meta.id }],
-        actionAlt: ['plugin-failure-action.alt', { ns: meta.id }],
+        actionLabel: ['plugin-failure-action.label', { ns: meta.profile.key }],
+        actionAlt: ['plugin-failure-action.alt', { ns: meta.profile.key }],
         onAction: () => void invoker.invokePromise(SettingsOperation.OpenPluginRegistry),
       };
       const state = registry.get(ephemeralAtom);
@@ -135,11 +137,11 @@ export default Capability.makeModule(
         : state.toasts;
       const toast: LayoutOperation.Toast = {
         id: undoId,
-        title: message ?? ['undo-available.label', { ns: meta.id }],
+        title: message ?? ['undo-available.label', { ns: meta.profile.key }],
         duration: UNDO_TOAST_DURATION,
-        actionLabel: ['undo-action.label', { ns: meta.id }],
-        actionAlt: ['undo-action.alt', { ns: meta.id }],
-        closeLabel: ['undo-close.label', { ns: meta.id }],
+        actionLabel: ['undo-action.label', { ns: meta.profile.key }],
+        actionAlt: ['undo-action.alt', { ns: meta.profile.key }],
+        closeLabel: ['undo-close.label', { ns: meta.profile.key }],
         onAction: onUndo,
       };
       registry.set(ephemeralAtom, { ...state, currentUndoId: undoId, toasts: [...toasts, toast] });

package/src/capabilities/react-root.tsx

@@ -14,7 +14,7 @@ import { meta } from '#meta';
 export default Capability.makeModule(() =>
   Effect.succeed(
     Capability.contributes(Capabilities.ReactRoot, {
-      id: meta.id,
+      id: meta.profile.key,
       root: () => {
         const { state, updateEphemeral } = useDeckState();
 

package/src/capabilities/react-surface.tsx

@@ -7,10 +7,10 @@ import React from 'react';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
 import { Surface, useSettingsState } from '@dxos/app-framework/ui';
-import { NOT_FOUND_PATH } from '@dxos/app-toolkit';
+import { NotFound } from '@dxos/app-toolkit';
 import { AppSurface, NotFoundArticle } from '@dxos/app-toolkit/ui';
 
-import { DeckSettings } from '#components';
+import { DeckSettings } from '#containers';
 import { meta } from '#meta';
 import { type Settings } from '#types';
 
@@ -19,7 +19,7 @@ export default Capability.makeModule(() =>
     Capability.contributes(Capabilities.ReactSurface, [
       Surface.create({
         id: 'pluginSettings',
-        filter: AppSurface.settings(AppSurface.Article, meta.id),
+        filter: AppSurface.settings(AppSurface.Article, meta.profile.key),
         component: ({ data: { subject } }) => {
           const { settings, updateSettings } = useSettingsState<Settings.Settings>(subject.atom);
           return <DeckSettings settings={settings} onSettingsChange={updateSettings} />;
@@ -27,8 +27,7 @@ export default Capability.makeModule(() =>
       }),
       Surface.create({
         id: 'notFound',
-        role: 'article',
-        filter: (data): data is { attendableId: string } => data.attendableId === NOT_FOUND_PATH,
+        filter: Surface.makeFilter(AppSurface.Article, (data) => data.attendableId === NotFound.NOT_FOUND_PATH),
         component: () => <NotFoundArticle />,
       }),
     ]),

package/src/capabilities/settings.ts

@@ -14,7 +14,7 @@ import { DeckCapabilities, Settings } from '#types';
 export default Capability.makeModule(() =>
   Effect.sync(() => {
     const settingsAtom = createKvsStore({
-      key: meta.id,
+      key: meta.profile.key,
       schema: Settings.Settings,
       defaultValue: () => ({
         showHints: false,
@@ -27,7 +27,7 @@ export default Capability.makeModule(() =>
     return [
       Capability.contributes(DeckCapabilities.Settings, settingsAtom),
       Capability.contributes(AppCapabilities.Settings, {
-        prefix: meta.id,
+        prefix: meta.profile.key,
         schema: Settings.Settings,
         atom: settingsAtom,
       }),

package/src/capabilities/state.ts

@@ -49,7 +49,7 @@ export default Capability.makeModule(
 
     // Persisted state using KVS store.
     const stateAtom = createKvsStore({
-      key: `${meta.id}.state`,
+      key: `${meta.profile.key}.state`,
       schema: StoredDeckState,
       defaultValue: () => ({ ...defaultDeckState }),
     });

package/src/capabilities/url-handler.ts

@@ -5,15 +5,7 @@
 import * as Effect from 'effect/Effect';
 
 import { Capabilities, Capability } from '@dxos/app-framework';
-import {
-  AppCapabilities,
-  LayoutOperation,
-  NOT_FOUND_PATH,
-  expandPath,
-  fromUrlPath,
-  getWorkspaceFromPath,
-  toUrlPath,
-} from '@dxos/app-toolkit';
+import { AppCapabilities, LayoutOperation, NotFound, Paths } from '@dxos/app-toolkit';
 import { Operation } from '@dxos/compute';
 import { EffectEx } from '@dxos/effect';
 import { invariant } from '@dxos/invariant';
@@ -91,8 +83,8 @@ export default Capability.makeModule(
         return;
       }
 
-      const qualifiedId = fromUrlPath(pathname);
-      const workspace = getWorkspaceFromPath(qualifiedId);
+      const qualifiedId = Paths.fromUrlPath(pathname);
+      const workspace = Paths.getWorkspaceFromPath(qualifiedId);
       if (workspace !== Node.RootId && workspace !== state.activeDeck) {
         yield* Operation.invoke(LayoutOperation.SwitchWorkspace, { subject: workspace });
       }
@@ -110,10 +102,10 @@ export default Capability.makeModule(
             mode: 'solo',
           });
         }
-      } else if (deck.solo && deck.solo !== NOT_FOUND_PATH) {
+      } else if (deck.solo && deck.solo !== NotFound.NOT_FOUND_PATH) {
         // Stay in solo mode; redirect URL to reflect the current solo item.
         // Do not switch to deck mode here — only explicit user action should change layout mode.
-        const path = toUrlPath(deck.solo);
+        const path = Paths.toUrlPath(deck.solo);
         if (window.location.pathname !== path) {
           history.replaceState(null, '', `${path}${stripPlanks(window.location.search)}`);
         }
@@ -122,7 +114,7 @@ export default Capability.makeModule(
         const plankIds = deserializePlanks(resolvedUrl);
         if (plankIds.length > 0) {
           for (const plankId of plankIds) {
-            expandPath(graph, plankId);
+            NotFound.expandPath(graph, plankId);
           }
           updateState((state) => updateActiveDeck(state, { active: plankIds, initialized: true }));
         }
@@ -203,7 +195,7 @@ export default Capability.makeModule(
         lastActiveDeck = activeDeck;
         lastActiveKey = activeKey;
 
-        const path = solo && solo !== NOT_FOUND_PATH ? toUrlPath(solo) : toUrlPath(activeDeck);
+        const path = solo && solo !== NotFound.NOT_FOUND_PATH ? Paths.toUrlPath(solo) : Paths.toUrlPath(activeDeck);
         const search = !solo
           ? serializePlanks(deck.active, window.location.search)
           : stripPlanks(window.location.search);

package/src/components/Companion/Companion.tsx

@@ -0,0 +1,91 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type ReactNode, useMemo } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { type Node } from '@dxos/plugin-graph';
+import { type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+import { mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+import { Pane, type PaneTab } from '../Pane';
+
+//
+// Companion
+//
+// A higher-level companion pane bound to a set of companion {@link Node}s: a {@link Pane} whose toolbar
+// holds the companion tab strip and whose body renders the companions' content Surfaces. All panels stay
+// mounted (inactive hidden) so switching tabs preserves each companion's state. Shares attention with the
+// primary plank via `attendableId`. Controls (e.g. close) are supplied by the container.
+//
+
+export type CompanionProps = ThemedClassName<{
+  companions: Node.Node[];
+  /** Selected companion id. */
+  value?: string;
+  onValueChange?: (id: string) => void;
+  /** Primary plank attendable id; the companion shares its attention. */
+  attendableId?: string;
+  /** Primary plank subject; companion Article surfaces filter on (and operate against) `companionTo`. */
+  companionTo?: unknown;
+  /** Toolbar controls rendered after the tabs (e.g. close). */
+  controls?: ReactNode;
+}>;
+
+export const Companion = ({
+  classNames,
+  companions,
+  value,
+  onValueChange,
+  attendableId,
+  companionTo,
+  controls,
+}: CompanionProps) => {
+  const { t } = useTranslation(meta.profile.key);
+
+  // Fall back to the first companion when uncontrolled so a panel is always visible.
+  const selected = value ?? companions[0]?.id;
+  const tabs = useMemo<PaneTab[]>(
+    () =>
+      companions.map((node) => ({
+        id: node.id,
+        icon: node.properties?.icon ?? 'ph--circle-dashed--regular',
+        label: toLocalizedString(node.properties?.label ?? '', t),
+      })),
+    [companions, t],
+  );
+
+  // Stable per-companion data objects so companion article surfaces don't receive a new prop reference on
+  // every parent re-render (the same pattern as the inline data fix in Plank).
+  const companionDataList = useMemo(
+    () =>
+      companions.map((node) => ({
+        attendableId,
+        subject: node.data,
+        companionTo,
+        variant: getLinkedVariant(node.id),
+        properties: node.properties,
+      })),
+    [companions, attendableId, companionTo],
+  );
+
+  return (
+    <Pane.Root classNames={classNames}>
+      <Pane.Toolbar>
+        <Pane.Tabs tabs={tabs} value={selected} onValueChange={onValueChange} attendableId={attendableId} related />
+        {controls}
+      </Pane.Toolbar>
+      {/* Panels stay mounted; the inactive ones are hidden so switching companions preserves their state. */}
+      {companions.map((node, index) => (
+        <Pane.Content key={node.id} classNames={mx(node.id !== selected && 'hidden')}>
+          <Surface.Surface type={AppSurface.Article} data={companionDataList[index]} limit={1} />
+        </Pane.Content>
+      ))}
+    </Pane.Root>
+  );
+};

package/src/components/Companion/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Companion';