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

package/src/types/DebugOperation.ts

@@ -7,6 +7,7 @@
 import * as Schema from 'effect/Schema';
 
 import * as Capability from '@dxos/app-framework/Capability';
+import * as Plugin from '@dxos/app-framework/Plugin';
 import * as Operation from '@dxos/compute/Operation';
 import { DXN } from '@dxos/echo';
 import * as MarkdownOperation from '@dxos/plugin-markdown/MarkdownOperation';
@@ -28,3 +29,208 @@ export const InsertLoremIpsum = Operation.make({
   // operation layer to the editor.
   services: [Capability.Service],
 });
+
+/**
+ * Shows a page of the debug panel — a node under `root/debug`, which has no URL for
+ * `LayoutOperation.Open` — opening the docked drawer when the panel is docked.
+ */
+export const OpenPage = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.debug.openPage'),
+    name: 'Open debug page',
+    description: 'Selects a page of the debug panel by its qualified graph id and shows the panel.',
+    icon: 'ph--terminal-window--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({
+    nodeId: Schema.String.annotate({ description: 'Qualified graph id of the page, under `root/debug`.' }),
+  }),
+  output: Schema.Void,
+});
+
+const LayoutSummary = Schema.Struct({
+  mode: Schema.String,
+  sidebarOpen: Schema.Boolean,
+  complementarySidebarOpen: Schema.Boolean,
+  dialogOpen: Schema.Boolean,
+  workspace: Schema.String,
+  active: Schema.Array(Schema.String).annotate({
+    description: 'Graph path ids of the open planks — the ids layout open/close operations accept.',
+  }),
+  inactive: Schema.Array(Schema.String),
+  scrollIntoView: Schema.optional(Schema.String),
+});
+
+const SubjectSummary = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  dxn: Schema.optional(Schema.String),
+  typename: Schema.optional(Schema.String),
+  name: Schema.optional(Schema.String),
+  text: Schema.optional(Schema.String).annotate({
+    description: 'The current text of a markdown document, so an edit can be judged without the editor.',
+  }),
+});
+
+const ActionSummary = Schema.Struct({
+  id: Schema.String,
+  label: Schema.optional(Schema.String),
+  icon: Schema.optional(Schema.String),
+  disabled: Schema.optional(Schema.Boolean),
+  operation: Schema.optional(Schema.String).annotate({
+    description: 'Operation DXN embedded in the action id — invokable via the operation invoker.',
+  }),
+  group: Schema.optional(Schema.Boolean),
+});
+
+const CommentMessageSummary = Schema.Struct({
+  id: Schema.String,
+  sender: Schema.optional(Schema.String),
+  text: Schema.optional(Schema.String),
+});
+
+const CommentThreadSummary = Schema.Struct({
+  id: Schema.String,
+  anchorId: Schema.String.annotate({
+    description: 'Id of the `AnchoredTo` relation that ties the thread to the subject.',
+  }),
+  anchor: Schema.optional(Schema.String),
+  status: Schema.optional(Schema.String),
+  messages: Schema.Array(CommentMessageSummary),
+});
+
+const PlankSummary = Schema.Struct({
+  id: Schema.String,
+  label: Schema.optional(Schema.String),
+  type: Schema.optional(Schema.String),
+  subject: Schema.optional(SubjectSummary),
+  actions: Schema.Array(ActionSummary),
+  comments: Schema.optional(Schema.Array(CommentThreadSummary)).annotate({
+    description: "Comment threads anchored to the plank's subject, when it is a database object.",
+  }),
+});
+
+const SurfaceSummary = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  role: Schema.optional(Schema.String),
+  component: Schema.optional(Schema.String),
+});
+
+const SpaceSummary = Schema.Struct({
+  id: Schema.String,
+  name: Schema.optional(Schema.String),
+  state: Schema.String.annotate({ description: 'The `SpaceState` name, e.g. `SPACE_READY`.' }),
+  default: Schema.optional(Schema.Boolean),
+});
+
+const ToastSummary = Schema.Struct({
+  title: Schema.optional(Schema.String),
+  description: Schema.optional(Schema.String),
+  actions: Schema.Array(Schema.String).annotate({ description: "Labels of the toast's buttons." }),
+});
+
+const ErrorSummary = Schema.Struct({
+  timestamp: Schema.Number,
+  message: Schema.optional(Schema.String),
+  error: Schema.optional(Schema.String),
+  file: Schema.optional(Schema.String),
+});
+
+/**
+ * One JSON document describing the live UI state — layout, attention, open planks with their
+ * subjects and reachable actions, mounted surfaces, and plugin counts — so an agent can infer what
+ * the user sees and what it can do without screenshots. See app-framework/docs/INTROSPECTION.md.
+ */
+export const Snapshot = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.debug.snapshot'),
+    name: 'UI Snapshot',
+    description:
+      'Returns a JSON snapshot of the live UI state: layout (mode, sidebars, open planks), attended ' +
+      'items, each open plank with its subject object and the actions the UI offers for it (with ' +
+      'their operation keys) and the comment threads on it, the mounted surfaces, the spaces, the visible toasts, the errors ' +
+      'logged since `since` (a timestamp; default: the last minute), and plugin counts. Read-only.',
+    icon: 'ph--camera--regular',
+  },
+  services: [Capability.Service, Plugin.Service],
+  input: Schema.Struct({
+    since: Schema.optional(Schema.Number).annotate({
+      description: 'Only errors logged at or after this unix timestamp (ms) are reported.',
+    }),
+  }),
+  output: Schema.Struct({
+    layout: Schema.optional(LayoutSummary),
+    attention: Schema.Array(Schema.String),
+    planks: Schema.Array(PlankSummary),
+    surfaces: Schema.Array(SurfaceSummary),
+    spaces: Schema.Array(SpaceSummary),
+    toasts: Schema.Array(ToastSummary),
+    errors: Schema.Array(ErrorSummary),
+    plugins: Schema.Struct({
+      installed: Schema.Number,
+      enabled: Schema.Number,
+      active: Schema.Number,
+    }),
+  }),
+}).pipe(Operation.mutation('none'));
+
+/**
+ * Undoes the last undoable operation — what the notification toast's **Undo** button does — so an
+ * agent driving the app through operations can exercise the undo path it cannot click.
+ */
+export const Undo = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.debug.revertLast'),
+    name: 'Revert last operation',
+    description: 'Undoes the last undoable operation, as the undo toast does. Fails when there is nothing to undo.',
+    icon: 'ph--arrow-counter-clockwise--regular',
+  },
+  services: [Capability.Service],
+  input: Schema.Struct({}),
+  output: Schema.Struct({
+    undone: Schema.Boolean,
+  }),
+});
+
+const SpaceTemplateSummary = Schema.Struct({
+  id: Schema.String,
+  label: Schema.String,
+  description: Schema.optional(Schema.String),
+});
+
+/**
+ * Creates a space from one of the templates plugins contribute, so an agent driving the debug port
+ * can seed a realistic space without clicking through the generator panel.
+ *
+ * TODO(wittjosiah): Reconcile with `SpaceOperation.Create`, which also takes a `template`. This adds
+ * only the listing (call without `id`) and deleting the space when the apply fails; the rest it
+ * hand-rolls because `Create` applies the template before the caller holds the space. Rollback
+ * belongs in `Create` for every caller or nowhere, and the listing belongs in a read-only
+ * operation rather than in a create that means something else when an argument is absent.
+ */
+export const CreateSpaceFromTemplate = Operation.make({
+  meta: {
+    key: DXN.make('org.dxos.operation.debug.createSpaceFromTemplate'),
+    name: 'Create Space From Template',
+    description:
+      'Creates a new space and fills it from a themed space template. Call without `id` to list ' +
+      'what is available without creating anything; the listing is the only way to learn the ids.',
+    icon: 'ph--dice-five--regular',
+  },
+  // The contributing modules are demand-gated, so the handler fires the activation event itself.
+  services: [Capability.Service, Plugin.Service],
+  input: Schema.Struct({
+    id: Schema.optional(Schema.String).annotate({
+      description: 'Space template id. Omit to list the available templates without creating anything.',
+    }),
+  }),
+  output: Schema.Struct({
+    applied: Schema.optional(SpaceTemplateSummary).annotate({
+      description: 'The template that was written; absent when listing.',
+    }),
+    spaceId: Schema.optional(Schema.String),
+    subject: Schema.optional(Schema.Array(Schema.String)).annotate({
+      description: 'Navigation path of the new space, for a follow-up open.',
+    }),
+    available: Schema.Array(SpaceTemplateSummary),
+  }),
+}).pipe(Operation.mutation('write'));

package/src/types/DebugSurface.ts

@@ -5,6 +5,7 @@
 // @import-as-namespace
 
 import * as Role from '@dxos/app-framework/Role';
+import type * as AppSurface from '@dxos/app-toolkit/AppSurface';
 
 import { meta } from '#meta';
 
@@ -14,3 +15,9 @@ import { meta } from '#meta';
  * the surface reads the store directly, so it needs no subject.
  */
 export const Stats = Role.make<Record<string, unknown>>(`${meta.profile.key}.surface.stats`);
+
+/** Article data for a page of the debug panel, whose nodes have no URL for `LayoutOperation.Open`. */
+export type PageData = AppSurface.ArticleData<unknown, { onNavigate: (nodeId: string) => void }>;
+
+/** Role token for a page of the debug panel; every node under `root/debug` registers its surface on it. */
+export const Page = Role.make<PageData>(`${meta.profile.key}.surface.page`);

package/src/types/index.ts

@@ -2,9 +2,9 @@
 // Copyright 2026 DXOS.org
 //
 
-export * as Debug from './Debug';
-export * as DebugEvents from './DebugEvents';
-export * as DebugNodes from './DebugNodes';
-export * as DebugOperation from './DebugOperation';
-export * as DebugSurface from './DebugSurface';
-export * as Settings from './Settings';
+export * as Debug from './Debug.ts';
+export * as DebugEvents from './DebugEvents.ts';
+export * as DebugNodes from './DebugNodes.ts';
+export * as DebugOperation from './DebugOperation.ts';
+export * as DebugSurface from './DebugSurface.ts';
+export * as Settings from './Settings.ts';

package/dist/lib/chunk-LogStatus.mjs

@@ -1,44 +0,0 @@
-import { meta } from "#meta";
-import "react";
-import { IconButton, Panel, Popover, useTranslation } from "@dxos/react-ui";
-import { jsx, jsxs } from "react/jsx-runtime";
-import { Logger } from "@dxos/react-ui-debug";
-import { StatusBar } from "@dxos/plugin-status-bar/components";
-//#region src/containers/LogStatus/LogStatus.tsx
-/** Status-bar button that opens the log panel in a popover for a quick glance. */
-var LogStatus = () => {
-	const { t } = useTranslation(meta.profile.key);
-	return /* @__PURE__ */ jsxs(Popover.Root, { children: [/* @__PURE__ */ jsx(StatusBar.Item, { children: /* @__PURE__ */ jsx(Popover.Trigger, {
-		asChild: true,
-		children: /* @__PURE__ */ jsx(IconButton, {
-			variant: "ghost",
-			icon: "ph--list-magnifying-glass--regular",
-			iconOnly: true,
-			label: t("open-logs.label")
-		})
-	}) }), /* @__PURE__ */ jsx(Popover.Portal, { children: /* @__PURE__ */ jsxs(Popover.Content, {
-		side: "top",
-		children: [/* @__PURE__ */ jsx(Popover.Viewport, {
-			classNames: "w-[40rem] h-[24rem]",
-			children: /* @__PURE__ */ jsx(Logger.Root, { children: /* @__PURE__ */ jsxs(Panel.Root, { children: [
-				/* @__PURE__ */ jsx(Panel.Toolbar, {
-					asChild: true,
-					children: /* @__PURE__ */ jsx(Logger.Toolbar, {})
-				}),
-				/* @__PURE__ */ jsx(Panel.Content, {
-					asChild: true,
-					children: /* @__PURE__ */ jsx(Logger.Content, { children: /* @__PURE__ */ jsx(Logger.List, {}) })
-				}),
-				/* @__PURE__ */ jsx(Panel.Statusbar, {
-					asChild: true,
-					children: /* @__PURE__ */ jsx(Logger.Filter, {})
-				})
-			] }) })
-		}), /* @__PURE__ */ jsx(Popover.Arrow, {})]
-	}) })] });
-};
-LogStatus.displayName = "LogStatus";
-//#endregion
-export { LogStatus };
-
-//# sourceMappingURL=chunk-LogStatus.mjs.map

package/dist/lib/chunk-LogStatus.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk-LogStatus.mjs","names":[],"sources":["../../src/containers/LogStatus/LogStatus.tsx"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\nimport React from 'react';\n\nimport { StatusBar } from '@dxos/plugin-status-bar/components';\nimport { IconButton, Panel, Popover, useTranslation } from '@dxos/react-ui';\nimport { Logger } from '@dxos/react-ui-debug';\n\nimport { meta } from '#meta';\n\n/** Status-bar button that opens the log panel in a popover for a quick glance. */\nexport const LogStatus = () => {\n  const { t } = useTranslation(meta.profile.key);\n\n  return (\n    <Popover.Root>\n      {/* IconButton is the direct trigger child so the trigger ref/handlers/ARIA attach to the button, not the container. */}\n      <StatusBar.Item>\n        <Popover.Trigger asChild>\n          <IconButton variant='ghost' icon='ph--list-magnifying-glass--regular' iconOnly label={t('open-logs.label')} />\n        </Popover.Trigger>\n      </StatusBar.Item>\n      <Popover.Portal>\n        <Popover.Content side='top'>\n          <Popover.Viewport classNames='w-[40rem] h-[24rem]'>\n            <Logger.Root>\n              <Panel.Root>\n                <Panel.Toolbar asChild>\n                  <Logger.Toolbar />\n                </Panel.Toolbar>\n                <Panel.Content asChild>\n                  <Logger.Content>\n                    <Logger.List />\n                  </Logger.Content>\n                </Panel.Content>\n                <Panel.Statusbar asChild>\n                  <Logger.Filter />\n                </Panel.Statusbar>\n              </Panel.Root>\n            </Logger.Root>\n          </Popover.Viewport>\n          <Popover.Arrow />\n        </Popover.Content>\n      </Popover.Portal>\n    </Popover.Root>\n  );\n};\n\nLogStatus.displayName = 'LogStatus';\n"],"mappings":";;;;;;;;AAaA,IAAa,kBAAkB;CAC7B,MAAM,EAAE,MAAM,eAAe,KAAK,QAAQ,GAAG;CAE7C,OACE,qBAAC,QAAQ,MAAT,EAAA,UAAA,CAEE,oBAAC,UAAU,MAAX,EAAA,UACE,oBAAC,QAAQ,SAAT;EAAiB,SAAA;EACf,UAAA,oBAAC,YAAD;GAAY,SAAQ;GAAQ,MAAK;GAAqC,UAAA;GAAS,OAAO,EAAE,iBAAiB;EAAI,CAAA;CAC9F,CAAA,EACH,CAAA,GAChB,oBAAC,QAAQ,QAAT,EAAA,UACE,qBAAC,QAAQ,SAAT;EAAiB,MAAK;EAAtB,UAAA,CACE,oBAAC,QAAQ,UAAT;GAAkB,YAAW;GAC3B,UAAA,oBAAC,OAAO,MAAR,EAAA,UACE,qBAAC,MAAM,MAAP,EAAA,UAAA;IACE,oBAAC,MAAM,SAAP;KAAe,SAAA;KACb,UAAA,oBAAC,OAAO,SAAR,CAAiB,CAAA;IACJ,CAAA;IACf,oBAAC,MAAM,SAAP;KAAe,SAAA;KACb,UAAA,oBAAC,OAAO,SAAR,EAAA,UACE,oBAAC,OAAO,MAAR,CAAc,CAAA,EACA,CAAA;IACH,CAAA;IACf,oBAAC,MAAM,WAAP;KAAiB,SAAA;KACf,UAAA,oBAAC,OAAO,QAAR,CAAgB,CAAA;IACD,CAAA;GACP,EAAA,CAAA,EACD,CAAA;EACG,CAAA,GAClB,oBAAC,QAAQ,OAAT,CAAgB,CAAA,CACD;CACH,CAAA,EAAA,CAAA,CACJ,EAAA,CAAA;AAElB;AAEA,UAAU,cAAc"}

package/dist/types/src/containers/LogStatus/LogStatus.d.ts

@@ -1,6 +0,0 @@
-import React from 'react';
-export declare function LogStatus(): React.JSX.Element;
-export declare namespace LogStatus {
-    var displayName: string;
-}
-//# sourceMappingURL=LogStatus.d.ts.map

package/dist/types/src/containers/LogStatus/LogStatus.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"LogStatus.d.ts","sourceRoot":"","sources":["../../../../../src/containers/LogStatus/LogStatus.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC"}

package/dist/types/src/containers/LogStatus/index.d.ts

@@ -1,2 +0,0 @@
-export * from './LogStatus';
-//# sourceMappingURL=index.d.ts.map

package/dist/types/src/containers/LogStatus/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/containers/LogStatus/index.ts"],"names":[],"mappings":"AAIA,cAAc,aAAa,CAAC"}

package/src/containers/LogStatus/LogStatus.tsx

@@ -1,51 +0,0 @@
-//
-// Copyright 2026 DXOS.org
-//
-
-import React from 'react';
-
-import { StatusBar } from '@dxos/plugin-status-bar/components';
-import { IconButton, Panel, Popover, useTranslation } from '@dxos/react-ui';
-import { Logger } from '@dxos/react-ui-debug';
-
-import { meta } from '#meta';
-
-/** Status-bar button that opens the log panel in a popover for a quick glance. */
-export const LogStatus = () => {
-  const { t } = useTranslation(meta.profile.key);
-
-  return (
-    <Popover.Root>
-      {/* IconButton is the direct trigger child so the trigger ref/handlers/ARIA attach to the button, not the container. */}
-      <StatusBar.Item>
-        <Popover.Trigger asChild>
-          <IconButton variant='ghost' icon='ph--list-magnifying-glass--regular' iconOnly label={t('open-logs.label')} />
-        </Popover.Trigger>
-      </StatusBar.Item>
-      <Popover.Portal>
-        <Popover.Content side='top'>
-          <Popover.Viewport classNames='w-[40rem] h-[24rem]'>
-            <Logger.Root>
-              <Panel.Root>
-                <Panel.Toolbar asChild>
-                  <Logger.Toolbar />
-                </Panel.Toolbar>
-                <Panel.Content asChild>
-                  <Logger.Content>
-                    <Logger.List />
-                  </Logger.Content>
-                </Panel.Content>
-                <Panel.Statusbar asChild>
-                  <Logger.Filter />
-                </Panel.Statusbar>
-              </Panel.Root>
-            </Logger.Root>
-          </Popover.Viewport>
-          <Popover.Arrow />
-        </Popover.Content>
-      </Popover.Portal>
-    </Popover.Root>
-  );
-};
-
-LogStatus.displayName = 'LogStatus';

package/src/containers/LogStatus/index.ts

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