@dxos/plugin-deck 0.9.0 → 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';
@@ -167,15 +169,14 @@ const TestPlugin = Plugin.define(pluginMeta).pipe(
         Capability.contributes(Capabilities.ReactSurface, [
           Surface.create({
             id: 'storyNavigation',
-            role: 'navigation',
-            filter: (data): data is { current: string } => typeof (data as any).current === 'string',
-            component: ({ data, ref }) => <NavContainer current={data.current} ref={ref} />,
+            filter: Surface.makeFilter(AppSurface.Navigation),
+            component: ({ data, ref }) => (
+              <NavContainer current={data.current} ref={ref as React.Ref<HTMLDivElement>} />
+            ),
           }),
           Surface.create({
             id: 'storyArticle',
-            role: 'article',
-            filter: (data): data is Record<string, unknown> =>
-              typeof data === 'object' && data !== null && (data as { companionTo?: unknown }).companionTo == null,
+            filter: Surface.makeFilter(AppSurface.Article, (data) => data.companionTo == null),
             component: ({ data }) => {
               const subject = (data as any)?.subject;
               const attendableId = (data as any)?.attendableId as string | undefined;
@@ -202,9 +203,7 @@ const TestPlugin = Plugin.define(pluginMeta).pipe(
           }),
           Surface.create({
             id: 'storyArticleCompanion',
-            role: 'article',
-            filter: (data): data is AppSurface.ArticleData<unknown, {}, unknown> =>
-              typeof data === 'object' && data !== null && (data as { companionTo?: unknown }).companionTo != null,
+            filter: Surface.makeFilter(AppSurface.Article, (data) => data.companionTo != null),
             component: ({ data: { subject, companionTo, properties, variant } }) => {
               if (companionTo == null) {
                 return <Loading />;
@@ -248,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'),
@@ -279,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>
   );
 });
@@ -315,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/containers/DeckLayout/Fallback.tsx

@@ -9,7 +9,7 @@ import { useTranslation } from '@dxos/react-ui';
 import { meta } from '#meta';
 
 const Fallback = () => {
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
 
   return (
     <div className='min-h-screen w-full flex items-center justify-center p-8'>

package/src/containers/DeckLayout/Popover.tsx

@@ -10,10 +10,12 @@ import { AppSurface, useObjectMenuItems } from '@dxos/app-toolkit/ui';
 import { Obj } from '@dxos/echo';
 import {
   Card,
+  Icon,
+  IconButton,
   Popover,
   type PopoverContentInteractOutsideEvent,
   toLocalizedString,
-  Toolbar,
+  useMediaQuery,
   useTranslation,
 } from '@dxos/react-ui';
 import { Menu } from '@dxos/react-ui-menu';
@@ -54,9 +56,12 @@ export const PopoverRoot = ({ children }: PopoverRootProps) => {
     }
   }, [state.popoverOpen, state.popoverAnchorId, state.popoverAnchor, state.popoverContent]);
 
+  // The rename popover is modal so other navtree item menus are inert while it is open.
+  const modal = state.popoverKind === 'rename';
+
   return (
     <DeckPopoverProvider setOpen={setOpen}>
-      <Popover.Root modal={false} open={open}>
+      <Popover.Root modal={modal} open={open}>
         {state.popoverAnchor && <Popover.VirtualTrigger key={virtualIter} virtualRef={virtualRef} />}
         {children}
       </Popover.Root>
@@ -65,7 +70,7 @@ export const PopoverRoot = ({ children }: PopoverRootProps) => {
 };
 
 export const PopoverContent = () => {
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
   const { state, updateEphemeral } = useDeckState();
   const { setOpen } = useDeckPopoverContext('PopoverContent');
   const popoverSubject =
@@ -75,8 +80,14 @@ export const PopoverContent = () => {
   const title = state.popoverTitle ? toLocalizedString(state.popoverTitle, t) : 'Unknown';
   const icon = isObjectPopover ? (Obj.getIcon(popoverSubject)?.icon ?? 'ph--circle-dashed--regular') : undefined;
   const content = state.popoverContent;
-  // A base popover renders a plugin-provided component; everything else falls through to the card.
-  const isBasePopover = state.popoverKind === 'base' && !!content && 'component' in content;
+  // Base and rename popovers render a plugin-provided component; everything else falls through to the card.
+  const isComponentPopover =
+    (state.popoverKind === 'base' || state.popoverKind === 'rename') && !!content && 'component' in content;
+  const isRename = state.popoverKind === 'rename';
+
+  // Anchor to the right of the row on wide displays; drop centered below on narrow ones.
+  const [isLg] = useMediaQuery('lg', { fallback: [true] });
+  const side = isRename ? (isLg ? 'right' : 'bottom') : state.popoverSide;
 
   const handleClose = useCallback(() => {
     setOpen(false);
@@ -91,15 +102,14 @@ export const PopoverContent = () => {
 
   const handleInteractOutside = useCallback(
     (event: KeyboardEvent | PopoverContentInteractOutsideEvent) => {
-      if (
-        // TODO(thure): CodeMirror should not focus itself when it updates.
-        event.type === 'dismissableLayer.focusOutside' &&
-        (event.currentTarget as HTMLElement | undefined)?.classList.contains('cm-content')
-      ) {
+      // Focus leaving the popover (clicking into the card surfaces a portaled menu, or CodeMirror
+      // re-focusing itself) must not dismiss it — only a pointer-down genuinely outside the card, or
+      // Escape, closes. (Clicks inside the card never reach here; Radix scopes them to the content.)
+      if (event.type === 'dismissableLayer.focusOutside') {
         event.preventDefault();
-      } else {
-        handleClose();
+        return;
       }
+      handleClose();
     },
     [handleClose],
   );
@@ -107,15 +117,22 @@ export const PopoverContent = () => {
   return (
     <Popover.Portal>
       <Popover.Content
-        side={state.popoverSide}
+        side={side}
         sticky='always'
         hideWhenDetached
-        onOpenAutoFocus={(event) => event.preventDefault()}
+        // Rename focuses its input; other popovers keep focus where it was.
+        onOpenAutoFocus={isRename ? undefined : (event) => event.preventDefault()}
         onInteractOutside={handleInteractOutside}
         onEscapeKeyDown={handleInteractOutside}
+        // Reuse the dialog's enter/exit motion so the rename popover does not flicker on open.
+        classNames={
+          isRename
+            ? ['data-[state=open]:animate-slide-up-and-fade', 'data-[state=closed]:animate-slide-down-and-fade']
+            : undefined
+        }
       >
         <Popover.Viewport>
-          {isBasePopover && content && 'component' in content ? (
+          {isComponentPopover && content && 'component' in content ? (
             /* Base popover: a plugin-provided component (e.g. editor link preview). */
             <Surface.Surface type={AppSurface.Popover} data={content} limit={1} />
           ) : (
@@ -129,12 +146,12 @@ export const PopoverContent = () => {
             <Menu.Root>
               <Card.Root border={false} classNames='dx-card-popover'>
                 <Card.Header>
-                  <Card.IconBlock>{icon && <Card.Icon icon={icon} />}</Card.IconBlock>
+                  <Card.Block>{icon && <Icon icon={icon} />}</Card.Block>
                   <Card.Title>{title}</Card.Title>
                   {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
-                  <Card.IconBlock>
+                  <Card.Block end>
                     <Menu.Trigger asChild disabled={!objectMenuItems.length}>
-                      <Toolbar.IconButton
+                      <IconButton
                         variant='ghost'
                         density='sm'
                         icon='ph--dots-three-vertical--regular'
@@ -143,11 +160,11 @@ export const PopoverContent = () => {
                       />
                     </Menu.Trigger>
                     <Menu.Content items={objectMenuItems} />
-                  </Card.IconBlock>
+                  </Card.Block>
                 </Card.Header>
 
                 {content && 'subject' in content ? (
-                  <Surface.Surface type={AppSurface.Card} data={content} limit={1} />
+                  <Surface.Surface type={AppSurface.CardContent} data={content} limit={1} />
                 ) : (
                   <Card.Body classNames='min-bs-8'>
                     <Card.Row>

package/src/containers/DeckLayout/Toast.tsx

@@ -21,7 +21,7 @@ export const Toast = ({
   onAction,
   onOpenChange,
 }: LayoutOperation.Toast & Pick<ToastRootProps, 'onOpenChange'>) => {
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
 
   // Control the open state so closing flips Radix's `open` (playing the exit animation) rather than
   // unmounting abruptly. Both the close button and Radix's own timeout/swipe route through here.

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

@@ -6,7 +6,8 @@ import React, { type MouseEvent, useCallback, useEffect, useMemo, useState } fro
 
 import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
 import { LayoutOperation } from '@dxos/app-toolkit';
-import { IconButton, type Label, Main, Panel, toLocalizedString, Toolbar, useTranslation } from '@dxos/react-ui';
+import { AppSurface } from '@dxos/app-toolkit/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';
@@ -16,10 +17,10 @@ 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.id }] satisfies Label;
+const label = ['complementary-sidebar.title', { ns: meta.profile.key }] satisfies Label;
 
 export type ComplementarySidebarProps = {
   current?: string;
@@ -27,7 +28,7 @@ export type ComplementarySidebarProps = {
 
 export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) => {
   const { invokePromise } = useOperationInvoker();
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
   const { state, deck, updateState } = useDeckState();
   const layoutMode = getMode(deck);
   const breakpoint = useBreakpoints();
@@ -117,7 +118,7 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
             className='grid grid-cols-1 auto-rows-(--dx-rail-item) py-0.5 gap-0.5 overflow-y-auto scrollbar-none'
             style={iconSize(4)}
           >
-            <Surface.Surface role='status-indicator' />
+            <Surface.Surface type={AppSurface.StatusIndicator} />
           </div>
           <div className='hidden lg:grid grid-cols-1 auto-rows-(--dx-rail-action) p-1'>
             <ToggleComplementarySidebarButton />
@@ -154,7 +155,7 @@ type ComplementarySidebarPanelProps = {
 };
 
 const ComplementarySidebarPanel = ({ companion, activeId, data }: ComplementarySidebarPanelProps) => {
-  const { t } = useTranslation(meta.id);
+  const { t } = useTranslation(meta.profile.key);
 
   if (getLinkedVariant(companion.id) !== activeId && !data) {
     return null;
@@ -178,7 +179,7 @@ const ComplementarySidebarPanel = ({ companion, activeId, data }: ComplementaryS
       </Panel.Toolbar>
       <Panel.Content classNames='bg-r1-surface'>
         <Surface.Surface
-          role={`deck-companion--${getLinkedVariant(companion.id)}`}
+          type={AppSurface.deckCompanion(getLinkedVariant(companion.id))}
           data={data}
           fallback={PlankErrorFallback}
           placeholder={<PlankLoading />}

package/src/containers/Sidebar/Sidebar.tsx

@@ -14,7 +14,7 @@ import { getMode } from '#types';
 
 import { layoutAppliesTopbar } from '../../util';
 
-const label = ['sidebar.title', { ns: meta.id }] satisfies Label;
+const label = ['sidebar.title', { ns: meta.profile.key }] satisfies Label;
 
 export const Sidebar = () => {
   const { state, deck } = useDeckState();