@dxos/plugin-debug 0.12.0-next-73daef452f1464b62efdbca75fb0067c1066f264 → 0.13.0

package/src/containers/DebugPanel/DebugPanelHeader.tsx

@@ -0,0 +1,54 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import * as Button from '@dxos/react-ui/Button';
+import * as Hooks from '@dxos/react-ui/Hooks';
+
+import { meta } from '#meta';
+
+import { type DebugPanelMode } from './view-state.ts';
+
+export type DebugPanelHeaderProps = Pick<Button.RootProps, 'size'> & {
+  mode: DebugPanelMode;
+  onModeChange: (mode: DebugPanelMode) => void;
+  /** Omitted where the host brings its own close (the floating window's `CloseTrigger`). */
+  onClose?: () => void;
+};
+
+/**
+ * The title-bar controls both hosts share: the dock/float switch, and a close for a host without one
+ * of its own. The button says what it does next, so the icon flips with the mode.
+ */
+export const DebugPanelHeader = ({ mode, onModeChange, onClose, size }: DebugPanelHeaderProps) => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  const floating = mode === 'floating';
+  return (
+    <>
+      <Button.Root
+        variant='ghost'
+        size={size}
+        iconOnly
+        icon={floating ? 'ph--arrow-square-in--regular' : 'ph--arrow-square-out--regular'}
+        label={floating ? t('dock-panel.label') : t('float-panel.label')}
+        data-testid='debugPanel.mode'
+        onClick={() => onModeChange(floating ? 'docked' : 'floating')}
+      />
+      {onClose && (
+        <Button.Root
+          variant='ghost'
+          size={size}
+          iconOnly
+          icon='ph--x--regular'
+          label={t('close-panel.label')}
+          data-testid='debugPanel.close'
+          onClick={onClose}
+        />
+      )}
+    </>
+  );
+};
+
+DebugPanelHeader.displayName = 'DebugPanelHeader';

package/src/containers/DebugPanel/DebugPanelMain.tsx

@@ -0,0 +1,116 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+
+import * as Surface from '@dxos/app-framework/Surface';
+import * as AppGraph from '@dxos/app-graph/AppGraph';
+import * as ToolkitHooks from '@dxos/app-toolkit/Hooks';
+import * as GraphHooks from '@dxos/plugin-graph/Hooks';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import * as Status from '@dxos/react-ui/Status';
+
+import { meta } from '#meta';
+import { DebugNodes, DebugSurface } from '#types';
+
+import { useDebugPanelContext } from './DebugPanelContext.ts';
+
+/** Pages that stay mounted once visited: their buffers are the point of the tool. */
+const KEEP_MOUNTED: ReadonlySet<unknown> = new Set([DebugNodes.Console, DebugNodes.Logs]);
+
+/**
+ * The selected page. The console and log viewer stay mounted (hidden) once visited so they keep
+ * their buffers while another tool is shown; every other page mounts only while selected.
+ */
+export const DebugPanelMain = () => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  const { contextId, nodeId, select } = useDebugPanelContext();
+  const { graph } = ToolkitHooks.useAppGraph();
+  const handleNavigate = useCallback(
+    (target: string) => {
+      AppGraph.expandPath(graph, target);
+      select(target);
+    },
+    [graph, select],
+  );
+  const node = GraphHooks.useNode(graph, nodeId);
+  const keepMounted = node !== undefined && KEEP_MOUNTED.has(node.data);
+  const [visited, setVisited] = useState<string[]>([]);
+  useEffect(() => {
+    if (nodeId && keepMounted) {
+      // Guarded in the updater: StrictMode runs the effect twice on mount, and two appends would mount the page twice.
+      setVisited((prev) => (prev.includes(nodeId) ? prev : [...prev, nodeId]));
+    }
+  }, [nodeId, keepMounted]);
+
+  if (!nodeId) {
+    return <Status.Empty>{t('debug-panel.empty.label')}</Status.Empty>;
+  }
+
+  // Appended in the same render it is selected (the effect only catches up), so the keyed page is
+  // never first mounted as the transient one and then remounted.
+  const mounted = keepMounted && !visited.includes(nodeId) ? [...visited, nodeId] : visited;
+
+  return (
+    <>
+      {mounted.map((id) => (
+        <DebugPanelPage
+          key={id}
+          graph={graph}
+          contextId={contextId}
+          nodeId={id}
+          hidden={id !== nodeId}
+          onNavigate={handleNavigate}
+        />
+      ))}
+      {!mounted.includes(nodeId) && (
+        <DebugPanelPage
+          key={nodeId}
+          graph={graph}
+          contextId={contextId}
+          nodeId={nodeId}
+          hidden={false}
+          onNavigate={handleNavigate}
+        />
+      )}
+    </>
+  );
+};
+
+DebugPanelMain.displayName = 'DebugPanel.Main';
+
+type DebugPanelPageProps = {
+  graph: AppGraph.ReadableGraph;
+  contextId: string;
+  nodeId: string;
+  hidden: boolean;
+  onNavigate: (nodeId: string) => void;
+};
+
+/** One tool's article surface; the `div` is its show/hide element, not layout. */
+const DebugPanelPage = ({ graph, contextId, nodeId, hidden, onNavigate }: DebugPanelPageProps) => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  const node = GraphHooks.useNode(graph, nodeId);
+  const data = useMemo<DebugSurface.PageData | undefined>(
+    () =>
+      node && {
+        attendableId: `${contextId}/${nodeId}`,
+        nodeId,
+        subject: node.data,
+        properties: node.properties,
+        onNavigate,
+      },
+    [node, contextId, nodeId, onNavigate],
+  );
+  if (!data) {
+    // A persisted id that no longer resolves (a plugin disabled) shows the empty state rather than nothing.
+    return hidden ? null : <Status.Empty>{t('debug-panel.empty.label')}</Status.Empty>;
+  }
+
+  return (
+    <div role='none' className='dx-expand' hidden={hidden}>
+      <Surface.Surface type={DebugSurface.Page} data={data} limit={1} />
+    </div>
+  );
+};

package/src/containers/DebugPanel/DebugPanelSidebar.tsx

@@ -0,0 +1,123 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Atom from 'effect/reactivity/Atom';
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import * as AppGraph from '@dxos/app-graph/AppGraph';
+import type * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
+import * as ToolkitHooks from '@dxos/app-toolkit/Hooks';
+import * as GraphHooks from '@dxos/plugin-graph/Hooks';
+import { useManager } from '@dxos/react-ui-attention';
+import { Path, Tree, type TreeSelectEvent } from '@dxos/react-ui-list';
+import * as Hooks from '@dxos/react-ui/Hooks';
+
+import { meta } from '#meta';
+import { DebugNodes } from '#types';
+
+import { useDebugPanelContext } from './DebugPanelContext.ts';
+import { debugPanelAspect } from './view-state.ts';
+
+const ROOT_PATH = [DebugNodes.DEBUG_ROOT_ID];
+
+/** The node and every ancestor under the debug root, so each level's connector runs. */
+const lineage = (nodeId: string): string[] => {
+  const segments = nodeId.split('/');
+  return segments
+    .map((_, index) => segments.slice(0, index + 1).join('/'))
+    .filter((id) => id.startsWith(DebugNodes.DEBUG_ROOT_ID));
+};
+
+/** Page ids the panel persisted before the pages lived under the Debug node. */
+const LEGACY_PAGE_IDS: Record<string, string> = {
+  [`${DebugNodes.DEBUG_ROOT_ID}/${DebugNodes.nodeId(DebugNodes.Console)}`]: DebugNodes.CONSOLE_NODE_ID,
+  [`${DebugNodes.DEBUG_ROOT_ID}/${DebugNodes.nodeId(DebugNodes.Logs)}`]: DebugNodes.LOGS_NODE_ID,
+};
+
+/** The tree over the hidden `root/debug` category: every developer tool, selected here and shown in `Main`. */
+export const DebugPanelSidebar = () => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  const { contextId, nodeId, open, select, setOpen } = useDebugPanelContext();
+  const { graph } = ToolkitHooks.useAppGraph();
+  const manager = useManager();
+  // The model reads state through atoms, and the manager's atom for this context is that state.
+  const stateAtom = useMemo(() => manager.atom(debugPanelAspect, contextId), [manager, contextId]);
+  const state = useMemo(
+    () => ({
+      itemOpen: (path: string[]) =>
+        Atom.make((get) => get(stateAtom).open.includes(Path.create(...path))).pipe(Atom.keepAlive),
+      itemCurrent: (path: string[]) =>
+        Atom.make((get) => get(stateAtom).nodeId === path[path.length - 1]).pipe(Atom.keepAlive),
+    }),
+    [stateAtom],
+  );
+  const model = GraphHooks.useGraphTreeModel(DebugNodes.DEBUG_ROOT_ID, state);
+
+  // Persisted state names nodes whose children come from connectors that only run on expansion, so
+  // without this an open branch restores empty and a nested selection restores to a blank page. A
+  // pristine panel opens on the console, as it did when the console was its first tab. The latest
+  // state is read through a ref so the restore runs once per context, not on every change.
+  const latestRef = useRef({ open, nodeId });
+  latestRef.current = { open, nodeId };
+  useEffect(() => {
+    AppGraph.expandSync(graph, DebugNodes.DEBUG_ROOT_ID, 'child');
+    const { open, nodeId } = latestRef.current;
+    if (!nodeId && open.length === 0) {
+      setOpen(Path.create(DebugNodes.DEBUG_ROOT_ID, contextId, DebugNodes.DEBUG_NODE_ID), true);
+      select(DebugNodes.CONSOLE_NODE_ID);
+    }
+    // The console and logs pages moved under the Debug node; a selection persisted at their old
+    // top-level ids is carried to the new ones.
+    const legacy = nodeId ? LEGACY_PAGE_IDS[nodeId] : undefined;
+    if (legacy) {
+      select(legacy);
+    }
+    for (const key of open) {
+      AppGraph.expandSync(graph, Path.last(key), 'child');
+    }
+    for (const id of lineage(legacy ?? nodeId ?? DebugNodes.CONSOLE_NODE_ID)) {
+      AppGraph.expandSync(graph, id, 'child');
+    }
+  }, [graph, contextId, select, setOpen]);
+
+  const handleOpenChange = useCallback(
+    ({ item, path, open }: { item: AppGraphNode.Node; path: string[]; open: boolean }) => {
+      setOpen(Path.create(...path), open);
+      AppGraph.expandSync(graph, item.id, 'child');
+    },
+    [graph, setOpen],
+  );
+
+  const handleSelect = useCallback(
+    ({ item, path }: TreeSelectEvent<AppGraphNode.Node>) => {
+      if (item.data === null) {
+        // A branch has no page: selecting it toggles it.
+        const key = Path.create(...path);
+        setOpen(key, !open.includes(key));
+        AppGraph.expandSync(graph, item.id, 'child');
+        return;
+      }
+      select(item.id);
+      AppGraph.expandSync(graph, item.id, 'child');
+    },
+    [graph, open, select, setOpen],
+  );
+
+  return (
+    <Tree.Root
+      id={contextId}
+      rootId={DebugNodes.DEBUG_ROOT_ID}
+      path={ROOT_PATH}
+      model={model}
+      size='sm'
+      onOpenChange={handleOpenChange}
+      onSelect={handleSelect}
+    >
+      <Tree.Label srOnly>{t('debug-panel.tree.label')}</Tree.Label>
+      <Tree.Content />
+    </Tree.Root>
+  );
+};
+
+DebugPanelSidebar.displayName = 'DebugPanel.Sidebar';

package/src/containers/DebugPanel/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './DebugPanel.tsx';
+export * from './DebugPanelContext.ts';
+export * from './DebugPanelHeader.tsx';
+export * from './DebugPanelMain.tsx';
+export * from './DebugPanelSidebar.tsx';
+export * from './view-state.ts';

package/src/containers/DebugPanel/view-state.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { ViewState } from '@dxos/react-ui-attention/types';
+
+// Kept out of `DebugPanel.tsx`: react-refresh only fast-refreshes a module whose exports are all
+// components, so a non-component export beside them forces a full page reload on every edit.
+
+const Point = Schema.Struct({ x: Schema.Number, y: Schema.Number });
+
+const Size = Schema.Struct({ width: Schema.Number, height: Schema.Number });
+
+const Mode = Schema.Literals(['floating', 'docked']);
+
+const DebugPanelViewStateSchema = Schema.Struct({
+  nodeId: Schema.optional(Schema.String),
+  mode: Schema.optional(Mode),
+  // Defaulted rather than required so a value persisted by the tab-based panel still decodes and
+  // keeps its position and size.
+  open: Schema.Array(Schema.String).pipe(Schema.withDecodingDefault(Effect.succeed([]))),
+  position: Schema.optional(Point),
+  size: Schema.optional(Size),
+});
+
+export type DebugPanelMode = Schema.Schema.Type<typeof Mode>;
+
+export type DebugPanelViewState = {
+  /** Qualified id of the selected page; absent until something is chosen. */
+  readonly nodeId?: string;
+  /** Docked in the deck's drawer or floating over the app; absent means docked. */
+  readonly mode?: DebugPanelMode;
+  /** Joined paths (`Path.create`) of the expanded branches. */
+  readonly open: readonly string[];
+  /** Where the floating panel was last left; absent until it has been dragged. */
+  readonly position?: Schema.Schema.Type<typeof Point>;
+  /** The size the floating panel was last resized to; absent until it has been. */
+  readonly size?: Schema.Schema.Type<typeof Size>;
+};
+
+/** The panel is a singleton in the status rail, so one context serves it. */
+export const DEBUG_PANEL_CONTEXT = 'debug-panel';
+
+/**
+ * Selection, expansion, mode, position and size, persisted (localStorage) so a debugging session survives
+ * the reloads it provokes; requires a `ViewStateProvider` ancestor to persist (degrades to the
+ * defaults without one).
+ */
+export const debugPanelAspect = ViewState.define<
+  DebugPanelViewState,
+  Schema.Codec.Encoded<typeof DebugPanelViewStateSchema>
+>({
+  key: 'debug-panel',
+  backend: 'local',
+  schema: DebugPanelViewStateSchema,
+  defaultValue: () => ({ open: [] }),
+});

package/src/containers/DebugPanelDrawer/DebugPanelDrawer.stories.tsx

@@ -0,0 +1,92 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import * as CorePlugins from '@dxos/plugin-testing/CorePlugins';
+import * as Main from '@dxos/react-ui/Main';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import * as DebugPlugin from '../../DebugPlugin.ts';
+import { StubDrawerPlugin, StubToolsPlugin, setDrawerState, useDrawerState } from '../../testing/index.ts';
+import { type DebugPanelViewState, debugPanelAspect } from '../DebugPanel/index.ts';
+import { DebugPanelDrawer, type DebugPanelDrawerProps } from './DebugPanelDrawer.tsx';
+
+/** The deck's frame with the drawer open, as `DeckContent` hosts the surface. */
+const Render = (props: DebugPanelDrawerProps) => {
+  const state = useDrawerState();
+  return (
+    <Main.Root drawerState={state} onDrawerStateChange={setDrawerState}>
+      <Main.Content classNames='p-4'>Main</Main.Content>
+      <Main.Drawer label='Drawer'>
+        <DebugPanelDrawer {...props} />
+      </Main.Drawer>
+    </Main.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-debug/containers/DebugPanelDrawer',
+  component: DebugPanelDrawer,
+  render: Render,
+  // The attention core plugin provides the view state the selection and mode persist through; the
+  // debug plugin contributes the console and log pages and their articles; the stubs add a branch
+  // and the drawer's layout handler.
+  decorators: [
+    withPluginManager({ plugins: [...CorePlugins.make(), DebugPlugin.make(), StubToolsPlugin(), StubDrawerPlugin()] }),
+    withTheme(),
+  ],
+  parameters: { translations, layout: 'fullscreen' },
+} satisfies Meta<typeof DebugPanelDrawer>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Its own context, so exercising the story does not decide which tool the app's drawer opens on. */
+export const Default: Story = {
+  args: { contextId: 'debug-panel-drawer-story' },
+};
+
+const FLOAT_CONTEXT = 'debug-panel-drawer-story-float';
+
+const readViewState = (): DebugPanelViewState | undefined => {
+  const raw = localStorage.getItem(`dxos:view-state:${debugPanelAspect.key}:${FLOAT_CONTEXT}`);
+  return raw ? JSON.parse(raw) : undefined;
+};
+
+/**
+ * Console by default, then Logs, then the float control: the drawer closes and the persisted mode
+ * records the switch — the part the floating host reads to take over.
+ */
+export const Float: Story = {
+  args: { contextId: FLOAT_CONTEXT },
+  loaders: [
+    () => {
+      localStorage.removeItem(`dxos:view-state:${debugPanelAspect.key}:${FLOAT_CONTEXT}`);
+      setDrawerState('open');
+    },
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const drawer = await canvas.findByRole('region', { name: 'Drawer' }, { timeout: 10_000 });
+    const tree = await within(drawer).findByRole('tree', {}, { timeout: 10_000 });
+    const terminal = await within(drawer).findByRole('textbox', {}, { timeout: 10_000 });
+    await expect(terminal).toBeInTheDocument();
+
+    // The terminal's input is xterm's transparent helper, so visibility is read off the page's show/hide element.
+    await userEvent.click(await within(tree).findByText('Logs', {}, { timeout: 10_000 }));
+    await expect(terminal.closest('[hidden]')).not.toBeNull();
+
+    await expect(readViewState()?.mode).toBeUndefined();
+    await userEvent.click(await within(drawer).findByTestId('debugPanel.mode'));
+    await waitFor(() => expect(readViewState()?.mode).toBe('floating'));
+    await waitFor(() => expect(canvas.queryByRole('region', { name: 'Drawer' })).toBeNull());
+  },
+};

package/src/containers/DebugPanelDrawer/DebugPanelDrawer.tsx

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import * as Hooks from '@dxos/app-framework/Hooks';
+import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
+import * as UiHooks from '@dxos/react-ui/Hooks';
+import * as Panel from '@dxos/react-ui/Panel';
+import * as Toolbar from '@dxos/react-ui/Toolbar';
+
+import { meta } from '#meta';
+
+import {
+  DEBUG_PANEL_CONTEXT,
+  DebugPanel,
+  DebugPanelHeader,
+  type DebugPanelMode,
+  useDebugPanelContext,
+} from '../DebugPanel/index.ts';
+
+export type DebugPanelDrawerProps = {
+  /** Overridable so a story gets its own selection rather than the app's. */
+  contextId?: string;
+};
+
+/**
+ * The debug panel docked as the deck's bottom drawer: a title bar over the tree and the page. It
+ * shares the floating window's context, so floating it keeps the tool that was open.
+ */
+export const DebugPanelDrawer = ({ contextId = DEBUG_PANEL_CONTEXT }: DebugPanelDrawerProps) => (
+  <DebugPanel.Root contextId={contextId}>
+    <DebugPanelDrawerContent />
+  </DebugPanel.Root>
+);
+
+DebugPanelDrawer.displayName = 'DebugPanelDrawer';
+
+const DebugPanelDrawerContent = () => {
+  const { t } = UiHooks.useTranslation(meta.profile.key);
+  const { mode, setMode } = useDebugPanelContext();
+  const { invokePromise } = Hooks.useOperationInvoker();
+
+  // Floating asks the drawer to close so the window the status bar opens on the mode change does
+  // not stay over it; docking keeps it open.
+  const handleModeChange = useCallback(
+    (next: DebugPanelMode) => {
+      void invokePromise(LayoutOperation.UpdateDrawer, { state: next === 'floating' ? 'closed' : 'open' });
+      setMode(next);
+    },
+    [invokePromise, setMode],
+  );
+  const handleClose = useCallback(
+    () => void invokePromise(LayoutOperation.UpdateDrawer, { state: 'closed' }),
+    [invokePromise],
+  );
+
+  return (
+    <Panel.Root>
+      <Panel.Header>
+        <Toolbar.Root size='sm'>
+          <Toolbar.Text classNames='grow'>{t('debug-panel.title')}</Toolbar.Text>
+          <DebugPanelHeader mode={mode} onModeChange={handleModeChange} onClose={handleClose} />
+        </Toolbar.Root>
+      </Panel.Header>
+      <Panel.Body classNames='grid'>
+        <DebugPanel.Body />
+      </Panel.Body>
+    </Panel.Root>
+  );
+};

package/src/containers/DebugPanelDrawer/index.ts

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

package/src/containers/DebugPanelStatus/DebugPanelStatus.stories.tsx

@@ -0,0 +1,119 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import * as CorePlugins from '@dxos/plugin-testing/CorePlugins';
+import {
+  type DebugPortController,
+  type DebugPortStartOptions,
+  type DebugPortStatus as DebugPortStatusType,
+} from '@dxos/react-client/devtools';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import * as DebugPlugin from '../../DebugPlugin.ts';
+import { StubDrawerPlugin, StubToolsPlugin, getDrawerState, setDrawerState } from '../../testing/index.ts';
+import { DEBUG_PANEL_CONTEXT, type DebugPanelViewState, debugPanelAspect } from '../DebugPanel/index.ts';
+import { DebugPanelStatus } from './DebugPanelStatus.tsx';
+
+/**
+ * Stand-in for the page-wide controller: the real one long-polls a loopback server and evaluates
+ * whatever it returns, which a story must never do.
+ */
+const createFakeController = (initial: Partial<DebugPortStatusType> = {}): DebugPortController => {
+  const listeners = new Set<() => void>();
+  let status: DebugPortStatusType = { running: false, ...initial };
+
+  const update = (patch: Partial<DebugPortStatusType>) => {
+    status = { ...status, ...patch };
+    listeners.forEach((listener) => listener());
+  };
+
+  return {
+    getStatus: () => status,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start: (_options?: DebugPortStartOptions) => {
+      const session = crypto.randomUUID();
+      update({ running: true, session, origin: 'http://127.0.0.1:9321' });
+      return session;
+    },
+    resume: () => undefined,
+    stop: () => update({ running: false, session: undefined, origin: undefined }),
+  };
+};
+
+const meta = {
+  title: 'plugins/plugin-debug/containers/DebugPanelStatus',
+  component: DebugPanelStatus,
+  // The window's tree reads the app graph the debug plugin (and the stub) populate; its selection
+  // and placement persist through the attention core plugin's view state; the drawer stub answers
+  // the docked toggle in the deck's stead.
+  decorators: [
+    withPluginManager({ plugins: [...CorePlugins.make(), DebugPlugin.make(), StubToolsPlugin(), StubDrawerPlugin()] }),
+    withTheme(),
+  ],
+  parameters: { translations },
+} satisfies Meta<typeof DebugPanelStatus>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** The status button reads the singleton context, so a story seeds and clears that one key. */
+const VIEW_STATE_KEY = `dxos:view-state:${debugPanelAspect.key}:${DEBUG_PANEL_CONTEXT}`;
+
+const seedViewState = (state: DebugPanelViewState | undefined) => () => {
+  if (state) {
+    localStorage.setItem(VIEW_STATE_KEY, JSON.stringify(state));
+  } else {
+    localStorage.removeItem(VIEW_STATE_KEY);
+  }
+};
+
+/** Docked by default: the button toggles the deck's drawer through the layout operation. */
+export const Default: Story = {
+  args: { controller: createFakeController() },
+  loaders: [
+    () => {
+      seedViewState(undefined)();
+      setDrawerState('closed');
+    },
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const button = await canvas.findByRole('button', { name: 'Show debug panel' });
+    await expect(getDrawerState()).toBe('closed');
+    await userEvent.click(button);
+    await waitFor(() => expect(getDrawerState()).toBe('open'));
+    await userEvent.click(button);
+    await waitFor(() => expect(getDrawerState()).toBe('closed'));
+    await expect(within(document.body).queryByRole('dialog', { name: 'Debug' })).toBeNull();
+  },
+};
+
+/** Floating: the button opens the panel as a window over the app. */
+export const Floating: Story = {
+  args: { controller: createFakeController() },
+  loaders: [seedViewState({ mode: 'floating', open: [] })],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(await canvas.findByRole('button', { name: 'Show debug panel' }));
+    // Portaled to the body, so the window is looked up on the document.
+    const body = within(document.body);
+    const dialog = await body.findByRole('dialog', { name: 'Debug' }, { timeout: 10_000 });
+    await expect(dialog).toHaveAttribute('data-state', 'open');
+    await expect(within(dialog).getByRole('heading', { name: 'Debug' })).toBeVisible();
+  },
+};
+
+export const PortOpen: Story = {
+  args: { controller: createFakeController({ running: true, session: 'story-session' }) },
+};