@dxos/plugin-thread 0.8.4-main.fd6878d → 0.9.0

package/src/containers/ChannelArticle/ChannelArticle.stories.tsx

@@ -0,0 +1,108 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { Capability } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { AppCapabilities } from '@dxos/app-toolkit';
+import { Feed, Query } from '@dxos/echo';
+import { createFeedServiceLayer } from '@dxos/echo-client';
+import { invariant } from '@dxos/invariant';
+import { ClientPlugin } from '@dxos/plugin-client/testing';
+import { initializeIdentity } from '@dxos/plugin-client/testing';
+import { SpacePlugin } from '@dxos/plugin-space/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { Config } from '@dxos/react-client';
+import { useQuery, useSpaces } from '@dxos/react-client/echo';
+import { withLayout, withTheme, Loading } from '@dxos/react-ui/testing';
+import { Channel, Message, Thread } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { ThreadPlugin } from '../../ThreadPlugin';
+import { ChannelArticle, type ChannelArticleProps } from './ChannelArticle';
+
+// TODO(wittjosiah): Channel doesn't render full height.
+const DefaultStory = ({ roomId }: ChannelArticleProps) => {
+  const [space] = useSpaces();
+  const [channel] = useQuery(space?.db, Query.type(Channel.Channel));
+  if (!channel) {
+    return <Loading data={{ channel }} />;
+  }
+
+  return <ChannelArticle subject={channel} attendableId='story' roomId={roomId} role='article' />;
+};
+
+const meta = {
+  title: 'plugins/plugin-thread/containers/ChannelArticle',
+  component: ChannelArticle,
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column' }),
+    withPluginManager({
+      capabilities: [
+        Capability.contributes(AppCapabilities.Schema, [Channel.Channel, Feed.Feed, Thread.Thread, Message.Message]),
+      ],
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Channel.Channel, Feed.Feed, Thread.Thread, Message.Message],
+          config: new Config({
+            runtime: {
+              services: {
+                edge: {
+                  url: 'https://edge.dxos.workers.dev/',
+                },
+                iceProviders: [
+                  {
+                    urls: 'https://edge.dxos.workers.dev/ice',
+                  },
+                ],
+              },
+            },
+          }),
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              const { personalSpace } = yield* initializeIdentity(client);
+              const channel = personalSpace.db.add(Channel.make({ name: 'general' }));
+              yield* Effect.promise(() => channel.backend.config.load());
+              const feed = Channel.getFeed(channel);
+              invariant(feed, 'Channel is not feed-backed');
+              const seed = [
+                Message.make({ sender: { role: 'user' }, blocks: [{ _tag: 'text', text: 'Hello, channel.' }] }),
+                Message.make({
+                  sender: { role: 'user' },
+                  blocks: [{ _tag: 'text', text: 'Messages are stored in the feed.' }],
+                }),
+              ];
+              yield* Feed.append(feed, seed).pipe(Effect.provide(createFeedServiceLayer(personalSpace.queues)));
+            }),
+        }),
+        SpacePlugin({}),
+        ThreadPlugin(),
+      ],
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof ChannelArticle>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    // Fixed room for testing.
+    subject: undefined,
+    attendableId: 'story',
+    role: 'article',
+    roomId: '04a1d1911703b8e929d0649021a965',
+  },
+};

package/src/containers/ChannelArticle/ChannelArticle.tsx

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { useCapabilities, useOperationInvoker } from '@dxos/app-framework/ui';
+import { type AppSurface } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import { getSpace, useMembers } from '@dxos/react-client/echo';
+import { useIdentity } from '@dxos/react-client/halo';
+import { Panel } from '@dxos/react-ui';
+import { type Channel } from '@dxos/types';
+
+import { Chat } from '#components';
+import { useMessages, useStatus } from '#hooks';
+import { ThreadCapabilities, ThreadOperation, resolveProvider } from '#types';
+
+export type ChannelArticleProps = AppSurface.ObjectArticleProps<
+  Channel.Channel | undefined,
+  {
+    roomId?: string;
+    fullscreen?: boolean;
+  }
+>;
+
+/**
+ * Channel article: renders the channel chat inside a document panel. Messages
+ * are read and written through the channel's backend provider (resolved by
+ * `channel.backend.kind`), so the container is agnostic to where messages are
+ * stored. Read-only state defaults to the provider's policy, or to "channel
+ * carries foreign-key `Obj.Meta`" when the provider has none.
+ *
+ * The "Start video call" action and the in-call surface are contributed by
+ * plugin-calls — this container is call-agnostic.
+ */
+export const ChannelArticle = ({ subject: channel }: ChannelArticleProps) => {
+  const identity = useIdentity();
+  const space = channel ? getSpace(channel) : undefined;
+  const members = useMembers(space?.id);
+  const id = channel ? Obj.getURI(channel) : undefined;
+  const activity = useStatus(space, id);
+  const { invokePromise } = useOperationInvoker();
+
+  const providers = useCapabilities(ThreadCapabilities.ChannelBackend);
+  const provider = channel ? resolveProvider(providers, channel.backend.kind) : undefined;
+  const messages = useMessages(channel);
+  const readOnly = channel ? (provider?.readOnly?.(channel) ?? Obj.getMeta(channel).keys.length > 0) : false;
+
+  const handleSend = (text: string) => {
+    if (!channel || !identity || readOnly) {
+      return false;
+    }
+
+    void invokePromise(ThreadOperation.AppendChannelMessage, {
+      channel,
+      sender: { identityDid: identity.did },
+      text,
+    });
+
+    return true;
+  };
+
+  if (!space || !channel || !id) {
+    return null;
+  }
+
+  return (
+    <Panel.Root classNames='dx-document'>
+      <Panel.Content asChild>
+        <Chat
+          id={id}
+          identity={identity ?? undefined}
+          members={members}
+          messages={messages}
+          activity={activity}
+          onSend={handleSend}
+          readOnly={readOnly}
+        />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};

package/src/containers/ChannelArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export { ChannelArticle as default } from './ChannelArticle';

package/src/containers/ChannelCreatePanel/ChannelCreatePanel.tsx

@@ -0,0 +1,52 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useCallback, useMemo } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { Obj } from '@dxos/echo';
+import { type SpaceCapabilities } from '@dxos/plugin-space';
+import { Column } from '@dxos/react-ui';
+import { Form } from '@dxos/react-ui-form';
+
+import { ThreadCapabilities, buildChannelFormSchema } from '#types';
+
+/**
+ * Provider-driven create panel for channels. Reads the registered
+ * `ChannelBackend` providers and renders a react-ui-form whose schema is the
+ * assembled `{ name?, backend: Union(...) }` — a backend selector plus the
+ * selected provider's create fields (just a name field when there is a single
+ * field-less provider).
+ */
+export const ChannelCreatePanel = ({ target, onCreateObject }: SpaceCapabilities.CreateObjectCustomPanelProps) => {
+  const providers = useCapabilities(ThreadCapabilities.ChannelBackend);
+  const schema = useMemo(() => buildChannelFormSchema(providers), [providers]);
+
+  const handleSave = useCallback(
+    (values: { name?: string; backend?: { kind: string } & Record<string, unknown> }) => {
+      const { name, backend } = values;
+      const { kind, ...options } = backend ?? {};
+      void onCreateObject({ name, kind, options });
+    },
+    [onCreateObject],
+  );
+
+  return (
+    <Form.Root
+      autoFocus
+      db={Obj.isObject(target) ? Obj.getDatabase(target) : target}
+      schema={schema}
+      defaultValues={{}}
+      onSave={handleSave}
+      testId='create-channel-form'
+    >
+      <Column.Center>
+        <Form.Content>
+          <Form.FieldSet />
+          <Form.Submit />
+        </Form.Content>
+      </Column.Center>
+    </Form.Root>
+  );
+};

package/src/containers/ChannelCreatePanel/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { ChannelCreatePanel as default } from './ChannelCreatePanel';

package/src/containers/ThreadArticle/ThreadArticle.stories.tsx

@@ -0,0 +1,86 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Surface } from '@dxos/app-framework/ui';
+import { corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { useClient } from '@dxos/react-client';
+import { type Space } from '@dxos/react-client/echo';
+import { useIdentity } from '@dxos/react-client/halo';
+import { withClientProvider } from '@dxos/react-client/testing';
+import { useAsyncEffect } from '@dxos/react-ui';
+import { Thread as ThreadComponent } from '@dxos/react-ui-thread';
+import { withLayout, Loading } from '@dxos/react-ui/testing';
+import { Message, Thread } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { ThreadArticle } from './ThreadArticle';
+
+random.seed(1);
+
+const DefaultStory = () => {
+  const client = useClient();
+  const identity = useIdentity();
+  const [space, setSpace] = useState<Space>();
+  const [thread, setThread] = useState<Thread.Thread | null>();
+
+  useAsyncEffect(async () => {
+    if (identity) {
+      const space = await client.spaces.create();
+      const thread = space.db.add(Thread.make({ status: 'active' }));
+      setSpace(space);
+      setThread(thread);
+    }
+  }, [identity]);
+
+  if (!identity || !thread || !space) {
+    return <Loading data={{ identity: !!identity, space: !!space, thread: !!thread }} />;
+  }
+
+  return <ThreadArticle space={space} thread={thread} />;
+};
+
+const meta = {
+  title: 'plugins/plugin-thread/containers/ThreadArticle',
+  component: ThreadComponent.Root as any,
+  render: DefaultStory,
+  decorators: [
+    withLayout({ layout: 'column' }),
+    // TODO(wittjosiah): This shouldn't depend on app framework (use withClientProvider instead).
+    //  Currently this is required because Chat renders an object tile via a Surface.
+    withPluginManager({
+      plugins: corePlugins(),
+      capabilities: [
+        Capability.contributes(
+          Capabilities.ReactSurface,
+          Surface.create({
+            id: 'test',
+            role: 'card',
+            component: ({ role }) => <span>{JSON.stringify({ role })}</span>,
+          }),
+        ),
+      ],
+    }),
+    withClientProvider({
+      createSpace: true,
+      types: [Thread.Thread, Message.Message],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/containers/ThreadArticle/ThreadArticle.tsx

@@ -0,0 +1,75 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { Obj, Ref } from '@dxos/echo';
+import { type Space, useMembers } from '@dxos/react-client/echo';
+import { useIdentity } from '@dxos/react-client/halo';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/react-ui';
+import { type ThreadContentProps } from '@dxos/react-ui-thread';
+import { Message, type Thread } from '@dxos/types';
+import { isNonNullable } from '@dxos/util';
+
+import { Chat } from '#components';
+import { useStatus } from '#hooks';
+
+export type ThreadArticleProps = ThemedClassName<
+  {
+    space: Space;
+    thread: Thread.Thread;
+    context?: Obj.Unknown;
+    autoFocus?: boolean;
+  } & Pick<ThreadContentProps, 'current'>
+>;
+
+/**
+ * Renders an AutoMerge {@link Thread} as a chat: appends new messages by pushing
+ * onto `thread.messages`. Used for comment threads and the meeting in-call chat.
+ */
+export const ThreadArticle = composable<HTMLDivElement, ThreadArticleProps>(
+  ({ space, thread, context, autoFocus, current, ...props }, forwardedRef) => {
+    const id = Obj.getURI(thread);
+    const identity = useIdentity()!;
+    const members = useMembers(space?.id);
+    const activity = useStatus(space, id);
+
+    const messages = useMemo(
+      () => thread.messages.map((message) => message.target).filter(isNonNullable),
+      [thread.messages],
+    );
+
+    const handleSend = (text: string) => {
+      Obj.update(thread, (thread) => {
+        thread.messages.push(
+          Ref.make(
+            Obj.make(Message.Message, {
+              created: new Date().toISOString(),
+              sender: { identityDid: identity.did },
+              blocks: [{ _tag: 'text', text }],
+              properties: context ? { context: Ref.make(context) } : undefined,
+            }),
+          ),
+        );
+      });
+      return true;
+    };
+
+    return (
+      <Chat
+        {...composableProps(props)}
+        id={id}
+        identity={identity}
+        members={members}
+        messages={messages}
+        activity={activity}
+        onSend={handleSend}
+        autoFocus={autoFocus}
+        current={current}
+        ref={forwardedRef}
+      />
+    );
+  },
+);

package/src/containers/ThreadArticle/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { ThreadArticle as default } from './ThreadArticle';

package/src/containers/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const ChannelCreatePanel: ComponentType<any> = lazy(() => import('./ChannelCreatePanel'));
+export const ChannelArticle: ComponentType<any> = lazy(() => import('./ChannelArticle'));
+export const ThreadArticle: ComponentType<any> = lazy(() => import('./ThreadArticle'));

package/src/hooks/index.ts

@@ -2,8 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './analytics';
-export * from './useDebugMode';
+export * from './useMessages';
 export * from './useStatus';
-export * from './useVideoStreamTrack';
-export * from './useInaudibleAudioStreamTrack';

package/src/hooks/useMessages.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+
+import { useCapabilities } from '@dxos/app-framework/ui';
+import { type Channel, type Message } from '@dxos/types';
+
+import { ThreadCapabilities, resolveProvider } from '../types';
+
+const EMPTY: readonly Message.Message[] = [];
+
+/** Reactive message list for a channel, resolved through its backend provider. */
+export const useMessages = (channel: Channel.Channel | undefined): readonly Message.Message[] => {
+  const providers = useCapabilities(ThreadCapabilities.ChannelBackend);
+  const provider = useMemo(
+    () => (channel ? resolveProvider(providers, channel.backend.kind) : undefined),
+    [providers, channel],
+  );
+
+  const ref = useRef<readonly Message.Message[]>(EMPTY);
+  const subscribe = useCallback(
+    (onChange: () => void) => {
+      if (!provider || !channel) {
+        return () => {};
+      }
+      return provider.subscribe(channel, (messages) => {
+        ref.current = messages;
+        onChange();
+      });
+    },
+    [provider, channel],
+  );
+
+  return useSyncExternalStore(subscribe, () => ref.current);
+};

package/src/index.ts

@@ -2,9 +2,9 @@
 // Copyright 2023 DXOS.org
 //
 
-export { ThreadCapabilities } from './capabilities';
-export * from './calls';
+// TODO(wittjosiah): Hooks should not be exported from the plugin package at all.
+//   Either refactor callers to not need them or factor them out to a shared package.
 export * from './hooks';
 export * from './meta';
-
-export * from './ThreadPlugin';
+export * from './paths';
+export * from './types';

package/src/meta.ts

@@ -2,16 +2,34 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
+import { trim } from '@dxos/util';
 
-export const THREAD_PLUGIN = 'dxos.org/plugin/thread';
-export const THREAD_ITEM = `${THREAD_PLUGIN}/item`;
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.thread'),
+  name: 'Threads',
+  author: 'DXOS',
+  description: trim`
+    ThreadPlugin provides chat: channels backed by an ECHO feed and free-standing
+    message threads. It renders the channel article and companion surfaces plus a
+    thread surface, and contributes the operations that create a default channel on
+    space creation, create new channels, and append messages.
 
-// TODO(wittjosiah): Needs screenshots.
-export const meta: PluginMeta = {
-  id: THREAD_PLUGIN,
-  name: 'Chat',
-  description: 'Chat via text, voice, and video in channels or create comment threads on objects.',
+    Channel messages are stored in the channel's feed queue and rendered newest-last
+    with a pinned composer; externally-synced channels (carrying foreign-key
+    metadata, e.g. Slack/Discord-sourced rooms) render read-only because there is no
+    local-write path back to the source. Free-standing threads render their messages
+    and append by pushing onto the thread's message list.
+
+    The shared message and thread UI comes from @dxos/react-ui-thread; the Channel,
+    Message, and Thread schema come from @dxos/types. Document comments and the
+    comment-thread AI agent live in the @dxos/plugin-comments plugin.
+  `,
   icon: 'ph--video-conference--regular',
+  iconHue: 'rose',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-thread',
-};
+  spec: 'PLUGIN.mdl',
+});
+
+export const THREAD_ITEM = `${meta.id}.item`;

package/src/operations/append-channel-message.ts

@@ -0,0 +1,31 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+import { Message } from '@dxos/types';
+
+import { ThreadCapabilities, ThreadOperation, resolveProvider } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.AppendChannelMessage> =
+  ThreadOperation.AppendChannelMessage.pipe(
+    Operation.withHandler(
+      Effect.fnUntraced(function* ({ channel, sender, text }) {
+        const providers = yield* Capability.getAll(ThreadCapabilities.ChannelBackend);
+        const provider = resolveProvider(providers, channel.backend.kind);
+        invariant(provider, `No channel backend for kind: ${channel.backend.kind}`);
+
+        const message = Message.make({
+          sender,
+          blocks: [{ _tag: 'text', text }],
+        });
+        yield* provider.send(channel, message);
+      }),
+    ),
+  );
+
+export default handler;

package/src/operations/create-channel.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+import { invariant } from '@dxos/invariant';
+import { Channel } from '@dxos/types';
+
+import { ThreadCapabilities, ThreadOperation, resolveProvider } from '../types';
+
+const handler: Operation.WithHandler<typeof ThreadOperation.CreateChannel> = ThreadOperation.CreateChannel.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ name, kind, options }) {
+      if (!kind || kind === Channel.FeedBackendKind) {
+        return { object: Channel.make({ name }) };
+      }
+
+      const providers = yield* Capability.getAll(ThreadCapabilities.ChannelBackend);
+      const provider = resolveProvider(providers, kind);
+      invariant(provider, `No channel backend for kind: ${kind}`);
+      const config = provider.makeConfig(options ?? {});
+      return { object: Channel.make({ name, backend: { kind, config } }) };
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const ThreadOperationHandlerSet = OperationHandlerSet.lazy(
+  () => import('./append-channel-message'),
+  () => import('./create-channel'),
+);

package/src/paths.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createTypeSectionPaths } from '@dxos/app-toolkit';
+import { Channel } from '@dxos/types';
+
+const { getSectionPath: getChannelsPath, getObjectPath: getChannelPath } = createTypeSectionPaths(Channel.Channel);
+
+export { getChannelsPath, getChannelPath };

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const ThreadPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { ThreadOperationHandlerSet } from './operations';