@dxos/plugin-transcription 0.8.4-main.abd8ff62ef → 0.8.4-main.bc2380dfbc

package/src/components/Oracle/Oracle.tsx

@@ -0,0 +1,141 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Primitive } from '@radix-ui/react-primitive';
+import { Slot } from '@radix-ui/react-slot';
+import React, { type PropsWithChildren, createContext, useContext, useMemo } from 'react';
+
+import '@dxos/react-ui-graph/styles/graph.css';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { TextBlock } from '@dxos/react-ui-components';
+import { SVG } from '@dxos/react-ui-graph';
+import { composableProps, mx, slottable } from '@dxos/ui-theme';
+import { type SlottableProps } from '@dxos/ui-types';
+
+//
+// Context
+//
+
+type OracleContextValue = {
+  /** Latest utterance / phrase rendered by `Oracle.Text`. */
+  text: string;
+  /** Per-character reveal delay in ms for the streaming TextBlock. */
+  delay: number;
+};
+
+const OracleContext = createContext<OracleContextValue | null>(null);
+
+const useOracleContext = (consumer: string): OracleContextValue => {
+  const ctx = useContext(OracleContext);
+  if (!ctx) {
+    throw new Error(`<Oracle.${consumer}> must be rendered inside <Oracle.Root>`);
+  }
+  return ctx;
+};
+
+//
+// Root (headless — provides context only, renders no DOM)
+//
+
+export type OracleRootProps = PropsWithChildren<{
+  /** Latest utterance / phrase rendered by `Oracle.Text`. */
+  text?: string;
+  /** Per-character reveal delay in ms for the streaming TextBlock. @default 12 */
+  delay?: number;
+}>;
+
+/**
+ * Oracle surface root. Headless — provides text/delay context to subcomponents and renders
+ * no DOM of its own. Wrap subcomponents in `<Oracle.Content>` for the standard relative
+ * stacking layout, or place `<Oracle.Canvas>` / `<Oracle.Text>` inside any positioned
+ * container of your choice.
+ */
+const Root = ({ children, text = '', delay = 12 }: OracleRootProps) => {
+  const value = useMemo(() => ({ text, delay }), [text, delay]);
+  return <OracleContext.Provider value={value}>{children}</OracleContext.Provider>;
+};
+
+//
+// Content
+//
+
+export type OracleContentProps = SlottableProps;
+
+/**
+ * Positioned container that stacks `Oracle.Canvas` (the SVG graph viewport, absolutely
+ * positioned to fill) under `Oracle.Text` (the centered overlay). Use this for the standard
+ * Oracle layout; skip it if you need custom positioning.
+ *
+ * Pass `asChild` to merge the positioning + sizing onto a parent slot (e.g. `Panel.Content`).
+ */
+const Content = slottable<HTMLDivElement>(({ children, asChild, ...props }, forwardedRef) => {
+  const Comp = asChild ? Slot : Primitive.div;
+  return (
+    <Comp {...composableProps(props, { classNames: 'relative dx-expander' })} ref={forwardedRef}>
+      {children}
+    </Comp>
+  );
+});
+
+Content.displayName = 'Oracle.Content';
+
+//
+// Canvas
+//
+
+export type OracleCanvasProps = ThemedClassName<PropsWithChildren<{}>>;
+
+/**
+ * SVG graph viewport. Renders sensible defaults (markers, grid, pan/zoom, empty graph)
+ * when no children are supplied; consumers can replace those by passing their own
+ * SVG.* children (e.g. a populated `<SVG.Graph model={…} />`).
+ */
+const Canvas = ({ classNames, children }: OracleCanvasProps) => (
+  <SVG.Root centered classNames={mx('absolute inset-0', classNames)}>
+    {children ?? (
+      <>
+        <SVG.Markers />
+        <SVG.Grid />
+        <SVG.Zoom extent={[1 / 4, 4]}>
+          <SVG.Graph />
+        </SVG.Zoom>
+      </>
+    )}
+  </SVG.Root>
+);
+
+//
+// Text
+//
+
+export type OracleTextProps = ThemedClassName<{}>;
+
+/**
+ * Centered text overlay. Reads `text` and `delay` from `Oracle.Root` context and renders
+ * a streaming `TextBlock` floating above the canvas. Pointer-events are disabled so the
+ * underlying graph remains interactive.
+ */
+const Text = ({ classNames }: OracleTextProps) => {
+  const { text, delay } = useOracleContext('Text');
+  return (
+    <div className='pointer-events-none absolute inset-0 flex items-center justify-center'>
+      <TextBlock
+        classNames={mx('max-w-xl px-6 py-4 text-center text-2xl font-medium text-balance text-subdued', classNames)}
+        text={text}
+        delay={delay}
+      />
+    </div>
+  );
+};
+
+//
+// Namespace
+//
+
+export const Oracle = {
+  Root,
+  Content,
+  Canvas,
+  Text,
+};

package/src/components/Oracle/index.ts

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

package/src/components/Transcription/Transcription.stories.tsx

@@ -5,29 +5,22 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
 import type * as Types from 'effect/Types';
-import React, { type FC, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
 
 import { withPluginManager } from '@dxos/app-framework/testing';
-import { Key } from '@dxos/echo';
-import { ClientPlugin } from '@dxos/plugin-client';
-import { initializeIdentity } from '@dxos/plugin-client/testing';
-import { PreviewPlugin } from '@dxos/plugin-preview';
+import { Feed, Filter, Obj, Query } from '@dxos/echo';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { PreviewPlugin } from '@dxos/plugin-preview/testing';
 import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
 import { random } from '@dxos/random';
-import { useMembers, useSpaces } from '@dxos/react-client/echo';
-import { IconButton, Toolbar } from '@dxos/react-ui';
+import { useMembers, useQuery, useSpaces } from '@dxos/react-client/echo';
+import { IconButton, Panel, Toolbar } from '@dxos/react-ui';
 import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
 import { withLayout } from '@dxos/react-ui/testing';
-import { TestSchema } from '@dxos/schema/testing';
-import { type ContentBlock, type Message, Organization, Person } from '@dxos/types';
-
-import { useQueueModelAdapter } from '#hooks';
-import {
-  MessageBuilder,
-  TestItem,
-  useTestTranscriptionQueue,
-  useTestTranscriptionQueueWithEntityExtraction,
-} from '#testing';
+import { type ContentBlock, Message, Organization, Person } from '@dxos/types';
+
+import { useFeedModelAdapter } from '#hooks';
+import { MessageBuilder, TestItem, useTestTranscriptionQueue } from '#testing';
 import { translations } from '#translations';
 
 import { SerializationModel } from '../../model';
@@ -36,56 +29,69 @@ import { Transcription, type TranscriptionProps } from './Transcription';
 
 random.seed(1);
 
-/**
- * Story wrapper with test controls.
- */
-const TranscriptContainer: FC<
-  TranscriptionProps & {
-    running: boolean;
-    onRunningChange: (running: boolean) => void;
-    onReset?: () => void;
-  }
-> = ({ model, running, onRunningChange, onReset }) => {
-  return (
-    <div className='grid grid-rows-[1fr_40px] grow divide-y divide-separator'>
-      <Transcription model={model} />
-      <div className='grid grid-cols-[1fr_16rem] overflow-hidden'>
-        <div className='flex items-center'>
-          <JsonHighlighter data={model.toJSON()} indent={0} classNames='text-sm' />
-        </div>
-        <Toolbar.Root classNames='justify-end'>
-          <IconButton
-            icon={running ? 'ph--pause--regular' : 'ph--play--regular'}
-            label={running ? 'Pause' : 'Start'}
-            onClick={() => onRunningChange(!running)}
-          />
-          {onReset && <IconButton icon='ph--x--regular' label='Reset' onClick={onReset} />}
-        </Toolbar.Root>
-      </div>
-    </div>
+type Source = 'local' | 'feed';
+
+type DefaultStoryProps = {
+  /** Where transcript messages come from. */
+  source?: Source;
+  /** Number of synthetic messages to pre-populate (local source only). */
+  seed?: number;
+};
+
+const DefaultStory = ({ source = 'local', seed = 0, ...props }: DefaultStoryProps) => {
+  const [resetKey, setResetKey] = useState(0);
+  const handleReset = useCallback(() => setResetKey((value) => value + 1), []);
+  return source === 'feed' ? (
+    <FeedStory key={resetKey} onReset={handleReset} {...props} />
+  ) : (
+    <LocalStory key={resetKey} seed={seed} onReset={handleReset} {...props} />
   );
 };
 
-type DefaultStoryProps = { messages?: Message.Message[] } & Pick<
-  TranscriptionProps,
-  'ignoreAttention' | 'attendableId'
->;
+type InnerProps = {
+  onReset: () => void;
+};
 
-/**
- * Basic story mutates array of messages.
- */
-const BasicStory = ({ messages: initialMessages = [], ...props }: DefaultStoryProps) => {
-  const [reset, setReset] = useState({});
+const LocalStory = ({ seed = 0, onReset, ...props }: InnerProps & { seed?: number }) => {
   const builder = useMemo(() => new MessageBuilder(), []);
+  const [initialMessages, setInitialMessages] = useState<Message.Message[]>([]);
+  const [ready, setReady] = useState(seed === 0);
+
+  useEffect(() => {
+    // Reset on every seed change so Storybook controls don't leave stale messages from a prior run.
+    let cancelled = false;
+    setInitialMessages([]);
+    setReady(seed === 0);
+
+    if (seed === 0) {
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    void Promise.all(Array.from({ length: seed }, () => builder.createMessage())).then((messages) => {
+      if (cancelled) {
+        return;
+      }
+      setInitialMessages(messages);
+      setReady(true);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [seed, builder]);
+
   const model = useMemo(
     () => new SerializationModel<Message.Message>(renderByline([]), initialMessages),
-    [initialMessages, reset],
+    [initialMessages],
   );
+
   const [running, setRunning] = useState(true);
-  // Use mutable type for local message building (not ECHO-managed).
   const [currentMessage, setCurrentMessage] = useState<Types.Mutable<Message.Message> | null>(null);
+
   useEffect(() => {
-    if (!running) {
+    if (!ready || !running) {
       return;
     }
 
@@ -97,83 +103,68 @@ const BasicStory = ({ messages: initialMessages = [], ...props }: DefaultStoryPr
       return;
     }
 
-    const i = setInterval(() => {
-      if (currentMessage?.blocks.length && currentMessage.blocks.length >= 3) {
+    const id = setInterval(() => {
+      if (currentMessage.blocks.length >= 3) {
         setCurrentMessage(null);
-        clearInterval(i);
+        clearInterval(id);
         return;
       }
-
-      (currentMessage.blocks as ContentBlock.Any[]).push(builder.createBlock());
+      Obj.update(currentMessage, (currentMessage) => {
+        (currentMessage.blocks as ContentBlock.Any[]).push(builder.createBlock());
+      });
       model.updateChunk(currentMessage);
     }, 3_000);
 
-    return () => clearInterval(i);
-  }, [model, currentMessage, running]);
-
-  const handleReset = () => {
-    setCurrentMessage(null);
-    setRunning(false);
-    setReset({});
-  };
-
-  return (
-    <TranscriptContainer
-      model={model}
-      running={running}
-      onRunningChange={setRunning}
-      onReset={handleReset}
-      {...props}
-    />
-  );
+    return () => clearInterval(id);
+  }, [ready, running, currentMessage, model, builder]);
+
+  return <Shell model={model} running={running} onRunningChange={setRunning} onReset={onReset} {...props} />;
 };
 
-/**
- * Queue story mutates queue with model adapter.
- */
-const QueueStory = ({
-  messages: initialMessages = [],
-  queueId,
-  onReset,
-  ...props
-}: DefaultStoryProps & { queueId: Key.ObjectId; onReset: () => void }) => {
+const FeedStory = ({ onReset, ...props }: InnerProps) => {
   const [running, setRunning] = useState(true);
   const [space] = useSpaces();
   const members = useMembers(space?.id).map((member) => member.identity);
-  const queue = useTestTranscriptionQueue(space, queueId, running, 2_000);
-  const model = useQueueModelAdapter(renderByline(members), queue, initialMessages);
-
-  return (
-    <TranscriptContainer model={model} running={running} onRunningChange={setRunning} onReset={onReset} {...props} />
+  const feed = useTestTranscriptionQueue(space, running, 2_000);
+  const messages = useQuery(
+    space?.db,
+    feed ? Query.select(Filter.type(Message.Message)).from(feed) : Query.select(Filter.nothing()),
   );
-};
-
-// TODO(burdon): Reconcile with QueueStory.
-const EntityExtractionQueueStory = () => {
-  const [running, setRunning] = useState(true);
-  const [space] = useSpaces();
-  const members = useMembers(space?.key).map((member) => member.identity);
-  const queue = useTestTranscriptionQueueWithEntityExtraction(space, undefined, running, 2_000);
-  const model = useQueueModelAdapter(renderByline(members), queue, []);
+  const model = useFeedModelAdapter(renderByline(members), messages, []);
 
-  return <TranscriptContainer model={model} running={running} onRunningChange={setRunning} />;
+  return <Shell model={model} running={running} onRunningChange={setRunning} onReset={onReset} {...props} />;
 };
 
-/**
- * Wrapper remounts on refresh to reload queue.
- */
-const QueueStoryWrapper = () => {
-  const [queueId] = useState(Key.ObjectId.random());
-  const [key, setKey] = useState(Key.ObjectId.random().toString());
-  const handleReset = () => {
-    setKey(Key.ObjectId.random().toString());
-  };
-
-  return <QueueStory key={key} queueId={queueId} onReset={handleReset} />;
+type ShellProps = TranscriptionProps & {
+  running: boolean;
+  onRunningChange: (running: boolean) => void;
+  onReset: () => void;
 };
 
+const Shell = ({ model, running, onRunningChange, onReset, ...props }: ShellProps) => (
+  <Panel.Root>
+    <Panel.Toolbar asChild>
+      <Toolbar.Root classNames='justify-end'>
+        <IconButton
+          icon={running ? 'ph--pause--regular' : 'ph--play--regular'}
+          label={running ? 'Pause' : 'Start'}
+          onClick={() => onRunningChange(!running)}
+        />
+        <IconButton icon='ph--x--regular' label='Reset' onClick={onReset} />
+      </Toolbar.Root>
+    </Panel.Toolbar>
+    <Panel.Content className='dx-document'>
+      <Transcription model={model} {...props} />
+    </Panel.Content>
+    <Panel.Statusbar className='flex items-center justify-center'>
+      <JsonHighlighter data={model.toJSON()} indent={0} classNames='text-sm' />
+    </Panel.Statusbar>
+  </Panel.Root>
+);
+
 const meta = {
   title: 'plugins/plugin-transcription/components/Transcription',
+  render: DefaultStory,
   decorators: [
     withLayout({ layout: 'fullscreen' }),
     withPluginManager({
@@ -181,13 +172,12 @@ const meta = {
         ...corePlugins(),
         StorybookPlugin({}),
         ClientPlugin({
-          types: [TestItem, TestSchema.DocumentType, Person.Person, Organization.Organization],
+          types: [TestItem, Person.Person, Organization.Organization, Feed.Feed, Message.Message],
           onClientInitialized: ({ client }) =>
             Effect.gen(function* () {
               yield* initializeIdentity(client);
             }),
         }),
-
         PreviewPlugin(),
       ],
     }),
@@ -196,52 +186,28 @@ const meta = {
     layout: 'fullscreen',
     translations,
   },
-} satisfies Meta;
+} satisfies Meta<typeof DefaultStory>;
 
 export default meta;
 
-const DefaultStory = (props: DefaultStoryProps) => {
-  const [messages, setMessages] = useState<Message.Message[]>([]);
-  useEffect(() => {
-    void Promise.all(Array.from({ length: 10 }, () => MessageBuilder.singleton.createMessage())).then(setMessages);
-  }, []);
-  if (messages.length === 0) {
-    return <div>Loading messages...</div>;
-  }
-  return <BasicStory {...props} messages={messages} />;
-};
+type Story = StoryObj<typeof meta>;
 
-export const Default: StoryObj<typeof DefaultStory> = {
-  render: DefaultStory,
+export const Default: Story = {
   args: {
-    ignoreAttention: true,
-    attendableId: 'story',
+    source: 'local',
+    seed: 10,
   },
 };
 
-export const Empty: StoryObj<typeof BasicStory> = {
-  render: BasicStory,
+export const Empty: Story = {
   args: {
-    ignoreAttention: true,
-    attendableId: 'story',
+    source: 'local',
+    seed: 0,
   },
 };
 
-export const WithQueue: StoryObj<typeof QueueStoryWrapper> = {
-  render: QueueStoryWrapper,
+export const WithQueue: Story = {
   args: {
-    ignoreAttention: true,
-    attendableId: 'story',
+    source: 'feed',
   },
 };
-
-// NOTE: We are running out of free quota on hugging face entity extraction.
-// TODO(mykola): Fix AI service in entity extraction function.
-// TODO(mykola): Fix hugging face quota issues.
-// export const WithEntityExtractionQueue: StoryObj<typeof EntityExtractionQueueStory> = {
-//   render: EntityExtractionQueueStory,
-//   args: {
-//     ignoreAttention: true,
-//     attendableId: 'story',
-//   },
-// };

package/src/components/Transcription/Transcription.tsx

@@ -8,16 +8,15 @@ import { useThemeContext } from '@dxos/react-ui';
 import { useTextEditor } from '@dxos/react-ui-editor';
 import { type Message, type Transcript } from '@dxos/types';
 import {
-  autoScroll,
   createBasicExtensions,
   createMarkdownExtensions,
   createThemeExtensions,
   decorateMarkdown,
   documentSlots,
   preview,
+  scroller,
 } from '@dxos/ui-editor';
 import { composable, composableProps } from '@dxos/ui-theme';
-import { isTruthy } from '@dxos/util';
 
 import { type SerializationModel } from '../../model';
 import { renderByline } from '../../util';
@@ -28,14 +27,9 @@ export { renderByline };
 export type TranscriptionProps = {
   transcript?: Transcript.Transcript;
   model: SerializationModel<Message.Message>;
-  // TODO(burdon): Are these still in use?
-  attendableId?: string;
-  ignoreAttention?: boolean;
 };
 
-/**
- * Transcript component implemented using the editor.
- */
+// TODO(burdon): Remove forwardedRef/use react-ui-editor.
 export const Transcription = composable<HTMLDivElement, TranscriptionProps>(
   ({ transcript: object, model, children, ...props }, forwardedRef) => {
     const { themeMode } = useThemeContext();
@@ -43,21 +37,21 @@ export const Transcription = composable<HTMLDivElement, TranscriptionProps>(
       return {
         extensions: [
           createBasicExtensions({ readOnly: true, lineWrapping: true, search: true }),
-          createMarkdownExtensions(),
           createThemeExtensions({ themeMode, slots: documentSlots }),
+          createMarkdownExtensions(),
           decorateMarkdown(),
           preview(),
           transcription({ model, started: object?.started ? new Date(object.started) : undefined }),
-          autoScroll(),
-        ].filter(isTruthy),
+          scroller(),
+        ],
       };
-    }, [model]);
+    }, [model, themeMode]);
 
     return (
       <div
         {...composableProps(props, { classNames: 'dx-container' })}
+        data-popover-collision-boundary={true}
         ref={parentRef}
-        data-popover-collision-boundary={true /* TODO(thure): Make this a constant and document it. */}
       />
     );
   },

package/src/components/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './Oracle';
 export * from './Transcription';

package/src/containers/TranscriptionArticle/TranscriptionArticle.stories.tsx

@@ -0,0 +1,61 @@
+//
+// 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 { Feed, Query, Ref } from '@dxos/echo';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { corePlugins } from '@dxos/plugin-testing';
+import { useQuery, useSpaces } from '@dxos/react-client/echo';
+import { Loading, withLayout } from '@dxos/react-ui/testing';
+import { Message, Transcript } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { TestItem } from '../../testing';
+import { TranscriptionPlugin } from '../../TranscriptionPlugin';
+import { TranscriptionArticle } from './TranscriptionArticle';
+
+const DefaultStory = () => {
+  const [space] = useSpaces();
+  const [transcript] = useQuery(space?.db, Query.type(Transcript.Transcript));
+  if (!space || !transcript) {
+    return <Loading />;
+  }
+
+  return <TranscriptionArticle role='article' attendableId='story' subject={transcript} />;
+};
+
+const meta = {
+  title: 'plugins/plugin-transcription/containers/TranscriptionArticle',
+  render: DefaultStory,
+  decorators: [
+    withLayout({ layout: 'column' }),
+    withPluginManager({
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Transcript.Transcript, Feed.Feed, Message.Message, TestItem],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              const { personalSpace } = yield* initializeIdentity(client);
+              const feed = personalSpace.db.add(Feed.make({ name: 'transcription' }));
+              personalSpace.db.add(Transcript.make(Ref.make(feed)));
+            }),
+        }),
+        TranscriptionPlugin(),
+      ],
+    }),
+  ],
+  parameters: { layout: 'fullscreen', translations },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};