@uniweb/content-writer 0.2.6 → 0.2.8

package/src/nodes.js

@@ -4,6 +4,7 @@
  * Each function takes a ProseMirror node and returns a markdown string.
  */
 
+import yaml from 'js-yaml'
 import { serializeInlineContent, serializeBlockImage, serializeInsetRef } from './marks.js'
 
 // inset_ref serialization is shared with the inline path; it lives in
@@ -49,7 +50,25 @@ export function serializeCodeBlock(node) {
   const lang = node.attrs?.language || ''
   const tag = node.attrs?.tag ? `:${node.attrs.tag}` : ''
   const text = node.content?.[0]?.text || ''
-  return `\`\`\`${lang}${tag}\n${text}\n\`\`\``
+  const fence = '`'.repeat(fenceWidthFor(text))
+  return `${fence}${lang}${tag}\n${text}\n${fence}`
+}
+
+/**
+ * How many backticks this content needs as a fence.
+ *
+ * A fence must be longer than the longest backtick run inside it, or the
+ * block ends early — which is why documentation that shows fenced markdown
+ * is itself fenced in four backticks. Emitting three unconditionally
+ * truncated those blocks and spilled their remainder into the page as prose.
+ *
+ * @param {string} text - The code block's content
+ * @returns {number} Fence length, never fewer than three
+ */
+function fenceWidthFor(text) {
+  const runs = String(text).match(/`+/g) || []
+  const longest = runs.reduce((max, run) => Math.max(max, run.length), 0)
+  return Math.max(3, longest + 1)
 }
 
 /**
@@ -78,13 +97,38 @@ export function serializeMathDisplay(node) {
 
 /**
  * Serialize a data block node.
- * @param {Object} node - Data block node with attrs.tag and attrs.data
+ *
+ * Emits the serialization the author wrote, which `attrs.language` records.
+ * This used to hardcode JSON, so a ```yaml:nav block came back as ```json:nav
+ * — same data, rewritten source, on every editor sync.
+ *
+ * **YAML is the fallback when `language` is absent**, not JSON. A node without
+ * it predates the reader recording it, and YAML is both the form the docs
+ * teach and the friendlier one to leave in someone's file; JSON is still
+ * emitted whenever it is what the author actually chose.
+ *
+ * @param {Object} node - Data block node with attrs.tag, attrs.data, attrs.language
  * @returns {string} Tagged fenced code block with serialized data
  */
 export function serializeDataBlock(node) {
-  const { tag, data } = node.attrs || {}
-  const serialized = JSON.stringify(data, null, 2)
-  return `\`\`\`json:${tag}\n${serialized}\n\`\`\``
+  const { tag, data, language } = node.attrs || {}
+
+  if ((language || '').toLowerCase() === 'json') {
+    return `\`\`\`json:${tag}\n${JSON.stringify(data, null, 2)}\n\`\`\``
+  }
+
+  // `yaml` and `yml` are both valid fences; echo back whichever was written.
+  const fence = language || 'yaml'
+  const serialized = yaml
+    .dump(data, {
+      lineWidth: -1, // Don't wrap long lines
+      quotingType: "'", // Use single quotes when quoting is needed
+      forceQuotes: false, // Only quote when necessary
+      noRefs: true, // Don't use YAML references
+    })
+    .trimEnd()
+
+  return `\`\`\`${fence}:${tag}\n${serialized}\n\`\`\``
 }
 
 /**
@@ -118,8 +162,8 @@ export function serializeBulletList(node, indent = 0) {
   if (!node.content) return ''
   const prefix = '  '.repeat(indent)
   return node.content
-    .map(item => serializeListItem(item, `${prefix}- `, indent))
-    .join('\n')
+    .map(item => serializeListItem(item, `${prefix}- `, indent, isLoose(node)))
+    .join(itemSeparator(node))
 }
 
 /**
@@ -133,8 +177,32 @@ export function serializeOrderedList(node, indent = 0) {
   const start = node.attrs?.start || 1
   const prefix = '  '.repeat(indent)
   return node.content
-    .map((item, i) => serializeListItem(item, `${prefix}${start + i}. `, indent))
-    .join('\n')
+    .map((item, i) => serializeListItem(item, `${prefix}${start + i}. `, indent, isLoose(node)))
+    .join(itemSeparator(node))
+}
+
+/**
+ * What goes between two list items.
+ *
+ * A loose list — one the author spaced out with blank lines — keeps that
+ * spacing. `attrs.loose` is recorded by content-reader; a list without it is
+ * tight, which is both the common case and the safe default for documents
+ * written before the flag existed.
+ *
+ * @param {Object} node - A bulletList or orderedList node
+ * @returns {string}
+ */
+function itemSeparator(node) {
+  return isLoose(node) ? '\n\n' : '\n'
+}
+
+/**
+ * Did the author space this list out?
+ * @param {Object} node - A bulletList or orderedList node
+ * @returns {boolean}
+ */
+function isLoose(node) {
+  return Boolean(node.attrs?.loose)
 }
 
 /**
@@ -142,31 +210,62 @@ export function serializeOrderedList(node, indent = 0) {
  * @param {Object} node - List item node with content
  * @param {string} bullet - The bullet prefix (e.g., "- " or "1. ")
  * @param {number} indent - Current indentation level
+ * @param {boolean} [loose=false] - Whether the parent list is loose
  * @returns {string} Markdown list item
  */
-function serializeListItem(node, bullet, indent) {
+function serializeListItem(node, bullet, indent, loose = false) {
   if (!node.content) return bullet
 
   const parts = []
+  const pad = ' '.repeat(bullet.length)
 
   for (let i = 0; i < node.content.length; i++) {
     const child = node.content[i]
 
-    if (i === 0 && child.type === 'paragraph') {
-      // First child paragraph is the item text
-      parts.push(bullet + serializeInlineContent(child.content))
-    } else if (child.type === 'bulletList') {
+    // Nested lists carry their own indentation.
+    if (child.type === 'bulletList') {
       parts.push(serializeBulletList(child, indent + 1))
-    } else if (child.type === 'orderedList') {
+      continue
+    }
+    if (child.type === 'orderedList') {
       parts.push(serializeOrderedList(child, indent + 1))
-    } else if (child.type === 'paragraph') {
-      // Additional paragraphs in the same list item
-      const pad = ' '.repeat(bullet.length)
-      parts.push(pad + serializeInlineContent(child.content))
+      continue
     }
+
+    // Anything else is an ordinary block. A paragraph is inline content; a
+    // code block, blockquote or table goes through the node serializer, the
+    // same way a blockquote's children do. Every one of those used to fall
+    // off the end of this loop and be dropped without a trace.
+    const text =
+      child.type === 'paragraph'
+        ? serializeInlineContent(child.content)
+        : await_serializer().serializeNode(child) || ''
+
+    parts.push(indentBlock(text, i === 0 ? bullet : pad, pad))
   }
 
-  return parts.join('\n')
+  // In a loose list the item's own blocks are blank-line separated too — the
+  // spacing is a property of the whole list, not just the gaps between items.
+  return parts.join(loose ? '\n\n' : '\n')
+}
+
+/**
+ * Place a block's lines inside a list item.
+ *
+ * The first line carries the bullet (or aligns under it, for a block that is
+ * not the item's opening one); every later line aligns under the bullet so it
+ * stays part of the item instead of ending the list.
+ *
+ * @param {string} text - Serialized block, possibly multi-line
+ * @param {string} firstPrefix - Prefix for the first line
+ * @param {string} pad - Prefix for continuation lines
+ * @returns {string}
+ */
+function indentBlock(text, firstPrefix, pad) {
+  const [first = '', ...rest] = String(text).split('\n')
+  const head = firstPrefix + first
+  if (rest.length === 0) return head
+  return [head, ...rest.map(line => (line ? pad + line : ''))].join('\n')
 }
 
 /**
@@ -187,13 +286,17 @@ export function serializeTable(node) {
 
   const rows = node.content
   const headerRow = rows[0]
+  // A row with no cells is legal ProseMirror — `tableRow` is
+  // `(tableCell | tableHeader)*`, a star — and PM's toJSON omits `content`
+  // entirely for an empty node. Reading it unguarded threw.
+  const cellsOf = row => row?.content ?? []
   const bodyRows = rows.slice(1)
 
   // Serialize header cells
-  const headerCells = headerRow.content.map(cell => serializeTableCell(cell))
+  const headerCells = cellsOf(headerRow).map(cell => serializeTableCell(cell))
 
   // Build alignment row from header cell attrs
-  const alignments = headerRow.content.map(cell => {
+  const alignments = cellsOf(headerRow).map(cell => {
     const align = cell.attrs?.align
     if (align === 'left') return ':---'
     if (align === 'center') return ':---:'
@@ -203,7 +306,7 @@ export function serializeTable(node) {
 
   // Serialize body rows
   const bodyLines = bodyRows.map(row =>
-    '| ' + row.content.map(cell => serializeTableCell(cell)).join(' | ') + ' |'
+    '| ' + cellsOf(row).map(cell => serializeTableCell(cell)).join(' | ') + ' |'
   )
 
   const headerLine = '| ' + headerCells.join(' | ') + ' |'
@@ -220,7 +323,7 @@ export function serializeTable(node) {
 function serializeTableCell(cell) {
   if (!cell.content) return ''
   // Table cells contain paragraphs; serialize their inline content
-  return cell.content
+  const text = cell.content
     .map(child => {
       if (child.type === 'paragraph') {
         return serializeInlineContent(child.content)
@@ -228,6 +331,27 @@ function serializeTableCell(cell) {
       return ''
     })
     .join(' ')
+
+  return escapeTableCell(text)
+}
+
+/**
+ * Escape the one character a table cell cannot contain literally.
+ *
+ * A pipe inside a cell ends it, so markdown spells a literal one `\|` and the
+ * parser hands back the unescaped character. Writing that back out unescaped
+ * splits the cell and shifts every column after it — the table silently gains
+ * a column and stops lining up with its header.
+ *
+ * Only the pipe needs this: the cell's other content has already been through
+ * the inline serializers, and a row is a single line by construction.
+ *
+ * @param {string} text - Serialized inline content of one cell
+ * @returns {string}
+ */
+function escapeTableCell(text) {
+  // Leave an already-escaped pipe alone rather than doubling its backslash.
+  return text.replace(/\\?\|/g, '\\|')
 }
 
 // Lazy reference to serializeNode to handle circular dependency with blockquote

package/src/normalize.js

@@ -155,9 +155,20 @@ function mapVideo(node) {
  */
 function mapUniwebIcon(node) {
   const attrs = node.attrs || {}
-  if (!attrs.library || !attrs.name) return null
 
-  const out = { role: 'icon', library: attrs.library, name: attrs.name }
+  // The insert path stores a single colon-joined `family:id` name (built from
+  // the icon CDN URL) and leaves `library` unset — so requiring both dropped
+  // every icon the editor actually produces. The separate-attr form is kept
+  // for content that already carries it.
+  let { library, name } = attrs
+  if (!library && typeof name === 'string' && name.includes(':')) {
+    const [family, ...rest] = name.split(':')
+    library = family
+    name = rest.join(':')
+  }
+  if (!library || !name) return null
+
+  const out = { role: 'icon', library, name }
   if (attrs.size) out.size = attrs.size
   if (attrs.color) out.color = attrs.color
   return { type: 'image', attrs: out }
@@ -179,7 +190,27 @@ function mapEditorNode(node) {
     case 'Video':
       return mapVideo(node)
     case 'UniwebIcon':
+    case 'Icon':
       return mapUniwebIcon(node)
+    case 'emoji':
+      // The node carries the character alongside a name; the character is the
+      // whole markdown form. Guarded rather than assumed to be populated.
+      return node.attrs?.emoji ? { type: 'text', text: node.attrs.emoji } : null
+    // A standalone "\n" text node is NOT mapped here, deliberately.
+    //
+    // It used to be: content-reader once spelled a hard break that way, and
+    // this healed old documents onto the node form. The migration is done —
+    // content-reader has emitted a `hardBreak` node for both markdown
+    // spellings for some time, and no persisted document carries the legacy
+    // form (confirmed 2026-07-26).
+    //
+    // Keeping the rule past that point made it wrong. content-reader still
+    // produces a lone "\n" node, but for a SOFT break — a newline lands in
+    // its own node whenever the spans on both sides are marked, as in
+    // "`--heading` → `text-heading`" followed by another such line. Healing
+    // that turned an ordinary wrapped line into a visible break: the sync
+    // wrote a trailing "\", and the next read made it a real <br>, so the
+    // page reflowed one round trip after the edit.
     default:
       return null
   }
@@ -191,10 +222,63 @@ function mapEditorNode(node) {
  * its children. Nodes without a mapping pass through unchanged so any
  * editor-dialect descendants are still caught.
  */
+/**
+ * The editor's named inline styles, and the framework spelling of each.
+ *
+ * These are theme tokens, not colours. The editor's picker offers exactly this
+ * closed set — the attribute is *named* `color` but holds a token, which its
+ * extension renders as `var(--<token>)`. So they map onto the `span` mark the
+ * framework already round-trips as `[text]{token}`, and nothing is lost.
+ *
+ * A value outside this set (a hex from a paste, until the editor gates its
+ * `parseHTML`) is deliberately NOT mapped: it falls through to the
+ * no-silent-drop guard rather than writing a raw colour into markdown, where
+ * it would contradict the theming model and not survive a change of brand.
+ */
+const NAMED_INLINE_STYLES = new Set(['accent', 'highlight', 'callout', 'muted'])
+
+/** A mark that carries nothing and should be removed rather than reported. */
+const DROP_MARK = Symbol('drop-mark')
+
+/**
+ * Map an editor-dialect mark to the framework dialect.
+ *
+ * @param {Object} mark
+ * @returns {Object|Symbol|null} a framework mark, `DROP_MARK` when the mark
+ *   carries no styling at all, or null when there is no mapping (the original
+ *   is kept and reported by the no-silent-drop guard)
+ */
+function mapEditorMark(mark) {
+  if (mark?.type === 'highlight') {
+    // Effectively boolean in the editor: its extension hardcodes the
+    // background and ignores the attribute.
+    return { type: 'span', attrs: { highlight: true } }
+  }
+
+  if (mark?.type === 'textStyle') {
+    const token = mark.attrs?.color
+    // The picker's "Normal" option. Nothing is being dropped, so reporting it
+    // would be noise in a guard whose value depends on staying quiet.
+    if (!token) return DROP_MARK
+    if (!NAMED_INLINE_STYLES.has(token)) return null // a colour, not a token
+    return { type: 'span', attrs: { [token]: true } }
+  }
+
+  return null
+}
+
 function normalizeNode(node) {
   if (!node || typeof node !== 'object') return node
 
-  const result = mapEditorNode(node) || node
+  let result = mapEditorNode(node) || node
+
+  if (Array.isArray(result.marks) && result.marks.length) {
+    // An unmapped mark is kept, so the no-silent-drop guard still reports it.
+    result = {
+      ...result,
+      marks: result.marks.map(m => mapEditorMark(m) || m).filter(m => m !== DROP_MARK),
+    }
+  }
 
   if (Array.isArray(result.content)) {
     return { ...result, content: result.content.map(normalizeNode) }

package/src/plain-text.js

@@ -4,8 +4,15 @@
  * Strips all markdown formatting, returning just the text content
  * with newlines for structure. Useful for word counting, search
  * indexing, and generating summaries.
+ *
+ * "Plain" is meant literally: PM text nodes carry HTML (see `entities.js`),
+ * so every text run is stripped of raw inline tags and its entities resolved
+ * to the characters a reader would see. Without that, a summary can ship
+ * `&lt;` or a stray `<span>` into whatever consumes it.
  */
 
+import { toPlainCharacters } from './entities.js'
+
 /**
  * Extract plain text from a ProseMirror document.
  *
@@ -21,6 +28,64 @@ export function docToPlainText(doc) {
     .join('\n\n')
 }
 
+/**
+ * Summarize a ProseMirror document in one sentence-ish line.
+ *
+ * Reads the document's **first paragraph**, not the whole document: pages
+ * routinely open with an `# H1`, and `docToPlainText` would hand back that
+ * title as the summary. A page with no paragraph at the top level returns
+ * `''` — callers are expected to have an authored fallback.
+ *
+ * The result is plain characters (tags stripped, entities resolved), so
+ * truncating on a sentence boundary lands on a real sentence boundary
+ * rather than somewhere inside a tag or an entity.
+ *
+ * @param {Object} doc - ProseMirror document
+ * @param {Object} [options]
+ * @param {number} [options.maxChars=200] - Soft upper bound on the result
+ * @returns {string} A single-line summary, or '' when there is nothing to say
+ */
+export function docSummaryText(doc, { maxChars = 200 } = {}) {
+  if (!doc?.content) return ''
+
+  let text = ''
+  for (const node of doc.content) {
+    if (node.type !== 'paragraph') continue
+    text = inlineToPlainText(node.content).trim()
+    if (text) break
+  }
+  if (!text) return ''
+
+  // Collapse internal whitespace — a summary is one line.
+  text = text.replace(/\s+/g, ' ')
+
+  return truncateAtSentence(text, maxChars)
+}
+
+/**
+ * Trim to `maxChars`, preferring a sentence boundary, then a word boundary.
+ *
+ * @param {string} text - Already-collapsed plain text
+ * @param {number} maxChars
+ * @returns {string}
+ */
+function truncateAtSentence(text, maxChars) {
+  if (text.length <= maxChars) return text
+
+  const window = text.slice(0, maxChars)
+
+  // A sentence end is terminal punctuation followed by whitespace — so
+  // "5 minutes." ends a sentence but the dot in "site.yml" does not. Take the
+  // last one in the window, to keep as much of the paragraph as fits.
+  const ends = [...window.matchAll(/[.!?](?=\s|$)/g)]
+  const lastEnd = ends.length ? ends[ends.length - 1].index : -1
+  if (lastEnd > 0) return window.slice(0, lastEnd + 1)
+
+  const lastSpace = window.lastIndexOf(' ')
+  const cut = lastSpace > 0 ? window.slice(0, lastSpace) : window
+  return `${cut.replace(/[,;:—–-]$/, '').trimEnd()}…`
+}
+
 /**
  * Extract plain text from a single ProseMirror node.
  * @param {Object} node
@@ -67,10 +132,12 @@ function nodeToPlainText(node) {
  */
 function inlineToPlainText(content) {
   if (!content) return ''
-  return content
-    .filter(node => node.type === 'text')
-    .map(node => node.text || '')
-    .join('')
+  return toPlainCharacters(
+    content
+      .filter(node => node.type === 'text')
+      .map(node => node.text || '')
+      .join('')
+  )
 }
 
 /**

package/tests/entities.test.js

@@ -0,0 +1,175 @@
+/**
+ * Entity handling on the way out of ProseMirror.
+ *
+ * The invariant these tests pin down (verified against `content-reader`'s
+ * `parser/inline.js`): a PM text node holds HTML. The reader decodes `&`,
+ * `"` and `'` and leaves `<`/`>` escaped, because the render
+ * path injects the string as HTML. Serializing has to undo exactly that, and
+ * exactly there — decoding more, or decoding in prose, corrupts source.
+ */
+
+import { markdownToProseMirror } from '@uniweb/content-reader'
+import { proseMirrorToMarkdown, docSummaryText, docToPlainText } from '../src/index.js'
+import { encodeMarkupEntities, decodeMarkupEntities, decodeTextEntities } from '../src/entities.js'
+
+const md = s => proseMirrorToMarkdown(markdownToProseMirror(s)).trim()
+
+describe('decodeMarkupEntities', () => {
+  test('undoes the pair the reader leaves escaped', () => {
+    expect(decodeMarkupEntities('/data/&lt;name&gt;.json')).toBe('/data/<name>.json')
+  })
+
+  test('leaves entities the reader already decoded alone', () => {
+    // A PM node holding these means the author typed them.
+    expect(decodeMarkupEntities('a &amp; b')).toBe('a &amp; b')
+    expect(decodeMarkupEntities('say &quot;hi&quot;')).toBe('say &quot;hi&quot;')
+  })
+
+  test('is a no-op on text with no entities', () => {
+    expect(decodeMarkupEntities('plain text')).toBe('plain text')
+  })
+})
+
+describe('decodeTextEntities', () => {
+  test('resolves every entity to the character a reader sees', () => {
+    expect(decodeTextEntities('&lt;b&gt; &amp; &quot;q&quot; &#39;a&#39;')).toBe(`<b> & "q" 'a'`)
+  })
+
+  test('decodes &amp; last, so &amp;lt; yields &lt; and not <', () => {
+    expect(decodeTextEntities('&amp;lt;')).toBe('&lt;')
+  })
+})
+
+describe('D1 — code spans round-trip a literal < >', () => {
+  test('the reported defect', () => {
+    expect(md('Read `/data/<name>.json` for the cascade.')).toBe(
+      'Read `/data/<name>.json` for the cascade.'
+    )
+  })
+
+  test('inside a heading', () => {
+    expect(md('# The `<slug>` folder')).toBe('# The `<slug>` folder')
+  })
+
+  test('inside a table cell', () => {
+    expect(md('| Col |\n| --- |\n| `<x>` |')).toContain('`<x>`')
+  })
+
+  test('inside a link', () => {
+    expect(md('[the `<x>` doc](/a)')).toBe('[the `<x>` doc](/a)')
+  })
+})
+
+describe('D1 — what the fix must NOT touch', () => {
+  test('prose entities stay escaped (decoding them would render as a tag)', () => {
+    expect(md('Literal &lt;name&gt; in prose.')).toBe('Literal &lt;name&gt; in prose.')
+  })
+
+  test('raw inline HTML in prose is preserved verbatim', () => {
+    expect(md('A <name> tag in prose.')).toBe('A <name> tag in prose.')
+  })
+
+  test('an authored &amp; inside a code span survives', () => {
+    expect(md('Code `a &amp; b` here.')).toBe('Code `a &amp; b` here.')
+  })
+
+  test('code blocks are raw text and are left alone', () => {
+    const source = '```js\nconst x = a < b && c > d;\n```'
+    expect(md(source)).toBe(source)
+  })
+
+  test('quotes and apostrophes in code spans are untouched', () => {
+    expect(md(`Code \`say "hi" it's\` here.`)).toBe(`Code \`say "hi" it's\` here.`)
+  })
+})
+
+describe('docSummaryText', () => {
+  const summary = (source, opts) => docSummaryText(markdownToProseMirror(source), opts)
+
+  test('skips the H1 and reads the first paragraph', () => {
+    expect(summary('# Quickstart\n\nCreate your first Uniweb site in 5 minutes.')).toBe(
+      'Create your first Uniweb site in 5 minutes.'
+    )
+  })
+
+  test('returns plain text — no anchors, no mark tags', () => {
+    expect(summary('# T\n\nSee **the [docs](/docs)** for *more*.')).toBe(
+      'See the docs for more.'
+    )
+  })
+
+  test('resolves entities and drops raw inline HTML', () => {
+    expect(summary('# T\n\nUse `<name>` and &lt;slug&gt; and <br> here.')).toBe(
+      'Use <name> and <slug> and here.'
+    )
+  })
+
+  test('truncates at a sentence boundary', () => {
+    const text = 'One sentence here. Two sentence here. Three sentence here.'
+    expect(summary(`# T\n\n${text}`, { maxChars: 40 })).toBe('One sentence here. Two sentence here.')
+  })
+
+  test('falls back to a word boundary with an ellipsis', () => {
+    const text = 'Collections let you manage repeating content across many files'
+    expect(summary(`# T\n\n${text}`, { maxChars: 40 })).toBe(
+      'Collections let you manage repeating…'
+    )
+  })
+
+  test('a dot inside a filename does not end a sentence', () => {
+    expect(summary('# T\n\nEdit site.yml then run the build now please.', { maxChars: 20 }))
+      .toBe('Edit site.yml then…')
+  })
+
+  test('returns empty string when there is no paragraph', () => {
+    expect(summary('# Only a heading')).toBe('')
+    expect(docSummaryText(null)).toBe('')
+  })
+
+  test('collapses newlines into one line', () => {
+    expect(summary('# T\n\nA line\nand another.')).toBe('A line and another.')
+  })
+})
+
+describe('docToPlainText also yields plain characters', () => {
+  test('strips tags and resolves entities', () => {
+    // Note the doubled space where <br> was: this primitive does not
+    // normalize whitespace, and its consumers (word counts, search tokens)
+    // do not care. `docSummaryText` is the one that promises a single line.
+    expect(docToPlainText(markdownToProseMirror('Use &lt;x&gt; and <br> here.'))).toBe(
+      'Use <x> and  here.'
+    )
+  })
+})
+
+describe('encodeMarkupEntities — the producer-side half', () => {
+  test('is the exact inverse of decodeMarkupEntities', () => {
+    const raw = '/data/<name>.json'
+    expect(encodeMarkupEntities(raw)).toBe('/data/&lt;name&gt;.json')
+    expect(decodeMarkupEntities(encodeMarkupEntities(raw))).toBe(raw)
+  })
+
+  test('does not touch &, so an authored entity is not double-encoded', () => {
+    expect(encodeMarkupEntities('a & b')).toBe('a & b')
+    expect(encodeMarkupEntities('&amp;')).toBe('&amp;')
+  })
+
+  test('round-trips what an author types in a code span', () => {
+    for (const raw of ['<div>', 'a < b && c > d', 'a & b', 'plain']) {
+      expect(decodeMarkupEntities(encodeMarkupEntities(raw))).toBe(raw)
+    }
+  })
+
+  test('the one input it does NOT round-trip: literal entity text', () => {
+    // `<div>` and `&lt;div&gt;` both store as `&lt;div&gt;`, so the pair
+    // cannot tell them apart and resolves to the decoded form.
+    //
+    // Accepted deliberately, because the loss happened earlier and elsewhere:
+    // a code span is rendered by injecting its text as HTML, so an author who
+    // typed `&lt;div&gt;` already sees `<div>` on the page. Decoding makes the
+    // file agree with the page rather than destroying something a reader could
+    // otherwise see. Escaping `&` as well would make the pair lossless, at the
+    // cost of changing what every existing code span stores.
+    expect(decodeMarkupEntities(encodeMarkupEntities('&lt;div&gt;'))).toBe('<div>')
+  })
+})

package/tests/fixtures/roundtrip/canonical-math.md

@@ -0,0 +1,3 @@
+$$
+E = mc^2
+$$

package/tests/fixtures/roundtrip/code.md

@@ -0,0 +1,11 @@
+# Code
+
+Install it first:
+
+```bash
+pnpm add @uniweb/kit
+```
+
+```js
+const site = { name: 'docs' }
+```

package/tests/fixtures/roundtrip/defect-bold-code.md

@@ -0,0 +1,3 @@
+- **Preview with `pnpm dev`.**
+
+Use **`npm install`** first.

package/tests/fixtures/roundtrip/defect-bold-link.md

@@ -0,0 +1 @@
+- **[Predicates](./predicates.md)** — filtering with `where:` clauses

package/tests/fixtures/roundtrip/defect-data-block.md

@@ -0,0 +1,6 @@
+# Navigation
+
+```yaml:nav
+- label: Docs
+  href: /docs
+```