@dxos/plugin-assistant 0.8.4-main.3eb6e50203 → 0.8.4-main.422d1c7879

package/src/components/ChatThread/ChatThread.stories.tsx

@@ -6,39 +6,37 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
 import * as Fiber from 'effect/Fiber';
 import * as Layer from 'effect/Layer';
-import React, { type CSSProperties, useEffect, useMemo, useState } from 'react';
+import React, { useEffect, useMemo, useState } from 'react';
 
+import { withPluginManager } from '@dxos/app-framework/testing';
 import { Database } from '@dxos/echo';
 import { runAndForwardErrors } from '@dxos/effect';
 import { ContextQueueService } from '@dxos/functions';
-import { faker } from '@dxos/random';
-import { useQueue, useSpace } from '@dxos/react-client/echo';
-import { withClientProvider } from '@dxos/react-client/testing';
-import { Popover } from '@dxos/react-ui';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import { MarkdownStream } from '@dxos/react-ui-components';
-import { EditorPreviewProvider, useEditorPreview } from '@dxos/react-ui-editor';
-import { Card } from '@dxos/react-ui-mosaic';
-import { render } from '@dxos/storybook-utils';
-import { type Message, Organization, Person } from '@dxos/types';
-
-import { createMessageGenerator } from '../../testing';
-import { translations } from '../../translations';
+import { ClientPlugin } from '@dxos/plugin-client';
+import { initializeIdentity } from '@dxos/plugin-client/testing';
+import { PreviewPlugin } from '@dxos/plugin-preview';
+import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { type Queue, useSpaces } from '@dxos/react-client/echo';
+import { EditorPreviewProvider } from '@dxos/react-ui-editor';
+import { Loading, withLayout, withTheme } from '@dxos/react-ui/testing';
+import { Message, Organization, Person } from '@dxos/types';
+
+import { createMessageGenerator } from '#testing';
 
+import { translations } from '../../translations';
 import { ChatThread, type ChatThreadProps } from './ChatThread';
-import { componentRegistry } from './registry';
-import TEXT from './testing/thread.md?raw';
 
-faker.seed(1);
+random.seed(1);
 
 type MessageGenerator = Effect.Effect<void, never, Database.Service | ContextQueueService>;
 
-type StoryProps = { generator?: MessageGenerator[]; delay?: number; wait?: boolean } & ChatThreadProps;
+type DefaultStoryProps = { generator?: MessageGenerator[]; delay?: number; wait?: boolean } & ChatThreadProps;
 
-const DefaultStory = ({ generator = [], delay = 0, wait, ...props }: StoryProps) => {
-  const space = useSpace();
-  const queueDxn = useMemo(() => space?.queues.create().dxn, [space]);
-  const queue = useQueue<Message.Message>(queueDxn);
+const DefaultStory = ({ generator = [], delay = 0, wait, ...props }: DefaultStoryProps) => {
+  const [space] = useSpaces();
+  const queue = useMemo<Queue<Message.Message> | undefined>(() => space?.queues.create(), [space]);
+  const messages = useQueueMessages(queue);
   const [done, setDone] = useState(false);
 
   // Generate messages.
@@ -55,6 +53,7 @@ const DefaultStory = ({ generator = [], delay = 0, wait, ...props }: StoryProps)
             yield* Effect.sleep(delay);
           }
         }
+
         setDone(true);
       }).pipe(Effect.provide(Layer.mergeAll(Database.layer(space.db), ContextQueueService.layer(queue)))),
     );
@@ -62,60 +61,67 @@ const DefaultStory = ({ generator = [], delay = 0, wait, ...props }: StoryProps)
     return () => {
       void runAndForwardErrors(Fiber.interrupt(fiber));
     };
-  }, [space, queue, generator]);
+  }, [space, queue, generator, delay]);
 
   if (wait && !done) {
-    return null;
+    return <Loading data={{ wait, done }} />;
   }
 
   return (
     <EditorPreviewProvider onLookup={async ({ dxn, label }) => ({ label, text: dxn })}>
-      <ChatThread {...props} messages={queue?.objects} />
-      <PreviewCard />
+      <ChatThread {...props} messages={messages} />
     </EditorPreviewProvider>
   );
 };
 
-const PreviewCard = () => {
-  const { target } = useEditorPreview('PreviewCard');
+const useQueueMessages = (queue?: Queue<Message.Message>) => {
+  const [messages, setMessages] = useState<Message.Message[]>([]);
 
-  return (
-    <Popover.Portal>
-      <Popover.Content onOpenAutoFocus={(event) => event.preventDefault()}>
-        <Popover.Viewport>
-          <Card.Root>
-            <Card.Heading>{target?.label}</Card.Heading>
-            {target && <Card.Text classNames='truncate line-clamp-3'>{target.text}</Card.Text>}
-          </Card.Root>
-        </Popover.Viewport>
-        <Popover.Arrow />
-      </Popover.Content>
-    </Popover.Portal>
-  );
+  useEffect(() => {
+    if (!queue) {
+      setMessages([]);
+      return;
+    }
+
+    const update = () => setMessages([...queue.objects]);
+    update();
+    return queue.subscribe(update);
+  }, [queue]);
+
+  return messages;
 };
 
 const meta = {
-  title: 'plugins/plugin-assistant/ChatThread',
+  title: 'plugins/plugin-assistant/components/ChatThread',
   component: ChatThread,
-  render: render(DefaultStory),
+  render: DefaultStory,
   decorators: [
     withTheme(),
     withLayout({ layout: 'column' }),
-    withClientProvider({
-      createIdentity: true,
-      createSpace: true,
-      types: [Organization.Organization, Person.Person],
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        StorybookPlugin({}),
+        PreviewPlugin(),
+        ClientPlugin({
+          types: [Organization.Organization, Person.Person],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              yield* initializeIdentity(client);
+            }),
+        }),
+      ],
     }),
   ],
   parameters: {
     layout: 'fullscreen',
     translations,
   },
-} satisfies Meta<StoryProps>;
+} satisfies Meta<DefaultStoryProps>;
 
 export default meta;
 
-type Story = StoryObj<StoryProps>;
+type Story = StoryObj<DefaultStoryProps>;
 
 export const Default: Story = {
   args: {
@@ -127,24 +133,11 @@ export const Default: Story = {
 export const Delayed: Story = {
   args: {
     generator: createMessageGenerator(),
-    delay: 1_000,
-    fadeIn: true,
-    cursor: false,
+    delay: 500,
+    options: {
+      autoScroll: true,
+      wire: true,
+      cursor: true,
+    },
   },
 };
-
-export const Raw: Story = {
-  render: () => (
-    <div className='contents' style={{ '--user-fill': 'var(--dx-amberFill)' } as CSSProperties}>
-      <MarkdownStream content={TEXT} />
-    </div>
-  ),
-};
-
-export const Static: Story = {
-  render: () => (
-    <div className='contents' style={{ '--user-fill': 'var(--dx-amberFill)' } as CSSProperties}>
-      <MarkdownStream content={TEXT} registry={componentRegistry} />
-    </div>
-  ),
-};

package/src/components/ChatThread/ChatThread.tsx

@@ -2,46 +2,49 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { type CSSProperties, forwardRef, useCallback, useEffect, useMemo, useState } from 'react';
+import React, { forwardRef, useCallback, useEffect, useMemo, useState } from 'react';
 
 import { PublicKey } from '@dxos/keys';
 import { type Identity } from '@dxos/react-client/halo';
-import { type ThemedClassName, useForwardedRef } from '@dxos/react-ui';
+import { type ThemedClassName, setRef } from '@dxos/react-ui';
 import { MarkdownStream, type MarkdownStreamController, type MarkdownStreamProps } from '@dxos/react-ui-components';
 import { type Message } from '@dxos/types';
 import { mx } from '@dxos/ui-theme';
 import { keyToFallback } from '@dxos/util';
 
 import { type ChatEvent } from '../Chat';
-
 import { blockToMarkdown, componentRegistry } from './registry';
 import { MessageSyncer } from './sync';
 
+const defaultOptions: MarkdownStreamProps['options'] = {
+  autoScroll: true,
+  // The `wire` extension intercepts append transactions, buffers the text, and drips it into
+  // the editor one character at a time (200 chars/sec by default) while keeping XML elements,
+  // markdown links and images atomic. It's what gives the smooth char-by-char typewriter you
+  // see in the MarkdownStream/Reasoning story.
+  wire: true,
+  cursor: true,
+};
+
 export type ChatThreadProps = ThemedClassName<
   {
     identity?: Identity;
     messages?: Message.Message[];
     error?: Error;
     onEvent?: (event: ChatEvent) => void;
-  } & Pick<MarkdownStreamProps, 'cursor' | 'fadeIn' | 'debug'>
+  } & Pick<MarkdownStreamProps, 'options' | 'debug'>
 >;
 
 // TODO(burdon): Memo thread position.
 export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThreadProps>(
-  (
-    { classNames, identity, messages = [], error, cursor = false, fadeIn = true, debug = false, onEvent },
-    forwardedRef,
-  ) => {
-    const controllerRef = useForwardedRef(forwardedRef);
+  ({ classNames, identity, messages = [], error, options = defaultOptions, debug = false, onEvent }, forwardedRef) => {
     const [controller, setController] = useState<MarkdownStreamController | null>(null);
-
-    // Callback ref to capture when MarkdownStream is mounted and trigger re-render.
-    const refCallback = useCallback(
-      (node: MarkdownStreamController | null) => {
-        controllerRef.current = node;
-        setController(node);
+    const handleMarkdownStreamRef = useCallback(
+      (instance: MarkdownStreamController | null) => {
+        setController(instance);
+        setRef(forwardedRef, instance);
       },
-      [controllerRef],
+      [forwardedRef],
     );
 
     const userHue = useMemo(
@@ -57,11 +60,13 @@ export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThread
     // Update document.
     const syncer = useMemo(() => controller && new MessageSyncer(controller, blockToMarkdown), [controller]);
     useEffect(() => {
-      const reset = syncer?.append(messages, true);
-      if (reset) {
+      if (!syncer) {
+        return;
+      }
+      if (syncer.update(messages)) {
         controller?.scrollToBottom('instant');
       }
-    }, [syncer, messages]);
+    }, [controller, syncer, messages]);
 
     // Event adapter.
     const handleEvent = useCallback<NonNullable<MarkdownStreamProps['onEvent']>>(
@@ -79,16 +84,15 @@ export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThread
     return (
       <div
         role='none'
-        className={mx('flex bs-full is-full justify-center overflow-hidden', classNames)}
-        style={{ '--user-fill': `var(--dx-${userHue}Fill)` } as CSSProperties}
+        data-hue={userHue}
+        className={mx('flex h-full w-full justify-center overflow-hidden', classNames)}
       >
         <MarkdownStream
-          ref={refCallback}
           registry={componentRegistry}
-          cursor={cursor}
-          fadeIn={fadeIn}
+          options={options}
           debug={debug}
           onEvent={handleEvent}
+          ref={handleMarkdownStreamRef}
         />
       </div>
     );

package/src/components/ChatThread/MarkdownStream.stories.tsx

@@ -0,0 +1,280 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useCallback, useEffect, useState } from 'react';
+
+import '@dxos/lit-ui';
+import { PublicKey } from '@dxos/keys';
+import { random } from '@dxos/random';
+import { Input, Toolbar } from '@dxos/react-ui';
+import { Panel } from '@dxos/react-ui';
+import {
+  MarkdownStream,
+  type MarkdownStreamController,
+  type MarkdownStreamProps,
+  textStream,
+} from '@dxos/react-ui-components';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ContentBlock } from '@dxos/types';
+import { keyToFallback } from '@dxos/util';
+
+import { translations } from '../../translations';
+import { componentRegistry } from './registry';
+import REASONING from './testing/reasoning.md?raw';
+import THINKING from './testing/thinking.md?raw';
+import THREAD_1 from './testing/thread-1.md?raw';
+import THREAD_WIDGETS from './testing/thread-widgets.md?raw';
+
+random.seed(123);
+
+const userHue = keyToFallback(PublicKey.random()).hue;
+
+type TextStreamOptions = {
+  wordsPerChunk?: number;
+  chunkDelay?: number;
+  variance?: number;
+};
+
+const defaultStreamOptions: TextStreamOptions = {
+  wordsPerChunk: 5,
+  chunkDelay: 200,
+  variance: 0.5,
+};
+
+/** Matches self-closing tool call tags in assistant markdown fixtures (e.g. thinking.md). */
+const TOOL_CALL_MARKUP_REGEX = /<toolCall\s+id="([^"]+)"\s*\/>/g;
+
+const extractToolCallIdsFromMarkdown = (markdown: string): string[] =>
+  [...markdown.matchAll(TOOL_CALL_MARKUP_REGEX)].map((match) => match[1]);
+
+const SAMPLE_TOOL_NAMES = [
+  'get_project_rules',
+  'list_mailboxes',
+  'query_inbox',
+  'enable_blueprint',
+  'create_schema',
+  'create_project',
+  'retry_operation',
+] as const;
+
+const sampleCallAndResultBlocks = (toolCallId: string, index: number): ContentBlock.Any[] => {
+  const name = SAMPLE_TOOL_NAMES[index % SAMPLE_TOOL_NAMES.length];
+  const input = JSON.stringify({ step: index + 1, tool: name });
+  const result = JSON.stringify({ ok: true, detail: `Sample result for ${name}.` });
+  return [
+    { _tag: 'toolCall', toolCallId, name, input, providerExecuted: false },
+    { _tag: 'toolResult', toolCallId, name, result, providerExecuted: false },
+  ];
+};
+
+type DefaultStoryProps = MarkdownStreamProps & {
+  initialContent?: string;
+  streamOptions?: TextStreamOptions;
+  /**
+   * When true, after loading `initialContent`, finds `<toolCall id="..." />` ids via
+   * {@link TOOL_CALL_MARKUP_REGEX} and seeds each portal widget with paired toolCall + toolResult blocks.
+   */
+  seedToolWidgetsFromMarkdown?: boolean;
+};
+
+const DefaultStory = ({
+  initialContent,
+  content,
+  streamOptions = defaultStreamOptions,
+  debug: debugProp,
+  seedToolWidgetsFromMarkdown = false,
+  ...props
+}: DefaultStoryProps) => {
+  const [controller, setController] = useState<MarkdownStreamController | null>(null);
+  const [streaming, setStreaming] = useState(false);
+  const [debug, setDebug] = useState(debugProp);
+
+  useEffect(() => {
+    if (!controller || !initialContent) {
+      return;
+    }
+
+    let cancelled = false;
+    void (async () => {
+      await controller.append(initialContent);
+      if (cancelled || !seedToolWidgetsFromMarkdown) {
+        return;
+      }
+
+      const toolCallIds = extractToolCallIdsFromMarkdown(initialContent);
+      toolCallIds.forEach((toolCallId, index) => {
+        controller.updateWidget(toolCallId, {
+          blocks: sampleCallAndResultBlocks(toolCallId, index),
+        });
+      });
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [controller, initialContent, seedToolWidgetsFromMarkdown]);
+
+  useEffect(() => {
+    if (!controller || !streaming || !content) {
+      return;
+    }
+
+    let cancelled = false;
+    void (async () => {
+      for await (const chunk of textStream(content + '\n', streamOptions)) {
+        if (cancelled) {
+          break;
+        }
+
+        await controller.append(chunk);
+      }
+
+      setStreaming(false);
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [controller, content, streaming]);
+
+  const handleReset = useCallback(() => {
+    setStreaming(false);
+    void controller?.setContent('');
+  }, [controller]);
+
+  return (
+    <Panel.Root data-hue={userHue}>
+      <Panel.Toolbar asChild>
+        <Toolbar.Root>
+          <Toolbar.IconButton
+            disabled={streaming}
+            icon='ph--play--regular'
+            iconOnly
+            label='Start'
+            onClick={() => setStreaming(true)}
+          />
+          <Toolbar.IconButton
+            disabled={!streaming}
+            icon='ph--stop--regular'
+            iconOnly
+            label='Stop'
+            onClick={() => setStreaming(false)}
+          />
+          <Toolbar.IconButton icon='ph--trash--regular' iconOnly label='Reset' onClick={handleReset} />
+          <Toolbar.Separator />
+          <Input.Root>
+            <Input.Label classNames='pr-1'>Debug</Input.Label>
+            <Input.Switch checked={debug} onCheckedChange={setDebug} />
+          </Input.Root>
+        </Toolbar.Root>
+      </Panel.Toolbar>
+      <Panel.Content>
+        <MarkdownStream {...props} debug={debug} ref={setController} />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/components/MarkdownStream',
+  render: DefaultStory,
+  decorators: [withTheme(), withLayout({ layout: 'column' })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    registry: componentRegistry,
+    initialContent: THREAD_1,
+    options: {
+      autoScroll: true,
+    },
+  },
+};
+
+export const Streaming: Story = {
+  args: {
+    registry: componentRegistry,
+    content: THREAD_1,
+    options: {
+      autoScroll: true,
+      wire: true,
+      cursor: true,
+    },
+  },
+};
+
+export const Widgets: Story = {
+  args: {
+    registry: componentRegistry,
+    initialContent: THREAD_WIDGETS,
+    options: {
+      autoScroll: true,
+    },
+  },
+};
+
+export const Debug: Story = {
+  args: {
+    initialContent: THREAD_1,
+    registry: componentRegistry,
+    content: THREAD_1,
+    debug: true,
+  },
+};
+
+export const Thinking: Story = {
+  args: {
+    initialContent: THINKING,
+    registry: componentRegistry,
+    seedToolWidgetsFromMarkdown: true,
+    options: {
+      autoScroll: true,
+    },
+  },
+};
+
+/**
+ * Splits a fixture at the first `</prompt>` so the prompt can be pre-loaded as initialContent
+ * (matching production: user prompts are submitted whole and never streamed) while the assistant
+ * body is streamed. Keeps the streaming-tail XML scan focused on the tags it is meant for
+ * (`<reasoning>`, `<status>`) instead of accumulating widgets for an unclosed `<prompt>`.
+ */
+const splitPromptAndBody = (markdown: string): { prompt: string; body: string } => {
+  const closing = '</prompt>';
+  const idx = markdown.indexOf(closing);
+  if (idx === -1) {
+    return { prompt: '', body: markdown };
+  }
+  return { prompt: markdown.slice(0, idx + closing.length), body: markdown.slice(idx + closing.length) };
+};
+
+const REASONING_PARTS = splitPromptAndBody(REASONING);
+
+/**
+ * Streams a reasoning block whose body contains a numbered list — exercises the streaming-tail XML
+ * scan as `<reasoning>` opens, accumulates list-marker lines like `"1. "`, and finally closes. Use
+ * this to visually verify that the reasoning widget renders cleanly without duplicate opening tags
+ * (regression from the per-line bullet stripper that used to collapse `"1. "` to empty mid-stream).
+ */
+export const Reasoning: Story = {
+  args: {
+    registry: componentRegistry,
+    initialContent: REASONING_PARTS.prompt,
+    content: REASONING_PARTS.body,
+    options: {
+      autoScroll: true,
+      wire: true,
+      cursor: true,
+    },
+  },
+};