@dxos/ui-editor 0.10.0 → 0.11.1

package/src/extensions/language/xml/stub.ts

@@ -0,0 +1,233 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EditorView, WidgetType } from '@codemirror/view';
+import { type FunctionComponent } from 'react';
+
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+import { Domino } from '@dxos/ui';
+
+import { type XmlWidgetProps, type XmlWidgetState } from './xml-tags';
+
+export interface XmlWidgetNotifier {
+  mounted(widget: XmlWidgetState): void;
+  unmounted(id: string): void;
+  /**
+   * Re-render the mounted widget for `id` with updated props. Keyed by id rather than by widget
+   * instance: a rebuild constructs fresh widgets, but `StubWidget.eq` (id equality) makes CodeMirror
+   * keep the previously-rendered DOM, so the instance in the decoration set is not the one holding
+   * the mounted root.
+   */
+  updated(id: string, widgetState: any): void;
+  /**
+   * Drop any mounted widgets whose id is not in `liveIds`. Needed because CM reuses a widget's DOM
+   * via `updateDOM` (without calling `destroy`) when a decoration's widget changes in place, so an
+   * id that is no longer present — e.g. a position-keyed id after an edit shifted the node — would
+   * otherwise leak a stale portal.
+   */
+  reconcile(liveIds: Set<string>): void;
+}
+
+/**
+ * Mounts a DOM placeholder that React portals render into.
+ * Uses a block <div> for block widgets and an inline <span> for inline widgets.
+ *
+ * Culling a large block widget out of the viewport and re-showing it tears down and rebuilds the
+ * portal, causing a blank frame + flicker. `#keepAlive` (for known-height blocks) caches `#root` and
+ * keeps the portal mounted across culls so CM re-shows the same populated node; `toDOM` also gives the
+ * placeholder a fixed height so CM's measurement is authoritative and content-independent.
+ *
+ * NOTE: This does NOT address the separate scroll-*jump* on large/fast scroll deltas. That was verified
+ * (Playwright, both async and plain-sync block stories) to be widget-independent: CM's measure-phase
+ * scroll re-anchor correcting its content-height *estimate* when a big scroll delta reveals a lot of
+ * not-yet-measured content. Gradual scrolling does not jump. That is general CM heightmap behavior, not
+ * fixable here — see upstream CM #1727 (https://code.haverbeke.berlin/codemirror/dev/issues/1727).
+ */
+export class StubWidget<TProps extends XmlWidgetProps> extends WidgetType {
+  #root: HTMLElement | null = null;
+  #view: EditorView | undefined;
+  // Throttle the (hot) coordsAt trace to at most once per frame.
+  #coordsLoggedThisFrame = false;
+
+  constructor(
+    readonly id: string,
+    readonly Component: FunctionComponent<TProps>,
+    readonly props: TProps,
+    readonly notifier: XmlWidgetNotifier,
+    readonly streaming?: boolean,
+    readonly block?: boolean,
+    /**
+     * Reserved block height (px). Feeds CodeMirror's off-screen viewport estimate and pre-sizes the
+     * placeholder so the block occupies its final height before the portaled content resolves —
+     * otherwise it collapses to the 24px minimum, causing scroll jitter and a blank on scroll-back.
+     */
+    readonly blockHeight?: number,
+    /** When true, trace the widget's DOM lifecycle to diagnose scroll-cull jitter/jump (see PreviewScrollSurface). */
+    readonly debug?: boolean,
+  ) {
+    super();
+    invariant(id);
+  }
+
+  get root(): HTMLElement | null {
+    return this.#root;
+  }
+
+  /** Gated lifecycle trace. Enable per-tag via `XmlWidgetDef.debug` to watch the scroll-cull sequence. */
+  #trace(event: string, data?: Record<string, unknown>): void {
+    if (this.debug) {
+      log.info(`stub-widget: ${event}`, { id: this.id, block: this.block, ...data });
+    }
+  }
+
+  // CodeMirror reserves this height for the block while it is outside the rendered viewport.
+  override get estimatedHeight() {
+    return this.block && this.blockHeight != null ? this.blockHeight : -1;
+  }
+
+  // Report per-position screen coordinates inside the block so CM can anchor scroll correctly. Large
+  // block widgets need this alongside `estimatedHeight` (codemirror/dev#761); returning the same rect
+  // for every position confuses CM's geometry, so interpolate a vertical position across the widget's
+  // range (offset `pos` within `to - from`).
+  override coordsAt(dom: HTMLElement, pos: number, side: number) {
+    if (!this.block) {
+      return null;
+    }
+    const rect = dom.getBoundingClientRect();
+    const range = (this.props as XmlWidgetProps).range;
+    const length = range ? range.to - range.from : 0;
+    const fraction = length > 0 ? Math.min(1, Math.max(0, pos / length)) : side > 0 ? 1 : 0;
+    const y = rect.top + rect.height * fraction;
+    if (this.debug) {
+      const detached = rect.height === 0 || (rect.top === 0 && rect.bottom === 0);
+      // A detached / re-parented node reports a zero rect; feeding that to CM's scroll anchor snaps the
+      // viewport to the document top. Flag it so the jump-to-top is attributable in the trace.
+      if (detached) {
+        log.warn('stub-widget: coordsAt on detached node (zero rect)', {
+          id: this.id,
+          pos,
+          side,
+          connected: dom.isConnected,
+          rect: { top: rect.top, height: rect.height },
+          y,
+        });
+      } else if (!this.#coordsLoggedThisFrame) {
+        // CM consults coordsAt to anchor the scroll; log one sample per frame to correlate with jumps.
+        this.#coordsLoggedThisFrame = true;
+        requestAnimationFrame(() => {
+          this.#coordsLoggedThisFrame = false;
+        });
+        log.info('stub-widget: coordsAt', {
+          id: this.id,
+          pos,
+          side,
+          rect: { top: Math.round(rect.top), height: Math.round(rect.height) },
+          y: Math.round(y),
+          scrollTop: Math.round(this.#view?.scrollDOM.scrollTop ?? -1),
+        });
+      }
+    }
+    return { left: rect.left, right: rect.right, top: y, bottom: y };
+  }
+
+  override eq(other: this) {
+    if (this.streaming) {
+      return false;
+    }
+    // Context too, not just the id: props are captured at build time, so an id-only comparison makes
+    // CodeMirror keep the existing widget (and its stale props) when the host publishes the context
+    // after the first build — leaving every widget callback bound to `undefined`.
+    const context = (props: TProps) => (props as XmlWidgetProps).context;
+    return this.id === other.id && context(this.props) === context(other.props);
+  }
+
+  override ignoreEvent() {
+    return true;
+  }
+
+  /**
+   * Keep the root DOM (and its portal) alive across CM viewport culls, for block widgets whose height
+   * we know up front. A cull calls `destroy()` then `toDOM()` on the SAME widget instance; reusing the
+   * cached, already-rendered node instead of rebuilding it keeps the block's measured geometry stable
+   * across the cull boundary, which sidesteps CM's measure-phase scroll re-anchor (upstream #1727) and
+   * the blank/flicker from the portal remounting. Genuine removals (the tag edited out) are pruned by
+   * `notifier.reconcile` on the next document change, not by cull. Scoped to known-height blocks so
+   * ordinary widgets keep CM's normal virtualization (no unbounded retained portals).
+   */
+  get #keepAlive(): boolean {
+    return !!this.block && this.blockHeight != null;
+  }
+
+  override toDOM(view: EditorView) {
+    this.#view = view;
+    const cached = this.#keepAlive && this.#root != null;
+    if (!this.#root) {
+      this.#root = this.block ? Domino.of('div').classNames('min-h-[24px]').root : Domino.of('span').root;
+      if (this.block && this.blockHeight != null) {
+        // Fixed (not min) height: give CM an authoritative, content-independent measurement so an async
+        // widget that mounts / re-lays-out later cannot perturb the heightmap (we know the height up
+        // front). `overflow: hidden` keeps content that briefly overshoots from changing the measured box.
+        this.#root.style.height = `${this.blockHeight}px`;
+        this.#root.style.overflow = 'hidden';
+      }
+    }
+    const props = Object.assign({}, this.props, { view }) as TProps;
+    this.notifier.mounted({ id: this.id, root: this.#root, props, Component: this.Component });
+    this.#trace(cached ? 'toDOM (reuse cached root)' : 'toDOM (create)', {
+      blockHeight: this.blockHeight,
+      scrollTop: Math.round(view.scrollDOM.scrollTop),
+    });
+    this.#measureAfterPaint('toDOM');
+    return this.#root;
+  }
+
+  override updateDOM(dom: HTMLElement) {
+    this.#root = dom;
+    const props = Object.assign({}, this.props, { view: this.#view }) as TProps;
+    this.notifier.mounted({ id: this.id, root: this.#root, props, Component: this.Component });
+    this.#trace('updateDOM (reuse/re-parent)', { connected: dom.isConnected });
+    this.#measureAfterPaint('updateDOM');
+    return true;
+  }
+
+  override destroy(_dom: HTMLElement) {
+    if (this.#keepAlive) {
+      // Cull, not removal: keep #root and the portal mounted so the next toDOM re-shows the identical,
+      // already-rendered node. `notifier.reconcile` drops it if the tag is genuinely removed.
+      this.#trace('destroy (cull, keep-alive)', { scrollTop: Math.round(this.#view?.scrollDOM.scrollTop ?? -1) });
+      return;
+    }
+    this.#trace('destroy (cull)', { scrollTop: Math.round(this.#view?.scrollDOM.scrollTop ?? -1) });
+    this.notifier.unmounted(this.id);
+    this.#root = null;
+    this.#view = undefined;
+  }
+
+  /**
+   * After the next paint, compare the measured block height against the reserved `estimatedHeight`.
+   * A large discrepancy is what shifts CM's total-height model and drives the scroll jump; logging it
+   * pinpoints when (and by how much) the portaled content diverges from the reserved space.
+   */
+  #measureAfterPaint(source: string): void {
+    if (!this.debug || !this.block) {
+      return;
+    }
+    const root = this.#root;
+    requestAnimationFrame(() => {
+      if (!root) {
+        return;
+      }
+      const measured = root.getBoundingClientRect().height;
+      const reserved = this.blockHeight ?? -1;
+      log.info(`stub-widget: measured after ${source}`, {
+        id: this.id,
+        reserved,
+        measured,
+        delta: reserved > 0 ? measured - reserved : undefined,
+        connected: root.isConnected,
+      });
+    });
+  }
+}

package/src/extensions/language/xml/xml-block-decoration.ts

@@ -0,0 +1,165 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Extension, type Range } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
+
+import { escapeRegExpSource } from '../../../util';
+
+export type XmlBlockDecorationOptions = {
+  /**
+   * Tag name to match (e.g. `'prompt'`).
+   */
+  tag: string;
+
+  /**
+   * Class added via `Decoration.line` to each line that intersects the element's content
+   * range. Use to style the bubble container (e.g. flex alignment, vertical margin).
+   */
+  lineClass?: string;
+
+  /**
+   * Additional class added only to the first line of the content range. Use to round the top
+   * of a block bubble and pad its top edge (single line receives both first and last classes).
+   */
+  firstLineClass?: string;
+
+  /**
+   * Additional class added only to the last line of the content range. Use to round the
+   * bottom of a block bubble and pad its bottom edge.
+   */
+  lastLineClass?: string;
+
+  /**
+   * Class added via `Decoration.mark` covering the inner content (between the open and
+   * close tags). Use to style the bubble surface (background, padding, rounding).
+   */
+  contentClass?: string;
+
+  /**
+   * When true, the open and close tag delimiters are hidden via `Decoration.replace`
+   * with no widget, so the rendered text is the inner content only.
+   */
+  hideTags?: boolean;
+};
+
+/**
+ * Scans the doc for `<tag>…</tag>` blocks and decorates them without replacing them with a
+ * widget — the source text remains in the document and can still be matched by other extensions
+ * (e.g. `xmlFormatting`). Use this for "bubble"-style styling of XML blocks (chat prompts,
+ * callouts, etc.) where the inner content should stay editable/copyable rather than living inside
+ * a CodeMirror widget.
+ *
+ * Matching is done by direct text scan rather than a full-document XML parse: the transcript is
+ * mostly markdown, and a single stray `<` anywhere upstream (code, `a < b`, an unclosed streaming
+ * widget tag) corrupts a whole-document XML parse — which previously caused a well-formed prompt's
+ * `</tag>` to go unrecognised, extending the bubble over the rest of the conversation. An
+ * unterminated open tag (no matching `</tag>`, e.g. mid-stream) is left undecorated rather than
+ * painting to the end of the document.
+ */
+// TODO(burdon): Change to array to support multiple tags.
+export const xmlBlockDecoration = ({
+  tag,
+  lineClass,
+  firstLineClass,
+  lastLineClass,
+  contentClass,
+  hideTags,
+}: XmlBlockDecorationOptions): Extension => {
+  const contentDecoration = contentClass ? Decoration.mark({ class: contentClass }) : undefined;
+  const hideDecoration = hideTags ? Decoration.replace({}) : undefined;
+
+  // Match an opening `<tag>` or `<tag …attrs>` (not self-closing); the paired `</tag>` is located
+  // by scanning forward so unrelated markup between blocks cannot break matching. `tag` is escaped
+  // so a name containing regex metacharacters (e.g. `foo.bar`) matches literally.
+  const escapedTag = escapeRegExpSource(tag);
+  const openTagRegExp = new RegExp(`<${escapedTag}(?:\\s[^>]*)?>`, 'g');
+  const closeTagStr = `</${tag}>`;
+
+  const buildDecorations = (view: EditorView): DecorationSet => {
+    const docLength = view.state.doc.length;
+    const text = view.state.sliceDoc(0, docLength);
+    if (!text.includes(`<${tag}`)) {
+      return Decoration.none;
+    }
+
+    const ranges: Range<Decoration>[] = [];
+    openTagRegExp.lastIndex = 0;
+    let match: RegExpExecArray | null;
+    while ((match = openTagRegExp.exec(text))) {
+      const openFrom = match.index;
+      const openTo = openFrom + match[0].length;
+      const closeFrom = text.indexOf(closeTagStr, openTo);
+      // Skip unterminated blocks: extending decoration to the document end would paint the bubble
+      // over everything that follows (e.g. the assistant response streaming in after the prompt).
+      if (closeFrom === -1) {
+        break;
+      }
+      const closeTo = closeFrom + closeTagStr.length;
+      const contentFrom = openTo;
+      const contentTo = closeFrom;
+
+      if (hideDecoration) {
+        ranges.push(hideDecoration.range(openFrom, openTo));
+        ranges.push(hideDecoration.range(closeFrom, closeTo));
+      }
+
+      if (contentDecoration && contentFrom < contentTo) {
+        ranges.push(contentDecoration.range(contentFrom, contentTo));
+      }
+
+      if (lineClass || firstLineClass || lastLineClass) {
+        // Collect every line that intersects the content range so that the first and last
+        // can be styled distinctly (e.g. rounding the top/bottom of a single block bubble).
+        const lines = [];
+        let pos = contentFrom;
+        while (pos < contentTo && pos <= docLength) {
+          const line = view.state.doc.lineAt(pos);
+          // Only lines that intersect visible content: a hidden close tag on its own line would
+          // otherwise get an empty rounded bubble line after the tag is replaced.
+          if (line.to > contentFrom && line.from < contentTo) {
+            lines.push(line);
+          }
+          if (line.to >= contentTo) {
+            break;
+          }
+          pos = line.to + 1;
+        }
+
+        lines.forEach((line, index) => {
+          const cls = [lineClass, index === 0 && firstLineClass, index === lines.length - 1 && lastLineClass]
+            .filter(Boolean)
+            .join(' ');
+          if (cls) {
+            ranges.push(Decoration.line({ class: cls }).range(line.from));
+          }
+        });
+      }
+
+      // Resume scanning past the close tag so content is never re-matched.
+      openTagRegExp.lastIndex = closeTo;
+    }
+
+    return Decoration.set(ranges, true);
+  };
+
+  return ViewPlugin.fromClass(
+    class {
+      decorations: DecorationSet;
+
+      constructor(view: EditorView) {
+        this.decorations = buildDecorations(view);
+      }
+
+      update(update: ViewUpdate) {
+        if (update.docChanged) {
+          this.decorations = buildDecorations(update.view);
+        }
+      }
+    },
+    {
+      decorations: (instance) => instance.decorations,
+    },
+  );
+};

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

@@ -6,15 +6,6 @@ import { xmlLanguage } from '@codemirror/lang-xml';
 import { type Extension, type Range } from '@codemirror/state';
 import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
 
-/**
- * Lezer XML node names that represent the angle-bracket delimited portions of an element.
- */
-const XML_TAG_NODES = new Set(['OpenTag', 'CloseTag', 'SelfClosingTag', 'MismatchedCloseTag']);
-
-const xmlElementMark = Decoration.mark({ class: 'cm-xml-element' });
-const xmlTagMark = Decoration.mark({ class: 'cm-xml-tag' });
-const xmlContentMark = Decoration.mark({ class: 'cm-xml-content' });
-
 export type XmlFormattingOptions = {
   /**
    * Tag names whose elements should NOT receive xmlFormatting decorations. Use to
@@ -47,6 +38,17 @@ export const xmlFormatting = ({ skip }: XmlFormattingOptions = {}): Extension =>
     }
 
     const tagNameAt = (node: { from: number; to: number }) => text.slice(node.from, node.to);
+    // A tag is only decorated when its `TagName` child parses as a real name. This gates out the
+    // malformed elements Lezer synthesises from a stray `<` in prose, which would otherwise span
+    // to the next `>` and paint the intervening text with `cm-xml-element`/`cm-xml-tag`.
+    const tagNameOf = (tagNode: { getChild: (name: string) => { from: number; to: number } | null }) => {
+      const tagNameNode = tagNode.getChild('TagName');
+      if (!tagNameNode) {
+        return undefined;
+      }
+      const value = tagNameAt(tagNameNode);
+      return VALID_TAG_NAME.test(value) ? value : undefined;
+    };
 
     const tree = xmlLanguage.parser.parse(text);
     const ranges: Range<Decoration>[] = [];
@@ -54,33 +56,36 @@ export const xmlFormatting = ({ skip }: XmlFormattingOptions = {}): Extension =>
       enter: (node) => {
         const name = node.type.name;
         if (name === 'SelfClosingTag' && node.from < node.to) {
-          if (skipSet) {
-            const tagNameNode = node.node.getChild('TagName');
-            if (tagNameNode && skipSet.has(tagNameAt(tagNameNode))) {
-              return false;
-            }
+          const tagName = tagNameOf(node.node);
+          if (!tagName) {
+            return;
+          }
+          if (skipSet?.has(tagName)) {
+            return false;
           }
           // Self-closing tag is its own outer block and tag delimiter.
           ranges.push(xmlElementMark.range(node.from, node.to));
           ranges.push(xmlTagMark.range(node.from, node.to));
           return;
         }
-        if (XML_TAG_NODES.has(name) && node.from < node.to) {
-          ranges.push(xmlTagMark.range(node.from, node.to));
-          return;
-        }
         if (name === 'Element' && node.from < node.to) {
           const openTag = node.node.getChild('OpenTag');
-          if (openTag && skipSet) {
-            const tagNameNode = openTag.getChild('TagName');
-            if (tagNameNode && skipSet.has(tagNameAt(tagNameNode))) {
-              // Skip this element AND its descendants — another extension owns rendering.
-              return false;
-            }
+          // Require a real matching `CloseTag` (not `MismatchedCloseTag`) with a valid name: an
+          // unterminated or malformed element is left undecorated. Keep descending so any
+          // well-formed nested elements still get styled.
+          const closeTag = node.node.getChild('CloseTag');
+          const tagName = openTag ? tagNameOf(openTag) : undefined;
+          if (!openTag || !closeTag || !tagName) {
+            return;
+          }
+          if (skipSet?.has(tagName)) {
+            // Skip this element AND its descendants — another extension owns rendering.
+            return false;
           }
-          const closeTag = node.node.getChild('CloseTag') ?? node.node.getChild('MismatchedCloseTag');
           ranges.push(xmlElementMark.range(node.from, node.to));
-          if (openTag && closeTag && openTag.to < closeTag.from) {
+          ranges.push(xmlTagMark.range(openTag.from, openTag.to));
+          ranges.push(xmlTagMark.range(closeTag.from, closeTag.to));
+          if (openTag.to < closeTag.from) {
             ranges.push(xmlContentMark.range(openTag.to, closeTag.from));
           }
         }
@@ -109,17 +114,28 @@ export const xmlFormatting = ({ skip }: XmlFormattingOptions = {}): Extension =>
       },
     ),
 
-    EditorView.baseTheme({
-      '.cm-xml-element': {
-        backgroundColor: 'var(--color-current-surface)',
-        borderRadius: '0.25rem',
-        padding: '0.25rem',
-      },
-      '.cm-xml-tag': {
-        color: 'var(--color-blue-500)',
-        fontFamily: 'var(--font-mono)',
-      },
-      '.cm-xml-content': {},
-    }),
+    styles,
   ];
 };
+
+/**
+ * Well-formed XML tag name (a stray `<` in prose — e.g. `a < b` — has none, so it stays undecorated).
+ */
+const VALID_TAG_NAME = /^[A-Za-z_][\w.-]*$/;
+
+const xmlElementMark = Decoration.mark({ class: 'cm-xml-element' });
+const xmlTagMark = Decoration.mark({ class: 'cm-xml-tag' });
+const xmlContentMark = Decoration.mark({ class: 'cm-xml-content' });
+
+const styles = EditorView.baseTheme({
+  '.cm-xml-element': {
+    backgroundColor: 'var(--color-current-surface)',
+    borderRadius: '0.25rem',
+    padding: '0.25rem',
+  },
+  '.cm-xml-tag': {
+    color: 'var(--color-blue-500)',
+    fontFamily: 'var(--font-mono)',
+  },
+  '.cm-xml-content': {},
+});