Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

44.3 KB
Raw Blame
import type { HocuspocusProvider } from '@hocuspocus/provider';
import {
  evictStaleEntries,
  FLASH_DEBOUNCE_MS,
  FLASH_DURATION_MS,
  hasNewEntries,
} from '@inkeep/open-knowledge-core/constants/activity';
import { sharedExtensions as coreExtensions } from '@inkeep/open-knowledge-core/extensions/shared';
import { MarkdownManager } from '@inkeep/open-knowledge-core/markdown';
import type { AgentFlashEntry } from '@inkeep/open-knowledge-core/types/awareness';
import { deriveIconColor } from '@inkeep/open-knowledge-core/utils/identity';
import { randomUUID } from '@inkeep/open-knowledge-core/utils/random-uuid';
import { t } from '@lingui/core/macro';
import { type AnyExtension, Editor, type EditorOptions, Extension, isMacOS } from '@tiptap/core';
import Collaboration from '@tiptap/extension-collaboration';
import Placeholder from '@tiptap/extension-placeholder';
import { EditorContent } from '@tiptap/react';
import { initProseMirrorDoc, yCursorPlugin, ySyncPluginKey } from '@tiptap/y-tiptap';
import { type FC, use, useEffect, useLayoutEffect, useRef, useState } from 'react';
import { createPortal } from 'react-dom';
import { SelectionAnnouncer } from '@/components/editor/SelectionAnnouncer';
import { useEditorPaneOnScreen } from '@/lib/use-editor-pane-on-screen';
import {
  clearRenameSnapshot,
  editorScrollContainerOf,
  parkTiptapEditor,
  peekRenameSnapshot,
} from './editor-cache';
import { InteractionLayerView } from './interaction-layer';
import { getInteractionLayer } from './interaction-layer-host';

const editorCtorStartTimes = new WeakMap<object, number>();

import { type Transaction as PMTransaction, TextSelection } from '@tiptap/pm/state';
import type { EditorView as PMEditorView } from '@tiptap/pm/view';
import { CommentAnchorLayer } from '@/comments/anchor-decorations';
import { CommentMarginRail } from '@/comments/CommentMarginRail';
import { CommentSelectionAffordance } from '@/comments/CommentSelectionAffordance';
import { CommentsBoundary } from '@/comments/CommentsBoundary';
import { loadFollowFilePref } from '@/components/acp/follow-file';
import {
  OUTLINE_NAV_BREADCRUMB,
  OUTLINE_NAV_EVENT,
  OUTLINE_NAV_SETTLED_BREADCRUMB,
  type OutlineNavDetail,
} from '@/components/OutlinePanel';
import { emitDiagnosticBreadcrumb } from '@/lib/diagnostic-breadcrumb';
import { anchorFromHash } from '@/lib/doc-hash';
import { claimNoteWindowInitialFocus } from '@/lib/note-window-focus';
import { mark } from '@/lib/perf';
import { wrapExtensionsWithTiming } from '@/lib/perf/cold-mount-instrumentation';
import { useSingleFileMode } from '@/lib/single-file-mode';
import { useIdentity } from '../presence/identity';
import { registerEditor, unregisterEditor } from './active-editor';
import { changedRangeIsOnScreen } from './agent-follow-scroll';
import { REPEAT_ANCHOR_NAV_EVENT } from './anchor-navigation-event';
import { findAnchorTarget } from './anchor-target';
import { applyLintFixes } from './apply-lint-fix.ts';
import { getAwarenessHeartbeat } from './awareness-heartbeat-runtime';
import { buildAwarenessUser } from './awareness-user';
import { bindingStalenessGuardPlugin, type WedgeDetail } from './binding-staleness-guard';
import { BubbleMenuBar } from './bubble-menu/BubbleMenuBar';
import { attachCaretLabel, caretLabelLayerPlugin } from './caret-label-layer';
import {
  createClipboardHtmlSerializer,
  createClipboardTextSerializer,
  createCopyCutHandler,
  createHandleDrop,
  createHandlePaste,
} from './clipboard/index.ts';
import { useDocumentContext } from './DocumentContext';
import { isUserIntentOrigin } from './extensions/autonomous-fragment-edit.ts';
import { createBareHtmlImageDecoration } from './extensions/bare-html-image-decoration';
import { setEditorDocName } from './extensions/doc-context.ts';
import { setEditorSingleFileMode, setEditorSourceMode } from './extensions/editor-mode-context.ts';
import { FrozenTableHeaders } from './extensions/frozen-table-headers.ts';
import { MarkdownLintDecorations } from './extensions/markdown-lint-decorations.ts';
import { scopeExtensionsToDocument, sharedExtensions } from './extensions/shared.ts';
import { SkillPathLinks } from './extensions/skill-path-links';
import { uploadDecorationPlugin } from './image-upload/index.ts';
import type { LandingHandle } from './landing-controller';
import { startWysiwygLanding } from './mode-switch-landing';
import { getMountId } from './mount-id-registry';
import { mountTiptapEditorPromise } from './mount-promise';
import { markUserTyping } from './observers';
import {
  AGENT_INSERT_FLASH_ACTIVATION_MS,
  AGENT_INSERT_FLASH_MS,
  agentInsertFlashKey,
  blockRangeToPositions,
  computeChangedRange,
  createAgentInsertFlashPlugin,
} from './plugins/agent-insert-flash';
import { isUserIntentPmTransaction, requestPreviewTabPromotion } from './preview-tab-promotion';
import { isScrollRestoreSuppressed, runScrollNavigation } from './scroll-restore-coordination';
import { publishSelectionContext, selectionSnapshotFromWysiwyg } from './selection-context';
import {
  publishSelectionStats,
  SELECTION_STATS_DEBOUNCE_MS,
  selectionStatsFromWysiwyg,
} from './selection-stats';
import {
  consumePendingWysiwygNavigation,
  peekPendingWysiwygNavigation,
} from './source-editor-navigation';
import { TableCellHandles } from './table-controls/TableCellHandles';
import { attachTypingBurstDetector } from './typing-burst-detector';
import { editorVisibleBand } from './utils/editor-visible-region';
import { getEditorView } from './utils/get-editor-view';
import { walkCurrencyExtension } from './walk-currency-extension';

function renderCursor(user: Record<string, string>): HTMLElement {
  const cursor = document.createElement('span');
  cursor.classList.add('collaboration-cursor__caret');
  cursor.style.borderColor = user.color;

  const label = document.createElement('div');
  label.classList.add('collaboration-cursor__label');
  label.style.backgroundColor = user.color;
  label.style.color = deriveIconColor(user.color);
  label.textContent = user.name;
  attachCaretLabel(cursor, label);

  return cursor;
}

interface AgentFlashState {
  state: 'idle' | 'editing' | 'settled';
  count: number;
  lastFiredAt: number | null;
  position: 'append' | 'prepend';
  lastAgentId: string | null;
}

const INITIAL_FLASH_STATE: AgentFlashState = {
  state: 'idle',
  count: 0,
  lastFiredAt: null,
  position: 'append',
  lastAgentId: null,
};

function freshestFlashEntry(
  activityMap: { entries(): IterableIterator<[string, unknown]> },
  since: number,
): { key: string; entry: AgentFlashEntry } | null {
  let best: { key: string; entry: AgentFlashEntry } | null = null;
  for (const [id, value] of activityMap.entries()) {
    const entry = value as AgentFlashEntry;
    if (typeof entry?.timestamp !== 'number' || entry.timestamp <= since) continue;
    if (best === null || entry.timestamp > best.entry.timestamp) {
      best = { key: `${id}:${entry.timestamp}`, entry };
    }
  }
  return best;
}

const ANCHOR_SCROLL_MAX_ATTEMPTS = 100;
const ANCHOR_SCROLL_RETRY_MS = 100;
const ANCHOR_SCROLL_FOLLOW_UP_ATTEMPTS = 3;
const ANCHOR_SCROLL_FOLLOW_UP_MS = 250;

const OUTLINE_NAV_SETTLE_MS = 600;

interface TiptapEditorProps {
  provider: HocuspocusProvider;
  placeholder?: string;
  isSourceMode: boolean;
  portalTarget: HTMLElement;
}

type ClipboardState = ReturnType<typeof buildClipboardState>;

type EditorContentBindingState = Editor & {
  contentComponent: unknown | null;
  isEditorContentInitialized: boolean;
};

function hasEditorContentBindingState(editor: Editor): editor is EditorContentBindingState {
  return 'contentComponent' in editor && 'isEditorContentInitialized' in editor;
}

function repairDetachedEditorContent(editor: Editor, portalTarget: HTMLElement): boolean {
  const view = getEditorView(editor);
  if (!view || portalTarget.contains(view.dom)) return false;

  if (!hasEditorContentBindingState(editor)) {
    console.warn(
      '[TiptapEditor] TipTap EditorContent binding fields missing; detached editor repair skipped',
    );
    return false;
  }

  const editorWithContent = editor;
  if (editorWithContent.contentComponent == null) return false;

  try {
    view.setProps({ nodeViews: {} });
  } catch {}
  editorWithContent.contentComponent = null;
  editorWithContent.isEditorContentInitialized = false;
  return true;
}

type ProsemirrorMapping = ReturnType<typeof initProseMirrorDoc>['mapping'];

function buildClipboardState() {
  const mdManager = new MarkdownManager({ extensions: coreExtensions });
  return {
    mdManager,
    text: createClipboardTextSerializer({ mdManager }),
    html: createClipboardHtmlSerializer({ mdManager }),
    paste: createHandlePaste({ mdManager }),
    copy: createCopyCutHandler({ mdManager }),
    drop: createHandleDrop({ mdManager }),
  };
}

interface BuildEditorOptionsArgs {
  provider: HocuspocusProvider;
  placeholder?: string;
  clipboard: ClipboardState;
  ctorStart: number;
  prebuiltMapping?: ProsemirrorMapping;
  onWedged?: (detail: WedgeDetail) => void;
}

interface PrewarmBoundCollaboration {
  collaboration: AnyExtension;
  guard: AnyExtension[];
}

function buildPrewarmBoundCollaboration(
  provider: HocuspocusProvider,
  prebuiltMapping: ProsemirrorMapping | undefined,
): PrewarmBoundCollaboration {
  if (!prebuiltMapping) {
    return { collaboration: Collaboration.configure({ document: provider.document }), guard: [] };
  }
  return {
    collaboration: Collaboration.configure({
      document: provider.document,
      ySyncOptions: { mapping: prebuiltMapping },
    }),
    guard: [
      walkCurrencyExtension({
        fragment: provider.document.getXmlFragment('default'),
        docName: provider.configuration.name ?? '',
      }),
    ],
  };
}

export function buildExtensionList(args: BuildEditorOptionsArgs): AnyExtension[] {
  const { provider, placeholder, prebuiltMapping, onWedged } = args;
  const { collaboration, guard } = buildPrewarmBoundCollaboration(provider, prebuiltMapping);
  return [
    ...scopeExtensionsToDocument(sharedExtensions, provider.configuration.name ?? ''),
    createBareHtmlImageDecoration(provider.configuration.name ?? ''),
    Placeholder.configure({
      placeholder: () => placeholder ?? t`Type '/' for commands`,
      showOnlyCurrent: true,
    }),
    SkillPathLinks.configure({ docName: provider.configuration.name ?? '' }),
    collaboration,
    Extension.create({
      name: 'imageUploadDecoration',
      addProseMirrorPlugins() {
        return [uploadDecorationPlugin];
      },
    }),
    Extension.create({
      name: 'collaborationCursor',
      addProseMirrorPlugins() {
        const awareness = provider.awareness;
        if (!awareness) {
          throw new Error(
            '[TiptapEditor] HocuspocusProvider has no awareness instance — cursor plugin cannot initialize',
          );
        }
        return [
          yCursorPlugin(awareness, {
            cursorBuilder: renderCursor,
          }),
          caretLabelLayerPlugin(),
        ];
      },
    }),
    Extension.create({
      name: 'bindingStalenessGuard',
      addProseMirrorPlugins() {
        return [
          bindingStalenessGuardPlugin({
            fragment: provider.document.getXmlFragment('default'),
            docName: provider.configuration.name ?? '',
            onWedged: onWedged ?? (() => {}),
          }),
        ];
      },
    }),
    ...guard,
    FrozenTableHeaders,
    MarkdownLintDecorations.configure({
      docName: provider.configuration.name ?? '',
      getSource: () => provider.document.getText('source').toString(),
      applyFix: (fixes) => applyLintFixes(provider, fixes, provider.configuration.name ?? ''),
    }),
  ];
}

function admitFocusedTextCaret(view: PMEditorView, event: KeyboardEvent): void {
  const isLineEndKey =
    !event.altKey &&
    !event.ctrlKey &&
    !event.shiftKey &&
    (isMacOS()
      ? event.key === 'ArrowRight' && event.metaKey
      : event.key === 'End' && !event.metaKey);
  if (
    event.isComposing ||
    view.composing ||
    !view.editable ||
    event.altKey ||
    event.ctrlKey ||
    event.shiftKey ||
    (!isLineEndKey && (event.metaKey || event.key.length !== 1)) ||
    !view.hasFocus() ||
    !(view.state.selection instanceof TextSelection) ||
    !view.state.selection.empty
  ) {
    return;
  }

  const domSelection = view.dom.ownerDocument.getSelection();
  const focusNode = domSelection?.focusNode;
  if (!domSelection?.isCollapsed || !focusNode || !view.dom.contains(focusNode)) return;
  const focusElement =
    focusNode.nodeType === Node.ELEMENT_NODE ? (focusNode as Element) : focusNode.parentElement;
  if (focusElement?.closest('[contenteditable="false"]')) return;

  const pos = view.posAtDOM(focusNode, domSelection.focusOffset, 1);
  const $pos = view.state.doc.resolve(pos);
  if (!$pos.parent.isTextblock) return;
  const nextSelection =
    view.someProp('createSelectionBetween', (create) => create(view, $pos, $pos)) ??
    TextSelection.between($pos, $pos, 1);
  if (!(nextSelection instanceof TextSelection) || !nextSelection.empty) return;
  if (focusNode.nodeType === Node.ELEMENT_NODE) {
    const element = focusNode as Element;
    const textNode = view.dom.ownerDocument
      .createTreeWalker(element, NodeFilter.SHOW_TEXT)
      .nextNode();
    if (
      textNode &&
      !textNode.parentElement?.closest('[contenteditable="false"]') &&
      view.posAtDOM(textNode, 0, 1) === pos
    ) {
      const range = view.dom.ownerDocument.createRange();
      range.setStart(textNode, 0);
      range.collapse(true);
      domSelection.removeAllRanges();
      domSelection.addRange(range);
    }
  }
  if (pos === view.state.selection.head) return;
  view.dispatch(view.state.tr.setSelection(nextSelection));
}

function buildEditorOptions(args: BuildEditorOptionsArgs): Partial<EditorOptions> {
  const { provider, placeholder, clipboard, ctorStart } = args;
  return {
    onBeforeCreate: ({ editor }) => {
      editorCtorStartTimes.set(editor, ctorStart);
    },
    onCreate: ({ editor }) => {
      clipboard.html.setView(editor.view);
      const start = editorCtorStartTimes.get(editor);
      editorCtorStartTimes.delete(editor);
      if (start == null) return;
      const now = performance.now();
      mark(
        'ok/editor/create-tiptap',
        {
          docName: provider.configuration.name ?? 'unknown',
          ytextLength: provider.document.getText('source').length,
        },
        { startTime: start, duration: Math.max(0, now - start) },
      );
    },
    editorProps: {
      attributes: {
        class: 'pt-4 pb-4 h-full',
        ...(placeholder === undefined ? {} : { 'data-empty-placeholder': placeholder }),
      },
      clipboardTextParser: (text, _context, _plain, view) => {
        const json = clipboard.mdManager.parse(text);
        const node = view.state.schema.nodeFromJSON(json);
        // biome-ignore lint/suspicious/noExplicitAny: TipTap's clipboardTextParser expects a Slice-like return but ProseMirror Fragment works at runtime; no public type expresses the union
        return node.content as any;
      },
      clipboardTextSerializer: (slice, view) => clipboard.text(slice, view),
      clipboardSerializer: clipboard.html.serializer,
      handlePaste: (view, event) => clipboard.paste(view, event),
      handleDrop: clipboard.drop,
      handleDOMEvents: {
        keydown: (view, event) => {
          admitFocusedTextCaret(view, event);
          return false;
        },
        copy: (view, event) => clipboard.copy(view, event as ClipboardEvent, false),
        cut: (view, event) => clipboard.copy(view, event as ClipboardEvent, true),
      },
    },
    extensions: wrapExtensionsWithTiming(buildExtensionList(args)),
  };
}

interface BuildPatternDConstructorOptionsArgs {
  provider: HocuspocusProvider;
  placeholder?: string;
  clipboard: ClipboardState;
  ctorStart: number;
  onWedged?: (detail: WedgeDetail) => void;
}

type PatternDConstructorOptions = Partial<EditorOptions> & { element: null };

export function buildPatternDConstructorOptions(
  args: BuildPatternDConstructorOptionsArgs,
): PatternDConstructorOptions {
  const { provider, placeholder, clipboard, ctorStart, onWedged } = args;
  const fragment = provider.document.getXmlFragment('default');
  const prebuiltMapping: ProsemirrorMapping = new Map();
  const baseOptions = buildEditorOptions({
    provider,
    placeholder,
    clipboard,
    ctorStart,
    prebuiltMapping,
    onWedged,
  });
  const baseOnBeforeCreate = baseOptions.onBeforeCreate;
  return {
    ...baseOptions,
    onBeforeCreate: (props) => {
      baseOnBeforeCreate?.(props);
      const { editor } = props;
      const { doc, mapping } = initProseMirrorDoc(fragment, editor.schema);
      mapping.forEach((node, key) => {
        prebuiltMapping.set(key, node);
      });
      editor.options.content = doc.toJSON();
    },
    element: null,
  };
}

/**
 * The only editor mount path in the app: Suspense plus `use(mountTiptapEditorPromise(...))` per
 * precedent #18(d), so `<EditorContent>` only ever sees a fully mounted editor and a mount
 * failure surfaces through `DocumentErrorBoundary`.
 */
export const TiptapEditor: FC<TiptapEditorProps> = ({
  provider,
  placeholder,
  isSourceMode,
  portalTarget,
}) => {
  const wrapperRef = useRef<HTMLDivElement | null>(null);
  const flashStateRef = useRef(INITIAL_FLASH_STATE);
  const identity = useIdentity();
  const { principal, activeDocName, recycleDocument } = useDocumentContext();
  const docName = provider.configuration.name ?? '';

  const [clipboard] = useState(buildClipboardState);

  const [construct] = useState(() => () => {
    const ctorStart = performance.now();
    const tipTapEditor = new Editor(
      buildPatternDConstructorOptions({
        provider,
        placeholder,
        clipboard,
        ctorStart,
        onWedged: ({ externalSeq, appliedSeq }) => {
          mark('ok/editor/binding-wedge-recycle', { docName, externalSeq, appliedSeq });
          recycleDocument(docName);
        },
      }),
    );
    return {
      editor: tipTapEditor,
      ydoc: provider.document,
      ytext: provider.document.getText('source'),
      provider,
    };
  });

  const bytes = provider.document.getText('source').length;
  const sizeStats = { viewCount: 0, bytes };

  const mountId = getMountId(docName) ?? randomUUID();
  const entry = use(mountTiptapEditorPromise({ docName, mountId, construct, sizeStats }));
  const editor = entry.editor;

  useEffect(() => {
    return () => {
      parkTiptapEditor(entry);
    };
  }, [entry]);

  return (
    <TiptapEditorChrome
      provider={provider}
      isSourceMode={isSourceMode}
      docName={docName}
      activeDocName={activeDocName}
      identity={identity}
      principal={principal}
      editor={editor}
      wrapperRef={wrapperRef}
      flashStateRef={flashStateRef}
      portalTarget={portalTarget}
    />
  );
};

interface TiptapEditorChromeProps {
  provider: HocuspocusProvider;
  isSourceMode: boolean;
  docName: string;
  activeDocName: string | null;
  identity: ReturnType<typeof useIdentity>;
  principal: ReturnType<typeof useDocumentContext>['principal'];
  editor: Editor;
  wrapperRef: React.RefObject<HTMLDivElement | null>;
  flashStateRef: React.RefObject<AgentFlashState>;
  portalTarget: HTMLElement;
}

const TiptapEditorChrome: FC<TiptapEditorChromeProps> = ({
  provider,
  isSourceMode,
  docName,
  activeDocName,
  identity,
  principal,
  editor,
  wrapperRef,
  flashStateRef,
  portalTarget,
}) => {
  const editorPaneOnScreen = useEditorPaneOnScreen();
  const portalSlotRef = useRef<HTMLDivElement | null>(null);
  const singleFile = useSingleFileMode();
  const [editorContentRevision, setEditorContentRevision] = useState(0);
  useLayoutEffect(() => {
    const slot = portalSlotRef.current;
    if (!slot) return;
    slot.appendChild(portalTarget);
    return () => {
      if (portalTarget.parentNode === slot) {
        slot.removeChild(portalTarget);
      }
    };
  }, [portalTarget]);

  useEffect(() => {
    if (repairDetachedEditorContent(editor, portalTarget)) {
      setEditorContentRevision((revision) => revision + 1);
    }
  }, [editor, portalTarget]);
  useEffect(() => {
    const docName = provider.configuration.name ?? null;
    setEditorDocName(editor, docName);
    return () => {
      setEditorDocName(editor, null);
    };
  }, [editor, provider]);

  useEffect(() => {
    const docName = provider.configuration.name;
    if (!docName) return;
    registerEditor(docName, editor);
    return () => unregisterEditor(docName, editor);
  }, [editor, provider]);

  useEffect(() => {
    if (isSourceMode) return;
    const docName = provider.configuration.name;
    if (!docName) return;
    if (!peekPendingWysiwygNavigation(docName)) return;

    let cancelled = false;
    let landing: LandingHandle | null = null;
    const begin = (): void => {
      queueMicrotask(() => {
        if (cancelled) return;
        const navigation = consumePendingWysiwygNavigation(docName);
        if (navigation?.kind !== 'selection-offset') return;
        landing = startWysiwygLanding({
          editor,
          docName,
          navigation,
          ydoc: provider.document,
          transition: { from: 'source', to: 'wysiwyg' },
        });
      });
    };
    if (getEditorView(editor)) {
      begin();
    } else {
      editor.on('create', begin);
    }
    return () => {
      cancelled = true;
      editor.off('create', begin);
      landing?.cancel('mode-flip');
    };
  }, [editor, provider, isSourceMode]);

  useEffect(() => {
    const docName = provider.configuration.name;
    if (!docName) return;
    let timer: ReturnType<typeof setTimeout> | null = null;
    const publish = () => {
      timer = null;
      publishSelectionStats(docName, 'wysiwyg', selectionStatsFromWysiwyg(editor));
      publishSelectionContext(docName, 'wysiwyg', selectionSnapshotFromWysiwyg(editor, docName));
    };
    const schedule = () => {
      if (timer) clearTimeout(timer);
      timer = setTimeout(publish, SELECTION_STATS_DEBOUNCE_MS);
    };
    publish();
    editor.on('selectionUpdate', schedule);
    editor.on('update', schedule);
    return () => {
      if (timer) clearTimeout(timer);
      editor.off('selectionUpdate', schedule);
      editor.off('update', schedule);
      publishSelectionStats(docName, 'wysiwyg', null);
      publishSelectionContext(docName, 'wysiwyg', null);
    };
  }, [editor, provider]);

  useEffect(() => {
    if (import.meta.env.PROD) return;
    if (!editor) return;
    const docName = provider.configuration.name;
    if (!docName) return;
    const mountId = getMountId(docName);
    if (!mountId) return;
    const sampler = attachTypingBurstDetector({
      mode: 'WYSIWYG',
      docName,
      mountId,
    });
    const onTransaction = (arg: unknown) => {
      const { transaction } = arg as { transaction: PMTransaction };
      if (!transaction.docChanged) return;
      if (!isUserIntentOrigin(transaction)) return;
      sampler.recordUserInput(0, 1);
    };
    editor.on('transaction', onTransaction);
    return () => {
      editor.off('transaction', onTransaction);
      sampler.detach();
    };
  }, [editor, provider]);

  useEffect(() => {
    const mark = () => markUserTyping();
    let attachedDom: HTMLElement | null = null;
    const attach = () => {
      if (attachedDom || editor.isDestroyed) return;
      const view = getEditorView(editor);
      if (!view) return;
      attachedDom = view.dom;
      attachedDom.addEventListener('keydown', mark);
      attachedDom.addEventListener('paste', mark);
      attachedDom.addEventListener('drop', mark);
      attachedDom.addEventListener('cut', mark);
    };
    const detach = () => {
      if (!attachedDom) return;
      attachedDom.removeEventListener('keydown', mark);
      attachedDom.removeEventListener('paste', mark);
      attachedDom.removeEventListener('drop', mark);
      attachedDom.removeEventListener('cut', mark);
      attachedDom = null;
    };
    const isMounted = !!getEditorView(editor);
    if (isMounted) {
      attach();
    } else {
      editor.on('create', attach);
    }
    return () => {
      editor.off('create', attach);
      detach();
    };
  }, [editor]);

  useEffect(() => {
    return () => {
      if (editor.isDestroyed || !getEditorView(editor)) return;
      editor.commands.setMeta('hideDragHandle', true);
    };
  }, [editor]);

  useEffect(() => {
    const docName = provider.configuration.name;
    if (!docName) return;
    const onTransaction = ({ transaction }: { transaction: PMTransaction }) => {
      if (!isUserIntentPmTransaction(transaction)) return;
      requestPreviewTabPromotion(docName);
    };
    editor.on('transaction', onTransaction);
    return () => {
      editor.off('transaction', onTransaction);
    };
  }, [editor, provider]);

  useEffect(() => {
    const focusIfClaimed = () => {
      if (editor.isDestroyed || !getEditorView(editor)) return;
      if (claimNoteWindowInitialFocus()) editor.commands.focus();
    };
    if (getEditorView(editor)) {
      focusIfClaimed();
    } else {
      editor.on('create', focusIfClaimed);
    }
    return () => {
      editor.off('create', focusIfClaimed);
    };
  }, [editor]);

  useEffect(() => {
    let fired = false;
    const consume = () => {
      if (fired || editor.isDestroyed) return;
      if (!getEditorView(editor)) return;
      fired = true;
      const selection = peekRenameSnapshot(docName)?.selection ?? null;
      if (selection) {
        try {
          const docSize = editor.state.doc.content.size;
          if (selection.type === 'text') {
            const anchor = Math.max(0, Math.min(selection.anchor, docSize));
            const head = Math.max(0, Math.min(selection.head, docSize));
            editor.commands.setTextSelection({ from: anchor, to: head });
          } else {
            const from = Math.max(0, Math.min(selection.from, docSize));
            editor.commands.setNodeSelection(from);
          }
        } catch (err) {
          const message = err instanceof Error ? err.message : String(err);
          console.warn(
            JSON.stringify({ event: 'ok-editor-selection-restore-failed', docName, message }),
          );
          mark('ok/editor/selection-restore-failed', { docName, message });
        }
      }
      clearRenameSnapshot(docName);
    };
    if (getEditorView(editor)) {
      consume();
      return undefined;
    }
    editor.on('create', consume);
    return () => {
      editor.off('create', consume);
    };
  }, [editor, docName]);

  useEffect(() => {
    const activityMap = provider.document.getMap('agent-flash');
    let lastSeenTimestamp = Date.now();
    let lastFlashTime = 0;
    let pendingTimeout: number | null = null;
    let flashEndTimeout: number | null = null;
    let flashSettledTimeout: number | null = null;

    const getLatestActivity = (): {
      agentId: string;
      type: string;
      description?: string;
    } | null => {
      let latest: {
        agentId: string;
        type: string;
        description?: string;
        timestamp: number;
      } | null = null;
      for (const [, value] of activityMap.entries()) {
        const entry = value as {
          agentId?: string;
          timestamp?: number;
          type?: string;
          description?: string;
        };
        if (entry.timestamp && (!latest || entry.timestamp > latest.timestamp)) {
          latest = {
            agentId: entry.agentId ?? 'unknown',
            timestamp: entry.timestamp,
            type: entry.type ?? 'insert',
            description: entry.description,
          };
        }
      }
      return latest;
    };

    const applyFlashStateToDom = (state: AgentFlashState) => {
      flashStateRef.current = state;
      if (import.meta.env.DEV) {
        window.__agentFlashState = state;
      }
      const el = wrapperRef.current;
      if (el) {
        el.setAttribute('data-agent-flash-state', state.state);
        el.setAttribute('data-agent-flash-count', String(state.count));
        el.setAttribute('data-agent-flash-position', state.position);
        el.setAttribute('data-agent-flash-agent-id', state.lastAgentId ?? '');
      }
    };

    const triggerFlash = () => {
      const latest = getLatestActivity();
      const position: 'append' | 'prepend' = latest?.description?.toLowerCase().includes('prepend')
        ? 'prepend'
        : 'append';

      const nextState: AgentFlashState = {
        state: 'editing',
        count: (flashStateRef.current?.count ?? 0) + 1,
        lastFiredAt: Date.now(),
        position,
        lastAgentId: latest?.agentId ?? null,
      };

      applyFlashStateToDom(nextState);
      document.dispatchEvent(new CustomEvent('agent-flash', { detail: nextState }));

      if (flashEndTimeout) clearTimeout(flashEndTimeout);
      if (flashSettledTimeout) clearTimeout(flashSettledTimeout);

      flashEndTimeout = window.setTimeout(() => {
        const settledState: AgentFlashState = { ...nextState, state: 'settled' };
        applyFlashStateToDom(settledState);
        document.dispatchEvent(new CustomEvent('agent-flash-end', { detail: settledState }));

        flashSettledTimeout = window.setTimeout(() => {
          applyFlashStateToDom({ ...settledState, state: 'idle' });
        }, 300);
      }, FLASH_DURATION_MS);
    };

    applyFlashStateToDom(INITIAL_FLASH_STATE);

    const observer = () => {
      evictStaleEntries(activityMap);

      if (!hasNewEntries(activityMap, lastSeenTimestamp)) return;

      if (document.visibilityState !== 'visible') return;

      const now = Date.now();
      lastSeenTimestamp = now;

      if (now - lastFlashTime < FLASH_DEBOUNCE_MS) {
        if (!pendingTimeout) {
          const delay = FLASH_DEBOUNCE_MS - (now - lastFlashTime);
          pendingTimeout = window.setTimeout(() => {
            pendingTimeout = null;
            lastFlashTime = Date.now();
            triggerFlash();
          }, delay);
        }
        return;
      }

      lastFlashTime = now;
      triggerFlash();
    };

    activityMap.observe(observer);

    const visibilityHandler = () => {
      if (document.visibilityState === 'visible') {
        if (hasNewEntries(activityMap, lastSeenTimestamp)) {
          lastSeenTimestamp = Date.now();
          lastFlashTime = Date.now();
          triggerFlash();
        }
      } else {
        lastSeenTimestamp = Date.now();
      }
    };
    document.addEventListener('visibilitychange', visibilityHandler);

    return () => {
      activityMap.unobserve(observer);
      document.removeEventListener('visibilitychange', visibilityHandler);
      if (pendingTimeout) clearTimeout(pendingTimeout);
      if (flashEndTimeout) clearTimeout(flashEndTimeout);
      if (flashSettledTimeout) clearTimeout(flashSettledTimeout);
    };
  }, [provider.document, flashStateRef, wrapperRef]);

  const lastAgentFlashKeyRef = useRef<string | null>(null);
  useEffect(() => {
    const plugin = createAgentInsertFlashPlugin();
    const activityMap = provider.document.getMap('agent-flash');
    let sweepTimeout: number | null = null;
    let disposed = false;
    queueMicrotask(() => {
      if (disposed || editor.isDestroyed) return;
      editor.registerPlugin(plugin);
    });
    const followUpTimers: number[] = [];
    const liveView = (): PMEditorView | null =>
      (editor as unknown as { editorView?: PMEditorView }).editorView ?? null;

    const flashAndScroll = (
      view: PMEditorView,
      from: number,
      to: number,
      followChange: boolean,
    ): void => {
      view.dispatch(
        view.state.tr.setMeta(agentInsertFlashKey, { add: { from, to }, now: Date.now() }),
      );
      if (sweepTimeout !== null) clearTimeout(sweepTimeout);
      sweepTimeout = window.setTimeout(() => {
        sweepTimeout = null;
        const sweepView = liveView();
        if (sweepView == null) return;
        sweepView.dispatch(
          sweepView.state.tr.setMeta(agentInsertFlashKey, { now: Date.now(), sweep: true }),
        );
      }, AGENT_INSERT_FLASH_MS + 50);

      if (!followChange || !loadFollowFilePref()) return;
      if (document.visibilityState !== 'visible') return;
      if (view.hasFocus()) return;
      if (view.dom.closest('[data-editor-pane-panel][inert]')) return;
      const elementAtPos = (sv: PMEditorView, pos: number): HTMLElement | null => {
        try {
          const domRef = sv.domAtPos(pos);
          const node = domRef.node;
          const raw =
            node.nodeType === Node.TEXT_NODE
              ? node.parentElement
              : (node.childNodes[domRef.offset] ?? node);
          return raw instanceof HTMLElement ? raw : (raw?.parentElement ?? null);
        } catch {
          return null;
        }
      };
      const scrollToChange = (): void => {
        const sv = liveView();
        if (
          sv == null ||
          sv.hasFocus() ||
          document.visibilityState !== 'visible' ||
          sv.dom.closest('[data-editor-pane-panel][inert]')
        )
          return;
        if (isScrollRestoreSuppressed(docName)) return;
        const docSize = sv.state.doc.content.size;
        const clamp = (pos: number): number => Math.max(0, Math.min(pos, docSize - 1));
        let start: { top: number; bottom: number };
        let end: { top: number; bottom: number };
        try {
          start = sv.coordsAtPos(clamp(from));
          end = sv.coordsAtPos(clamp(to));
        } catch {
          return;
        }
        const range = {
          top: Math.min(start.top, end.top),
          bottom: Math.max(start.bottom, end.bottom),
        };
        if (changedRangeIsOnScreen(range, editorVisibleBand(editor))) return;
        const target = elementAtPos(sv, clamp(Math.floor((from + to) / 2)));
        if (target === null) return;
        target.scrollIntoView({ block: 'center', behavior: 'smooth' });
      };
      requestAnimationFrame(scrollToChange);
      followUpTimers.push(
        window.setTimeout(scrollToChange, 250),
        window.setTimeout(scrollToChange, 550),
      );
    };

    const onTransaction = ({ transaction }: { transaction: PMTransaction }) => {
      if (!transaction.docChanged) return;
      const syncMeta = transaction.getMeta(ySyncPluginKey) as
        | { isChangeOrigin?: boolean }
        | undefined;
      if (syncMeta?.isChangeOrigin !== true) return;
      if (!hasNewEntries(activityMap, Date.now() - AGENT_INSERT_FLASH_MS)) return;
      if (docName !== activeDocName) return;
      const fresh = freshestFlashEntry(activityMap, Date.now() - AGENT_INSERT_FLASH_MS);
      if (fresh !== null && fresh.key === lastAgentFlashKeyRef.current) return;
      const range = computeChangedRange(transaction.before, transaction.doc);
      if (range === null) return;
      const view = liveView();
      if (view == null) return;
      if (fresh !== null) lastAgentFlashKeyRef.current = fresh.key;
      flashAndScroll(view, range.from, range.to, true);
    };
    editor.on('transaction', onTransaction);

    const replayFromEntry = (): void => {
      if (disposed || docName !== activeDocName) return;
      const view = liveView();
      if (view == null) return;
      const fresh = freshestFlashEntry(activityMap, Date.now() - AGENT_INSERT_FLASH_ACTIVATION_MS);
      if (fresh === null || fresh.key === lastAgentFlashKeyRef.current) return;
      const blocks = fresh.entry.changedBlocks;
      if (blocks === undefined) return;
      const range = blockRangeToPositions(view.state.doc, blocks.from, blocks.to);
      if (range === null) return;
      lastAgentFlashKeyRef.current = fresh.key;
      flashAndScroll(
        view,
        range.from,
        range.to,
        view.dom.closest('[data-editor-pane-projected]') === null,
      );
    };
    const activationRaf = requestAnimationFrame(replayFromEntry);
    const onSynced = (): void => {
      requestAnimationFrame(replayFromEntry);
    };
    provider.on('synced', onSynced);

    return () => {
      disposed = true;
      editor.off('transaction', onTransaction);
      provider.off('synced', onSynced);
      cancelAnimationFrame(activationRaf);
      if (sweepTimeout !== null) clearTimeout(sweepTimeout);
      for (const timer of followUpTimers) clearTimeout(timer);
      editor.unregisterPlugin(agentInsertFlashKey);
    };
  }, [editor, provider.document, docName, activeDocName, provider.on, provider.off]);

  useEffect(() => {
    if (isSourceMode) return;
    let attempts = 0;
    let timeoutId: number | undefined;
    let pendingAnchor: string | null = null;
    let pendingHash: string | null = null;
    let handledHash: string | null = null;

    function retryOrGiveUp() {
      if (attempts < ANCHOR_SCROLL_MAX_ATTEMPTS) {
        attempts += 1;
        timeoutId = window.setTimeout(tryScroll, ANCHOR_SCROLL_RETRY_MS);
        return;
      }
      pendingAnchor = null;
      pendingHash = null;
      attempts = 0;
    }

    function scrollAnchorIntoView(anchor: string): boolean {
      const realView = getEditorView(editor);
      const el = realView ? findAnchorTarget(realView.dom, anchor) : null;
      if (!el) return false;
      return runScrollNavigation(docName, 'deep-link', () => {
        el.scrollIntoView({ behavior: 'smooth', block: 'start' });
      });
    }

    function scheduleFollowUpScroll(anchor: string, hash: string) {
      let remaining = ANCHOR_SCROLL_FOLLOW_UP_ATTEMPTS;
      const followUp = () => {
        timeoutId = undefined;
        if (docName !== activeDocName || window.location.hash !== hash) return;
        scrollAnchorIntoView(anchor);
        remaining -= 1;
        if (remaining > 0) {
          timeoutId = window.setTimeout(followUp, ANCHOR_SCROLL_FOLLOW_UP_MS);
        }
      };
      timeoutId = window.setTimeout(followUp, ANCHOR_SCROLL_FOLLOW_UP_MS);
    }

    function tryScroll() {
      if (!pendingAnchor) return;
      if (docName !== activeDocName) return;
      const anchor = pendingAnchor;
      const hash = pendingHash;
      if (!hash) {
        retryOrGiveUp();
        return;
      }
      if (scrollAnchorIntoView(anchor)) {
        handledHash = hash;
        pendingAnchor = null;
        pendingHash = null;
        attempts = 0;
        scheduleFollowUpScroll(anchor, hash);
      } else {
        retryOrGiveUp();
      }
    }

    function scheduleScrollFromHash() {
      if (docName !== activeDocName) return;
      const hash = window.location.hash;
      if (!pendingAnchor && handledHash === hash) return;
      const anchor = anchorFromHash(hash);
      if (!anchor) {
        handledHash = hash;
        return;
      }
      pendingAnchor = anchor;
      pendingHash = hash;
      attempts = 0;
      if (timeoutId !== undefined) {
        clearTimeout(timeoutId);
        timeoutId = undefined;
      }
      tryScroll();
    }

    function retryPendingOrSchedule() {
      if (docName !== activeDocName) return;
      if (pendingAnchor) {
        tryScroll();
        return;
      }
      scheduleScrollFromHash();
    }

    function repeatScrollFromHash() {
      handledHash = null;
      scheduleScrollFromHash();
    }

    scheduleScrollFromHash();
    provider.on('synced', retryPendingOrSchedule);
    editor.on('transaction', retryPendingOrSchedule);
    window.addEventListener('hashchange', scheduleScrollFromHash);
    window.addEventListener(REPEAT_ANCHOR_NAV_EVENT, repeatScrollFromHash);

    return () => {
      if (timeoutId !== undefined) clearTimeout(timeoutId);
      provider.off('synced', retryPendingOrSchedule);
      editor.off('transaction', retryPendingOrSchedule);
      window.removeEventListener('hashchange', scheduleScrollFromHash);
      window.removeEventListener(REPEAT_ANCHOR_NAV_EVENT, repeatScrollFromHash);
    };
  }, [provider, editor, docName, activeDocName, isSourceMode]);

  useEffect(() => {
    if (isSourceMode) return;
    let settleTimer: ReturnType<typeof setTimeout> | undefined;

    function onNav(e: Event) {
      const detail = (e as CustomEvent<OutlineNavDetail>).detail;
      if (!detail || detail.docName !== docName || detail.mode !== 'wysiwyg' || editor.isDestroyed)
        return;
      const trace = { docName, mode: 'wysiwyg', index: detail.index };
      const realView = getEditorView(editor);
      if (!realView) {
        emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, { ...trace, outcome: 'no-view' });
        return;
      }
      const scroller = editorScrollContainerOf(realView.dom);
      const headings = realView.dom.querySelectorAll<HTMLElement>('h1, h2, h3, h4, h5, h6');
      const resolved = {
        ...trace,
        scrollTopBefore: scroller?.scrollTop,
        domHeadingCount: headings.length,
        slugFoundAt: Array.from(headings).findIndex((h) => h.id === detail.slug),
      };
      const target = headings[detail.index];
      if (!target) {
        emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, { ...resolved, outcome: 'no-target' });
        return;
      }
      const targetTop = () =>
        scroller === null || !scroller.isConnected || !target.isConnected
          ? undefined
          : Math.round(target.getBoundingClientRect().top - scroller.getBoundingClientRect().top);
      const targetTopBefore = targetTop();
      const scrollHeightBefore = scroller?.scrollHeight;
      const claimed = runScrollNavigation(docName, 'outline', () => {
        target.scrollIntoView({ behavior: 'smooth', block: 'start' });
      });
      emitDiagnosticBreadcrumb(OUTLINE_NAV_BREADCRUMB, {
        ...resolved,
        outcome: claimed ? 'scrolled' : 'declined',
        resolvedLevel: Number(target.tagName.slice(1)),
        targetTopBefore,
        scrollHeightBefore,
      });
      if (!claimed) return;
      detail.onNavigated?.(realView.dom);
      clearTimeout(settleTimer);
      settleTimer = setTimeout(() => {
        emitDiagnosticBreadcrumb(OUTLINE_NAV_SETTLED_BREADCRUMB, {
          docName,
          mode: 'wysiwyg',
          index: detail.index,
          scrollTopAfter: scroller?.isConnected === true ? scroller.scrollTop : undefined,
          scrollHeightAfter: scroller?.isConnected === true ? scroller.scrollHeight : undefined,
          targetTopAfter: targetTop(),
          scrollerDetached: scroller !== null && !scroller.isConnected,
          targetDetached: !target.isConnected,
        });
      }, OUTLINE_NAV_SETTLE_MS);
    }
    window.addEventListener(OUTLINE_NAV_EVENT, onNav);
    return () => {
      window.removeEventListener(OUTLINE_NAV_EVENT, onNav);
      clearTimeout(settleTimer);
    };
  }, [editor, docName, isSourceMode]);

  useEffect(() => {
    const awareness = provider.awareness;
    if (!awareness) return;
    if (docName !== activeDocName) {
      awareness.setLocalState(null);
      return;
    }
    awareness.setLocalState({
      user: buildAwarenessUser({ principal, identity }),
      mode: isSourceMode ? 'source' : 'wysiwyg',
    });
    const heartbeat = getAwarenessHeartbeat();
    heartbeat.start();
    heartbeat.setAwareness(awareness);
    return () => heartbeat.clearAwareness(awareness);
  }, [provider, docName, activeDocName, identity, principal, isSourceMode]);

  useEffect(() => {
    setEditorSourceMode(editor, isSourceMode);
    return () => {
      setEditorSourceMode(editor, false);
    };
  }, [editor, isSourceMode]);

  useLayoutEffect(() => {
    setEditorSingleFileMode(editor, singleFile);
    return () => setEditorSingleFileMode(editor, false);
  }, [editor, singleFile]);

  return (
    <div
      ref={wrapperRef}
      className="tiptap-editor h-full"
      data-agent-flash-state="idle"
      data-agent-flash-count="0"
      data-agent-flash-position="append"
      data-agent-flash-agent-id=""
    >
      {!isSourceMode && editorPaneOnScreen && (
        <BubbleMenuBar editor={editor} shortcutEnabled={docName === activeDocName} />
      )}
      {!isSourceMode && (
        <CommentsBoundary>
          <CommentSelectionAffordance
            editor={editor}
            docName={docName}
            shortcutEnabled={docName === activeDocName}
          />
          <CommentAnchorLayer editor={editor} docName={docName} />
          {docName === activeDocName && <CommentMarginRail editor={editor} docName={docName} />}
        </CommentsBoundary>
      )}
      {!isSourceMode && <TableCellHandles editor={editor} />}
      <div ref={portalSlotRef} style={{ display: 'contents' }} />
      {createPortal(
        // oxlint-disable-next-line ok/no-unportaled-editor-content -- canonical portaled site — H6 fix per PRECEDENTS.md #44
        <EditorContent
          key={editorContentRevision}
          editor={editor}
          className="tiptap-editor-portal-content h-full"
        />,
        portalTarget,
      )}
      <SelectionAnnouncer editor={editor} />
      <InteractionLayerView
        /**
         * RawMdxFallback renders inline via `RawMdxFallbackCMView` (precedent #30) and never
         * registers with InteractionLayer.
         */
        store={getInteractionLayer(editor).store}
      />
    </div>
  );
};

declare global {
  interface Window {
    __agentFlashState?: AgentFlashState;
  }
}