@dxos/ui-editor 0.10.0 → 0.11.1

package/src/extensions/completion/typeahead.ts

@@ -0,0 +1,97 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { EditorSelection, type Extension, Prec, RangeSetBuilder } from '@codemirror/state';
+import {
+  type Command,
+  Decoration,
+  type DecorationSet,
+  type EditorView,
+  ViewPlugin,
+  type ViewUpdate,
+  keymap,
+} from '@codemirror/view';
+
+import { type CompletionContext } from './match';
+import { PlaceholderWidget } from './placeholder';
+
+// TODO(burdon): Option to complete only at end of line.
+export type TypeaheadOptions = {
+  onComplete?: (context: CompletionContext) => string | undefined;
+};
+
+/**
+ * Shows a completion placeholder.
+ */
+export const typeahead = ({ onComplete }: TypeaheadOptions = {}): Extension => {
+  // Kept per-view (not in the factory closure) so a single extension instance shared across
+  // multiple editors does not leak completion state between them.
+  const typeaheadPlugin = ViewPlugin.fromClass(
+    class {
+      decorations: DecorationSet = Decoration.none;
+      hint: string | undefined;
+      update(update: ViewUpdate) {
+        // Only recompute on doc/selection changes; skip unrelated updates on this per-keystroke path.
+        if (!update.docChanged && !update.selectionSet) {
+          return;
+        }
+
+        const builder = new RangeSetBuilder<Decoration>();
+        const selection = update.view.state.selection.main;
+        const line = update.view.state.doc.lineAt(selection.from);
+
+        // TODO(burdon): Check at end of line and matches start of previous word.
+        // TODO(burdon): Context grammar.
+        this.hint = undefined;
+        if (selection.from === selection.to && selection.from === line.to) {
+          const str = update.state.sliceDoc(line.from, selection.from);
+          this.hint = onComplete?.({ line: str });
+          if (this.hint) {
+            builder.add(selection.from, selection.to, Decoration.widget({ widget: new PlaceholderWidget(this.hint) }));
+          }
+        }
+
+        this.decorations = builder.finish();
+      }
+    },
+    {
+      decorations: (value) => value.decorations,
+    },
+  );
+
+  const complete: Command = (view: EditorView) => {
+    const hint = view.plugin(typeaheadPlugin)?.hint;
+    if (!hint) {
+      return false;
+    }
+
+    const selection = view.state.selection.main;
+    view.dispatch({
+      changes: [{ from: selection.from, to: selection.to, insert: hint }],
+      selection: EditorSelection.cursor(selection.from + hint.length),
+    });
+
+    return true;
+  };
+
+  return [
+    typeaheadPlugin,
+
+    // Keys.
+    Prec.highest(
+      keymap.of([
+        {
+          key: 'Tab',
+          preventDefault: true,
+          run: complete,
+        },
+        {
+          key: 'ArrowRight',
+          preventDefault: true,
+          run: complete,
+        },
+      ]),
+    ),
+  ];
+};

package/src/extensions/{factories.ts → core/factories.ts}

@@ -25,15 +25,14 @@ import { generateName } from '@dxos/display-name';
 import { Doc } from '@dxos/echo-doc';
 import { log } from '@dxos/log';
 import { type Messenger } from '@dxos/protocols';
-import { type Identity } from '@dxos/protocols/proto/dxos/client/services';
 import { type ChromaticPalette, type ThemeMode } from '@dxos/ui-types';
 import { hexToHue, isTruthy } from '@dxos/util';
 
-import { baseTheme, createFontTheme, editorGutter } from '../styles';
-import { automerge } from './automerge';
-import { SpaceAwarenessProvider, awareness } from './awareness';
-import { focus } from './focus';
-import { scrollPastEnd } from './scrolling';
+import { baseTheme, createFontTheme, editorGutter } from '../../styles';
+import { automerge } from '../collab/automerge';
+import { SpaceAwarenessProvider, awareness } from '../collab/awareness';
+import { focus } from '../state/focus';
+import { scrollPastEnd } from '../streaming/scrolling';
 
 //
 // Basic
@@ -44,6 +43,9 @@ import { scrollPastEnd } from './scrolling';
  */
 export const tabbable = EditorView.contentAttributes.of({ tabindex: '0' });
 
+/**
+ * Transaction filter that strips characters matching the given pattern from inserted text.
+ */
 export const filterChars = (chars: RegExp) => {
   return EditorState.transactionFilter.of((transaction) => {
     if (!transaction.docChanged) {
@@ -122,6 +124,10 @@ const keymaps: { [key: string]: readonly KeyBinding[] } = {
   default: defaultKeymap,
 };
 
+/**
+ * Assembles the base editor setup: keymaps, history, bracket matching/closing, drop cursor,
+ * read-only handling, line wrapping, and tab handling.
+ */
 export const createBasicExtensions = (propsProp?: BasicExtensionsOptions): Extension => {
   const props = defaultsDeep({}, propsProp, defaultBasicOptions);
   return [
@@ -209,7 +215,7 @@ export type ThemeExtensionsOptions = {
 
 export const grow: ThemeExtensionsOptions['slots'] = {
   editor: {
-    className: 'h-full w-full',
+    className: 'w-full h-full',
   },
 } as const;
 
@@ -265,32 +271,48 @@ export const createThemeExtensions = ({
 // Data
 //
 
+/**
+ * Minimal identity shape consumed by awareness. Kept structural so both the
+ * client identity and the `@dxos/halo` `Identity.Info` can be passed without
+ * this foundational editor package depending on either.
+ */
+export type DataExtensionsIdentity = {
+  /** Hex-encoded identity key, used as the awareness peer id. */
+  identityKey?: string;
+  displayName?: string;
+  /** Free-form profile metadata (e.g. `hue`). */
+  data?: Record<string, unknown>;
+};
+
 export type DataExtensionsProps<T> = {
   id: string;
   text?: Doc.Accessor<T>;
   messenger?: Messenger;
-  identity?: Identity | null;
+  identity?: DataExtensionsIdentity | null;
 };
 
+/**
+ * Wires document sync (automerge) and presence (awareness) for a text accessor.
+ */
 export const createDataExtensions = <T>({ id, text, messenger, identity }: DataExtensionsProps<T>): Extension[] => {
   const extensions: Extension[] = [];
   if (text) {
     extensions.push(automerge(text));
   }
 
-  if (messenger && identity) {
-    const peerId = identity?.identityKey.toHex();
-    const hue = (identity?.profile?.data?.hue as ChromaticPalette | undefined) ?? hexToHue(peerId ?? '0');
+  if (messenger && identity?.identityKey) {
+    const peerId = identity.identityKey;
+    const hue = (identity.data?.hue as ChromaticPalette | undefined) ?? hexToHue(peerId);
     extensions.push(
       awareness(
         new SpaceAwarenessProvider({
           messenger,
           channel: `awareness.${id}`,
-          peerId: identity.identityKey.toHex(),
+          peerId,
           info: {
             darkColor: `var(--color-${hue}-border)`,
             lightColor: `var(--color-${hue}-border)`,
-            displayName: identity.profile?.displayName ?? generateName(identity.identityKey.toHex()),
+            displayName: identity.displayName ?? generateName(peerId),
           },
         }),
       ),

package/src/extensions/core/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './factories';
+export * from './modes';

package/src/extensions/{modes.ts → core/modes.ts}

@@ -7,7 +7,7 @@ import { keymap } from '@codemirror/view';
 import { vim } from '@replit/codemirror-vim';
 import { vscodeKeymap } from '@replit/codemirror-vscode-keymap';
 
-import { singleValueFacet } from '../util';
+import { singleValueFacet } from '../../util';
 
 export type EditorInputConfig = {
   type?: string;
@@ -16,6 +16,9 @@ export type EditorInputConfig = {
 
 export const editorInputMode = singleValueFacet<EditorInputConfig>({});
 
+/**
+ * Map of input-mode keymap bundles (default, vscode, vim).
+ */
 export const InputModeExtensions: { [mode: string]: Extension } = {
   default: [],
   vscode: [

package/src/extensions/{debug.ts → debug/debug.ts}

@@ -5,6 +5,9 @@
 import { syntaxTree } from '@codemirror/language';
 import { type EditorState, type Extension, type RangeSet, StateField, type Transaction } from '@codemirror/state';
 
+/**
+ * Logs every syntax-tree node type on each editor update (debug only).
+ */
 // eslint-disable-next-line no-console
 export const debugNodeLogger = (log: (...args: any[]) => void = console.log): Extension => {
   const logTokens = (state: EditorState) => syntaxTree(state).iterate({ enter: (node) => log(node.type) });

package/src/extensions/debug/index.ts

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

package/src/extensions/{annotations.ts → decoration/annotations.ts}

@@ -5,14 +5,12 @@
 import { type Extension, RangeSetBuilder } from '@codemirror/state';
 import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
 
-const annotationMark = Decoration.mark({ class: 'cm-annotation' });
-
 export type AnnotationOptions = {
   match?: RegExp; // TODO(burdon): Update via hook (e.g., for search).
 };
 
 /**
- *
+ * Wavy-underline decoration over regex matches in the viewport.
  */
 export const annotations = ({ match }: AnnotationOptions = {}): Extension => {
   return [
@@ -44,12 +42,16 @@ export const annotations = ({ match }: AnnotationOptions = {}): Extension => {
       },
     ),
 
-    EditorView.theme({
-      '.cm-annotation': {
-        textDecoration: 'underline',
-        textDecorationStyle: 'wavy',
-        textDecorationColor: 'var(--color-error-text)',
-      },
-    }),
+    styles,
   ];
 };
+
+const annotationMark = Decoration.mark({ class: 'cm-annotation' });
+
+const styles = EditorView.theme({
+  '.cm-annotation': {
+    textDecoration: 'underline',
+    textDecorationStyle: 'wavy',
+    textDecorationColor: 'var(--color-error-text)',
+  },
+});

package/src/extensions/decoration/assistant.ts

@@ -0,0 +1,225 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Diagnostic, forEachDiagnostic, linter, setDiagnostics } from '@codemirror/lint';
+import { ChangeSet, type Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+
+import { log } from '@dxos/log';
+import { safeParseJson, trim } from '@dxos/util';
+
+export type AssistantOptions = {
+  /**
+   * Instructions to use for the language model.
+   */
+  instructions?: string;
+  /**
+   * Show panel automatically.
+   */
+  autoPanel?: boolean;
+  /**
+   * Debounce delay.
+   */
+  delay?: number;
+  /**
+   * Invoke the language model with the given prompt and return the raw text response.
+   */
+  generate: (request: { instructions: string; content: string }) => Promise<string>;
+};
+
+/**
+ * LLM-backed proofreading linter that draws colored underlines and populates a lint panel.
+ */
+export const assistant = (options: AssistantOptions): Extension[] => {
+  const styles = getComputedStyle(document.documentElement);
+  const style = {
+    info: styles.getPropertyValue('--color-green-500').trim(),
+    warning: styles.getPropertyValue('--color-orange-500').trim(),
+    error: styles.getPropertyValue('--color-rose-500').trim(),
+  };
+
+  return [
+    assistantLinter(options),
+    EditorView.baseTheme({
+      '.cm-lintRange-info': {
+        backgroundImage: underline(style.info),
+      },
+      '.cm-lintRange-warning': {
+        backgroundImage: underline(style.warning),
+      },
+      '.cm-lintRange-error': {
+        backgroundImage: underline(style.error),
+      },
+
+      '.cm-panels-bottom': {
+        borderTop: '1px solid var(--color-separator) !important',
+      },
+      '.cm-panel-lint .cm-panel': {
+        outline: 'none !important',
+      },
+      '.cm-panel button': {
+        color: 'var(--color-base-fg) !important',
+      },
+      '.cm-panel.cm-panel-lint ul': {
+        color: 'var(--color-base-fg) !important',
+        backgroundColor: 'var(--color-base-surface) !important',
+        marginRight: '2rem !important',
+      },
+      '.cm-panel.cm-panel-lint ul [aria-selected]': {
+        color: 'var(--color-base-fg) !important',
+        backgroundColor: 'var(--color-base-surface) !important',
+      },
+      '.cm-panel.cm-panel-lint ul li': {
+        display: 'grid',
+        gridTemplateColumns: '1fr auto',
+        alignItems: 'center',
+      },
+      '.cm-panel.cm-panel-lint ul li .cm-diagnosticText': {
+        paddingRight: '8px !important',
+      },
+      '.cm-panel.cm-panel-lint ul li button.cm-diagnosticAction': {
+        margin: 'none !important',
+      },
+      '.cm-diagnostic': {
+        padding: '0px 8px !important',
+        whiteSpace: 'pre-wrap !important',
+      },
+      '.cm-diagnostic-info': {
+        border: 'none !important',
+      },
+    }),
+  ];
+};
+
+const underline = (color: string) => {
+  const svg = trim`
+    <svg xmlns="http://www.w3.org/2000/svg" width="6" height="3">
+      <path d="m0 3 l2 -2 l1 0 l2 2 l1 0" stroke="${color}" fill="none" stroke-width="1"/>
+    </svg>
+  `;
+
+  return `url('data:image/svg+xml;base64,${btoa(svg)}') !important`;
+};
+
+//
+// Linter
+//
+
+type Suggestion = {
+  original: string;
+  replacement: string;
+  context: string;
+};
+
+const isSuggestion = (value: unknown): value is Suggestion =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as Suggestion).original === 'string' &&
+  typeof (value as Suggestion).replacement === 'string' &&
+  typeof (value as Suggestion).context === 'string';
+
+/**
+ * Find the index of `original` within `content`, using `context` to disambiguate when there are multiple occurrences.
+ */
+const findSuggestionIndex = (content: string, suggestion: Suggestion): number => {
+  const firstIdx = content.indexOf(suggestion.original);
+  if (firstIdx === -1) {
+    return -1;
+  }
+
+  // Check for duplicate occurrences; use context to disambiguate.
+  const secondIdx = content.indexOf(suggestion.original, firstIdx + 1);
+  if (secondIdx === -1) {
+    return firstIdx;
+  }
+
+  // Find the occurrence whose surrounding text best matches the context.
+  const contextIdx = content.indexOf(suggestion.context);
+  if (contextIdx !== -1) {
+    const contextEnd = contextIdx + suggestion.context.length;
+    if (secondIdx >= contextIdx && secondIdx <= contextEnd) {
+      return secondIdx;
+    }
+  }
+
+  return firstIdx;
+};
+
+const replaceTextAndDropLintAtRange = (view: EditorView, from: number, to: number, insert: string) => {
+  const kept: Diagnostic[] = [];
+  forEachDiagnostic(view.state, (diagnostic, diagnosticFrom, diagnosticTo) => {
+    if (diagnosticFrom < to && diagnosticTo > from) {
+      return;
+    }
+    kept.push({ ...diagnostic, from: diagnosticFrom, to: diagnosticTo });
+  });
+  const changeSet = ChangeSet.of({ from, to, insert }, view.state.doc.length);
+  const next = kept.map((d) => ({
+    ...d,
+    from: changeSet.mapPos(d.from, 1),
+    to: changeSet.mapPos(d.to, -1),
+  }));
+  view.dispatch({
+    changes: { from, to, insert },
+    ...setDiagnostics(view.state, next),
+  });
+};
+
+const DEFAULT_INSTRUCTIONS = trim`
+  Proofread the input text below.
+  Identify typos and grammatical errors. 
+  Return ONLY a valid JSON array of objects with fields: "original" (string), "replacement" (string), "context" (string, 3-5 words around match).
+  --
+`;
+
+const assistantLinter = ({
+  generate,
+  instructions = DEFAULT_INSTRUCTIONS,
+  autoPanel = true,
+  delay = 2_000,
+}: AssistantOptions) =>
+  linter(
+    async (view) => {
+      try {
+        const content = view.state.doc.toString();
+        const result = await generate({ instructions, content });
+
+        const [match] = result.match(/\[.*\]/s) ?? [];
+        const parsed = match ? safeParseJson<unknown[]>(match, []) : [];
+        const suggestions = Array.isArray(parsed) ? parsed.filter(isSuggestion) : [];
+        if (suggestions && suggestions.length > 0) {
+          const diagnostics: Diagnostic[] = [];
+          for (const suggestion of suggestions) {
+            const idx = findSuggestionIndex(content, suggestion);
+            if (idx !== -1) {
+              diagnostics.push({
+                from: idx,
+                to: idx + suggestion.original.length,
+                severity: 'info',
+                message: `Suggestion: ${suggestion.replacement}`,
+                actions: [
+                  {
+                    name: 'Apply',
+                    apply: (view, from, to) => {
+                      replaceTextAndDropLintAtRange(view, from, to, suggestion.replacement);
+                    },
+                  },
+                ],
+              });
+            }
+          }
+
+          return diagnostics;
+        }
+      } catch (err) {
+        log.catch(err);
+      }
+
+      return [];
+    },
+    {
+      delay,
+      autoPanel,
+    },
+  );

package/src/extensions/{fader.ts → decoration/fader.ts}

@@ -5,10 +5,6 @@
 import { type Extension, StateEffect, StateField } from '@codemirror/state';
 import { Decoration, type DecorationSet, EditorView, ViewPlugin } from '@codemirror/view';
 
-const DEFAULT_REMOVAL_DELAY = 5_000; // ms.
-const DEFAULT_COALESCE_WINDOW = 100; // ms.
-const CLEANUP_INTERVAL = 1_000; // ms.
-
 export type FaderOptions = {
   /** Time window in ms to coalesce adjacent appends into a single decoration. */
   coalesce?: number;
@@ -177,19 +173,21 @@ export const fader = (options: FaderOptions = {}): Extension => {
     },
   );
 
-  return [
-    fadeField,
-    cleanup,
-    EditorView.theme({
-      '.cm-fader': {
-        animation: 'fader 1s ease-out forwards',
-      },
-      '@keyframes fader': {
-        '0%': {
-          textShadow: '0 0 16px rgba(100, 200, 255, 1), 0 0 32px rgba(100, 200, 255, 0.6)',
-        },
-        '100%': {},
-      },
-    }),
-  ];
+  return [fadeField, cleanup, styles];
 };
+
+const DEFAULT_REMOVAL_DELAY = 5_000; // ms.
+const DEFAULT_COALESCE_WINDOW = 100; // ms.
+const CLEANUP_INTERVAL = 1_000; // ms.
+
+const styles = EditorView.theme({
+  '.cm-fader': {
+    animation: 'fader 1s ease-out forwards',
+  },
+  '@keyframes fader': {
+    '0%': {
+      textShadow: '0 0 16px rgba(100, 200, 255, 1), 0 0 32px rgba(100, 200, 255, 0.6)',
+    },
+    '100%': {},
+  },
+});

package/src/extensions/{hashtag.ts → decoration/hashtag.ts}

@@ -15,28 +15,10 @@ import {
 
 import { getHashStyles, mx } from '@dxos/ui-theme';
 
-class TagWidget extends WidgetType {
-  constructor(private _text: string) {
-    super();
-  }
-
-  toDOM(): HTMLSpanElement {
-    const span = document.createElement('span');
-    span.className = mx('cm-tag', getHashStyles(this._text).surface);
-    span.textContent = this._text;
-    return span;
-  }
-}
-
-const tagMatcher = new MatchDecorator({
-  regexp: /#(\w+)\W/g,
-  decoration: (match) =>
-    Decoration.replace({
-      widget: new TagWidget(match[1]),
-    }),
-});
-
 // TODO(burdon): Autocomplete from existing tags?
+/**
+ * Replaces `#tag` occurrences with a styled atomic widget.
+ */
 export const hashtag = (): Extension => [
   ViewPlugin.fromClass(
     class {
@@ -58,11 +40,36 @@ export const hashtag = (): Extension => [
     },
   ),
 
-  EditorView.theme({
-    '.cm-tag': {
-      borderRadius: '4px',
-      marginRight: '6px',
-      padding: '2px 6px',
-    },
-  }),
+  styles,
 ];
+
+class TagWidget extends WidgetType {
+  constructor(private _text: string) {
+    super();
+  }
+
+  toDOM(): HTMLSpanElement {
+    const span = document.createElement('span');
+    span.className = mx('cm-tag', getHashStyles(this._text).surface);
+    span.textContent = this._text;
+    return span;
+  }
+}
+
+const tagMatcher = new MatchDecorator({
+  // `\w+` stops at the first non-word char, so no trailing boundary is needed; requiring one
+  // (e.g. `\W`) would consume that char and fail to match a tag at the end of the document.
+  regexp: /#(\w+)/g,
+  decoration: (match) =>
+    Decoration.replace({
+      widget: new TagWidget(match[1]),
+    }),
+});
+
+const styles = EditorView.theme({
+  '.cm-tag': {
+    borderRadius: '4px',
+    marginRight: '6px',
+    padding: '2px 6px',
+  },
+});

package/src/extensions/decoration/index.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './annotations';
+export * from './assistant';
+export * from './fader';
+export * from './hashtag';
+export * from './marker';
+export * from './pos';
+export * from './replacer';