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

package/src/containers/DebugConsole/cli.ts

@@ -0,0 +1,296 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Args from 'effect/cli/Argument';
+import * as Command from 'effect/cli/Command';
+import * as Flag from 'effect/cli/Flag';
+import * as Console from 'effect/Console';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import * as Capabilities from '@dxos/app-framework/Capabilities';
+import * as Capability from '@dxos/app-framework/Capability';
+import type * as Devtools from '@dxos/app-framework/Devtools';
+import * as Plugin from '@dxos/app-framework/Plugin';
+import type * as PluginManager from '@dxos/app-framework/PluginManager';
+import type * as Operation from '@dxos/compute/Operation';
+import { BaseError } from '@dxos/errors';
+import { SpaceId } from '@dxos/keys';
+import { getDebugPortController } from '@dxos/react-client/devtools';
+
+import { DebugOperationError } from '../../operations/errors.ts';
+
+/**
+ * The debug console's command set — the introspection surface an agent uses over the debug port
+ * (operations, snapshot, plugin management), driveable by hand. Operations are invoked through the
+ * same invoker the agent path uses, so the two surfaces cannot drift.
+ */
+export type DebugCli = {
+  command: ReturnType<typeof makeCommand>;
+  layer: Layer.Layer<Plugin.Service | Capability.Service, never, never>;
+};
+
+export type DebugCliOptions = {
+  /** Receives each command result as printed — the clipboard source for "copy last result". */
+  onResult?: (text: string) => void;
+};
+
+const normalizeKey = (key: unknown): string => String(key).replace(/^dxn:/, '');
+
+/**
+ * The Linear label the PostHog feedback submissions sync under; console-filed issues carry it too
+ * so both sources land in one triage view.
+ */
+const REPORT_LABEL = 'Composer Feedback Form';
+
+const findDefinition = Effect.fn(function* (key: string) {
+  const capabilities = (yield* Plugin.Service).capabilities;
+  const wanted = normalizeKey(key);
+  for (const set of capabilities.getAll(Capabilities.OperationHandler)) {
+    const definition = set.definitions().find((candidate) => normalizeKey(candidate.meta.key) === wanted);
+    if (definition) {
+      return definition;
+    }
+  }
+  return yield* Effect.fail(new DebugOperationError({ message: `Unknown operation: ${key} (try "ops").` }));
+});
+
+const invokeOperation = Effect.fn(function* (key: string, input: unknown, spaceId?: SpaceId) {
+  const capabilities = (yield* Plugin.Service).capabilities;
+  const definition = yield* findDefinition(key);
+  const invoker = capabilities.get(Capabilities.OperationInvoker);
+  const { data, error } = yield* Effect.promise(() =>
+    invoker.invokePromise(definition as Operation.Definition.Any, input as never, spaceId ? { spaceId } : undefined),
+  );
+  if (error) {
+    return yield* Effect.fail(error instanceof BaseError ? error : DebugOperationError.wrap()(error));
+  }
+  return data;
+});
+
+/** Results may hold live objects; a snapshot of what is printable beats a serializer crash. */
+const format = (value: unknown): string => {
+  if (value === undefined) {
+    return 'undefined';
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  try {
+    return JSON.stringify(value, null, 2) ?? String(value);
+  } catch {
+    return String(value);
+  }
+};
+
+/**
+ * Evaluates a snippet with the same bindings the agent debug port provides (`dxos`, `composer`).
+ * Tried as an expression first so `1 + 1` works; statements fall back to an async body.
+ */
+const evalSnippet = (code: string): Promise<unknown> => {
+  const compile = () => {
+    try {
+      // eslint-disable-next-line no-implied-eval -- eval is this console's purpose, same as the debug port.
+      return new Function('dxos', 'composer', `'use strict'; return (async () => (${code}))();`);
+    } catch {
+      // eslint-disable-next-line no-implied-eval -- as above; statement-shaped snippets need a body.
+      return new Function('dxos', 'composer', `'use strict'; return (async () => { ${code} })();`);
+    }
+  };
+  const composer: Devtools.ComposerDevtools | undefined = globalThis.composer;
+  return Promise.resolve(compile()(Reflect.get(globalThis, '__DXOS__'), composer));
+};
+
+const makeCommand = (options: DebugCliOptions = {}) => {
+  const print = (value: unknown) =>
+    Effect.suspend(() => {
+      const text = format(value);
+      options.onResult?.(text);
+      return Console.log(text);
+    });
+
+  const snapshot = Command.make('snapshot', {}, () =>
+    Effect.gen(function* () {
+      yield* print(yield* invokeOperation('org.dxos.operation.debug.snapshot', {}));
+    }),
+  ).pipe(Command.withDescription('One JSON document of the live UI state: layout, attention, planks, actions.'));
+
+  const plugins = Command.make(
+    'plugins',
+    {
+      all: Flag.Boolean('all').pipe(Flag.withDefault(false), Flag.withDescription('Include disabled plugins.')),
+    },
+    ({ all }) =>
+      Effect.gen(function* () {
+        const manager = yield* Plugin.Service;
+        const enabled = new Set(manager.getEnabled());
+        const active = new Set(manager.getActive());
+        const rows = manager
+          .getPlugins()
+          .map((plugin) => {
+            const id = plugin.meta.profile.key;
+            return {
+              id,
+              enabled: enabled.has(id),
+              active: plugin.modules.some((module) => active.has(module.id)),
+            };
+          })
+          .filter((row) => all || row.enabled);
+        yield* print(rows);
+      }),
+  ).pipe(Command.withDescription('List plugins on this host.'));
+
+  const enable = Command.make(
+    'enable',
+    {
+      ids: Args.String('ids').pipe(Args.withDescription('Plugin ids.'), Args.variadic({ min: 1 })),
+    },
+    ({ ids }) =>
+      Effect.gen(function* () {
+        yield* print(yield* invokeOperation('org.dxos.operation.registry.enablePlugins', { ids }));
+      }),
+  ).pipe(Command.withDescription('Enable plugins (with their dependencies).'));
+
+  const disable = Command.make(
+    'disable',
+    {
+      ids: Args.String('ids').pipe(Args.withDescription('Plugin ids.'), Args.variadic({ min: 1 })),
+    },
+    ({ ids }) =>
+      Effect.gen(function* () {
+        yield* print(yield* invokeOperation('org.dxos.operation.registry.disablePlugins', { ids }));
+      }),
+  ).pipe(Command.withDescription('Disable plugins (with their enabled dependents).'));
+
+  const ops = Command.make(
+    'ops',
+    {
+      filter: Args.String('filter').pipe(
+        Args.withDescription('Substring filter on the key.'),
+        Args.variadic({ max: 1 }),
+      ),
+    },
+    ({ filter }) =>
+      Effect.gen(function* () {
+        const capabilities = (yield* Plugin.Service).capabilities;
+        const needle = filter[0]?.toLowerCase();
+        const keys = new Set<string>();
+        for (const set of capabilities.getAll(Capabilities.OperationHandler)) {
+          for (const definition of set.definitions()) {
+            const key = normalizeKey(definition.meta.key);
+            if (!needle || key.toLowerCase().includes(needle)) {
+              keys.add(key);
+            }
+          }
+        }
+        yield* print([...keys].sort());
+      }),
+  ).pipe(Command.withDescription('List invokable operations.'));
+
+  const invoke = Command.make(
+    'invoke',
+    {
+      key: Args.String('key').pipe(Args.withDescription('Operation key (bare or dxn: form).')),
+      input: Args.String('input').pipe(Args.withDescription('JSON input; defaults to {}.'), Args.variadic({ max: 1 })),
+      space: Flag.String('space').pipe(
+        Flag.optional,
+        Flag.withDescription('Space id, for operations that declare a database service.'),
+      ),
+    },
+    ({ key, input, space }) =>
+      Effect.gen(function* () {
+        const parsed: unknown = input[0] ? JSON.parse(input[0]) : {};
+        const spaceId = space._tag === 'Some' ? SpaceId.make(space.value) : undefined;
+        yield* print(yield* invokeOperation(key, parsed, spaceId));
+      }),
+  ).pipe(Command.withDescription('Invoke an operation with a JSON payload.'));
+
+  const evaluate = Command.make(
+    'eval',
+    {
+      code: Args.String('code').pipe(Args.withDescription('JavaScript to evaluate.'), Args.variadic({ min: 1 })),
+    },
+    ({ code }) =>
+      Effect.gen(function* () {
+        yield* print(yield* Effect.promise(() => evalSnippet(code.join(' '))));
+      }),
+  ).pipe(Command.withDescription('Evaluate a snippet with `dxos` and `composer` in scope.'));
+
+  const report = Command.make(
+    'report',
+    {
+      title: Args.String('title').pipe(Args.withDescription('Issue title.'), Args.variadic({ min: 1 })),
+      body: Flag.String('body').pipe(Flag.optional, Flag.withDescription('Issue body; defaults to the title.')),
+      type: Flag.String('type').pipe(Flag.optional, Flag.withDescription('bug | feature.')),
+      severity: Flag.String('severity').pipe(
+        Flag.optional,
+        Flag.withDescription('"High priority" | "Medium priority" | "Low priority".'),
+      ),
+      label: Flag.String('label').pipe(
+        Flag.optional,
+        Flag.withDescription(`Linear label; defaults to "${REPORT_LABEL}".`),
+      ),
+      noLogs: Flag.Boolean('no-logs').pipe(Flag.withDefault(false), Flag.withDescription('Skip the debug log dump.')),
+    },
+    ({ title, body, type, severity, label, noLogs }) =>
+      Effect.gen(function* () {
+        const heading = title.join(' ');
+        const result = yield* invokeOperation('org.dxos.operation.support.submitIssue', {
+          report: {
+            title: heading,
+            // The report schema requires a description, so a bare `report <title>` repeats the title.
+            body: body._tag === 'Some' && body.value.trim() ? body.value : heading,
+            ...(type._tag === 'Some' ? { type: type.value } : {}),
+            ...(severity._tag === 'Some' ? { severity: severity.value } : {}),
+            labels: [label._tag === 'Some' ? label.value : REPORT_LABEL],
+            includeLogs: !noLogs,
+          },
+        });
+        const issue = result as { issueIdentifier?: string; issueUrl?: string } | undefined;
+        yield* print(issue?.issueUrl ? `${issue.issueIdentifier} ${issue.issueUrl}` : result);
+      }),
+  ).pipe(Command.withDescription('File a Linear issue with the logs attached.'), Command.unlisted);
+
+  const port = Command.make(
+    'port',
+    {
+      action: Args.String('action').pipe(
+        Args.withDescription('start | stop; omit for status.'),
+        Args.variadic({ max: 1 }),
+      ),
+    },
+    ({ action }) =>
+      Effect.gen(function* () {
+        const controller = getDebugPortController();
+        switch (action[0]) {
+          case 'start': {
+            const session = controller.start({ persist: true });
+            yield* print(`Session: ${session}`);
+            break;
+          }
+          case 'stop': {
+            controller.stop();
+            yield* print('Stopped.');
+            break;
+          }
+          default: {
+            yield* print(controller.getStatus());
+          }
+        }
+      }),
+  ).pipe(Command.withDescription('Agent debug port: status, start, stop.'));
+
+  return Command.make('debug').pipe(
+    Command.withDescription('Composer debug console.'),
+    Command.withSubcommands([snapshot, plugins, enable, disable, ops, invoke, evaluate, report, port]),
+  );
+};
+
+export const createDebugCli = (manager: PluginManager.PluginManager, options?: DebugCliOptions): DebugCli => ({
+  command: makeCommand(options),
+  layer: Layer.mergeAll(
+    Layer.succeed(Plugin.Service, manager),
+    Layer.succeed(Capability.Service, manager.capabilities),
+  ),
+});

package/src/containers/DebugConsole/index.ts

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

package/src/containers/DebugObjectPanel/DebugObjectPanel.tsx

@@ -4,13 +4,15 @@
 
 import React, { useMemo, useState } from 'react';
 
-import { AppSurface } from '@dxos/app-toolkit/ui';
+import * as AppSurface from '@dxos/app-toolkit/AppSurface';
 import { ObjectsTree } from '@dxos/devtools';
 import { type Entity, Filter, Json, Obj, Query } from '@dxos/echo';
 import { useQuery } from '@dxos/echo-react';
 import type { EntityId } from '@dxos/keys';
-import { Clipboard, Panel, ScrollArea, Toolbar } from '@dxos/react-ui';
 import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import * as Panel from '@dxos/react-ui/Panel';
+import * as ScrollArea from '@dxos/react-ui/ScrollArea';
+import * as Toolbar from '@dxos/react-ui/Toolbar';
 import { mx } from '@dxos/ui-theme';
 
 export type DebugObjectPanelProps = Pick<
@@ -37,48 +39,46 @@ export const DebugObjectPanel = ({ role, companionTo, onOpen, canOpen }: DebugOb
   const [selectedObject] = useQuery(db, selectionQuery);
 
   return (
-    <Clipboard.Provider>
-      <Panel.Root role={role}>
-        <Panel.Toolbar asChild>
-          <Toolbar.Root />
-        </Panel.Toolbar>
-        <Panel.Content asChild>
-          <div className={mx('grid divide-y divide-subdued-separator', db && 'grid-rows-[1fr_2fr]')}>
-            {db && (
-              <ScrollArea.Root>
-                <ScrollArea.Viewport>
-                  <ObjectsTree
-                    db={db}
-                    root={companionTo}
-                    onSelect={(entity) => setSelectedId(entity.id)}
-                    onOpen={onOpen}
-                    canOpen={canOpen}
-                  />
-                </ScrollArea.Viewport>
-              </ScrollArea.Root>
-            )}
-            <Syntax.Root
-              data={selectedObject}
-              getReplacer={(depth) => (db ? Json.createRefReplacer({ db, depth }) : undefined)}
-            >
-              <Panel.Root>
-                <Panel.Toolbar asChild>
-                  <Toolbar.Root classNames='grid grid-cols-[1fr_3rem]'>
-                    <Syntax.Filter />
-                    <Syntax.Depth />
-                  </Toolbar.Root>
-                </Panel.Toolbar>
-                <Panel.Content asChild>
-                  <Syntax.Viewport>
-                    <Syntax.Code />
-                  </Syntax.Viewport>
-                </Panel.Content>
-              </Panel.Root>
-            </Syntax.Root>
-          </div>
-        </Panel.Content>
-      </Panel.Root>
-    </Clipboard.Provider>
+    <Panel.Root role={role}>
+      <Panel.Header>
+        <Toolbar.Root />
+      </Panel.Header>
+      <Panel.Body asChild>
+        <div className={mx('grid divide-y divide-separator-subtle', db && 'grid-rows-[1fr_2fr]')}>
+          {db && (
+            <ScrollArea.Root>
+              <ScrollArea.Viewport>
+                <ObjectsTree
+                  db={db}
+                  root={companionTo}
+                  onSelect={(entity) => setSelectedId(entity.id)}
+                  onOpen={onOpen}
+                  canOpen={canOpen}
+                />
+              </ScrollArea.Viewport>
+            </ScrollArea.Root>
+          )}
+          <Syntax.Root
+            data={selectedObject}
+            getReplacer={(depth) => (db ? Json.createRefReplacer({ db, depth }) : undefined)}
+          >
+            <Panel.Root>
+              <Panel.Header>
+                <Toolbar.Root classNames='grid grid-cols-[1fr_6rem]'>
+                  <Syntax.Filter />
+                  <Syntax.Depth />
+                </Toolbar.Root>
+              </Panel.Header>
+              <Panel.Body asChild>
+                <Syntax.Viewport>
+                  <Syntax.Code />
+                </Syntax.Viewport>
+              </Panel.Body>
+            </Panel.Root>
+          </Syntax.Root>
+        </div>
+      </Panel.Body>
+    </Panel.Root>
   );
 };
 

package/src/containers/DebugObjectPanel/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2024 DXOS.org
 //
 
-export { DebugObjectPanel as default } from './DebugObjectPanel';
+export { DebugObjectPanel as default } from './DebugObjectPanel.tsx';

package/src/containers/DebugPanel/DebugPanel.stories.tsx

@@ -0,0 +1,118 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { expect, userEvent, within } from 'storybook/test';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import * as CorePlugins from '@dxos/plugin-testing/CorePlugins';
+import { Path } from '@dxos/react-ui-list';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+import { DebugNodes } from '#types';
+
+import * as DebugPlugin from '../../DebugPlugin.ts';
+import { STUB_TOOL_PAGES, STUB_TOOLS_BRANCH, StubToolsPlugin } from '../../testing/index.ts';
+import { DebugPanel, type DebugPanelRootProps } from './DebugPanel.tsx';
+import { type DebugPanelViewState, debugPanelAspect } from './view-state.ts';
+
+/**
+ * The body as every host splits it, sized by the story: the tree over the hidden debug category
+ * beside the selected tool's article. Selection and open branches come from persisted view state,
+ * so choosing a tool here survives a reload of the story.
+ */
+const Render = (props: DebugPanelRootProps) => (
+  <div className='h-[24rem] w-[64rem] max-w-full grid'>
+    <DebugPanel.Root {...props}>
+      <DebugPanel.Body />
+    </DebugPanel.Root>
+  </div>
+);
+
+const meta = {
+  title: 'plugins/plugin-debug/containers/DebugPanel',
+  component: DebugPanel.Root,
+  render: Render,
+  decorators: [
+    // The attention core plugin provides the view state the selection persists through; the debug
+    // plugin contributes the console and log pages and their articles; the stub adds a branch.
+    withPluginManager({ plugins: [...CorePlugins.make(), DebugPlugin.make(), StubToolsPlugin()] }),
+    withTheme(),
+    withLayout({ layout: 'centered' }),
+  ],
+  parameters: { translations },
+} satisfies Meta<typeof DebugPanel.Root>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** Its own context, so exercising the story does not decide which tool the app's rail opens on. */
+export const Default: Story = {
+  args: { contextId: 'debug-panel-story' },
+};
+
+/**
+ * Console, then Logs, then a stub page under the branch, then the console again: the console stays
+ * mounted (hidden) throughout, while the stub page is gone once it is no longer selected.
+ */
+export const Select: Story = {
+  args: { contextId: 'debug-panel-story-select' },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const tree = await canvas.findByRole('tree', {}, { timeout: 10_000 });
+    await userEvent.click(await within(tree).findByText('Console', {}, { timeout: 10_000 }));
+    const terminal = await canvas.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();
+
+    const [page] = STUB_TOOL_PAGES;
+    await userEvent.click(await within(tree).findByText('Tools', {}, { timeout: 10_000 }));
+    await userEvent.click(await within(tree).findByText(page.label, {}, { timeout: 10_000 }));
+    const stubPage = await canvas.findByTestId(`stubTool.${page.id}`, {}, { timeout: 10_000 });
+    await expect(stubPage).toBeVisible();
+    // The same console element is still there behind the page shown.
+    await expect(terminal).toBeInTheDocument();
+
+    await userEvent.click(await within(tree).findByText('Console', {}, { timeout: 10_000 }));
+    await expect(terminal.closest('[hidden]')).toBeNull();
+    // A page that is not the console or logs is mounted only while it is selected.
+    await expect(stubPage).not.toBeInTheDocument();
+  },
+};
+
+const RESTORE_CONTEXT = 'debug-panel-story-restore';
+
+/** What the local backend persists for a context: the tree's open keys carry its id (`Tree` appends it to the path). */
+const restoredState: DebugPanelViewState = {
+  nodeId: `${DebugNodes.DEBUG_ROOT_ID}/${STUB_TOOLS_BRANCH}/${STUB_TOOL_PAGES[1].id}`,
+  open: [Path.create(DebugNodes.DEBUG_ROOT_ID, RESTORE_CONTEXT, `${DebugNodes.DEBUG_ROOT_ID}/${STUB_TOOLS_BRANCH}`)],
+};
+
+/**
+ * A reload with a page selected under an open branch: the branch's pages come from a connector that
+ * only runs on expansion, so the panel has to expand what the persisted state names before either
+ * the row or the page can render.
+ */
+export const Restore: Story = {
+  args: { contextId: RESTORE_CONTEXT },
+  loaders: [
+    () => {
+      localStorage.setItem(`dxos:view-state:${debugPanelAspect.key}:${RESTORE_CONTEXT}`, JSON.stringify(restoredState));
+    },
+  ],
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const page = STUB_TOOL_PAGES[1];
+    await expect(await canvas.findByTestId(`stubTool.${page.id}`, {}, { timeout: 10_000 })).toBeVisible();
+    const tree = await canvas.findByRole('tree', {}, { timeout: 10_000 });
+    const row = (await within(tree).findByText(page.label, {}, { timeout: 10_000 })).closest('[role="treeitem"]');
+    await expect(row).toHaveAttribute('aria-selected', 'true');
+  },
+};

package/src/containers/DebugPanel/DebugPanel.tsx

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type PropsWithChildren, useCallback, useMemo } from 'react';
+
+import { useViewState, useViewStateActions } from '@dxos/react-ui-attention';
+import * as Splitter from '@dxos/react-ui/Splitter';
+
+import { DebugPanelContext, type DebugPanelContextValue } from './DebugPanelContext.ts';
+import { DebugPanelMain } from './DebugPanelMain.tsx';
+import { DebugPanelSidebar } from './DebugPanelSidebar.tsx';
+import { DEBUG_PANEL_CONTEXT, type DebugPanelMode, debugPanelAspect } from './view-state.ts';
+
+export type DebugPanelRootProps = PropsWithChildren<{
+  /** Overridable so a second host (or a story) gets its own selection rather than the rail's. */
+  contextId?: string;
+}>;
+
+/**
+ * The debug surface in parts, so a host places the tree and the page where the room is — the
+ * floating window and the deck's drawer both split them under a title bar. `Root` owns the
+ * selection, the expanded branches and the mode, persisted so a debugging session survives the
+ * reloads it provokes.
+ */
+const DebugPanelRoot = ({ contextId = DEBUG_PANEL_CONTEXT, children }: DebugPanelRootProps) => {
+  const { nodeId, open, mode = 'docked' } = useViewState(debugPanelAspect, contextId);
+  const { update } = useViewStateActions(debugPanelAspect, contextId);
+  const select = useCallback((nodeId: string) => update((prev) => ({ ...prev, nodeId })), [update]);
+  const setOpen = useCallback(
+    (pathKey: string, isOpen: boolean) =>
+      update((prev) => ({
+        ...prev,
+        open: isOpen ? [...new Set([...prev.open, pathKey])] : prev.open.filter((key) => key !== pathKey),
+      })),
+    [update],
+  );
+  const setMode = useCallback((mode: DebugPanelMode) => update((prev) => ({ ...prev, mode })), [update]);
+  const value = useMemo<DebugPanelContextValue>(
+    () => ({ contextId, nodeId, open, mode, select, setOpen, setMode }),
+    [contextId, nodeId, open, mode, select, setOpen, setMode],
+  );
+
+  return <DebugPanelContext.Provider value={value}>{children}</DebugPanelContext.Provider>;
+};
+
+DebugPanelRoot.displayName = 'DebugPanel.Root';
+
+/** The tree's opening width (rem): a navtree sidebar's, so tool labels read at the scale they do there. */
+const SIDEBAR_SIZE = 16;
+
+/** The tree beside the selected tool's page, split the same way in every host. */
+const DebugPanelBody = () => (
+  <Splitter.Root orientation='horizontal' anchor='start' resizable defaultSize={SIDEBAR_SIZE} minSize={8}>
+    <Splitter.Panel position='start'>
+      <DebugPanelSidebar />
+    </Splitter.Panel>
+    <Splitter.ResizeTrigger />
+    <Splitter.Panel position='end'>
+      <DebugPanelMain />
+    </Splitter.Panel>
+  </Splitter.Root>
+);
+
+DebugPanelBody.displayName = 'DebugPanel.Body';
+
+export const DebugPanel = {
+  Root: DebugPanelRoot,
+  Body: DebugPanelBody,
+  Sidebar: DebugPanelSidebar,
+  Main: DebugPanelMain,
+};

package/src/containers/DebugPanel/DebugPanelContext.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext, useContext } from 'react';
+
+import { type DebugPanelMode } from './view-state.ts';
+
+// Kept out of `DebugPanel.tsx`: the sidebar and main parts read the context the root provides, and
+// a module importing its own importers is a cycle.
+
+export type DebugPanelContextValue = {
+  contextId: string;
+  /** Qualified id of the selected page. */
+  nodeId?: string;
+  /** Joined paths of the expanded branches. */
+  open: readonly string[];
+  /** Where the panel is hosted; the hosts read it to decide which of them shows. */
+  mode: DebugPanelMode;
+  select: (nodeId: string) => void;
+  setOpen: (pathKey: string, open: boolean) => void;
+  setMode: (mode: DebugPanelMode) => void;
+};
+
+export const DebugPanelContext = createContext<DebugPanelContextValue | null>(null);
+
+export const useDebugPanelContext = (): DebugPanelContextValue => {
+  const value = useContext(DebugPanelContext);
+  if (!value) {
+    throw new Error('Missing DebugPanelContext');
+  }
+  return value;
+};