@dxos/react-ui-assistant 0.11.1

package/src/components/MessageChrome/MessageChrome.tsx

@@ -0,0 +1,147 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import React, { type PropsWithChildren } from 'react';
+
+import { IconButton, type ThemedClassName, useTranslation } from '@dxos/react-ui';
+import { type MessageChromeProps } from '@dxos/react-ui-feed';
+import { Message } from '@dxos/types';
+import { mx } from '@dxos/ui-theme';
+
+import { translationKey } from '../../translations';
+import { formatTime } from '../widgets';
+
+//
+// Context
+//
+
+const MESSAGE_CHROME_NAME = 'MessageChrome';
+
+type MessageChromeContextValue = {
+  /** Soft-fork the thread from the given prompt; the rewind button renders only when present. */
+  onRewind?: (id: string) => void;
+};
+
+const [MessageChromeProvider, useMessageChromeContext] = createContext<MessageChromeContextValue>(MESSAGE_CHROME_NAME);
+
+export { MessageChromeProvider };
+
+//
+// Toolbars
+//
+
+/** Copies the message's extracted text — the model's truth, not the DOM's partial render. */
+const CopyButton = ({ message }: { message: Message.Message }) => {
+  const { t } = useTranslation(translationKey);
+  return (
+    <IconButton
+      icon='ph--copy--regular'
+      iconOnly
+      label={t('copy.label')}
+      variant='ghost'
+      density='sm'
+      onClick={() => void navigator.clipboard?.writeText(Message.extractText(message))}
+    />
+  );
+};
+
+const timeOf = (message: Message.Message) => (
+  <time dateTime={message.created} title={new Date(message.created).toLocaleString()}>
+    {formatTime(message.created)}
+  </time>
+);
+
+export type MessageToolbarProps = ThemedClassName<{
+  message: Message.Message;
+}>;
+
+/**
+ * The controls under the reader's own prompt: copy, rewind (edit-and-resend), and when it was
+ * sent. Revealed on hover by the chrome, but never removed from flow — chrome that appears and
+ * disappears changes the row's height, and a pointer travelling down a scrolling list would then
+ * move every row below it.
+ */
+export const PromptToolbar = ({ classNames, message }: MessageToolbarProps) => {
+  const { t } = useTranslation(translationKey);
+  const { onRewind } = useMessageChromeContext('PromptToolbar');
+
+  return (
+    <div role='toolbar' className={mx('flex items-center gap-1 text-xs text-description', classNames)}>
+      <CopyButton message={message} />
+      {onRewind && (
+        <IconButton
+          icon='ph--clock-counter-clockwise--regular'
+          iconOnly
+          label={t('rewind.label')}
+          variant='ghost'
+          density='sm'
+          data-testid='chat.rewind'
+          onClick={() => onRewind(message.id)}
+        />
+      )}
+      {timeOf(message)}
+    </div>
+  );
+};
+
+PromptToolbar.displayName = 'PromptToolbar';
+
+/** The controls under an answer: copy, and when the answer finished. */
+export const AssistantToolbar = ({ classNames, message }: MessageToolbarProps) => {
+  return (
+    <div role='toolbar' className={mx('flex items-center gap-1 text-xs text-description', classNames)}>
+      <CopyButton message={message} />
+      {timeOf(message)}
+    </div>
+  );
+};
+
+AssistantToolbar.displayName = 'AssistantToolbar';
+
+//
+// Chrome
+//
+
+/** Shared hover reveal: present in flow at all times, visible when the row is under the pointer. */
+const reveal = 'pt-1 opacity-0 transition-opacity group-hover:opacity-100';
+
+const Row = ({ children, classNames }: PropsWithChildren<{ classNames?: string }>) => (
+  <div className={mx('group relative px-2 py-2', classNames)} data-testid='feed.message'>
+    {children}
+  </div>
+);
+
+/**
+ * The assistant feed's per-message frame: the reader's prompts and the model's answers are framed
+ * differently because they are different kinds of thing — a prompt is an instruction the thread
+ * can be rewound to, an answer is a result.
+ *
+ * A prompt sits apart from the model's prose: right-aligned, at most two thirds of the viewport —
+ * the chat convention that makes whose-turn legible at a glance — with its toolbar following the
+ * bubble's edge.
+ */
+export const MessageChrome = ({ message, selected, children }: MessageChromeProps) => {
+  const prompt = message.sender.role === 'user';
+
+  return (
+    <Row classNames={mx(selected && 'bg-hover-surface')}>
+      {prompt ? (
+        <div className='min-w-0 flex flex-col items-end'>
+          <div className='max-w-[66%] min-w-0'>
+            <div className='px-4 py-3 border-s-2 border-accent-bg rounded-sm bg-input-surface'>{children}</div>
+            <PromptToolbar classNames={mx('justify-end', reveal)} message={message} />
+          </div>
+        </div>
+      ) : (
+        <div className='min-w-0'>
+          {children}
+          <AssistantToolbar classNames={reveal} message={message} />
+        </div>
+      )}
+    </Row>
+  );
+};
+
+MessageChrome.displayName = MESSAGE_CHROME_NAME;

package/src/components/MessageChrome/index.ts

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

package/src/components/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './ChatThread';
+export * from './MessageChrome';
+export * from './widgets';

package/src/components/widgets/FallbackWidget.tsx

@@ -0,0 +1,26 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { TogglePanel } from '@dxos/react-ui-components';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { type XmlWidgetProps } from '@dxos/ui-editor';
+
+export const FallbackWidget = ({ _tag, ...props }: XmlWidgetProps) => {
+  return (
+    <TogglePanel.Root>
+      <TogglePanel.Content>
+        <TogglePanel.Header classNames='dx-group-surface'>{_tag}</TogglePanel.Header>
+        <TogglePanel.Body classNames='dx-modal-surface'>
+          <TogglePanel.Viewport>
+            <JsonHighlighter classNames='p-2! text-sm' data={props} />
+          </TogglePanel.Viewport>
+        </TogglePanel.Body>
+      </TogglePanel.Content>
+    </TogglePanel.Root>
+  );
+};
+
+FallbackWidget.displayName = 'Fallback';

package/src/components/widgets/ReasoningWidget.stories.tsx

@@ -0,0 +1,68 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useRef } from 'react';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { ReasoningWidget } from './ReasoningWidget';
+
+export type StoryArgs = {
+  text: string;
+};
+
+// TODO(burdon): Generalize factory for DOM widgets.
+const DefaultStory = ({ text }: StoryArgs) => {
+  const hostRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) {
+      return;
+    }
+
+    host.replaceChildren();
+    const widget = new ReasoningWidget(text, 0);
+    const dom = widget.toDOM();
+    host.appendChild(dom);
+    widget.updateDOM(dom);
+    return () => {
+      widget.destroy(dom);
+      host.replaceChildren();
+    };
+  }, [text]);
+
+  return <div ref={hostRef} />;
+};
+
+const meta = {
+  title: 'ui/react-ui-assistant/widgets/ReasoningWidget',
+  component: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    text: 'The user is asking about nested flex layouts and overflow. I should mention min-height 0 and grid track sizing.',
+  },
+};
+
+export const LongText: Story = {
+  args: {
+    text: [
+      'Step 1: Identify the scroll container and ensure it participates in a definite height chain.',
+      'Step 2: Apply min-h-0 to flex children that should shrink and scroll.',
+      'Step 3: Prefer overflow-y-auto on the leaf viewport, not on every ancestor.',
+      'Step 4: Use min-h-0 on the scroll container to ensure it participates in a definite height chain.',
+      'Step 5: Use min-w-0 on the scroll container to ensure it participates in a definite width chain.',
+    ].join('\n\n'),
+  },
+};

package/src/components/widgets/ReasoningWidget.ts

@@ -0,0 +1,139 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { WidgetType } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+import { styles } from './defaults';
+
+/**
+ * Props used to derive a stable key for a reasoning block across CodeMirror widget rebuilds.
+ * CodeMirror does not assign persistent IDs to widgets; streaming re-runs the factory each tick.
+ */
+export type ReasoningWidgetBlockIdProps = {
+  id?: string;
+  range?: { from: number; to: number };
+};
+
+/**
+ * AI reasoning widget.
+ */
+export class ReasoningWidget extends WidgetType {
+  readonly #pos: string;
+  /** The timer id last registered for this instance (may differ from the map if superseded). */
+  #ownedTimerId: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private readonly text: string,
+    pos: string | number | undefined,
+  ) {
+    super();
+    this.#pos = pos === undefined || pos === '' ? 'reasoning' : String(pos);
+  }
+
+  override eq(other: this) {
+    return this.text === other.text && this.#pos === other.#pos;
+  }
+
+  override toDOM() {
+    return Domino.of('div')
+      .classNames(styles.padding)
+      .append(
+        Domino.of('div')
+          .classNames('relative overflow-hidden p-px', styles.border)
+          .attributes({ 'data-trail-container': '' })
+          .append(
+            Domino.of('div')
+              .classNames(
+                'relative z-10 dx-base-surface rounded-sm text-sm text-subdued py-1',
+                'grid grid-cols-[24px_1fr] gap-x-0.5 items-start',
+              )
+              .append(
+                Domino.of('div')
+                  .classNames('flex h-5 w-full shrink-0 items-center justify-center self-start')
+                  .append(Domino.svg('ph--brain--regular').classNames('shrink-0 size-4 opacity-70')),
+                Domino.of('div')
+                  .classNames('px-2 max-h-[5lh] overflow-y-auto dx-scrollbar-thin min-w-0')
+                  .text(this.text)
+                  .attributes({ 'data-reasoning-text': '' }),
+              ),
+            Domino.of('div').attributes({ 'data-id': this.#pos }),
+          ),
+      ).root;
+  }
+
+  override updateDOM(dom: HTMLElement) {
+    // Update only the text leaf; `dom` may be wrapped in an outer shell, and the trail host is a
+    // sibling of the text node inside the bordered container — setting `textContent` on the wrong
+    // ancestor would remove `[data-id]`.
+    dom.querySelector<HTMLElement>('[data-reasoning-text]')?.replaceChildren(this.text);
+
+    // Recreate trail host if it was removed by a prior timeout (streaming paused > TRAIL_REMOVAL_DELAY_MS).
+    const container = dom.querySelector<HTMLElement>('[data-trail-container]');
+    let trailHost = container?.querySelector<HTMLElement>('[data-id]');
+    if (container && !trailHost) {
+      trailHost = Domino.of('div').attributes({ 'data-id': this.#pos }).root;
+      container.append(trailHost);
+    }
+    if (trailHost?.childElementCount === 0) {
+      trailHost.append(...createTrailLayers());
+    }
+
+    this.#scheduleTrailRemoval(dom);
+    return true;
+  }
+
+  override destroy(_dom: HTMLElement) {
+    this.#clearOwnedTrailTimer();
+  }
+
+  #scheduleTrailRemoval(dom: HTMLElement) {
+    const previous = trailRemovalTimers.get(this.#pos);
+    if (previous !== undefined) {
+      clearTimeout(previous);
+    }
+
+    const timerId = setTimeout(() => {
+      if (trailRemovalTimers.get(this.#pos) !== timerId) {
+        return;
+      }
+      trailRemovalTimers.delete(this.#pos);
+      this.#ownedTimerId = null;
+      dom.querySelector<HTMLElement>('[data-id]')?.remove();
+    }, TRAIL_REMOVAL_DELAY_MS);
+
+    trailRemovalTimers.set(this.#pos, timerId);
+    this.#ownedTimerId = timerId;
+  }
+
+  #clearOwnedTrailTimer() {
+    const active = trailRemovalTimers.get(this.#pos);
+    if (active !== undefined && active === this.#ownedTimerId) {
+      clearTimeout(active);
+      trailRemovalTimers.delete(this.#pos);
+    }
+    this.#ownedTimerId = null;
+  }
+}
+
+const trail = [
+  'absolute z-0 aspect-[2/1] w-16',
+  'bg-[radial-gradient(at_100%_50%,_theme(colors.green.700),_transparent_80%)]',
+  '[offset-anchor:100%_50%] [offset-path:border-box]',
+];
+
+/** Delay after the last content update before hiding the trail. */
+const TRAIL_REMOVAL_DELAY_MS = 1_000;
+
+/**
+ * One pending removal timer per logical block. Streaming creates a new widget instance each tick;
+ * `destroy` may run after the next instance has already scheduled, so we must not clear a newer timer.
+ */
+const trailRemovalTimers = new Map<string, ReturnType<typeof setTimeout>>();
+
+const createTrailLayers = (): [HTMLElement, HTMLElement] => [
+  Domino.of('div').classNames(...trail, 'animate-trail').root,
+  Domino.of('div').classNames(...trail, 'animate-trail-offset').root,
+];

package/src/components/widgets/ReferenceWidget.ts

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { WidgetType } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+import { styles } from './defaults';
+
+export class ReferenceWidget extends WidgetType {
+  constructor(
+    private text: string,
+    private dxn: string,
+  ) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this.dxn === other.dxn;
+  }
+
+  override toDOM() {
+    return Domino.of('div')
+      .classNames(styles.padding)
+      .append(Domino.of('dx-anchor').classNames('dx-tag--anchor').attributes({ dxn: this.dxn }).text(this.text)).root;
+  }
+}

package/src/components/widgets/SelectWidget.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { WidgetType } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+import { styles } from './defaults';
+
+/**
+ * Simple prompt widget.
+ */
+export class SelectWidget extends WidgetType {
+  constructor(private options: string[]) {
+    super();
+  }
+
+  override eq(other: this) {
+    return JSON.stringify(this.options) === JSON.stringify(other.options);
+  }
+
+  /**
+   * NOTE: Container must set var based on user's identity.
+   */
+  override toDOM() {
+    return Domino.of('div')
+      .attributes({ role: 'group' })
+      .classNames(styles.padding, 'flex flex-wrap gap-1')
+      .append(
+        ...this.options.map((option) =>
+          Domino.of('button')
+            .classNames('dx-button inline-block max-w-[100cqi]')
+            .attributes({ 'data-action': 'submit', 'data-value': option, 'data-density': 'md' })
+            .text(option),
+        ),
+      ).root;
+  }
+}

package/src/components/widgets/StatsWidget.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { WidgetType } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+import { styles } from './defaults';
+
+/**
+ * Simple stats widget.
+ */
+export class StatsWidget extends WidgetType {
+  constructor(private text: string) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this.text === other.text;
+  }
+
+  override toDOM() {
+    return Domino.of('div').classNames(styles.padding, 'text-sm text-placeholder').text(this.text).root;
+  }
+
+  override updateDOM(dom: HTMLElement) {
+    dom.textContent = this.text;
+    return true;
+  }
+}

package/src/components/widgets/StatusWidget.ts

@@ -0,0 +1,53 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { WidgetType } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+import { styles } from './defaults';
+
+/**
+ * AI status widget.
+ */
+export class StatusWidget extends WidgetType {
+  constructor(private readonly text: string) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this.text === other.text;
+  }
+
+  override toDOM() {
+    return Domino.of('div')
+      .classNames(styles.padding)
+      .append(
+        Domino.of('div')
+          .classNames('relative overflow-hidden rounded-sm')
+          .append(
+            Domino.of('div')
+              .classNames('grid grid-cols-[24px_1fr] gap-x-0.5 gap-y-0 items-start px-0.5 py-0.5 text-placeholder')
+              .append(
+                Domino.of('div')
+                  .classNames('flex h-5 w-full shrink-0 items-center justify-center self-start')
+                  .append(Domino.svg('ph--info--regular').classNames('shrink-0 size-4 opacity-70')),
+                Domino.of('div')
+                  .classNames('relative min-w-0')
+                  .append(
+                    Domino.of('div')
+                      .classNames('relative z-10 rounded-sm text-sm leading-5')
+                      .attributes({ 'data-status-text': '' })
+                      .text(this.text),
+                  ),
+              ),
+          ),
+      ).root;
+  }
+
+  override updateDOM(dom: HTMLElement) {
+    dom.querySelector<HTMLElement>('[data-status-text]')?.replaceChildren(this.text);
+    return true;
+  }
+}

package/src/components/widgets/SuggestionWidget.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { WidgetType } from '@codemirror/view';
+
+import { Domino, mx } from '@dxos/ui';
+
+/**
+ * Simple prompt widget.
+ */
+export class SuggestionWidget extends WidgetType {
+  constructor(private text: string) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this.text === other.text;
+  }
+
+  override toDOM() {
+    // NOTE: Container must have `dx-inline-size-container` (or `dx-size-container`) to support cqi.
+    //
+    // Inline-level root so consecutive suggestions flow onto one wrapped line rather than stacking —
+    // the tag is registered `block: false` and the renderer omits the usual block separator between
+    // them.
+    //
+    // Vertical space must be **padding, never margin**: CodeMirror measures a widget from its own box,
+    // and a margin sits outside what it can see, so the height model drifts from what is rendered, the
+    // error accumulates down the document, and the turn-fold gutter markers end up visibly misaligned.
+    // Adjacent chips are likewise spaced with trailing padding rather than a margin.
+    return Domino.of('span')
+      .classNames(mx('inline-flex max-w-[calc(100cqi-8px)] py-1 pe-1 overflow-hidden'))
+      .append(
+        Domino.of('button')
+          .attributes({
+            'data-density': 'md',
+            'data-action': 'submit',
+            'data-value': this.text,
+          })
+          .classNames(mx('dx-button gap-2 w-full overflow-hidden'))
+          .append(
+            Domino.of('dx-icon').attributes({
+              icon: 'ph--lightning--regular',
+            }),
+            Domino.of('span').classNames('flex-1 truncate min-w-0').text(this.text),
+          ),
+      ).root;
+  }
+}

package/src/components/widgets/SummaryWidget.tsx

@@ -0,0 +1,27 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { useTranslation } from '@dxos/react-ui';
+import { TogglePanel } from '@dxos/react-ui-components';
+import { type XmlWidgetProps, getXmlTextChild } from '@dxos/ui-editor';
+
+import { translationKey } from '../../translations';
+import { styles } from './defaults';
+
+export const SummaryWidget = ({ children }: XmlWidgetProps) => {
+  const { t } = useTranslation(translationKey);
+
+  return (
+    <TogglePanel.Root>
+      <TogglePanel.Content classNames={styles.border}>
+        <TogglePanel.Header classNames='text-sm dx-group-surface'>{t('summary.label')}</TogglePanel.Header>
+        <TogglePanel.Body>
+          <div className='p-1 text-sm text-subdued'>{getXmlTextChild(children ?? [])}</div>
+        </TogglePanel.Body>
+      </TogglePanel.Content>
+    </TogglePanel.Root>
+  );
+};

package/src/components/widgets/ToolWidget.stories.tsx

@@ -0,0 +1,55 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ContentBlock } from '@dxos/types';
+
+import { translations } from '../../translations';
+import { ToolWidget, type ToolWidgetProps } from './ToolWidget';
+
+const baseWidgetProps = {
+  _tag: 'toolkit',
+  range: { from: 0, to: 1 },
+} satisfies Pick<ToolWidgetProps, '_tag' | 'range'>;
+
+const toolCallAndResult: ContentBlock.Any[] = [
+  {
+    _tag: 'toolCall',
+    toolCallId: 'tc-story-1',
+    name: 'example_tool',
+    input: JSON.stringify({ query: 'status', limit: 10 }),
+    providerExecuted: false,
+  },
+  {
+    _tag: 'toolResult',
+    toolCallId: 'tc-story-1',
+    name: 'example_tool',
+    result: JSON.stringify({ ok: true, rows: [{ id: 1 }, { id: 2 }] }),
+    providerExecuted: false,
+  },
+];
+
+const meta = {
+  title: 'ui/react-ui-assistant/widgets/ToolWidget',
+  component: ToolWidget,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof ToolWidget>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    ...baseWidgetProps,
+    // The tag carries the run as JSON text; the widget parses it back out.
+    children: [JSON.stringify(toolCallAndResult)],
+  },
+};