@dxos/plugin-assistant 0.8.4-main.406dc2a → 0.8.4-main.422d1c7879

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

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Database, Filter, Obj } from '@dxos/echo';
+import { DxAnchor } from '@dxos/lit-ui/react';
+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 { useQuery, useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout } from '@dxos/react-ui/testing';
+import { Organization } from '@dxos/types';
+
+/**
+ * Production-style click → popover demo.
+ *
+ * Wires up the same chain Composer uses:
+ * - `<DxAnchor dxn=…>label</DxAnchor>` fires `DxAnchorActivate` on click.
+ * - `PreviewPlugin`'s `preview-popover` capability listens for the event, resolves the DXN
+ *   to a real ECHO object via `space.db.makeRef(dxn).load()`, then invokes
+ *   `LayoutOperation.UpdatePopover`.
+ * - `StorybookPlugin` provides both the `LayoutOperation.UpdatePopover` handler (mutating
+ *   the layout-state atom) and the `<Layout>` shell that renders the popover via
+ *   `<Surface.Surface type={AppSurface.Card} data={popoverContent}>`.
+ * - `PreviewPlugin` also registers Card-role surfaces (Organization, Person, Task, …); the
+ *   Surface system picks the matching one based on the resolved object's type.
+ *
+ * Click the anchor — the matching Card surface (from plugin-preview) renders inside the
+ * popover, anchored to the trigger.
+ */
+const DefaultStory = () => {
+  const [space] = useSpaces();
+  const [organization] = useQuery(space?.db, Filter.type(Organization.Organization));
+  if (!organization) {
+    return <Loading />;
+  }
+
+  const dxn = Obj.getDXN(organization).toString();
+  return (
+    <div role='none' className='flex flex-col gap-2 p-4'>
+      <p>
+        Click{' '}
+        <DxAnchor className='dx-tag--anchor' dxn={dxn}>
+          {organization.name}
+        </DxAnchor>{' '}
+        to open the popover.
+      </p>
+    </div>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-assistant/components/ChatThread/Anchor',
+  render: DefaultStory,
+  decorators: [
+    withLayout({ layout: 'centered' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        StorybookPlugin({}),
+        PreviewPlugin(),
+        ClientPlugin({
+          types: [Organization.Organization],
+          onClientInitialized: Effect.fnUntraced(function* ({ client }) {
+            const { personalSpace } = yield* initializeIdentity(client);
+            yield* Effect.gen(function* () {
+              yield* Database.add(
+                Obj.make(Organization.Organization, {
+                  name: 'DXOS',
+                  website: 'https://dxos.org',
+                  description: 'A decentralized network for collaborative applications.',
+                }),
+              );
+            }).pipe(Effect.provide(Database.layer(personalSpace.db)));
+          }),
+        }),
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

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

@@ -8,31 +8,36 @@ import * as Fiber from 'effect/Fiber';
 import * as Layer from 'effect/Layer';
 import React, { useEffect, useMemo, useState } from 'react';
 
-import { ContextQueueService, DatabaseService } 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 { withTheme } from '@dxos/react-ui/testing';
-import { PreviewPopoverProvider, usePreviewPopover } from '@dxos/react-ui-editor/testing';
-import { Card } from '@dxos/react-ui-stack';
-import { DataType } from '@dxos/schema';
-
-import { createMessageGenerator } from '../../testing';
-import { translations } from '../../translations';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Database } from '@dxos/echo';
+import { runAndForwardErrors } from '@dxos/effect';
+import { ContextQueueService } from '@dxos/functions';
+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 { ChatThread, type ChatThreadController, type ChatThreadProps } from './ChatThread';
+import { translations } from '../../translations';
+import { ChatThread, type ChatThreadProps } from './ChatThread';
 
-faker.seed(1);
+random.seed(1);
 
-type MessageGenerator = Effect.Effect<void, never, DatabaseService | ContextQueueService>;
+type MessageGenerator = Effect.Effect<void, never, Database.Service | ContextQueueService>;
 
-type StoryProps = ChatThreadProps & { generator?: MessageGenerator[]; delay?: number };
+type DefaultStoryProps = { generator?: MessageGenerator[]; delay?: number; wait?: boolean } & ChatThreadProps;
 
-const DefaultStory = ({ generator = [], delay = 0, ...props }: StoryProps) => {
-  const space = useSpace();
-  const queueDxn = useMemo(() => space?.queues.create().dxn, [space]);
-  const queue = useQueue<DataType.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.
   useEffect(() => {
@@ -48,82 +53,91 @@ const DefaultStory = ({ generator = [], delay = 0, ...props }: StoryProps) => {
             yield* Effect.sleep(delay);
           }
         }
-      }).pipe(Effect.provide(Layer.mergeAll(DatabaseService.layer(space.db), ContextQueueService.layer(queue)))),
+
+        setDone(true);
+      }).pipe(Effect.provide(Layer.mergeAll(Database.layer(space.db), ContextQueueService.layer(queue)))),
     );
 
     return () => {
-      void Effect.runPromise(Fiber.interrupt(fiber));
+      void runAndForwardErrors(Fiber.interrupt(fiber));
     };
-  }, [space, queue, generator]);
+  }, [space, queue, generator, delay]);
 
-  // Set context.
-  const [controller, setController] = useState<ChatThreadController | null>(null);
-  useEffect(() => {
-    // controller?.setContext({ timestamp: Date.now() });
-  }, [controller]);
+  if (wait && !done) {
+    return <Loading data={{ wait, done }} />;
+  }
 
-  // TODO(burdon): Elsewhere PreviewProvider is implemented via the plugin-preview.
   return (
-    <PreviewPopoverProvider
-      onLookup={async ({ label, ref }) => {
-        return { label, text: ref };
-      }}
-    >
-      <ChatThread {...props} messages={queue?.objects ?? []} ref={setController} />
-      <PreviewCard />
-    </PreviewPopoverProvider>
+    <EditorPreviewProvider onLookup={async ({ dxn, label }) => ({ label, text: dxn })}>
+      <ChatThread {...props} messages={messages} />
+    </EditorPreviewProvider>
   );
 };
 
-// TODO(burdon): Factor out.
-// TODO(burdon): Provide renderer for preview extension.
-const PreviewCard = () => {
-  const { target } = usePreviewPopover('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.SurfaceRoot role='card--popover'>
-            <Card.Heading>{target?.label}</Card.Heading>
-            {target && <Card.Text classNames='truncate line-clamp-3'>{target.text}</Card.Text>}
-          </Card.SurfaceRoot>
-        </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: DefaultStory,
   decorators: [
-    withTheme,
-    withClientProvider({ createIdentity: true, createSpace: true, types: [DataType.Organization, DataType.Person] }),
+    withTheme(),
+    withLayout({ layout: 'column' }),
+    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<typeof ChatThread>;
+} satisfies Meta<DefaultStoryProps>;
 
 export default meta;
 
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<DefaultStoryProps>;
 
 export const Default: Story = {
   args: {
     generator: createMessageGenerator(),
+    wait: true,
   },
 };
 
 export const Delayed: Story = {
   args: {
     generator: createMessageGenerator(),
-    delay: 3_000,
-    fadeIn: true,
-    cursor: false,
+    delay: 500,
+    options: {
+      autoScroll: true,
+      wire: true,
+      cursor: true,
+    },
   },
 };

package/src/components/ChatThread/ChatThread.tsx

@@ -2,53 +2,55 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, {
-  type CSSProperties,
-  forwardRef,
-  useCallback,
-  useEffect,
-  useImperativeHandle,
-  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 } from '@dxos/react-ui';
+import { type ThemedClassName, setRef } from '@dxos/react-ui';
 import { MarkdownStream, type MarkdownStreamController, type MarkdownStreamProps } from '@dxos/react-ui-components';
-import { mx } from '@dxos/react-ui-theme';
-import { type DataType } from '@dxos/schema';
+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';
 
-export type ChatThreadController = Pick<MarkdownStreamController, 'setContext' | 'scrollToBottom'>;
+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?: DataType.Message[];
+    messages?: Message.Message[];
     error?: Error;
-    overscroll?: number;
     onEvent?: (event: ChatEvent) => void;
-  } & Pick<MarkdownStreamProps, 'cursor' | 'fadeIn' | 'overscroll'>
+  } & Pick<MarkdownStreamProps, 'options' | 'debug'>
 >;
 
-export const ChatThread = forwardRef<ChatThreadController | null, ChatThreadProps>(
-  (
-    { classNames, identity, messages = [], error, cursor = false, fadeIn = true, overscroll, onEvent },
-    forwardedRef,
-  ) => {
-    const userHue = useMemo(() => {
-      return identity?.profile?.data?.hue || keyToFallback(identity?.identityKey ?? PublicKey.random()).hue;
-    }, [identity]);
-
-    // Expose controller.
+// TODO(burdon): Memo thread position.
+export const ChatThread = forwardRef<MarkdownStreamController | null, ChatThreadProps>(
+  ({ classNames, identity, messages = [], error, options = defaultOptions, debug = false, onEvent }, forwardedRef) => {
     const [controller, setController] = useState<MarkdownStreamController | null>(null);
-    useImperativeHandle(forwardedRef, () => (controller ? controller : (null as any)), [controller]);
+    const handleMarkdownStreamRef = useCallback(
+      (instance: MarkdownStreamController | null) => {
+        setController(instance);
+        setRef(forwardedRef, instance);
+      },
+      [forwardedRef],
+    );
+
+    const userHue = useMemo(
+      () => identity?.profile?.data?.hue || keyToFallback(identity?.identityKey ?? PublicKey.random()).hue,
+      [identity],
+    );
 
     // Show error.
     useEffect(() => {
@@ -58,19 +60,20 @@ export const ChatThread = forwardRef<ChatThreadController | null, ChatThreadProp
     // Update document.
     const syncer = useMemo(() => controller && new MessageSyncer(controller, blockToMarkdown), [controller]);
     useEffect(() => {
-      syncer?.sync(messages);
-    }, [syncer, messages]);
+      if (!syncer) {
+        return;
+      }
+      if (syncer.update(messages)) {
+        controller?.scrollToBottom('instant');
+      }
+    }, [controller, syncer, messages]);
 
-    // Event handler.
+    // Event adapter.
     const handleEvent = useCallback<NonNullable<MarkdownStreamProps['onEvent']>>(
-      (ev) => {
-        switch (ev.type) {
+      ({ type, value }) => {
+        switch (type) {
           case 'submit': {
-            ev.value &&
-              onEvent?.({
-                type: 'submit',
-                text: ev.value,
-              });
+            value && onEvent?.({ type, text: value });
             break;
           }
         }
@@ -80,16 +83,16 @@ export const ChatThread = forwardRef<ChatThreadController | null, ChatThreadProp
 
     return (
       <div
-        className={mx('flex bs-full is-full justify-center overflow-hidden', classNames)}
-        style={{ '--user-fill': `var(--dx-${userHue}Fill)` } as CSSProperties}
+        role='none'
+        data-hue={userHue}
+        className={mx('flex h-full w-full justify-center overflow-hidden', classNames)}
       >
         <MarkdownStream
-          ref={setController}
           registry={componentRegistry}
-          cursor={cursor}
-          fadeIn={fadeIn}
-          overscroll={overscroll}
+          options={options}
+          debug={debug}
           onEvent={handleEvent}
+          ref={handleMarkdownStreamRef}
         />
       </div>
     );

package/src/components/ChatThread/Link.tsx

@@ -5,7 +5,7 @@
 import React, { useMemo } from 'react';
 
 import { type Space } from '@dxos/client/echo';
-import { Obj } from '@dxos/echo';
+import { Entity } from '@dxos/echo';
 import { type DXN } from '@dxos/keys';
 import { DxAnchor } from '@dxos/lit-ui/react';
 
@@ -15,11 +15,11 @@ export type ObjectLinkProps = {
 };
 
 export const ObjectLink = ({ space, dxn }: ObjectLinkProps) => {
-  const ref = useMemo(() => space.db.ref(dxn), [space, dxn.toString()]);
+  const ref = useMemo(() => space.db.makeRef(dxn), [space, dxn.toString()]);
 
-  const title = Obj.getLabel(ref.target) ?? ref.target?.id ?? ref.dxn.toString();
+  const title = (ref.target && Entity.getLabel(ref.target)) ?? ref.target?.id ?? ref.dxn.toString();
   return (
-    <DxAnchor rootclassname='dx-tag--anchor' refid={dxn.toString()}>
+    <DxAnchor rootclassname='dx-tag--anchor' dxn={dxn.toString()}>
       {title}
     </DxAnchor>
   );