@uniweb/content-writer 0.3.4 → 1.1.0

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@uniweb/content-writer",
-  "version": "0.3.4",
+  "version": "1.1.0",
   "description": "ProseMirror document structure to Markdown converter",
   "type": "module",
   "main": "src/index.js",
   "exports": {
-    ".": "./src/index.js",
-    "./entities": "./src/entities.js"
+    ".": "./src/index.js"
   },
   "keywords": [
     "markdown",
@@ -20,7 +19,7 @@
   },
   "devDependencies": {
     "vitest": "^4.1.7",
-    "@uniweb/content-reader": "1.2.4"
+    "@uniweb/content-reader": "1.3.0"
   },
   "directories": {
     "test": "tests"

package/src/diagnostics.js

@@ -44,12 +44,40 @@ export function resetDiagnostics() {
   warnedMarks.clear()
 }
 
+/** Set while `collectOmittedNodes` runs: the node types the write leaves out. */
+let omitted = null
+
+/**
+ * Run a write and return the node types it left out, instead of reporting them.
+ * For a caller that must refuse rather than lose content — a pull, whose next
+ * push would delete whatever the file does not hold.
+ *
+ * @template T
+ * @param {() => T} run
+ * @returns {{ result: T, omitted: string[] }}
+ */
+export function collectOmittedNodes(run) {
+  const previous = omitted
+  omitted = new Set()
+  try {
+    const result = run()
+    return { result, omitted: [...omitted] }
+  } finally {
+    omitted = previous
+  }
+}
+
 /**
  * Report a ProseMirror node the serializer has no markdown form for.
  * @param {Object} node - The unmapped node ({ type, attrs, ... })
  */
 export function warnUnmappedNode(node) {
   const type = node?.type || 'unknown'
+  // A caller collecting what a write leaves out is told every time, not once per type.
+  if (omitted) {
+    omitted.add(type)
+    return
+  }
   if (warnedNodes.has(type)) return
   warnedNodes.add(type)
   report(

package/src/index.js

@@ -5,11 +5,10 @@
  * documents back to Markdown text.
  */
 
-export { serializeDoc as proseMirrorToMarkdown } from './serializer.js'
+export { serializeDoc as proseMirrorToMarkdown, unwritableNodes } from './serializer.js'
 export { serializeInlineContent } from './marks.js'
 export { serializeFrontmatter } from './frontmatter.js'
 export { docToPlainText, docSummaryText } from './plain-text.js'
-export { encodeMarkupEntities, decodeMarkupEntities, decodeTextEntities } from './entities.js'
 export { normalizeDialect } from './normalize.js'
 export { setDiagnosticsReporter, resetDiagnostics } from './diagnostics.js'
 

package/src/marks.js

@@ -5,7 +5,6 @@
  */
 
 import { serializeAttributes } from './attributes.js'
-import { decodeMarkupEntities } from './entities.js'
 import { warnUnmappedMark, warnUnmappedNode } from './diagnostics.js'
 
 /**
@@ -232,13 +231,58 @@ export function serializeBlockImage(node) {
  * @param {Array} content - Array of text/image nodes with optional marks
  * @returns {string} Markdown string
  */
-export function serializeInlineContent(content) {
+export function serializeInlineContent(content, { lineBreak = '\\\n' } = {}) {
   if (!content || content.length === 0) return ''
 
   // No silent drops: flag any mark we can't represent before serializing.
   reportUnknownMarks(content)
 
-  return serializeRuns(content)
+  return serializeRuns(mergeAdjacentText(content), { lineBreak, literal: false })
+}
+
+/**
+ * Join neighbouring text nodes that carry the same marks, as ProseMirror itself
+ * would. The reader splits a run wherever markdown had an escape — `\<name>`
+ * arrives as `<` and `name>` — and the escaping below has to see the run whole,
+ * or a `<` that ends one node would go out bare before the tag-like text of the
+ * next.
+ *
+ * @param {Array} content
+ * @returns {Array}
+ */
+function mergeAdjacentText(content) {
+  const out = []
+  for (const node of content) {
+    const last = out[out.length - 1]
+    if (
+      node?.type === 'text' &&
+      last?.type === 'text' &&
+      JSON.stringify(last.marks || []) === JSON.stringify(node.marks || [])
+    ) {
+      out[out.length - 1] = { ...last, text: (last.text || '') + (node.text || '') }
+    } else {
+      out.push(node)
+    }
+  }
+  return out
+}
+
+/**
+ * Escape text so the reader decodes it back to the same characters.
+ *
+ * A text node holds the characters a reader sees, and content-reader decodes
+ * what markdown escapes — so the two characters it would otherwise read as
+ * something else are escaped here: a `<` that would open a tag or an autolink,
+ * and an `&` that would spell a character reference. `a < b` and `R&D` stay as
+ * they are. ⛔ Until 2026-10-14 a text node held HTML and was written verbatim.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeMarkdownText(text) {
+  return String(text)
+    .replace(/&(?=#[0-9]+;|#[xX][0-9a-fA-F]+;|[A-Za-z][A-Za-z0-9]*;)/g, '\\&')
+    .replace(/<(?=[A-Za-z/!?])/g, '\\<')
 }
 
 /**
@@ -262,7 +306,7 @@ export function serializeInlineContent(content) {
  * @param {Array} nodes - Inline nodes
  * @returns {string} Markdown string
  */
-function serializeRuns(nodes) {
+function serializeRuns(nodes, context) {
   const out = []
   let i = 0
 
@@ -271,7 +315,7 @@ function serializeRuns(nodes) {
     const outer = node.type === 'text' ? outermostMark(node) : null
 
     if (!outer) {
-      out.push(serializePlainNode(node))
+      out.push(serializePlainNode(node, context))
       i++
       continue
     }
@@ -286,7 +330,9 @@ function serializeRuns(nodes) {
       j++
     }
 
-    out.push(applyMark(serializeRuns(group), outer))
+    // A code span is literal: what it wraps is written as the characters it is.
+    const inner = serializeRuns(group, outer.type === 'code' ? { ...context, literal: true } : context)
+    out.push(applyMark(inner, outer))
     i = j
   }
 
@@ -327,9 +373,7 @@ function withoutOutermostMark(node) {
 function applyMark(inner, mark) {
   switch (mark.type) {
     case 'code':
-      // Leaving HTML-land: a code span is the one place the reader leaves
-      // `&lt;`/`&gt;` escaped (see entities.js).
-      return serializeCodeSpan(decodeMarkupEntities(inner))
+      return serializeCodeSpan(inner)
     case 'bold':
       return `**${inner}**`
     case 'italic':
@@ -352,7 +396,7 @@ function applyMark(inner, mark) {
 /**
  * Serialize a plain node (no wrapping mark).
  */
-function serializePlainNode(node) {
+function serializePlainNode(node, { lineBreak = '\\\n', literal = false } = {}) {
   if (node.type === 'image') {
     return serializeInlineImage(node)
   }
@@ -367,7 +411,9 @@ function serializePlainNode(node) {
     // Backslash rather than the two-trailing-spaces spelling: it survives
     // editors, formatters and pre-commit hooks that strip trailing whitespace,
     // and it is visible in a diff. Both spellings read back as a hard break.
-    return '\\\n'
+    // A heading or a table cell is one line, so there it is `<br/>` — the one
+    // tag the reader keeps, as the same hard break.
+    return lineBreak
   }
   if (node.type !== 'text') {
     // No silent drops: an inline node we have no markdown form for is
@@ -376,7 +422,9 @@ function serializePlainNode(node) {
     warnUnmappedNode(node)
     return ''
   }
-  return serializeTextWithMarks(node.text, node.marks || [])
+  const marks = node.marks || []
+  const keep = literal || marks.some((mark) => mark.type === 'code')
+  return serializeTextWithMarks(keep ? node.text : escapeMarkdownText(node.text), marks)
 }
 
 /**

package/src/nodes.js

@@ -20,7 +20,8 @@ export { serializeInsetRef }
  */
 export function serializeHeading(node) {
   const prefix = '#'.repeat(node.attrs?.level || 1)
-  const text = serializeInlineContent(node.content)
+  // A heading is one line: a hard break inside it is written `<br/>`.
+  const text = serializeInlineContent(node.content, { lineBreak: '<br/>' })
   // A `#>` label line (pretitle). The hash count carries the authored
   // spelling only — `#>` and `##>` mean the same thing — so emitting the
   // stored level keeps the file byte-identical through a round-trip.
@@ -443,7 +444,8 @@ function serializeTableCell(cell) {
   const text = cell.content
     .map(child => {
       if (child.type === 'paragraph') {
-        return serializeInlineContent(child.content)
+        // A table row is one line: a hard break in a cell is written `<br/>`.
+        return serializeInlineContent(child.content, { lineBreak: '<br/>' })
       }
       return ''
     })

package/src/normalize.js

@@ -55,8 +55,12 @@
  *   regenerated fixture in `_contracts/editor-vocabulary-diff.test.js`
  *   stopped listing them. That fixture is the signal, and it is the only one
  *   there is — no message announces it.
- *   - colour/highlight/strike/underline marks — need the named-inline-
- *     style convention decision.
+ *   - a colour that is not a named style (`textStyle` with a raw value), and
+ *     `underline` — neither has a markdown form. `highlight` and the named
+ *     styles (`accent`, `highlight`, `callout`, `muted`) ARE mapped, onto the
+ *     `span` mark (`mapEditorMark`), and `strike` serializes as `~~text~~`.
+ *     ⛔ This line listed all of them as awaiting a decision until 2026-10-14,
+ *     long after the mapping shipped.
  *
  * Each unmapped construct reaches content-writer's serializer as-is and
  * is reported by the no-silent-drop guard (diagnostics.js) — never lost

package/src/plain-text.js

@@ -5,14 +5,12 @@
  * 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.
+ * A text node holds the characters a reader sees, so a run is already plain:
+ * it is joined as it is. ⛔ Until 2026-10-14 text nodes carried HTML, and each
+ * run had its inline tags stripped and its entities resolved here — which, on
+ * text that is text, would delete a `<div>` an author wrote about.
  */
 
-import { toPlainCharacters } from './entities.js'
-
 /**
  * Extract plain text from a ProseMirror document.
  *
@@ -36,9 +34,8 @@ export function docToPlainText(doc) {
  * 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.
+ * The result is plain characters — what a text node holds — so truncating on
+ * a sentence boundary lands on a real sentence boundary.
  *
  * @param {Object} doc - ProseMirror document
  * @param {Object} [options]
@@ -132,12 +129,10 @@ function nodeToPlainText(node) {
  */
 function inlineToPlainText(content) {
   if (!content) return ''
-  return toPlainCharacters(
-    content
-      .filter(node => node.type === 'text')
-      .map(node => node.text || '')
-      .join('')
-  )
+  return content
+    .filter(node => node.type === 'text')
+    .map(node => node.text || '')
+    .join('')
 }
 
 /**

package/src/serializer.js

@@ -22,7 +22,7 @@ import {
   setSerializer,
 } from './nodes.js'
 import { normalizeDialect } from './normalize.js'
-import { warnUnmappedNode } from './diagnostics.js'
+import { warnUnmappedNode, collectOmittedNodes } from './diagnostics.js'
 
 const NODE_SERIALIZERS = {
   heading: serializeHeading,
@@ -62,6 +62,19 @@ export function serializeNode(node) {
 // Wire up the circular reference for blockquotes
 setSerializer(serializeNode)
 
+/**
+ * The node types a document holds that markdown cannot carry — what writing it
+ * to a file would leave out. A caller that writes files from stored content (a
+ * pull) asks first, so content is never dropped on its way to a file and then
+ * deleted by the push after it.
+ *
+ * @param {Object} doc - ProseMirror document
+ * @returns {string[]} the node types left out; empty when the whole doc fits
+ */
+export function unwritableNodes(doc) {
+  return collectOmittedNodes(() => serializeDoc(doc)).omitted
+}
+
 /**
  * Serialize a ProseMirror document to markdown.
  * @param {Object} doc - ProseMirror document ({ type: "doc", content: [...] })

package/tests/fixtures/roundtrip/prose.md

@@ -8,5 +8,5 @@ Each collection is declared in `site.yml`, and every item compiles into
 `/data/<name>.json`. See the [collections guide](/docs/authoring/collections)
 for the full story.
 
-Text can be **bold**, *italic*, or ***both***. A literal &lt;name&gt; stays
+Text can be **bold**, *italic*, or ***both***. A literal \<name> stays
 escaped in prose, and `a &amp; b` keeps its entity inside code.

package/tests/text-is-text.test.js

@@ -0,0 +1,79 @@
+import { markdownToProseMirror } from '@uniweb/content-reader'
+import { proseMirrorToMarkdown, docToPlainText } from '../src/index.js'
+import { serializeInlineContent } from '../src/marks.js'
+
+/**
+ * A text node holds the characters a reader sees, so the writer escapes what
+ * the reader would otherwise decode — and nothing else.
+ *
+ * Until 2026-10-14 a text node held HTML and was written verbatim, with a code
+ * span's `<` decoded on the way out. Now the reader decodes every value, and
+ * the property that matters is the one these pin: read(write(text)) is the
+ * same text, whatever characters it holds.
+ */
+
+const paragraph = (content) => ({ type: 'doc', content: [{ type: 'paragraph', content }] })
+const text = (t, marks) => ({ type: 'text', text: t, ...(marks ? { marks } : {}) })
+const readBack = (markdown) =>
+  markdownToProseMirror(markdown)
+    .content[0].content.map((n) => (n.type === 'text' ? n.text : `[${n.type}]`))
+    .join('')
+
+describe('text round-trips as the characters it is', () => {
+  test.each([
+    'if a<b then swap',
+    'x < y and y > z',
+    'a <img src=x onerror=alert(1)> b',
+    'the &copy; reference, typed',
+    'R&D and AT&T',
+    'a tag-like </div> and <!-- not a comment -->',
+    '<https://x.test> is not a link here',
+  ])('%s', (value) => {
+    const markdown = proseMirrorToMarkdown(paragraph([text(value)]))
+    expect(readBack(markdown)).toBe(value)
+  })
+
+  test('only what the reader would decode is escaped', () => {
+    expect(serializeInlineContent([text('a<b, x < y, R&D, &copy;')])).toBe('a\\<b, x < y, R&D, \\&copy;')
+  })
+
+  test('a code span is written as its characters', () => {
+    expect(serializeInlineContent([text('Use '), text('<div> & &lt;', [{ type: 'code' }])])).toBe(
+      'Use `<div> & &lt;`',
+    )
+    expect(readBack('Use `<div> & &lt;`')).toBe('Use <div> & &lt;')
+  })
+
+  test('a run the reader split at an escape is written whole', () => {
+    // `\<name>` reads back as two nodes, `<` and `name>`.
+    const doc = markdownToProseMirror('A literal \\<name> here.')
+    expect(proseMirrorToMarkdown(doc).trim()).toBe('A literal \\<name> here.')
+  })
+})
+
+describe('a hard break', () => {
+  const brk = { type: 'hardBreak' }
+
+  test('in a paragraph is a trailing backslash', () => {
+    expect(serializeInlineContent([text('a'), brk, text('b')])).toBe('a\\\nb')
+  })
+
+  test('in a heading, which is one line, is <br/> — and reads back as the same break', () => {
+    const doc = { type: 'doc', content: [{ type: 'heading', attrs: { level: 1 }, content: [text('Launch'), brk, text('yours')] }] }
+    const markdown = proseMirrorToMarkdown(doc).trim()
+    expect(markdown).toBe('# Launch<br/>yours')
+    expect(markdownToProseMirror(markdown).content[0].content.map((n) => n.text ?? n.type)).toEqual([
+      'Launch',
+      'hardBreak',
+      'yours',
+    ])
+  })
+})
+
+describe('plain text', () => {
+  test('is the characters, with nothing stripped', () => {
+    expect(docToPlainText(paragraph([text('Write '), text('<div>', [{ type: 'code' }]), text(' & go')]))).toBe(
+      'Write <div> & go',
+    )
+  })
+})

package/tests/unwritable.test.js

@@ -0,0 +1,39 @@
+import { unwritableNodes, proseMirrorToMarkdown, setDiagnosticsReporter, resetDiagnostics } from '../src/index.js'
+
+/**
+ * What a write would leave out, asked per document.
+ *
+ * The serializer reports a node it cannot write once per type per process, so
+ * a caller writing many documents could not tell which of them lost content —
+ * and a pull went on, writing a file without the node, which the next push then
+ * deleted from the site (measured 2026-10-14 with an editor's button node). A caller
+ * that must refuse rather than lose content asks first.
+ */
+
+const doc = (...content) => ({ type: 'doc', content })
+const p = (text) => ({ type: 'paragraph', content: [{ type: 'text', text }] })
+
+describe('unwritableNodes', () => {
+  beforeEach(() => resetDiagnostics())
+  afterEach(() => setDiagnosticsReporter())
+
+  test('a document markdown can carry has nothing left out', () => {
+    expect(unwritableNodes(doc(p('a'), { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'b' }] }))).toEqual([])
+  })
+
+  test('a node with no markdown form is named — every time it is asked', () => {
+    const lossy = doc(p('a'), { type: 'mysteryWidget', content: [] })
+    expect(unwritableNodes(lossy)).toEqual(['mysteryWidget'])
+    expect(unwritableNodes(lossy)).toEqual(['mysteryWidget'])
+  })
+
+  test('asking prints nothing, and the ordinary write still reports once', () => {
+    const printed = []
+    setDiagnosticsReporter((m) => printed.push(m))
+    unwritableNodes(doc({ type: 'mysteryWidget' }))
+    expect(printed).toEqual([])
+    proseMirrorToMarkdown(doc({ type: 'mysteryWidget' }))
+    proseMirrorToMarkdown(doc({ type: 'mysteryWidget' }))
+    expect(printed).toHaveLength(1)
+  })
+})

package/src/entities.js

@@ -1,107 +0,0 @@
-/**
- * @fileoverview Undo the HTML escaping that ProseMirror text nodes carry.
- *
- * Text in a PM node is HTML, because the render path injects it as HTML
- * (`kit`'s `SafeHtml` / `Text` use `dangerouslySetInnerHTML`). A literal `<`
- * the author typed inside a code span therefore has to be *stored* escaped —
- * `<code><x></code>` would have the browser swallow `<x>` as an unknown tag.
- *
- * `content-reader` encodes that asymmetry deliberately: it decodes `&amp;`,
- * `&quot;` and `&#39;` back to plain characters and leaves `&lt;` / `&gt;`
- * escaped. Verified against the parser (`parser/inline.js`) — raw HTML an
- * author writes in prose is preserved verbatim through the `html` token, so
- * only *machine-escaped* text carries entities on the way out.
- *
- * Two exports, because "leaving HTML-land" means different things depending
- * on where the text is going:
- *
- * - `decodeMarkupEntities` — the markdown lane. Undoes only the pair the
- *   reader left behind, so serializing is the reader's exact inverse.
- * - `decodeTextEntities` — the plain-text lane. The target is not HTML at
- *   all, so every entity resolves to the character a reader would see.
- */
-
-/**
- * Undo the escaping `content-reader` leaves in place (`&lt;` / `&gt;`).
- *
- * Deliberately narrow. `&amp;`, `&quot;` and `&#39;` are already decoded by
- * the reader, so a PM node holding one of those means the author wrote the
- * entity themselves — decoding it again would corrupt their source.
- *
- * @param {string} text
- * @returns {string}
- */
-export function decodeMarkupEntities(text) {
-  if (!text || !text.includes('&')) return text
-  return text.replace(/&lt;/g, '<').replace(/&gt;/g, '>')
-}
-
-/**
- * Escape a code span's text for storage in a ProseMirror text node.
- *
- * The exact inverse of {@link decodeMarkupEntities}, and the other half of the
- * invariant: a code span's content is rendered by injecting it as HTML, so a
- * literal `<` has to be stored escaped or `<code><x></code>` has the browser
- * swallow `<x>` and the span renders empty.
- *
- * Exported for **producers other than content-reader**. Any tool that writes a
- * ProseMirror code span — an editor, a converter — needs this rule, and the
- * rule living in prose rather than in code is what let two producers diverge.
- * Import it instead of reimplementing it.
- *
- * Only `<` and `>`: every other character is safe inside an HTML text node,
- * and escaping `&` here would double-encode an entity the author typed.
- *
- * @param {string} text - Raw code span content, as the author typed it
- * @returns {string} Text safe to store in a PM code-marked node
- */
-export function encodeMarkupEntities(text) {
-  if (!text) return text
-  return text.replace(/</g, '&lt;').replace(/>/g, '&gt;')
-}
-
-/**
- * Resolve every entity to the character a reader would actually see.
- *
- * `&amp;` is decoded **last** so `&amp;lt;` yields `&lt;` rather than `<` —
- * one decoding pass, not a cascade.
- *
- * @param {string} text
- * @returns {string}
- */
-export function decodeTextEntities(text) {
-  if (!text || !text.includes('&')) return text
-  return text
-    .replace(/&lt;/g, '<')
-    .replace(/&gt;/g, '>')
-    .replace(/&quot;/g, '"')
-    .replace(/&#0*39;/g, "'")
-    .replace(/&apos;/g, "'")
-    .replace(/&nbsp;/g, ' ')
-    .replace(/&amp;/g, '&')
-}
-
-/**
- * Drop raw inline HTML an author wrote in prose (`<br>`, `<span …>`).
- *
- * Only for the plain-text lane. Runs **before** entity decoding, so text the
- * author escaped on purpose (`&lt;b&gt;`, meaning a literal `<b>`) survives
- * as characters instead of being mistaken for a tag and stripped.
- *
- * @param {string} text
- * @returns {string}
- */
-export function stripInlineHtml(text) {
-  if (!text || !text.includes('<')) return text
-  return text.replace(/<\/?[a-zA-Z][^>]*>/g, '')
-}
-
-/**
- * The plain-text cleanup, in the order the two steps have to run.
- *
- * @param {string} text
- * @returns {string}
- */
-export function toPlainCharacters(text) {
-  return decodeTextEntities(stripInlineHtml(text))
-}

package/tests/entities.test.js

@@ -1,175 +0,0 @@
-/**
- * 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>')
-  })
-})