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

package/src/extensions/structure/blocks/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './blocks';
+export * from './drag';
+export * from './selection';
+export * from './types';

package/src/extensions/structure/blocks/selection.test.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { markdown, markdownLanguage } from '@codemirror/lang-markdown';
+import { EditorState } from '@codemirror/state';
+import { describe, test } from 'vitest';
+
+import { findBlocks } from './blocks';
+import { blockSelectionField, getSelectedBlocks, setBlockSelection, toggleBlockSelection } from './selection';
+
+const extensions = [markdown({ base: markdownLanguage }), blockSelectionField];
+const create = (doc: string) => EditorState.create({ doc, extensions });
+
+describe('blockSelectionField', () => {
+  test('set replaces and toggle adds/removes, kept sorted', ({ expect }) => {
+    let state = create('A\n\nB\n\nC'); // anchors: A@0, B@3, C@6
+    state = state.update({ effects: setBlockSelection.of([6, 0]) }).state;
+    expect([...state.field(blockSelectionField)]).to.deep.eq([0, 6]);
+    state = state.update({ effects: toggleBlockSelection.of(0) }).state;
+    expect([...state.field(blockSelectionField)]).to.deep.eq([6]);
+    state = state.update({ effects: toggleBlockSelection.of(3) }).state;
+    expect([...state.field(blockSelectionField)]).to.deep.eq([3, 6]);
+  });
+
+  test('anchors map through edits', ({ expect }) => {
+    let state = create('A\n\nB\n\nC');
+    state = state.update({ effects: setBlockSelection.of([3, 6]) }).state;
+    // Insert two characters at the start; anchors shift by two.
+    state = state.update({ changes: { from: 0, insert: 'XY' } }).state;
+    expect([...state.field(blockSelectionField)]).to.deep.eq([5, 8]);
+  });
+
+  test('a caret move keeps the selection (extendable via keyboard)', ({ expect }) => {
+    let state = create('A\n\nB');
+    state = state.update({ effects: setBlockSelection.of([0]) }).state;
+    state = state.update({ selection: { anchor: 3 } }).state;
+    expect([...state.field(blockSelectionField)]).to.deep.eq([0]);
+  });
+
+  test('getSelectedBlocks resolves anchors to blocks in order', ({ expect }) => {
+    let state = create('A\n\nB\n\nC');
+    state = state.update({ effects: setBlockSelection.of([6, 3]) }).state;
+    const selected = getSelectedBlocks(state, findBlocks);
+    expect(selected.map((entry) => entry.index)).to.deep.eq([1, 2]);
+    expect(state.doc.sliceString(selected[0].block.from, selected[0].block.to)).to.eq('B');
+  });
+
+  test('getSelectedBlocks drops stale anchors', ({ expect }) => {
+    let state = create('A\n\nB\n\nC');
+    // Anchor 4 is not a block start.
+    state = state.update({ effects: setBlockSelection.of([0, 4]) }).state;
+    const selected = getSelectedBlocks(state, findBlocks);
+    expect(selected.map((entry) => entry.index)).to.deep.eq([0]);
+  });
+});

package/src/extensions/structure/blocks/selection.ts

@@ -0,0 +1,279 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorState, type Extension, Prec, StateEffect, StateField } from '@codemirror/state';
+import { EditorView, RectangleMarker, keymap, layer } from '@codemirror/view';
+
+import { type Block, type BlockExtent } from './types';
+
+// Amount (px) the highlight extends left of the content, matching the outline boxes and drag preview.
+const BOX_INSET_X = 8;
+const BOX_PADDING = 2;
+
+/**
+ * Operations a document supplies so whole blocks can be selected, reordered, and cut/copy/pasted. The
+ * same contract backs markdown top-level blocks and outliner items — nothing here is markdown-specific.
+ */
+export type BlockOps = {
+  /** Blocks in document order; ranges non-overlapping. Should be memoized per state. */
+  getBlocks: (state: EditorState) => Block[];
+  /**
+   * Moves the blocks at `sourceIndices` to the slot before `dropIndex` (the end when
+   * `dropIndex === blocks.length`), preserving their relative order, as a single edit.
+   */
+  moveBlocks: (view: EditorView, sourceIndices: number[], dropIndex: number) => void;
+  /** Serializes blocks to clipboard text (markdown joins with a blank line; the outliner with newlines). */
+  serialize: (state: EditorState, blocks: Block[]) => string;
+  /**
+   * Removes the blocks at `indices` and, when `text` is non-null, inserts it as block(s) at the first
+   * removed slot — as a single edit. `text === null` is a pure delete (cut); non-null is a replace (paste).
+   */
+  replaceBlocks: (view: EditorView, indices: number[], text: string | null) => void;
+};
+
+//
+// State: the block selection is an ordered set of block anchors (each block's `from`), kept sorted.
+// Positions — not indices — so the set survives edits (mapped through changes).
+//
+
+/** Replaces the whole block selection. */
+export const setBlockSelection = StateEffect.define<readonly number[]>();
+
+/** Adds/removes a single block anchor, keeping the rest. */
+export const toggleBlockSelection = StateEffect.define<number>();
+
+const hasSelectionEffect = (effects: readonly StateEffect<any>[]): boolean =>
+  effects.some((effect) => effect.is(setBlockSelection) || effect.is(toggleBlockSelection));
+
+export const blockSelectionField = StateField.define<readonly number[]>({
+  create: () => [],
+  update: (value, tr) => {
+    // Our own effects take precedence and are the only way to grow the selection.
+    if (hasSelectionEffect(tr.effects)) {
+      let next = value;
+      for (const effect of tr.effects) {
+        if (effect.is(setBlockSelection)) {
+          next = [...effect.value].sort((a, b) => a - b);
+        } else if (effect.is(toggleBlockSelection)) {
+          const set = new Set(next);
+          set.has(effect.value) ? set.delete(effect.value) : set.add(effect.value);
+          next = [...set].sort((a, b) => a - b);
+        }
+      }
+      return next;
+    }
+
+    if (value.length === 0) {
+      return value;
+    }
+
+    // Keep anchors aligned through edits (a consumer re-resolves them against `getBlocks`). Caret moves
+    // (keyboard nav) keep the selection so it can be extended; a plain text click clears it (see below).
+    if (tr.docChanged) {
+      return value.map((pos) => tr.changes.mapPos(pos, -1));
+    }
+
+    return value;
+  },
+});
+
+/** Resolves the selection anchors to `{ block, index }` in document order, dropping stale anchors. */
+export const getSelectedBlocks = (
+  state: EditorState,
+  getBlocks: BlockOps['getBlocks'],
+): { block: Block; index: number }[] => {
+  const anchors = state.field(blockSelectionField, false);
+  if (!anchors || anchors.length === 0) {
+    return [];
+  }
+  const byFrom = new Map(getBlocks(state).map((block, index) => [block.from, { block, index }]));
+  const result: { block: Block; index: number }[] = [];
+  for (const anchor of anchors) {
+    const match = byFrom.get(anchor);
+    if (match) {
+      result.push(match);
+    }
+  }
+  return result;
+};
+
+//
+// Highlight (layer): a full-width tinted box behind each selected block, aligned with the outline boxes.
+//
+
+const buildSelectionMarkers = (
+  view: EditorView,
+  getBlocks: BlockOps['getBlocks'],
+  getExtent?: BlockExtent,
+): RectangleMarker[] => {
+  const selected = getSelectedBlocks(view.state, getBlocks);
+  if (selected.length === 0) {
+    return [];
+  }
+
+  const contentRect = view.contentDOM.getBoundingClientRect();
+  const gutterOffset = contentRect.left - view.scrollDOM.getBoundingClientRect().left;
+  const markers: RectangleMarker[] = [];
+  for (const { block } of selected) {
+    // The extent is the range the block visually occupies (its subtree for the outliner).
+    const extent = getExtent ? getExtent(view.state, block) : block;
+    const from = Math.max(extent.from, view.viewport.from);
+    const to = Math.min(extent.to, view.viewport.to);
+    if (from > to) {
+      continue;
+    }
+    const firstLine = view.lineBlockAt(from);
+    const lastLine = view.lineBlockAt(to);
+    markers.push(
+      new RectangleMarker(
+        'cm-blockSelected',
+        gutterOffset - BOX_INSET_X,
+        firstLine.top - BOX_PADDING,
+        contentRect.width + BOX_INSET_X,
+        lastLine.bottom - firstLine.top + BOX_PADDING * 2,
+      ),
+    );
+  }
+  return markers;
+};
+
+const selectionChanged = (a: EditorState, b: EditorState): boolean =>
+  a.field(blockSelectionField, false) !== b.field(blockSelectionField, false);
+
+const selectionTheme = EditorView.theme({
+  '.cm-blockSelectedLayer': {
+    pointerEvents: 'none',
+  },
+  '.cm-blockSelected': {
+    boxSizing: 'border-box',
+    backgroundColor: 'var(--color-cm-highlight-surface)',
+  },
+});
+
+//
+// Clipboard: cut/copy/paste act on the block selection; when it is empty they fall through to native
+// text behavior. Mod-C/X/V route through these same DOM events, so no separate keymap is needed.
+//
+
+const clipboardHandlers = (ops: BlockOps): Extension =>
+  EditorView.domEventHandlers({
+    copy: (event, view) => {
+      const selected = getSelectedBlocks(view.state, ops.getBlocks);
+      if (selected.length === 0) {
+        return false;
+      }
+      event.clipboardData?.setData(
+        'text/plain',
+        ops.serialize(
+          view.state,
+          selected.map((entry) => entry.block),
+        ),
+      );
+      event.preventDefault();
+      return true;
+    },
+    cut: (event, view) => {
+      const selected = getSelectedBlocks(view.state, ops.getBlocks);
+      if (selected.length === 0) {
+        return false;
+      }
+      event.clipboardData?.setData(
+        'text/plain',
+        ops.serialize(
+          view.state,
+          selected.map((entry) => entry.block),
+        ),
+      );
+      event.preventDefault();
+      // `replaceBlocks` clears the block selection within its own transaction.
+      ops.replaceBlocks(
+        view,
+        selected.map((entry) => entry.index),
+        null,
+      );
+      return true;
+    },
+    paste: (event, view) => {
+      const selected = getSelectedBlocks(view.state, ops.getBlocks);
+      if (selected.length === 0) {
+        return false;
+      }
+      const text = event.clipboardData?.getData('text/plain') ?? '';
+      event.preventDefault();
+      // Replace the selected blocks with the pasted text (`replaceBlocks` clears the block selection).
+      ops.replaceBlocks(
+        view,
+        selected.map((entry) => entry.index),
+        text,
+      );
+      return true;
+    },
+  });
+
+// A plain press in the text clears the block selection (handle presses go through the gutter and don't
+// hit `.cm-content`; shift-presses are left to extend the block selection via the gutter).
+const clearOnTextPress = EditorView.domEventHandlers({
+  mousedown: (event, view) => {
+    if (event.shiftKey) {
+      return false;
+    }
+    const target = event.target;
+    const anchors = view.state.field(blockSelectionField, false);
+    if (anchors && anchors.length > 0 && target instanceof Node && view.contentDOM.contains(target)) {
+      view.dispatch({ effects: setBlockSelection.of([]) });
+    }
+    return false;
+  },
+});
+
+// Escape clears the block selection. High precedence so it wins over other Escape bindings while a
+// selection is active, but falls through (returns false) when there is nothing selected.
+const clearOnEscape = Prec.high(
+  keymap.of([
+    {
+      key: 'Escape',
+      run: (view) => {
+        const anchors = view.state.field(blockSelectionField, false);
+        if (!anchors || anchors.length === 0) {
+          return false;
+        }
+        view.dispatch({ effects: setBlockSelection.of([]) });
+        return true;
+      },
+    },
+  ]),
+);
+
+/**
+ * Draws a border/background box behind each selected block, in a below-text layer re-measured on edits,
+ * scrolling, and viewport changes. Separate from the selection state and clipboard so it can travel with
+ * the drag grip (which populates the selection) independently of `createBlockSelection`. The blocks are
+ * supplied by the caller (see `blockSelectionHighlight` for markdown top-level blocks).
+ */
+export const createBlockSelectionHighlight = (getBlocks: BlockOps['getBlocks'], getExtent?: BlockExtent): Extension => [
+  blockSelectionField,
+  selectionTheme,
+  layer({
+    above: false,
+    class: 'cm-blockSelectedLayer',
+    update: (update) =>
+      update.docChanged ||
+      update.viewportChanged ||
+      update.geometryChanged ||
+      selectionChanged(update.startState, update.state),
+    markers: (view) => buildSelectionMarkers(view, getBlocks, getExtent),
+  }),
+];
+
+/**
+ * Whole-block selection state and cut/copy/paste over the selected blocks. The border/background behind
+ * the selection is drawn by `createBlockSelectionHighlight`, and the gutter grip gestures that populate
+ * the selection live in `createBlockDrag` (the handle is a gutter marker) — compose all three together.
+ */
+export const createBlockSelection = (ops: BlockOps): Extension => [
+  blockSelectionField,
+  clipboardHandlers(ops),
+  clearOnTextPress,
+  clearOnEscape,
+];

package/src/extensions/structure/blocks/types.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorState } from '@codemirror/state';
+
+/**
+ * A contiguous document region that can be selected, dragged, and reordered as a unit. Lives in its own
+ * module so `drag.ts` and `selection.ts` can share it without importing from each other (a cycle that
+ * makes the dev bundler instantiate the shared state field twice).
+ */
+export type Block = {
+  from: number;
+  to: number;
+};
+
+/**
+ * Maps a block to the document range it visually occupies for the selection highlight and drag
+ * (collapse/preview/placeholder). Defaults to the block's own range; a hierarchical consumer (the
+ * outliner) returns the block's whole subtree so selecting/dragging a parent covers its descendants.
+ */
+export type BlockExtent = (state: EditorState, block: Block) => Block;

package/src/extensions/{folding.ts → structure/folding/folding.ts}

@@ -32,15 +32,17 @@ export const folding = (): Extension => {
           ).root;
       },
     }),
-    EditorView.theme({
-      '.cm-foldGutter': {
-        opacity: 0.3,
-        transition: 'opacity 0.3s',
-        width: '32px',
-      },
-      '.cm-foldGutter:hover': {
-        opacity: 1,
-      },
-    }),
+    styles,
   ];
 };
+
+const styles = EditorView.theme({
+  '.cm-foldGutter': {
+    opacity: 0.3,
+    transition: 'opacity 0.3s',
+    width: '32px',
+  },
+  '.cm-foldGutter:hover': {
+    opacity: 1,
+  },
+});

package/src/extensions/structure/folding/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './folding';
+export * from './turns';

package/src/extensions/structure/folding/turns.test.ts

@@ -0,0 +1,72 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorState } from '@codemirror/state';
+import { describe, test } from 'vitest';
+
+import { PROMPT_ELEMENT, createTurnSource } from './turns';
+
+describe('createTurnSource', () => {
+  test('folds the response below a prompt', ({ expect }) => {
+    const turns = scan(['<prompt>Hi</prompt>', 'Answer.'].join('\n'));
+    expect(turns).toHaveLength(1);
+    expect(turns[0].head).toBe('<prompt>Hi</prompt>');
+    expect(turns[0].folded).toBe('Answer.');
+  });
+
+  test('anchors the gutter marker on the first line of a multi-line head', ({ expect }) => {
+    const doc = ['<prompt>line one', 'line two</prompt>', 'Answer.'].join('\n');
+    const turns = scan(doc);
+    expect(turns[0].headLine).toBe(0);
+    expect(turns[0].folded).toBe('Answer.');
+  });
+
+  // A toolbar rendered under the prompt belongs to the head: folding the response must not hide the
+  // control that folds it.
+  test('keeps a trailing self-closing toolbar tag out of the fold range', ({ expect }) => {
+    const doc = ['<prompt>Hi</prompt>', '', '<branch messageId="a" created="t" />', 'Answer.'].join('\n');
+    const turns = scan(doc);
+    expect(turns).toHaveLength(1);
+    expect(turns[0].head).toContain('<branch');
+    expect(turns[0].folded).toBe('Answer.');
+    // The marker still sits on the prompt, not on the toolbar.
+    expect(turns[0].headLine).toBe(0);
+  });
+
+  test('absorbs several trailing self-closing tags', ({ expect }) => {
+    const doc = ['<prompt>Hi</prompt>', '<branch messageId="a" />', '<other />', 'Answer.'].join('\n');
+    const turns = scan(doc);
+    expect(turns[0].folded).toBe('Answer.');
+  });
+
+  test('does not absorb a paired tag that opens the response', ({ expect }) => {
+    const doc = ['<prompt>Hi</prompt>', '<reasoning>Thinking</reasoning>', 'Answer.'].join('\n');
+    const turns = scan(doc);
+    expect(turns[0].head).toBe('<prompt>Hi</prompt>');
+    expect(turns[0].folded).toBe(['<reasoning>Thinking</reasoning>', 'Answer.'].join('\n'));
+  });
+
+  test('ends a turn where the next prompt begins, trailing whitespace trimmed', ({ expect }) => {
+    const doc = ['<prompt>One</prompt>', 'First.', '', '<prompt>Two</prompt>', 'Second.', ''].join('\n');
+    const turns = scan(doc);
+    expect(turns).toHaveLength(2);
+    expect(turns[0].folded).toBe('First.');
+    expect(turns[1].folded).toBe('Second.');
+  });
+
+  test('yields no turn for a prompt with an empty response', ({ expect }) => {
+    expect(scan('<prompt>Hi</prompt>')).toHaveLength(0);
+    expect(scan(['<prompt>Hi</prompt>', '<branch messageId="a" />'].join('\n'))).toHaveLength(0);
+  });
+});
+
+/** Resolves each turn into the text it treats as head vs. the text it would hide. */
+const scan = (doc: string) => {
+  const state = EditorState.create({ doc });
+  return createTurnSource(PROMPT_ELEMENT)(state).map((turn) => ({
+    head: state.doc.sliceString(turn.headLineFrom, turn.from).trim(),
+    folded: state.doc.sliceString(turn.from, turn.to).trim(),
+    headLine: state.doc.lineAt(turn.headLineFrom).number - 1,
+  }));
+};

package/src/extensions/structure/folding/turns.ts

@@ -0,0 +1,209 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { codeFolding, foldedRanges, foldEffect, unfoldEffect } from '@codemirror/language';
+import { type EditorState, type Extension, RangeSetBuilder } from '@codemirror/state';
+import { EditorView, GutterMarker, gutter } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+/**
+ * Turn folding.
+ *
+ * Makes each turn's response a foldable region. `codeFolding` (from `@codemirror/language`) hides the
+ * folded ranges and renders the placeholder, but folds are driven **only** by this extension's own
+ * gutter — never through CodeMirror's `foldable()`/`foldGutter`/`foldService`. That matters because
+ * `foldable()` unconditionally falls back to the language's `syntaxFolding` (markdown `foldNodeProp`
+ * — headings, fenced code, …) whenever no fold service matches a line; routing folds through
+ * `foldEffect` on our own ranges instead means only turns from the caller-provided {@link TurnSource}
+ * can ever fold. The section model (scan text, read a tree, derive from a message array) lives with
+ * the host and can change without touching the fold UI.
+ *
+ * Folding starts at the end of a turn's head, so the head (e.g. the user prompt) stays visible while
+ * its response collapses.
+ */
+
+/** A foldable turn response. */
+export type Turn = {
+  /** Fold range start — the end of the head line, so the head stays visible. */
+  from: number;
+  /** Fold range end — the end of the response that follows the head. */
+  to: number;
+  /** Start offset of the head line; the gutter marker anchors here. */
+  headLineFrom: number;
+};
+
+/** Yields the foldable turn ranges for a document. */
+export type TurnSource = (state: EditorState) => Turn[];
+
+export type TurnFoldingOptions = {
+  /** Source of foldable ranges (e.g. scanned from text or derived from the message model). */
+  source: TurnSource;
+};
+
+/** Turn-response folding driven by a custom gutter and TurnSource, bypassing markdown syntax folding. */
+export const turnFolding = ({ source }: TurnFoldingOptions): Extension => {
+  // The gutter's `markers` runs per update; memoize the per-state turn scan.
+  const cache = new WeakMap<EditorState, Turn[]>();
+  const turnsOf = (state: EditorState): Turn[] => {
+    let turns = cache.get(state);
+    if (!turns) {
+      turns = source(state);
+      cache.set(state, turns);
+    }
+    return turns;
+  };
+
+  return [
+    // Hides folded ranges + renders the placeholder; folds are dispatched only by the gutter below.
+    codeFolding({
+      placeholderDOM: () => Domino.of('span').classNames('hidden').root,
+    }),
+    gutter({
+      class: 'cm-turn-gutter',
+      markers: (view) => {
+        const builder = new RangeSetBuilder<GutterMarker>();
+        for (const turn of turnsOf(view.state)) {
+          builder.add(turn.headLineFrom, turn.headLineFrom, new TurnMarker(isFolded(view.state, turn)));
+        }
+        return builder.finish();
+      },
+      // A fold toggle changes neither the doc nor the viewport, so re-measure on our fold effects
+      // to keep the caret direction in sync.
+      lineMarkerChange: (update) =>
+        update.transactions.some((tr) => tr.effects.some((effect) => effect.is(foldEffect) || effect.is(unfoldEffect))),
+      domEventHandlers: {
+        mousedown: (view, line) => {
+          const turn = turnsOf(view.state).find((candidate) => candidate.headLineFrom === line.from);
+          if (!turn) {
+            return false;
+          }
+          const effect = isFolded(view.state, turn) ? unfoldEffect : foldEffect;
+          view.dispatch({ effects: effect.of({ from: turn.from, to: turn.to }) });
+          return true;
+        },
+      },
+    }),
+    styles,
+  ];
+};
+
+/** Whether `turn`'s range is currently folded. */
+const isFolded = (state: EditorState, turn: Turn): boolean => {
+  let folded = false;
+  foldedRanges(state).between(turn.from, turn.to, (from, to) => {
+    if (from <= turn.from && to >= turn.to) {
+      folded = true;
+    }
+  });
+  return folded;
+};
+
+/** Folds every turn from `source` (used for a host "collapse all"). Folds only turns, never syntax. */
+export const foldTurns = (view: EditorView, source: TurnSource): void => {
+  const effects = source(view.state)
+    .filter((turn) => turn.to > turn.from)
+    .map((turn) => foldEffect.of({ from: turn.from, to: turn.to }));
+  if (effects.length > 0) {
+    view.dispatch({ effects });
+  }
+};
+
+/** Unfolds every turn from `source` (used for a host "expand all"). */
+export const unfoldTurns = (view: EditorView, source: TurnSource): void => {
+  const effects = source(view.state).map((turn) => unfoldEffect.of({ from: turn.from, to: turn.to }));
+  if (effects.length > 0) {
+    view.dispatch({ effects });
+  }
+};
+
+/** Gutter marker for a turn head: a caret whose direction reflects the fold state. */
+class TurnMarker extends GutterMarker {
+  #folded: boolean;
+
+  constructor(folded: boolean) {
+    super();
+    this.#folded = folded;
+  }
+
+  override eq(other: TurnMarker): boolean {
+    return this.#folded === other.#folded;
+  }
+
+  override toDOM(): HTMLElement {
+    return Domino.of('div')
+      .classNames('flex h-full items-center justify-center cursor-pointer')
+      .append(
+        Domino.of('svg', Domino.SVG)
+          .classNames('w-4 h-4')
+          .append(
+            Domino.of('use', Domino.SVG).attributes({
+              href: Domino.icon(this.#folded ? 'ph--caret-right--regular' : 'ph--caret-down--regular'),
+            }),
+          ),
+      ).root;
+  }
+}
+
+/**
+ * Default head element: a `<prompt>…</prompt>` element (content is escaped, so it never nests),
+ * plus any run of self-closing tags immediately following it.
+ *
+ * Those trailing tags are per-turn affordances belonging to the head — a toolbar rendered under the
+ * prompt, say — so they must stay visible when the response folds. Absorbing them into the head also
+ * keeps the fold starting below them, rather than swallowing the toolbar that triggers the fold.
+ */
+export const PROMPT_ELEMENT = /<prompt\b[^>]*>[\s\S]*?<\/prompt>(?:\s*<[a-zA-Z][\w-]*\b[^>]*\/>)*/g;
+
+/**
+ * Builds a {@link TurnSource} that scans the document for head elements matching `element`, folding
+ * the response after each — from the end of that head's line up to the next head (or the end of the
+ * document), trailing whitespace trimmed. `element` selects the turn head (e.g. {@link PROMPT_ELEMENT}
+ * for `<prompt>`); pass another pattern to key turns off a different tag.
+ */
+export const createTurnSource = (element: RegExp): TurnSource => {
+  // Clone with the global flag so `exec` iterates (and never shares `lastIndex` with the caller).
+  const pattern = new RegExp(element.source, element.flags.includes('g') ? element.flags : `${element.flags}g`);
+  return (state) => {
+    const doc = state.doc;
+    const text = doc.toString();
+    const heads: number[] = [];
+    let match: RegExpExecArray | null;
+    pattern.lastIndex = 0;
+    while ((match = pattern.exec(text)) !== null) {
+      heads.push(match.index, match.index + match[0].length);
+    }
+
+    const turns: Turn[] = [];
+    for (let index = 0; index < heads.length; index += 2) {
+      const headStart = heads[index];
+      const headEnd = heads[index + 1];
+      // Fold starts after the head's last line (so the whole head stays visible), but the gutter
+      // marker anchors to the head's first line so the toggle sits at the top of a multi-line head.
+      const from = doc.lineAt(headEnd).to;
+      const headLineFrom = doc.lineAt(headStart).from;
+      const nextHeadStart = index + 2 < heads.length ? heads[index + 2] : doc.length;
+      let to = nextHeadStart;
+      while (to > from && /\s/.test(text[to - 1])) {
+        to--;
+      }
+      if (to > from) {
+        turns.push({ from, to, headLineFrom });
+      }
+    }
+    return turns;
+  };
+};
+
+const styles = EditorView.theme({
+  '.cm-turn-gutter': {
+    width: '1.5rem',
+    color: 'var(--dx-description, currentColor)',
+    opacity: '0.4',
+    transition: 'opacity 0.2s',
+  },
+  '.cm-turn-gutter:hover': {
+    opacity: '1',
+  },
+});