@abraca/convert 2.3.0

package/src/markdown-to-yjs.ts

@@ -0,0 +1,1208 @@
+import * as Y from 'yjs'
+import type { DocPageMeta } from './types.ts'
+
+// ── Filename → readable label ────────────────────────────────────────────────
+
+/**
+ * Converts a filename (without extension) to a human-readable label.
+ *
+ * - `this-is-a-doc`  → `"This is a doc"`   (kebab/snake: sentence case)
+ * - `ThisIsADoc`     → `"This Is A Doc"`   (PascalCase: preserves word caps)
+ * - `thisIsADoc`     → `"This Is A Doc"`   (camelCase: preserves word caps)
+ */
+export function filenameToLabel(raw: string): string {
+  const base = raw.replace(/\.[^.]+$/, '') // strip extension if present
+  const spaced = base.replace(/([a-z])([A-Z])/g, '$1 $2')
+  const clean = spaced.replace(/[-_.]+/g, ' ').replace(/\s+/g, ' ').trim()
+  return clean.charAt(0).toUpperCase() + clean.slice(1)
+}
+
+// ── YAML frontmatter parser ──────────────────────────────────────────────────
+
+export interface FrontmatterResult {
+  title?: string
+  type?: string
+  meta: Partial<DocPageMeta>
+  body: string
+}
+
+function coerceScalar(raw: string): string | number | boolean {
+  const trimmed = raw.trim()
+  if (trimmed === 'true') return true
+  if (trimmed === 'false') return false
+  const num = Number(trimmed)
+  if (!Number.isNaN(num) && trimmed !== '') return num
+  // Strip surrounding quotes
+  if ((trimmed.startsWith('"') && trimmed.endsWith('"'))
+    || (trimmed.startsWith('\'') && trimmed.endsWith('\''))) {
+    return trimmed.slice(1, -1)
+  }
+  return trimmed
+}
+
+function parseInlineArray(raw: string): string[] {
+  // e.g. "[a, b, c]"
+  return raw.slice(1, -1).split(',').map(s => s.trim()).filter(Boolean)
+}
+
+function stripQuotes(s: string): string {
+  if (s.length >= 2
+    && ((s.startsWith('"') && s.endsWith('"'))
+      || (s.startsWith('\'') && s.endsWith('\'')))) {
+    return s.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\')
+  }
+  return s
+}
+
+export function parseFrontmatter(markdown: string): FrontmatterResult {
+  const noResult: FrontmatterResult = { meta: {}, body: markdown }
+
+  const match = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+  if (!match) return noResult
+
+  const yamlBlock = match[1]!
+  const body = markdown.slice(match[0].length)
+
+  // Parse YAML into a raw map
+  const raw: Record<string, string | string[]> = {}
+  const lines = yamlBlock.split('\n')
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]!
+    // Block sequence: "key:\n  - a\n  - b"
+    const blockSeqKey = line.match(/^(\w[\w-]*):\s*$/)
+    if (blockSeqKey && i + 1 < lines.length && /^\s+-\s/.test(lines[i + 1]!)) {
+      const key = blockSeqKey[1]!
+      const items: string[] = []
+      i++
+      while (i < lines.length && /^\s+-\s/.test(lines[i]!)) {
+        items.push(lines[i]!.replace(/^\s+-\s/, '').trim())
+        i++
+      }
+      raw[key] = items
+      continue
+    }
+    // Scalar or inline array
+    const kvMatch = line.match(/^(\w[\w-]*):\s*(.*)$/)
+    if (kvMatch) {
+      const key = kvMatch[1]!
+      const val = kvMatch[2]!.trim()
+      if (val.startsWith('[') && val.endsWith(']')) {
+        raw[key] = parseInlineArray(val).map(stripQuotes)
+      } else {
+        // Strip surrounding quotes up-front so downstream readers
+        // don't have to. The original quote state is irrelevant — we
+        // re-emit with our canonical quoting rules.
+        raw[key] = stripQuotes(val)
+      }
+    }
+    i++
+  }
+
+  // Map raw YAML keys → PageMeta
+  const meta: Partial<DocPageMeta> = {}
+
+  const getStr = (keys: string[]): string | undefined => {
+    for (const k of keys) {
+      const v = raw[k]
+      if (typeof v === 'string' && v) return v
+    }
+  }
+  const getArr = (keys: string[]): string[] | undefined => {
+    for (const k of keys) {
+      const v = raw[k]
+      if (Array.isArray(v)) return v
+      if (typeof v === 'string' && v) return [v]
+    }
+  }
+
+  if (raw['tags']) meta.tags = Array.isArray(raw['tags']) ? raw['tags'] : [raw['tags'] as string]
+  const color = getStr(['color'])
+  if (color) meta.color = color
+  const icon = getStr(['icon'])
+  if (icon) meta.icon = icon
+  const status = getStr(['status'])
+  if (status) meta.status = status
+
+  const priorityRaw = getStr(['priority'])
+  if (priorityRaw !== undefined) {
+    const map: Record<string, number> = { low: 1, medium: 2, high: 3, urgent: 4 }
+    meta.priority = map[priorityRaw.toLowerCase()] ?? (Number(priorityRaw) || 0)
+  }
+
+  const checkedRaw: unknown = raw['checked'] ?? raw['done']
+  if (checkedRaw !== undefined) meta.checked = checkedRaw === 'true' || checkedRaw === true
+
+  // Canonical keys are checked first, aliases follow — so files that
+  // already use the canonical name (dateStart, dateEnd, subtitle) keep
+  // round-tripping byte-stably while legacy aliases still parse.
+  const dateStart = getStr(['dateStart', 'date', 'created'])
+  if (dateStart) meta.dateStart = dateStart
+  const dateEnd = getStr(['dateEnd', 'due'])
+  if (dateEnd) meta.dateEnd = dateEnd
+
+  const subtitle = getStr(['subtitle', 'description'])
+  if (subtitle) meta.subtitle = subtitle
+  const url = getStr(['url'])
+  if (url) meta.url = url
+
+  const ratingRaw = getStr(['rating'])
+  if (ratingRaw !== undefined) {
+    const n = Number(ratingRaw)
+    if (!Number.isNaN(n)) meta.rating = Math.min(5, Math.max(0, n))
+  }
+
+  const rawTitle = typeof raw['title'] === 'string' ? raw['title'] : undefined
+  const title = rawTitle !== undefined ? stripQuotes(rawTitle) : undefined
+  const type = getStr(['type'])
+
+  return { title, type, meta, body }
+}
+
+// ── Inline token parsing ─────────────────────────────────────────────────────
+
+interface InlineToken {
+  text: string
+  attrs?: Record<string, unknown>
+}
+
+function parseInline(text: string): InlineToken[] {
+  // Strip MDC attribute annotations on inline code: `string`{lang="ts-type"}
+  const stripped = text.replace(/\{lang="[^"]*"\}/g, '')
+    // Strip remaining unknown inline MDC components (but NOT badge/icon/kbd — handled below)
+    .replace(/:(?!badge|icon|kbd)(\w[\w-]*)\[([^\]]*)\](\{[^}]*\})?/g, '$2')
+    .replace(/:(?!badge|icon|kbd)(\w[\w-]*)(\{[^}]*\})/g, '')
+
+  const tokens: InlineToken[] = []
+  // Order matters: math (`$\u2026$`) before italic (so `$x$` doesn't match
+  // `$ \u2026 $` as italic-with-dollars); inline MDC first; mentions before
+  // plain `[\u2026]` links; wikilinks before plain brackets; strikethrough;
+  // bold before italic.
+  const re = /\$([^$\n]+?)\$|@\[([^\]]+?)\]\(user:([^)]+?)\)|:badge\[([^\]]*)\](\{[^}]*\})?|:icon\{([^}]*)\}|:kbd\{([^}]*)\}|\[\[([0-9a-fA-F-]{36})(?:\|([^\]]+?))?\]\]|~~(.+?)~~|\*\*(.+?)\*\*|\*(.+?)\*|_(.+?)_|`(.+?)`|\[(.+?)\]\((.+?)\)/g
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+
+  while ((match = re.exec(stripped)) !== null) {
+    if (match.index > lastIndex) {
+      tokens.push({ text: stripped.slice(lastIndex, match.index) })
+    }
+    if (match[1] !== undefined) {
+      // $expression$ \u2014 inline math atom
+      tokens.push({ text: match[1], attrs: { mathInline: { expression: match[1] } } })
+    } else if (match[2] !== undefined && match[3] !== undefined) {
+      // @[label](user:uuid) \u2014 mention atom
+      tokens.push({ text: match[2], attrs: { mention: { userId: match[3], label: match[2] } } })
+    } else if (match[4] !== undefined) {
+      // :badge[text]{props}
+      const badgeProps = parseMdcProps(match[5])
+      tokens.push({ text: match[4] || 'Badge', attrs: { badge: { label: match[4] || 'Badge', color: badgeProps['color'] || 'neutral', variant: badgeProps['variant'] || 'subtle' } } })
+    } else if (match[6] !== undefined) {
+      // :icon{name="..."}
+      const iconProps = parseMdcProps(`{${match[6]}}`)
+      tokens.push({ text: '\u200B', attrs: { proseIcon: { name: iconProps['name'] || 'i-lucide-star' } } })
+    } else if (match[7] !== undefined) {
+      // :kbd{value="..."}
+      const kbdProps = parseMdcProps(`{${match[7]}}`)
+      tokens.push({ text: kbdProps['value'] || '', attrs: { kbd: { value: kbdProps['value'] || '' } } })
+    } else if (match[8] !== undefined) {
+      // [[uuid]] or [[uuid|label]] \u2014 inline doc link atom. The docId
+      // is the canonical anchor; the label is display-only. The
+      // serialiser may regenerate the label from a live doc registry
+      // (see SPEC.md \u00A76); when no resolver is supplied, the parser's
+      // stored display text is reused on emit.
+      const docId = match[8]
+      const label = match[9] ?? docId
+      tokens.push({ text: label, attrs: { docLink: { docId } } })
+    } else if (match[10] !== undefined) {
+      tokens.push({ text: match[10], attrs: { strike: true } })
+    } else if (match[11] !== undefined) {
+      tokens.push({ text: match[11], attrs: { bold: true } })
+    } else if (match[12] !== undefined) {
+      tokens.push({ text: match[12], attrs: { italic: true } })
+    } else if (match[13] !== undefined) {
+      tokens.push({ text: match[13], attrs: { italic: true } })
+    } else if (match[14] !== undefined) {
+      tokens.push({ text: match[14], attrs: { code: true } })
+    } else if (match[15] !== undefined && match[16] !== undefined) {
+      tokens.push({ text: match[15], attrs: { link: { href: match[16] } } })
+    }
+    lastIndex = match.index + match[0].length
+  }
+
+  if (lastIndex < stripped.length) {
+    tokens.push({ text: stripped.slice(lastIndex) })
+  }
+  return tokens.filter(t => t.text.length > 0)
+}
+
+// ── Block-level parser ───────────────────────────────────────────────────────
+
+interface TaskItem {
+  text: string
+  checked: boolean
+}
+
+interface ListItemBlock {
+  text: string
+  innerBlocks?: Block[]
+  checked?: boolean
+}
+
+type Block
+  = | { type: 'heading', level: number, text: string }
+    | { type: 'paragraph', text: string }
+    | { type: 'bulletList', items: ListItemBlock[] }
+    | { type: 'orderedList', items: ListItemBlock[] }
+    | { type: 'taskList', items: ListItemBlock[] }
+    | { type: 'codeBlock', lang: string, code: string }
+    | { type: 'blockquote', lines: string[] }
+    | { type: 'table', headerRow: string[], dataRows: string[][] }
+    | { type: 'hr' }
+    | { type: 'callout', calloutType: string, innerBlocks: Block[] }
+    | { type: 'collapsible', label: string, open: boolean, innerBlocks: Block[] }
+    | { type: 'steps', innerBlocks: Block[] }
+    | { type: 'card', title: string, icon: string, to: string, innerBlocks: Block[] }
+    | { type: 'cardGroup', cards: Block[] }
+    | { type: 'codeCollapse', codeBlocks: Block[] }
+    | { type: 'codeGroup', codeBlocks: Block[] }
+    | { type: 'codePreview', innerBlocks: Block[], codeBlocks: Block[] }
+    | { type: 'codeTree', files: string }
+    | { type: 'accordion', items: { label: string, icon: string, innerBlocks: Block[] }[] }
+    | { type: 'tabs', items: { label: string, icon: string, innerBlocks: Block[] }[] }
+    | { type: 'field', name: string, fieldType: string, required: boolean, innerBlocks: Block[] }
+    | { type: 'fieldGroup', fields: Block[] }
+    | { type: 'image', src: string, alt: string, width?: string, height?: string }
+    | { type: 'docEmbed', docId: string, label: string, props: Record<string, string> }
+    | { type: 'mathBlock', expression: string }
+    | { type: 'fileBlock', src: string, mime: string, uploadId: string, filename: string }
+
+function parseTableRow(line: string): string[] {
+  const parts = line.split('|')
+  // Remove the first and last (empty from leading/trailing |) and trim each
+  return parts.slice(1, parts.length - 1).map(c => c.trim())
+}
+
+function isTableSeparator(line: string): boolean {
+  return /^\|[\s|:-]+\|$/.test(line.trim())
+}
+
+/** Extract fenced code blocks from MDC #code slot lines. */
+function extractFencedCode(lines: string[]): Block[] {
+  const result: Block[] = []
+  let i = 0
+  while (i < lines.length) {
+    const line = lines[i]!
+    // Match opening fence (```, ````, etc.)
+    const fenceMatch = line.match(/^(`{3,})(\w*)/)
+    if (fenceMatch) {
+      const fence = fenceMatch[1]!
+      const lang = fenceMatch[2] ?? ''
+      const codeLines: string[] = []
+      i++
+      while (i < lines.length && !lines[i]!.startsWith(fence)) {
+        codeLines.push(lines[i]!)
+        i++
+      }
+      i++ // skip closing fence
+      result.push({ type: 'codeBlock', lang, code: codeLines.join('\n') })
+      continue
+    }
+    i++
+  }
+  return result
+}
+
+/** Extract key="value" pairs from MDC prop syntax `{key="value" other="x"}` */
+function parseMdcProps(propsStr: string | undefined): Record<string, string> {
+  if (!propsStr) return {}
+  const result: Record<string, string> = {}
+  // Drop the wrapping `{ … }` if present.
+  let s = propsStr.trim()
+  if (s.startsWith('{') && s.endsWith('}')) s = s.slice(1, -1)
+
+  // Three accepted shapes per SPEC.md §5:
+  //   key="value"   (quoted)
+  //   key=value     (bare, no whitespace)
+  //   key           (boolean shorthand → "true")
+  const re = /(\w[\w-]*)(?:=(?:"([^"]*)"|([^\s"}]+)))?/g
+  let m: RegExpExecArray | null
+  while ((m = re.exec(s)) !== null) {
+    const key = m[1]!
+    if (m[2] !== undefined) result[key] = m[2]
+    else if (m[3] !== undefined) result[key] = m[3]
+    else result[key] = 'true'
+  }
+  return result
+}
+
+/** Parse named child MDC blocks from inner lines (e.g. #item for accordion, #tab for tabs) */
+function parseMdcChildren(innerLines: string[], slotPrefix: string): { label: string, icon: string, innerBlocks: Block[] }[] {
+  const items: { label: string, icon: string, lines: string[] }[] = []
+  let current: { label: string, icon: string, lines: string[] } | null = null
+  const slotRe = new RegExp(`^#${slotPrefix}(\\{[^}]*\\})?\\s*$`)
+
+  for (const line of innerLines) {
+    const slotMatch = line.match(slotRe)
+    if (slotMatch) {
+      if (current) items.push(current)
+      const props = parseMdcProps(slotMatch[1])
+      current = { label: props['label'] || props['title'] || `Item ${items.length + 1}`, icon: props['icon'] || '', lines: [] }
+      continue
+    }
+    if (current) {
+      current.lines.push(line)
+    } else {
+      // Content before first slot — treat as first unnamed item
+      if (!items.length && !current) {
+        current = { label: `Item 1`, icon: '', lines: [line] }
+      }
+    }
+  }
+  if (current) items.push(current)
+
+  return items.map(item => ({
+    label: item.label,
+    icon: item.icon,
+    innerBlocks: parseBlocks(item.lines.join('\n'))
+  }))
+}
+
+const TASK_RE = /^[-*+]\s+\[([ xX])\]\s+(.*)/
+
+/**
+ * Consume a list (bullet / ordered / task) starting at `start`. Indented
+ * continuation lines and nested lists are captured into each item's
+ * `innerBlocks` so the parse → serialise → parse cycle preserves tree
+ * structure instead of flattening nested lists onto a single line.
+ *
+ * `indent` is the column of the item marker for the current list. A
+ * nested list starts ≥2 columns deeper. Lines with less indent than
+ * `indent` belong to the outer block and stop consumption.
+ */
+function consumeList(
+  lines: string[],
+  start: number,
+  indent: number,
+  kind: 'bullet' | 'ordered' | 'task',
+): { items: ListItemBlock[], next: number } {
+  const items: ListItemBlock[] = []
+  let i = start
+  while (i < lines.length) {
+    const line = lines[i]!
+    if (line.trim() === '') {
+      // Blank line — peek ahead: if the next non-blank line still
+      // belongs to this list, treat the blank as an inter-item
+      // separator. Otherwise terminate.
+      let j = i + 1
+      while (j < lines.length && lines[j]!.trim() === '') j++
+      if (j >= lines.length) break
+      const lookahead = lines[j]!
+      if (leadingSpaces(lookahead) < indent) break
+      if (!matchMarker(lookahead.slice(indent), kind)) break
+      i = j
+      continue
+    }
+    const leading = leadingSpaces(line)
+    if (leading < indent) break
+    if (leading > indent) break // belongs to a nested list opened by the previous item
+    const deindented = line.slice(indent)
+    const m = matchMarker(deindented, kind)
+    if (!m) break
+
+    const item: ListItemBlock = { text: m.text }
+    if (kind === 'task') item.checked = m.checked
+    i++
+
+    // Consume continuation: lines indented deeper than `indent`.
+    const contLines: string[] = []
+    while (i < lines.length) {
+      const next = lines[i]!
+      if (next.trim() === '') {
+        // Blank inside a continuation block — could be part of the
+        // continuation if the next non-blank is still indented. Peek.
+        let k = i + 1
+        while (k < lines.length && lines[k]!.trim() === '') k++
+        if (k >= lines.length) break
+        const peekIndent = leadingSpaces(lines[k]!)
+        if (peekIndent <= indent) break
+        // Carry forward the blank line as a paragraph separator.
+        contLines.push('')
+        i++
+        continue
+      }
+      const nextIndent = leadingSpaces(next)
+      if (nextIndent <= indent) break
+      // De-indent by exactly 2 to match the canonical wire form.
+      const deindentBy = Math.min(nextIndent, indent + 2)
+      contLines.push(next.slice(deindentBy))
+      i++
+    }
+    if (contLines.length > 0) {
+      item.innerBlocks = parseBlocks(contLines.join('\n'))
+    }
+    items.push(item)
+  }
+  return { items, next: i }
+}
+
+function leadingSpaces(s: string): number {
+  let n = 0
+  while (n < s.length && s[n] === ' ') n++
+  return n
+}
+
+function matchMarker(
+  s: string,
+  kind: 'bullet' | 'ordered' | 'task',
+): { text: string, checked: boolean } | null {
+  if (kind === 'task') {
+    const m = s.match(TASK_RE)
+    if (!m) return null
+    return { text: m[2]!, checked: m[1]!.toLowerCase() === 'x' }
+  }
+  if (kind === 'bullet') {
+    if (TASK_RE.test(s)) return null
+    const m = s.match(/^[-*+]\s+(.*)$/)
+    if (!m) return null
+    return { text: m[1]!, checked: false }
+  }
+  // ordered
+  const m = s.match(/^\d+\.\s+(.*)$/)
+  if (!m) return null
+  return { text: m[1]!, checked: false }
+}
+
+function parseBlocks(markdown: string): Block[] {
+  // Strip top-level MDX import/export lines (only before the first content block).
+  // We must NOT strip `export default ...` etc. inside fenced code blocks.
+  const rawLines = markdown.split('\n')
+  let firstContentLine = 0
+  while (firstContentLine < rawLines.length) {
+    const l = rawLines[firstContentLine]!
+    if (l.trim() === '' || /^import\s/.test(l) || /^export\s/.test(l)) {
+      firstContentLine++
+    } else {
+      break
+    }
+  }
+  const stripped = rawLines.slice(firstContentLine).join('\n')
+
+  const blocks: Block[] = []
+  const lines = stripped.split('\n')
+  let i = 0
+
+  while (i < lines.length) {
+    const line = lines[i]!
+
+    // Fenced code block (supports variable-length fences: ```, ````, etc.)
+    const fenceBlockMatch = line.match(/^(`{3,})(.*)$/)
+    if (fenceBlockMatch) {
+      const fence = fenceBlockMatch[1]!
+      const lang = fenceBlockMatch[2]!.trim()
+        .replace(/\{[^}]*\}$/, '') // strip highlight annotations like {4-5}
+        .replace(/\s*\[.*\]$/, '') // strip filename hints like [nuxt.config.ts]
+        .trim()
+      const codeLines: string[] = []
+      i++
+      while (i < lines.length && !lines[i]!.startsWith(fence)) {
+        codeLines.push(lines[i]!)
+        i++
+      }
+      i++ // skip closing fence
+      const code = codeLines.join('\n')
+      if (lang === 'math') {
+        // ```math … ``` — block math atom (SPEC.md §6).
+        blocks.push({ type: 'mathBlock', expression: code })
+      }
+      else {
+        blocks.push({ type: 'codeBlock', lang, code })
+      }
+      continue
+    }
+
+    // Heading
+    const headingMatch = line.match(/^(#{1,6})\s+(.*)/)
+    if (headingMatch) {
+      blocks.push({ type: 'heading', level: headingMatch[1]!.length, text: headingMatch[2]!.trim() })
+      i++
+      continue
+    }
+
+    // Horizontal rule
+    if (/^[-*_]{3,}\s*$/.test(line)) {
+      blocks.push({ type: 'hr' })
+      i++
+      continue
+    }
+
+    // Doc embed: ![[uuid|label]]{collapsed tall seamless} — block-level,
+    // must be on its own line. UUID is required (the bracket syntax
+    // without one is reserved for inline doc-link).
+    const embedMatch = line.match(/^!\[\[([0-9a-fA-F-]{36})(?:\|([^\]]+))?\]\](\{[^}]*\})?\s*$/)
+    if (embedMatch) {
+      const docId = embedMatch[1]!
+      const label = embedMatch[2] ?? ''
+      const props = parseMdcProps(embedMatch[3])
+      blocks.push({ type: 'docEmbed', docId, label, props })
+      i++
+      continue
+    }
+
+    // Image: ![alt](src){attrs} — must be on its own line
+    const imgMatch = line.match(/^!\[([^\]]*)\]\(([^)]+)\)(\{[^}]*\})?\s*$/)
+    if (imgMatch) {
+      const alt = imgMatch[1] ?? ''
+      const src = imgMatch[2] ?? ''
+      const attrs = parseMdcProps(imgMatch[3])
+      blocks.push({ type: 'image', src, alt, width: attrs['width'], height: attrs['height'] })
+      i++
+      continue
+    }
+
+    // Blockquote
+    if (line.startsWith('> ') || line === '>') {
+      const bqLines: string[] = []
+      while (i < lines.length && (lines[i]!.startsWith('> ') || lines[i] === '>')) {
+        bqLines.push(lines[i]!.replace(/^>\s?/, ''))
+        i++
+      }
+      blocks.push({ type: 'blockquote', lines: bqLines })
+      continue
+    }
+
+    // Table — detect by leading pipe
+    if (/^\s*\|/.test(line)) {
+      const tableLines: string[] = []
+      while (i < lines.length && /^\s*\|/.test(lines[i]!)) {
+        tableLines.push(lines[i]!)
+        i++
+      }
+      // Need at least: header row, separator row
+      if (tableLines.length >= 2 && isTableSeparator(tableLines[1]!)) {
+        const headerRow = parseTableRow(tableLines[0]!)
+        const dataRows = tableLines.slice(2)
+          .filter(l => !isTableSeparator(l))
+          .map(parseTableRow)
+        blocks.push({ type: 'table', headerRow, dataRows })
+      } else {
+        // Couldn't parse as table — emit as paragraphs
+        for (const l of tableLines) blocks.push({ type: 'paragraph', text: l })
+      }
+      continue
+    }
+
+    // MDC atom block (single-colon, no body): `:name{props}` on its
+    // own line. Currently recognised: `:file{…}` (fileBlock per
+    // SPEC.md §7). Other atom blocks (`:video{…}`, `:embed{…}`, etc.)
+    // are reserved for later workstreams.
+    const atomMatch = line.match(/^:(\w[\w-]*)(\{[^}]*\})?\s*$/)
+    if (atomMatch && atomMatch[1] === 'file') {
+      const props = parseMdcProps(atomMatch[2])
+      const uploadId = props['upload-id'] ?? props['uploadId'] ?? ''
+      const filename = props['filename'] ?? ''
+      const mime = props['mime'] ?? ''
+      const src = props['src'] ?? (uploadId && filename
+        ? `.abracadabra/files/${uploadId}-${filename}`
+        : '')
+      blocks.push({ type: 'fileBlock', src, mime, uploadId, filename })
+      i++
+      continue
+    }
+
+    // MDC component block (::component-name ... ::)
+    // Allow optional leading whitespace so indented nested blocks are recognised
+    const MDC_OPEN = /^\s*(:{2,})(\w[\w-]*)(\{[^}]*\})?\s*$/
+    if (MDC_OPEN.test(line)) {
+      const colons = line.match(/^\s*(:+)/)?.[1]?.length ?? 2
+      const componentName = line.match(/^\s*:{2,}(\w[\w-]*)/)?.[1] ?? ''
+      const innerLines: string[] = []
+      i++
+      // Collect inner lines, but skip over fenced code blocks so that
+      // `::` inside ```...``` or ````...```` doesn't close the MDC block
+      while (i < lines.length) {
+        const l = lines[i]!
+        // Closing tag: same colon count, possibly indented
+        if (new RegExp(`^\\s*:{${colons}}\\s*$`).test(l)) { i++; break }
+        // If we hit a fenced code block, consume it entirely
+        const innerFence = l.match(/^(\s*`{3,})/)
+        if (innerFence) {
+          const fenceStr = innerFence[1]!.trimStart()
+          innerLines.push(l)
+          i++
+          while (i < lines.length && !lines[i]!.trimStart().startsWith(fenceStr)) {
+            innerLines.push(lines[i]!)
+            i++
+          }
+          if (i < lines.length) { innerLines.push(lines[i]!); i++ } // push closing fence
+          continue
+        }
+        innerLines.push(l)
+        i++
+      }
+
+      // Strip common leading indentation from inner lines
+      const nonBlank = innerLines.filter(l => l.trim().length > 0)
+      if (nonBlank.length) {
+        const minIndent = Math.min(...nonBlank.map(l => l.match(/^(\s*)/)?.[1]?.length ?? 0))
+        if (minIndent > 0) {
+          for (let j = 0; j < innerLines.length; j++) {
+            innerLines[j] = innerLines[j]!.slice(Math.min(minIndent, innerLines[j]!.length))
+          }
+        }
+      }
+
+      // Strip inline frontmatter props (---...---)
+      let contentStart = 0
+      if (innerLines[0]?.trim() === '---') {
+        const fmEnd = innerLines.findIndex((l, idx) => idx > 0 && l.trim() === '---')
+        if (fmEnd !== -1) contentStart = fmEnd + 1
+      }
+      const contentLines = innerLines.slice(contentStart)
+
+      // Split into named slots: collect default slot and #code slot separately
+      const defaultSlotLines: string[] = []
+      const codeSlotLines: string[] = []
+      let currentSlot: 'default' | 'code' | 'other' = 'default'
+      for (const l of contentLines) {
+        if (/^#code\s*$/.test(l)) { currentSlot = 'code'; continue }
+        if (/^#\w+/.test(l) && !/^#{2,}\s/.test(l)) { currentSlot = 'other'; continue }
+        if (currentSlot === 'default') defaultSlotLines.push(l)
+        else if (currentSlot === 'code') codeSlotLines.push(l)
+      }
+      const innerBlocks = parseBlocks(defaultSlotLines.join('\n'))
+
+      // Extract fenced code from #code slot and add as code blocks
+      const codeBlocks = extractFencedCode(codeSlotLines)
+
+      const CALLOUT_NAMES = new Set(['tip', 'note', 'info', 'warning', 'caution', 'danger', 'callout', 'alert'])
+      if (CALLOUT_NAMES.has(componentName.toLowerCase())) {
+        blocks.push({ type: 'callout', calloutType: componentName.toLowerCase(), innerBlocks })
+      } else {
+        const mdcProps = parseMdcProps(line.match(MDC_OPEN)?.[3])
+        const lc = componentName.toLowerCase()
+
+        if (lc === 'collapsible') {
+          blocks.push({ type: 'collapsible', label: mdcProps['label'] || 'Details', open: mdcProps['open'] === 'true', innerBlocks })
+        } else if (lc === 'steps') {
+          blocks.push({ type: 'steps', innerBlocks })
+        } else if (lc === 'card') {
+          blocks.push({ type: 'card', title: mdcProps['title'] || '', icon: mdcProps['icon'] || '', to: mdcProps['to'] || '', innerBlocks })
+        } else if (lc === 'card-group') {
+          // Each nested ::card inside card-group is already parsed as inner blocks
+          const cards = innerBlocks.filter(b => b.type === 'card')
+          if (cards.length) {
+            blocks.push({ type: 'cardGroup', cards })
+          } else {
+            blocks.push(...innerBlocks)
+          }
+        } else if (lc === 'code-collapse') {
+          blocks.push({ type: 'codeCollapse', codeBlocks: codeBlocks.length ? codeBlocks : innerBlocks.filter(b => b.type === 'codeBlock') })
+        } else if (lc === 'code-group') {
+          const allCode = [...innerBlocks.filter(b => b.type === 'codeBlock'), ...codeBlocks]
+          blocks.push({ type: 'codeGroup', codeBlocks: allCode })
+        } else if (lc === 'code-preview') {
+          blocks.push({ type: 'codePreview', innerBlocks, codeBlocks })
+        } else if (lc === 'code-tree') {
+          blocks.push({ type: 'codeTree', files: mdcProps['files'] || '[]' })
+        } else if (lc === 'accordion') {
+          const items = parseMdcChildren(contentLines, 'item')
+          if (items.length) {
+            blocks.push({ type: 'accordion', items })
+          } else {
+            blocks.push({ type: 'accordion', items: [{ label: 'Item 1', icon: '', innerBlocks }] })
+          }
+        } else if (lc === 'tabs') {
+          const items = parseMdcChildren(contentLines, 'tab')
+          if (items.length) {
+            blocks.push({ type: 'tabs', items })
+          } else {
+            blocks.push({ type: 'tabs', items: [{ label: 'Tab 1', icon: '', innerBlocks }] })
+          }
+        } else if (lc === 'field') {
+          blocks.push({ type: 'field', name: mdcProps['name'] || '', fieldType: mdcProps['type'] || 'string', required: mdcProps['required'] === 'true', innerBlocks })
+        } else if (lc === 'field-group') {
+          const fields = innerBlocks.filter(b => b.type === 'field')
+          if (fields.length) {
+            blocks.push({ type: 'fieldGroup', fields })
+          } else {
+            blocks.push(...innerBlocks)
+          }
+        } else {
+          // Unknown component — inline the content
+          blocks.push(...innerBlocks)
+          blocks.push(...codeBlocks)
+        }
+      }
+      continue
+    }
+
+    // Task list (must check before bullet list — `- [x]` starts the same way)
+    if (TASK_RE.test(line)) {
+      const { items, next } = consumeList(lines, i, 0, 'task')
+      i = next
+      blocks.push({ type: 'taskList', items })
+      continue
+    }
+
+    // Bullet list
+    if (/^[-*+]\s+/.test(line)) {
+      const { items, next } = consumeList(lines, i, 0, 'bullet')
+      if (items.length > 0) {
+        i = next
+        blocks.push({ type: 'bulletList', items })
+        continue
+      }
+    }
+
+    // Ordered list
+    if (/^\d+\.\s+/.test(line)) {
+      const { items, next } = consumeList(lines, i, 0, 'ordered')
+      if (items.length > 0) {
+        i = next
+        blocks.push({ type: 'orderedList', items })
+        continue
+      }
+    }
+
+    // Blank line
+    if (line.trim() === '') {
+      i++
+      continue
+    }
+
+    // Paragraph — consecutive non-special lines
+    const paraLines: string[] = []
+    while (
+      i < lines.length
+      && lines[i]!.trim() !== ''
+      && !/^(#{1,6}\s|[-*+]\s|\d+\.\s|>|`{3,}|\s*\||[-*_]{3,}\s*$|\s*:{2,}\w)/.test(lines[i]!)
+    ) {
+      paraLines.push(lines[i]!)
+      i++
+    }
+    if (paraLines.length) {
+      blocks.push({ type: 'paragraph', text: paraLines.join(' ') })
+    }
+  }
+
+  return blocks
+}
+
+// ── Y.js content population ──────────────────────────────────────────────────
+//
+// IMPORTANT — attach-before-fill ordering:
+//
+// Y.XmlText.insert() is only deterministically ordered when the text node is
+// already attached to a Y.Doc (so it can use the doc's logical clock).
+// Inserting text into a standalone Y.XmlText gives every operation clock-0,
+// which causes the YATA algorithm to produce reversed or scrambled text.
+//
+// Rule: attach container to doc → attach Y.XmlText to container → insert text.
+
+/**
+ * Insert formatted inline tokens into an already-attached Y.XmlElement.
+ * Creates one Y.XmlText per token (attach first, fill second).
+ */
+function fillTextInto(el: Y.XmlElement, tokens: InlineToken[]): void {
+  const filtered = tokens.filter(t => t.text.length > 0)
+  if (!filtered.length) return
+
+  // Create empty text nodes and attach them to el in one batch
+  const xtNodes = filtered.map(() => new Y.XmlText())
+  el.insert(0, xtNodes)
+
+  // Fill text only after attachment — el is already attached to the doc
+  filtered.forEach((tok, i) => {
+    if (tok.attrs) {
+      xtNodes[i]!.insert(0, tok.text, tok.attrs as Record<string, boolean | object>)
+    } else {
+      xtNodes[i]!.insert(0, tok.text)
+    }
+  })
+}
+
+function blockElName(b: Block): string {
+  switch (b.type) {
+    case 'heading': return 'heading'
+    case 'paragraph': return 'paragraph'
+    case 'bulletList': return 'bulletList'
+    case 'orderedList': return 'orderedList'
+    case 'taskList': return 'taskList'
+    case 'codeBlock': return 'codeBlock'
+    case 'blockquote': return 'blockquote'
+    case 'table': return 'table'
+    case 'hr': return 'horizontalRule'
+    case 'callout': return 'callout'
+    case 'collapsible': return 'collapsible'
+    case 'steps': return 'steps'
+    case 'card': return 'card'
+    case 'cardGroup': return 'cardGroup'
+    case 'codeCollapse': return 'codeCollapse'
+    case 'codeGroup': return 'codeGroup'
+    case 'codePreview': return 'codePreview'
+    case 'codeTree': return 'codeTree'
+    case 'accordion': return 'accordion'
+    case 'tabs': return 'tabs'
+    case 'field': return 'field'
+    case 'fieldGroup': return 'fieldGroup'
+    case 'image': return 'image'
+    case 'docEmbed': return 'docEmbed'
+    case 'mathBlock': return 'mathBlock'
+    case 'fileBlock': return 'fileBlock'
+  }
+}
+
+function populateListItemChildren(
+  itemEl: Y.XmlElement,
+  item: ListItemBlock,
+  _itemKind: 'listItem' | 'taskItem',
+): void {
+  // Always start with a paragraph carrying the item's inline text.
+  const paraEl = new Y.XmlElement('paragraph')
+  itemEl.insert(itemEl.length, [paraEl])
+  fillTextInto(paraEl, parseInline(item.text))
+
+  // Nested blocks (sub-lists, paragraphs, code, etc.) follow.
+  if (!item.innerBlocks?.length) return
+  const innerEls = item.innerBlocks.map(b => new Y.XmlElement(blockElName(b)))
+  itemEl.insert(itemEl.length, innerEls)
+  item.innerBlocks.forEach((b, i) => fillBlock(innerEls[i]!, b))
+}
+
+function fillBlock(el: Y.XmlElement, block: Block): void {
+  switch (block.type) {
+    case 'heading': {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      el.setAttribute('level', block.level as any)
+      fillTextInto(el, parseInline(block.text))
+      break
+    }
+    case 'paragraph': {
+      fillTextInto(el, parseInline(block.text))
+      break
+    }
+    case 'bulletList':
+    case 'orderedList': {
+      const listItemEls = block.items.map(() => new Y.XmlElement('listItem'))
+      el.insert(0, listItemEls)
+      block.items.forEach((item, i) => {
+        populateListItemChildren(listItemEls[i]!, item, 'listItem')
+      })
+      break
+    }
+    case 'taskList': {
+      const taskItemEls = block.items.map(() => new Y.XmlElement('taskItem'))
+      el.insert(0, taskItemEls)
+      block.items.forEach((item, i) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        taskItemEls[i]!.setAttribute('checked', !!item.checked as any)
+        populateListItemChildren(taskItemEls[i]!, item, 'taskItem')
+      })
+      break
+    }
+    case 'codeBlock': {
+      if (block.lang) el.setAttribute('language', block.lang)
+      const xt = new Y.XmlText()
+      el.insert(0, [xt]) // attach xt to el (already attached)
+      xt.insert(0, block.code)
+      break
+    }
+    case 'blockquote': {
+      const paraEls = block.lines.map(() => new Y.XmlElement('paragraph'))
+      el.insert(0, paraEls)
+      block.lines.forEach((line, i) => fillTextInto(paraEls[i]!, parseInline(line)))
+      break
+    }
+    case 'table': {
+      const headerRowEl = new Y.XmlElement('tableRow')
+      const dataRowEls = block.dataRows.map(() => new Y.XmlElement('tableRow'))
+      el.insert(0, [headerRowEl, ...dataRowEls])
+
+      // Header cells
+      const headerCellEls = block.headerRow.map(() => new Y.XmlElement('tableHeader'))
+      headerRowEl.insert(0, headerCellEls)
+      block.headerRow.forEach((cellText, i) => {
+        const paraEl = new Y.XmlElement('paragraph')
+        headerCellEls[i]!.insert(0, [paraEl])
+        fillTextInto(paraEl, parseInline(cellText))
+      })
+
+      // Data rows
+      block.dataRows.forEach((row, ri) => {
+        const cellEls = row.map(() => new Y.XmlElement('tableCell'))
+        dataRowEls[ri]!.insert(0, cellEls)
+        row.forEach((cellText, ci) => {
+          const paraEl = new Y.XmlElement('paragraph')
+          cellEls[ci]!.insert(0, [paraEl])
+          fillTextInto(paraEl, parseInline(cellText))
+        })
+      })
+      break
+    }
+    case 'hr': break // horizontalRule has no content
+    case 'callout': {
+      el.setAttribute('type', block.calloutType)
+      if (!block.innerBlocks.length) {
+        const paraEl = new Y.XmlElement('paragraph')
+        el.insert(0, [paraEl])
+        break
+      }
+      const innerEls = block.innerBlocks.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, innerEls)
+      block.innerBlocks.forEach((b, i) => fillBlock(innerEls[i]!, b))
+      break
+    }
+    case 'collapsible': {
+      el.setAttribute('label', block.label)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      el.setAttribute('open', block.open as any)
+      const inner = block.innerBlocks.length ? block.innerBlocks : [{ type: 'paragraph' as const, text: '' }]
+      const innerEls = inner.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, innerEls)
+      inner.forEach((b, i) => fillBlock(innerEls[i]!, b))
+      break
+    }
+    case 'steps': {
+      const inner = block.innerBlocks.length ? block.innerBlocks : [{ type: 'paragraph' as const, text: '' }]
+      const innerEls = inner.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, innerEls)
+      inner.forEach((b, i) => fillBlock(innerEls[i]!, b))
+      break
+    }
+    case 'card': {
+      if (block.title) el.setAttribute('title', block.title)
+      if (block.icon) el.setAttribute('icon', block.icon)
+      if (block.to) el.setAttribute('to', block.to)
+      const inner = block.innerBlocks.length ? block.innerBlocks : [{ type: 'paragraph' as const, text: '' }]
+      const innerEls = inner.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, innerEls)
+      inner.forEach((b, i) => fillBlock(innerEls[i]!, b))
+      break
+    }
+    case 'cardGroup': {
+      const cardEls = block.cards.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, cardEls)
+      block.cards.forEach((b, i) => fillBlock(cardEls[i]!, b))
+      break
+    }
+    case 'codeCollapse': {
+      const codes = block.codeBlocks.length ? block.codeBlocks : [{ type: 'codeBlock' as const, lang: '', code: '' }]
+      // Only insert the first code block (content model is singular codeBlock)
+      const codeEl = new Y.XmlElement('codeBlock')
+      el.insert(0, [codeEl])
+      fillBlock(codeEl, codes[0]!)
+      break
+    }
+    case 'codeGroup': {
+      const codes = block.codeBlocks.length ? block.codeBlocks : [{ type: 'codeBlock' as const, lang: '', code: '' }]
+      const codeEls = codes.map(() => new Y.XmlElement('codeBlock'))
+      el.insert(0, codeEls)
+      codes.forEach((b, i) => fillBlock(codeEls[i]!, b))
+      break
+    }
+    case 'codePreview': {
+      const all = [...block.innerBlocks, ...block.codeBlocks]
+      const inner = all.length ? all : [{ type: 'paragraph' as const, text: '' }]
+      const innerEls = inner.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, innerEls)
+      inner.forEach((b, i) => fillBlock(innerEls[i]!, b))
+      break
+    }
+    case 'codeTree': {
+      el.setAttribute('files', block.files)
+      break
+    }
+    case 'accordion': {
+      const itemEls = block.items.map(() => new Y.XmlElement('accordionItem'))
+      el.insert(0, itemEls)
+      block.items.forEach((item, i) => {
+        itemEls[i]!.setAttribute('label', item.label)
+        if (item.icon) itemEls[i]!.setAttribute('icon', item.icon)
+        const inner = item.innerBlocks.length ? item.innerBlocks : [{ type: 'paragraph' as const, text: '' }]
+        const childEls = inner.map(b => new Y.XmlElement(blockElName(b)))
+        itemEls[i]!.insert(0, childEls)
+        inner.forEach((b, ci) => fillBlock(childEls[ci]!, b))
+      })
+      break
+    }
+    case 'tabs': {
+      const itemEls = block.items.map(() => new Y.XmlElement('tabsItem'))
+      el.insert(0, itemEls)
+      block.items.forEach((item, i) => {
+        itemEls[i]!.setAttribute('label', item.label)
+        if (item.icon) itemEls[i]!.setAttribute('icon', item.icon)
+        const inner = item.innerBlocks.length ? item.innerBlocks : [{ type: 'paragraph' as const, text: '' }]
+        const childEls = inner.map(b => new Y.XmlElement(blockElName(b)))
+        itemEls[i]!.insert(0, childEls)
+        inner.forEach((b, ci) => fillBlock(childEls[ci]!, b))
+      })
+      break
+    }
+    case 'field': {
+      if (block.name) el.setAttribute('name', block.name)
+      el.setAttribute('type', block.fieldType)
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      el.setAttribute('required', block.required as any)
+      const inner = block.innerBlocks.length ? block.innerBlocks : [{ type: 'paragraph' as const, text: '' }]
+      const innerEls = inner.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, innerEls)
+      inner.forEach((b, i) => fillBlock(innerEls[i]!, b))
+      break
+    }
+    case 'fieldGroup': {
+      const fieldEls = block.fields.map(b => new Y.XmlElement(blockElName(b)))
+      el.insert(0, fieldEls)
+      block.fields.forEach((b, i) => fillBlock(fieldEls[i]!, b))
+      break
+    }
+    case 'image': {
+      el.setAttribute('src', block.src)
+      if (block.alt) el.setAttribute('alt', block.alt)
+      if (block.width) el.setAttribute('width', block.width)
+      if (block.height) el.setAttribute('height', block.height)
+      break
+    }
+    case 'docEmbed': {
+      el.setAttribute('docId', block.docId)
+      for (const flag of ['collapsed', 'tall', 'seamless']) {
+        if (block.props[flag] === 'true' || block.props[flag] === '1') {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          el.setAttribute(flag, true as any)
+        }
+      }
+      break
+    }
+    case 'mathBlock': {
+      el.setAttribute('expression', block.expression)
+      break
+    }
+    case 'fileBlock': {
+      if (block.src) el.setAttribute('src', block.src)
+      if (block.mime) el.setAttribute('mime', block.mime)
+      if (block.uploadId) el.setAttribute('uploadId', block.uploadId)
+      if (block.filename) el.setAttribute('filename', block.filename)
+      break
+    }
+  }
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Parses markdown text and writes the result into a Y.XmlFragment that
+ * TipTap's Collaboration extension can read.
+ *
+ * Requires `fragment.doc` to be set (i.e. the fragment must already be
+ * obtained from a live Y.Doc via `ydoc.getXmlFragment('default')`).
+ *
+ * @param fragment      The target `Y.Doc.getXmlFragment('default')`
+ * @param markdown      Raw markdown string
+ * @param fallbackTitle Used as the title when the markdown has no H1
+ */
+export function populateYDocFromMarkdown(
+  fragment: Y.XmlFragment,
+  markdown: string,
+  fallbackTitle = 'Untitled'
+): void {
+  const ydoc = fragment.doc
+  if (!ydoc) {
+    console.warn('[markdownToYjs] fragment has no doc — skipping population')
+    return
+  }
+
+  // Strip YAML frontmatter from the head of the input so its `---`
+  // fences don't get reinterpreted as horizontal rules.
+  const fm = parseFrontmatter(markdown)
+  const blocks = parseBlocks(fm.body)
+
+  let title = fallbackTitle
+  // The title can live in three places: frontmatter, the first body H1,
+  // or a filename-derived fallback. We track which so the serialiser
+  // can round-trip into the same form. Body H1 wins over frontmatter
+  // when both are present (frontmatter's title is typically a stale
+  // copy of the body H1).
+  let titleSource: 'h1' | 'frontmatter' | undefined
+  if (fm.title !== undefined) {
+    title = fm.title
+    titleSource = 'frontmatter'
+  }
+  let contentBlocks = blocks
+  const h1 = blocks.findIndex(b => b.type === 'heading' && b.level === 1)
+  if (h1 !== -1) {
+    title = (blocks[h1] as { type: 'heading', level: number, text: string }).text
+    contentBlocks = blocks.filter((_, i) => i !== h1)
+    titleSource = 'h1'
+  }
+  // For empty markdown we used to seed an empty paragraph so the
+  // editor had something to focus. That bytes-pads the round-trip
+  // back to "\n\n" — keep contentBlocks empty so the serialiser can
+  // emit a clean empty file.
+
+  ydoc.transact(() => {
+    // ── Step 1: create empty skeleton elements ────────────────────────────
+    const headerEl = new Y.XmlElement('documentHeader')
+    const metaEl = new Y.XmlElement('documentMeta')
+    const bodyEls: Y.XmlElement[] = contentBlocks.map((b) => {
+      switch (b.type) {
+        case 'heading': return new Y.XmlElement('heading')
+        case 'paragraph': return new Y.XmlElement('paragraph')
+        case 'bulletList': return new Y.XmlElement('bulletList')
+        case 'orderedList': return new Y.XmlElement('orderedList')
+        case 'taskList': return new Y.XmlElement('taskList')
+        case 'codeBlock': return new Y.XmlElement('codeBlock')
+        case 'blockquote': return new Y.XmlElement('blockquote')
+        case 'table': return new Y.XmlElement('table')
+        case 'hr': return new Y.XmlElement('horizontalRule')
+        case 'callout': return new Y.XmlElement('callout')
+        case 'collapsible': return new Y.XmlElement('collapsible')
+        case 'steps': return new Y.XmlElement('steps')
+        case 'card': return new Y.XmlElement('card')
+        case 'cardGroup': return new Y.XmlElement('cardGroup')
+        case 'codeCollapse': return new Y.XmlElement('codeCollapse')
+        case 'codeGroup': return new Y.XmlElement('codeGroup')
+        case 'codePreview': return new Y.XmlElement('codePreview')
+        case 'codeTree': return new Y.XmlElement('codeTree')
+        case 'accordion': return new Y.XmlElement('accordion')
+        case 'tabs': return new Y.XmlElement('tabs')
+        case 'field': return new Y.XmlElement('field')
+        case 'fieldGroup': return new Y.XmlElement('fieldGroup')
+        case 'image': return new Y.XmlElement('image')
+        case 'docEmbed': return new Y.XmlElement('docEmbed')
+        case 'mathBlock': return new Y.XmlElement('mathBlock')
+        case 'fileBlock': return new Y.XmlElement('fileBlock')
+      }
+    })
+
+    // ── Step 2: attach ALL skeleton elements to fragment in one shot ──────
+    // After this line everything is connected to ydoc and subsequent ops
+    // use the real doc clock — no more clock-0 scrambling.
+    fragment.insert(0, [headerEl, metaEl, ...bodyEls])
+
+    // ── Step 3: fill header title + record where it came from ─────────────
+    if (titleSource) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      headerEl.setAttribute('titleSource', titleSource as any)
+    }
+    const headerXt = new Y.XmlText()
+    headerEl.insert(0, [headerXt])
+    headerXt.insert(0, title)
+
+    // ── Step 4: stash parsed frontmatter meta on documentMeta ─────────────
+    // Each universal-meta key becomes an attribute on documentMeta so
+    // the serialiser can faithfully emit it back to frontmatter. Type
+    // (page-type) is also stashed here under the well-known "type" key.
+    for (const k of Object.keys(fm.meta)) {
+      const v = (fm.meta as Record<string, unknown>)[k]
+      if (v === undefined || v === null) continue
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      metaEl.setAttribute(k, v as any)
+    }
+    if (fm.type) {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      metaEl.setAttribute('type', fm.type as any)
+    }
+
+    // ── Step 5: fill body blocks ──────────────────────────────────────────
+    contentBlocks.forEach((block, i) => fillBlock(bodyEls[i]!, block))
+  })
+}