@dxos/react-ui-editor 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-ui-editor",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Text editor components.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -40,55 +40,55 @@
     "@codemirror/search": "^6.7.2",
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.13",
-    "@dxos/app-graph": "0.14.0",
-    "@dxos/async": "0.14.0",
-    "@dxos/invariant": "0.14.0",
-    "@dxos/log": "0.14.0",
-    "@dxos/react-hooks": "0.14.0",
-    "@dxos/react-ui-menu": "0.14.0",
-    "@dxos/ui-editor": "0.14.0",
-    "@dxos/ui-types": "0.14.0",
-    "@dxos/util": "0.14.0"
+    "@dxos/app-graph": "0.16.0",
+    "@dxos/async": "0.16.0",
+    "@dxos/invariant": "0.16.0",
+    "@dxos/log": "0.16.0",
+    "@dxos/react-hooks": "0.16.0",
+    "@dxos/react-ui-menu": "0.16.0",
+    "@dxos/ui-editor": "0.16.0",
+    "@dxos/ui-types": "0.16.0",
+    "@dxos/util": "0.16.0"
   },
   "devDependencies": {
     "@codemirror/autocomplete": "^6.20.3",
     "@codemirror/lang-javascript": "^6.2.5",
     "@codemirror/lang-markdown": "6.5.2",
-    "@effect/atom-react": "4.0.0",
+    "@effect/atom-react": "4.0.4",
     "@storybook/react-vite": "^10.6.0",
     "@types/lodash.defaultsdeep": "^4.6.6",
     "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "effect": "4.0.0",
+    "effect": "4.0.4",
     "happy-dom": "^20.0.0",
     "lodash.defaultsdeep": "^4.6.1",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "vite": "^8.2.2",
-    "@dxos/ai": "0.14.0",
-    "@dxos/echo": "0.14.0",
-    "@dxos/echo-client": "0.14.0",
-    "@dxos/echo-doc": "0.14.0",
-    "@dxos/echo-react": "0.14.0",
-    "@dxos/keys": "0.14.0",
-    "@dxos/protocols": "0.14.0",
-    "@dxos/random": "0.14.0",
-    "@dxos/react-client": "0.14.0",
-    "@dxos/react-ui": "0.14.0",
-    "@dxos/react-ui-attention": "0.14.0",
-    "@dxos/react-ui-list": "0.14.0",
-    "@dxos/react-ui-syntax-highlighter": "0.14.0",
-    "@dxos/schema": "0.14.0",
-    "@dxos/ui": "0.14.0",
-    "@dxos/ui-theme": "0.14.0"
+    "vite": "^8.3.4",
+    "@dxos/ai": "0.16.0",
+    "@dxos/echo": "0.16.0",
+    "@dxos/echo-client": "0.16.0",
+    "@dxos/echo-doc": "0.16.0",
+    "@dxos/echo-react": "0.16.0",
+    "@dxos/keys": "0.16.0",
+    "@dxos/protocols": "0.16.0",
+    "@dxos/random": "0.16.0",
+    "@dxos/react-client": "0.16.0",
+    "@dxos/react-ui": "0.16.0",
+    "@dxos/react-ui-attention": "0.16.0",
+    "@dxos/react-ui-list": "0.16.0",
+    "@dxos/react-ui-syntax-highlighter": "0.16.0",
+    "@dxos/schema": "0.16.0",
+    "@dxos/ui": "0.16.0",
+    "@dxos/ui-theme": "0.16.0"
   },
   "peerDependencies": {
-    "@effect/atom-react": "4.0.0",
-    "effect": "4.0.0",
+    "@effect/atom-react": "4.0.4",
+    "effect": "4.0.4",
     "react": "~19.2.7",
     "react-dom": "~19.2.7",
-    "@dxos/react-ui": "^0.14.0",
-    "@dxos/ui-theme": "^0.14.0"
+    "@dxos/react-ui": "^0.16.0",
+    "@dxos/ui-theme": "^0.16.0"
   },
   "publishConfig": {
     "access": "public"

package/src/components/EditorMenuProvider/EditorMenuProvider.tsx

@@ -306,7 +306,7 @@ const MenuItem = ({ item, current, onSelect }: MenuItemProps) => {
   return (
     // Menu row metrics without a Menu machine: the popover keeps focus in the editor, so `current` is the highlight.
     <li ref={listRef} className='dx-menu-item' data-highlighted={current ? '' : undefined} onClick={handleSelect}>
-      {item.icon && <Icon.Icon icon={item.icon} />}
+      {item.icon && <Icon.Icon icon={item.icon} hue={item.iconHue} />}
       <span className='dx-menu-item-text'>{Theme.toLocalizedString(item.label, t)}</span>
     </li>
   );

package/src/components/EditorMenuProvider/menu.ts

@@ -6,6 +6,7 @@ import { type EditorView } from '@codemirror/view';
 
 import type * as Theme from '@dxos/react-ui/Theme';
 import { insertAtCursor } from '@dxos/ui-editor';
+import { type ChromaticPalette } from '@dxos/ui-types';
 import { type MaybePromise } from '@dxos/util';
 
 export type EditorMenuGroup = {
@@ -18,6 +19,7 @@ export type EditorMenuItem = {
   id: string;
   label: Theme.Label;
   icon?: string;
+  iconHue?: ChromaticPalette;
   onSelect?: (event: { view: EditorView; head: number }) => MaybePromise<void>;
 };
 

package/src/components/EditorMenuProvider/popover.ts

@@ -22,7 +22,8 @@ const DELIMITERS = [' ', ':'];
 export type PopoverOptions = {
   trigger?: string | string[];
   triggerKey?: string;
-  placeholder?: Partial<PlaceholderOptions>;
+  /** Overrides the trigger hint shown in an empty, focused editor; `false` omits the hint. */
+  placeholder?: Partial<PlaceholderOptions> | false;
   delimiters?: string[];
 
   /**
@@ -38,6 +39,12 @@ export type PopoverOptions = {
    */
   activateOnDelimiters?: string[];
 
+  /**
+   * Triggers whose query may contain spaces (e.g. multi-word names). A double space, a leading space or a
+   * line break still ends it, and Escape keeps the typed text.
+   */
+  multiWordTriggers?: string[];
+
   // Trigger update.
   onTextChange?: (event: { view: EditorView; pos: number; text: string; trigger?: string }) => void;
   onClose?: (event: { view: EditorView }) => void;
@@ -62,6 +69,7 @@ export const popover = (options: PopoverOptions = {}): Extension => {
     popoverAnchorDecoration(options),
     modalStateField,
     options.trigger &&
+      options.placeholder !== false &&
       placeholder({
         // TODO(burdon): Translations.
         content: `Press '${Array.isArray(options.trigger) ? options.trigger[0] : options.trigger}' for commands`,
@@ -82,12 +90,13 @@ const popoverTriggerListener = (options: PopoverOptions) =>
     }
 
     const text = view.state.doc.sliceString(activeRange.from, activeRange.to);
+    const query = trigger ? text.slice(1) : text;
     const selection = view.state.selection.main;
     const shouldClose =
       // Trigger deleted.
       (trigger ? trigger !== text[0] : false) ||
-      // Whitespace in text.
-      /\s/.test(trigger ? text.slice(1) : text) ||
+      // Whitespace in text; a multi-word query may hold single spaces between words.
+      (trigger && options.multiWordTriggers?.includes(trigger) ? /^\s|[^\S ]| {2}/.test(query) : /\s/.test(query)) ||
       // Cursor moved before the range.
       selection.head < activeRange.from ||
       // Cursor moved after the range (+1 to handle selection changing before doc).

package/src/components/EditorMenuProvider/useEditorMenu.test.tsx

@@ -0,0 +1,125 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+import React, { act, useEffect } from 'react';
+import { createRoot } from 'react-dom/client';
+import { beforeAll, describe, onTestFinished, test, vi } from 'vitest';
+
+import { useTextEditor } from '../../hooks/index.ts';
+import { type EditorMenuGroup, type EditorMenuItem, createMenuGroup } from './menu.ts';
+import { popoverStateField } from './popover.ts';
+import { type UseEditorMenuProps, useEditorMenu } from './useEditorMenu.ts';
+
+const getMenu: UseEditorMenuProps['getMenu'] = ({ text }): EditorMenuGroup[] => [
+  { id: 'create', items: [{ id: 'create', label: 'Add object' }] },
+  createMenuGroup({ id: 'test', filter: text, items: ['Hello world', 'Hello DXOS', 'Goodbye world'] }),
+];
+
+type Menu = { view: EditorView; labels: () => EditorMenuItem['label'][]; cancel: () => void };
+
+const MenuEditor = ({ onReady }: { onReady: (menu: Menu) => void }) => {
+  const { groupsRef, extension, onCancel } = useEditorMenu({ trigger: '@', multiWordTriggers: ['@'], getMenu });
+  const { parentRef, view } = useTextEditor({ extensions: [extension] });
+  useEffect(() => {
+    if (view) {
+      onReady({
+        view,
+        labels: () => groupsRef.current.flatMap((group) => group.items.map((item) => item.label)),
+        cancel: () => onCancel?.({ view }),
+      });
+    }
+  }, [view, groupsRef, onCancel, onReady]);
+
+  return <div ref={parentRef} />;
+};
+
+const mountMenuEditor = async (): Promise<Menu> => {
+  const container = document.createElement('div');
+  document.body.append(container);
+  const root = createRoot(container);
+  let menu: Menu | undefined;
+  await act(async () => root.render(<MenuEditor onReady={(ready) => (menu = ready)} />));
+  onTestFinished(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+  return vi.waitFor(() => menu!);
+};
+
+/** Types as a user does: the trigger through its keymap, the rest as input. */
+const type = (view: EditorView, text: string) => {
+  for (const char of text) {
+    const event = new KeyboardEvent('keydown', { key: char, bubbles: true, cancelable: true });
+    view.contentDOM.dispatchEvent(event);
+    if (!event.defaultPrevented) {
+      const head = view.state.selection.main.head;
+      view.dispatch({
+        changes: { from: head, insert: char },
+        selection: { anchor: head + 1 },
+        userEvent: 'input.type',
+      });
+    }
+  }
+};
+
+const press = (view: EditorView, key: string) =>
+  view.contentDOM.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
+
+describe('useEditorMenu', () => {
+  beforeAll(() => {
+    Reflect.set(globalThis, 'IS_REACT_ACT_ENVIRONMENT', true);
+  });
+
+  test('a multi-word query stays open as the user types, matching or not', async ({ expect }) => {
+    const { view, labels } = await mountMenuEditor();
+    const isOpen = () => view.state.field(popoverStateField) !== null;
+
+    await act(async () => type(view, '@hello '));
+    await vi.waitFor(() => expect(labels()).toEqual(['Add object', 'Hello world', 'Hello DXOS']));
+
+    await act(async () => type(view, 'w'));
+    await vi.waitFor(() => expect(labels()).toEqual(['Add object', 'Hello world']));
+
+    await act(async () => type(view, 'x and more'));
+    await vi.waitFor(() => expect(labels()).toEqual(['Add object']));
+    expect(isOpen()).toBe(true);
+  });
+
+  test('Enter picks the highlighted row in place of a multi-word query', async ({ expect }) => {
+    const { view, labels } = await mountMenuEditor();
+    await act(async () => type(view, '@hello w'));
+    await vi.waitFor(() => expect(labels()).toEqual(['Add object', 'Hello world']));
+
+    await act(async () => press(view, 'ArrowDown'));
+    await act(async () => press(view, 'Enter'));
+    expect(view.state.doc.toString()).toBe('Hello world');
+    expect(view.state.field(popoverStateField)).toBeNull();
+  });
+
+  test('moving the cursor out of a multi-word query ends it', async ({ expect }) => {
+    const { view } = await mountMenuEditor();
+    await act(async () => type(view, 'x @hello world'));
+    expect(view.state.field(popoverStateField)).not.toBeNull();
+
+    await act(async () => view.dispatch({ selection: { anchor: 0 } }));
+    expect(view.state.field(popoverStateField)).toBeNull();
+  });
+
+  test('a double or leading space ends the query', async ({ expect }) => {
+    const { view } = await mountMenuEditor();
+    await act(async () => type(view, '@hello  '));
+    expect(view.state.field(popoverStateField)).toBeNull();
+
+    await act(async () => type(view, '@ '));
+    expect(view.state.field(popoverStateField)).toBeNull();
+  });
+
+  test('cancel keeps a multi-word query in the document', async ({ expect }) => {
+    const { view, cancel } = await mountMenuEditor();
+    await act(async () => type(view, '@hello world'));
+    cancel();
+    expect(view.state.doc.toString()).toBe('@hello world');
+  });
+});

package/src/components/EditorMenuProvider/useEditorMenu.ts

@@ -5,7 +5,7 @@
 import { type Extension } from '@codemirror/state';
 import { type EditorState } from '@codemirror/state';
 import { type EditorView } from '@codemirror/view';
-import { type RefObject, useCallback, useMemo, useRef, useState } from 'react';
+import { type RefObject, useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
 
 import { invariant } from '@dxos/invariant';
 import { modalStateEffect } from '@dxos/ui-editor';
@@ -29,9 +29,22 @@ export type UseEditorMenuProps = {
    * Triggers whose menu is rendered as a combobox: the popover owns a search input and the query is
    * typed there rather than into the document.
    */
+  // TODO(wittjosiah): Remove? Prefer inline instead.
   searchTriggers?: string[];
   getMenu?: (context: GetMenuContext) => MaybePromise<EditorMenuGroup[]>;
-} & Pick<PopoverOptions, 'trigger' | 'triggerKey' | 'placeholder' | 'activateOnTyping' | 'activateOnDelimiters'>;
+} & Pick<
+  PopoverOptions,
+  'trigger' | 'triggerKey' | 'placeholder' | 'activateOnTyping' | 'activateOnDelimiters' | 'multiWordTriggers'
+>;
+
+type MenuContext = {
+  view: EditorView;
+  pos: number;
+  text: string;
+  trigger?: string;
+  /** The trigger's query may hold spaces; see {@link PopoverOptions.multiWordTriggers}. */
+  multiWord?: boolean;
+};
 
 export type UseEditorMenu = {
   groupsRef: RefObject<EditorMenuGroup[]>;
@@ -67,6 +80,7 @@ export const useEditorMenu = ({
   placeholder,
   activateOnTyping,
   activateOnDelimiters,
+  multiWordTriggers,
   filter = true,
   searchTriggers,
   getMenu,
@@ -81,17 +95,24 @@ export const useEditorMenu = ({
 
   // The document range only supplies the trigger-relative prefix (e.g. the second "@" of a block
   // embed); in search mode the rest of the query comes from the popover's input.
-  const contextRef = useRef<{ view: EditorView; pos: number; text: string; trigger?: string } | null>(null);
+  const contextRef = useRef<MenuContext | null>(null);
 
   // Monotonic token identifying the latest menu query; bumped per request and on close.
   const requestRef = useRef(0);
 
+  // The latest `getMenu`, read when the menu opens: it changes whenever the caller's data does, and the extension
+  // built from it would otherwise rebuild the view, blurring the editor mid-keystroke.
+  const getMenuRef = useRef(getMenu);
+  useLayoutEffect(() => {
+    getMenuRef.current = getMenu;
+  }, [getMenu]);
+
   /**
    * Get filtered options.
    */
   const getMenuOptions = useCallback<NonNullable<UseEditorMenuProps['getMenu']>>(
     async ({ text, trigger, ...props }) => {
-      const groups = (await getMenu?.({ text, trigger, ...props })) ?? [];
+      const groups = (await getMenuRef.current?.({ text, trigger, ...props })) ?? [];
       // The "@" menu can use "@@" as syntax for block embeds, so it owns its own query filtering.
       return filter && trigger !== '@'
         ? filterMenuGroups(groups, (item) =>
@@ -99,37 +120,7 @@ export const useEditorMenu = ({
           )
         : groups;
     },
-    [getMenu, filter],
-  );
-
-  /**
-   * Recompute the menu and preselect the first item.
-   */
-  const updateGroups = useCallback(
-    async ({ view, pos, text, trigger }: { view: EditorView; pos: number; text: string; trigger?: string }) => {
-      const request = ++requestRef.current;
-      const groups = (await getMenuOptions({ state: view.state, pos, text, trigger })) ?? [];
-      // Queries resolve out of order, so a slower earlier one must not overwrite a newer result
-      // (or repopulate the menu after it closed).
-      if (request !== requestRef.current) {
-        return;
-      }
-
-      groupsRef.current = groups;
-      const firstItem = groupsRef.current.filter((group) => group.items.length > 0)[0]?.items[0];
-      if (firstItem) {
-        setCurrentItem(firstItem.id);
-        currentRef.current = firstItem;
-      } else {
-        // No matches: clear the selection so Enter falls through instead of
-        // selecting a stale item from a previous query.
-        setCurrentItem(undefined);
-        currentRef.current = null;
-      }
-
-      refresh({});
-    },
-    [getMenuOptions],
+    [filter],
   );
 
   const handleOpenChange = useCallback<NonNullable<UseEditorMenu['onOpenChange']>>(
@@ -161,6 +152,36 @@ export const useEditorMenu = ({
     [getMenuOptions],
   );
 
+  /**
+   * Recompute the menu and preselect the first item.
+   */
+  const updateGroups = useCallback(
+    async ({ view, pos, text, trigger }: MenuContext) => {
+      const request = ++requestRef.current;
+      const groups = (await getMenuOptions({ state: view.state, pos, text, trigger })) ?? [];
+      // Queries resolve out of order, so a slower earlier one must not overwrite a newer result
+      // (or repopulate the menu after it closed).
+      if (request !== requestRef.current) {
+        return;
+      }
+
+      groupsRef.current = groups;
+      const firstItem = groupsRef.current.filter((group) => group.items.length > 0)[0]?.items[0];
+      if (firstItem) {
+        setCurrentItem(firstItem.id);
+        currentRef.current = firstItem;
+      } else {
+        // No matches: clear the selection so Enter falls through instead of
+        // selecting a stale item from a previous query.
+        setCurrentItem(undefined);
+        currentRef.current = null;
+      }
+
+      refresh({});
+    },
+    [getMenuOptions],
+  );
+
   const handleActivate = useCallback<NonNullable<UseEditorMenu['onActivate']>>(
     async ({ view, trigger }) => {
       const item = getMenuItem(groupsRef.current, currentItem);
@@ -186,9 +207,9 @@ export const useEditorMenu = ({
   }, []);
 
   const handleCancel = useCallback<NonNullable<UseEditorMenu['onCancel']>>(({ view }) => {
-    // Delete trigger.
+    // Delete trigger; a multi-word query may be a sentence the user wants to keep.
     const { range, trigger } = view.state.field(popoverStateField) ?? {};
-    if (range && trigger) {
+    if (range && trigger && !contextRef.current?.multiWord) {
       view.dispatch({
         changes: { ...range, insert: '' },
       });
@@ -224,17 +245,21 @@ export const useEditorMenu = ({
 
   // Array props are compared by CONTENT, not identity: a caller writing `trigger={['#']}` inline
   // hands over a new array every render, and a changed extension destroys and recreates the view —
-  // blurring the editor mid-keystroke.
-  const serializedTrigger = Array.isArray(trigger) ? trigger.join(',') : trigger;
-  const serializedSearchTriggers = searchTriggers?.join(',');
-  const serializedDelimiters = activateOnDelimiters?.join(',');
+  // blurring the editor mid-keystroke. The memo reads them back from the key, so the React Compiler keys it the
+  // same way.
+  const arraysKey = JSON.stringify({ trigger, searchTriggers, activateOnDelimiters, multiWordTriggers });
   const extension = useMemo<Extension>(() => {
+    const arrays: Pick<
+      UseEditorMenuProps,
+      'trigger' | 'searchTriggers' | 'activateOnDelimiters' | 'multiWordTriggers'
+    > = JSON.parse(arraysKey);
     return popover({
-      trigger,
+      trigger: arrays.trigger,
       triggerKey,
       placeholder,
       activateOnTyping,
-      activateOnDelimiters,
+      activateOnDelimiters: arrays.activateOnDelimiters,
+      multiWordTriggers: arrays.multiWordTriggers,
       onClose: ({ view }) => handleOpenChange({ view, open: false }),
       onEnter: ({ view }) => {
         if (currentRef.current) {
@@ -246,23 +271,21 @@ export const useEditorMenu = ({
       onArrowUp: () => handleNavigate('up'),
       onArrowDown: () => handleNavigate('down'),
       onTextChange: async ({ view, pos, text, trigger }) => {
-        contextRef.current = { view, pos, text, trigger };
+        const context: MenuContext = {
+          view,
+          pos,
+          text,
+          trigger,
+          multiWord: !!trigger && !!arrays.multiWordTriggers?.includes(trigger),
+        };
+        contextRef.current = context;
         // The input is remounted per activation, so the query always starts empty.
-        setSearch(!!trigger && !!searchTriggers?.includes(trigger));
+        setSearch(!!trigger && !!arrays.searchTriggers?.includes(trigger));
         setQuery('');
-        await updateGroups({ view, pos, text, trigger });
+        await updateGroups(context);
       },
     });
-  }, [
-    handleOpenChange,
-    handleNavigate,
-    updateGroups,
-    serializedTrigger,
-    serializedSearchTriggers,
-    serializedDelimiters,
-    placeholder,
-    activateOnTyping,
-  ]);
+  }, [handleOpenChange, handleNavigate, updateGroups, arraysKey, triggerKey, placeholder, activateOnTyping]);
 
   return {
     groupsRef,

package/src/hooks/useTextEditor.test.tsx

@@ -2,22 +2,34 @@
 // Copyright 2026 DXOS.org
 //
 
-import React, { act } from 'react';
+import React, { act, useEffect } from 'react';
 import { createRoot } from 'react-dom/client';
 import { beforeAll, describe, onTestFinished, test } from 'vitest';
 
-import { useTextEditor } from './useTextEditor.ts';
+import { type EditorView } from '@dxos/ui-editor';
+
+import { type UseTextEditorProps, useTextEditor } from './useTextEditor.ts';
 
 const AutoFocusEditor = () => {
   const { parentRef } = useTextEditor({ autoFocus: true });
   return <div ref={parentRef} />;
 };
 
-const mountAutoFocusEditor = async (): Promise<HTMLElement> => {
+const RestoringEditor = ({ onView, ...props }: UseTextEditorProps & { onView: (view: EditorView) => void }) => {
+  const { parentRef, view } = useTextEditor(props);
+  useEffect(() => {
+    if (view) {
+      onView(view);
+    }
+  }, [view]);
+  return <div ref={parentRef} />;
+};
+
+const mount = async (element: React.ReactElement): Promise<HTMLElement> => {
   const container = document.createElement('div');
   document.body.append(container);
   const root = createRoot(container);
-  await act(async () => root.render(<AutoFocusEditor />));
+  await act(async () => root.render(element));
   onTestFinished(() => {
     act(() => root.unmount());
     container.remove();
@@ -25,6 +37,8 @@ const mountAutoFocusEditor = async (): Promise<HTMLElement> => {
   return container;
 };
 
+const mountAutoFocusEditor = () => mount(<AutoFocusEditor />);
+
 describe('useTextEditor', () => {
   beforeAll(() => {
     Reflect.set(globalThis, 'IS_REACT_ACT_ENVIRONMENT', true);
@@ -46,4 +60,31 @@ describe('useTextEditor', () => {
     await mountAutoFocusEditor();
     expect(document.activeElement).toBe(menu);
   });
+
+  // A bound editor mounts empty and the binding fills it afterwards; the recorded caret must land
+  // once the content arrives rather than being dropped against the empty document.
+  test('restores the selection once the content arrives', async ({ expect }) => {
+    let view: EditorView | undefined;
+    await mount(<RestoringEditor id='doc' selection={{ anchor: 5 }} onView={(next) => (view = next)} />);
+    expect(view?.state.doc.length).toBe(0);
+
+    await act(async () => {
+      view?.dispatch({ changes: { from: 0, insert: 'hello world' } });
+      await Promise.resolve();
+    });
+    expect(view?.state.selection.main.anchor).toBe(5);
+  });
+
+  test('restores the selection immediately when the content is present', async ({ expect }) => {
+    let view: EditorView | undefined;
+    await mount(
+      <RestoringEditor
+        id='doc'
+        initialValue='hello world'
+        selection={{ anchor: 7 }}
+        onView={(next) => (view = next)}
+      />,
+    );
+    expect(view?.state.selection.main.anchor).toBe(7);
+  });
 });

package/src/hooks/useTextEditor.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { EditorState, type EditorStateConfig, type Text } from '@codemirror/state';
+import { EditorState, type EditorStateConfig, StateEffect, type Text } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
 import {
   type ComponentPropsWithoutRef,
@@ -20,6 +20,7 @@ import {
 import { log } from '@dxos/log';
 import {
   type EditorSelection,
+  type EditorSelectionState,
   debugDispatcher,
   documentId,
   modalStateField,
@@ -56,6 +57,10 @@ export type UseTextEditorProps = Pick<EditorStateConfig, 'extensions'> & {
   debug?: boolean;
 };
 
+/** Whether every position in a recorded state lies within a document of `length`. */
+const fitsDocument = ({ scrollTo, selection }: EditorSelectionState, length: number): boolean =>
+  (scrollTo ?? 0) <= length && (selection?.anchor ?? 0) <= length && (selection?.head ?? 0) <= length;
+
 /**
  * Creates codemirror text editor.
  */
@@ -130,16 +135,39 @@ export const useTextEditor = (
   }, deps);
 
   useEffect(() => {
-    if (view) {
-      if (scrollTo != null || selection) {
-        if (selection && selection.anchor > view.state.doc.length) {
-          log.warn('invalid selection', { length: view.state.doc.length, scrollTo, selection });
-          return;
-        }
+    if (!view || (scrollTo == null && !selection)) {
+      return;
+    }
 
-        restoreEditorState(view, { scrollTo, scrollOffset, selection });
-      }
+    const state: EditorSelectionState = { scrollTo, scrollOffset, selection };
+    if (fitsDocument(state, view.state.doc.length)) {
+      restoreEditorState(view, state);
+      return;
     }
+
+    // A bound editor is created before its content arrives (the automerge binding fills the document
+    // on attach), so a restore against the empty document would be dropped; restore on the fill instead.
+    let active = true;
+    let pending = true;
+    view.dispatch({
+      effects: StateEffect.appendConfig.of(
+        EditorView.updateListener.of((update) => {
+          if (pending && update.docChanged && fitsDocument(state, update.state.doc.length)) {
+            pending = false;
+            // A view cannot be dispatched to from within its own update.
+            queueMicrotask(() => {
+              if (active) {
+                restoreEditorState(update.view, state);
+              }
+            });
+          }
+        }),
+      ),
+    });
+
+    return () => {
+      active = false;
+    };
   }, [view, scrollTo, scrollOffset, selection]);
 
   useEffect(() => {