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

package/src/extensions/structure/outliner/dnd.ts

@@ -0,0 +1,375 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { getIndentUnit } from '@codemirror/language';
+import { type EditorState, type Extension } from '@codemirror/state';
+import { type Command, EditorView } from '@codemirror/view';
+
+import { bulletListIndentationWidth } from '../../language/markdown/styles';
+import {
+  type Block,
+  type BlockOps,
+  blockSelectionField,
+  createBlockDrag,
+  createBlockSelection,
+  setBlockSelection,
+} from '../blocks';
+import { type Item, type Tree, getRange, treeFacet } from './tree';
+
+/**
+ * Flattens the tree into draggable units in document order, one per item. Each unit spans only the
+ * item's own lines (up to its first child), so the ranges are non-overlapping and every item — parent
+ * or leaf — gets its own gutter handle. Memoized per state so the gutter and drag plugin share it.
+ */
+const itemCache = new WeakMap<EditorState, Item[]>();
+const flattenItems = (state: EditorState): Item[] => {
+  const cached = itemCache.get(state);
+  if (cached) {
+    return cached;
+  }
+
+  const tree = state.facet(treeFacet);
+  const items: Item[] = [];
+  tree.traverse((item) => {
+    items.push(item);
+  });
+
+  itemCache.set(state, items);
+  return items;
+};
+
+const getBlocks = (state: EditorState): Block[] =>
+  flattenItems(state).map((item) => ({
+    from: item.lineRange.from,
+    // The item's own lines end just before its first child (or at its line range end for a leaf).
+    to: item.children.length > 0 ? item.children[0].lineRange.from - 1 : item.lineRange.to,
+  }));
+
+// The range a block visually occupies for selection/drag: its whole subtree (item + descendants), so
+// selecting or dragging a parent covers its children. `getBlocks` still yields per-item own-lines.
+// Exported for tests.
+export const getExtent = (state: EditorState, block: Block): Block => {
+  const tree = state.facet(treeFacet);
+  const item = tree.find(block.from);
+  if (!item) {
+    return block;
+  }
+  const [from, to] = getRange(tree, item);
+  return { from, to };
+};
+
+/** Leading-whitespace width of the line at `pos` (indentation depth in characters). */
+const indentAt = (state: EditorState, pos: number): number => {
+  const text = state.doc.lineAt(pos).text;
+  return text.length - text.trimStart().length;
+};
+
+/**
+ * Resolves the drop indentation for a single-item drag (see DESIGN "Drag reindent — drop level rules").
+ * The dragged subtree stays in the branch of the item above the drop slot by default, outdenting to a
+ * sibling of the (shallower) drop target only while the pointer is over that target's row. Returns the
+ * target leading-space count and the horizontal pixel offset that previews it. Exported for tests.
+ */
+export const getDropIndent = (
+  view: EditorView,
+  sourceIndices: number[],
+  dropIndex: number,
+  pointerY: number,
+): { indent: number; offset: number } | null => {
+  // Multi-item group moves keep their own relative indentation (no single re-root).
+  if (sourceIndices.length !== 1) {
+    return null;
+  }
+
+  const { state } = view;
+  const items = flattenItems(state);
+  const count = items.length;
+  const unit = getIndentUnit(state);
+  const sourceItem = items[sourceIndices[0]];
+  const sourceIndent = indentAt(state, sourceItem.lineRange.from);
+
+  // The item directly above the drop slot, skipping the dragged subtree (the source's children are
+  // collapsed with it, so they cannot serve as the indent reference).
+  const [sourceFrom, sourceTo] = getRange(state.facet(treeFacet), sourceItem);
+  let aboveIndex = dropIndex - 1;
+  while (
+    aboveIndex >= 0 &&
+    items[aboveIndex].lineRange.from >= sourceFrom &&
+    items[aboveIndex].lineRange.from <= sourceTo
+  ) {
+    aboveIndex--;
+  }
+  const above = aboveIndex >= 0 ? items[aboveIndex] : null;
+  const target = dropIndex < count ? items[dropIndex] : null;
+
+  const aboveIndent = above ? indentAt(state, above.lineRange.from) : 0;
+  // Valid range for the slot: a sibling of the target (shallowest) up to a child of the item above.
+  const minIndent = target ? indentAt(state, target.lineRange.from) : 0;
+  const maxIndent = above ? aboveIndent + unit : minIndent;
+  const clamp = (value: number) => Math.max(minIndent, Math.min(maxIndent, value));
+
+  // Default: keep the dragged item at its own level (staying in its branch), clamped to the slot's range.
+  let indent = clamp(sourceIndent);
+  // Outdent to a sibling of the target only at a real branch boundary and while over the target row.
+  if (target && minIndent < indent) {
+    const top = view.coordsAtPos(target.lineRange.from)?.top;
+    if (top != null && pointerY >= top) {
+      indent = minIndent;
+    }
+  }
+
+  // Preview offset: one indentation width per indent unit of delta from the source's own indent.
+  const offset = ((indent - sourceIndent) / unit) * bulletListIndentationWidth;
+  return { indent, offset };
+};
+
+/**
+ * Re-roots `text` (a moved subtree) from `fromIndent` to `toIndent` by shifting every line's leading
+ * whitespace, preserving the subtree's internal relative indentation. Keeps the moved item valid at
+ * its new depth (e.g. dragging a nested task to the top level).
+ */
+const reindent = (text: string, fromIndent: number, toIndent: number): string => {
+  const delta = toIndent - fromIndent;
+  if (delta === 0) {
+    return text;
+  }
+  return text
+    .split('\n')
+    .map((line) => {
+      const existing = line.length - line.trimStart().length;
+      const next = Math.max(0, existing + delta);
+      return ' '.repeat(next) + line.slice(existing);
+    })
+    .join('\n');
+};
+
+/**
+ * Moves the item at `sourceIndex` (with its whole subtree) to the slot before `dropIndex`, or to the
+ * end of the document when `dropIndex === items.length`. Expressed as a minimal delete + insert so it
+ * is a single undo step and syncs as a small edit.
+ */
+const moveItem = (view: EditorView, sourceIndex: number, dropIndex: number, indent?: number): void => {
+  const { state } = view;
+  const tree: Tree = state.facet(treeFacet);
+  const items = flattenItems(state);
+  const count = items.length;
+  if (sourceIndex < 0 || sourceIndex >= count || dropIndex === sourceIndex) {
+    return;
+  }
+
+  const source = items[sourceIndex];
+  const [from, to] = getRange(tree, source);
+
+  // Insert before the drop-target item, or append at the end.
+  const insertAt = dropIndex < count ? items[dropIndex].lineRange.from : state.doc.length;
+  // Dropping inside the item's own subtree (including immediately after its own line) is a no-op.
+  if (insertAt > from && insertAt <= to) {
+    return;
+  }
+
+  const sourceIndent = indentAt(state, from);
+  // The drop level resolved live during the drag (`getDropIndent`), else the drop-target's own indent.
+  const targetIndent = indent ?? (dropIndex < count ? indentAt(state, items[dropIndex].lineRange.from) : 0);
+  const text = reindent(state.doc.sliceString(from, to), sourceIndent, targetIndent);
+
+  // Remove the subtree together with one adjacent newline so no blank line is orphaned.
+  const hasFollowing = to < state.doc.length;
+  const deleteFrom = hasFollowing ? from : Math.max(0, from - 1);
+  const deleteTo = hasFollowing ? Math.min(to + 1, state.doc.length) : to;
+  const insert = dropIndex < count ? `${text}\n` : `\n${text}`;
+
+  // Sort the two changes by position (CodeMirror requires ascending, non-overlapping specs).
+  const changes =
+    insertAt <= deleteFrom
+      ? [
+          { from: insertAt, insert },
+          { from: deleteFrom, to: deleteTo },
+        ]
+      : [
+          { from: deleteFrom, to: deleteTo },
+          { from: insertAt, insert },
+        ];
+
+  // Caret at the end of the moved item; keep the moved item selected (its new anchor is where the moved
+  // text starts — the subtree's first line).
+  const changeSet = state.changes(changes);
+  const textStart = changeSet.mapPos(insertAt, -1) + (dropIndex < count ? 0 : 1);
+  const caret = textStart + text.length;
+  view.dispatch({
+    changes,
+    selection: { anchor: Math.min(caret, changeSet.newLength) },
+    effects: setBlockSelection.of([textStart]),
+    userEvent: 'move.item',
+  });
+};
+
+// Merges sorted ranges, combining any that overlap or touch. Exported for the menu commands.
+export const mergeRanges = (ranges: { from: number; to: number }[]): { from: number; to: number }[] => {
+  const sorted = [...ranges].sort((a, b) => a.from - b.from);
+  const merged: { from: number; to: number }[] = [];
+  for (const range of sorted) {
+    const last = merged.at(-1);
+    if (last && range.from <= last.to) {
+      last.to = Math.max(last.to, range.to);
+    } else {
+      merged.push({ ...range });
+    }
+  }
+  return merged;
+};
+
+// Delete ranges for the given items: each item's own lines plus its separating newline (the one below,
+// down to the next item; for the last item the one above instead, so no trailing blank is orphaned),
+// merged so adjacent selections form one range.
+const deleteRanges = (state: EditorState, blocks: Block[], indices: number[]): { from: number; to: number }[] => {
+  const count = blocks.length;
+  return mergeRanges(
+    indices.map((index) => ({
+      from: index === count - 1 && index > 0 ? blocks[index - 1].to : blocks[index].from,
+      to: index + 1 < count ? blocks[index + 1].from : state.doc.length,
+    })),
+  );
+};
+
+/**
+ * Moves the items at `sourceIndices` to the slot before `dropIndex`. A single item moves with its whole
+ * subtree (re-indented — see `moveItem`); multiple items move by their own lines as a group (a
+ * best-effort for multi-selection reorder).
+ */
+// Exported for tests (the drag path calls this via `outlinerBlockOps`).
+export const moveBlocks = (view: EditorView, sourceIndices: number[], dropIndex: number, indent?: number): void => {
+  const { state } = view;
+  const items = flattenItems(state);
+  const count = items.length;
+  const sources = [...new Set(sourceIndices)].filter((index) => index >= 0 && index < count).sort((a, b) => a - b);
+  if (sources.length === 0 || sources.includes(dropIndex)) {
+    return;
+  }
+  if (sources.length === 1) {
+    // Single-item drags re-root the whole subtree to the drag's resolved drop level (`getDropIndent`).
+    moveItem(view, sources[0], dropIndex, indent);
+    return;
+  }
+
+  const blocks = getBlocks(state);
+  const text = sources.map((index) => state.doc.sliceString(blocks[index].from, blocks[index].to)).join('\n');
+  const deletes = deleteRanges(state, blocks, sources);
+  const insertAt = dropIndex < count ? blocks[dropIndex].from : state.doc.length;
+  if (deletes.some((range) => insertAt > range.from && insertAt < range.to)) {
+    return;
+  }
+
+  const insert = dropIndex < count ? `${text}\n` : `\n${text}`;
+  const changes = [...deletes.map((range) => ({ from: range.from, to: range.to })), { from: insertAt, insert }];
+  const changeSet = state.changes(changes);
+  const textStart = changeSet.mapPos(insertAt, -1) + (dropIndex < count ? 0 : 1);
+  // Keep the moved items selected: their new anchors are the start of each item within the inserted
+  // text, joined by a single newline (item length + 1). The caret lands at the end of the moved content.
+  const anchors: number[] = [];
+  let anchor = textStart;
+  for (const index of sources) {
+    anchors.push(anchor);
+    anchor += blocks[index].to - blocks[index].from + 1;
+  }
+  const caret = textStart + text.length;
+  view.dispatch({
+    changes,
+    selection: { anchor: Math.min(caret, changeSet.newLength) },
+    effects: setBlockSelection.of(anchors),
+    userEvent: 'move.item',
+  });
+};
+
+/** Removes the items at `indices`, optionally replacing the first slot with `text` (paste). */
+// Exported for tests (the drag/clipboard path calls this via `outlinerBlockOps`).
+export const replaceBlocks = (view: EditorView, indices: number[], text: string | null): void => {
+  const { state } = view;
+  const blocks = getBlocks(state);
+  const count = blocks.length;
+  const sources = [...new Set(indices)].filter((index) => index >= 0 && index < count).sort((a, b) => a - b);
+  if (sources.length === 0) {
+    return;
+  }
+
+  const deletes = deleteRanges(state, blocks, sources);
+  const changes = deletes.map(
+    (range) => ({ from: range.from, to: range.to }) as { from: number; to: number; insert?: string },
+  );
+  let anchor = deletes[0].from;
+  if (text != null && text.length > 0) {
+    const insert = deletes[0].to >= state.doc.length ? text : `${text}\n`;
+    changes[0] = { from: deletes[0].from, to: deletes[0].to, insert };
+    anchor = deletes[0].from + text.length;
+  }
+
+  view.dispatch({
+    changes,
+    selection: { anchor: Math.min(anchor, state.doc.length) },
+    effects: setBlockSelection.of([]),
+    userEvent: text == null ? 'delete.block' : 'input.paste',
+  });
+};
+
+const outlinerBlockOps: BlockOps = {
+  getBlocks,
+  moveBlocks,
+  serialize: (state, selected) => selected.map((block) => state.doc.sliceString(block.from, block.to)).join('\n'),
+  replaceBlocks,
+};
+
+/**
+ * Block selection, drag-to-reorder, and cut/copy/paste for outliner items. Single-item drag relocates
+ * the whole subtree (re-indented); the generic block-selection and clipboard from the `blocks` extensions
+ * operate on item lines. The grip is a floating overlay pinned to the content's left edge (see
+ * `createBlockDrag`), so it needs no outliner-specific gutter styling.
+ */
+export const outlinerDnd = (): Extension => [
+  // The selection highlight is drawn by `outliner.ts` as a line decoration (aligned to the actual rows);
+  // the `blocks` RectangleMarker layer is skipped here because it drifts against the outliner's row CSS.
+  createBlockSelection(outlinerBlockOps),
+  createBlockDrag({ getBlocks, moveBlocks, getExtent, keepTrailingBreak: true, getDropIndent }),
+];
+
+//
+// Selection commands over the block selection (each item's line-start anchor). Replaces the outliner's
+// former `selectionFacet`, so keyboard selection and the grip share one model.
+//
+
+const itemAnchors = (state: EditorState): number[] => flattenItems(state).map((item) => item.lineRange.from);
+
+/** Select every item; pressing again (when all are selected) clears the selection. */
+export const selectAllItems: Command = (view) => {
+  const anchors = itemAnchors(view.state);
+  const current = view.state.field(blockSelectionField, false) ?? [];
+  view.dispatch({ effects: setBlockSelection.of(current.length === anchors.length ? [] : anchors) });
+  return true;
+};
+
+/** Clear the block selection. */
+export const selectNoneItems: Command = (view) => {
+  view.dispatch({ effects: setBlockSelection.of([]) });
+  return true;
+};
+
+// Extend the block selection by one item toward `delta`, moving the caret into the target item.
+const extendSelection = (view: EditorView, delta: -1 | 1): boolean => {
+  const items = flattenItems(view.state);
+  const caret = view.state.selection.main.head;
+  const index = items.findIndex((item) => caret >= item.lineRange.from && caret <= item.lineRange.to);
+  if (index < 0) {
+    return false;
+  }
+  const target = Math.min(items.length - 1, Math.max(0, index + delta));
+  const anchors = new Set(view.state.field(blockSelectionField, false) ?? []);
+  anchors.add(items[index].lineRange.from);
+  anchors.add(items[target].lineRange.from);
+  view.dispatch({
+    selection: { anchor: items[target].contentRange.from },
+    effects: setBlockSelection.of([...anchors].sort((a, b) => a - b)),
+  });
+  return true;
+};
+
+export const selectUp: Command = (view) => extendSelection(view, -1);
+export const selectDown: Command = (view) => extendSelection(view, 1);

package/src/extensions/structure/outliner/editor.test.ts

@@ -0,0 +1,85 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { markdown, markdownLanguage } from '@codemirror/lang-markdown';
+import { type ChangeSpec, EditorSelection, EditorState } from '@codemirror/state';
+import { describe, test } from 'vitest';
+
+import { editor } from './editor';
+import { outlinerTree, treeFacet } from './tree';
+
+const extensions = [markdown({ base: markdownLanguage }), outlinerTree(), editor()];
+
+// Two items: item 1 content [6,7]='A'; line 2 starts at 8, item 2 marker [8,14), content [14,15]='B'.
+const DOC = '- [ ] A\n- [ ] B';
+
+// Resulting caret after moving it to `pos` (the transaction filter snaps out-of-range positions).
+const snap = (doc: string, pos: number): number =>
+  EditorState.create({ doc, extensions }).update({ selection: EditorSelection.cursor(pos) }).state.selection.main.from;
+
+// Resulting caret after moving from `prev` to `next` (the filter uses the delta to pick a direction).
+const snapFrom = (doc: string, prev: number, next: number): number => {
+  const state = EditorState.create({ doc, extensions }).update({ selection: EditorSelection.cursor(prev) }).state;
+  return state.update({ selection: EditorSelection.cursor(next) }).state.selection.main.from;
+};
+
+// Resulting document after applying `spec` with the caret at `cursor`.
+const applyChange = (doc: string, cursor: number, spec: ChangeSpec): string => {
+  const state = EditorState.create({ doc, extensions }).update({ selection: EditorSelection.cursor(cursor) }).state;
+  return state.update({ changes: spec }).state.doc.toString();
+};
+
+describe('editor', () => {
+  test('an empty document still has a tree', ({ expect }) => {
+    const state = EditorState.create({ extensions });
+    expect(state.facet(treeFacet)).to.exist;
+  });
+
+  describe('selection guard', () => {
+    test('snaps a caret placed inside the marker to the content start', ({ expect }) => {
+      for (const pos of [0, 1, 3, 5]) {
+        expect(snap('- [ ] ', pos)).to.eq(6);
+      }
+      // A caret already at the content start is left alone.
+      expect(snap('- [ ] ', 6)).to.eq(6);
+    });
+
+    test('snaps within a later item too', ({ expect }) => {
+      expect(snap(DOC, 9)).to.eq(14); // Inside item 2's marker.
+      expect(snap(DOC, 10)).to.eq(14);
+      expect(snap(DOC, 14)).to.eq(14); // Content start is valid.
+    });
+
+    test('moving down into an item lands at its content start', ({ expect }) => {
+      expect(snapFrom(DOC, 7, 10)).to.eq(14);
+    });
+
+    test('moving up into an item lands at its content end', ({ expect }) => {
+      expect(snapFrom(DOC, 14, 4)).to.eq(7);
+    });
+
+    test('moving left across the marker goes to the previous line end', ({ expect }) => {
+      expect(snapFrom(DOC, 14, 13)).to.eq(7);
+    });
+  });
+
+  describe('change validation', () => {
+    test('allows deleting a whole item line', ({ expect }) => {
+      expect(applyChange(DOC, 0, { from: 0, to: 8 })).to.eq('- [ ] B');
+    });
+
+    test('allows typing into the content', ({ expect }) => {
+      expect(applyChange('- [ ] ', 6, { from: 6, to: 6, insert: 'X' })).to.eq('- [ ] X');
+    });
+
+    test('allows editing within the content', ({ expect }) => {
+      expect(applyChange('- [ ] A', 7, { from: 6, to: 7 })).to.eq('- [ ] ');
+    });
+  });
+
+  // Task-marker atomicity (backspace on `- [ ] ` removing the whole marker, or inserting a continuation
+  // indent) is enforced by the markdown extension's keymap, which produces the specific change shapes the
+  // filter reacts to — not by raw `changes`. Covering it needs the full keymap dispatched through a view.
+  test.todo('task-marker atomicity (needs the markdown keymap, not a raw change)');
+});

package/src/extensions/{outliner → structure/outliner}/editor.ts

@@ -7,7 +7,6 @@ import { type EditorView, ViewPlugin } from '@codemirror/view';
 
 import { log } from '@dxos/log';
 
-import { getSelection } from './selection';
 import { treeFacet } from './tree';
 
 const LIST_ITEM_REGEX = /^\s*- (\[ \]|\[x\])? /;
@@ -18,12 +17,17 @@ const LIST_ITEM_REGEX = /^\s*- (\[ \]|\[x\])? /;
 const initialize = () => {
   return ViewPlugin.fromClass(
     class {
+      #timer: ReturnType<typeof setTimeout> | null = null;
+
       constructor(view: EditorView) {
         const first = view.state.doc.lineAt(0);
         const text = view.state.sliceDoc(first.from, first.to);
         const match = text.match(LIST_ITEM_REGEX);
         if (!match) {
-          setTimeout(() => {
+          // Deferred so the dispatch runs after the view finishes constructing; cleared on destroy so it
+          // never fires on a torn-down view.
+          this.#timer = setTimeout(() => {
+            this.#timer = null;
             const insert = '- [ ] ';
             view.dispatch({
               changes: [{ from: 0, to: 0, insert }],
@@ -32,6 +36,12 @@ const initialize = () => {
           });
         }
       }
+
+      destroy() {
+        if (this.#timer != null) {
+          clearTimeout(this.#timer);
+        }
+      }
     },
   );
 };
@@ -49,7 +59,7 @@ export const editor = () => [
     // Check cursor is in a valid position.
     //
     if (!tr.docChanged) {
-      const current = getSelection(tr.state).from;
+      const current = tr.state.selection.main.from;
       if (current != null) {
         const currentItem = tree.find(current);
         if (!currentItem) {
@@ -58,7 +68,7 @@ export const editor = () => [
 
         // Check if outside of editable range.
         if (current < currentItem.contentRange.from || current > currentItem.contentRange.to) {
-          const prev = getSelection(tr.startState).from;
+          const prev = tr.startState.selection.main.from;
           const prevItem = prev != null ? tree.find(prev) : undefined;
           if (!prevItem) {
             return [{ selection: EditorSelection.cursor(currentItem.contentRange.from) }];
@@ -110,11 +120,6 @@ export const editor = () => [
           return;
         }
 
-        // if (!deleteLine && (!startItem || fromA < startItem.contentRange.from || toA > startItem.contentRange.to)) {
-        //   cancel = true;
-        //   return;
-        // }
-
         // Check valid item.
         const currentItem = tree.find(tr.state.selection.main.from);
         if (!currentItem?.contentRange) {

package/src/extensions/{outliner → structure/outliner}/index.ts

@@ -3,5 +3,6 @@
 //
 
 export * from './commands';
+export * from './dnd';
 export * from './outliner';
 export * from './tree';

package/src/extensions/{outliner → structure/outliner}/menu.ts

@@ -6,6 +6,13 @@ import { type Extension } from '@codemirror/state';
 import { EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
 
 import { type CleanupFn, addEventListener } from '@dxos/async';
+import { Domino } from '@dxos/ui';
+
+import { GUTTER_WIDTH } from '../blocks';
+
+// Square trigger size (px), matching the drag grip (`dx-button` density `xs` + `aspect-square` → `size-6`).
+// The right-hand strip (`GUTTER_WIDTH`, shared with the grip's left strip) centers the trigger within it.
+const TRIGGER_SIZE = 24;
 
 export type MenuOptions = {
   icon?: string;
@@ -13,6 +20,7 @@ export type MenuOptions = {
   padding?: number;
 };
 
+/** Floating action button positioned beside the active outliner line. */
 // TODO(burdon): Replace with popover.
 export const menu = (options: MenuOptions = {}): Extension => [
   ViewPlugin.fromClass(
@@ -31,14 +39,16 @@ export const menu = (options: MenuOptions = {}): Extension => [
           container.style.position = 'relative';
         }
 
-        {
-          const icon = document.createElement('dx-icon');
-          icon.setAttribute('icon', options.icon ?? 'ph--dots-three-vertical--regular');
-
-          this.tag = document.createElement('dx-anchor');
-          this.tag.classList.add('cm-popover-trigger');
-          this.tag.appendChild(icon);
-        }
+        // Outer `dx-anchor` (fires `dx-anchor-activate`, driving the popover) styled as a `dx-button`;
+        // inner element holds the phosphor glyph. Mirrors the drag grip's construction.
+        this.tag = Domino.of('dx-anchor')
+          .classNames('dx-button aspect-square cm-popover-trigger')
+          .attributes({ 'data-variant': 'ghost', 'data-density': 'xs' })
+          .append(
+            Domino.of('div')
+              .classNames('cm-popover-trigger-icon')
+              .append(Domino.svg(options.icon ?? 'ph--dots-three-vertical--regular')),
+          ).root;
 
         container.appendChild(this.tag);
 
@@ -86,14 +96,18 @@ export const menu = (options: MenuOptions = {}): Extension => [
         const line = this.view.lineBlockAt(pos);
         const coords = this.view.coordsAtPos(line.from);
         if (!coords) {
+          // No resolvable line (e.g. the caret's item was just deleted): hide rather than leave the
+          // trigger stranded at its previous position.
+          this.tag.style.display = 'none';
           return;
         }
 
         const lineHeight = coords.bottom - coords.top;
-        const dy = (lineHeight - (options.height ?? 32)) / 2;
+        const dy = (lineHeight - (options.height ?? TRIGGER_SIZE)) / 2;
 
         const offsetTop = coords.top + dy;
-        const offsetLeft = x + width + (options.padding ?? 8);
+        // Center the trigger within the 3rem gutter immediately right of the content (mirrors the grip).
+        const offsetLeft = x + width + GUTTER_WIDTH / 2 - TRIGGER_SIZE / 2;
 
         this.tag.style.top = `${offsetTop}px`;
         this.tag.style.left = `${offsetLeft}px`;
@@ -110,19 +124,28 @@ export const menu = (options: MenuOptions = {}): Extension => [
     },
   ),
 
-  EditorView.theme({
-    '.cm-popover-trigger': {
-      position: 'fixed',
-      padding: '0',
-      border: 'none',
-      opacity: '0',
-      display: 'grid',
-      placeContent: 'center',
-      width: '2rem',
-      height: '2rem',
-    },
-    '&:focus-within .cm-popover-trigger': {
-      opacity: '1',
-    },
-  }),
+  styles,
 ];
+
+const styles = EditorView.theme({
+  // `dx-button` owns the box (size, hover); this only pins it and gates visibility on editor focus.
+  '.cm-popover-trigger': {
+    position: 'fixed',
+    opacity: '0',
+    cursor: 'pointer',
+  },
+  '.cm-popover-trigger-icon': {
+    display: 'grid',
+    placeContent: 'center',
+    fontSize: '16px',
+    color: 'var(--color-description, currentColor)',
+  },
+  '&:focus-within .cm-popover-trigger': {
+    opacity: '1',
+  },
+  // Hide the trigger while a block drag is in flight (the scroller carries `cm-blockDragging`).
+  '.cm-scroller.cm-blockDragging .cm-popover-trigger': {
+    opacity: '0 !important',
+    pointerEvents: 'none',
+  },
+});