@dxos/ui-editor 0.10.0 → 0.11.0

package/src/extensions/{tags → language/xml}/xml-tags.ts

@@ -2,7 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-import { syntaxTree } from '@codemirror/language';
+import { syntaxTree, syntaxTreeAvailable } from '@codemirror/language';
 import { type EditorState, type Extension, Prec, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
 import {
   Decoration,
@@ -17,9 +17,9 @@ import { type FunctionComponent } from 'react';
 
 import { log } from '@dxos/log';
 
-import { type Range } from '../../types';
-import { decorationSetToArray } from '../../util';
-import { crawlerLineEffect } from '../scrolling';
+import { type Range } from '../../../types';
+import { decorationSetToArray, escapeRegExpSource } from '../../../util';
+import { crawlerLineEffect } from '../../streaming/scrolling';
 import { StubWidget, type XmlWidgetNotifier } from './stub';
 import { nodeToJson } from './xml-util';
 
@@ -52,10 +52,10 @@ export type XmlEventHandler<TEvent = any> = (event: TEvent) => void;
  */
 export type XmlWidgetProps<TProps = any, TContext = any> = TProps & {
   _tag: string;
+  view?: EditorView;
   range: { from: number; to: number };
   children?: any[];
   context?: TContext;
-  view?: EditorView;
   onEvent?: XmlEventHandler;
 };
 
@@ -104,6 +104,13 @@ export type XmlWidgetDef = {
    * Block widgets are created for Image nodes; inline widgets for Link nodes.
    */
   urlSchemes?: string[];
+
+  /**
+   * Reserved block height (px) derived from the widget's props (e.g. parsed from the image label),
+   * used to size the placeholder and CodeMirror's viewport estimate before the React content mounts.
+   * Only meaningful for block widgets.
+   */
+  estimatedHeight?: (props: XmlWidgetProps) => number | undefined;
 };
 
 export type XmlWidgetRegistry = Record<string, XmlWidgetDef>;
@@ -117,9 +124,6 @@ export const getXmlTextChild = (children: any[]): string | null => {
 const xmlWidgetId = (explicit: unknown, fallback: string): string =>
   typeof explicit === 'string' && explicit.length > 0 ? explicit : fallback;
 
-/** Escapes a string for safe embedding in RegExp source (tag names from the registry). */
-const escapeRegExpSource = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
 /**
  * Update context.
  */
@@ -130,6 +134,12 @@ export const xmlTagContextEffect = StateEffect.define<any>();
  */
 export const xmlTagResetEffect = StateEffect.define();
 
+/**
+ * Force a full decoration rebuild without a document change — dispatched once background parsing of a
+ * long document completes, so blocks past the initial parse window are decorated without needing an edit.
+ */
+export const xmlTagRebuildEffect = StateEffect.define();
+
 /**
  * Update widget.
  */
@@ -153,6 +163,44 @@ export type XmlWidgetState = {
 
 export type { XmlWidgetNotifier };
 
+export type XmlTagsOptions = {
+  /** Tag registry. */
+  registry?: XmlWidgetRegistry;
+
+  /** Tags to bookmark for navigation. */
+  bookmarks?: string[];
+
+  /** Called when widgets are mounted or unmounted. */
+  setWidgets?: (widgets: XmlWidgetState[]) => void;
+};
+
+/**
+ * Implements custom XML tags via CodeMirror-native Widgets and portaled React/Solid components.
+ *
+ * Basic mechanism:
+ * - Decorations are created from XML tags that matched the provided Widget registry.
+ * - Native widgets are rendered inline.
+ * - React/Solid widgets are rendered in portals outside of the editor via the StubWidget.
+ * - Widget state can be update via effects.
+ *   - NOTE: Widget state may be updated BEFORE the widget is mounted.
+ */
+export const xmlTags = ({ registry, setWidgets, bookmarks }: XmlTagsOptions = {}): Extension => {
+  const debug = registry ? Object.values(registry).some((def) => def.debug) : false;
+  const notifier = createWidgetMap(setWidgets, debug);
+  const widgetDecorationsField = createWidgetDecorationsField(registry, notifier);
+
+  return [
+    widgetContextStateField,
+    widgetStateMapStateField,
+    widgetDecorationsField,
+    createWidgetUpdatePlugin(widgetDecorationsField, notifier),
+    createParseCompletionPlugin(),
+    createNavigationEffectPlugin(widgetDecorationsField, bookmarks),
+    bookmarks?.length ? Prec.highest(keyHandlers) : [],
+    debug ? createScrollJumpMonitor() : [],
+  ];
+};
+
 /**
  * Context state.
  */
@@ -175,76 +223,115 @@ const widgetContextStateField = StateField.define<any>({
 const widgetStateMapStateField = StateField.define<XmlWidgetStateMap>({
   create: () => ({}),
   update: (map, tr) => {
+    // Reduce over every effect: a transaction may carry several updates (or a reset followed by them),
+    // and returning on the first would silently drop the rest.
+    let next = map;
     for (const effect of tr.effects) {
       if (effect.is(xmlTagResetEffect)) {
-        return {};
-      }
-
-      if (effect.is(xmlTagUpdateEffect)) {
+        next = {};
+      } else if (effect.is(xmlTagUpdateEffect)) {
         // Update accumulated widget props by id.
         const { id, value } = effect.value;
         log('widget updated', { id, value });
-        const state = typeof value === 'function' ? value(map[id]) : value;
-        return { ...map, [id]: state };
+        next = { ...next, [id]: typeof value === 'function' ? value(next[id]) : value };
       }
     }
 
-    return map;
+    return next;
   },
 });
 
-export type XmlTagsOptions = {
-  /** Tag registry. */
-  registry?: XmlWidgetRegistry;
-
-  /** Tags to bookmark for navigation. */
-  bookmarks?: string[];
+/**
+ * Debug-only: flag large single-event scroll deltas (the "jump") so they can be correlated with the
+ * widget lifecycle trace. A smooth user scroll produces small per-event deltas; a jump-to-top is one
+ * big negative delta to near-zero.
+ */
+const createScrollJumpMonitor = () => {
+  let last = -1;
+  return EditorView.domEventHandlers({
+    scroll: (_event, view) => {
+      const top = view.scrollDOM.scrollTop;
+      if (last >= 0 && Math.abs(top - last) > 600) {
+        log.warn('xml-tags: scroll jump', {
+          from: Math.round(last),
+          to: Math.round(top),
+          delta: Math.round(top - last),
+        });
+      }
+      last = top;
+    },
+  });
+};
 
-  /** Called when widgets are mounted or unmounted. */
-  setWidgets?: (widgets: XmlWidgetState[]) => void;
+/**
+ * Re-decorate once the whole document has parsed. `StateField.create` (and incremental rebuilds) only
+ * see the syntax tree parsed so far, so a block past CodeMirror's initial background-parse window is
+ * not decorated until some later transaction — previously it appeared only after the first edit. This
+ * dispatches a one-shot rebuild when the full tree becomes available (re-armed on each edit).
+ */
+const createParseCompletionPlugin = () => {
+  let rebuiltForLength = -1;
+  return EditorView.updateListener.of((update) => {
+    if (update.docChanged) {
+      rebuiltForLength = -1;
+    }
+    const length = update.state.doc.length;
+    if (rebuiltForLength !== length && syntaxTreeAvailable(update.state, length)) {
+      rebuiltForLength = length;
+      // Defer: cannot dispatch during an update.
+      queueMicrotask(() => update.view.dispatch({ effects: xmlTagRebuildEffect.of(null) }));
+    }
+  });
 };
 
 /**
- * Implements custom XML tags via CodeMirror-native Widgets and portaled React/Solid components.
+ * Re-applies the accumulated widget state at mount time.
  *
- * Basic mechanism:
- * - Decorations are created from XML tags that matched the provided Widget registry.
- * - Native widgets are rendered inline.
- * - React/Solid widgets are rendered in portals outside of the editor via the StubWidget.
- * - Widget state can be update via effects.
- *   - NOTE: Widget state may be updated BEFORE the widget is mounted.
+ * A widget's props are baked when its decoration is built, but state can be dispatched before the
+ * widget mounts — rehydration after a document reset targets widgets that are still outside
+ * CodeMirror's viewport, and `xmlTagUpdateEffect` alone rebuilds no decorations. Such a widget would
+ * otherwise mount with the stale props it was built with, since `StubWidget.eq` (id equality) stops a
+ * later rebuild from replacing the instance.
  */
-export const xmlTags = ({ registry, setWidgets, bookmarks }: XmlTagsOptions = {}): Extension => {
-  const notifier = createWidgetMap(setWidgets);
-  const widgetDecorationsField = createWidgetDecorationsField(registry, notifier);
-
-  return [
-    widgetContextStateField,
-    widgetStateMapStateField,
-    widgetDecorationsField,
-    createWidgetUpdatePlugin(widgetDecorationsField, notifier),
-    createNavigationEffectPlugin(widgetDecorationsField, bookmarks),
-    bookmarks?.length ? Prec.highest(keyHandlers) : [],
-  ];
+const withCurrentWidgetState = (state: XmlWidgetState): XmlWidgetState => {
+  const view: EditorView | undefined = state.props?.view;
+  const widgetState = view?.state.field(widgetStateMapStateField, false)?.[state.id];
+  return widgetState ? { ...state, props: { ...state.props, ...widgetState } } : state;
 };
 
 /**
  * Manages the collection of widgets.
  */
-const createWidgetMap = (setWidgets?: (widgets: XmlWidgetState[]) => void): XmlWidgetNotifier => {
+const createWidgetMap = (setWidgets?: (widgets: XmlWidgetState[]) => void, debug = false): XmlWidgetNotifier => {
   const widgets = new Map<string, XmlWidgetState>();
 
   // TODO(burdon): Batch updates?
   const notifier = {
-    mounted: (state: XmlWidgetState) => {
-      log('widget mounted', { id: state.id, tag: state.props._tag });
+    mounted: (rawState: XmlWidgetState) => {
+      const state = withCurrentWidgetState(rawState);
+      const isNew = !widgets.has(state.id);
       widgets.set(state.id, state);
+      // Only a genuinely new id changes the portal set (blank-frame culprit); re-parents just re-notify.
+      if (debug && isNew) {
+        log.info('widget-map: mounted', { id: state.id, count: widgets.size });
+      }
+      setWidgets?.([...widgets.values()]);
+    },
+    updated: (id: string, widgetState: any) => {
+      const current = widgets.get(id);
+      if (!current || !widgetState) {
+        return;
+      }
+
+      widgets.set(id, { ...current, props: { ...current.props, ...widgetState } });
       setWidgets?.([...widgets.values()]);
     },
     unmounted: (id: string) => {
-      const state = widgets.get(id);
-      log('widget unmounted', { id, tag: state?.props._tag });
       widgets.delete(id);
+      // A cull drops the portal for a frame before it re-mounts — this is the blank-space window.
+      if (debug) {
+        log.info('widget-map: unmounted', { id, count: widgets.size });
+      }
       setWidgets?.([...widgets.values()]);
     },
     reconcile: (liveIds: Set<string>) => {
@@ -256,6 +343,9 @@ const createWidgetMap = (setWidgets?: (widgets: XmlWidgetState[]) => void): XmlW
         }
       }
       if (changed) {
+        if (debug) {
+          log.info('widget-map: reconcile pruned', { live: [...liveIds], count: widgets.size });
+        }
         setWidgets?.([...widgets.values()]);
       }
     },
@@ -382,22 +472,11 @@ const createWidgetUpdatePlugin = (
           notifier.reconcile(liveIds);
         }
 
-        // Check for widget update effects and re-render widgets.
+        // Re-render widgets whose state changed. Widgets not yet mounted pick their state up at mount
+        // time instead (see `withCurrentWidgetState`).
         for (const effect of update.transactions.flatMap((tr) => tr.effects)) {
           if (effect.is(xmlTagUpdateEffect)) {
-            const widgetState = widgetStateMap[effect.value.id];
-
-            // Find and render widget.
-            for (const range of decorationSetToArray(decorations)) {
-              const deco = range.value;
-              const widget = deco?.spec?.widget;
-
-              // NOTE: If the widget has not yet been mounted, then the root will be null.
-              if (widget && widget instanceof StubWidget && widget.id === effect.value.id && widget.root) {
-                const props = { ...widget.props, ...widgetState };
-                notifier.mounted({ id: widget.id, props, root: widget.root, Component: widget.Component });
-              }
-            }
+            notifier.updated(effect.value.id, widgetStateMap[effect.value.id]);
           }
         }
       }
@@ -435,6 +514,16 @@ const createWidgetDecorationsField = (registry: XmlWidgetRegistry = {}, notifier
           }
           return { from: 0, decorations: Decoration.none };
         }
+        // Full rebuild once background parsing has advanced (no document change).
+        if (effect.is(xmlTagRebuildEffect)) {
+          return buildDecorations(tr.state, { from: 0, to: tr.state.doc.length }, registry, notifier, urlSchemeMap);
+        }
+        // Widget props capture the context at build time and `StubWidget.eq` compares ids, so a context
+        // set after the first build would otherwise never reach a widget — leaving its callbacks bound to
+        // `undefined` for the life of the document.
+        if (effect.is(xmlTagContextEffect)) {
+          return buildDecorations(tr.state, { from: 0, to: tr.state.doc.length }, registry, notifier, urlSchemeMap);
+        }
       }
 
       if (tr.docChanged) {
@@ -499,6 +588,11 @@ const buildDecorations = (
   let last = range.from;
   let streamingFrom: number | undefined;
 
+  // Per-dxn occurrence counter for position-independent url-scheme widget ids. Keying on document
+  // position would change the id on every keystroke above the widget (full rebuild), remounting the
+  // portal and flashing the embed; occurrence order is stable because edits above force a full rebuild.
+  const dxnOccurrences = new Map<string, number>();
+
   tree.iterate({
     from: range.from,
     to: range.to,
@@ -532,11 +626,13 @@ const buildDecorations = (
                   ...widgetState,
                 } satisfies XmlWidgetProps;
 
-                // Create widget.
+                // Create widget. Known-height block widgets get their reserved height so StubWidget's
+                // fixed-height keep-alive applies to Component element tags too, not just url-scheme widgets.
+                const blockHeight = block ? def.estimatedHeight?.(props) : undefined;
                 const widget: WidgetType | undefined = factory
                   ? (factory(props) ?? undefined)
                   : Component
-                    ? new StubWidget(widgetId, Component, props, notifier, false, !!block)
+                    ? new StubWidget(widgetId, Component, props, notifier, false, !!block, blockHeight, def.debug)
                     : undefined;
 
                 // Add decoration.
@@ -589,7 +685,9 @@ const buildDecorations = (
           const [tag, def] = matched;
           const label = state.sliceDoc(markNodes[0].to, markNodes[1].from);
           const nodeRange = { from: node.node.from, to: node.node.to };
-          const widgetId = `cm-url-${node.from}-${dxn}`;
+          const occurrence = dxnOccurrences.get(dxn) ?? 0;
+          dxnOccurrences.set(dxn, occurrence + 1);
+          const widgetId = `cm-url-${dxn}-${occurrence}`;
           const widgetState = widgetStateMap[widgetId];
           const props: XmlWidgetProps = {
             id: widgetId,
@@ -602,10 +700,11 @@ const buildDecorations = (
             suggest: isBlock,
             ...widgetState,
           };
+          const blockHeight = isBlock ? def.estimatedHeight?.(props) : undefined;
           const widget: WidgetType | undefined = def.factory
             ? (def.factory(props) ?? undefined)
             : def.Component
-              ? new StubWidget(widgetId, def.Component, props, notifier, false, isBlock)
+              ? new StubWidget(widgetId, def.Component, props, notifier, false, isBlock, blockHeight, def.debug)
               : undefined;
           if (widget) {
             builder.add(
@@ -667,7 +766,7 @@ const buildDecorations = (
         const widget: WidgetType | undefined = def.factory
           ? (def.factory(mergedProps) ?? undefined)
           : def.Component
-            ? new StubWidget(widgetId, def.Component, mergedProps, notifier, true)
+            ? new StubWidget(widgetId, def.Component, mergedProps, notifier, true, undefined, undefined, def.debug)
             : undefined;
 
         if (widget) {

package/src/extensions/{tags → language/xml}/xml-util.test.ts

@@ -10,7 +10,7 @@ import { trim } from '@dxos/util';
 
 import { extendedMarkdown } from './extended-markdown';
 import TEXT from './testing/text.md?raw';
-import { xmlTags } from './xml-tags';
+import { type XmlWidgetRegistry, xmlTags } from './xml-tags';
 import { type Tag, nodeToJson } from './xml-util';
 
 type ParsedElement = Tag & {
@@ -22,7 +22,7 @@ type ParsedElement = Tag & {
  * Helper to extract all parsed XML elements from a document.
  * Checks completeness by verifying the Element node has a CloseTag child.
  */
-const parseElements = (doc: string, registry: Record<string, any> = {}): ParsedElement[] => {
+const parseElements = (doc: string, registry: XmlWidgetRegistry = {}): ParsedElement[] => {
   const state = EditorState.create({
     doc,
     extensions: [extendedMarkdown({ registry }), xmlTags({ registry })],

package/src/extensions/review/change-bar.ts

@@ -0,0 +1,94 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorState, type Extension, Facet, RangeSet } from '@codemirror/state';
+import { EditorView, GutterMarker, gutter } from '@codemirror/view';
+
+/**
+ * A change-bar gutter marker: a vertical bar tinted with the author's colour. Full line height by
+ * default; `rows` caps it to that many text rows (in `lh` units) — a BLOCK-insert proposal renders
+ * as a widget occupying the top rows of its host line, and the bar must cover the proposal's rows
+ * without tinting the host line's own text below it.
+ */
+export class ChangeBarMarker extends GutterMarker {
+  #colour: string;
+  #rows?: number;
+  #offsetRows?: number;
+
+  constructor(colour: string, rows?: number, offsetRows?: number) {
+    super();
+    this.#colour = colour;
+    this.#rows = rows;
+    this.#offsetRows = offsetRows;
+  }
+
+  override eq(other: ChangeBarMarker): boolean {
+    return other.#colour === this.#colour && other.#rows === this.#rows && other.#offsetRows === this.#offsetRows;
+  }
+
+  override toDOM(): HTMLElement {
+    const bar = document.createElement('div');
+    bar.className = 'cm-change-bar';
+    // Attribution colour is per-author (dynamic); the bar geometry lives in the theme class.
+    bar.style.background = this.#colour;
+    if (this.#rows !== undefined) {
+      bar.style.height = `calc(${this.#rows}lh)`;
+    }
+    // A proposal that STARTS with a newline renders its text below the break; shift the bar with it.
+    if (this.#offsetRows) {
+      bar.style.marginTop = `calc(${this.#offsetRows}lh)`;
+    }
+    return bar;
+  }
+}
+
+/**
+ * Per-line change-bar markers for one suggestion source, derived from editor state. Contributed by the
+ * suggestion extensions (`trackChanges`, `suggestions`) so each can colour its own lines by author.
+ */
+export type ChangeBarProvider = (state: EditorState) => RangeSet<GutterMarker>;
+
+const changeBarTheme = EditorView.baseTheme({
+  '& .cm-change-bar-gutter': {
+    width: '3px',
+    paddingInline: '1px',
+  },
+  '& .cm-change-bar': {
+    width: '3px',
+    height: '100%',
+    borderRadius: '1px',
+  },
+});
+
+/**
+ * Providers of per-line change bars. `enables` adds the single shared gutter (+ theme) once when any
+ * provider is present — identical extension instances dedupe — so own edits (`trackChanges`) and foreign
+ * suggestions (`suggestions`) share one bar column rather than stacking separate gutters. The gutter is
+ * built inside `enables` so its `markers` can read this same facet.
+ */
+const changeBarProviders = Facet.define<ChangeBarProvider>({
+  enables: (self) => [
+    gutter({
+      class: 'cm-change-bar-gutter',
+      // Merge every contributor's per-line markers into the shared gutter (sorted so co-located markers
+      // from different sources interleave rather than throw).
+      markers: (view) => {
+        const sets = view.state.facet(self).map((provider) => provider(view.state));
+        return sets.length ? RangeSet.join(sets) : RangeSet.empty;
+      },
+    }),
+    changeBarTheme,
+  ],
+});
+
+/** Contribute per-line change bars to the shared author-coloured gutter (see {@link ChangeBarMarker}). */
+export const changeBars = (provider: ChangeBarProvider): Extension => changeBarProviders.of(provider);
+
+/**
+ * Keeps the change-bar column mounted with no markers. Hosts that toggle review overlays install this
+ * once alongside their compartments, so entering/leaving Suggesting reconfigures marker providers
+ * inside an existing gutter instead of adding and removing the column — which shifted the text and
+ * flickered on every mode switch.
+ */
+export const changeBarGutter: Extension = changeBarProviders.of(() => RangeSet.empty);

package/src/extensions/review/comments.test.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorView } from '@codemirror/view';
+import { describe, test } from 'vitest';
+
+import { comments, createComment } from './comments';
+
+describe('createComment', () => {
+  test('collapses the selection to its start after creating a comment', ({ expect }) => {
+    const created: { cursor: string; from: number }[] = [];
+    const view = new EditorView({
+      doc: 'The quick brown fox jumps over the lazy dog.',
+      extensions: [comments({ id: 'test', onCreate: ({ cursor, from }) => created.push({ cursor, from }) })],
+    });
+
+    // Select "quick".
+    view.dispatch({ selection: { anchor: 4, head: 9 } });
+    const result = createComment(view);
+
+    expect(result).to.eq(true);
+    expect(created).to.have.length(1);
+    // The text selection is collapsed to the start of the commented range.
+    expect(view.state.selection.main.empty).to.eq(true);
+    expect(view.state.selection.main.head).to.eq(4);
+
+    view.destroy();
+  });
+
+  test('expands a bare cursor to the word under it', ({ expect }) => {
+    const created: { from: number }[] = [];
+    const view = new EditorView({
+      doc: 'The quick brown fox.',
+      extensions: [comments({ id: 'test', onCreate: ({ from }) => created.push({ from }) })],
+    });
+
+    // Cursor inside "quick", no range: the comment expands to the whole word.
+    view.dispatch({ selection: { anchor: 6 } });
+    expect(createComment(view)).to.eq(true);
+    expect(created).to.have.length(1);
+    expect(created[0].from).to.eq(4);
+
+    view.destroy();
+  });
+
+  test('is a no-op when there is no word or range under the caret', ({ expect }) => {
+    const view = new EditorView({
+      doc: '   ',
+      extensions: [comments({ id: 'test', onCreate: () => {} })],
+    });
+
+    view.dispatch({ selection: { anchor: 1 } });
+    expect(createComment(view)).to.eq(false);
+
+    view.destroy();
+  });
+
+  test('is prohibited when readonly (e.g. a suggestion branch)', ({ expect }) => {
+    const created: unknown[] = [];
+    const view = new EditorView({
+      doc: 'The quick brown fox.',
+      extensions: [comments({ id: 'test', readonly: true, onCreate: () => created.push(1) })],
+    });
+
+    view.dispatch({ selection: { anchor: 4, head: 9 } });
+    expect(createComment(view)).to.eq(false);
+    expect(created).to.have.length(0);
+
+    view.destroy();
+  });
+});