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

package/src/extensions/review/track-changes.test.ts

@@ -0,0 +1,101 @@
+//
+// Copyright 2026 DXOS.org
+//
+// @vitest-environment happy-dom
+
+import { history, undo } from '@codemirror/commands';
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { describe, test } from 'vitest';
+
+import { computeCharHunks } from './diff';
+import { trackChanges } from './track-changes';
+
+const MAIN = 'alpha\nbravo\ncharlie';
+
+const mount = (doc: string, extensions = [trackChanges({ main: MAIN, colour: 'var(--dx-accent)' })]) =>
+  new EditorView({ state: EditorState.create({ doc, extensions }), parent: document.body });
+
+describe('trackChanges', () => {
+  test('a multi-line (block) deletion renders a single phantom preserving the removed lines', ({ expect }) => {
+    // The branch removed the middle line "bravo\n"; the phantom must show it (with its newline), not
+    // collapse the block away.
+    const view = mount('alpha\ncharlie');
+    const phantoms = view.dom.querySelectorAll('.cm-track-delete');
+    expect(phantoms).toHaveLength(1);
+    // textContent carries the removed block including its line break (pre-wrap renders the break).
+    expect(phantoms[0].textContent).toBe('bravo\n');
+    view.destroy();
+  });
+
+  test('undo re-instates a deletion (un-delete) and clears the phantom', ({ expect }) => {
+    const view = mount(MAIN, [history(), trackChanges({ main: MAIN, colour: 'var(--dx-accent)' })]);
+    // Delete the "bravo\n" block on the branch → a phantom appears.
+    view.dispatch({ changes: { from: 6, to: 12, insert: '' } });
+    expect(view.dom.querySelector('.cm-track-delete')).not.toBeNull();
+    expect(view.state.doc.toString()).toBe('alpha\ncharlie');
+
+    // Native undo restores the deleted text (the deletion is an ordinary branch edit) and the phantom
+    // disappears.
+    undo(view);
+    expect(view.state.doc.toString()).toBe(MAIN);
+    expect(view.dom.querySelector('.cm-track-delete')).toBeNull();
+    view.destroy();
+  });
+
+  test('a changed line renders a gutter change-bar in the author colour', ({ expect }) => {
+    // Branch inserts " extra" on the first line → that line gets a change-bar; an unchanged line does not.
+    const view = mount('alpha extra\nbravo\ncharlie');
+    const bars = view.dom.querySelectorAll<HTMLElement>('.cm-change-bar');
+    expect(bars.length).toBe(1);
+    expect(bars[0].style.background).toBe('var(--dx-accent)');
+    view.destroy();
+  });
+
+  test('a new-paragraph insertion bars only the text line, not the trailing blank line', ({ expect }) => {
+    // The branch inserts a new first paragraph "intro\n\n" before "alpha"; the trailing paragraph break
+    // must not tag the blank line — exactly one bar, on the inserted text line.
+    const view = mount('intro\n\nalpha\nbravo\ncharlie');
+    expect(view.dom.querySelectorAll('.cm-change-bar')).toHaveLength(1);
+    view.destroy();
+  });
+
+  // A reader deleting a run of words must strike exactly those words: character diffing used to match
+  // stray letters across the run (`t` of `it` against `t` of `two`), splitting words at both edges.
+  test('deleting a run of words strikes whole words', ({ expect }) => {
+    const main = 'the revision it was written on, so two people can suggest changes';
+    const doc = main.replace('it was written on, so ', '');
+    const hunks = computeCharHunks(main, doc);
+    expect(hunks).toHaveLength(1);
+    expect(main.slice(hunks[0].fromA, hunks[0].toA)).toBe('it was written on, so ');
+  });
+
+  // Selections do not respect word edges. Cutting into the words at each end fuses the survivors, and a
+  // word-level hunk then reads as "delete both words, insert this fused one" — rendering a phantom of
+  // both whole words plus a bogus insertion (`writte` + inserted `ngest`) instead of a plain deletion.
+  test('a deletion that cuts into words at both ends strikes only what was removed', ({ expect }) => {
+    const main = 'the revision it was written on, so two people can suggest changes';
+    const cut = 'n on, so two people can sugge';
+    const doc = main.replace(cut, '');
+
+    const hunks = computeCharHunks(main, doc);
+    expect(hunks).toHaveLength(1);
+    expect(main.slice(hunks[0].fromA, hunks[0].toA)).toBe(cut);
+    // Nothing is reported as inserted: the reader only deleted.
+    expect(doc.slice(hunks[0].fromB, hunks[0].toB)).toBe('');
+  });
+
+  // Deleting `suggest change` from `suggest changes` leaves an `s`, and that survivor is equally the
+  // tail of `changes` or the head of `suggest`. The minimal edit is ambiguous, so the strike must be
+  // slid to the word boundary — otherwise it keeps the `s` of `suggest` and strikes `uggest changes`.
+  test('an ambiguous deletion strikes from the word boundary', ({ expect }) => {
+    const main = 'so two people can suggest changes to the same';
+    const cut = 'suggest change';
+    const doc = main.replace(cut, '');
+
+    const hunks = computeCharHunks(main, doc);
+    expect(hunks).toHaveLength(1);
+    expect(main.slice(hunks[0].fromA, hunks[0].toA)).toBe(cut);
+    expect(main[hunks[0].fromA - 1]).toBe(' ');
+  });
+});

package/src/extensions/review/track-changes.ts

@@ -0,0 +1,215 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorState, type Extension, RangeSet, StateEffect, StateField } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, type GutterMarker, WidgetType, keymap } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+import { ChangeBarMarker, changeBars } from './change-bar';
+import { computeCharHunks } from './diff';
+
+export type TrackChangesOptions = {
+  /**
+   * The accepted base (`main`) the branch is diffed against. The editor's document is the branch, so
+   * insertions and deletions are computed relative to this. Replace it live with {@link setBase} (e.g.
+   * when a merge lands on main) rather than rebuilding the extension.
+   */
+  main: string;
+  /** The branch author's palette colour (e.g. `var(--color-cyan-text)`) applied to the tracked marks. */
+  colour: string;
+};
+
+/**
+ * Replaces the tracked base without rebuilding the extension, so a merge to main re-diffs the live
+ * document. The base is a {@link StateField} fed by this effect rather than a closure constant, matching
+ * the production shape (see the bind-to-branch spike).
+ */
+export const setBase = StateEffect.define<string>();
+
+/**
+ * Google-Docs-style "Suggesting mode" via bind-to-branch: the editor is bound to the branch document
+ * and edits accrue natively to it, while the diff against {@link TrackChangesOptions.main} is decorated
+ * over the live buffer — insertions as author-coloured underlined marks, deletions as phantom
+ * strikethrough widgets rendering the removed base text (which is absent from the document). A
+ * replacement renders both, `~~old~~new`. Single author; foreign authors compose via the separate
+ * `suggestions()` overlay.
+ */
+export const trackChanges = ({ main, colour }: TrackChangesOptions): Extension => {
+  // The author colour is constant for the instance, so bind it to the insertion mark once. Structural
+  // styling lives in the theme class; only the dynamic attribution colour is inline (as in `suggest.ts`).
+  const insertMark = Decoration.mark({
+    class: 'cm-track-insert',
+    attributes: { style: `color:${colour};text-decoration-color:${colour}` },
+  });
+
+  // One-entry memo of the last (base, doc) → decorations. Rebuilding is a whole-document char diff, so
+  // reuse it when the same state recurs (undo/redo to a prior revision, or a doc-changing transaction
+  // that lands back on a cached buffer). The key is length-prefixed so no base/doc pair is ambiguous.
+  let cache: { base: string; doc: string; state: TrackState } | undefined;
+
+  const build = (base: string, state: EditorState): TrackState => {
+    const doc = state.doc.toString();
+    if (cache && cache.base === base && cache.doc === doc) {
+      return cache.state;
+    }
+    const decorations = [];
+    const phantomRanges = [];
+    const phantomPositions: number[] = [];
+    // Line starts carrying a change, for the gutter change-bar (deduped, one bar per line).
+    const changedLines = new Set<number>();
+    const markLines = (from: number, to: number) => {
+      // Trim a trailing newline so an inserted/removed paragraph break does not tag the following
+      // (empty) line — otherwise a new-paragraph suggestion draws a bar two lines deep.
+      let end = to;
+      while (end > from && state.doc.sliceString(end - 1, end) === '\n') {
+        end--;
+      }
+      for (let line = state.doc.lineAt(from).number; line <= state.doc.lineAt(end).number; line++) {
+        changedLines.add(state.doc.line(line).from);
+      }
+    };
+    for (const hunk of computeCharHunks(base, doc)) {
+      // Deletion: base text absent from the branch. Anchor the phantom at `fromB` with `side: -1` so it
+      // renders before a co-located insertion (giving `~~old~~new`).
+      if (hunk.toA > hunk.fromA) {
+        const widget = Decoration.widget({
+          widget: new PhantomDeleteWidget(base.slice(hunk.fromA, hunk.toA), colour),
+          side: -1,
+        }).range(hunk.fromB);
+        decorations.push(widget);
+        phantomRanges.push(widget);
+        phantomPositions.push(hunk.fromB);
+        markLines(hunk.fromB, hunk.fromB);
+      }
+      // Insertion: branch text absent from the base.
+      if (hunk.toB > hunk.fromB) {
+        decorations.push(insertMark.range(hunk.fromB, hunk.toB));
+        markLines(hunk.fromB, hunk.toB);
+      }
+    }
+    const result: TrackState = {
+      base,
+      // `sort: true` orders the interleaved widget/mark ranges (co-located phantom before its mark).
+      decorations: Decoration.set(decorations, true),
+      atomic: Decoration.set(phantomRanges, true),
+      phantoms: phantomPositions,
+      changeBars: RangeSet.of(
+        [...changedLines].sort((a, b) => a - b).map((from) => new ChangeBarMarker(colour).range(from)),
+      ),
+    };
+    cache = { base, doc, state: result };
+    return result;
+  };
+
+  const field = StateField.define<TrackState>({
+    create: (state) => build(main, state),
+    update: (value, transaction) => {
+      let base = value.base;
+      let baseChanged = false;
+      for (const effect of transaction.effects) {
+        if (effect.is(setBase)) {
+          base = effect.value;
+          baseChanged = true;
+        }
+      }
+      if (!transaction.docChanged && !baseChanged) {
+        return value;
+      }
+      return build(base, transaction.state);
+    },
+    provide: (self) => EditorView.decorations.from(self, (value) => value.decorations),
+  });
+
+  return [
+    field,
+    trackChangesKeymap(field),
+    trackChangesAtomic(field),
+    changeBars((state) => state.field(field).changeBars),
+    trackChangesTheme,
+  ];
+};
+
+type TrackState = {
+  base: string;
+  decorations: DecorationSet;
+  /** Phantom widgets only, for the atomic-range facet (they are zero-width, so this is inert today). */
+  atomic: DecorationSet;
+  /** Document offsets carrying a phantom, for the keymap guard. */
+  phantoms: readonly number[];
+  /** Per-changed-line gutter change-bar markers, tinted with the author colour. */
+  changeBars: RangeSet<GutterMarker>;
+};
+
+/**
+ * Phantom render of text present in `main` but deleted on the branch — struck through and
+ * non-editable, since the text has no extent in the document.
+ */
+class PhantomDeleteWidget extends WidgetType {
+  #text: string;
+  #colour: string;
+
+  constructor(text: string, colour: string) {
+    super();
+    this.#text = text;
+    this.#colour = colour;
+  }
+
+  override eq(other: PhantomDeleteWidget): boolean {
+    return other.#text === this.#text && other.#colour === this.#colour;
+  }
+
+  override toDOM(): HTMLElement {
+    return (
+      Domino.of('span')
+        .classNames('cm-track-delete')
+        .attributes({ contenteditable: 'false' })
+        // Attribution colour is per-author (dynamic); the strikethrough itself is in the theme class.
+        .style({ color: this.#colour, textDecorationColor: this.#colour })
+        .text(this.#text).root
+    );
+  }
+
+  override ignoreEvent(): boolean {
+    return true;
+  }
+}
+
+/**
+ * A phantom has zero document extent, so the caret can only sit beside it — a plain Backspace beside a
+ * phantom therefore deletes the real branch character hidden behind the strikethrough rather than the
+ * phantom. Swallow it so tracked deletions read as protected units. Arrow keys need no override: the
+ * zero-width phantom is stepped over in a single motion already.
+ */
+const trackChangesKeymap = (field: StateField<TrackState>): Extension =>
+  keymap.of([
+    {
+      key: 'Backspace',
+      run: (view) => {
+        const selection = view.state.selection.main;
+        return selection.empty && view.state.field(field).phantoms.includes(selection.head);
+      },
+    },
+  ]);
+
+/** Register the phantoms as atomic ranges so cursor motion treats each as one unit. */
+const trackChangesAtomic = (field: StateField<TrackState>): Extension =>
+  EditorView.atomicRanges.of((view) => view.state.field(field, false)?.atomic ?? Decoration.none);
+
+const trackChangesTheme = EditorView.baseTheme({
+  // Insertion: author-coloured (inline) and underlined so it reads as added, not merely tinted.
+  '& .cm-track-insert': {
+    textDecoration: 'underline',
+    textDecorationThickness: '1px',
+    textUnderlineOffset: '2px',
+  },
+  // Deletion: struck through and de-emphasised; the removed base text, rendered as a phantom.
+  // `pre-wrap` preserves newlines in a multi-line/block deletion (a plain span collapses them to a
+  // single space), so a removed paragraph reads with its line breaks intact.
+  '& .cm-track-delete': {
+    textDecoration: 'line-through',
+    opacity: 0.7,
+    whiteSpace: 'pre-wrap',
+  },
+});

package/src/extensions/{busy.ts → state/busy.ts}

@@ -11,6 +11,7 @@ import { type EditorState, type Extension, StateEffect, StateField } from '@code
  */
 export const setBusy = StateEffect.define<boolean>();
 
+/** Shared busy StateField. Included by {@link busy}; exported for direct reads (see {@link isBusy}). */
 export const busyState = StateField.define<boolean>({
   create: () => false,
   update: (value, tr) => {

package/src/extensions/{focus.ts → state/focus.ts}

@@ -7,6 +7,10 @@ import { EditorView } from '@codemirror/view';
 
 const focusEffect = StateEffect.define<boolean>();
 
+/**
+ * Boolean StateField holding the editor's current focus state.
+ * Included by {@link focus}; exported for direct reads.
+ */
 export const focusField = StateField.define<boolean>({
   create: () => false,
   update: (value, tr) => {

package/src/extensions/state/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './busy';
+export * from './focus';
+export * from './modal';
+export * from './selection';

package/src/extensions/{selection.ts → state/selection.ts}

@@ -9,7 +9,7 @@ import * as Schema from 'effect/Schema';
 import { debounce } from '@dxos/async';
 import { isTruthy } from '@dxos/util';
 
-import { singleValueFacet } from '../util';
+import { singleValueFacet } from '../../util';
 
 /**
  * Currently edited document id as FQ string.
@@ -26,14 +26,14 @@ export type EditorSelectionState = {
   selection?: EditorSelection;
 };
 
-export const EditorSelectionSchema = Schema.Struct({
+export const EditorSelection = Schema.Struct({
   anchor: Schema.Number,
   head: Schema.optional(Schema.Number),
 }).pipe(Schema.mutable);
 
 export const EditorSelectionStateSchema = Schema.Struct({
   scrollTo: Schema.optional(Schema.Number),
-  selection: Schema.optional(EditorSelectionSchema),
+  selection: Schema.optional(EditorSelection),
 }).pipe(Schema.mutable);
 
 export type EditorStateStore = {

package/src/extensions/streaming/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './pending';
+export * from './scrolling';
+export * from './typewriter';

package/src/extensions/{pending → streaming/pending}/pending-text-stream.ts

@@ -126,6 +126,7 @@ export class PendingTextStreamer {
   #postHandle: unknown = null;
   /** The in-flight post-process pass, tracked so `flush()` can await it (drain contract). */
   #postPromise: Promise<void> | null = null;
+  #disposed = false;
 
   constructor(sink: PendingTextSink, options: PendingTextStreamerOptions = {}) {
     this.#sink = sink;
@@ -200,6 +201,7 @@ export class PendingTextStreamer {
   }
 
   dispose(): void {
+    this.#disposed = true;
     [this.#bufferHandle, this.#wordHandle, this.#postHandle].forEach((handle) => this.#clear(handle));
     this.#bufferHandle = this.#wordHandle = this.#postHandle = null;
   }
@@ -248,11 +250,16 @@ export class PendingTextStreamer {
   }
 
   async #runPostProcess(): Promise<void> {
+    const { postProcess } = this.#options;
+    if (!postProcess) {
+      return;
+    }
     const input = this.#final;
     try {
-      const result = await this.#options.postProcess!(input);
-      // Skip if the buffer grew while processing — a later pass will cover the newer text.
-      if (result !== input && this.#final === input) {
+      const result = await postProcess(input);
+      // Skip if disposed while processing (avoid writing into a torn-down sink / destroyed view), or
+      // if the buffer grew — a later pass will cover the newer text.
+      if (!this.#disposed && result !== input && this.#final === input) {
         this.#final = result;
         this.#sink.replaceFinal(result);
       }

package/src/extensions/{pending → streaming/pending}/pending-text.test.ts

@@ -6,7 +6,7 @@ import { EditorState } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
 import { describe, test } from 'vitest';
 
-import { isBusy } from '../busy';
+import { isBusy } from '../../state/busy';
 import {
   appendPendingText,
   cancelPending,

package/src/extensions/{pending → streaming/pending}/pending-text.ts

@@ -7,8 +7,8 @@ import { type Command, Decoration, EditorView, WidgetType, keymap } from '@codem
 
 import { Domino } from '@dxos/ui';
 
-import { busy, setBusy } from '../busy';
-import { type MarkerHue, markerButtons, markerText, markerTheme } from '../marker';
+import { type MarkerHue, markerButtons, markerText, markerTheme } from '../../decoration/marker';
+import { busy, setBusy } from '../../state/busy';
 
 //
 // State.
@@ -49,6 +49,7 @@ const emptyAt = (anchor: number, placeholder?: string): PendingTextState => ({
   placeholder,
 });
 
+/** StateField holding the pending text buffer (anchor, final, interim, placeholder); building block of the pendingText extension. */
 export const pendingTextState = StateField.define<PendingTextState | null>({
   create: () => null,
   update: (value, tr) => {
@@ -221,23 +222,6 @@ const busyListener = EditorView.updateListener.of((update) => {
   });
 });
 
-const styles = EditorView.theme({
-  // Keep the marker and affordances on a single line (it already sits on its own line at the anchor).
-  '.cm-pending-text': {
-    display: 'inline-flex',
-    alignItems: 'center',
-    gap: '0.5rem',
-  },
-  // The interim tail is distinguished from the finalized text only by reduced opacity.
-  '.cm-pending-text-interim': {
-    opacity: 0.6,
-  },
-  // Keep the "Recording…" indicator (text + spinner) on a single line.
-  '.cm-pending-text-indicator': {
-    whiteSpace: 'nowrap',
-  },
-});
-
 //
 // Extension.
 //
@@ -262,3 +246,20 @@ export const pendingText = (): Extension => [
     { key: 'Escape', run: cancelPending },
   ]),
 ];
+
+const styles = EditorView.theme({
+  // Keep the marker and affordances on a single line (it already sits on its own line at the anchor).
+  '.cm-pending-text': {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '0.5rem',
+  },
+  // The interim tail is distinguished from the finalized text only by reduced opacity.
+  '.cm-pending-text-interim': {
+    opacity: 0.6,
+  },
+  // Keep the "Recording…" indicator (text + spinner) on a single line.
+  '.cm-pending-text-indicator': {
+    whiteSpace: 'nowrap',
+  },
+});

package/src/extensions/{scrolling → streaming/scrolling}/auto-scroll.ts

@@ -214,11 +214,7 @@ export const autoScroll = ({ scrollOnResize = true }: AutoScrollProps = {}) => {
           const button = Domino.of('button')
             .classNames('dx-button bg-accent-bg aspect-square')
             .attributes({ 'data-density': 'sm' })
-            .append(
-              Domino.of('dx-icon' as any)
-                .classNames(getSize(4))
-                .attributes({ icon: 'ph--arrow-down--regular' }),
-            )
+            .append(Domino.of('dx-icon').classNames(getSize(4)).attributes({ icon: 'ph--arrow-down--regular' }))
             .on('click', () => {
               setPinned(true);
               view.dispatch({
@@ -235,7 +231,14 @@ export const autoScroll = ({ scrollOnResize = true }: AutoScrollProps = {}) => {
             .classNames('cm-scroll-button transition-opacity duration-300 opacity-0 z-1')
             .append(button).root as HTMLDivElement;
 
-          view.scrollDOM.parentElement!.appendChild(buttonContainer);
+          // The button lives outside CM's managed DOM (the scroller's parent), so remove it on
+          // teardown; otherwise it is orphaned and duplicated when the editor is recreated.
+          view.scrollDOM.parentElement?.appendChild(buttonContainer);
+        }
+
+        destroy() {
+          buttonContainer?.remove();
+          buttonContainer = undefined;
         }
       },
     ),

package/src/extensions/{scrolling → streaming/scrolling}/scroll-past-end.ts

@@ -26,6 +26,7 @@ const scrollPastEndPlugin = ViewPlugin.fromClass(
   },
 );
 
+/** Adds bottom padding so the last line can scroll to the top of the viewport, accounting for the actual last-line height. */
 export const scrollPastEnd = (): Extension => [
   scrollPastEndPlugin,
   EditorView.contentAttributes.of((view) => view.plugin(scrollPastEndPlugin)?._attrs ?? null),

package/src/extensions/{scrolling → streaming/scrolling}/scrollbar-autohide.ts

@@ -47,15 +47,17 @@ export const scrollbarAutohide = ({ timeout = 800 }: ScrollbarAutohideOptions =
       };
     },
   ),
-  EditorView.theme({
-    // Reveal the thumb only while actively scrolling.
-    '.cm-scroller.cm-scrolling::-webkit-scrollbar-thumb': {
-      background: 'var(--color-scrollbar-thumb)',
-    },
-    // Suppress the base theme's hover-reveal (higher specificity via `:not(.cm-scrolling)`), so a
-    // hovered/focused-but-idle editor keeps the thumb hidden.
-    '&:hover .cm-scroller:not(.cm-scrolling)::-webkit-scrollbar-thumb': {
-      background: 'transparent',
-    },
-  }),
+  styles,
 ];
+
+const styles = EditorView.theme({
+  // Reveal the thumb only while actively scrolling.
+  '.cm-scroller.cm-scrolling::-webkit-scrollbar-thumb': {
+    background: 'var(--color-scrollbar-thumb)',
+  },
+  // Suppress the base theme's hover-reveal (higher specificity via `:not(.cm-scrolling)`), so a
+  // hovered/focused-but-idle editor keeps the thumb hidden.
+  '&:hover .cm-scroller:not(.cm-scrolling)::-webkit-scrollbar-thumb': {
+    background: 'transparent',
+  },
+});

package/src/extensions/{typewriter.ts → streaming/typewriter.ts}

@@ -15,50 +15,7 @@ import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate
 
 import { Domino } from '@dxos/ui';
 
-/** Annotate a transaction to bypass the typewriter buffer (content appears immediately). */
-export const typewriterBypass = Annotation.define<boolean>();
-
-/**
- * Public state effect signalling whether typewriter's drip queue is currently draining.
- * Other extensions can subscribe to coordinate behaviour with the typewriter (e.g. hide
- * a block-widget footer while text is being dripped to avoid scroll-measure conflicts).
- *
- * Dispatched at queue transitions:
- * - `true` — empty → non-empty (drain rAF/interval is starting).
- * - `false` — non-empty → empty (last char written, drain stopped).
- */
-export const typewriterDrainingEffect = StateEffect.define<boolean>();
-
-/**
- * Buffer state. The pending text is `text.slice(head)` — but `head` is advanced
- * without slicing on every drip to avoid O(n²) string copying. The prefix is
- * compacted lazily once it exceeds half the string or `COMPACT_HEAD_THRESHOLD`.
- */
-type BufferState = { text: string; head: number; insertAt: number };
-
-/** How long to show the cursor after motion has stopped. */
-const CURSOR_LINGER = 3_000;
-
-/** Per-frame time budget for draining the buffer. Stays well under a 16 ms frame. */
-const FRAME_BUDGET_MS = 4;
-
-/**
- * Visible characters of plain text emitted per animation frame. At 60 fps a value of 1
- * gives ~60 char/s — fast enough to keep up with most streams while still reading as a
- * smooth character-by-character drip. Atomic structures (XML elements, markdown links)
- * always flush whole regardless of this cap.
- */
-const CHARS_PER_FRAME = 5;
-
-/**
- * When the pending buffer exceeds this many characters, abandon typewriter pacing
- * and flush the entire buffer in one transaction. The visual benefit of typewriter
- * has negative value past human-reading rates.
- */
-const FLUSH_THRESHOLD = 2_000;
-
-/** Compaction trigger for the head-offset rope. */
-const COMPACT_HEAD_THRESHOLD = 4_096;
+import { escapeRegExpSource } from '../../util';
 
 export type TypewriterOptions = {
   /** Show a blinking cursor at the insertion point while streaming. */
@@ -303,6 +260,51 @@ export const typewriter = (options: TypewriterOptions = {}): Extension => {
   ) as Extension[];
 };
 
+/** Annotate a transaction to bypass the typewriter buffer (content appears immediately). */
+export const typewriterBypass = Annotation.define<boolean>();
+
+/**
+ * Public state effect signalling whether typewriter's drip queue is currently draining.
+ * Other extensions can subscribe to coordinate behaviour with the typewriter (e.g. hide
+ * a block-widget footer while text is being dripped to avoid scroll-measure conflicts).
+ *
+ * Dispatched at queue transitions:
+ * - `true` — empty → non-empty (drain rAF/interval is starting).
+ * - `false` — non-empty → empty (last char written, drain stopped).
+ */
+export const typewriterDrainingEffect = StateEffect.define<boolean>();
+
+/**
+ * Buffer state. The pending text is `text.slice(head)` — but `head` is advanced
+ * without slicing on every drip to avoid O(n²) string copying. The prefix is
+ * compacted lazily once it exceeds half the string or `COMPACT_HEAD_THRESHOLD`.
+ */
+type BufferState = { text: string; head: number; insertAt: number };
+
+/** How long to show the cursor after motion has stopped. */
+const CURSOR_LINGER = 3_000;
+
+/** Per-frame time budget for draining the buffer. Stays well under a 16 ms frame. */
+const FRAME_BUDGET_MS = 4;
+
+/**
+ * Visible characters of plain text emitted per animation frame. At 60 fps a value of 1
+ * gives ~60 char/s — fast enough to keep up with most streams while still reading as a
+ * smooth character-by-character drip. Atomic structures (XML elements, markdown links)
+ * always flush whole regardless of this cap.
+ */
+const CHARS_PER_FRAME = 5;
+
+/**
+ * When the pending buffer exceeds this many characters, abandon typewriter pacing
+ * and flush the entire buffer in one transaction. The visual benefit of typewriter
+ * has negative value past human-reading rates.
+ */
+const FLUSH_THRESHOLD = 2_000;
+
+/** Compaction trigger for the head-offset rope. */
+const COMPACT_HEAD_THRESHOLD = 4_096;
+
 //
 // Cursor
 //
@@ -426,9 +428,6 @@ const OPENING_TAG_NAME = /^<([a-zA-Z][\w-]*)/;
 /** Tag names are short — bound the slice we hand to the regex matcher. */
 const TAG_NAME_PROBE = 64;
 
-/** Escapes a string for safe embedding in RegExp source (tag names from the document). */
-const escapeRegExpSource = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
 type FlushResult = {
   count: number;
   /** Tag name to enter streaming mode for. */