@uniweb/content-writer 0.2.4 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/content-writer",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "ProseMirror document structure to Markdown converter",
   "type": "module",
   "main": "src/index.js",
@@ -18,12 +18,8 @@
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "@uniweb/content-reader": "1.1.5"
-  },
-  "jest": {
-    "testEnvironment": "node",
-    "verbose": true
+    "vitest": "^4.1.7",
+    "@uniweb/content-reader": "1.1.12"
   },
   "directories": {
     "test": "tests"
@@ -37,7 +33,7 @@
   },
   "homepage": "https://github.com/uniweb/content-writer#readme",
   "scripts": {
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
-    "test:watch": "NODE_OPTIONS=--experimental-vm-modules jest --watch"
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/diagnostics.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview No-silent-drop diagnostics for the markdown serializer.
+ *
+ * content-writer used to return `null` for any node type it did not
+ * recognize and `serializeDoc` filtered those nulls out — so an
+ * editor-authored node the serializer didn't know about (a `Video`,
+ * `card-group`, `FormBlock`, an unmapped mark …) vanished on write with
+ * no signal. That silent loss was the original sin this module closes.
+ *
+ * The contract now: a node or mark the serializer can't represent is
+ * still dropped from the output (we can't invent a markdown form for it),
+ * but it is reported loudly instead of silently. Editor-dialect content
+ * should be run through `normalizeDialect` (normalize.js) first, which
+ * maps the constructs that DO have a faithful markdown form; whatever
+ * reaches the serializer unmapped is a genuine, tracked capability gap.
+ *
+ * Warnings dedupe per type so a build pipeline processing many documents
+ * reports each unmapped construct once, not once per occurrence.
+ */
+
+const warnedNodes = new Set()
+const warnedMarks = new Set()
+
+/* The reporter is injectable so callers (and tests) can collect rather
+ * than print. Defaults to console.warn. */
+let report = (message) => console.warn(message)
+
+/**
+ * Override the diagnostics reporter (e.g. to collect warnings in tests
+ * or route them into a build log). Pass no argument to restore the
+ * default console.warn reporter.
+ * @param {(message: string) => void} [fn]
+ */
+export function setDiagnosticsReporter(fn) {
+  report = typeof fn === 'function' ? fn : (message) => console.warn(message)
+}
+
+/**
+ * Clear the dedupe memory. Tests call this between cases so a warning
+ * emitted once earlier doesn't suppress the assertion in a later case.
+ */
+export function resetDiagnostics() {
+  warnedNodes.clear()
+  warnedMarks.clear()
+}
+
+/**
+ * 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'
+  if (warnedNodes.has(type)) return
+  warnedNodes.add(type)
+  report(
+    `[content-writer] No markdown serializer for node type "${type}" — ` +
+      `it was omitted from the output. If this is editor-dialect content, ` +
+      `normalize it first (see @uniweb/content-writer normalizeDialect); ` +
+      `otherwise this is a tracked capability gap.`
+  )
+}
+
+/**
+ * Report an inline mark the serializer has no markdown form for. The
+ * marked text itself is still emitted (unstyled); only the styling is
+ * dropped.
+ * @param {string} type - The unmapped mark type
+ */
+export function warnUnmappedMark(type) {
+  const key = type || 'unknown'
+  if (warnedMarks.has(key)) return
+  warnedMarks.add(key)
+  report(
+    `[content-writer] No markdown serializer for mark "${key}" — the text ` +
+      `was kept but its styling was dropped. Tracked capability gap.`
+  )
+}

package/src/index.js

@@ -8,6 +8,8 @@
 export { serializeDoc as proseMirrorToMarkdown } from './serializer.js'
 export { serializeFrontmatter } from './frontmatter.js'
 export { docToPlainText } from './plain-text.js'
+export { normalizeDialect } from './normalize.js'
+export { setDiagnosticsReporter, resetDiagnostics } from './diagnostics.js'
 
 import { serializeDoc } from './serializer.js'
 import { serializeFrontmatter } from './frontmatter.js'

package/src/marks.js

@@ -5,6 +5,26 @@
  */
 
 import { serializeAttributes } from './attributes.js'
+import { warnUnmappedMark, warnUnmappedNode } from './diagnostics.js'
+
+/**
+ * Marks the markdown serializer can represent. Any other mark on an
+ * inline node has its styling dropped (the text is still emitted) and is
+ * reported by the no-silent-drop guard — e.g. editor-dialect `highlight`,
+ * `textStyle` (colour), `strike`, `underline`, `uniqueID`, which need a
+ * named-inline-style mapping decision.
+ */
+const KNOWN_MARKS = new Set(['bold', 'italic', 'code', 'link', 'button', 'span'])
+
+/** Report any inline mark we have no markdown form for (deduped per type). */
+function reportUnknownMarks(content) {
+  for (const node of content) {
+    if (!node?.marks) continue
+    for (const mark of node.marks) {
+      if (!KNOWN_MARKS.has(mark.type)) warnUnmappedMark(mark.type)
+    }
+  }
+}
 
 /**
  * Check if a node has a specific mark type.
@@ -60,6 +80,41 @@ function serializeSpanSuffix(mark) {
   return serializeAttributes(mark.attrs || {})
 }
 
+/**
+ * Serialize an inset_ref node (a foundation-component reference) back to
+ * markdown. Shared by both the block path (the document-level node
+ * serializer) and the inline path (mid-prose insets, cites, refs) so a
+ * single definition stays the inverse of the content-reader parser.
+ *
+ *   visual  (the `!` form, default)  → ![label](@Component){attrs}
+ *   text    (embedKind: 'text')      → [label](@Component){attrs}
+ *   Cite/Ref text-inset with a key   → [@key] / [#id] {attrs}  (sigil shorthand)
+ *
+ * `label` is the reference key (keyed form) when present, else the alt
+ * text. `component`/`embedKind`/`alt`/`key` are structural and consumed
+ * here; everything else in attrs becomes curly-brace attributes.
+ *
+ * Visual is the parser's default (block.js treats `embedKind !== 'text'`
+ * as visual, and the inset extractor omits the default), so the `!` is
+ * emitted unless `embedKind` is explicitly `'text'`.
+ */
+export function serializeInsetRef(node) {
+  const { component, embedKind, alt, key, ...rest } = node.attrs || {}
+  const attrStr = serializeAttributes(rest)
+  const isText = embedKind === 'text'
+
+  // A keyed Cite/Ref text-inset round-trips to its sigil shorthand —
+  // [@key] / [#id] — the cleanest canonical form and exactly what the
+  // cite/ref tokenizers produce. (key already carries its @/# sigil.)
+  if (isText && key && (component === 'Cite' || component === 'Ref')) {
+    return `[${key}]${attrStr}`
+  }
+
+  const label = key ?? alt ?? ''
+  const bang = isText ? '' : '!'
+  return `${bang}[${label}](@${component})${attrStr}`
+}
+
 /**
  * Serialize an inline image node (icon within a paragraph).
  */
@@ -138,6 +193,9 @@ export function serializeBlockImage(node) {
 export function serializeInlineContent(content) {
   if (!content || content.length === 0) return ''
 
+  // No silent drops: flag any mark we can't represent before serializing.
+  reportUnknownMarks(content)
+
   // Pre-process: group nodes by wrapping marks (link, button, span)
   const segments = groupByWrappingMarks(content)
   return segments.map(seg => serializeSegment(seg)).join('')
@@ -222,11 +280,20 @@ function serializePlainNode(node) {
   if (node.type === 'image') {
     return serializeInlineImage(node)
   }
+  if (node.type === 'inset_ref') {
+    return serializeInsetRef(node)
+  }
   if (node.type === 'math_inline') {
     const latex = node.attrs?.latex || ''
     return node.attrs?.display ? '$$' + latex + '$$' : '$' + latex + '$'
   }
-  if (node.type !== 'text') return ''
+  if (node.type !== 'text') {
+    // No silent drops: an inline node we have no markdown form for is
+    // still omitted (we can't invent one) but reported loudly, the same
+    // contract the block path follows.
+    warnUnmappedNode(node)
+    return ''
+  }
   return serializeTextWithMarks(node.text, node.marks || [])
 }
 

package/src/nodes.js

@@ -4,8 +4,12 @@
  * Each function takes a ProseMirror node and returns a markdown string.
  */
 
-import { serializeInlineContent, serializeBlockImage } from './marks.js'
-import { serializeAttributes } from './attributes.js'
+import { serializeInlineContent, serializeBlockImage, serializeInsetRef } from './marks.js'
+
+// inset_ref serialization is shared with the inline path; it lives in
+// marks.js (alongside the other inline-attribute serializers) and is
+// re-exported here so the document-level node serializer can register it.
+export { serializeInsetRef }
 
 /**
  * Serialize a heading node.
@@ -36,18 +40,6 @@ export function serializeImage(node) {
   return serializeBlockImage(node)
 }
 
-/**
- * Serialize an inset_ref node (component reference).
- * @param {Object} node - Inset ref node with attrs.component
- * @returns {string} Markdown component reference
- */
-export function serializeInsetRef(node) {
-  const { component, alt, ...rest } = node.attrs || {}
-  const altPart = alt || ''
-  const attrStr = serializeAttributes(rest)
-  return `![${altPart}](@${component})${attrStr}`
-}
-
 /**
  * Serialize a code block node.
  * @param {Object} node - Code block node with attrs.language and content

package/src/normalize.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Editor-dialect → framework-dialect ProseMirror normalizer.
+ *
+ * Two ProseMirror dialects flow through Uniweb:
+ *
+ *   - the **framework-markdown dialect** that content-reader produces and
+ *     content-writer's serializers are written against (`image` with a
+ *     `role`, `divider`, `dataBlock`, `inset_ref`, marks `bold/italic/
+ *     link/button/code/span`), and
+ *   - the **editor (TipTap) dialect** (`ImageBlock`, `Video`,
+ *     `UniwebIcon`/`Icon`, `DividerBlock`, `card-group`, `FormBlock`,
+ *     `WarningBlock`, `details`, colour/highlight marks …).
+ *
+ * A ProseMirror document handed to content-writer may be in either dialect,
+ * or a mix (file-origin content is framework-dialect; editor-authored
+ * content is editor-dialect). Rather than teach the serializers both
+ * vocabularies, we normalize the editor dialect onto the framework dialect
+ * FIRST, then serialize one canonical dialect. semantic-parser's
+ * `sequence.js` is the reference for what each editor construct means.
+ *
+ * This is the "normalize-first" half of the codec. It is **idempotent on
+ * framework-dialect input**: every framework node
+ * passes through unchanged, so running it on already-canonical content is
+ * a structural no-op (the existing round-trip tests stay green).
+ *
+ * ## What this maps today (zero-guess cells only)
+ *
+ *   - `DividerBlock` / `horizontalRule` → `divider`
+ *   - `Video`      → `image{role:'video'}`  — only when a real media URL
+ *                    is present (`src`)
+ *   - `ImageBlock` → `image`                — only when a real URL is
+ *                    present (`url`/`src`)
+ *   - `UniwebIcon` → `image{role:'icon'}`   — only the `library`+`name`
+ *                    form (`![](lib-name)`)
+ *
+ * ## What it deliberately does NOT map (left for the serializer's
+ * no-silent-drop guard to report — a tracked capability gap)
+ *
+ *   - Media that carries only a structured asset identifier (no direct
+ *     `url`/`src`) or an inline `svg` blob. Media references are written
+ *     VERBATIM — the codec does not resolve or render; the kit Image/Video
+ *     components resolve the reference at render time. The common case (a
+ *     `url`/`src` on the node) is handled by writing it verbatim; an
+ *     identifier-only node is the edge (carry it verbatim once its form is
+ *     confirmed), and inline `svg` blobs hit the guard.
+ *   - `FormBlock` — the editor node carries `activeSchemaId` + filled
+ *     `data`; the framework `yaml:form` block carries a form *definition*.
+ *     Different shapes; mapping needs a decision, not a guess.
+ *   - `card-group`/`document-group`, `details`, `WarningBlock` — open
+ *     mapping decisions (items vs insets; 🟥 gaps).
+ *   - colour/highlight/strike/underline marks — need the named-inline-
+ *     style convention decision.
+ *
+ * Each unmapped construct reaches content-writer's serializer as-is and
+ * is reported by the no-silent-drop guard (diagnostics.js) — never lost
+ * silently.
+ */
+
+/**
+ * Editor-transient image attrs that have no on-disk markdown meaning and
+ * are dropped by design (not data loss — they're editor UI/upload state
+ * or layout hints the markdown form doesn't carry).
+ */
+const DROPPED_IMAGE_ATTRS = new Set([
+  'url',
+  'src',
+  'info',
+  'direction',
+  'credit',
+  'theme',
+  'filter',
+  'targetId',
+  'contentId',
+  'uploading',
+  'uploadingObject',
+  'loading_progress',
+  'aspect_ratio',
+])
+
+/**
+ * Markdown-meaningful image/media attrs we carry through, when present
+ * with a real value. Mirrors content-reader's image schema + the media
+ * attrs documented in content-structure.md (role/poster/href/etc.).
+ */
+const KEPT_IMAGE_ATTRS = [
+  'alt',
+  'caption',
+  'href',
+  'target',
+  'width',
+  'height',
+  'loading',
+  'poster',
+  'preview',
+  'autoplay',
+  'muted',
+  'loop',
+  'controls',
+  'fit',
+  'position',
+  'class',
+  'id',
+]
+
+/** Pick the non-empty markdown-meaningful attrs from an editor image node. */
+function keptImageAttrs(attrs) {
+  const out = {}
+  for (const key of KEPT_IMAGE_ATTRS) {
+    const value = attrs[key]
+    if (value === null || value === undefined || value === '') continue
+    out[key] = value
+  }
+  return out
+}
+
+/**
+ * Map an editor `ImageBlock` to a framework `image` node.
+ * @returns {Object|null} framework image node, or null if unresolvable
+ *   (identifier-only asset → leave for the guard to report).
+ */
+function mapImageBlock(node) {
+  const attrs = node.attrs || {}
+  const src = attrs.url || attrs.src
+  if (!src) return null // identifier-only / not yet uploaded → can't resolve to a URL
+
+  const out = { src, ...keptImageAttrs(attrs) }
+  if (attrs.role && attrs.role !== 'image') out.role = attrs.role
+  return { type: 'image', attrs: out }
+}
+
+/**
+ * Map an editor `Video` to a framework `image{role:'video'}` node
+ * (the framework expresses video as media-by-role; there is no Video
+ * node by design).
+ * @returns {Object|null}
+ */
+function mapVideo(node) {
+  const attrs = node.attrs || {}
+  const src = attrs.src
+  if (!src) return null // identifier-only → asset channel, not a URL
+
+  const out = { src, role: 'video', ...keptImageAttrs(attrs) }
+  // The editor carries the poster as a coverImg object; only a real URL
+  // (not an identifier) has a markdown home.
+  const poster = attrs.coverImg?.src
+  if (poster) out.poster = poster
+  return { type: 'image', attrs: out }
+}
+
+/**
+ * Map an editor `UniwebIcon` to a framework `image{role:'icon'}` node.
+ * Only the `library`+`name` form (e.g. `![](lu-home)`) is mapped — an
+ * inline `svg` blob or a bare `url` has no clean markdown home yet.
+ * @returns {Object|null}
+ */
+function mapUniwebIcon(node) {
+  const attrs = node.attrs || {}
+  if (!attrs.library || !attrs.name) return null
+
+  const out = { role: 'icon', library: attrs.library, name: attrs.name }
+  if (attrs.size) out.size = attrs.size
+  if (attrs.color) out.color = attrs.color
+  return { type: 'image', attrs: out }
+}
+
+/**
+ * Map a single node from editor dialect to framework dialect.
+ * @returns {Object|null} a framework-dialect node, or null when there is
+ *   no faithful mapping (the original node is then kept and reported by
+ *   the serializer's no-silent-drop guard).
+ */
+function mapEditorNode(node) {
+  switch (node.type) {
+    case 'DividerBlock':
+    case 'horizontalRule':
+      return { type: 'divider', attrs: {} }
+    case 'ImageBlock':
+      return mapImageBlock(node)
+    case 'Video':
+      return mapVideo(node)
+    case 'UniwebIcon':
+      return mapUniwebIcon(node)
+    default:
+      return null
+  }
+}
+
+/**
+ * Recursively normalize one node: map it to the framework dialect (if it
+ * is a recognized editor node with a faithful mapping), then normalize
+ * its children. Nodes without a mapping pass through unchanged so any
+ * editor-dialect descendants are still caught.
+ */
+function normalizeNode(node) {
+  if (!node || typeof node !== 'object') return node
+
+  const result = mapEditorNode(node) || node
+
+  if (Array.isArray(result.content)) {
+    return { ...result, content: result.content.map(normalizeNode) }
+  }
+  return result
+}
+
+/**
+ * Normalize an editor-dialect (or mixed-dialect) ProseMirror document to
+ * the framework dialect that content-writer's serializers consume.
+ * Idempotent on framework-dialect input.
+ *
+ * @param {Object} doc - ProseMirror document ({ type:'doc', content:[…] })
+ * @returns {Object} a framework-dialect document
+ */
+export function normalizeDialect(doc) {
+  if (!doc || !Array.isArray(doc.content)) return doc
+  return { ...doc, content: doc.content.map(normalizeNode) }
+}

package/src/serializer.js

@@ -19,6 +19,8 @@ import {
   serializeMathDisplay,
   setSerializer,
 } from './nodes.js'
+import { normalizeDialect } from './normalize.js'
+import { warnUnmappedNode } from './diagnostics.js'
 
 const NODE_SERIALIZERS = {
   heading: serializeHeading,
@@ -42,7 +44,14 @@ const NODE_SERIALIZERS = {
  */
 export function serializeNode(node) {
   const serializer = NODE_SERIALIZERS[node.type]
-  if (!serializer) return null
+  if (!serializer) {
+    // No silent drops: an unmapped node is still omitted (we have no
+    // markdown form for it) but reported loudly. Editor-dialect content
+    // should be normalized first (normalizeDialect); whatever reaches
+    // here unmapped is a tracked capability gap (§8).
+    warnUnmappedNode(node)
+    return null
+  }
   return serializer(node)
 }
 
@@ -57,6 +66,10 @@ setSerializer(serializeNode)
 export function serializeDoc(doc) {
   if (!doc?.content) return ''
 
+  // Normalize editor-dialect (or mixed-dialect) input onto the framework
+  // dialect the node serializers consume. No-op for framework-dialect docs.
+  doc = normalizeDialect(doc)
+
   return doc.content
     .map(node => serializeNode(node))
     .filter(s => s !== null && s !== undefined)

package/tests/normalize.test.js

@@ -0,0 +1,198 @@
+/**
+ * Editor-dialect normalization + no-silent-drop guard.
+ *
+ * Verifies that content-writer maps the editor (TipTap) dialect onto the
+ * framework markdown dialect for the zero-guess constructs, that it stays
+ * a no-op on framework-dialect input, and that anything it can't map is
+ * reported loudly instead of silently dropped.
+ *
+ * Editor-node attr shapes are modelled on the editor block definitions and
+ * the committed semantic-parser fixtures.
+ */
+
+import { beforeEach, afterEach } from 'vitest'
+import { markdownToProseMirror } from '@uniweb/content-reader'
+import {
+  proseMirrorToMarkdown,
+  normalizeDialect,
+  setDiagnosticsReporter,
+  resetDiagnostics,
+} from '../src/index.js'
+
+const doc = (...content) => ({ type: 'doc', content })
+const para = (...content) => ({ type: 'paragraph', content })
+
+/** Assert an editor doc serializes to expected markdown and is a fixed point. */
+function expectMarkdown(editorDoc, expected) {
+  const md = proseMirrorToMarkdown(editorDoc)
+  expect(md).toBe(expected)
+  // Re-parsing and re-serializing the framework markdown must be stable.
+  const md2 = proseMirrorToMarkdown(markdownToProseMirror(md))
+  expect(md2).toBe(md)
+}
+
+describe('normalizeDialect: idempotent on framework dialect', () => {
+  test('a framework-dialect document is unchanged through normalization', () => {
+    const md =
+      '# Title\n\nSome **bold** text.\n\n---\n\n![Hero](./hero.jpg){role=banner}'
+    const frameworkDoc = markdownToProseMirror(md)
+    // normalize then serialize === serialize (serializeDoc normalizes internally)
+    expect(proseMirrorToMarkdown(normalizeDialect(frameworkDoc))).toBe(
+      proseMirrorToMarkdown(frameworkDoc)
+    )
+    // and the round trip is preserved
+    expect(markdownToProseMirror(proseMirrorToMarkdown(frameworkDoc))).toEqual(
+      frameworkDoc
+    )
+  })
+})
+
+describe('normalizeDialect: editor blocks → framework markdown', () => {
+  test('DividerBlock → ---', () => {
+    expectMarkdown(doc({ type: 'DividerBlock', attrs: { type: 'dot' } }), '---')
+  })
+
+  test('horizontalRule → ---', () => {
+    expectMarkdown(doc({ type: 'horizontalRule' }), '---')
+  })
+
+  test('ImageBlock (url) → ![](){role}', () => {
+    expectMarkdown(
+      doc({
+        type: 'ImageBlock',
+        attrs: {
+          url: './hero.jpg',
+          role: 'banner',
+          alt: 'Hero',
+          direction: 'center', // editor layout state — intentionally dropped
+          info: { identifier: '' },
+        },
+      }),
+      '![Hero](./hero.jpg){role=banner}'
+    )
+  })
+
+  test('ImageBlock without a role serializes as a plain image', () => {
+    expectMarkdown(
+      doc({ type: 'ImageBlock', attrs: { url: './photo.jpg', alt: 'Photo' } }),
+      '![Photo](./photo.jpg)'
+    )
+  })
+
+  test('Video (src + coverImg) → ![](){role=video poster}', () => {
+    expectMarkdown(
+      doc({
+        type: 'Video',
+        attrs: {
+          src: './demo.mp4',
+          alt: 'Demo',
+          coverImg: { src: './poster.jpg', identifier: null },
+          direction: 'center',
+        },
+      }),
+      '![Demo](./demo.mp4){role=video poster=./poster.jpg}'
+    )
+  })
+
+  test('UniwebIcon (library+name) → ![](lib-name)', () => {
+    expectMarkdown(
+      doc(para({ type: 'UniwebIcon', attrs: { library: 'lu', name: 'home' } })),
+      '![](lu-home)'
+    )
+  })
+})
+
+describe('no-silent-drop guard: unmappable nodes are reported, not lost', () => {
+  let warnings
+
+  beforeEach(() => {
+    warnings = []
+    resetDiagnostics()
+    setDiagnosticsReporter((m) => warnings.push(m))
+  })
+
+  afterEach(() => {
+    setDiagnosticsReporter() // restore console.warn
+    resetDiagnostics()
+  })
+
+  test('an unmapped editor container (card-group) warns', () => {
+    proseMirrorToMarkdown(
+      doc({
+        type: 'card-group',
+        content: [{ type: 'card', attrs: { title: 'A' } }],
+      })
+    )
+    expect(warnings.some((m) => m.includes('card-group'))).toBe(true)
+  })
+
+  test('FormBlock warns (activeSchemaId has no markdown home yet)', () => {
+    proseMirrorToMarkdown(
+      doc({
+        type: 'FormBlock',
+        attrs: { activeSchemaId: 'stats', data: [{ number: '42' }] },
+      })
+    )
+    expect(warnings.some((m) => m.includes('FormBlock'))).toBe(true)
+  })
+
+  test('media with only an asset identifier (no URL) warns rather than guessing a src', () => {
+    proseMirrorToMarkdown(
+      doc({
+        type: 'ImageBlock',
+        attrs: { url: null, src: null, info: { identifier: 'v1/base.jpg' } },
+      })
+    )
+    expect(warnings.some((m) => m.includes('ImageBlock'))).toBe(true)
+  })
+
+  test('an unmapped mark (highlight) warns but keeps the text', () => {
+    const md = proseMirrorToMarkdown(
+      doc(
+        para({
+          type: 'text',
+          text: 'important',
+          marks: [{ type: 'highlight' }],
+        })
+      )
+    )
+    expect(md).toBe('important') // text preserved, styling dropped
+    expect(warnings.some((m) => m.includes('highlight'))).toBe(true)
+  })
+
+  test('a known framework document produces no warnings', () => {
+    proseMirrorToMarkdown(
+      markdownToProseMirror('# Hi\n\nSome **bold** and a [link](/x).')
+    )
+    expect(warnings).toEqual([])
+  })
+
+  test('an inline inset_ref is serialized, not silently dropped', () => {
+    const md = proseMirrorToMarkdown(
+      doc(
+        para(
+          { type: 'text', text: 'See ' },
+          { type: 'inset_ref', attrs: { component: 'Cite', embedKind: 'text', key: '@darwin', alt: null } },
+          { type: 'text', text: ' here.' }
+        )
+      )
+    )
+    expect(md).toBe('See [@darwin] here.')
+    expect(warnings).toEqual([]) // a known inline node — no warning
+  })
+
+  test('an unmapped inline node warns rather than vanishing', () => {
+    const md = proseMirrorToMarkdown(
+      doc(
+        para(
+          { type: 'text', text: 'before ' },
+          { type: 'FancyInlineWidget', attrs: { id: 'x' } },
+          { type: 'text', text: ' after' }
+        )
+      )
+    )
+    // the surrounding text survives; the unmapped node is omitted but reported
+    expect(md).toBe('before  after')
+    expect(warnings.some((m) => m.includes('FancyInlineWidget'))).toBe(true)
+  })
+})

package/tests/roundtrip.test.js

@@ -228,6 +228,59 @@ describe('Round-trip: Component References', () => {
   )
 })
 
+describe('Round-trip: Inline insets, cites, and refs', () => {
+  testRoundTrip(
+    'Text with [@darwin1859] citation.',
+    'inline cite shorthand'
+  )
+
+  testRoundTrip(
+    'Multi [@a;@b]{page=42} cite.',
+    'multi-cite with locator'
+  )
+
+  testRoundTrip(
+    'See [#fig1] here.',
+    'inline cross-reference shorthand'
+  )
+
+  testRoundTrip(
+    'See [#a;#b]{class=compact} together.',
+    'multi-ref with attrs'
+  )
+
+  testRoundTrip(
+    'Inline [the label](@Tooltip){variant=compact} here.',
+    'inline textual inset with label and params'
+  )
+
+  testRoundTrip(
+    'Visual ![alt text](@Badge){size=sm} mid prose.',
+    'inline visual inset mid-paragraph'
+  )
+
+  testRoundTrip(
+    'Keyed visual ![@darwin](@Cite) mid prose.',
+    'inline keyed visual inset'
+  )
+
+  // A keyed Cite/Ref written in the explicit link form normalizes to the
+  // sigil shorthand — both parse to the same node.
+  test('keyed cite in link form normalizes to shorthand', () => {
+    const markdown = 'Keyed [@darwin](@Cite){page=10} ref.'
+    const parsed = markdownToProseMirror(markdown)
+    const serialized = proseMirrorToMarkdown(parsed)
+    expect(serialized).toBe('Keyed [@darwin]{page=10} ref.')
+    const reparsed = markdownToProseMirror(serialized)
+    expect(reparsed).toEqual(parsed)
+  })
+
+  testRoundTrip(
+    'A [@key] cite and an [#id] ref in one paragraph.',
+    'cite and ref in the same paragraph'
+  )
+})
+
 describe('Round-trip: Code', () => {
   testRoundTrip(
     '```javascript\nconst x = 1;\nconsole.log(\'x:\', x);\n```',

package/vitest.config.js

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.js']
+  }
+})