@dxos/ui-editor 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/extensions/pos.test.ts

@@ -0,0 +1,97 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { describe, test } from 'vitest';
+
+import { type Document, sourceHash } from '@dxos/nlp';
+
+import { clearAnalysis, pos, posAnalysisField, posDecorations, posSpans, setAnalysis, spanDiverged } from './pos';
+
+describe('posAnalysisField', () => {
+  const make = (doc = 'hello world') => EditorState.create({ doc, extensions: [posAnalysisField] });
+
+  test('setAnalysis adds a span', ({ expect }) => {
+    const state = make().update({ effects: setAnalysis.of({ from: 0, to: 5, document: docFor('hello') }) }).state;
+    expect(posSpans(state)).toHaveLength(1);
+    expect(posSpans(state)[0]).toMatchObject({ from: 0, to: 5, stale: false });
+  });
+
+  test('span offsets are mapped through an insertion before them', ({ expect }) => {
+    const withSpan = make().update({ effects: setAnalysis.of({ from: 6, to: 11, document: docFor('world') }) }).state;
+    const afterEdit = withSpan.update({ changes: { from: 0, insert: 'XXX' } }).state;
+    expect(posSpans(afterEdit)[0]).toMatchObject({ from: 9, to: 14 });
+  });
+
+  test('clearAnalysis removes all spans', ({ expect }) => {
+    const withSpan = make().update({ effects: setAnalysis.of({ from: 0, to: 5, document: docFor('hello') }) }).state;
+    const cleared = withSpan.update({ effects: clearAnalysis.of(null) }).state;
+    expect(posSpans(cleared)).toHaveLength(0);
+  });
+});
+
+describe('posDecorations', () => {
+  test('emits decorations for the analyzed tokens', ({ expect }) => {
+    const text = 'hello world';
+    let state = EditorState.create({ doc: text, extensions: [posAnalysisField, posDecorations] });
+    const document: Document = {
+      sourceHash: 'deadbeef',
+      sentences: [
+        {
+          index: 0,
+          start: 0,
+          end: 11,
+          tokens: [
+            { index: 0, text: 'hello', upos: 'INTJ', start: 0, end: 5 },
+            { index: 1, text: 'world', upos: 'NOUN', start: 6, end: 11 },
+          ],
+        },
+      ],
+    };
+    state = state.update({ effects: setAnalysis.of({ from: 0, to: 11, document }) }).state;
+    const sources = state.facet(EditorView.decorations);
+    expect(sources.length).toBeGreaterThan(0);
+  });
+});
+
+describe('pos reactive initial parse', () => {
+  test('parses existing content on mount (decorates without an edit)', async ({ expect }) => {
+    const text = 'hello world';
+    const fakeParse = async (input: string): Promise<Document> => docFor(input);
+    const view = new EditorView({ doc: text, extensions: [pos({ parse: fakeParse })] });
+    try {
+      // The mount parse and its dispatch run as microtasks (no timer); drain the queue rather than
+      // sleeping so the assertion is deterministic.
+      await flushMicrotasks();
+      expect(posSpans(view.state).length).toBe(1);
+      expect(posSpans(view.state)[0]).toMatchObject({ from: 0, to: text.length });
+    } finally {
+      view.destroy();
+    }
+  });
+});
+
+describe('spanDiverged', () => {
+  test('detects when live span text no longer matches the stored hash', ({ expect }) => {
+    const span = { from: 0, to: 5, sourceHash: sourceHash('hello'), document: docFor('hello'), stale: false };
+    expect(spanDiverged('hello world', span)).toBe(false);
+    expect(spanDiverged('hELLo world', span)).toBe(true);
+  });
+});
+
+/** A minimal single-token `Document` whose hash matches `text`. */
+const docFor = (text: string): Document => ({
+  sourceHash: sourceHash(text),
+  sentences: [
+    { index: 0, start: 0, end: text.length, tokens: [{ index: 0, text, upos: 'NOUN', start: 0, end: text.length }] },
+  ],
+});
+
+/** Drain the microtask queue so chained `.then` callbacks settle without a real timer. */
+const flushMicrotasks = async (ticks = 4): Promise<void> => {
+  for (let index = 0; index < ticks; index++) {
+    await Promise.resolve();
+  }
+};

package/src/extensions/pos.ts

@@ -0,0 +1,206 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorState, type Extension, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
+import { Decoration, EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
+
+import { debounce } from '@dxos/async';
+import { type Document, type Upos, sourceHash } from '@dxos/nlp';
+
+/** One analyzed region of the document. `document` offsets are relative to the span's own text. */
+export type PosSpan = {
+  from: number;
+  to: number;
+  /** Hash of the source text the analysis covers; compared to live text to detect divergence. */
+  sourceHash: string;
+  document: Document;
+  /** True once the underlying text diverged from `sourceHash` (decorations render dimmed). */
+  stale: boolean;
+};
+
+/** Replace/add the analysis for a region. */
+export const setAnalysis = StateEffect.define<{ from: number; to: number; document: Document }>();
+
+/** Remove all analysis spans. */
+export const clearAnalysis = StateEffect.define<null>();
+
+/** Internal: mark a span stale (dispatched by the reactive driver on divergence). */
+export const markStale = StateEffect.define<{ from: number; to: number }>();
+
+export const posAnalysisField = StateField.define<PosSpan[]>({
+  create: () => [],
+  update: (spans, tr) => {
+    let next = spans;
+
+    // Map existing span ranges through document changes so anchors follow edits.
+    if (tr.docChanged) {
+      next = next.map((span) => ({
+        ...span,
+        from: tr.changes.mapPos(span.from, 1),
+        to: tr.changes.mapPos(span.to, -1),
+      }));
+    }
+
+    for (const effect of tr.effects) {
+      if (effect.is(setAnalysis)) {
+        const { from, to, document } = effect.value;
+        // Replace any span at the same anchor; otherwise append.
+        const without = next.filter((span) => !(span.from === from && span.to === to));
+        next = [...without, { from, to, sourceHash: document.sourceHash, document, stale: false }];
+      } else if (effect.is(clearAnalysis)) {
+        next = [];
+      } else if (effect.is(markStale)) {
+        const { from, to } = effect.value;
+        next = next.map((span) => (span.from === from && span.to === to ? { ...span, stale: true } : span));
+      }
+    }
+
+    return next;
+  },
+});
+
+/** Read the current analysis spans from editor state. */
+export const posSpans = (state: EditorState): PosSpan[] => state.field(posAnalysisField);
+
+/** One mark per UPOS tag; CSS class drives color (see `posTheme`). Stale spans add `cm-pos-stale`. */
+const posMark = (upos: Upos, stale: boolean) =>
+  Decoration.mark({ class: ['cm-pos', `cm-pos-${upos}`, stale && 'cm-pos-stale'].filter(Boolean).join(' ') });
+
+export const posDecorations = EditorView.decorations.compute([posAnalysisField], (state) => {
+  const builder = new RangeSetBuilder<Decoration>();
+  const spans = state.field(posAnalysisField);
+  // Tokens are span-relative; absolute offset = span.from + token.start. Sort by absolute start so
+  // the RangeSetBuilder receives ranges in non-decreasing order.
+  const marks = spans
+    .flatMap((span) =>
+      span.document.sentences.flatMap((sentence) =>
+        sentence.tokens.map((token) => ({
+          from: span.from + token.start,
+          to: span.from + token.end,
+          deco: posMark(token.upos, span.stale),
+        })),
+      ),
+    )
+    .filter((mark) => mark.to <= state.doc.length && mark.from < mark.to)
+    .sort((markA, markB) => markA.from - markB.from || markA.to - markB.to);
+  for (const mark of marks) {
+    builder.add(mark.from, mark.to, mark.deco);
+  }
+  return builder.finish();
+});
+
+// UPOS → ui-theme hue. Content classes (NOUN/VERB/ADJ/ADV/PROPN/NUM) get distinct hues; function
+// words share a muted neutral; PUNCT/SYM/X are unstyled.
+const POS_HUE: Partial<Record<Upos, string>> = {
+  NOUN: 'blue',
+  PROPN: 'indigo',
+  VERB: 'red',
+  ADJ: 'green',
+  ADV: 'amber',
+  NUM: 'cyan',
+  INTJ: 'pink',
+  PRON: 'neutral',
+  DET: 'neutral',
+  ADP: 'neutral',
+  AUX: 'neutral',
+  CCONJ: 'neutral',
+  SCONJ: 'neutral',
+  PART: 'neutral',
+};
+
+export const posTheme = (): Extension =>
+  EditorView.theme({
+    '.cm-pos': { borderRadius: '0.125rem' },
+    ...Object.fromEntries(
+      Object.entries(POS_HUE).map(([upos, hue]) => [
+        `.cm-pos-${upos}`,
+        { borderBottom: `2px solid var(--color-${hue}-500)` },
+      ]),
+    ),
+    '.cm-pos-stale': { opacity: '0.4' },
+  });
+
+/** A span has diverged when the current text under its (mapped) range no longer matches its hash. */
+export const spanDiverged = (docText: string, span: { from: number; to: number; sourceHash: string }): boolean =>
+  sourceHash(docText.slice(span.from, span.to)) !== span.sourceHash;
+
+export type PosOptions = {
+  /** When set, the extension self-parses on idle and dispatches `setAnalysis`. */
+  parse?: (text: string) => Promise<Document>;
+  /** Idle debounce before reactive parsing (ms). */
+  debounceMs?: number;
+};
+
+/**
+ * Reactive driver: on doc change, mark edit-touched spans stale (immediate visual feedback), then
+ * after idle re-parse and dispatch fresh analysis. Re-hashing is bounded to spans overlapping the
+ * edit. This driver intentionally treats the whole document as a single span; per-span/sub-document
+ * analysis is left to external drivers dispatching `setAnalysis` (e.g. the transcription pipeline).
+ */
+const reactiveDriver = (parse: NonNullable<PosOptions['parse']>, debounceMs: number): Extension => {
+  // Monotonic id so a slow parse that resolves after a newer one (or after the doc moved on) is
+  // discarded rather than overwriting current analysis with stale spans. Parser rejections are
+  // swallowed so they don't surface as unhandled rejections and the prior analysis is preserved.
+  let latest = 0;
+  const applyParse = (view: EditorView) => {
+    const text = view.state.doc.toString();
+    const id = ++latest;
+    void parse(text)
+      .then((document) => {
+        if (id !== latest || view.state.doc.toString() !== text) {
+          return;
+        }
+        view.dispatch({ effects: setAnalysis.of({ from: 0, to: text.length, document }) });
+      })
+      .catch(() => {});
+  };
+
+  const run = debounce((view: EditorView) => applyParse(view), debounceMs);
+
+  // Parse existing content on mount so reactive mode decorates immediately, not just after an edit.
+  // Dispatch is deferred via the parse promise's microtask; CodeMirror forbids dispatching during construction.
+  const initial = ViewPlugin.define((view) => {
+    if (view.state.doc.length > 0) {
+      applyParse(view);
+    }
+    return {};
+  });
+
+  const onEdit = EditorView.updateListener.of((update: ViewUpdate) => {
+    if (!update.docChanged) {
+      return;
+    }
+    // Collect the post-edit ranges this transaction touched; re-hashing is bounded to spans that
+    // overlap them, so cost scales with the edit, not the total analyzed text.
+    const touched: Array<[number, number]> = [];
+    update.changes.iterChangedRanges((_fromA, _toA, fromB, toB) => touched.push([fromB, toB]));
+    const overlapsEdit = (span: PosSpan) => touched.some(([from, to]) => from <= span.to && to >= span.from);
+
+    // Immediate: mark any diverged touched span stale so its decorations dim until the re-parse lands.
+    const text = update.state.doc.toString();
+    const effects = update.state
+      .field(posAnalysisField)
+      .filter((span) => !span.stale && overlapsEdit(span) && spanDiverged(text, span))
+      .map((span) => markStale.of({ from: span.from, to: span.to }));
+    if (effects.length > 0) {
+      update.view.dispatch({ effects });
+    }
+    run(update.view);
+  });
+
+  return [initial, onEdit];
+};
+
+/**
+ * Part-of-speech decoration extension. Renders per-word UPOS marks from analysis state held in a
+ * span-oriented state field. State can be set externally via `setAnalysis`/`clearAnalysis`, or — when
+ * `options.parse` is supplied — self-driven on idle (reactive mode).
+ */
+export const pos = (options: PosOptions = {}): Extension => {
+  const extensions: Extension[] = [posAnalysisField, posDecorations, posTheme()];
+  if (options.parse) {
+    extensions.push(reactiveDriver(options.parse, options.debounceMs ?? 500));
+  }
+  return extensions;
+};

package/src/extensions/scrolling/auto-scroll.ts

@@ -5,7 +5,7 @@
 import { StateEffect } from '@codemirror/state';
 import { EditorView, ViewPlugin } from '@codemirror/view';
 
-import { addEventListener, combine, throttle } from '@dxos/async';
+import { addEventListener, combine, debounceAndThrottle, throttle } from '@dxos/async';
 import { Domino } from '@dxos/ui';
 import { getSize } from '@dxos/ui-theme';
 
@@ -176,7 +176,10 @@ export const autoScroll = ({ scrollOnResize = true }: AutoScrollProps = {}) => {
           // Re-pin check is throttled so the listener doesn't thrash while scrolling, but
           // unpinning must be immediate — otherwise content arriving during the throttle
           // window re-applies the crawl effect and yanks the viewport back to the bottom.
-          const onUserScroll = throttle(() => {
+          // `debounceAndThrottle` (not bare `throttle`) guarantees a trailing call after the
+          // gesture stops; a leading-only throttle drops the final at-bottom sample, leaving the
+          // scroll-to-bottom button visible even though the viewport settled at the bottom.
+          const onUserScroll = debounceAndThrottle(() => {
             requestAnimationFrame(() => {
               const { scrollTop, scrollHeight, clientHeight } = view.scrollDOM;
               const delta = scrollHeight - scrollTop - clientHeight;
@@ -208,13 +211,14 @@ export const autoScroll = ({ scrollOnResize = true }: AutoScrollProps = {}) => {
     ViewPlugin.fromClass(
       class {
         constructor(view: EditorView) {
-          const icon = Domino.of('dx-icon' as any)
-            .classNames(getSize(4))
-            .attributes({ icon: 'ph--arrow-down--regular' });
           const button = Domino.of('button')
-            .classNames('dx-button bg-accent-bg')
-            .attributes({ 'data-density': 'md' })
-            .append(icon)
+            .classNames('dx-button bg-accent-bg aspect-square')
+            .attributes({ 'data-density': 'sm' })
+            .append(
+              Domino.of('dx-icon' as any)
+                .classNames(getSize(4))
+                .attributes({ icon: 'ph--arrow-down--regular' }),
+            )
             .on('click', () => {
               setPinned(true);
               view.dispatch({

package/src/extensions/selection.test.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { EditorSelectionStateSchema } from './selection';
+
+describe('EditorSelectionStateSchema', () => {
+  test('encode/decode preserves the legacy serialized shape', ({ expect }) => {
+    const value = { scrollTo: 42, selection: { anchor: 3, head: 9 } };
+    const encoded = Schema.encodeSync(EditorSelectionStateSchema)(value);
+    expect(encoded).toEqual(value);
+    expect(Schema.decodeUnknownSync(EditorSelectionStateSchema)(JSON.parse(JSON.stringify(encoded)))).toEqual(value);
+  });
+
+  test('accepts an empty state', ({ expect }) => {
+    expect(Schema.decodeUnknownSync(EditorSelectionStateSchema)({})).toEqual({});
+  });
+
+  test('accepts selection without head', ({ expect }) => {
+    const value = { selection: { anchor: 5 } };
+    expect(Schema.decodeUnknownSync(EditorSelectionStateSchema)(value)).toEqual(value);
+  });
+});

package/src/extensions/selection.ts

@@ -4,9 +4,9 @@
 
 import { type Extension, Transaction, type TransactionSpec } from '@codemirror/state';
 import { EditorView, keymap } from '@codemirror/view';
+import * as Schema from 'effect/Schema';
 
 import { debounce } from '@dxos/async';
-import { invariant } from '@dxos/invariant';
 import { isTruthy } from '@dxos/util';
 
 import { singleValueFacet } from '../util';
@@ -26,6 +26,16 @@ export type EditorSelectionState = {
   selection?: EditorSelection;
 };
 
+export const EditorSelectionSchema = Schema.Struct({
+  anchor: Schema.Number,
+  head: Schema.optional(Schema.Number),
+}).pipe(Schema.mutable);
+
+export const EditorSelectionStateSchema = Schema.Struct({
+  scrollTo: Schema.optional(Schema.Number),
+  selection: Schema.optional(EditorSelectionSchema),
+}).pipe(Schema.mutable);
+
 export type EditorStateStore = {
   setState: (id: string, state: EditorSelectionState) => void;
   getState: (id: string) => EditorSelectionState | undefined;
@@ -42,19 +52,6 @@ export const createEditorStateTransaction = ({ scrollTo, selection }: EditorSele
   };
 };
 
-export const createEditorStateStore = (keyPrefix: string): EditorStateStore => ({
-  getState: (id) => {
-    invariant(id);
-    const state = localStorage.getItem(`${keyPrefix}/${id}`);
-    return state ? JSON.parse(state) : undefined;
-  },
-
-  setState: (id, state) => {
-    invariant(id);
-    localStorage.setItem(`${keyPrefix}/${id}`, JSON.stringify(state));
-  },
-});
-
 /**
  * Track scrolling and selection state to be restored when switching to document.
  */
@@ -89,7 +86,9 @@ export const selectionState = ({ getState, setState }: Partial<EditorStateStore>
           key: 'Ctrl-r', // TODO(burdon): Setting to jump back to selection.
           run: (view) => {
             const state = getState(view.state.facet(documentId));
-            if (state) {
+            // Only restore when something was actually stored; a store may return an empty state
+            // (no scroll/selection) for an unseen document, which would otherwise dispatch a no-op.
+            if (state && (state.scrollTo != null || state.selection)) {
               view.dispatch(createEditorStateTransaction(state));
             }
             return true;

package/src/extensions/tags/DESIGN.md

@@ -0,0 +1,58 @@
+# Widget Portal Mechanism
+
+React components are rendered into CodeMirror editor positions via a single unified mechanism:
+a `WidgetType.toDOM()` creates a DOM placeholder, and React portals render content into it.
+
+---
+
+## `xmlTags` / `StubWidget`
+
+**Source:** `packages/ui/ui-editor/src/extensions/tags/xml-tags.ts`
+
+**How it works:**
+
+1. A `XmlWidgetRegistry` maps tag names and URL scheme prefixes to `XmlWidgetDef` entries.
+2. `xmlTags({ registry, setWidgets })` is added to a CodeMirror extension list.
+3. On each document change, `buildDecorations` walks the syntax tree and handles two node types:
+   - **`Element` nodes** — matched by XML tag name (e.g. `<surface>`, `<toolCall>`).
+   - **`Link`/`Image` nodes** — matched when the URL starts with a declared `urlSchemes` prefix
+     (e.g. `dxn:`, `echo:`). Block widgets are created for `Image`; inline for `Link`.
+4. For each match, a `factory` returns a native `WidgetType`, or a `StubWidget` is created for
+   `Component`-backed entries.
+5. `StubWidget.toDOM()` creates a `<div class="min-h-[24px]">` and calls
+   `notifier.mounted({ id, root, props, Component })`.
+6. The `setWidgets` callback (owned by the React host) receives the updated widget list.
+7. The React host renders `createPortal(<Component {...props} />, root)` for each widget.
+8. `StubWidget.destroy()` calls `notifier.unmounted(id)`; the host removes the portal.
+
+**Extra capabilities:**
+
+- Widget state updated imperatively via `xmlTagUpdateEffect`.
+- Context propagated to all widgets via `xmlTagContextEffect`.
+- Full reset via `xmlTagResetEffect`.
+- Streaming tag support (unclosed opening tags while content streams in).
+- Keyboard navigation bookmarks (`navigatePreviousEffect` / `navigateNextEffect`).
+
+**Call sites:**
+
+| File                                                                                | Role                                                                                                   |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `packages/ui/ui-editor/src/extensions/tags/xml-tags.ts`                             | Definition                                                                                             |
+| `packages/ui/react-ui-markdown/src/MarkdownStream/MarkdownStream.tsx`               | Chat thread renderer — XML tags + dxn:/echo: url-scheme widgets                                        |
+| `packages/plugins/plugin-assistant/src/components/ChatThread/registry.tsx`          | Defines component registry (summary, surface, toolCall, toolResult, toolkit, json, inline factories)   |
+| `packages/plugins/plugin-markdown/src/hooks/useExtensions.tsx`                      | Editor — registers `dxn-preview` (block) and `link-preview` (inline) url-scheme widgets                |
+| `packages/plugins/plugin-inbox/src/components/MarkdownViewer/MarkdownViewer.tsx`    | Read-only viewer — inline anchor chips via url-scheme registry                                         |
+| `packages/ui/react-ui-transcription/src/components/Transcription/Transcription.tsx` | Transcription viewer — inline anchor chips via url-scheme registry                                     |
+| `packages/ui/react-ui-editor/src/stories/Widgets.stories.tsx`                       | Stories: `XmlTags` (XML tag registry) and `Preview` (url-scheme registry with `EditorPreviewProvider`) |
+| `packages/ui/ui-editor/src/extensions/tags/xml-util.test.ts`                        | Unit tests                                                                                             |
+| `packages/ui/react-ui-markdown/src/MarkdownStream/MarkdownStream.stories.tsx`       | Story defining dom-widget (factory) and react-widget (Component)                                       |
+
+---
+
+## Inline anchor chip
+
+`Link` nodes that match a url-scheme entry with `block: false` use a `factory` that returns an
+`AnchorInlineWidget` — a native `WidgetType` that renders a `<dx-anchor>` Lit web component.
+No React portal is involved. On click, `<dx-anchor>` dispatches a `DxAnchorActivate` custom event
+that either `EditorPreviewProvider` (standalone/stories) or `PreviewPlugin` (Composer) handles to
+open a popover.

package/src/extensions/tags/index.ts

@@ -3,8 +3,8 @@
 //
 
 export * from './extended-markdown';
-export * from './fader';
-export * from './typewriter';
+export * from './stub';
 export * from './xml-block-decoration';
 export * from './xml-formatting';
 export * from './xml-tags';
+export * from './widgets';

package/src/extensions/tags/stub.ts

@@ -0,0 +1,80 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EditorView, WidgetType } from '@codemirror/view';
+import { type FunctionComponent } from 'react';
+
+import { invariant } from '@dxos/invariant';
+import { Domino } from '@dxos/ui';
+
+import { type XmlWidgetProps, type XmlWidgetState } from './xml-tags';
+
+export interface XmlWidgetNotifier {
+  mounted(widget: XmlWidgetState): void;
+  unmounted(id: string): 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.
+ */
+export class StubWidget<TProps extends XmlWidgetProps> extends WidgetType {
+  #root: HTMLElement | null = null;
+  #view: EditorView | undefined;
+
+  constructor(
+    readonly id: string,
+    readonly Component: FunctionComponent<TProps>,
+    readonly props: TProps,
+    readonly notifier: XmlWidgetNotifier,
+    readonly streaming?: boolean,
+    readonly block?: boolean,
+  ) {
+    super();
+    invariant(id);
+  }
+
+  get root(): HTMLElement | null {
+    return this.#root;
+  }
+
+  override eq(other: this) {
+    if (this.streaming) {
+      return false;
+    }
+    return this.id === other.id;
+  }
+
+  override ignoreEvent() {
+    return true;
+  }
+
+  override toDOM(view: EditorView) {
+    this.#view = view;
+    this.#root = this.block ? Domino.of('div').classNames('min-h-[24px]').root : Domino.of('span').root;
+    const props = Object.assign({}, this.props, { view }) as TProps;
+    this.notifier.mounted({ id: this.id, root: this.#root, props, Component: this.Component });
+    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 });
+    return true;
+  }
+
+  override destroy(_dom: HTMLElement) {
+    this.notifier.unmounted(this.id);
+    this.#root = null;
+    this.#view = undefined;
+  }
+}

package/src/extensions/tags/widgets/anchor.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EditorView, WidgetType } from '@codemirror/view';
+
+/**
+ * Inline widget for echo/dxn links (e.g., `[Label](echo:/123)`).
+ * The <dx-anchor> tag is a web component that renders a link chip and popover.
+ */
+export class AnchorWidget extends WidgetType {
+  constructor(
+    readonly _label: string,
+    readonly _dxn: string,
+  ) {
+    super();
+  }
+
+  override eq(other: this) {
+    return this._dxn === other._dxn && this._label === other._label;
+  }
+
+  override toDOM(_view: EditorView) {
+    const root = document.createElement('dx-anchor');
+    root.classList.add('dx-tag--anchor');
+    root.textContent = this._label;
+    root.setAttribute('dxn', this._dxn);
+    return root;
+  }
+}

package/src/extensions/{preview → tags/widgets}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './preview';
+export * from './anchor';