@dxos/react-ui-assistant 0.11.1

package/src/components/widgets/ToolWidget.tsx

@@ -0,0 +1,185 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as Tool from 'effect/unstable/ai/Tool';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { Icon, IconBlock, useTranslation } from '@dxos/react-ui';
+import { NumericTabs, TextCrawl, TogglePanel, type TogglePanelRootProps } from '@dxos/react-ui-components';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { type ContentBlock } from '@dxos/types';
+import { type XmlWidgetProps, getXmlTextChild } from '@dxos/ui-editor';
+import { isNonNullable, safeParseJson } from '@dxos/util';
+
+import { translationKey } from '../../translations';
+
+export type ToolWidgetProps = XmlWidgetProps;
+
+/**
+ * A run of tool blocks as one collapsible panel with a tab per call. The `<toolkit>` tag carries
+ * the run as JSON — the item is rebuilt from its message alone, so there is no widget-state side
+ * channel to accumulate blocks through.
+ */
+export const ToolWidget = ({ view, children }: ToolWidgetProps) => {
+  const { t } = useTranslation(translationKey);
+  const blocks = useMemo<ContentBlock.Any[]>(() => {
+    const parsed = safeParseJson(getXmlTextChild(children ?? []) ?? '');
+    return Array.isArray(parsed) ? (parsed as ContentBlock.Any[]) : [];
+  }, [children]);
+
+  const items = useMemo<ToolPanelProps['items']>(() => {
+    let lastToolCall: { tool: Tool.Any | undefined; block: ContentBlock.ToolCall } | undefined;
+    const tools: Tool.Any[] = [];
+    return blocks
+      .filter((block) => block._tag === 'toolCall' || block._tag === 'toolResult' || block._tag === 'stats')
+      .map((block) => {
+        switch (block._tag) {
+          case 'toolCall': {
+            if (block.pending && lastToolCall?.block.toolCallId === block.toolCallId) {
+              return null;
+            }
+
+            const tool = tools.find((tool) => tool.name === block.name);
+            lastToolCall = { tool, block };
+            return {
+              title: tool?.description ?? [t('tool-call.label'), block.name].filter(Boolean).join(' '),
+              icon: block.operationIcon,
+              content: {
+                ...block,
+                input: safeParseJson(block.input),
+              },
+            };
+          }
+
+          case 'toolResult': {
+            // TODO(burdon): Parse error type.
+            if (block.error) {
+              return {
+                title: t('tool-error.label'),
+                icon: lastToolCall?.block.operationIcon,
+                content: block,
+              };
+            }
+
+            const title =
+              lastToolCall?.tool?.description ??
+              [t('tool-result.label'), lastToolCall?.block.name].filter(Boolean).join(' ');
+            const icon = lastToolCall?.block.operationIcon;
+            lastToolCall = undefined;
+            return {
+              title,
+              icon,
+              content: {
+                ...block,
+                result: typeof block.result === 'string' ? safeParseJson(block.result) : block.result,
+              },
+            };
+          }
+
+          case 'stats': {
+            if (!lastToolCall) {
+              return null;
+            }
+
+            return {
+              title: t('stats.label'),
+              icon: lastToolCall.block.operationIcon,
+              content: block,
+            };
+          }
+        }
+      })
+      .filter(isNonNullable);
+  }, [blocks, t]);
+
+  const handleChangeOpen = useCallback(() => {
+    setTimeout(() => {
+      // Measure after animation.
+      view?.requestMeasure();
+    }, 1_000);
+  }, [view]);
+
+  // Ignore if empty.
+  if (!items.length) {
+    return null;
+  }
+
+  return <ToolPanel items={items} onChangeOpen={handleChangeOpen} />;
+};
+
+type ToolPanelItem = { title: string; icon?: string; content: any };
+
+type ToolPanelProps = {
+  items: ToolPanelItem[];
+} & Pick<TogglePanelRootProps, 'onChangeOpen'>;
+
+const DEFAULT_TOOL_ICON = 'ph--wrench--regular';
+
+const ToolPanel = ({ items, onChangeOpen }: ToolPanelProps) => {
+  const tabsRef = useRef<HTMLDivElement>(null);
+  const [selected, setSelected] = useState(0);
+  const [open, setOpen] = useState(false);
+
+  // Clamp selected to avoid out-of-bounds after items shrink.
+  useEffect(() => {
+    setSelected((prev) => Math.min(prev, Math.max(0, items.length - 1)));
+  }, [items.length]);
+
+  useEffect(() => {
+    onChangeOpen?.(open);
+    if (open) {
+      tabsRef.current?.focus();
+    }
+  }, [open, onChangeOpen]);
+
+  const handleSelect = useCallback((index: number) => {
+    setSelected(index);
+  }, []);
+
+  // Prefer the icon from the latest tool call so the header reflects what's currently active.
+  // TextCrawl shows multiple titles, but only one icon slot — using the most recent keeps it in sync
+  // with the visible operation while it streams.
+  const headerIcon = items[items.length - 1]?.icon ?? items[0]?.icon ?? DEFAULT_TOOL_ICON;
+
+  return (
+    <TogglePanel.Root open={open} onChangeOpen={setOpen}>
+      <TogglePanel.Content>
+        <TogglePanel.Header classNames='flex items-center gap-2 text-sm'>
+          <div className='w-full grid grid-cols-[1fr_auto] items-center gap-2'>
+            <TextCrawl
+              key='status-roll'
+              classNames='text-description'
+              lines={items.map((item) => item.title)}
+              autoAdvance
+              greedy
+            />
+            <IconBlock>
+              <Icon icon={headerIcon} size={4} />
+            </IconBlock>
+          </div>
+        </TogglePanel.Header>
+        <TogglePanel.Body>
+          <TogglePanel.Viewport classNames='grid grid-cols-[32px_1fr]'>
+            <NumericTabs
+              ref={tabsRef}
+              classNames='p-1'
+              length={items.length}
+              selected={selected}
+              onSelect={handleSelect}
+            />
+            <JsonHighlighter
+              data={items[selected]?.content}
+              classNames='p-1 text-xs bg-transparent'
+              replacer={{
+                maxDepth: 3,
+                maxArrayLen: 10,
+                maxStringLen: 128,
+              }}
+            />
+          </TogglePanel.Viewport>
+        </TogglePanel.Body>
+      </TogglePanel.Content>
+    </TogglePanel.Root>
+  );
+};

package/src/components/widgets/defaults.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export const styles = {
+  /**
+   * Vertical rhythm for block widgets. Padding, never margin: CodeMirror measures a widget from its own
+   * box, so a margin sits outside what it can see and its height model drifts from what is rendered —
+   * the error accumulates down the document until the turn-fold gutter markers are visibly misaligned.
+   * Note padding does not collapse between adjacent siblings the way margins do
+   */
+  padding: 'pt-2 pb-4',
+  border: 'border border-subdued-separator rounded-sm',
+};

package/src/components/widgets/format-time.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Kept out of `BranchWidget.tsx`: react-refresh only fast-refreshes a module whose
+// exports are all components, so values exported beside them force a full page reload on
+// every edit.
+
+/**
+ * Relative ("5 min ago", "yesterday") within two days, absolute date beyond that. The exact
+ * timestamp is always available via the `title` tooltip.
+ *
+ * Recent prompts are the ones a reader places by elapsed time; older ones by date.
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export const formatTime = (created: string, now = Date.now()): string => {
+  const date = new Date(created);
+  if (Number.isNaN(date.getTime())) {
+    return '';
+  }
+
+  const elapsed = now - date.getTime();
+  if (elapsed < 0 || elapsed >= 2 * DAY_MS) {
+    return date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+  }
+
+  const format = new Intl.RelativeTimeFormat(undefined, { numeric: 'auto' });
+  const minutes = Math.round(elapsed / 60_000);
+  if (minutes < 1) {
+    // Seconds rather than `format(0, 'minute')`, which renders as "this minute".
+    return format.format(-Math.max(1, Math.round(elapsed / 1000)), 'second');
+  }
+  if (minutes < 60) {
+    return format.format(-minutes, 'minute');
+  }
+
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) {
+    return format.format(-hours, 'hour');
+  }
+
+  // `numeric: 'auto'` renders -1 day as "yesterday".
+  return format.format(-Math.round(hours / 24), 'day');
+};

package/src/components/widgets/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './format-time';
+export * from './FallbackWidget';
+export * from './ReasoningWidget';
+export * from './ReferenceWidget';
+export * from './SelectWidget';
+export * from './StatsWidget';
+export * from './StatusWidget';
+export * from './SuggestionWidget';
+export * from './SummaryWidget';
+export * from './ToolWidget';

package/src/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './components';
+export * from './registry';
+export * from './renderer';
+export * from './translations';
+export * from './types';

package/src/registry.tsx

@@ -0,0 +1,144 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { AnchorWidget, type XmlWidgetRegistry, getXmlTextChild } from '@dxos/ui-editor';
+
+import {
+  FallbackWidget,
+  ReasoningWidget,
+  ReferenceWidget,
+  SelectWidget,
+  StatsWidget,
+  StatusWidget,
+  SuggestionWidget,
+  SummaryWidget,
+  ToolWidget,
+} from './components/widgets';
+
+/**
+ * Floor for a portaled panel's collapsed height, reserved before its content paints. `heightMode:
+ * 'min'` makes it a floor rather than a pin — without it the row is measured at the height of an
+ * empty box and grows a frame later, a row moving under a reader scrolling up.
+ */
+const COLLAPSED_HEIGHT = 42;
+
+/**
+ * Widgets for the tags {@link createRenderer} emits.
+ *
+ * Host-extensible by spreading: the plugin adds its `surface` widget (which renders an
+ * app-framework Surface this package must not depend on) over the fallback registered here.
+ * DOM widgets render synchronously from the tag alone; React widgets are portaled and declare a
+ * collapsed-height floor so the row's first measurement is honest.
+ */
+export const assistantRegistry: XmlWidgetRegistry = {
+  // No widget: the reader's own words stay in the document, where they can be selected and
+  // searched. Registered so the markdown parser keeps the tag as one block, and framed by the
+  // chrome, not here.
+  'prompt': {
+    block: true,
+  },
+
+  //
+  // DOM widgets
+  //
+
+  'link-preview': {
+    block: false,
+    urlSchemes: ['dxn:', 'echo:'],
+    factory: ({ label, dxn }) =>
+      typeof label === 'string' && typeof dxn === 'string' ? new AnchorWidget(label, dxn) : null,
+  },
+  // A "user"-turn message generated by the system (a trigger, an encoded event): meant to start the
+  // agent without reading as the reader's own prompt.
+  'synthetic': {
+    block: true,
+    factory: ({ children, range }) => {
+      const text = getXmlTextChild(children ?? []);
+      return text ? new ReasoningWidget(text, range?.from) : null;
+    },
+  },
+  'reasoning': {
+    block: true,
+    streaming: true,
+    factory: ({ children, range }) => {
+      const text = getXmlTextChild(children ?? []);
+      return text ? new ReasoningWidget(text, range?.from) : null;
+    },
+  },
+  'status': {
+    block: true,
+    streaming: true,
+    factory: ({ children }) => {
+      const text = getXmlTextChild(children ?? []);
+      return text ? new StatusWidget(text) : null;
+    },
+  },
+  'reference': {
+    block: false,
+    factory: ({ children, ref }) => {
+      const text = getXmlTextChild(children ?? []);
+      return text && typeof ref === 'string' ? new ReferenceWidget(text, ref) : null;
+    },
+  },
+  // Inline so a run of suggestions flows onto one wrapped line instead of one block per line.
+  'suggestion': {
+    block: false,
+    factory: ({ children }) => {
+      const text = getXmlTextChild(children ?? []);
+      return text ? new SuggestionWidget(text) : null;
+    },
+  },
+  'select': {
+    block: true,
+    factory: ({ children }) => {
+      const options = (children ?? [])
+        .map((option: any) => option?._tag === 'option' && getXmlTextChild(option.children))
+        .filter(Boolean) as string[];
+      return options.length ? new SelectWidget(options) : null;
+    },
+  },
+  'stats': {
+    block: true,
+    factory: ({ children }) => {
+      const text = getXmlTextChild(children ?? []);
+      return text ? new StatsWidget(text) : null;
+    },
+  },
+
+  //
+  // React widgets (portaled outside the editor)
+  //
+
+  'toolkit': {
+    block: true,
+    streaming: true,
+    estimatedHeight: () => COLLAPSED_HEIGHT,
+    heightMode: 'min',
+    Component: ToolWidget,
+  },
+  'summary': {
+    block: true,
+    estimatedHeight: () => COLLAPSED_HEIGHT,
+    heightMode: 'min',
+    Component: SummaryWidget,
+  },
+  // The host overrides this with a widget that can actually dispatch the surface.
+  'surface': {
+    block: true,
+    estimatedHeight: () => COLLAPSED_HEIGHT,
+    heightMode: 'min',
+    Component: FallbackWidget,
+  },
+
+  //
+  // Fallback
+  //
+
+  'json': {
+    block: true,
+    estimatedHeight: () => COLLAPSED_HEIGHT,
+    heightMode: 'min',
+    Component: FallbackWidget,
+  },
+} as const;

package/src/renderer.ts

@@ -0,0 +1,216 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type URI } from '@dxos/keys';
+import { type MessageRenderer } from '@dxos/react-ui-feed';
+import { type ContentBlock, type Message } from '@dxos/types';
+
+import { type ChatView } from './types';
+
+export type CreateRendererOptions = {
+  /** Resolves a reference's display label; the tag carries the DXN either way. */
+  getObjectLabel?: (uri: URI.URI) => string;
+};
+
+/**
+ * The assistant's projection of a message: each block flattened to markdown, everything that is not
+ * prose emitted as an XML tag for the registry's widgets. The view type is a filter over blocks —
+ * the model always carries everything, so switching views is a re-render, not a re-fetch.
+ *
+ * Consecutive tool blocks (`toolCall`/`toolResult`/`stats`) render as ONE `<toolkit>` tag carrying
+ * the run as JSON: the panel widget shows a run of calls as tabs, and the item is rebuilt from its
+ * message alone — there is no side channel accumulating widget state (the old `MessageSyncer`
+ * machinery this package retires).
+ */
+export const createRenderer = (
+  viewType: ChatView | undefined,
+  { getObjectLabel = () => 'Object' }: CreateRendererOptions = {},
+): MessageRenderer => {
+  return (message) => {
+    const blocks = message.blocks.filter((block) => isBlockVisible(viewType, block));
+    const segments: string[] = [];
+    let tools: ContentBlock.Any[] = [];
+
+    const flushTools = () => {
+      if (tools.length) {
+        segments.push(toolkitTag(tools));
+        tools = [];
+      }
+    };
+
+    for (const block of blocks) {
+      if (block._tag === 'toolCall' || block._tag === 'toolResult' || (block._tag === 'stats' && tools.length)) {
+        tools.push(block);
+        continue;
+      }
+
+      flushTools();
+      const rendered = blockToMarkdown(message, block, getObjectLabel);
+      if (rendered) {
+        segments.push(rendered);
+      }
+    }
+    flushTools();
+
+    // Suggestions are inline widgets meant to flow: a run of them joins on one line and wraps as
+    // chips; everything else is separated by a blank line so each block parses as its own
+    // markdown block.
+    const text = segments
+      .reduce<string[]>((parts, segment) => {
+        const previous = parts[parts.length - 1];
+        if (previous?.startsWith('<suggestion') && segment.startsWith('<suggestion')) {
+          parts[parts.length - 1] = `${previous} ${segment}`;
+        } else {
+          parts.push(segment);
+        }
+        return parts;
+      }, [])
+      .join('\n\n');
+
+    return { kind: 'markdown', text };
+  };
+};
+
+const isBlockVisible = (viewType: ChatView | undefined, block: ContentBlock.Any): boolean => {
+  switch (viewType) {
+    case 'debug':
+      return true;
+    case 'summary':
+      // Only conversational text; hide reasoning, tool calls, status, stats and synthetic turns.
+      return block._tag === 'text' && (block as ContentBlock.Text).disposition !== 'synthetic';
+    case 'normal':
+      return block._tag !== 'reasoning';
+    case 'thinking':
+    default:
+      return true;
+  }
+};
+
+const blockToMarkdown = (
+  message: Message.Message,
+  block: ContentBlock.Any,
+  getObjectLabel: (uri: URI.URI) => string,
+): string | undefined => {
+  switch (block._tag) {
+    case 'text': {
+      if (message.sender.role === 'user') {
+        // A synthetic turn is system-generated input (a trigger, an encoded event): shown like
+        // reasoning, not framed as the reader's own words.
+        return block.disposition === 'synthetic'
+          ? tag('synthetic', block.text, block)
+          : tag('prompt', block.text, block);
+      }
+      return block.text.trim() || undefined;
+    }
+
+    case 'reasoning':
+      return tag('reasoning', block.reasoningText ?? block.redactedText ?? '', block);
+
+    case 'status':
+      return tag('status', block.statusText, block);
+
+    case 'summary':
+      return tag('summary', block.content, block);
+
+    case 'suggestion':
+      return block.pending ? undefined : tag('suggestion', block.text, block);
+
+    case 'select':
+      return block.pending || !block.options.length
+        ? undefined
+        : `<select>${block.options.map((option) => `<option>${escapeXml(option)}</option>`).join('')}</select>`;
+
+    case 'reference': {
+      if (block.pending) {
+        return undefined;
+      }
+      const uri = block.reference.uri;
+      return `<reference ref="${escapeAttribute(uri.toString())}">${escapeXml(getObjectLabel(uri))}</reference>`;
+    }
+
+    case 'stats':
+      // Only meaningful inside a tool run (grouped by the caller); bare stats render nothing.
+      return undefined;
+
+    case 'surface':
+      return block.pending
+        ? undefined
+        : `<surface role="${escapeAttribute(block.role)}">${escapeXml(JSON.stringify(block.data ?? {}))}</surface>`;
+
+    default:
+      // Nothing renders blank: an unknown block is shown as what it is.
+      return tag('json', JSON.stringify(block), block);
+  }
+};
+
+/** A run of tool blocks as one tag; the widget parses the payload back out. */
+const toolkitTag = (blocks: ContentBlock.Any[]): string => {
+  const pending = blocks.some((block) => block.pending);
+  return `<toolkit${pending ? ' pending="true"' : ''}>${escapeXml(JSON.stringify(blocks))}</toolkit>`;
+};
+
+/**
+ * An XML tag holding block content.
+ *
+ * A pending block is emitted **unclosed**, which is the streaming contract: the item reconciles by
+ * appending, so a closing tag written before the content is complete would be rewritten per chunk.
+ * Paragraph breaks inside tag content are collapsed, since a blank line would end the enclosing
+ * markdown block and leave the rest of the tag parsing as prose.
+ */
+const tag = (name: string, content: string, block: ContentBlock.Any): string => {
+  const text = escapeXml(content.replace(/\n\n+/g, ' ').trim());
+  if (!text.length && !block.pending) {
+    return '';
+  }
+
+  const open = `<${name}>`;
+  return block.pending ? `${open}${text}` : `${open}${text}</${name}>`;
+};
+
+const escapeXml = (raw: string): string => raw.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const escapeAttribute = (raw: string): string => escapeXml(raw).replace(/"/g, '&quot;');
+
+//
+// Estimates
+//
+
+/** Chrome around every row: the padding and the hover toolbar's reserved line. */
+const ROW_CHROME = 46;
+/** Height of a wrapped line of body text, and how many characters fit at typical thread width. */
+const LINE_HEIGHT = 24;
+const LINE_CHARS = 90;
+/** A collapsed panel: reasoning, a tool run, a summary. */
+const PANEL_HEIGHT = 50;
+
+/**
+ * What a row will measure, from the message alone. Rough on purpose — its only job is to be close
+ * enough that measuring the row does not move the rows below it.
+ */
+export const estimateRow = (message: Message.Message): number => {
+  let height = ROW_CHROME;
+  for (const block of message.blocks) {
+    switch (block._tag) {
+      case 'text': {
+        for (const paragraph of block.text.split('\n\n')) {
+          height += Math.max(1, Math.ceil(paragraph.length / LINE_CHARS)) * LINE_HEIGHT;
+        }
+        break;
+      }
+      case 'suggestion':
+        height += LINE_HEIGHT + 8;
+        break;
+      case 'select':
+        height += block.options.length * (LINE_HEIGHT + 10);
+        break;
+      case 'toolResult':
+      case 'stats':
+        // Folded into the preceding call's panel.
+        break;
+      default:
+        height += PANEL_HEIGHT;
+    }
+  }
+
+  return height;
+};

package/src/testing/index.ts

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