@k2b/editor 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,16 @@
+export { ariaShortcut, isApple, markdownActions, shortcutLabel } from "./actions";
+export { BubbleMenu, type BubbleMenuProps } from "./BubbleMenu";
+export { Editor, type EditorProps } from "./Editor";
+export { asUndoStep, createEditor, type EditorAction, type EditorHandle } from "./editor-state";
+export { editorMessages } from "./messages";
+export { SlashMenu, type SlashMenuProps } from "./SlashMenu";
+export { type SlashAction, type SlashMenuOptions, slashCompletionSource, slashMenu } from "./slash-menu";
+export {
+  Toolbar,
+  ToolbarButton,
+  type ToolbarCustom,
+  type ToolbarGroup,
+  type ToolbarItem,
+  type ToolbarMenu,
+  type ToolbarProps,
+} from "./Toolbar";

package/src/markdown/_lib/cursor-zone-field.ts

@@ -0,0 +1,338 @@
+/**
+ * Cursor-zone StateField — shared by editor decoration pipelines
+ * that rebuild on doc changes OR when the cursor crosses a "zone"
+ * boundary (entered, left, or moved between zones).
+ *
+ * # Two modes
+ *
+ * The field supports two operating modes:
+ *
+ *  - **Default mode** (no `incremental` option): rebuild on every
+ *    doc change and every newly delivered syntax tree, rebuild on
+ *    selection changes that cross a range boundary. Used by
+ *    image/link extensions whose `build` already walks the syntax
+ *    tree incrementally — a full call is cheap.
+ *
+ *  - **Incremental mode** (with `incremental.changesMightAffectSyntax`):
+ *    on doc change, skip the rebuild when the doc has no relevant
+ *    marker syntax AND the change doesn't introduce any, OR when
+ *    the existing ranges are unaffected by the change. A newly
+ *    delivered syntax tree always rebuilds, also when it arrives
+ *    with a doc change that carries it past its old end. Used by
+ *    extensions whose `build` does a full `doc.toString() +
+ *    regex.matchAll()` pass (katex, tag-pill) — those
+ *    rebuilds are expensive enough to be worth gating.
+ *
+ * Each caller (images, links, tag-pill, info-blocks, katex) tracks
+ * the source-byte ranges where editing should reveal raw markdown
+ * source instead of the rendered widget. Without the cursor-zone
+ * gate, every plain cursor move through prose would re-walk the
+ * syntax tree / re-scan the doc text — visibly laggy on long notes.
+ *
+ * # State shape
+ *
+ * Callers return `{ decorations, ranges, hasSyntax? }` from `build`.
+ * `hasSyntax` only matters in incremental mode; default mode
+ * ignores it.
+ *
+ * NOTE: `tables.ts` does NOT use this helper — its state carries
+ * an extra cached `blockWidgetDecorations` field that doesn't fit
+ * the standard shape.
+ */
+import { forceParsing, syntaxTree } from "@codemirror/language";
+import type { EditorState, Extension, SelectionRange, Transaction } from "@codemirror/state";
+import { Prec, StateEffect, StateField } from "@codemirror/state";
+import type { DecorationSet } from "@codemirror/view";
+import { Decoration, EditorView, keymap, ViewPlugin } from "@codemirror/view";
+
+export type CursorZoneRange = { from: number; to: number };
+
+export type CursorZoneState = {
+  decorations: DecorationSet;
+  /** Optional subset of replacement decorations that should behave
+   *  atomically for cursor movement. Use this for block widgets that
+   *  hide source text; it prevents CM from resolving mouse/vertical
+   *  navigation into the replaced source range. */
+  atomicDecorations?: DecorationSet;
+  /** Source-byte ranges where the cursor "activates" the source
+   *  (i.e. hides the widget so the user can edit raw markdown). */
+  ranges: CursorZoneRange[];
+  /** Incremental mode only: `true` if the doc currently contains
+   *  any relevant marker syntax. Lets the field skip the rebuild
+   *  when both this AND the per-change predicate return falsy. */
+  hasSyntax?: boolean;
+};
+
+export type IncrementalOptions = {
+  /** Cheap predicate run on every doc-change transaction. Returns
+   *  `true` if the inserted text OR a small window around the
+   *  change might introduce / remove relevant marker syntax.
+   *
+   *  Bias: when in doubt, return `true` — a false positive only
+   *  costs a rebuild (back to baseline). A false negative leaves
+   *  decorations stale, so the predicate MUST be conservative. */
+  changesMightAffectSyntax: (tr: Transaction) => boolean;
+};
+
+export const selectionIntersectsRange = (selection: SelectionRange, from: number, to: number): boolean => {
+  if (selection.empty) return selection.from >= from && selection.to <= to;
+  return selection.from < to && selection.to > from;
+};
+
+export const isPointerSelectionTransaction = (tr: Transaction): boolean =>
+  !tr.docChanged && !!tr.selection && tr.isUserEvent("select.pointer");
+
+/** True when a transaction changed the document or delivered a new syntax tree.
+ *  CodeMirror parses a long note in steps and hands each further part of the tree
+ *  over in a transaction without a document change, so a decoration field that
+ *  reads the tree must rebuild on both. Selection and focus transactions keep the
+ *  same tree and stay cheap. */
+export const treeOrDocChanged = (tr: Transaction): boolean => tr.docChanged || syntaxTree(tr.startState) !== syntaxTree(tr.state);
+
+export const refreshMarkdownDecorationsEffect = StateEffect.define<void>();
+
+export const pointerSelectionHoldEffect = StateEffect.define<boolean>();
+
+/** True while a mouse or pen button is down in the editor. Revealing Markdown then would move the text under the
+ *  pointer mid-drag, so selection-driven decorations wait for the refresh after release. */
+export const pointerSelectionHeld = StateField.define<boolean>({
+  create: () => false,
+  update(value, tr) {
+    for (const effect of tr.effects) {
+      if (effect.is(refreshMarkdownDecorationsEffect)) return false;
+      if (effect.is(pointerSelectionHoldEffect)) value = effect.value;
+    }
+    return value;
+  },
+});
+
+export const holdsDecorations = (tr: Transaction): boolean =>
+  tr.startState.field(pointerSelectionHeld, false) === true &&
+  tr.state.field(pointerSelectionHeld, false) === true &&
+  isPointerSelectionTransaction(tr);
+
+export const initialMarkdownDecorationRefreshExtension = (): Extension =>
+  ViewPlugin.fromClass(
+    class {
+      private raf: number | null = null;
+      private attempts = 0;
+
+      constructor(private view: EditorView) {
+        this.schedule();
+      }
+
+      private schedule() {
+        this.raf = window.requestAnimationFrame(() => {
+          this.raf = null;
+          this.attempts += 1;
+          // Markdown parsing is viewport/background-driven. Force the parse
+          // to the end after mount so syntax-tree based widgets don't stay raw
+          // until the parser reaches them. forceParsing hands a newer tree over
+          // in a transaction, and every tree-based field rebuilds on it.
+          const parsed = forceParsing(this.view, this.view.state.doc.length, 50);
+          if (!parsed && this.attempts < 4) this.schedule();
+        });
+      }
+
+      destroy() {
+        if (this.raf !== null) window.cancelAnimationFrame(this.raf);
+      }
+    },
+  );
+
+export const pointerSelectionMarkdownRefreshExtension = (): Extension => [
+  pointerSelectionHeld,
+  ViewPlugin.fromClass(
+    class {
+      private timeout: number | null = null;
+
+      constructor(private view: EditorView) {
+        view.contentDOM.addEventListener("pointerdown", this.onPointerDown);
+        document.addEventListener("pointerup", this.onPointerDone);
+        document.addEventListener("pointercancel", this.onPointerDone);
+      }
+
+      private onPointerDown = (event: PointerEvent) => {
+        // Native touch selection must keep working on phones, without a hold.
+        if (event.pointerType === "touch" || event.button !== 0) return;
+        if (this.timeout !== null) window.clearTimeout(this.timeout);
+        this.timeout = null;
+        this.view.dispatch({ effects: pointerSelectionHoldEffect.of(true) });
+      };
+
+      private onPointerDone = () => {
+        if (!this.view.state.field(pointerSelectionHeld) || this.timeout !== null) return;
+        this.timeout = window.setTimeout(() => {
+          this.timeout = null;
+          this.view.dispatch({ effects: refreshMarkdownDecorationsEffect.of() });
+        }, 0);
+      };
+
+      destroy() {
+        this.view.contentDOM.removeEventListener("pointerdown", this.onPointerDown);
+        document.removeEventListener("pointerup", this.onPointerDone);
+        document.removeEventListener("pointercancel", this.onPointerDone);
+        if (this.timeout !== null) window.clearTimeout(this.timeout);
+      }
+    },
+  ),
+];
+
+export const blockWidgetLineNavigationExtension = <T>(
+  field: StateField<T>,
+  getBlockDecorations: (value: T) => DecorationSet | undefined,
+): Extension => {
+  const findWidgetRange = (set: DecorationSet | undefined, from: number, to: number): CursorZoneRange | null => {
+    let found: CursorZoneRange | null = null;
+    set?.between(from, to, (decoFrom, decoTo) => {
+      found = { from: decoFrom, to: decoTo };
+      return false;
+    });
+    return found;
+  };
+
+  const navigateLine = (view: EditorView, dir: -1 | 1, extend: boolean): boolean => {
+    const value = view.state.field(field, false);
+    if (!value) return false;
+    const blockDecorations = getBlockDecorations(value);
+    if (!blockDecorations || blockDecorations === Decoration.none) return false;
+
+    const sel = view.state.selection.main;
+    const caretLine = view.state.doc.lineAt(sel.head);
+    const caretCol = sel.head - caretLine.from;
+    let targetLineNumber = caretLine.number + dir;
+    let skippedWidget = false;
+
+    while (targetLineNumber >= 1 && targetLineNumber <= view.state.doc.lines) {
+      const line = view.state.doc.line(targetLineNumber);
+      const widget = findWidgetRange(blockDecorations, line.from, line.to);
+      if (!widget) break;
+      skippedWidget = true;
+      const widgetStartLine = view.state.doc.lineAt(widget.from).number;
+      const widgetEndLine = view.state.doc.lineAt(widget.to).number;
+      targetLineNumber = dir < 0 ? widgetStartLine - 1 : widgetEndLine + 1;
+    }
+    if (!skippedWidget) return false;
+
+    const target =
+      targetLineNumber < 1
+        ? 0
+        : targetLineNumber > view.state.doc.lines
+          ? view.state.doc.length
+          : view.state.doc.line(targetLineNumber).from + Math.min(caretCol, view.state.doc.line(targetLineNumber).length);
+
+    view.dispatch({
+      selection: extend ? { anchor: sel.anchor, head: target } : { anchor: target },
+      scrollIntoView: true,
+      userEvent: "select",
+    });
+    return true;
+  };
+
+  return Prec.highest(
+    keymap.of([
+      { key: "ArrowUp", run: (view) => navigateLine(view, -1, false) },
+      { key: "Shift-ArrowUp", run: (view) => navigateLine(view, -1, true) },
+      { key: "ArrowDown", run: (view) => navigateLine(view, 1, false) },
+      { key: "Shift-ArrowDown", run: (view) => navigateLine(view, 1, true) },
+    ]),
+  );
+};
+
+/** Identity of the range the cursor currently sits inside, or
+ *  `null` if it sits outside all ranges. A cursor-only transaction
+ *  needs a rebuild only when this answer changes. */
+const cursorKey = (state: EditorState, ranges: CursorZoneRange[]): string | null => {
+  if (ranges.length === 0) return null;
+  const cursor = state.selection.main;
+  const hits: number[] = [];
+  for (const r of ranges) {
+    if (selectionIntersectsRange(cursor, r.from, r.to)) hits.push(r.from);
+  }
+  return hits.length > 0 ? hits.sort((a, b) => a - b).join(",") : null;
+};
+
+const intersectsAnyRange = (ranges: CursorZoneRange[], from: number, to: number): boolean =>
+  ranges.some((r) => (from >= r.from && from < r.to) || (to > r.from && to <= r.to) || (from <= r.from && to >= r.to));
+
+/** True if any of the transaction's changed regions intersects (or
+ *  touches the boundary of) one of `ranges`. Pre-change positions
+ *  are used because `ranges` haven't been mapped through `tr` yet. */
+const changesIntersectRanges = (tr: Transaction, ranges: CursorZoneRange[]): boolean => {
+  if (ranges.length === 0) return false;
+  let intersects = false;
+  tr.changes.iterChangedRanges((fromA, toA) => {
+    if (intersects) return;
+    intersects = intersectsAnyRange(ranges, fromA, toA) || ranges.some((r) => fromA === r.from || fromA === r.to);
+  });
+  return intersects;
+};
+
+/** Map pre-change ranges through a transaction's changes so they
+ *  reflect the post-change document. `from` biases right, `to`
+ *  biases left — keeps the range tight around the original span. */
+const mapRanges = (tr: Transaction, ranges: CursorZoneRange[]): CursorZoneRange[] =>
+  ranges
+    .map((r) => ({
+      from: tr.changes.mapPos(r.from, 1),
+      to: tr.changes.mapPos(r.to, -1),
+    }))
+    .filter((r) => r.from < r.to);
+
+/** True when a doc change also carried the syntax tree past the end of the previous,
+ *  partial tree. CodeMirror parses up to the viewport while it applies an edit, so an
+ *  edit after a jump into the unparsed end of a long note can bring new code or math
+ *  nodes that the incremental skip checks can't see. */
+const treeGrewPastOldEnd = (tr: Transaction): boolean =>
+  syntaxTree(tr.state).length > tr.changes.mapPos(syntaxTree(tr.startState).length, 1);
+
+export const cursorZoneStateField = (
+  build: (state: EditorState) => CursorZoneState,
+  incremental?: IncrementalOptions,
+): StateField<CursorZoneState> => {
+  return StateField.define<CursorZoneState>({
+    create: build,
+    update(value, tr) {
+      if (tr.effects.some((effect) => effect.is(refreshMarkdownDecorationsEffect))) {
+        return build(tr.state);
+      }
+      if (tr.docChanged) {
+        if (incremental && !treeGrewPastOldEnd(tr)) {
+          const decorations = value.decorations.map(tr.changes);
+          const atomicDecorations = value.atomicDecorations?.map(tr.changes);
+          const mightAffect = incremental.changesMightAffectSyntax(tr);
+          // No syntax anywhere AND change doesn't introduce any →
+          // nothing to scan, just keep an empty state.
+          if (!value.hasSyntax && !mightAffect) {
+            return { decorations, atomicDecorations, ranges: [], hasSyntax: false };
+          }
+          // Have syntax, change misses the ranges AND introduces
+          // no new markers → keep current decorations, just remap
+          // range positions through the change.
+          if (value.hasSyntax && !changesIntersectRanges(tr, value.ranges) && !mightAffect) {
+            return {
+              decorations,
+              atomicDecorations,
+              ranges: mapRanges(tr, value.ranges),
+              hasSyntax: true,
+            };
+          }
+        }
+        return build(tr.state);
+      }
+      if (treeOrDocChanged(tr)) return build(tr.state);
+      if (holdsDecorations(tr)) return value;
+      if (!tr.selection) return value;
+      const oldKey = cursorKey(tr.startState, value.ranges);
+      const newKey = cursorKey(tr.state, value.ranges);
+      if (oldKey === newKey) return value;
+      return build(tr.state);
+    },
+    provide(field) {
+      return [
+        EditorView.decorations.from(field, (v) => v.decorations),
+        EditorView.atomicRanges.of((view) => view.state.field(field).atomicDecorations ?? Decoration.none),
+      ];
+    },
+  });
+};

package/src/markdown/_lib/inline-syntax.ts

@@ -0,0 +1,9 @@
+// Text syntax shared by editor decorations and the server preview.
+export const TAG_REGEX = /(^|\s)#([a-zA-Z][\w-]*(?:\/[\w-]+)*)/g;
+export const MARK_REGEX = /==(?!=)([^\s=][^=]*?[^\s=]|[^\s=])==(?!=)/g;
+export const SUB_REGEX = /(?<!~)~(?!~)([^~\s]+)~(?!~)/g;
+export const SUP_REGEX = /\^([^\^\s]+)\^/g;
+
+// CodeMirror highlightSpecialChars defaults (tabs keep their native tab-size).
+export const SPECIAL_CHAR_REGEX =
+  /[\u0000-\u0008\u000a-\u001f\u007f-\u009f\u00ad\u061c\u200b\u200e\u200f\u2028\u2029\u202d\u202e\u2066\u2067\u2069\ufeff\ufff9-\ufffc]/gu;

package/src/markdown/_lib/link-opener.ts

@@ -0,0 +1,50 @@
+import type { EditorSelection } from "@codemirror/state";
+import type { EditorView } from "@codemirror/view";
+
+/** A pointer that moved further than this between press and click dragged a selection. */
+const CLICK_SLOP_PX = 4;
+
+/**
+ * The element opens its link on click and, where the editor is read-only, from the keyboard as a link.
+ *
+ * A mouse or pen press reaches CodeMirror, so a drag that starts on the element selects text. The pointer hold keeps
+ * the element rendered until release, so a click still lands on it; the click then restores the selection from before
+ * the press and opens the link. A touch press keeps the native tap: it moves no caret, and the tap opens the link.
+ * The widget passes `mousedown` to CodeMirror and ignores every other event.
+ */
+export const makeOpener = (el: HTMLElement, view: EditorView, open: () => void) => {
+  el.classList.add("cm-link-open");
+  el.setAttribute("role", "link");
+  if (view.state.readOnly) el.tabIndex = 0;
+  let touch = false;
+  let press: { x: number; y: number; selection: EditorSelection } | null = null;
+  el.onpointerdown = (e) => {
+    touch = e.pointerType === "touch";
+  };
+  el.onmousedown = (e) => {
+    press = null;
+    if (touch) {
+      e.preventDefault();
+      e.stopPropagation();
+      return;
+    }
+    press = { x: e.clientX, y: e.clientY, selection: view.state.selection };
+  };
+  el.onclick = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    const start = press;
+    press = null;
+    if (start) {
+      if (Math.hypot(e.clientX - start.x, e.clientY - start.y) > CLICK_SLOP_PX) return;
+      view.dispatch({ selection: start.selection });
+    }
+    open();
+  };
+  el.onkeydown = (e) => {
+    if (e.key !== "Enter") return;
+    e.preventDefault();
+    e.stopPropagation();
+    open();
+  };
+};

package/src/markdown/_lib/list-item-line.ts

@@ -0,0 +1,34 @@
+import type { Line } from "@codemirror/state";
+import type { SyntaxNode, Tree } from "@lezer/common";
+import type { ExcludedSpan } from "./list-structure";
+
+export const LIST_ITEM = /^( *)([-*+]|\d{1,9}[.)])( +|$)/;
+const CODE = new Set(["FencedCode", "CodeBlock"]);
+
+export type ListItemLine = { indent: number; content: number; marker: string };
+
+export const leadingWhitespace = (text: string) => text.length - text.trimStart().length;
+
+export const inCode = (tree: Tree, pos: number): boolean => {
+  for (let node: SyntaxNode | null = tree.resolveInner(pos, 1); node; node = node.parent) {
+    if (CODE.has(node.name)) return true;
+  }
+  return false;
+};
+
+/**
+ * A line that starts with a list marker outside code, data and directives. The line text decides, not the parse:
+ * an empty item right after Tab reads as paragraph text until someone types, and Shift+Tab
+ * must still lift it.
+ */
+export const listItemLine = (tree: Tree, line: Line, excluded: () => readonly ExcludedSpan[]): ListItemLine | null => {
+  const match = LIST_ITEM.exec(line.text);
+  if (!match || /^([-*_])(?: *\1){2,} *$/.test(line.text.trimStart())) return null;
+  const indent = match[1]!.length;
+  if (inCode(tree, line.from + indent) || excluded().some((span) => line.from + indent >= span.from && line.from + indent < span.to))
+    return null;
+  const marker = match[2]!.length;
+  const spaces = match[3]!.length;
+  const rest = line.text.length > match[0].length;
+  return { indent, marker: match[2]!, content: indent + marker + (rest && spaces >= 1 && spaces <= 4 ? spaces : 1) };
+};

package/src/markdown/_lib/list-structure.ts

@@ -0,0 +1,227 @@
+/**
+ * The list items of a note as Markdown parses them: real nesting depth, the
+ * number Book shows, and the source ranges of markers and content. Editor
+ * display, renumbering, moving items and list-aware paste share this model.
+ */
+import { syntaxTree } from "@codemirror/language";
+import { type ChangeSet, type ChangeSpec, type EditorState, Facet } from "@codemirror/state";
+import type { Tree } from "@lezer/common";
+
+export type ListItemKind = "bullet" | "ordered" | "task";
+export type ListItem = {
+  /** 1-based marker line and its start position. */
+  line: number;
+  from: number;
+  /** End of the ListItem node, including its descendants. */
+  to: number;
+  depth: number;
+  orderedDepth: number;
+  kind: ListItemKind;
+  ordered: boolean;
+  start: number | null;
+  ordinal: number | null;
+  checked: boolean;
+  markerFrom: number;
+  markerTo: number;
+  taskFrom: number | null;
+  taskTo: number | null;
+  contentFrom: number;
+  parent: number;
+  /** Source identity of the containing list, including separate lists of the same kind. */
+  listFrom: number;
+  /** Index one past the last descendant. */
+  subtreeEnd: number;
+};
+export type ListStructure = { items: readonly ListItem[] };
+export type ExcludedSpan = { from: number; to: number };
+
+export type MarkdownRangeOptions = {
+  /** Source ranges that must keep literal text, such as data or query directives. */
+  excludedRanges?: (markdown: string) => readonly ExcludedSpan[];
+};
+
+/** Shared by list display and commands, including commands used without rich list display. */
+export const listExcludedRanges = Facet.define<NonNullable<MarkdownRangeOptions["excludedRanges"]>>({
+  combine: (values) => [...new Set(values)],
+});
+
+/** Full source scan; callers cache these spans independently of parser progress. */
+export const excludedSpans = (state: EditorState): ExcludedSpan[] =>
+  state.facet(listExcludedRanges).flatMap((ranges) => ranges(state.doc.toString()).map(({ from, to }) => ({ from, to })));
+
+/** Items outside quotes, data blocks and directives. Optional ranges cover whole top-level list blocks; exclusions are read only when a list exists. */
+export const listStructure = (
+  state: EditorState,
+  excludedSpans: () => readonly ExcludedSpan[],
+  range?: ExcludedSpan,
+  tree: Tree = syntaxTree(state),
+): ListStructure => {
+  const items: ListItem[] = [];
+  const parents: Array<{ from: number; index: number }> = [];
+  const lists: Array<{ ordered: boolean; start: number | null; index: number }> = [];
+  tree.iterate({
+    from: range?.from,
+    to: range?.to,
+    enter(ref) {
+      if (ref.name === "Blockquote") return false;
+      const node = ref.node;
+      if (ref.name === "BulletList" || ref.name === "OrderedList") {
+        if (range && (ref.to <= range.from || ref.from >= range.to)) return false;
+        const ordered = ref.name === "OrderedList";
+        const mark = node.getChild("ListItem")?.getChild("ListMark");
+        lists.push({ ordered, start: ordered && mark ? Number.parseInt(state.sliceDoc(mark.from, mark.to), 10) : null, index: 0 });
+      }
+      if (ref.name !== "ListItem" || !["BulletList", "OrderedList"].includes(node.parent?.name ?? "")) return;
+      const list = lists.at(-1);
+      const mark = node.getChild("ListMark");
+      if (!list || !mark) return false;
+      const ordinal = list.start === null ? null : list.start + list.index;
+      list.index++;
+      const line = state.doc.lineAt(mark.from);
+      if (items.at(-1)?.line === line.number || excludedSpans().some((span) => mark.from >= span.from && mark.from < span.to)) return false;
+      const task = node.getChild("Task")?.getChild("TaskMarker");
+      let contentFrom = task?.to ?? mark.to;
+      while (contentFrom < line.to && /[ \t]/.test(state.sliceDoc(contentFrom, contentFrom + 1))) contentFrom++;
+      const parent = parents.at(-1)?.index ?? -1;
+      const ancestor = items[parent];
+      const index = items.length;
+      items.push({
+        line: line.number,
+        from: line.from,
+        to: node.to,
+        depth: parents.length,
+        orderedDepth: ancestor ? ancestor.orderedDepth + Number(ancestor.ordered) : 0,
+        kind: task ? "task" : list.ordered ? "ordered" : "bullet",
+        ordered: list.ordered,
+        start: list.start,
+        ordinal,
+        checked: task ? state.sliceDoc(task.from, task.to) !== "[ ]" : false,
+        markerFrom: mark.from,
+        markerTo: mark.to,
+        taskFrom: task?.from ?? null,
+        taskTo: task?.to ?? null,
+        contentFrom,
+        parent,
+        listFrom: node.parent!.from,
+        subtreeEnd: index + 1,
+      });
+      parents.push({ from: node.from, index });
+    },
+    leave(ref) {
+      if (ref.name === "BulletList" || ref.name === "OrderedList") lists.pop();
+      if (ref.name === "ListItem" && parents.at(-1)?.from === ref.from) {
+        const parent = parents.pop();
+        if (parent) items[parent.index]!.subtreeEnd = items.length;
+      }
+    },
+  });
+  return { items };
+};
+
+/** Rewrite markers and shift continuation text and children by the width delta. Source-only items also cover empty, not-yet-parsed items. */
+export const markerChanges = (
+  state: EditorState,
+  structure: { items: readonly Pick<ListItem, "line" | "to" | "markerFrom" | "markerTo">[] },
+  markers: ReadonlyMap<number, string>,
+): ChangeSet => {
+  const changes: ChangeSpec[] = [];
+  const deltas = new Map<number, number>();
+  for (const [index, marker] of markers) {
+    const item = structure.items[index]!;
+    const old = state.sliceDoc(item.markerFrom, item.markerTo);
+    if (old === marker) continue;
+    let prefix = 0;
+    while (prefix < old.length && prefix < marker.length && old[prefix] === marker[prefix]) prefix++;
+    let suffix = 0;
+    while (
+      suffix < old.length - prefix &&
+      suffix < marker.length - prefix &&
+      old[old.length - suffix - 1] === marker[marker.length - suffix - 1]
+    )
+      suffix++;
+    changes.push({ from: item.markerFrom + prefix, to: item.markerTo - suffix, insert: marker.slice(prefix, marker.length - suffix) });
+    const delta = marker.length - (item.markerTo - item.markerFrom);
+    if (!delta) continue;
+    for (let number = item.line + 1; number <= state.doc.lineAt(item.to).number; number++) {
+      const line = state.doc.line(number);
+      if (line.text.trim()) deltas.set(number, (deltas.get(number) ?? 0) + delta);
+    }
+  }
+  for (const [number, delta] of deltas) {
+    const line = state.doc.line(number);
+    if (delta > 0) changes.push({ from: line.from, insert: " ".repeat(delta) });
+    else if (delta < 0) changes.push({ from: line.from, to: line.from + Math.min(-delta, /^ */.exec(line.text)![0].length) });
+  }
+  return state.changes(changes);
+};
+
+/** Repair only the specified ordered lists, using their supplied starts and preserving delimiters. */
+export const renumberChanges = (state: EditorState, structure: ListStructure, starts: ReadonlyMap<number, number>): ChangeSet => {
+  const markers = new Map<number, string>();
+  structure.items.forEach((item, index) => {
+    const start = starts.get(item.listFrom);
+    if (!item.ordered || start === undefined || item.ordinal === null || item.start === null) return;
+    const written = state.sliceDoc(item.markerFrom, item.markerTo);
+    const marker = `${item.ordinal - item.start + start}${written.at(-1)}`;
+    if (written !== marker) markers.set(index, marker);
+  });
+  return markerChanges(state, structure, markers);
+};
+
+export const siblingIndex = (structure: ListStructure, index: number, direction: 1 | -1): number => {
+  const item = structure.items[index]!;
+  for (let next = direction > 0 ? item.subtreeEnd : index - 1; next >= 0 && next < structure.items.length; next += direction) {
+    const candidate = structure.items[next]!;
+    if (candidate.depth < item.depth) break;
+    if (candidate.depth === item.depth) return candidate.parent === item.parent && candidate.listFrom === item.listFrom ? next : -1;
+  }
+  return -1;
+};
+
+/** Binary search for the item whose marker is on this line. */
+export const listItemAtLine = (structure: ListStructure, line: number): number => {
+  let low = 0;
+  let high = structure.items.length - 1;
+  while (low <= high) {
+    const middle = (low + high) >>> 1;
+    const candidate = structure.items[middle]!;
+    if (candidate.line === line) return middle;
+    if (candidate.line < line) low = middle + 1;
+    else high = middle - 1;
+  }
+  return -1;
+};
+
+const romanDigits: readonly (readonly [number, string])[] = [
+  [1000, "m"],
+  [900, "cm"],
+  [500, "d"],
+  [400, "cd"],
+  [100, "c"],
+  [90, "xc"],
+  [50, "l"],
+  [40, "xl"],
+  [10, "x"],
+  [9, "ix"],
+  [5, "v"],
+  [4, "iv"],
+  [1, "i"],
+];
+
+/** Labels cycle through 1., a., i. for six ordered levels; deeper levels keep roman like Book and the PDF, with CSS's decimal fallback. */
+export const orderedLabel = (ordinal: number, orderedDepth: number): string => {
+  const style = Math.min(orderedDepth, 5) % 3;
+  let label = "";
+  if (style === 1 && ordinal >= 1) {
+    for (let n = ordinal; n > 0; n = Math.floor((n - 1) / 26)) label = String.fromCharCode(97 + ((n - 1) % 26)) + label;
+  } else if (style === 2 && ordinal >= 1 && ordinal <= 3999) {
+    let n = ordinal;
+    for (const [value, digit] of romanDigits) {
+      while (n >= value) {
+        label += digit;
+        n -= value;
+      }
+    }
+  } else label = String(ordinal);
+  return `${label}.`;
+};

package/src/markdown/_lib/math-syntax.ts

@@ -0,0 +1,3 @@
+/** KaTeX source syntax, shared by the math widgets and every decoration that must leave math alone. */
+export const blockMathPattern = (): RegExp => /\$\$([^$]+)\$\$|\\\[(.*?)\\\]/gs;
+export const inlineMathPattern = (): RegExp => /(?<!\$)\$(?!\$)([^\n$]+)\$(?!\$)|\\\(([^)\n]*?)\\\)/g;