@abraca/convert 2.3.0

package/src/yjs-to-markdown.ts

@@ -0,0 +1,820 @@
+import * as Y from 'yjs'
+import type { DocPageMeta } from './types.ts'
+
+// ── Inline serialization ────────────────────────────────────────────────────
+
+function serializeDelta(delta: any[]): string {
+  let result = ''
+  for (const op of delta) {
+    if (typeof op.insert !== 'string') continue
+    let text = op.insert as string
+    const attrs = op.attributes ?? {}
+
+    if (attrs.code) {
+      result += `\`${text}\``
+      continue
+    }
+
+    // Badge mark
+    if (attrs.badge) {
+      const b = attrs.badge as { label?: string, color?: string, variant?: string }
+      const props: string[] = []
+      if (b.color && b.color !== 'neutral') props.push(`color="${b.color}"`)
+      if (b.variant && b.variant !== 'subtle') props.push(`variant="${b.variant}"`)
+      result += `:badge[${b.label || text}]${props.length ? `{${props.join(' ')}}` : ''}`
+      continue
+    }
+
+    // Prose icon mark
+    if (attrs.proseIcon) {
+      const icon = (attrs.proseIcon as { name?: string }).name || 'i-lucide-star'
+      result += `:icon{name="${icon}"}`
+      continue
+    }
+
+    // Kbd mark
+    if (attrs.kbd) {
+      const value = (attrs.kbd as { value?: string }).value || text
+      result += `:kbd{value="${value}"}`
+      continue
+    }
+
+    // docLink — inline doc reference. The label is the displayed text;
+    // the docId is the canonical anchor. Per SPEC.md §6 the label may
+    // be regenerated from a live registry, but the converter is pure —
+    // we use the stored text. Consumers that need fresh labels should
+    // rewrite them in the Y tree before serialising.
+    if (attrs.docLink) {
+      const docId = (attrs.docLink as { docId?: string }).docId
+      if (docId) {
+        result += text === docId ? `[[${docId}]]` : `[[${docId}|${text}]]`
+        continue
+      }
+    }
+
+    // mention — `@[label](user:uuid)`
+    if (attrs.mention) {
+      const { userId, label } = attrs.mention as { userId?: string, label?: string }
+      if (userId) {
+        result += `@[${label || text}](user:${userId})`
+        continue
+      }
+    }
+
+    // Inline math — `$expression$`
+    if (attrs.mathInline) {
+      const expr = (attrs.mathInline as { expression?: string }).expression ?? text
+      result += `$${expr}$`
+      continue
+    }
+
+    if (attrs.bold) text = `**${text}**`
+    if (attrs.italic) text = `*${text}*`
+    if (attrs.strike) text = `~~${text}~~`
+    if (attrs.link) {
+      const href = (attrs.link as { href?: string }).href ?? ''
+      text = `[${text}](${href})`
+    }
+
+    result += text
+  }
+  return result
+}
+
+function serializeInline(el: Y.XmlElement | Y.XmlFragment): string {
+  const parts: string[] = []
+  for (const child of el.toArray()) {
+    if (child instanceof Y.XmlText) {
+      parts.push(serializeDelta(child.toDelta()))
+    } else if (child instanceof Y.XmlElement) {
+      // Nested inline element — just get text
+      parts.push(serializeInline(child))
+    }
+  }
+  return parts.join('')
+}
+
+// ── Block serialization ─────────────────────────────────────────────────────
+
+function serializeBlock(el: Y.XmlElement | Y.XmlText, indent = ''): string {
+  if (el instanceof Y.XmlText) {
+    return serializeDelta(el.toDelta())
+  }
+
+  const name = el.nodeName
+  switch (name) {
+    case 'documentHeader':
+    case 'documentMeta':
+      return '' // handled via frontmatter
+
+    case 'heading': {
+      const level = Number(el.getAttribute('level') ?? 2)
+      const hashes = '#'.repeat(level)
+      return `${hashes} ${serializeInline(el)}`
+    }
+
+    case 'paragraph':
+      return serializeInline(el)
+
+    case 'bulletList':
+      return serializeListItems(el, 'bullet', indent)
+
+    case 'orderedList':
+      return serializeListItems(el, 'ordered', indent)
+
+    case 'taskList':
+      return serializeTaskList(el, indent)
+
+    case 'codeBlock': {
+      const lang = el.getAttribute('language') ?? ''
+      const code = getCodeBlockText(el)
+      // Empty body — single-newline form preserves the `\`\`\`lang\n\`\`\``
+      // wire form (no padding blank line).
+      if (code === '') return `\`\`\`${lang}\n\`\`\``
+      return `\`\`\`${lang}\n${code}\n\`\`\``
+    }
+
+    case 'blockquote': {
+      const lines: string[] = []
+      for (const child of el.toArray()) {
+        if (child instanceof Y.XmlElement) {
+          const text = serializeBlock(child)
+          for (const line of text.split('\n')) {
+            lines.push(`> ${line}`)
+          }
+        }
+      }
+      return lines.join('\n')
+    }
+
+    case 'table':
+      return serializeTable(el)
+
+    case 'horizontalRule':
+      return '---'
+
+    case 'image': {
+      const src = el.getAttribute('src') ?? ''
+      const alt = el.getAttribute('alt') ?? ''
+      const width = el.getAttribute('width')
+      const height = el.getAttribute('height')
+      const attrs: string[] = []
+      // MDC convention is `{width=400 height=300}` — bare values, no
+      // quotes — matching what the parser at the time accepts.
+      if (width) attrs.push(`width=${width}`)
+      if (height) attrs.push(`height=${height}`)
+      return `![${alt}](${src})${attrs.length ? `{${attrs.join(' ')}}` : ''}`
+    }
+
+    case 'docEmbed': {
+      const docId = el.getAttribute('docId') ?? ''
+      const collapsed: unknown = el.getAttribute('collapsed')
+      const tall: unknown = el.getAttribute('tall')
+      const seamless: unknown = el.getAttribute('seamless')
+      const flags: string[] = []
+      if (collapsed === true || collapsed === 'true') flags.push('collapsed')
+      if (tall === true || tall === 'true') flags.push('tall')
+      if (seamless === true || seamless === 'true') flags.push('seamless')
+      return `![[${docId}]]${flags.length ? `{${flags.join(' ')}}` : ''}`
+    }
+
+    case 'mathBlock': {
+      const expr = el.getAttribute('expression') ?? ''
+      return `\`\`\`math\n${expr}\n\`\`\``
+    }
+
+    case 'fileBlock': {
+      // SPEC.md §7 wire form: `:file{src=… mime=… upload-id=… filename=…}`.
+      // The sidecar binary lives under `.abracadabra/files/`; this tag
+      // is purely a reference into that store + the manifest.
+      const uploadId = el.getAttribute('uploadId') ?? ''
+      const filename = el.getAttribute('filename') ?? ''
+      const mime = el.getAttribute('mime') ?? ''
+      const src = el.getAttribute('src') ?? (uploadId && filename
+        ? `.abracadabra/files/${uploadId}-${filename}`
+        : '')
+      const props: string[] = []
+      if (src) props.push(`src="${src}"`)
+      if (mime) props.push(`mime="${mime}"`)
+      if (uploadId) props.push(`upload-id="${uploadId}"`)
+      if (filename) props.push(`filename="${filename}"`)
+      return `:file{${props.join(' ')}}`
+    }
+
+    // MDC components
+    case 'callout': {
+      const type = el.getAttribute('type') ?? 'note'
+      return `::${type}\n${serializeChildren(el)}\n::`
+    }
+
+    case 'collapsible': {
+      const label = el.getAttribute('label') ?? 'Details'
+      const open: unknown = el.getAttribute('open')
+      const props: string[] = [`label="${label}"`]
+      if (open === true || open === 'true') props.push('open="true"')
+      return `::collapsible{${props.join(' ')}}\n${serializeChildren(el)}\n::`
+    }
+
+    case 'steps':
+      return `::steps\n${serializeChildren(el)}\n::`
+
+    case 'card': {
+      const props: string[] = []
+      const title = el.getAttribute('title')
+      const icon = el.getAttribute('icon')
+      const to = el.getAttribute('to')
+      if (title) props.push(`title="${title}"`)
+      if (icon) props.push(`icon="${icon}"`)
+      if (to) props.push(`to="${to}"`)
+      return `::card${props.length ? `{${props.join(' ')}}` : ''}\n${serializeChildren(el)}\n::`
+    }
+
+    case 'cardGroup': {
+      const cards = el.toArray()
+        .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+        .map(c => serializeBlock(c))
+        .join('\n\n')
+      return `::card-group\n${cards}\n::`
+    }
+
+    case 'codeCollapse': {
+      const code = el.toArray()
+        .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement && c.nodeName === 'codeBlock')
+        .map(c => serializeBlock(c))
+        .join('\n\n')
+      return `::code-collapse\n${code}\n::`
+    }
+
+    case 'codeGroup': {
+      const code = el.toArray()
+        .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement && c.nodeName === 'codeBlock')
+        .map(c => serializeBlock(c))
+        .join('\n\n')
+      return `::code-group\n${code}\n::`
+    }
+
+    case 'codePreview': {
+      const children = el.toArray().filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+      const nonCode = children.filter(c => c.nodeName !== 'codeBlock').map(c => serializeBlock(c)).join('\n\n')
+      const code = children.filter(c => c.nodeName === 'codeBlock').map(c => serializeBlock(c)).join('\n\n')
+      const parts = [nonCode]
+      if (code) parts.push(`#code\n${code}`)
+      return `::code-preview\n${parts.filter(Boolean).join('\n\n')}\n::`
+    }
+
+    case 'codeTree': {
+      const files = el.getAttribute('files') ?? '[]'
+      return `::code-tree{files="${files}"}\n::`
+    }
+
+    case 'accordion':
+      return serializeSlottedContainer(el, 'accordion', 'accordionItem', 'item')
+
+    case 'tabs':
+      return serializeSlottedContainer(el, 'tabs', 'tabsItem', 'tab')
+
+    case 'field': {
+      const fieldName = el.getAttribute('name') ?? ''
+      const fieldType = el.getAttribute('type') ?? 'string'
+      const required: unknown = el.getAttribute('required')
+      const props = [`name="${fieldName}"`, `type="${fieldType}"`]
+      if (required === true || required === 'true') props.push('required="true"')
+      return `::field{${props.join(' ')}}\n${serializeChildren(el)}\n::`
+    }
+
+    case 'fieldGroup': {
+      const fields = el.toArray()
+        .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+        .map(c => serializeBlock(c))
+        .join('\n\n')
+      return `::field-group\n${fields}\n::`
+    }
+
+    default:
+      // Unknown node type — try to serialize children
+      return serializeChildren(el)
+  }
+}
+
+function serializeChildren(el: Y.XmlElement | Y.XmlFragment): string {
+  const blocks: string[] = []
+  for (const child of el.toArray()) {
+    if (child instanceof Y.XmlElement) {
+      const text = serializeBlock(child)
+      if (text) blocks.push(text)
+    } else if (child instanceof Y.XmlText) {
+      const text = serializeDelta(child.toDelta())
+      if (text) blocks.push(text)
+    }
+  }
+  return blocks.join('\n\n')
+}
+
+function serializeListItems(el: Y.XmlElement, type: 'bullet' | 'ordered', indent: string): string {
+  const lines: string[] = []
+  let counter = 1
+  for (const child of el.toArray()) {
+    if (!(child instanceof Y.XmlElement) || child.nodeName !== 'listItem') continue
+    const prefix = type === 'bullet' ? '- ' : `${counter++}. `
+    // A listItem may contain paragraphs and nested lists
+    const subParts: string[] = []
+    for (const sub of child.toArray()) {
+      if (!(sub instanceof Y.XmlElement)) continue
+      if (sub.nodeName === 'bulletList') {
+        subParts.push(serializeListItems(sub, 'bullet', indent + '  '))
+      } else if (sub.nodeName === 'orderedList') {
+        subParts.push(serializeListItems(sub, 'ordered', indent + '  '))
+      } else {
+        subParts.push(serializeInline(sub))
+      }
+    }
+    if (subParts.length <= 1) {
+      lines.push(`${indent}${prefix}${subParts[0] ?? ''}`)
+    } else {
+      lines.push(`${indent}${prefix}${subParts[0] ?? ''}`)
+      for (let i = 1; i < subParts.length; i++) {
+        // Nested lists are already indented; plain text gets continuation indent
+        lines.push(subParts[i]!)
+      }
+    }
+  }
+  return lines.join('\n')
+}
+
+function serializeTaskList(el: Y.XmlElement, indent: string): string {
+  const lines: string[] = []
+  for (const child of el.toArray()) {
+    if (!(child instanceof Y.XmlElement) || child.nodeName !== 'taskItem') continue
+    const checked: unknown = child.getAttribute('checked')
+    const marker = (checked === true || checked === 'true') ? '[x]' : '[ ]'
+
+    let header = ''
+    const nestedParts: string[] = []
+    for (const sub of child.toArray()) {
+      if (!(sub instanceof Y.XmlElement)) continue
+      if (sub.nodeName === 'paragraph' && header === '') {
+        header = serializeInline(sub)
+      }
+      else if (sub.nodeName === 'bulletList') {
+        nestedParts.push(serializeListItems(sub, 'bullet', indent + '  '))
+      }
+      else if (sub.nodeName === 'orderedList') {
+        nestedParts.push(serializeListItems(sub, 'ordered', indent + '  '))
+      }
+      else if (sub.nodeName === 'taskList') {
+        nestedParts.push(serializeTaskList(sub, indent + '  '))
+      }
+      else {
+        // Other block — render under the item with a 2-space hanging indent
+        nestedParts.push((indent + '  ') + serializeBlock(sub, indent + '  '))
+      }
+    }
+    lines.push(`${indent}- ${marker} ${header}`)
+    for (const part of nestedParts) lines.push(part)
+  }
+  return lines.join('\n')
+}
+
+function getCodeBlockText(el: Y.XmlElement): string {
+  for (const child of el.toArray()) {
+    if (child instanceof Y.XmlText) {
+      return child.toString()
+    }
+  }
+  return ''
+}
+
+function serializeTable(el: Y.XmlElement): string {
+  const rows = el.toArray().filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+  if (!rows.length) return ''
+
+  const serializedRows: string[][] = []
+  for (const row of rows) {
+    const cells = row.toArray()
+      .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+      .map((cell) => {
+        // Cell contains paragraphs — join their text
+        return cell.toArray()
+          .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+          .map(c => serializeInline(c))
+          .join(' ')
+      })
+    serializedRows.push(cells)
+  }
+
+  if (!serializedRows.length) return ''
+
+  const colCount = Math.max(...serializedRows.map(r => r.length))
+  const headerRow = serializedRows[0]!
+  const separator = Array(colCount).fill('---')
+  const dataRows = serializedRows.slice(1)
+
+  const formatRow = (cells: string[]) => {
+    const padded = Array(colCount).fill('').map((_, i) => cells[i] ?? '')
+    return `| ${padded.join(' | ')} |`
+  }
+
+  const lines = [formatRow(headerRow), formatRow(separator), ...dataRows.map(formatRow)]
+  return lines.join('\n')
+}
+
+function serializeSlottedContainer(
+  el: Y.XmlElement,
+  containerName: string,
+  childName: string,
+  slotPrefix: string
+): string {
+  const items = el.toArray().filter((c): c is Y.XmlElement => c instanceof Y.XmlElement && c.nodeName === childName)
+  const slots = items.map((item) => {
+    const label = item.getAttribute('label') ?? ''
+    const icon = item.getAttribute('icon') ?? ''
+    const props: string[] = []
+    if (label) props.push(`label="${label}"`)
+    if (icon) props.push(`icon="${icon}"`)
+    const content = serializeChildren(item)
+    return `#${slotPrefix}{${props.join(' ')}}\n${content}`
+  })
+  return `::${containerName}\n${slots.join('\n\n')}\n::`
+}
+
+// ── Frontmatter generation ──────────────────────────────────────────────────
+
+function generateFrontmatter(label: string | undefined, meta?: DocPageMeta, type?: string): string {
+  const lines: string[] = []
+
+  if (label !== undefined) lines.push(`title: "${escapeYaml(label)}"`)
+
+  if (type && type !== 'doc') {
+    lines.push(`type: ${type}`)
+  }
+
+  if (!meta) return `---\n${lines.join('\n')}\n---`
+
+  if (meta.tags?.length) {
+    lines.push(`tags: [${meta.tags.join(', ')}]`)
+  }
+  if (meta.color) lines.push(`color: ${yamlScalar(meta.color)}`)
+  if (meta.icon) lines.push(`icon: ${yamlScalar(meta.icon)}`)
+  if (meta.status) lines.push(`status: ${yamlScalar(meta.status)}`)
+
+  if (meta.priority !== undefined && meta.priority !== 0) {
+    const map: Record<number, string> = { 1: 'low', 2: 'medium', 3: 'high', 4: 'urgent' }
+    lines.push(`priority: ${map[meta.priority] ?? meta.priority}`)
+  }
+
+  if (meta.checked !== undefined) lines.push(`checked: ${meta.checked}`)
+  if (meta.dateStart) lines.push(`dateStart: "${escapeYaml(meta.dateStart)}"`)
+  if (meta.dateEnd) lines.push(`dateEnd: "${escapeYaml(meta.dateEnd)}"`)
+  if (meta.subtitle) lines.push(`subtitle: "${escapeYaml(meta.subtitle)}"`)
+  if (meta.url) lines.push(`url: ${meta.url}`)
+  if (meta.rating !== undefined && meta.rating !== 0) lines.push(`rating: ${meta.rating}`)
+
+  return `---\n${lines.join('\n')}\n---`
+}
+
+/**
+ * Render a YAML scalar — bare when safe, double-quoted when the value
+ * needs escaping. YAML treats `#`, `:`, leading whitespace, and a few
+ * other characters as syntactically significant, so anything starting
+ * with one of those gets quoted to stay round-trip safe.
+ */
+function yamlScalar(s: string): string {
+  if (s === '') return '""'
+  if (/^[#&*!|>%@`]/.test(s)) return `"${escapeYaml(s)}"`
+  if (/[:"]/.test(s)) return `"${escapeYaml(s)}"`
+  if (/^\s|\s$/.test(s)) return `"${escapeYaml(s)}"`
+  return s
+}
+
+function escapeYaml(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+// ── HTML serialization ──────────────────────────────────────────────────────
+
+function serializeBlockToHtml(el: Y.XmlElement | Y.XmlText): string {
+  if (el instanceof Y.XmlText) {
+    return serializeDeltaToHtml(el.toDelta())
+  }
+
+  const name = el.nodeName
+  switch (name) {
+    case 'documentHeader':
+    case 'documentMeta':
+      return ''
+
+    case 'heading': {
+      const level = Number(el.getAttribute('level') ?? 2)
+      return `<h${level}>${serializeInlineHtml(el)}</h${level}>`
+    }
+
+    case 'paragraph':
+      return `<p>${serializeInlineHtml(el)}</p>`
+
+    case 'bulletList':
+      return `<ul>${serializeListHtml(el)}</ul>`
+
+    case 'orderedList':
+      return `<ol>${serializeListHtml(el)}</ol>`
+
+    case 'taskList':
+      return `<ul>${serializeTaskListHtml(el)}</ul>`
+
+    case 'codeBlock': {
+      const lang = el.getAttribute('language') ?? ''
+      const code = escapeHtml(getCodeBlockText(el))
+      return lang
+        ? `<pre><code class="language-${lang}">${code}</code></pre>`
+        : `<pre><code>${code}</code></pre>`
+    }
+
+    case 'blockquote': {
+      const inner = el.toArray()
+        .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+        .map(c => serializeBlockToHtml(c))
+        .join('\n')
+      return `<blockquote>\n${inner}\n</blockquote>`
+    }
+
+    case 'table':
+      return serializeTableHtml(el)
+
+    case 'horizontalRule':
+      return '<hr>'
+
+    case 'image': {
+      const src = el.getAttribute('src') ?? ''
+      const alt = el.getAttribute('alt') ?? ''
+      return `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}">`
+    }
+
+    case 'fileBlock': {
+      const uploadId = el.getAttribute('uploadId') ?? ''
+      const filename = el.getAttribute('filename') ?? 'file'
+      if (uploadId) return `<!--fileblock:${uploadId}:${filename}-->`
+      return `<!-- file: ${filename} -->`
+    }
+
+    default: {
+      // Generic wrapper for MDC blocks etc.
+      const inner = el.toArray()
+        .filter((c): c is Y.XmlElement | Y.XmlText => c instanceof Y.XmlElement || c instanceof Y.XmlText)
+        .map(c => c instanceof Y.XmlElement ? serializeBlockToHtml(c) : serializeDeltaToHtml(c.toDelta()))
+        .join('\n')
+      return `<div data-type="${name}">\n${inner}\n</div>`
+    }
+  }
+}
+
+function serializeInlineHtml(el: Y.XmlElement | Y.XmlFragment): string {
+  const parts: string[] = []
+  for (const child of el.toArray()) {
+    if (child instanceof Y.XmlText) {
+      parts.push(serializeDeltaToHtml(child.toDelta()))
+    } else if (child instanceof Y.XmlElement) {
+      parts.push(serializeInlineHtml(child))
+    }
+  }
+  return parts.join('')
+}
+
+function serializeDeltaToHtml(delta: any[]): string {
+  let result = ''
+  for (const op of delta) {
+    if (typeof op.insert !== 'string') continue
+    let text = escapeHtml(op.insert as string)
+    const attrs = op.attributes ?? {}
+    if (attrs.code) text = `<code>${text}</code>`
+    if (attrs.bold) text = `<strong>${text}</strong>`
+    if (attrs.italic) text = `<em>${text}</em>`
+    if (attrs.strike) text = `<s>${text}</s>`
+    if (attrs.link) {
+      const href = escapeHtml((attrs.link as { href?: string }).href ?? '')
+      text = `<a href="${href}">${text}</a>`
+    }
+    result += text
+  }
+  return result
+}
+
+function serializeListHtml(el: Y.XmlElement): string {
+  return el.toArray()
+    .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement && c.nodeName === 'listItem')
+    .map(li => `<li>${li.toArray().filter((c): c is Y.XmlElement => c instanceof Y.XmlElement).map(c => serializeBlockToHtml(c)).join('')}</li>`)
+    .join('\n')
+}
+
+function serializeTaskListHtml(el: Y.XmlElement): string {
+  return el.toArray()
+    .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement && c.nodeName === 'taskItem')
+    .map((ti) => {
+      const rawChecked: unknown = ti.getAttribute('checked')
+      const checked = rawChecked === true || rawChecked === 'true'
+      const text = ti.toArray().filter((c): c is Y.XmlElement => c instanceof Y.XmlElement).map(c => serializeInlineHtml(c)).join('')
+      return `<li><input type="checkbox"${checked ? ' checked' : ''} disabled> ${text}</li>`
+    })
+    .join('\n')
+}
+
+function serializeTableHtml(el: Y.XmlElement): string {
+  const rows = el.toArray().filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+  if (!rows.length) return ''
+
+  const htmlRows = rows.map((row, ri) => {
+    const tag = ri === 0 ? 'th' : 'td'
+    const cells = row.toArray()
+      .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+      .map((cell) => {
+        const inner = cell.toArray()
+          .filter((c): c is Y.XmlElement => c instanceof Y.XmlElement)
+          .map(c => serializeInlineHtml(c))
+          .join('')
+        return `<${tag}>${inner}</${tag}>`
+      })
+      .join('')
+    return `<tr>${cells}</tr>`
+  })
+
+  return `<table>\n${htmlRows.join('\n')}\n</table>`
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export function yjsToMarkdown(
+  fragment: Y.XmlFragment,
+  label: string,
+  meta?: DocPageMeta,
+  type?: string
+): string {
+  // The title can come from three places. We honour where the parser
+  // captured it so the wire form round-trips byte-stably:
+  //   - 'h1'           → emit `# title` as the first body block
+  //   - 'frontmatter'  → emit `title:` in frontmatter
+  //   - undefined      → no real title; skip the frontmatter block
+  //                      when no other meta is set
+  const { text: headerText, source: titleSource } = readDocumentHeader(fragment)
+  const effectiveTitle = headerText || label
+
+  // If the caller didn't pass meta / type, read them from documentMeta —
+  // that's where the parser stashes frontmatter fields so they survive
+  // round-trip without needing to be piped through the consumer.
+  const docMeta = readDocumentMeta(fragment)
+  const effectiveMeta = meta ?? docMeta.meta
+  const effectiveType = type ?? docMeta.type
+
+  const metaIsEmpty = isMetaEmpty(effectiveMeta)
+  const typeIsDefault = !effectiveType || effectiveType === 'doc'
+
+  const bodyBlocks = collectBodyBlocks(fragment)
+
+  // Body assembly — when the parser captured the title from a body H1
+  // we restore it at the top of the body before serialising.
+  let body: string
+  if (titleSource === 'h1' && effectiveTitle) {
+    const tail = serializeBlocksClean(bodyBlocks)
+    body = tail === '' ? `# ${effectiveTitle}` : `# ${effectiveTitle}\n\n${tail}`
+  }
+  else {
+    body = serializeBlocksClean(bodyBlocks)
+  }
+
+  const wantFrontmatterTitle = titleSource === 'frontmatter'
+  const wantFrontmatterMeta = !metaIsEmpty || !typeIsDefault
+  if (!wantFrontmatterTitle && !wantFrontmatterMeta) {
+    return body === '' ? '' : `${body}\n`
+  }
+  const fmTitle = wantFrontmatterTitle ? effectiveTitle : undefined
+  const frontmatter = generateFrontmatter(fmTitle, effectiveMeta, effectiveType)
+  if (body === '') return `${frontmatter}\n`
+  return `${frontmatter}\n\n${body}\n`
+}
+
+function readDocumentMeta(fragment: Y.XmlFragment): { meta: DocPageMeta, type?: string } {
+  const meta: DocPageMeta = {}
+  let type: string | undefined
+  for (const child of fragment.toArray()) {
+    if (!(child instanceof Y.XmlElement) || child.nodeName !== 'documentMeta') continue
+    const attrs = child.getAttributes() as Record<string, unknown>
+    for (const k of Object.keys(attrs)) {
+      const v = attrs[k]
+      if (v === undefined || v === null) continue
+      if (k === 'type' && typeof v === 'string') {
+        type = v
+        continue
+      }
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (meta as Record<string, unknown>)[k] = v
+    }
+    break
+  }
+  return { meta, type }
+}
+
+interface HeaderInfo { text: string, source?: 'h1' | 'frontmatter' }
+
+function readDocumentHeader(fragment: Y.XmlFragment): HeaderInfo {
+  for (const child of fragment.toArray()) {
+    if (!(child instanceof Y.XmlElement) || child.nodeName !== 'documentHeader') continue
+    const text = child.toArray().find(c => c instanceof Y.XmlText) as Y.XmlText | undefined
+    const src: unknown = child.getAttribute('titleSource')
+    const source = src === 'h1' || src === 'frontmatter' ? src : undefined
+    return { text: text ? text.toString() : '', source }
+  }
+  return { text: '' }
+}
+
+function collectBodyBlocks(fragment: Y.XmlFragment): Y.XmlElement[] {
+  const out: Y.XmlElement[] = []
+  for (const child of fragment.toArray()) {
+    if (!(child instanceof Y.XmlElement)) continue
+    if (child.nodeName === 'documentHeader' || child.nodeName === 'documentMeta') continue
+    out.push(child)
+  }
+  return out
+}
+
+function serializeBlocksClean(blocks: Y.XmlElement[]): string {
+  const parts: string[] = []
+  for (const block of blocks) {
+    // Empty trailing paragraphs are the parser's placeholder for an
+    // "empty doc"; skip them so empty input round-trips to "".
+    if (block.nodeName === 'paragraph' && block.length === 0) {
+      parts.push('')
+      continue
+    }
+    parts.push(serializeBlock(block))
+  }
+  while (parts.length && parts[parts.length - 1] === '') parts.pop()
+  return parts.join('\n\n')
+}
+
+function isMetaEmpty(meta: DocPageMeta | undefined): boolean {
+  if (!meta) return true
+  for (const key of Object.keys(meta)) {
+    const v = (meta as Record<string, unknown>)[key]
+    if (v === undefined || v === null) continue
+    if (typeof v === 'string' && v === '') continue
+    if (Array.isArray(v) && v.length === 0) continue
+    return false
+  }
+  return true
+}
+
+/**
+ * Walk the Y.XmlFragment and concatenate all text content with no
+ * markup or frontmatter. Block boundaries become newlines. Useful for
+ * accessibility tooling, search indexing, and snippet previews.
+ */
+export function yjsToPlainText(fragment: Y.XmlFragment): string {
+  const out: string[] = []
+  const visit = (node: Y.XmlElement | Y.XmlText): void => {
+    if (node instanceof Y.XmlText) {
+      out.push(node.toString())
+      return
+    }
+    if (node.nodeName === 'documentMeta') return
+    if (node.nodeName === 'image') {
+      const alt = node.getAttribute('alt') ?? ''
+      if (alt) out.push(alt)
+      return
+    }
+    for (const child of node.toArray()) {
+      if (child instanceof Y.XmlText || child instanceof Y.XmlElement) visit(child)
+    }
+    // Insert a single newline after block-level elements so paragraphs
+    // and headings produce a readable plain-text form.
+    if (node.nodeName !== 'paragraph' && node.length === 0) return
+    out.push('\n')
+  }
+  for (const child of fragment.toArray()) {
+    if (child instanceof Y.XmlText || child instanceof Y.XmlElement) visit(child)
+  }
+  return out.join('').replace(/\n+$/, '').replace(/\n{3,}/g, '\n\n')
+}
+
+export function yjsToHtml(
+  fragment: Y.XmlFragment,
+  label: string
+): string {
+  const title = escapeHtml(label)
+  const bodyParts: string[] = []
+  for (const child of fragment.toArray()) {
+    if (child instanceof Y.XmlElement) {
+      const html = serializeBlockToHtml(child)
+      if (html) bodyParts.push(html)
+    }
+  }
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>${title}</title></head>
+<body>
+<h1>${title}</h1>
+${bodyParts.join('\n')}
+</body>
+</html>
+`
+}