@uniweb/content-writer 0.2.8 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/content-writer",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "ProseMirror document structure to Markdown converter",
   "type": "module",
   "main": "src/index.js",
@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "vitest": "^4.1.7",
-    "@uniweb/content-reader": "1.1.16"
+    "@uniweb/content-reader": "1.2.0"
   },
   "directories": {
     "test": "tests"

package/probe.tmp.mjs

@@ -0,0 +1,18 @@
+import { proseMirrorToMarkdown } from './src/index.js'
+const doc = c => ({ type: 'doc', content: [c] })
+const text = t => ({ type: 'text', text: t })
+
+console.log('WarningBlock (text*, today):')
+console.log(' ', JSON.stringify(proseMirrorToMarkdown(doc({ type: 'WarningBlock', attrs: {}, content: [text('Be careful.')] })).trim()))
+
+console.log('WarningBlock with type:')
+console.log(' ', JSON.stringify(proseMirrorToMarkdown(doc({ type: 'WarningBlock', attrs: { type: 'warning' }, content: [text('Careful.')] })).trim()))
+
+console.log('WarningBlock (block+, after widening):')
+console.log(' ', JSON.stringify(proseMirrorToMarkdown(doc({ type: 'WarningBlock', attrs: {}, content: [
+  { type: 'paragraph', content: [text('One.')] }, { type: 'paragraph', content: [text('Two.')] }] })).trim()))
+
+console.log('details:')
+console.log(' ', JSON.stringify(proseMirrorToMarkdown(doc({ type: 'details', content: [
+  { type: 'detailsSummary', content: [text('Breaking '), { type: 'text', text: 'changes', marks: [{ type: 'bold' }] }] },
+  { type: 'detailsContent', content: [{ type: 'paragraph', content: [text('Body text.')] }] }] })).trim()))

package/src/attributes.js

@@ -2,7 +2,13 @@
  * @fileoverview Serialize attributes to curly brace syntax
  *
  * Inverse of content-reader's attributes.js.
- * Produces syntax like: {role=hero width=1200 .class #id autoplay}
+ * Produces syntax like: {role=hero width=1200 #id autoplay}
+ *
+ * There is no CSS-class form. A `class` attribute serializes as an ordinary
+ * `class=value` pair, and a name that starts with a dot (`{".featured": true}`)
+ * serializes through the plain boolean branch as `{.featured}` — the dot is
+ * part of the name. Both directions need no special case, which is why this
+ * file no longer has one.
  */
 
 /**
@@ -22,13 +28,7 @@ export function serializeAttributes(attrs, skipKeys = []) {
     if (skipSet.has(key)) continue
     if (value === null || value === undefined) continue
 
-    if (key === 'class') {
-      // Split class string into individual .class entries
-      const classes = String(value).split(/\s+/).filter(Boolean)
-      for (const cls of classes) {
-        parts.push(`.${cls}`)
-      }
-    } else if (key === 'id') {
+    if (key === 'id') {
       parts.push(`#${value}`)
     } else if (value === true) {
       // Boolean attribute

package/src/marks.js

@@ -38,6 +38,32 @@ function marksEqual(a, b) {
   return true
 }
 
+/**
+ * Would `inner` on its own re-parse to exactly this link?
+ *
+ * An author who writes a bare `https://example.com` gets a link mark whose
+ * href equals its text. Writing that back as `[https://example.com](https://example.com)`
+ * is content-identical but rewrites the author's file — and content-writer is
+ * what the editor uses to sync back to a developer's repository, so every save
+ * would churn every bare URL in it.
+ *
+ * Kept deliberately narrow. The bare form is only emitted when the mark
+ * carries nothing but an href, the text IS that href (or its address, for
+ * mailto), and the URL is one GFM autolinking will recapture with the same
+ * bounds: no whitespace or brackets, and no trailing punctuation, which
+ * autolink detection excludes from the match. Anything else keeps the
+ * explicit form, which is always correct if more verbose.
+ */
+const AUTOLINK_SAFE = /^[^\s<>()[\]]*[^\s<>()[\].,;:!?'"]$/
+
+function isBareAutolink(mark, inner) {
+  const { href, title, ...rest } = mark.attrs || {}
+  if (!href || title || Object.keys(rest).length > 0) return false
+  if (href === inner) return /^https?:\/\//.test(href) && AUTOLINK_SAFE.test(href)
+  if (href === `mailto:${inner}`) return AUTOLINK_SAFE.test(inner) && inner.includes('@')
+  return false
+}
+
 /**
  * Serialize a link mark's suffix: (href "title"){attrs}
  */
@@ -313,7 +339,7 @@ function applyMark(inner, mark) {
       // rule, Mod-Shift-s) and had no markdown form, so it was dropped.
       return `~~${inner}~~`
     case 'link':
-      return `[${inner}]${serializeLinkSuffix(mark)}`
+      return isBareAutolink(mark, inner) ? inner : `[${inner}]${serializeLinkSuffix(mark)}`
     case 'button':
       return `[${inner}]${serializeButtonSuffix(mark)}`
     case 'span':

package/src/nodes.js

@@ -6,6 +6,7 @@
 
 import yaml from 'js-yaml'
 import { serializeInlineContent, serializeBlockImage, serializeInsetRef } from './marks.js'
+import { serializeAttributes } from './attributes.js'
 
 // inset_ref serialization is shared with the inline path; it lives in
 // marks.js (alongside the other inline-attribute serializers) and is
@@ -95,6 +96,72 @@ export function serializeMathDisplay(node) {
     : '$$' + latex + '$$'
 }
 
+/**
+ * Serialize a container node back to its fence.
+ *
+ * The inverse of content-reader's `@Component{params}` fence. The info string
+ * is the inset's own token, so a container is byte-for-byte the block form of
+ * an inset — same concept, two levels.
+ *
+ * The fence widens past any backtick run in the body, which is what lets a
+ * container hold a code sample: `fenceWidthFor` is the same computation the
+ * plain code-block path uses.
+ *
+ * @param {Object} node - inset_block node with attrs.component + params
+ * @returns {string} Fenced container
+ */
+export function serializeInsetBlock(node) {
+  const { component, ...params } = node.attrs || {}
+  if (!component) return ''
+
+  const { serializeNode } = await_serializer()
+  const body = (node.content || [])
+    .map(child => serializeNode(child))
+    .filter(Boolean)
+    .join('\n\n')
+
+  const fence = '`'.repeat(fenceWidthFor(body))
+  const attrStr = serializeAttributes(params)
+
+  return `${fence}@${component}${attrStr}\n${body}\n${fence}`
+}
+
+/**
+ * Serialize a concept block back to its ```md:<tag> fence.
+ *
+ * The inverse of content-reader's concept-block branch. The body is real block
+ * content, so it serializes through the ordinary node path — a concept block is
+ * the section pipeline one level down, and its body is markdown at both ends.
+ *
+ * The fence widens past any backtick run in the body, for the same reason a
+ * container's does: an answer that shows a code sample is ordinary
+ * documentation, and a three-backtick fence would close on the sample's own
+ * fence and spill the remainder into the page as prose.
+ *
+ * A missing serializer here is not a cosmetic gap. `serializeNode` omits an
+ * unmapped node, so the whole block — the author's prose with it — would
+ * vanish from the file on the next write-back and from the per-page markdown
+ * projection. That is why the round-trip test asserts the BODY rather than
+ * just the fence line.
+ *
+ * @param {Object} node - concept_block node with attrs.tag + block content
+ * @returns {string} Fenced concept block
+ */
+export function serializeConceptBlock(node) {
+  const { tag } = node.attrs || {}
+  if (!tag) return ''
+
+  const { serializeNode } = await_serializer()
+  const body = (node.content || [])
+    .map(child => serializeNode(child))
+    .filter(Boolean)
+    .join('\n\n')
+
+  const fence = '`'.repeat(fenceWidthFor(body))
+
+  return `${fence}md:${tag}\n${body}\n${fence}`
+}
+
 /**
  * Serialize a data block node.
  *
@@ -154,30 +221,35 @@ export function serializeBlockquote(node) {
 
 /**
  * Serialize a bullet list node.
+ *
+ * `pad` is the literal indentation this list sits at — the parent item's
+ * CONTENT COLUMN, not a level count. See serializeListItem for why.
+ *
  * @param {Object} node - Bullet list node with content (listItem nodes)
- * @param {number} [indent=0] - Indentation level
+ * @param {string} [pad=''] - Indentation prefix for every marker in this list
  * @returns {string} Markdown bullet list
  */
-export function serializeBulletList(node, indent = 0) {
+export function serializeBulletList(node, pad = '') {
   if (!node.content) return ''
-  const prefix = '  '.repeat(indent)
   return node.content
-    .map(item => serializeListItem(item, `${prefix}- `, indent, isLoose(node)))
+    .map(item => serializeListItem(item, `${pad}- `, isLoose(node)))
     .join(itemSeparator(node))
 }
 
 /**
  * Serialize an ordered list node.
+ *
+ * `pad` is the literal indentation this list sits at — see serializeBulletList.
+ *
  * @param {Object} node - Ordered list node with attrs.start and content
- * @param {number} [indent=0] - Indentation level
+ * @param {string} [pad=''] - Indentation prefix for every marker in this list
  * @returns {string} Markdown ordered list
  */
-export function serializeOrderedList(node, indent = 0) {
+export function serializeOrderedList(node, pad = '') {
   if (!node.content) return ''
   const start = node.attrs?.start || 1
-  const prefix = '  '.repeat(indent)
   return node.content
-    .map((item, i) => serializeListItem(item, `${prefix}${start + i}. `, indent, isLoose(node)))
+    .map((item, i) => serializeListItem(item, `${pad}${start + i}. `, isLoose(node)))
     .join(itemSeparator(node))
 }
 
@@ -207,13 +279,24 @@ function isLoose(node) {
 
 /**
  * Serialize a list item.
+ *
+ * A nested list is indented to this item's CONTENT COLUMN — `bullet.length` —
+ * not by a fixed two spaces per level. The marker's width varies (`- ` is 2,
+ * `9. ` is 3, `10. ` is 4), and a child indented less than the parent's
+ * content column is not a child at all: markdown reads it as ending the
+ * outer list. That is a source-corrupting bug, not a cosmetic one — a
+ * three-item ordered list with a nested bullet list came back as three
+ * separate top-level nodes.
+ *
+ * `pad` already computes that column for every other block in the item; nested
+ * lists now use the same value instead of their own count.
+ *
  * @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, loose = false) {
+function serializeListItem(node, bullet, loose = false) {
   if (!node.content) return bullet
 
   const parts = []
@@ -224,11 +307,11 @@ function serializeListItem(node, bullet, indent, loose = false) {
 
     // Nested lists carry their own indentation.
     if (child.type === 'bulletList') {
-      parts.push(serializeBulletList(child, indent + 1))
+      parts.push(serializeBulletList(child, pad))
       continue
     }
     if (child.type === 'orderedList') {
-      parts.push(serializeOrderedList(child, indent + 1))
+      parts.push(serializeOrderedList(child, pad))
       continue
     }
 
@@ -270,9 +353,21 @@ function indentBlock(text, firstPrefix, pad) {
 
 /**
  * Serialize a divider node.
- * @returns {string} Markdown horizontal rule
+ *
+ * Emits the attribute spelling only when `type` carries a non-default value, so
+ * an ordinary rule stays `---` and no existing document is rewritten. `style` and
+ * `size` are deliberately NOT emitted: they are dead attrs (nothing reads them,
+ * no spelling sets them) and writing them would put vocabulary into every
+ * author's file that the framework is trying to retire.
+ *
+ * @param {Object} [node] - Divider node
+ * @returns {string} Markdown thematic break, with `{type=…}` when meaningful
  */
-export function serializeDivider() {
+export function serializeDivider(node) {
+  const type = node?.attrs?.type
+  if (typeof type === 'string' && type && type !== 'hr') {
+    return `---{type=${type}}`
+  }
   return '---'
 }
 

package/src/normalize.js

@@ -192,6 +192,15 @@ function mapEditorNode(node) {
     case 'UniwebIcon':
     case 'Icon':
       return mapUniwebIcon(node)
+    case 'WarningBlock':
+    case 'details': {
+      const attrs = EDITOR_CONTAINERS[node.type](node)
+      return {
+        type: 'inset_block',
+        attrs,
+        content: node.type === 'details' ? detailsBody(node) : asBlocks(node.content),
+      }
+    }
     case 'emoji':
       // The node carries the character alongside a name; the character is the
       // whole markdown form. Guarded rather than assumed to be populated.
@@ -237,6 +246,68 @@ function mapEditorNode(node) {
  */
 const NAMED_INLINE_STYLES = new Set(['accent', 'highlight', 'callout', 'muted'])
 
+/**
+ * Editor container nodes → the framework's `inset_block`, as an explicit table.
+ *
+ * Deliberately not derived from the node name. The editor's node is
+ * `WarningBlock` while the component is `Alert`, and its `type` defaults to
+ * `info` rather than `warning` — a name-derived mapping drops exactly that row,
+ * which is how `mapUniwebIcon` came to lose every icon the editor produces. A
+ * missing entry here is a visible gap rather than a silent assumption.
+ */
+const EDITOR_CONTAINERS = {
+  WarningBlock: node => ({ component: 'Alert', type: node.attrs?.type || 'info' }),
+  details: () => ({ component: 'Details' }),
+}
+
+/** Inline node types, for deciding whether a container's body needs wrapping. */
+const INLINE_TYPES = new Set([
+  'text',
+  'hardBreak',
+  'image',
+  'math_inline',
+  'inset_ref',
+  'emoji',
+  'UniwebIcon',
+])
+
+/**
+ * A container body as block content.
+ *
+ * `WarningBlock` holds `text*` today and `block+` after the editor's widening,
+ * so both shapes arrive here. Inline content is wrapped in one paragraph;
+ * block content passes through.
+ *
+ * @param {Array} content
+ * @returns {Array}
+ */
+function asBlocks(content) {
+  if (!content?.length) return []
+  return content.every(node => INLINE_TYPES.has(node.type))
+    ? [{ type: 'paragraph', content }]
+    : content
+}
+
+/**
+ * Flatten the editor's `details` › `detailsSummary` + `detailsContent` into the
+ * container's body, summary first.
+ *
+ * The summary leads rather than riding on an attribute: `detailsSummary` can
+ * carry marks, and `summary="…"` would flatten emphasis and links.
+ *
+ * @param {Object} node
+ * @returns {Array}
+ */
+function detailsBody(node) {
+  const body = []
+  for (const child of node.content || []) {
+    if (child.type === 'detailsSummary') body.push(...asBlocks(child.content))
+    else if (child.type === 'detailsContent') body.push(...(child.content || []))
+    else body.push(child)
+  }
+  return body
+}
+
 /** A mark that carries nothing and should be removed rather than reported. */
 const DROP_MARK = Symbol('drop-mark')
 

package/src/serializer.js

@@ -9,6 +9,8 @@ import {
   serializeParagraph,
   serializeImage,
   serializeInsetRef,
+  serializeInsetBlock,
+  serializeConceptBlock,
   serializeCodeBlock,
   serializeDataBlock,
   serializeBlockquote,
@@ -27,6 +29,8 @@ const NODE_SERIALIZERS = {
   paragraph: serializeParagraph,
   image: serializeImage,
   inset_ref: serializeInsetRef,
+  inset_block: serializeInsetBlock,
+  concept_block: serializeConceptBlock,
   codeBlock: serializeCodeBlock,
   dataBlock: serializeDataBlock,
   blockquote: serializeBlockquote,

package/tests/attributes.test.js

@@ -27,12 +27,12 @@ describe('Attribute Serialization', () => {
     expect(serializeAttributes({ autoplay: true, muted: true })).toBe('{autoplay muted}')
   })
 
-  test('serializes class as dot notation', () => {
-    expect(serializeAttributes({ class: 'featured' })).toBe('{.featured}')
+  test('serializes a dotted NAME through the plain boolean branch', () => {
+    expect(serializeAttributes({ '.featured': true })).toBe('{.featured}')
   })
 
-  test('serializes multiple classes', () => {
-    expect(serializeAttributes({ class: 'featured rounded shadow' })).toBe('{.featured .rounded .shadow}')
+  test('serializes several dotted names', () => {
+    expect(serializeAttributes({ '.featured': true, '.rounded': true, '.shadow': true })).toBe('{.featured .rounded .shadow}')
   })
 
   test('serializes id as hash notation', () => {
@@ -41,7 +41,7 @@ describe('Attribute Serialization', () => {
 
   test('serializes mixed attributes', () => {
     const result = serializeAttributes({
-      class: 'featured',
+      '.featured': true,
       id: 'main-logo',
       width: 800,
       loading: 'lazy',
@@ -95,7 +95,7 @@ describe('Attribute Serialization', () => {
 
   test('serializes data attributes', () => {
     const result = serializeAttributes({
-      class: 'info',
+      '.info': true,
       'data-tooltip': 'More info',
     })
     expect(result).toBe('{.info data-tooltip="More info"}')

package/tests/fixtures/roundtrip/bare-autolink.md

@@ -0,0 +1,7 @@
+Open http://localhost:5173 in your browser.
+
+Email me at a@b.com when it works.
+
+A labelled link to [the docs](https://example.com) stays labelled.
+
+A link whose label happens to be a URL, [https://example.com](https://example.com "titled"), keeps its explicit form.

package/tests/fixtures/roundtrip/containers.md

@@ -0,0 +1,22 @@
+# Containers
+
+```@Details
+A summary with **marks**
+
+Body content, [links](/x), the lot.
+```
+
+```@Alert{type=warning}
+Be careful with this.
+
+- one
+- two
+```
+
+````@Alert{type=info}
+Do not do this:
+
+```js
+const x = 1
+```
+````

package/tests/fixtures/roundtrip/nested-list-indent.md

@@ -0,0 +1,18 @@
+1. Push your repo to the host
+2. Configure:
+   - Base directory: `site`
+   - Build command: `pnpm build`
+3. Deploy
+
+## A two-digit marker is wider
+
+8. eight
+9. nine
+10. ten
+    - nested under a two-digit marker
+
+## A bullet parent stays at two
+
+- a
+  - b
+    - c

package/tests/marks.test.js

@@ -202,7 +202,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'highlighted text',
-        marks: [{ type: 'span', attrs: { class: 'highlight' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true } }],
       },
       { type: 'text', text: ' in a sentence.' },
     ]
@@ -216,7 +216,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'important note',
-        marks: [{ type: 'span', attrs: { class: 'callout bold' } }],
+        marks: [{ type: 'span', attrs: { '.callout': true, '.bold': true } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[important note]{.callout .bold}')
@@ -227,7 +227,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'key term',
-        marks: [{ type: 'span', attrs: { class: 'highlight', id: 'glossary-term' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true, id: 'glossary-term' } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[key term]{.highlight #glossary-term}')
@@ -238,7 +238,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'tooltip text',
-        marks: [{ type: 'span', attrs: { class: 'info', 'data-tooltip': 'More info' } }],
+        marks: [{ type: 'span', attrs: { '.info': true, 'data-tooltip': 'More info' } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[tooltip text]{.info data-tooltip="More info"}')
@@ -274,13 +274,13 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'first',
-        marks: [{ type: 'span', attrs: { class: 'highlight' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true } }],
       },
       { type: 'text', text: ' normal ' },
       {
         type: 'text',
         text: 'second',
-        marks: [{ type: 'span', attrs: { class: 'muted' } }],
+        marks: [{ type: 'span', attrs: { '.muted': true } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe('[first]{.highlight} normal [second]{.muted}')
@@ -297,7 +297,7 @@ describe('Inline Content Serialization', () => {
       {
         type: 'text',
         text: 'span',
-        marks: [{ type: 'span', attrs: { class: 'highlight' } }],
+        marks: [{ type: 'span', attrs: { '.highlight': true } }],
       },
     ]
     expect(serializeInlineContent(content)).toBe(

package/tests/roundtrip-source.test.js

@@ -242,3 +242,43 @@ describe('blocks inside list items', () => {
     expect(rt(source)).toBe(source)
   })
 })
+
+describe('containers — the block form of an inset', () => {
+  const rt = md => proseMirrorToMarkdown(markdownToProseMirror(md)).trim()
+
+  test('a container round-trips with its params', () => {
+    const source = '```@Alert{type=warning}\nBe careful.\n```'
+    expect(rt(source)).toBe(source)
+  })
+
+  test('a rich body survives — marks, links and blocks', () => {
+    const source = '```@Details\nA **summary**\n\nBody with [a link](/x).\n```'
+    expect(rt(source)).toBe(source)
+  })
+
+  test('the outer fence widens for a code block inside', () => {
+    // What makes a code sample in a callout possible, and why the body
+    // cannot be inline-only.
+    const source = '````@Alert{type=info}\nDo not:\n\n```js\nconst x = 1\n```\n````'
+    expect(rt(source)).toBe(source)
+  })
+
+  test('the editor container shapes normalize onto it', () => {
+    const text = t => ({ type: 'text', text: t })
+    const doc = node => proseMirrorToMarkdown({ type: 'doc', content: [node] }).trim()
+
+    // WarningBlock ↔ @Alert, defaulting to info, NOT warning — a name-derived
+    // mapping drops exactly this.
+    expect(doc({ type: 'WarningBlock', attrs: {}, content: [text('Careful.')] }))
+      .toBe('```@Alert{type=info}\nCareful.\n```')
+
+    // The summary is the first block and keeps its marks.
+    expect(doc({
+      type: 'details',
+      content: [
+        { type: 'detailsSummary', content: [text('Breaking '), { type: 'text', text: 'changes', marks: [{ type: 'bold' }] }] },
+        { type: 'detailsContent', content: [{ type: 'paragraph', content: [text('Body.')] }] },
+      ],
+    })).toBe('```@Details\nBreaking **changes**\n\nBody.\n```')
+  })
+})

package/tests/roundtrip.test.js

@@ -389,3 +389,71 @@ describe('Round-trip: Hard breaks', () => {
     expect(proseMirrorToMarkdown(parsed).trim()).toBe('wrapped\nparagraph')
   })
 })
+
+describe('Round-trip: Concept blocks', () => {
+  testRoundTrip(
+    '```md:faq\n# A question\nAn answer.\n\n# Another\nAlso answered.\n```',
+    'concept block with two pairs'
+  )
+
+  testRoundTrip(
+    '```md:warning\nBack up your database **first**.\n\n- Not reversible\n```',
+    'headingless concept block (a callout)'
+  )
+
+  testRoundTrip(
+    '```md:faq\n# Q\nAn answer with **bold** and a [link](/x).\n```',
+    'concept block whose body carries marks and links'
+  )
+
+  test('the BODY survives, not just the fence line', () => {
+    // A missing NODE_SERIALIZERS entry omits the whole node, so a test that
+    // only checks the fence and tag came back would pass on an empty block —
+    // and on a serializer that mangles the prose while the first line looks
+    // right. Assert the content.
+    const md = '```md:faq\n# What plans do you have?\nWe have three.\n```'
+    const out = proseMirrorToMarkdown(markdownToProseMirror(md))
+
+    expect(out).toContain('md:faq')
+    expect(out).toContain('# What plans do you have?')
+    expect(out).toContain('We have three.')
+  })
+
+  test('serialization is a FIXED POINT, which is the bar — not byte equality', () => {
+    // pass1 may differ from the author's original: the serializer normalizes
+    // spacing, so `# Q` immediately followed by its answer comes back with a
+    // blank line between them. Nothing is lost. Asserting byte-equality
+    // against the original would fail on content that is behaving correctly,
+    // and someone would "fix" the serializer to make it pass.
+    const original = '```md:faq\n# Q1\nA1\n# Q2\nA2\n```'
+    const pass1 = proseMirrorToMarkdown(markdownToProseMirror(original))
+    const pass2 = proseMirrorToMarkdown(markdownToProseMirror(pass1))
+
+    // Guard the guard: a fixed point on NOTHING is trivially true. Verified by
+    // canary — unregister the serializer and every other test in this block
+    // fails while `'' === ''` sails through. So pin the content first.
+    expect(pass1).toContain('# Q1')
+    expect(pass1).toContain('A2')
+    expect(pass2).toBe(pass1)
+  })
+
+  test('a code sample inside a concept block widens the outer fence', () => {
+    // Without fenceWidthFor the outer fence closes on the sample's own fence
+    // and the remainder spills into the page as prose. An FAQ answer that
+    // shows code is ordinary documentation, so this is the common case, not
+    // an edge one.
+    const md = '````md:faq\n# How do I start?\nRun this:\n\n```sh\nnpm i\n```\n````'
+    const out = proseMirrorToMarkdown(markdownToProseMirror(md))
+
+    expect(out.startsWith('````md:faq')).toBe(true)
+    expect(out).toContain('```sh')
+    expect(markdownToProseMirror(out)).toEqual(markdownToProseMirror(md))
+  })
+
+  test('an unmapped node would be dropped — so this one must stay mapped', () => {
+    // The failure mode this suite exists to catch: serializeNode omits a node
+    // it has no serializer for, taking the author's prose with it.
+    const doc = markdownToProseMirror('```md:faq\n# Q\nA\n```')
+    expect(proseMirrorToMarkdown(doc).trim()).not.toBe('')
+  })
+})

package/tests/serializer.test.js

@@ -180,7 +180,7 @@ describe('Image Serialization', () => {
             alt: 'Logo',
             caption: null,
             role: 'image',
-            class: 'featured',
+            '.featured': true,
             id: 'main-logo',
           },
         },
@@ -200,7 +200,7 @@ describe('Image Serialization', () => {
             alt: 'Gallery',
             caption: null,
             role: 'image',
-            class: 'featured rounded shadow',
+            '.featured': true, '.rounded': true, '.shadow': true,
           },
         },
       ],