@dxos/react-ui-markdown 0.9.1-staging.ee54ba693a → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-markdown",
-  "version": "0.9.1-staging.ee54ba693a",
+  "version": "0.11.0",
   "description": "Markdown components.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -15,7 +15,7 @@
     ".": {
       "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
-      "default": "./dist/lib/browser/index.mjs"
+      "import": "./dist/lib/index.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
@@ -24,10 +24,10 @@
     "src"
   ],
   "dependencies": {
-    "@codemirror/autocomplete": "^6.20.2",
-    "@codemirror/language": "^6.12.3",
-    "@codemirror/state": "^6.6.0",
-    "@codemirror/view": "^6.43.0",
+    "@codemirror/autocomplete": "^6.20.3",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.6",
     "@lezer/common": "^1.5.2",
     "@lezer/highlight": "^1.2.3",
     "@lezer/markdown": "^1.6.3",
@@ -39,18 +39,18 @@
     "react-markdown": "^10.1.0",
     "react-resize-detector": "^11.0.1",
     "remark-gfm": "^4.0.1",
-    "@dxos/async": "0.9.1-staging.ee54ba693a",
-    "@dxos/echo": "0.9.1-staging.ee54ba693a",
-    "@dxos/effect": "0.9.1-staging.ee54ba693a",
-    "@dxos/log": "0.9.1-staging.ee54ba693a",
-    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
-    "@dxos/react-ui-editor": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui": "0.9.1-staging.ee54ba693a",
-    "@dxos/react-ui-syntax-highlighter": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui-editor": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a",
-    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
-    "@dxos/util": "0.9.1-staging.ee54ba693a"
+    "@dxos/async": "0.11.0",
+    "@dxos/echo": "0.11.0",
+    "@dxos/effect": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/log": "0.11.0",
+    "@dxos/react-ui": "0.11.0",
+    "@dxos/react-ui-editor": "0.11.0",
+    "@dxos/react-ui-syntax-highlighter": "0.11.0",
+    "@dxos/ui": "0.11.0",
+    "@dxos/ui-editor": "0.11.0",
+    "@dxos/util": "0.11.0",
+    "@dxos/ui-theme": "0.11.0"
   },
   "devDependencies": {
     "@effect/vitest": "0.29.0",
@@ -58,23 +58,23 @@
     "@types/react-dom": "~19.2.3",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "vite": "^8.0.16",
-    "@dxos/keys": "0.9.1-staging.ee54ba693a",
-    "@dxos/echo": "0.9.1-staging.ee54ba693a",
-    "@dxos/lit-ui": "0.9.1-staging.ee54ba693a",
-    "@dxos/random": "0.9.1-staging.ee54ba693a",
-    "@dxos/react-client": "0.9.1-staging.ee54ba693a",
-    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
-    "@dxos/schema": "0.9.1-staging.ee54ba693a",
-    "@dxos/storybook-utils": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a"
+    "vite": "^8.1.4",
+    "@dxos/echo": "0.11.0",
+    "@dxos/keys": "0.11.0",
+    "@dxos/lit-ui": "0.11.0",
+    "@dxos/random": "0.11.0",
+    "@dxos/react-client": "0.11.0",
+    "@dxos/react-ui": "0.11.0",
+    "@dxos/schema": "0.11.0",
+    "@dxos/storybook-utils": "0.11.0",
+    "@dxos/ui-theme": "0.11.0"
   },
   "peerDependencies": {
     "effect": "3.21.4",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
-    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a"
+    "@dxos/react-ui": "^0.11.0",
+    "@dxos/ui-theme": "^0.11.0"
   },
   "publishConfig": {
     "access": "public"

package/src/MarkdownStream/MarkdownStream.tsx

@@ -3,7 +3,7 @@
 //
 
 import { EditorSelection, type Extension, Transaction } from '@codemirror/state';
-import { type EditorView } from '@codemirror/view';
+import { EditorView } from '@codemirror/view';
 import * as Effect from 'effect/Effect';
 import * as Fiber from 'effect/Fiber';
 import * as Queue from 'effect/Queue';
@@ -26,20 +26,21 @@ import { ErrorBoundary, type ThemedClassName, useDynamicRef, useStateWithRef, us
 import { type UseTextEditor, useTextEditor } from '@dxos/react-ui-editor';
 import {
   type AutoScrollProps,
+  PROMPT_ELEMENT,
+  ThemeExtensionsOptions,
   type XmlTagsOptions,
   type XmlWidgetState,
   type XmlWidgetStateManager,
-  crawlerLineEffect,
   createBasicExtensions,
   createThemeExtensions,
+  createTurnSource,
   decorateMarkdown,
   documentSlots,
   extendedMarkdown,
   fader,
   lineSpacing,
-  navigateNextEffect,
-  navigatePreviousEffect,
   scroller,
+  turnFolding,
   typewriter,
   typewriterBypass,
   xmlBlockDecoration,
@@ -47,24 +48,38 @@ import {
   xmlTagContextEffect,
   xmlTagResetEffect,
   xmlTags,
-  xmlTagUpdateEffect,
 } from '@dxos/ui-editor';
 import { mx } from '@dxos/ui-theme';
 import { isTruthy } from '@dxos/util';
 
+import { createMarkdownStreamController } from './create-controller';
 import { footer, setFooterVisibleEffect } from './footer';
 import { type StreamerOptions, createStreamer } from './stream';
+
+/** Document offset range (CodeMirror positions). */
+export type DocumentRange = { from: number; to: number };
+
 export interface MarkdownStreamController extends XmlWidgetStateManager {
   get length(): number | undefined;
   focus: () => void;
   scrollToBottom: (behavior?: ScrollBehavior) => void;
+  /** Scroll the given document position into view. */
+  scrollTo: (pos: number, options?: { y?: 'start' | 'center' | 'end' | 'nearest' }) => void;
+  /** The document range currently visible in the viewport, or `undefined` if not mounted. */
+  getVisibleRange: () => DocumentRange | undefined;
+  /** Subscribe to visible-range changes (fires immediately with the current range). Returns an unsubscribe fn. */
+  onVisibleRangeChange: (cb: (range: DocumentRange) => void) => () => void;
   navigateNext: () => void;
   navigatePrevious: () => void;
   setContext: (context: any) => void;
+  /** Re-applies the last context set. Idempotent; a no-op when none was set or the view is absent. */
+  flushContext: () => void;
   setContent: (text: string) => Promise<void>;
   append: (text: string) => Promise<void>;
 }
 
+/** Map the scroll container's top/bottom edges to document positions. */
+
 export type MarkdownStreamEvent = {
   type: 'submit';
   value: string | null;
@@ -113,6 +128,11 @@ export type MarkdownStreamProps = ThemedClassName<
      */
     extensions?: Extension;
 
+    /**
+     * Theme extensions.
+     */
+    slots?: ThemeExtensionsOptions['slots'];
+
     /** Event handler. */
     onEvent?: (event: MarkdownStreamEvent) => void;
   } & (XmlTagsOptions & AutoScrollProps)
@@ -122,7 +142,7 @@ export type MarkdownStreamProps = ThemedClassName<
  * Codemirror-based markdown editor with xml tag widtgets and streaming support.
  */
 export const MarkdownStream = forwardRef<MarkdownStreamController | null, MarkdownStreamProps>(
-  ({ classNames, debug, content, options, registry, extensions, footer, onEvent }, forwardedRef) => {
+  ({ classNames, debug, content, options, registry, extensions, footer, slots, onEvent }, forwardedRef) => {
     // Store current content so that we can toggle debug mode. Default to '' so the
     // `append()` path (which does `contentRef.current += text`) doesn't concatenate
     // against `undefined` and stamp `"undefined"` into the transcript snapshot.
@@ -131,8 +151,12 @@ export const MarkdownStream = forwardRef<MarkdownStreamController | null, Markdo
     // DOM node for the footer block widget — populated when its decoration mounts.
     const [footerRoot, setFooterRoot] = useState<HTMLElement | null>(null);
 
+    // Survives a context set before the view exists; flushed once it does (see `flushContext`).
+    const pendingContextRef = useRef<{ value: any } | undefined>(undefined);
+
     // Codemirror editor.
     const { parentRef, view, viewRef, widgets } = useMarkdownStreamTextEditor(contentRef, {
+      slots,
       debug,
       registry,
       options,
@@ -157,9 +181,11 @@ export const MarkdownStream = forwardRef<MarkdownStreamController | null, Markdo
           return;
         }
 
-        // Set content and scroll to bottom.
+        // Set content and scroll to bottom. Re-assert the host context rather than clearing it: it
+        // belongs to the host, not the document, so nulling it here would strand every widget in the
+        // replacement document with `context: undefined`.
         viewRef.current.dispatch({
-          effects: [xmlTagContextEffect.of(null), xmlTagResetEffect.of(null)],
+          effects: [xmlTagContextEffect.of(pendingContextRef.current?.value ?? null), xmlTagResetEffect.of(null)],
           changes: [{ from: 0, to: viewRef.current.state.doc.length, insert: text }],
           annotations: typewriterBypass.of(true),
           selection: EditorSelection.cursor(text.length),
@@ -168,16 +194,25 @@ export const MarkdownStream = forwardRef<MarkdownStreamController | null, Markdo
         // New queue.
         setQueue(Effect.runSync(Queue.unbounded<string>()));
       },
-      [contentRef, viewRef, setQueue],
+      [contentRef, viewRef, setQueue, pendingContextRef],
     );
 
     // Controller API.
     useImperativeHandle(
       forwardedRef,
-      () => createMarkdownStreamController({ contentRef, viewRef, queueRef, onReset }),
+      () => createMarkdownStreamController({ contentRef, viewRef, queueRef, onReset, pendingContextRef }),
       [onReset],
     );
 
+    // Apply a context that was set before the view existed — the dispatch in `setContext` is a no-op
+    // until then, and a host mounting the controller has no way to know.
+    useEffect(() => {
+      const pending = pendingContextRef.current;
+      if (view && pending) {
+        view.dispatch({ effects: xmlTagContextEffect.of(pending.value) });
+      }
+    }, [view]);
+
     // Widget events.
     useEffect(() => {
       if (!parentRef.current) {
@@ -226,9 +261,13 @@ export const MarkdownStream = forwardRef<MarkdownStreamController | null, Markdo
   },
 );
 
-type MarkdownStreamTextEditorParams = Pick<MarkdownStreamProps, 'debug' | 'registry' | 'options' | 'extensions'> & {
-  setFooterRoot?: (el: HTMLElement | null) => void;
-};
+// Fold each agent response beneath its `<prompt>` (the head element rendered by `xmlBlockDecoration`).
+const turnSource = createTurnSource(PROMPT_ELEMENT);
+
+type MarkdownStreamTextEditorParams = Pick<MarkdownStreamProps, 'debug' | 'registry' | 'options' | 'extensions'> &
+  Pick<ThemeExtensionsOptions, 'slots'> & {
+    setFooterRoot?: (el: HTMLElement | null) => void;
+  };
 
 type MarkdownStreamTextEditorResult = UseTextEditor & {
   viewRef: RefObject<EditorView | null>;
@@ -240,7 +279,14 @@ type MarkdownStreamTextEditorResult = UseTextEditor & {
  */
 const useMarkdownStreamTextEditor = (
   currentContent: RefObject<string | undefined>,
-  { debug, registry, options, extensions: extraExtensions, setFooterRoot }: MarkdownStreamTextEditorParams,
+  {
+    debug,
+    registry,
+    options,
+    extensions: extensionsProp,
+    slots = documentSlots,
+    setFooterRoot,
+  }: MarkdownStreamTextEditorParams,
 ): MarkdownStreamTextEditorResult => {
   const { themeMode } = useThemeContext();
 
@@ -254,40 +300,31 @@ const useMarkdownStreamTextEditor = (
       initialValue: content,
       selection: EditorSelection.cursor(content?.length ?? 0),
       extensions: [
-        createBasicExtensions({
-          lineWrapping: true,
-          readOnly: true,
-        }),
-        createThemeExtensions({
-          slots: documentSlots,
-          scrollbarThin: true,
-          syntaxHighlighting: true,
-          themeMode,
-        }),
+        createBasicExtensions({ lineWrapping: true, readOnly: true }),
+        createThemeExtensions({ slots, scrollbarThin: true, syntaxHighlighting: true, themeMode }),
         xmlFormatting({ skip: debug ? [] : ['prompt'] }),
         !debug &&
           [
             extendedMarkdown({ registry }),
             decorateMarkdown({
-              // `echo:`/`dxn:` links/images are handled by the `link-preview` entry in the
-              // registry via `xmlTags` `urlSchemes`. Skipping them here avoids `decorateMarkdown`
-              // adding a non-functional `LinkButton` anchor on top of the same node.
+              // xmlTags extension will handle `dxn:`/`echo:` links/images.
               skip: (node) =>
                 (node.name === 'Link' || node.name === 'Image') &&
                 (node.url.startsWith('dxn:') || node.url.startsWith('echo:')),
             }),
             // TODO(burdon): Make optional; Removes need for '\n\n'.
             lineSpacing(),
-            // NOTE: An ancestor element must set `data-hue` so `.dx-panel` resolves to the user's
-            // hue tokens (see `packages/ui/ui-theme/src/css/components/panel.css`). Tailwind picks
-            // up these utility classes from this source file.
             xmlBlockDecoration({
               tag: 'prompt',
-              lineClass: 'cm-prompt-line my-8',
-              contentClass: 'cm-prompt-bubble dx-panel px-2 py-1.5 box-decoration-clone rounded-sm [&_*]:text-inherit!',
+              lineClass:
+                'cm-prompt-line cm-prompt-bubble bg-group-surface text-base-fg border-l-[8px] pl-[8px]! pr-2 [&_*]:text-inherit!',
+              firstLineClass: 'pt-1.5 rounded-t-sm',
+              lastLineClass: 'pb-1.5 rounded-b-sm',
               hideTags: true,
             }),
             xmlTags({ registry, setWidgets, bookmarks: ['prompt'] }),
+            // TODO(burdon): Folding gets progressively off due to some widgets?
+            turnFolding({ source: turnSource }),
             scroller({ overScroll: 80, autoScroll: options?.autoScroll }),
             options?.typewriter &&
               typewriter({
@@ -301,7 +338,7 @@ const useMarkdownStreamTextEditor = (
             options?.fader && fader(),
             setFooterRoot && footer(setFooterRoot),
           ].filter(isTruthy),
-        extraExtensions,
+        extensionsProp,
       ].filter(isTruthy),
     };
   }, [
@@ -312,7 +349,8 @@ const useMarkdownStreamTextEditor = (
     options?.typewriter,
     options?.cursor,
     options?.fader,
-    extraExtensions,
+    slots,
+    extensionsProp,
   ]);
 
   const viewRef = useDynamicRef(view);
@@ -360,85 +398,3 @@ const useMarkdownStreamQueue = (
     };
   }, [view, queue, chunkSize, delayMs]);
 };
-
-type MarkdownStreamControllerDeps = {
-  contentRef: RefObject<string | undefined>;
-  viewRef: RefObject<EditorView | null>;
-  queueRef: RefObject<Queue.Queue<string>>;
-  onReset: (text: string) => Promise<void>;
-};
-
-/**
- * External controller API.
- */
-const createMarkdownStreamController = ({
-  contentRef,
-  viewRef,
-  queueRef,
-  onReset,
-}: MarkdownStreamControllerDeps): MarkdownStreamController => {
-  return {
-    get length() {
-      return viewRef.current?.state.doc.length;
-    },
-
-    /** Focus the editor. */
-    focus: () => {
-      viewRef.current?.focus();
-    },
-
-    /** Scroll to bottom. */
-    scrollToBottom: (behavior?: ScrollBehavior) => {
-      viewRef.current?.dispatch({
-        effects: crawlerLineEffect.of({ line: -1, behavior }),
-      });
-    },
-
-    /** Navigate previous prompt. */
-    navigatePrevious: () => {
-      viewRef.current?.dispatch({
-        effects: navigatePreviousEffect.of(),
-      });
-    },
-
-    /** Navigate next prompt. */
-    navigateNext: () => {
-      viewRef.current?.dispatch({
-        effects: navigateNextEffect.of(),
-      });
-    },
-
-    /** Set the context for widgets (XML tags). */
-    setContext: (context: any) => {
-      viewRef.current?.dispatch({
-        effects: xmlTagContextEffect.of(context),
-      });
-    },
-
-    /** Reset document. */
-    setContent: onReset,
-
-    /** Append to queue (and stream). */
-    append: async (text: string) => {
-      contentRef.current += text;
-      if (text.length) {
-        // Always go through the streaming queue, even when the doc starts empty. Skipping the
-        // queue in that case (via `onReset`) bypasses the `typewriter` extension's transaction filter
-        // and the first chunk lands in one CM dispatch — defeating the typewriter for any
-        // consumer (e.g. ChatThread) where the first delta is large because upstream batching
-        // collected several streaming partials before React rendered.
-        const queue = queueRef.current;
-        if (queue) {
-          await EffectEx.runAndForwardErrors(Queue.offer(queue, text));
-        }
-      }
-    },
-
-    /** Update widget state. */
-    updateWidget: (id: string, value: any) => {
-      viewRef.current?.dispatch({
-        effects: xmlTagUpdateEffect.of({ id, value }),
-      });
-    },
-  } satisfies MarkdownStreamController;
-};

package/src/MarkdownStream/controller.test.ts

@@ -0,0 +1,143 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @vitest-environment jsdom
+
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import * as Effect from 'effect/Effect';
+import * as Queue from 'effect/Queue';
+import { describe, test } from 'vitest';
+
+import {
+  type XmlWidgetDef,
+  decorationSetToArray,
+  extendedMarkdown,
+  xmlTagContextEffect,
+  xmlTags,
+} from '@dxos/ui-editor';
+
+import { createMarkdownStreamController } from './create-controller';
+
+/**
+ * The host↔editor seam: a host mounts the controller and publishes the context widgets call back
+ * through, but the controller's dispatches are no-ops until the editor view exists — and the host has no
+ * signal for when that is. These pin the contract that a context set at any point still reaches widgets.
+ */
+describe('MarkdownStreamController context', () => {
+  test('a context set before the view exists is applied once it does', ({ expect }) => {
+    const harness = createHarness();
+    const context = { rewind: () => {} };
+
+    // No view yet — this is what a host mounting the controller in an effect actually does.
+    harness.controller.setContext(context);
+    expect(harness.widgetContext()).toBeUndefined();
+
+    harness.attachView();
+    harness.controller.flushContext();
+    expect(harness.widgetContext()).toBe(context);
+  });
+
+  test('a context set after the view exists is applied immediately', ({ expect }) => {
+    const harness = createHarness();
+    harness.attachView();
+
+    const context = { rewind: () => {} };
+    harness.controller.setContext(context);
+    expect(harness.widgetContext()).toBe(context);
+  });
+
+  test('flushContext is a no-op when no context was set', ({ expect }) => {
+    const harness = createHarness();
+    harness.attachView();
+
+    harness.controller.flushContext();
+    expect(harness.widgetContext()).toBeUndefined();
+  });
+
+  // `setContent` resets the document and rebuilds decorations, which used to clear the context — the
+  // context belongs to the host, not the document, so it has to survive.
+  test('the context survives a document reset', async ({ expect }) => {
+    const harness = createHarness();
+    harness.attachView();
+
+    const context = { rewind: () => {} };
+    harness.controller.setContext(context);
+    await harness.controller.setContent('<branch id="b" />');
+
+    expect(harness.widgetContext('b')).toBe(context);
+  });
+
+  test('the latest context wins', ({ expect }) => {
+    const harness = createHarness();
+    harness.attachView();
+
+    const first = { rewind: () => {} };
+    const second = { rewind: () => {} };
+    harness.controller.setContext(first);
+    harness.controller.setContext(second);
+    expect(harness.widgetContext()).toBe(second);
+  });
+});
+
+const registry: Record<string, XmlWidgetDef> = {
+  branch: { block: true, Component: () => null },
+};
+
+/**
+ * Mirrors how `MarkdownStream` wires the controller: refs the host holds, a view created later, and
+ * `onReset` replacing the document while re-asserting the host context.
+ */
+const createHarness = () => {
+  const contentRef = { current: '<branch id="a" />' };
+  const viewRef: { current: EditorView | null } = { current: null };
+  const queueRef = { current: Effect.runSync(Queue.unbounded<string>()) };
+  const pendingContextRef: { current: { value: any } | undefined } = { current: undefined };
+
+  const controller = createMarkdownStreamController({
+    contentRef,
+    viewRef,
+    queueRef,
+    pendingContextRef,
+    onReset: async (text) => {
+      contentRef.current = text;
+      viewRef.current?.dispatch({
+        effects: [xmlTagContextEffect.of(pendingContextRef.current?.value ?? null)],
+        changes: [{ from: 0, to: viewRef.current.state.doc.length, insert: text }],
+      });
+    },
+  });
+
+  return {
+    controller,
+    attachView: () => {
+      viewRef.current = new EditorView({
+        state: EditorState.create({
+          doc: contentRef.current,
+          extensions: [extendedMarkdown({ registry }), xmlTags({ registry })],
+        }),
+        parent: document.createElement('div'),
+      });
+    },
+    /** The `context` prop the named widget's decoration was built with. */
+    widgetContext: (id = 'a') => {
+      const view = viewRef.current;
+      if (!view) {
+        return undefined;
+      }
+      for (const source of view.state.facet(EditorView.decorations)) {
+        const set = typeof source === 'function' ? source(view) : source;
+        if (!set) {
+          continue;
+        }
+        for (const { value } of decorationSetToArray(set)) {
+          const widget = value.spec?.widget;
+          if (widget?.id === id) {
+            return widget.props?.context;
+          }
+        }
+      }
+    },
+  };
+};