@ceedcv-maya/shared-editor-react 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceedcv-maya/shared-editor-react",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -23,6 +23,7 @@
     "@tiptap/pm": "^3.0.0",
     "@tiptap/react": "^3.0.0",
     "@tiptap/starter-kit": "^3.0.0",
+    "@tiptap/static-renderer": "^3.0.0",
     "dompurify": "^3.0.0",
     "mammoth": "^1.8.0",
     "react": "^18.0.0 || ^19.0.0",
@@ -34,7 +35,9 @@
     }
   },
   "devDependencies": {
+    "@tiptap/static-renderer": "^3.0.0",
     "@types/dompurify": "^3.0.0",
+    "@types/node": "^25.9.2",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^29.1.1",

package/src/components/EditorContentJson.tsx

@@ -0,0 +1,29 @@
+import { useMemo } from 'react';
+
+import { renderTiptapJsonToHtml } from '../lib/renderTiptapJson';
+import { EditorContentHtml } from './EditorContentHtml';
+import type { TiptapDoc, TiptapNode } from '../types';
+
+interface EditorContentJsonProps {
+  /**
+   * Stored TipTap content — a wrapped doc (`{ type: 'doc', content }`) or the
+   * bare content array that `MayaEditor` emits and the backend persists.
+   */
+  content: TiptapDoc | TiptapNode[] | unknown;
+  className?: string;
+}
+
+/**
+ * Read-only renderer for stored TipTap JSON. Renders via TipTap's static
+ * renderer (single source of truth with the editor schema) and sanitises the
+ * result through `EditorContentHtml` (DOMPurify).
+ *
+ * Use this instead of hand-rolled JSON→HTML walkers. For pre-rendered HTML
+ * strings (e.g. server-side `TiptapHtmlRenderer` output) use
+ * `EditorContentHtml` directly.
+ */
+export function EditorContentJson({ content, className }: EditorContentJsonProps) {
+  const html = useMemo(() => renderTiptapJsonToHtml(content), [content]);
+  if (!html) return null;
+  return <EditorContentHtml html={html} className={className} />;
+}

package/src/components/MayaEditor.tsx

@@ -9,6 +9,7 @@ import { useEditorContent, type EditorOutput } from '../hooks/useEditorContent';
 import { sanitizeEditorHtml } from '../lib/dompurifyConfig';
 import { markdownToHtml } from '../lib/markdownToHtml';
 import { htmlToMarkdown } from '../lib/htmlToMarkdown';
+import { looksLikeMarkdown } from '../lib/looksLikeMarkdown';
 import { normalizeTableHtml } from '../lib/normalizeTableHtml';
 import { docxToHtml } from '../lib/docxToHtml';
 import type { EditorMode, TiptapDoc } from '../types';
@@ -141,6 +142,10 @@ export function MayaEditor({
 
   const extensions = useMemo(() => buildMayaEditorExtensions(mode), [mode]);
 
+  // Stable handle to the editor for use inside editorProps callbacks, which are
+  // defined before `useEditor` returns.
+  const editorRef = useRef<Editor | null>(null);
+
   const editor = useEditor({
     extensions,
     content: initialContent ?? '',
@@ -153,9 +158,28 @@ export function MayaEditor({
       // Reshape pasted HTML so complex tables (caption/tfoot/colgroup)
       // survive TipTap's parser. See `normalizeTableHtml` for details.
       transformPastedHTML: (html) => normalizeTableHtml(html),
+      // Plain-text paste that is actually Markdown is converted to structured
+      // nodes instead of being stored as a literal text node (which would show
+      // "## " / "**bold**" verbatim in previews). Rich paste carries text/html
+      // and is left to `transformPastedHTML` / the default handler.
+      handlePaste: (_view, event) => {
+        const cb = event.clipboardData;
+        if (!cb) return false;
+        if (cb.getData('text/html')) return false;
+        const text = cb.getData('text/plain');
+        if (!text || !looksLikeMarkdown(text)) return false;
+        const activeEditor = editorRef.current;
+        if (!activeEditor) return false;
+        const html = sanitizeEditorHtml(normalizeTableHtml(markdownToHtml(text)));
+        if (!html) return false;
+        activeEditor.commands.insertContent(html);
+        return true;
+      },
     },
   });
 
+  editorRef.current = editor;
+
   useEditorContent(editor, onChange, { output: effectiveOutput });
 
   const readPayloadFromEditor = useCallback((): string | TiptapDoc | undefined => {

package/src/index.ts

@@ -1,6 +1,7 @@
 export { MayaEditor } from './components/MayaEditor';
 export type { MayaEditorProps } from './components/MayaEditor';
 export { EditorContentHtml } from './components/EditorContentHtml';
+export { EditorContentJson } from './components/EditorContentJson';
 export { EditorToolbar } from './components/EditorToolbar';
 export type { ToolbarLabels } from './components/EditorToolbar';
 
@@ -23,6 +24,7 @@ export { normalizeTableHtml } from './lib/normalizeTableHtml';
 export { splitHtmlIntoBlocks } from './lib/splitHtmlIntoBlocks';
 export type { BlockChunk, BlockChunkType } from './lib/splitHtmlIntoBlocks';
 export { htmlToTiptapDoc } from './lib/htmlToTiptapDoc';
+export { renderTiptapJsonToHtml } from './lib/renderTiptapJson';
 export { buildMayaEditorExtensions } from './lib/editorExtensions';
 export { isEditorReady } from './lib/isEditorReady';
 export {

package/src/lib/looksLikeMarkdown.test.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect } from 'vitest';
+import { looksLikeMarkdown } from './looksLikeMarkdown';
+
+describe('looksLikeMarkdown', () => {
+  it('detects ATX headings', () => {
+    expect(looksLikeMarkdown('## Programa del curso')).toBe(true);
+  });
+
+  it('detects ordered and unordered lists', () => {
+    expect(looksLikeMarkdown('1. **Introducción a Laravel**')).toBe(true);
+    expect(looksLikeMarkdown('- item uno\n- item dos')).toBe(true);
+  });
+
+  it('detects fenced code and blockquotes and tables', () => {
+    expect(looksLikeMarkdown('```\ncode\n```')).toBe(true);
+    expect(looksLikeMarkdown('> cita')).toBe(true);
+    expect(looksLikeMarkdown('| a | b |\n| --- | --- |')).toBe(true);
+  });
+
+  it('does NOT flag intentional pipe text without a delimiter row', () => {
+    expect(looksLikeMarkdown('| Total 1º ASIR | 30 | 1000 | 265')).toBe(false);
+  });
+
+  it('detects inline bold/code/links', () => {
+    expect(looksLikeMarkdown('texto con **negrita** dentro')).toBe(true);
+    expect(looksLikeMarkdown('usa `composer install` aquí')).toBe(true);
+    expect(looksLikeMarkdown('ver [docs](https://x.y)')).toBe(true);
+  });
+
+  it('leaves ordinary prose untouched', () => {
+    expect(looksLikeMarkdown('Esto es un párrafo normal sin formato.')).toBe(false);
+    expect(looksLikeMarkdown('Precio: 5 * 3 = 15')).toBe(false);
+    expect(looksLikeMarkdown('C# y F# son lenguajes')).toBe(false);
+    expect(looksLikeMarkdown('')).toBe(false);
+  });
+});

package/src/lib/looksLikeMarkdown.ts

@@ -0,0 +1,37 @@
+/**
+ * Heuristic: does this plain text contain Markdown syntax worth converting to
+ * structured nodes?
+ *
+ * Used by the editor paste handler (convert pasted Markdown → TipTap nodes
+ * instead of storing it as a literal text node) and mirrored by the backend
+ * data-repair detection. Kept conservative so ordinary prose is NOT rewritten:
+ * a single stray `*` or `#` is ignored; we require a real block marker at the
+ * start of a line or an unambiguous inline pair.
+ */
+
+const BLOCK_PATTERNS: RegExp[] = [
+  /^#{1,6}\s+\S/m, // ATX heading: "## Title"
+  /^\s*[-*+]\s+\S/m, // unordered list item: "- item"
+  /^\s*\d+\.\s+\S/m, // ordered list item: "1. item"
+  /^\s*>\s+\S/m, // blockquote: "> quote"
+  /^```/m, // fenced code block
+  // GFM table: require a delimiter row (|---|), so intentional pipe text like
+  // "| Total | 30 |" (no delimiter) is NOT flagged as markdown.
+  /\|\s*:?-{3,}|-{3,}:?\s*\|/,
+];
+
+const INLINE_PATTERNS: RegExp[] = [
+  /\*\*[^\s*][^*]*\*\*/, // **bold**
+  /__[^\s_][^_]*__/, // __bold__
+  /~~[^\s~][^~]*~~/, // ~~strike~~
+  /`[^`\n]+`/, // `inline code`
+  /\[[^\]]+\]\([^)\s]+\)/, // [text](url)
+];
+
+export function looksLikeMarkdown(text: string): boolean {
+  if (!text || text.length < 2) return false;
+  if (BLOCK_PATTERNS.some((re) => re.test(text))) return true;
+  // Require an inline marker to actually be present; a lone "*" won't match the
+  // paired patterns above, so prose stays untouched.
+  return INLINE_PATTERNS.some((re) => re.test(text));
+}

package/src/lib/markdownIngestion.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Guards the paste/ingestion contract used by MayaEditor's `handlePaste`:
+ * Markdown text → HTML (markdownToHtml) → TipTap nodes (htmlToTiptapDoc) must
+ * yield STRUCTURED nodes, never a single literal text node. This is the fix for
+ * the "## " / "**bold**" rendered verbatim bug (a data/ingestion problem).
+ */
+import { describe, it, expect } from 'vitest';
+import { markdownToHtml } from './markdownToHtml';
+import { htmlToTiptapDoc } from './htmlToTiptapDoc';
+import { looksLikeMarkdown } from './looksLikeMarkdown';
+
+function ingest(md: string) {
+  return htmlToTiptapDoc(markdownToHtml(md));
+}
+
+describe('markdown ingestion pipeline', () => {
+  it('turns a heading line into a heading node, not literal "## "', () => {
+    const md = '## Programa del curso';
+    expect(looksLikeMarkdown(md)).toBe(true);
+    const doc = ingest(md);
+    const heading = doc.content.find((n) => n.type === 'heading');
+    expect(heading).toBeTruthy();
+    expect(heading?.attrs?.level).toBe(2);
+    const text = JSON.stringify(doc);
+    expect(text).not.toContain('## Programa');
+  });
+
+  it('turns an ordered list with bold into list + strong nodes', () => {
+    const doc = ingest('1. **Introducción a Laravel 13.**');
+    const list = doc.content.find((n) => n.type === 'orderedList');
+    expect(list).toBeTruthy();
+    const json = JSON.stringify(doc);
+    expect(json).toContain('"bold"');
+    expect(json).not.toContain('**Introducción');
+  });
+
+  it('turns inline bold into a strong node', () => {
+    const doc = ingest('CICLO FORMATIVO DE **NOMBRE_DEL_CICLO**');
+    const json = JSON.stringify(doc);
+    expect(json).toContain('"bold"');
+    expect(json).toContain('NOMBRE_DEL_CICLO');
+    expect(json).not.toContain('**NOMBRE_DEL_CICLO**');
+  });
+});

package/src/lib/markdownToHtml.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { markdownToHtml } from './markdownToHtml';
+
+describe('markdownToHtml', () => {
+  it('bolds **text** and emphasises *text*', () => {
+    expect(markdownToHtml('**b**')).toContain('<strong>b</strong>');
+    expect(markdownToHtml('*i*')).toContain('<em>i</em>');
+  });
+
+  it('does NOT emphasise intra-word underscores (CommonMark)', () => {
+    // Regression: placeholders like NOMBRE_DEL_CICLO must survive intact.
+    const html = markdownToHtml('CICLO DE **NOMBRE_DEL_CICLO**');
+    expect(html).toContain('NOMBRE_DEL_CICLO');
+    expect(html).not.toContain('<em>DEL</em>');
+    expect(html).toContain('<strong>NOMBRE_DEL_CICLO</strong>');
+  });
+
+  it('still emphasises standalone _word_', () => {
+    expect(markdownToHtml('hola _mundo_ chau')).toContain('<em>mundo</em>');
+  });
+
+  it('renders ATX headings', () => {
+    expect(markdownToHtml('## Programa')).toMatch(/<h2[^>]*>Programa<\/h2>/);
+  });
+});

package/src/lib/markdownToHtml.ts

@@ -43,7 +43,10 @@ function applyInline(text: string): string {
   out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
   out = out.replace(/__([^_]+)__/g, '<strong>$1</strong>');
   out = out.replace(/(?<!\*)\*([^*\n]+)\*(?!\*)/g, '<em>$1</em>');
-  out = out.replace(/(?<!_)_([^_\n]+)_(?!_)/g, '<em>$1</em>');
+  // Underscore emphasis must not fire intra-word (CommonMark): `a_b_c` stays
+  // literal, so placeholders like `NOMBRE_DEL_CICLO` survive. Require a
+  // non-word boundary on both sides.
+  out = out.replace(/(?<![\w_])_([^_\n]+?)_(?![\w_])/g, '<em>$1</em>');
   // Strikethrough.
   out = out.replace(/~~([^~]+)~~/g, '<s>$1</s>');
   // Links — only http/https/mailto/tel; reject `javascript:` etc.

package/src/lib/renderTiptapJson.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { renderTiptapJsonToHtml } from './renderTiptapJson';
+import type { TiptapDoc } from '../types';
+
+describe('renderTiptapJsonToHtml', () => {
+  it('renders a wrapped doc', () => {
+    const doc: TiptapDoc = {
+      type: 'doc',
+      content: [
+        { type: 'paragraph', content: [{ type: 'text', text: 'hola' }] },
+      ],
+    };
+    const html = renderTiptapJsonToHtml(doc);
+    expect(html).toContain('<p');
+    expect(html).toContain('hola');
+  });
+
+  it('accepts a bare content array (the shape MayaEditor emits)', () => {
+    const html = renderTiptapJsonToHtml([
+      { type: 'heading', attrs: { level: 2 }, content: [{ type: 'text', text: 'Sección' }] },
+    ]);
+    expect(html).toMatch(/<h2[^>]*>.*Sección.*<\/h2>/s);
+  });
+
+  it('renders bold marks as <strong>', () => {
+    const html = renderTiptapJsonToHtml([
+      {
+        type: 'paragraph',
+        content: [
+          { type: 'text', text: 'plain ' },
+          { type: 'text', text: 'bold', marks: [{ type: 'bold' }] },
+        ],
+      },
+    ]);
+    expect(html).toMatch(/<strong[^>]*>bold<\/strong>/);
+  });
+
+  it('renders a code block without interpreting markdown inside it', () => {
+    const html = renderTiptapJsonToHtml([
+      { type: 'codeBlock', content: [{ type: 'text', text: '## not a heading' }] },
+    ]);
+    expect(html).toContain('<pre');
+    expect(html).toContain('## not a heading');
+  });
+
+  it('does NOT turn literal markdown text into formatting (data, not render)', () => {
+    // Regression guard: markdown stored as plain text must render literally —
+    // this is why the fix lives at ingestion, not in the renderer.
+    const html = renderTiptapJsonToHtml([
+      { type: 'paragraph', content: [{ type: 'text', text: '## Programa **negrita**' }] },
+    ]);
+    expect(html).toContain('## Programa **negrita**');
+    expect(html).not.toContain('<h2');
+    expect(html).not.toContain('<strong>');
+  });
+
+  it('renders a table', () => {
+    const html = renderTiptapJsonToHtml([
+      {
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [
+              { type: 'tableHeader', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }] },
+              { type: 'tableCell', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'B' }] }] },
+            ],
+          },
+        ],
+      },
+    ]);
+    expect(html).toContain('<table');
+    expect(html).toContain('A');
+    expect(html).toContain('B');
+  });
+
+  it('returns empty string for null/empty content', () => {
+    expect(renderTiptapJsonToHtml(null)).toBe('');
+    expect(renderTiptapJsonToHtml([])).toBe('');
+    expect(renderTiptapJsonToHtml(undefined)).toBe('');
+  });
+});

package/src/lib/renderTiptapJson.ts

@@ -0,0 +1,72 @@
+/**
+ * Render a stored TipTap/ProseMirror JSON document to an HTML string using
+ * TipTap's official static renderer.
+ *
+ * This replaces hand-rolled JSON→HTML walkers (which drift from the live
+ * editor and from the server-side `TiptapHtmlRenderer.php`). The static
+ * renderer builds the schema from the canonical extension set and runs each
+ * extension's `renderHTML`, so custom nodes (AlertBlock, IframeBlock, …) and
+ * marks render exactly as the editor defines them — a single source of truth
+ * on the JS side.
+ *
+ * The returned HTML is NOT sanitised; pass it through `EditorContentHtml`
+ * (DOMPurify) or use the `EditorContentJson` component for read-only views.
+ *
+ * Accepts both shapes persisted by the platform:
+ *  - a wrapped doc `{ type: 'doc', content: [...] }`
+ *  - a bare content array (`MayaEditor` emits `onChange(doc.content)`)
+ *
+ * Static-renderer caveats (per TipTap docs): no editor instance is created, so
+ * `addProseMirrorPlugins`/`onCreate`/transaction hooks do not run, and the
+ * output can differ slightly from the live editor for nodeView-backed nodes.
+ */
+import { renderToHTMLString } from '@tiptap/static-renderer';
+import type { Extensions } from '@tiptap/core';
+
+import { buildMayaEditorExtensions } from './editorExtensions';
+import type { TiptapDoc, TiptapNode } from '../types';
+
+function looksLikeTiptapDoc(value: unknown): value is TiptapDoc {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    (value as { type?: unknown }).type === 'doc' &&
+    Array.isArray((value as { content?: unknown }).content)
+  );
+}
+
+function looksLikeTiptapContentArray(value: unknown): value is TiptapNode[] {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    value.every((n) => !!n && typeof n === 'object')
+  );
+}
+
+/** Normalise the accepted input shapes to a wrapped doc, or `null` if empty. */
+function toDoc(content: unknown): TiptapDoc | null {
+  if (content == null) return null;
+  if (looksLikeTiptapDoc(content)) return content;
+  if (looksLikeTiptapContentArray(content)) {
+    return { type: 'doc', content };
+  }
+  return null;
+}
+
+export function renderTiptapJsonToHtml(
+  content: TiptapDoc | TiptapNode[] | unknown,
+  extensions?: Extensions,
+): string {
+  const doc = toDoc(content);
+  if (!doc) return '';
+
+  try {
+    return renderToHTMLString({
+      content: doc,
+      extensions: extensions ?? buildMayaEditorExtensions('full'),
+    });
+  } catch {
+    return '';
+  }
+}

package/src/lib/tiptapContentSemantics.ts

@@ -14,7 +14,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 }
 
 function asNode(value: unknown): TiptapNode | null {
-  return isRecord(value) && typeof value.type === 'string' ? (value as TiptapNode) : null;
+  return isRecord(value) && typeof value.type === 'string' ? (value as unknown as TiptapNode) : null;
 }
 
 function inlineTextLength(nodes: unknown): number {

package/src/mammoth-browser.d.ts

@@ -0,0 +1,3 @@
+// mammoth ships no types for its browser entrypoint; it's imported dynamically
+// and immediately cast to a narrow shape in docxToHtml.ts.
+declare module 'mammoth/mammoth.browser.js';

package/src/parity/fingerprint.ts

@@ -0,0 +1,75 @@
+/**
+ * Semantic fingerprint of rendered editor HTML, used by the renderer parity
+ * oracle. MUST stay logically identical to the PHP version in
+ * `shared-editor-laravel/tests/Support/Fingerprint.php`.
+ *
+ * Captures content + structure (what must agree between the CSR static renderer
+ * and the server-side `TiptapHtmlRenderer`), deliberately ignoring cosmetic
+ * markup (wrappers, data-* attributes, inline-style formatting).
+ */
+export interface HtmlFingerprint {
+  text: string;
+  headings: number[];
+  links: string[];
+  images: string[];
+  strong: number;
+  em: number;
+  u: number;
+  s: number;
+  code: number;
+  ul: number;
+  ol: number;
+  li: number;
+  pre: number;
+  blockquote: number;
+  hr: number;
+  table: number;
+  tr: number;
+  th: number;
+  td: number;
+  aside: number;
+  checkbox: number;
+}
+
+export function fingerprintHtml(html: string): HtmlFingerprint {
+  const doc = new DOMParser().parseFromString(`<div id="__root">${html}</div>`, 'text/html');
+  const root = doc.getElementById('__root');
+  if (!root) {
+    throw new Error('fingerprintHtml: could not parse HTML');
+  }
+
+  const count = (sel: string): number => root.querySelectorAll(sel).length;
+  const attrs = (sel: string, attr: string): string[] =>
+    Array.from(root.querySelectorAll(sel))
+      .map((el) => el.getAttribute(attr) ?? '')
+      .sort();
+
+  return {
+    // Whitespace removed entirely: inter-element spacing (e.g. the space PHP
+    // emits after a task checkbox, or block concatenation) is cosmetic and must
+    // not break parity — only the sequence of visible characters matters.
+    text: (root.textContent ?? '').replace(/\s+/g, ''),
+    headings: Array.from(root.querySelectorAll('h1,h2,h3,h4,h5,h6')).map((h) =>
+      Number(h.tagName.charAt(1)),
+    ),
+    links: attrs('a[href]', 'href'),
+    images: attrs('img[src]', 'src'),
+    strong: count('strong'),
+    em: count('em'),
+    u: count('u'),
+    s: count('s'),
+    code: count('code'),
+    ul: count('ul'),
+    ol: count('ol'),
+    li: count('li'),
+    pre: count('pre'),
+    blockquote: count('blockquote'),
+    hr: count('hr'),
+    table: count('table'),
+    tr: count('tr'),
+    th: count('th'),
+    td: count('td'),
+    aside: count('aside'),
+    checkbox: count('input[type="checkbox"]'),
+  };
+}

package/src/parity/parity.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Parity oracle (JS side).
+ *
+ * Renders shared TipTap fixtures via the static renderer and computes a
+ * SEMANTIC fingerprint (visible text + structural counts + headings/links/
+ * images). The committed `fingerprints.json` is the parity contract; the PHP
+ * test (`TiptapRendererParityTest`) asserts `TiptapHtmlRenderer` produces the
+ * SAME fingerprint. Cosmetic differences (colgroup, data-*, <mark> vs <span>,
+ * target/rel, inline-style spacing) are intentionally ignored — only content
+ * and structure must agree, since CSR previews and server PDFs can style
+ * differently.
+ *
+ * Regenerate the contract after intentional changes:
+ *   UPDATE_FP=1 pnpm vitest run src/parity/parity.test.ts
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { renderTiptapJsonToHtml } from '../lib/renderTiptapJson';
+import { fingerprintHtml } from './fingerprint';
+
+const FIXTURES_DIR = resolve(
+  process.cwd(),
+  '../../php/shared-editor-laravel/tests/fixtures/tiptap',
+);
+const fixtures = JSON.parse(
+  readFileSync(resolve(FIXTURES_DIR, 'fixtures.json'), 'utf8'),
+) as Record<string, unknown>;
+const fpPath = resolve(FIXTURES_DIR, 'fingerprints.json');
+
+describe('renderer parity (JS / static-renderer)', () => {
+  if (process.env.UPDATE_FP) {
+    it('regenerates the fingerprint contract', () => {
+      const out: Record<string, unknown> = {};
+      for (const [name, doc] of Object.entries(fixtures)) {
+        out[name] = fingerprintHtml(renderTiptapJsonToHtml(doc));
+      }
+      writeFileSync(fpPath, `${JSON.stringify(out, null, 2)}\n`);
+      expect(Object.keys(out).length).toBe(Object.keys(fixtures).length);
+    });
+    return;
+  }
+
+  const expected = JSON.parse(readFileSync(fpPath, 'utf8')) as Record<string, unknown>;
+
+  for (const [name, doc] of Object.entries(fixtures)) {
+    it(`fixture "${name}" matches the contract`, () => {
+      expect(fingerprintHtml(renderTiptapJsonToHtml(doc))).toEqual(expected[name]);
+    });
+  }
+});