@lovett/ui 0.0.11 → 0.2.0

package/src/thread/markdown-spec.ts

@@ -0,0 +1,754 @@
+/**
+ * markdown-spec — the editor side of the thread wire format.
+ *
+ * ADR-148 D3, D4, D13. `body_md` is markdown and stays markdown (D1): the rich
+ * editor is an editing surface over that string, never a second storage
+ * format. This file is the ONLY place the editor learns how the two syntaxes
+ * ADR-147 D11 / ADR-148 D13 add on top of CommonMark + GFM are spelled:
+ *
+ *     @[Marcus Webb](user:usr_9f2)   <->  a `mention` node        (D4)
+ *     ++underlined++                 <->  the `underline` mark    (D13)
+ *
+ * …plus the fail-closed detector `isRichEditable` (D3 rule 2), and the two
+ * helpers the composer and the tests both use, `parseRichMarkdown` /
+ * `serializeRichMarkdown`, so there is exactly one parse and one serialize
+ * path in the package.
+ *
+ * NOT re-exported from the package barrel, on purpose. Everything here imports
+ * TipTap statically, and the barrel must stay free of it so a thread LIST never
+ * pays for ProseMirror (D5, AC#10). The lazily loaded `rich-composer-impl.tsx`
+ * is the only production consumer; the tests import this file directly.
+ *
+ * THE UNDERLINE GRAMMAR, as agreed with the renderer side (`++text++`, no
+ * whitespace touching the markers, no `++` inside `++`) is deliberately
+ * STRICTER than the tokenizer StarterKit's own Underline ships — that one trims
+ * inner whitespace and spans lines — which is why StarterKit's copy is disabled
+ * and the mark is defined here. Same name, same commands, same `Mod-u`; only
+ * the markdown spelling is ours.
+ *
+ * ESCAPING. `@tiptap/markdown` backslash-escapes `` \ ` * _ [ ] ~ `` in text
+ * and HTML-encodes `& < >`, which already covers most of CommonMark's inline
+ * syntax and blockquotes. It does NOT escape `+` (so a literal `++x++` typed in
+ * the editor would come back as an underline) or block starters (`# `, `- `,
+ * `1. `, `---`), so a paragraph typed as "- not a list" would come back as a
+ * list. Those are handled here, before the manager runs, with a private-use
+ * sentinel that stands in for the backslash: the manager would double any real
+ * backslash it saw, and it would double-encode any entity. The sentinel is
+ * swapped for `\` after serialization. A U+E000 already present in user text is
+ * dropped first; it is a private-use code point with no meaning to keep.
+ */
+
+import {
+  Editor,
+  Extension,
+  InputRule,
+  Mark,
+  mergeAttributes,
+  type Extensions,
+  type JSONContent,
+  type MarkdownToken,
+  type Range,
+  markInputRule,
+} from '@tiptap/core'
+import { Mention, type MentionNodeAttrs, type MentionOptions } from '@tiptap/extension-mention'
+import { Markdown, type MarkdownManager } from '@tiptap/markdown'
+import { Node as ProseMirrorNode, type Schema } from '@tiptap/pm/model'
+import { PluginKey } from '@tiptap/pm/state'
+import { StarterKit } from '@tiptap/starter-kit'
+import { parseMentionHref, type MentionTargetType } from './comment-body'
+import { emojiByShortcode, searchEmoji } from './emoji'
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    underline: {
+      setUnderline: () => ReturnType
+      toggleUnderline: () => ReturnType
+      unsetUnderline: () => ReturnType
+    }
+  }
+}
+
+/* ── Underline (D13) ──────────────────────────────────────────────────────── */
+
+const UNDERLINE_MARKER = '++'
+
+/**
+ * `++text++`: the inner text starts and ends with a non-space, contains no
+ * `++` (so no nesting) and no newline. Anything else is literal text, which is
+ * what the renderer side does with it too.
+ *
+ * A backslash escape is consumed as ONE unit, so the closer can never begin
+ * inside one: in `++C\+\+++` the escaped pluses are text and the last two
+ * characters are the closer. Without this the lazy match ended at the `+` of
+ * `\+` and the serialized form did not re-parse to itself.
+ */
+const UNDERLINE_PATTERN = /^\+\+(?=\S)((?:\\[^\n]|(?!\+\+)[^\n\\])+?)(?<=\S)\+\+/
+
+interface UnderlineOptions {
+  readonly HTMLAttributes: Record<string, unknown>
+}
+
+/**
+ * The `++text++` input rule's pattern. Exported so it can be tested without an
+ * Editor: input rules only fire on real text input, which jsdom cannot
+ * faithfully simulate, and the regex is where a bug would actually live. The
+ * end-to-end behaviour is verified in a browser.
+ *
+ * STRICTER than TipTap's own bold/strike rules, deliberately, because it has to
+ * agree with the RENDERER. `lib/remark-underline.ts` rejects whitespace
+ * immediately inside either marker; TipTap's `(?!\s+\*\*)` shape does not, so a
+ * copy of it fired on `++ under++` — the editor would have drawn an underline
+ * that the renderer then showed as literal plus signs. The lookarounds are the
+ * fix: `(?!\s)` after the opener, `(?<!\s)` before the closer, and a lazy
+ * `[^+]+?` so a run cannot swallow a second pair. (Lookbehind is ES2018,
+ * Safari 16.4+ — the same floor `overflow: clip` already sets.)
+ */
+export const UNDERLINE_INPUT_RULE = /(?:^|\s)(\+\+(?!\s)([^+]+?)(?<!\s)\+\+)$/
+
+export const ThreadUnderline = Mark.create<UnderlineOptions>({
+  name: 'underline',
+
+  addOptions() {
+    return { HTMLAttributes: {} }
+  },
+
+  parseHTML() {
+    return [
+      { tag: 'u' },
+      {
+        style: 'text-decoration',
+        consuming: false,
+        getAttrs: (style) =>
+          typeof style === 'string' && style.includes('underline') ? {} : false,
+      },
+    ]
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    return ['u', mergeAttributes(this.options.HTMLAttributes, HTMLAttributes), 0]
+  },
+
+  addCommands() {
+    return {
+      setUnderline:
+        () =>
+        ({ commands }) =>
+          commands.setMark(this.name),
+      toggleUnderline:
+        () =>
+        ({ commands }) =>
+          commands.toggleMark(this.name),
+      unsetUnderline:
+        () =>
+        ({ commands }) =>
+          commands.unsetMark(this.name),
+    }
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      'Mod-u': () => this.editor.commands.toggleUnderline(),
+      'Mod-U': () => this.editor.commands.toggleUnderline(),
+    }
+  },
+
+  /**
+   * Type `++text++` and it becomes underlined, the moment the closing `++`
+   * lands — the same as `**bold**` and `~~strike~~`, which StarterKit gives us
+   * for free. Without this the mark had commands, a shortcut and full markdown
+   * serialization but no way to reach it by TYPING, which is the way people
+   * who know markdown actually reach it. (Owner, 2026-09-07: "is it not like
+   * obsidian where you type them in and it autoformats as you type?")
+   *
+   * The pattern mirrors TipTap's own bold rule, with `+` swapped for `*`:
+   *   - `(?:^|\s)` — the run starts at the line start or after whitespace, so
+   *     `i++;` and `C++` are never rules, matching the renderer's flanking rule
+   *     (D13) rather than fighting it.
+   *   - `(?!\s+\+\+)` — no whitespace immediately inside the opener.
+   *   - `[^+]+` — the content cannot itself contain `+`, so `+++` runs and
+   *     `a++b++c++d` degrade to text instead of matching greedily.
+   */
+  addInputRules() {
+    return [markInputRule({ find: UNDERLINE_INPUT_RULE, type: this.type })]
+  },
+
+  markdownTokenizer: {
+    name: 'underline',
+    level: 'inline',
+    start: (src) => src.indexOf(UNDERLINE_MARKER),
+    tokenize: (src, _tokens, lexer) => {
+      const match = UNDERLINE_PATTERN.exec(src)
+      const inner = match?.[1]
+      if (match === null || inner === undefined) return undefined
+      return { type: 'underline', raw: match[0], text: inner, tokens: lexer.inlineTokens(inner) }
+    },
+  },
+
+  parseMarkdown: (token, helpers) =>
+    helpers.applyMark('underline', helpers.parseInline(token.tokens ?? [])),
+
+  renderMarkdown: (node, helpers) => `++${helpers.renderChildren(node)}++`,
+})
+
+/* ── Mention (D4) ─────────────────────────────────────────────────────────── */
+
+/**
+ * The Suggestion plugin key the `@` picker (ADR-149) hangs off. Exported so
+ * the composer can read the plugin state — "is a Suggestion popup open?" is
+ * what D7 (no bubble menu while it is) and D9 (Escape closes it second) need.
+ */
+export const THREAD_MENTION_SUGGESTION_KEY = new PluginKey('threadMentionSuggestion')
+
+/** `@[label](scheme:id)`; the label may carry `\]` / `\[` / `\\` escapes. */
+const MENTION_PATTERN = /^@\[((?:\\.|[^\]\\\n])+)\]\(([^)\s]+)\)/
+
+function escapeMentionLabel(label: string): string {
+  return label.replace(/[\\[\]]/g, (char) => `\\${char}`)
+}
+
+function unescapeMentionLabel(raw: string): string {
+  return raw.replace(/\\(.)/g, '$1')
+}
+
+export interface ThreadMentionAttrs {
+  readonly id: string
+  readonly label: string
+  readonly type: MentionTargetType
+}
+
+/** Narrow a node's attrs to a mention without a cast. Null for anything malformed. */
+function readMentionAttrs(attrs: Record<string, unknown> | undefined): ThreadMentionAttrs | null {
+  if (attrs === undefined) return null
+  const id = attrs['id']
+  const label = attrs['label']
+  const type = attrs['type']
+  if (typeof id !== 'string' || id === '') return null
+  if (typeof type !== 'string') return null
+  const target = parseMentionHref(`${type}:${id}`)
+  if (target === null) return null
+  return { id: target.id, label: typeof label === 'string' && label !== '' ? label : id, type: target.type }
+}
+
+export const ThreadMention = Mention.extend({
+  addAttributes() {
+    return {
+      ...this.parent?.(),
+      type: {
+        default: 'user',
+        parseHTML: (element) => element.getAttribute('data-mention-type'),
+        renderHTML: (attributes) => ({ 'data-mention-type': attributes['type'] }),
+      },
+    }
+  },
+
+  markdownTokenizer: {
+    name: 'mention',
+    level: 'inline',
+    start: (src) => src.indexOf('@['),
+    tokenize: (src) => {
+      const match = MENTION_PATTERN.exec(src)
+      const rawLabel = match?.[1]
+      const href = match?.[2]
+      if (match === null || rawLabel === undefined || href === undefined) return undefined
+      // Any other `@[…](…)` — an https link, an unknown scheme — is NOT a
+      // mention. Returning undefined hands it back to marked, which tokenizes
+      // it as a plain link, exactly as the renderer treats it.
+      const target = parseMentionHref(href)
+      if (target === null) return undefined
+      return {
+        type: 'mention',
+        raw: match[0],
+        label: unescapeMentionLabel(rawLabel),
+        id: target.id,
+        mentionType: target.type,
+      }
+    },
+  },
+
+  parseMarkdown: (token) => ({
+    type: 'mention',
+    attrs: {
+      id: token['id'],
+      label: token['label'],
+      type: token['mentionType'],
+      mentionSuggestionChar: '@',
+    },
+  }),
+
+  renderMarkdown: (node) => {
+    const mention = readMentionAttrs(node.attrs)
+    // A mention node without a valid target cannot reach the wire: it would
+    // serialize to something the server-side extractor would refuse. Its
+    // label survives as text so nothing the user wrote disappears.
+    if (mention === null) return typeof node.attrs?.['label'] === 'string' ? `@${node.attrs['label']}` : ''
+    return `@[${escapeMentionLabel(mention.label)}](${mention.type}:${mention.id})`
+  },
+})
+
+/* ── The subset (D2 / D3) ─────────────────────────────────────────────────── */
+
+export const RICH_HEADING_LEVELS = [1, 2, 3] as const
+const RICH_HEADING_LEVEL_SET: ReadonlySet<number> = new Set<number>(RICH_HEADING_LEVELS)
+
+type MentionSuggestion = MentionOptions['suggestion']
+
+/**
+ * How many characters after the sigil before the popup may open (ADR-149 D4).
+ *
+ * A bare `:` is punctuation and far more common in prose than an emoji, so it
+ * takes two; a bare `@` is rare enough that one is right. Below the threshold
+ * the plugin hands the renderer an EMPTY item list, which is what closes the
+ * popup — the same door "no matches" comes through, so there is one rule in
+ * the UI and not two.
+ */
+export const MENTION_SUGGESTION_MIN_QUERY = 1
+export const EMOJI_SUGGESTION_MIN_QUERY = 2
+
+/**
+ * The `:` trigger's Suggestion plugin key, beside the `@` one above. Two keys
+ * because they are two plugins; ONE popup, because they are one interaction
+ * (D1) — the difference is data and rendering, never behaviour.
+ */
+export const THREAD_EMOJI_SUGGESTION_KEY = new PluginKey('threadEmojiSuggestion')
+
+/**
+ * A complete, typed shortcode at the end of the current textblock. The shape
+ * is deliberately only the lexical first pass: `EMOJI_INPUT_RULE` then asks
+ * the curated table whether the spelling is a real name or alias. Keywords
+ * are search aids, not shortcodes, and must not make prose transform.
+ */
+const EMOJI_SHORTCODE_AT_END = /(?:^|\s)(:([^:\s]+):)$/
+
+/**
+ * Slack-style closing-colon matcher, exported for a direct test. TipTap input
+ * rules only run on real text input, while `insertContent` bypasses them.
+ */
+export const EMOJI_INPUT_RULE = (text: string) => {
+  const match = EMOJI_SHORTCODE_AT_END.exec(text)
+  const shortcode = match?.[1]
+  if (match === null || shortcode === undefined || emojiByShortcode(shortcode) === undefined) {
+    return null
+  }
+  return { index: match.index, text: match[0], data: { shortcode } }
+}
+
+const ThreadEmojiShortcode = Extension.create({
+  name: 'threadEmojiShortcode',
+
+  addInputRules() {
+    return [
+      new InputRule({
+        find: EMOJI_INPUT_RULE,
+        handler: ({ state, range, match }) => {
+          const shortcode = match.data?.['shortcode']
+          const entry = typeof shortcode === 'string' ? emojiByShortcode(shortcode) : undefined
+          if (entry === undefined || typeof shortcode !== 'string') return null
+          state.tr.insertText(entry.glyph, range.to - shortcode.length, range.to)
+          return undefined
+        },
+      }),
+    ]
+  },
+})
+
+/**
+ * What the `:` picker hands back when an option is chosen.
+ *
+ * `id` is the canonical shortcode, and it is deliberately the ONLY thing that
+ * crosses the seam: `@tiptap/extension-mention` types its `command` payload as
+ * `MentionNodeAttrs`, so an emoji-shaped payload would not type-check through
+ * it. Passing the shortcode and re-resolving the glyph from the table on the
+ * other side keeps this honest with zero casts, and means the insert can never
+ * write a glyph that is not in the table.
+ */
+export interface EmojiSuggestionAttrs {
+  readonly id: string
+  readonly label: string
+}
+
+/**
+ * D2 — an emoji is inserted as UNICODE, never as a shortcode. `body_md` then
+ * contains the character, so every render site (the digest, an export, an
+ * agent's context, a plain-text copy) shows it without a lookup table.
+ *
+ * The trailing space, and the guard against doubling it, mirror the mention
+ * command exactly, so choosing from either popup leaves the caret in the same
+ * place.
+ */
+function insertEmoji({
+  editor,
+  range,
+  props,
+}: {
+  editor: Editor
+  range: Range
+  props: MentionNodeAttrs
+}): void {
+  const entry = emojiByShortcode(props.id ?? '')
+  if (entry === undefined) return
+  const nodeAfter = editor.view.state.selection.$to.nodeAfter
+  const to = nodeAfter?.text?.startsWith(' ') === true ? range.to + 1 : range.to
+  editor
+    .chain()
+    .focus()
+    .insertContentAt({ from: range.from, to }, [{ type: 'text', text: `${entry.glyph} ` }])
+    .run()
+}
+
+/** The `:` picker's options, in the shape the Suggestion payload accepts. */
+function emojiSuggestionItems(query: string): EmojiSuggestionAttrs[] {
+  return searchEmoji(query).map((entry) => ({ id: entry.name, label: entry.glyph }))
+}
+
+/**
+ * The two trigger configurations (D1). The DATA half — what each trigger
+ * offers and what choosing does — lives here; the RENDERING half is one
+ * `render()` per trigger, supplied by the composer, pointing at one popup.
+ */
+export interface RichSuggestionRenderers {
+  /** The `@` trigger. Absent, the mention popup never opens. */
+  readonly mention?: Partial<MentionSuggestion> | undefined
+  /** The `:` trigger. Absent, the emoji popup never opens. */
+  readonly emoji?: Partial<MentionSuggestion> | undefined
+}
+
+/**
+ * The editor's extension set — the D3 subset, written down (ADR-148 D2).
+ *
+ * StarterKit is configured explicitly so a future minor cannot admit a
+ * construct silently. Today the only things it does not keep at default are
+ * the heading levels (1–3), the link options an EDITOR needs (a click must
+ * edit, not navigate), and `underline: false` — replaced by `ThreadUnderline`
+ * above, same name and commands, strict `++` grammar.
+ *
+ * BOTH triggers hang off the ONE Mention extension, through its `suggestions`
+ * array. That is not a trick: `@tiptap/suggestion` is a transitive dependency
+ * with no direct entry in `@lovett/ui`'s `package.json`, so under pnpm's
+ * strict layout it cannot be imported from this package, and ADR-148 D2
+ * deliberately did not install it ("zero new runtime dependencies",
+ * ADR-149 AC#1). `suggestions` is the extension's own supported way to run a
+ * second trigger, and it gives the `:` plugin the same match-finding,
+ * dismissal and floating-ui anchoring the `@` one already had. The `:` trigger
+ * never creates a mention node — its `command` inserts text (D2).
+ */
+export function richSubsetExtensions(renderers: RichSuggestionRenderers = {}): Extensions {
+  return [
+    StarterKit.configure({
+      heading: { levels: [...RICH_HEADING_LEVELS] },
+      // horizontalRule: default, IN — owner, 2026-09-07.
+      underline: false,
+      link: {
+        openOnClick: false,
+        autolink: true,
+        linkOnPaste: true,
+        enableClickSelection: false,
+      },
+    }),
+    ThreadUnderline,
+    ThreadEmojiShortcode,
+    ThreadMention.configure({
+      HTMLAttributes: { class: 'ds-thread-mention' },
+      suggestions: [
+        {
+          char: '@',
+          pluginKey: THREAD_MENTION_SUGGESTION_KEY,
+          minQueryLength: MENTION_SUGGESTION_MIN_QUERY,
+          ...renderers.mention,
+        },
+        {
+          char: ':',
+          pluginKey: THREAD_EMOJI_SUGGESTION_KEY,
+          minQueryLength: EMOJI_SUGGESTION_MIN_QUERY,
+          // The plugin's own view of what it is offering. The POPUP does not
+          // read this — it recomputes from the query, because
+          // `@tiptap/suggestion` types its items as `any` and the composer
+          // does not take `any` — but leaving it unset would make the plugin's
+          // state say "no items" while eight are on screen, which is a lie any
+          // future reader of that state would trip over.
+          items: ({ query }: { query: string }) => emojiSuggestionItems(query),
+          command: insertEmoji,
+          // A shortcode typed inside code stays literal: `:tada:` in a snippet
+          // is text about an emoji, not an emoji. The mention trigger keeps
+          // the extension's own default, which asks the schema whether a
+          // mention node may sit here.
+          allow: ({ editor }: { editor: Editor }) =>
+            !editor.isActive('codeBlock') && !editor.isActive('code'),
+          ...renderers.emoji,
+        },
+      ],
+    }),
+    Markdown,
+  ]
+}
+
+/* ── Headless probe ───────────────────────────────────────────────────────── */
+
+let probe: Editor | null = null
+
+/**
+ * One headless editor over the subset, created on first use. It owns the
+ * `MarkdownManager` every parse and serialize below goes through and the
+ * schema the detector checks against — so the detector, the tests and the live
+ * composer agree by construction, not by keeping three configurations in step.
+ */
+function getProbe(): Editor {
+  if (probe === null) {
+    probe = new Editor({ element: null, extensions: richSubsetExtensions(), content: '' })
+  }
+  return probe
+}
+
+function getManager(): MarkdownManager {
+  const manager = getProbe().markdown
+  if (manager === undefined) {
+    throw new Error('rich composer: the Markdown extension did not attach a manager')
+  }
+  return manager
+}
+
+function getSchema(): Schema {
+  return getProbe().schema
+}
+
+/* ── Parse / serialize ────────────────────────────────────────────────────── */
+
+export function parseRichMarkdown(markdown: string): JSONContent {
+  return canonicalizeInlineMarks(getManager().parse(markdown))
+}
+
+/* ── Canonical mark boundaries ────────────────────────────────────────────── */
+
+/**
+ * Marks that markdown cannot open or close on whitespace. `*a *` is not
+ * emphasis and `` ` a ` `` is `a`; a link, by contrast, keeps `[a ](url)`.
+ */
+const BOUNDARY_MARKS: readonly string[] = ['bold', 'italic', 'underline', 'strike', 'code']
+
+function hasMark(node: JSONContent, type: string): boolean {
+  return (node.marks ?? []).some((mark) => mark.type === type)
+}
+
+function withoutMark(node: JSONContent, type: string): JSONContent {
+  const marks = (node.marks ?? []).filter((mark) => mark.type !== type)
+  const { marks: _marks, ...rest } = node
+  return marks.length === 0 ? rest : { ...rest, marks }
+}
+
+/**
+ * Push the whitespace at either end of every maximal run of `type`-marked text
+ * OUT of the mark — into a node that keeps the run's other marks. One mark at
+ * a time, so `**bold with *italic inside* it**` is untouched (the bold run is
+ * all three nodes; the italic run has no boundary whitespace) while
+ * `*quarter @[…] **creative***` — italic on the space beside a mention, which
+ * no serializer can spell — settles into the one form that re-parses to
+ * itself. This is the canonicalization D3 rule 1 allows, applied where the
+ * manager's own output would otherwise not be a fixed point.
+ */
+function trimMarkRuns(content: readonly JSONContent[], type: string): JSONContent[] {
+  const out: JSONContent[] = []
+  let run: JSONContent[] = []
+  const flush = () => {
+    if (run.length === 0) return
+    const first = run[0]
+    const last = run[run.length - 1]
+    if (first === undefined || last === undefined) return
+    const leading = /^\s+/.exec(first.text ?? '')?.[0] ?? ''
+    if (leading !== '' && leading.length < (first.text ?? '').length) {
+      run[0] = { ...first, text: (first.text ?? '').slice(leading.length) }
+      out.push(withoutMark({ ...first, text: leading }, type))
+    } else if (leading !== '') {
+      run[0] = withoutMark(first, type)
+    }
+    const tail = run[run.length - 1]
+    if (tail !== undefined && run.length >= 1 && !(run.length === 1 && leading !== '' && leading.length >= (first.text ?? '').length)) {
+      const trailing = /\s+$/.exec(tail.text ?? '')?.[0] ?? ''
+      if (trailing !== '' && trailing.length < (tail.text ?? '').length) {
+        run[run.length - 1] = { ...tail, text: (tail.text ?? '').slice(0, -trailing.length) }
+        out.push(...run)
+        out.push(withoutMark({ ...tail, text: trailing }, type))
+        run = []
+        return
+      }
+      if (trailing !== '' && run.length > 1) {
+        run[run.length - 1] = withoutMark(tail, type)
+      }
+    }
+    out.push(...run)
+    run = []
+  }
+  for (const node of content) {
+    if (node.type === 'text' && hasMark(node, type)) {
+      run.push(node)
+      continue
+    }
+    flush()
+    out.push(node)
+  }
+  flush()
+  return out
+}
+
+function canonicalizeInlineMarks(node: JSONContent): JSONContent {
+  const content = node.content
+  if (content === undefined) return node
+  if (node.type === 'paragraph' || node.type === 'heading') {
+    let inline: JSONContent[] = [...content]
+    for (const type of BOUNDARY_MARKS) inline = trimMarkRuns(inline, type)
+    return { ...node, content: inline }
+  }
+  return { ...node, content: content.map(canonicalizeInlineMarks) }
+}
+
+/**
+ * Run a document through the schema: attrs get their defaults, invalid
+ * content throws. `parse → normalize` is what `editor.setContent` produces,
+ * so this is what the round-trip tests compare.
+ */
+export function normalizeRichDocument(doc: JSONContent): JSONContent {
+  const node = ProseMirrorNode.fromJSON(getSchema(), doc)
+  node.check()
+  return node.toJSON()
+}
+
+const ESCAPE_SENTINEL = '\u{E000}'
+
+function hasCodeMark(node: JSONContent): boolean {
+  return (node.marks ?? []).some((mark) => mark.type === 'code')
+}
+
+/** Block starters the manager does not escape; `>` it already entity-encodes. */
+function escapeBlockStart(text: string): string {
+  return text
+    .replace(/^(#{1,6})(?=[ \t]|$)/, (hashes) => hashes.replace(/#/g, `${ESCAPE_SENTINEL}#`))
+    .replace(/^([-+])(?=[ \t]|$)/, `${ESCAPE_SENTINEL}$1`)
+    .replace(/^(\d{1,9})([.)])(?=[ \t]|$)/, `$1${ESCAPE_SENTINEL}$2`)
+    .replace(/^-{3,}[ \t]*$/, (rule) => `${ESCAPE_SENTINEL}${rule}`)
+}
+
+function escapePlusRuns(text: string): string {
+  return text.replace(/\+{2,}/g, (run) => run.replace(/\+/g, `${ESCAPE_SENTINEL}+`))
+}
+
+/**
+ * Mark, in a COPY of the tree, every character the manager would let through
+ * unescaped. Code is left alone at every level: inside a code block or a code
+ * mark the characters are literal already.
+ */
+function markLiteralSyntax(node: JSONContent): JSONContent {
+  if (node.type === 'codeBlock') return node
+  const content = node.content
+  if (content === undefined) return node
+  let lineStart = node.type === 'paragraph' || node.type === 'heading'
+  const next = content.map((child): JSONContent => {
+    if (child.type === 'text') {
+      const startsLine = lineStart
+      lineStart = false
+      if (hasCodeMark(child)) return child
+      const source = (child.text ?? '').replaceAll(ESCAPE_SENTINEL, '')
+      let text = escapePlusRuns(source)
+      if (startsLine) text = escapeBlockStart(text)
+      return text === child.text ? child : { ...child, text }
+    }
+    if (child.type === 'hardBreak') {
+      lineStart = true
+      return child
+    }
+    lineStart = false
+    return markLiteralSyntax(child)
+  })
+  return { ...node, content: next }
+}
+
+export function serializeRichMarkdown(doc: JSONContent): string {
+  // The same boundary rule on the way out: a mark the editor put on a trailing
+  // space cannot be spelled, so it is moved off the space before the manager
+  // sees it, and the output re-parses to exactly what was serialized.
+  // Trailing blank lines are not markdown: CommonMark parses `x\n\n` and `x`
+  // to the same tree, and the editor always ends in an empty paragraph (the
+  // trailing node that lets a caret land after a final list or code block).
+  // Trimming the end is what makes the serialized form a fixed point.
+  return getManager()
+    .serialize(markLiteralSyntax(canonicalizeInlineMarks(doc)))
+    .replaceAll(ESCAPE_SENTINEL, '\\')
+    .trimEnd()
+}
+
+/* ── Fail-closed detector (D3 rule 2) ─────────────────────────────────────── */
+
+/**
+ * Every token marked's lexer may emit for a body the subset can hold. Anything
+ * not on this list — `table`, `html`, `image`, a token a future marked adds —
+ * fails closed, which is the point: the list is what we can VOUCH for, not
+ * what we happen to have seen.
+ */
+const SUPPORTED_TOKENS: ReadonlySet<string> = new Set([
+  'space',
+  'paragraph',
+  'heading',
+  'hr',
+  'blockquote',
+  'list',
+  'list_item',
+  'code',
+  'def',
+  'text',
+  'strong',
+  'em',
+  'del',
+  'codespan',
+  'link',
+  'br',
+  'escape',
+  'underline',
+  'mention',
+])
+
+function tokensSupported(tokens: readonly MarkdownToken[]): boolean {
+  return tokens.every((token) => {
+    const type = token.type
+    if (type === undefined || !SUPPORTED_TOKENS.has(type)) return false
+    if (type === 'heading' && !RICH_HEADING_LEVEL_SET.has(token.depth ?? 1)) return false
+    if (type === 'list_item' && token['task'] === true) return false
+    const children: MarkdownToken[] = [...(token.tokens ?? []), ...(token.items ?? [])]
+    return tokensSupported(children)
+  })
+}
+
+function documentSupported(node: JSONContent): boolean {
+  if (node.type === 'heading') {
+    const level = node.attrs?.['level']
+    if (typeof level !== 'number' || !RICH_HEADING_LEVEL_SET.has(level)) return false
+  }
+  if (node.type === 'mention' && readMentionAttrs(node.attrs) === null) return false
+  return (node.content ?? []).every(documentSupported)
+}
+
+/**
+ * May this body open in the rich editor?
+ *
+ * Two checks, because they fail differently. The token scan catches syntax
+ * the schema could *absorb* but must not — raw `<u>` would become an underline
+ * mark and be re-serialized as `++`, which is exactly the byte change rule 2
+ * forbids. The schema check (`Node.fromJSON` + `check()`, plus the attrs the
+ * schema does not validate) catches anything the parse emits that the editor
+ * cannot hold. Either failing means the plain composer, source untouched.
+ */
+export function isRichEditable(markdown: string): boolean {
+  if (markdown.trim() === '') return true
+  const manager = getManager()
+  let tokens: readonly MarkdownToken[]
+  try {
+    tokens = manager.instance.lexer(markdown)
+  } catch {
+    return false
+  }
+  if (!tokensSupported(tokens)) return false
+  try {
+    const doc = manager.parse(markdown)
+    if (!documentSupported(doc)) return false
+    normalizeRichDocument(doc)
+    return true
+  } catch {
+    return false
+  }
+}