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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceedcv-maya/shared-editor-react",
-  "version": "0.8.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

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, type MutableRefObject } from 'react';
 import { EditorContent, useEditor } from '@tiptap/react';
 import type { Editor } from '@tiptap/react';
 
@@ -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';
@@ -31,10 +32,15 @@ export interface MayaEditorProps {
   /** Debounced change callback (300ms). Payload depends on `output`. */
   onChange?: (payload: string | TiptapDoc) => void;
   /**
-   * Llamado al perder el foco del editor, antes de HTML/Markdown o al destruir
-   * la instancia. El padre suele enlazarlo a `forceSave` del autoguardado.
+   * Llamado tras sincronizar el contenido (blur, cambio de bloque, destroy).
+   * Recibe el payload ya leído del editor; el padre suele enlazarlo a `forceSave`.
    */
-  onFlush?: () => void;
+  onFlush?: (payload?: string | TiptapDoc) => void | Promise<void>;
+  /**
+   * Ref opcional para invocar flush+sync desde fuera (p. ej. antes de cambiar de bloque),
+   * evitando perder el último keystroke por el debounce de `onChange`.
+   */
+  editorFlushRef?: MutableRefObject<(() => void | Promise<void>) | null>;
   /**
    * Output shape: `'html'` (default) emits a sanitisation-ready string;
    * `'json'` emits the full ProseMirror doc `{type:'doc', content:[…]}`,
@@ -102,6 +108,7 @@ export function MayaEditor({
   onExportDocx,
   commentsById,
   onFlush,
+  editorFlushRef,
 }: MayaEditorProps) {
   const effectiveOutput: EditorOutput = output ?? (mode === 'full' ? 'json' : 'html');
   const [isFullscreen, setIsFullscreen] = useState(false);
@@ -126,11 +133,19 @@ export function MayaEditor({
   const wrapperRef = useRef<HTMLDivElement | null>(null);
   const onChangeRef = useRef(onChange);
   const onFlushRef = useRef(onFlush);
+  const viewModeRef = useRef(viewMode);
+  const sourceTextRef = useRef(sourceText);
   onChangeRef.current = onChange;
   onFlushRef.current = onFlush;
+  viewModeRef.current = viewMode;
+  sourceTextRef.current = sourceText;
 
   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 ?? '',
@@ -143,30 +158,73 @@ 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 syncContentToParent = useCallback(() => {
-    if (!editor) return;
-    const handler = onChangeRef.current;
-    if (!handler) return;
+  const readPayloadFromEditor = useCallback((): string | TiptapDoc | undefined => {
+    if (!editor) return undefined;
     const rawPayload =
       effectiveOutput === 'json'
         ? (editor.getJSON() as TiptapDoc)
         : editor.getHTML();
-    const payload =
-      effectiveOutput === 'json'
-        ? normalizeTiptapDocPayload(rawPayload)
-        : rawPayload;
-    handler(payload);
+    return effectiveOutput === 'json'
+      ? normalizeTiptapDocPayload(rawPayload)
+      : rawPayload;
   }, [editor, effectiveOutput]);
 
-  const requestFlush = useCallback(() => {
-    syncContentToParent();
-    onFlushRef.current?.();
-  }, [syncContentToParent]);
+  const syncContentToParent = useCallback((): string | TiptapDoc | undefined => {
+    const payload = readPayloadFromEditor();
+    if (payload === undefined) return undefined;
+    onChangeRef.current?.(payload);
+    return payload;
+  }, [readPayloadFromEditor]);
+
+  const requestFlush = useCallback(async () => {
+    if (!editor) return;
+
+    const mode = viewModeRef.current;
+    if (mode !== 'wysiwyg') {
+      const rawHtml =
+        mode === 'markdown'
+          ? markdownToHtml(sourceTextRef.current)
+          : sourceTextRef.current;
+      const html = sanitizeEditorHtml(normalizeTableHtml(rawHtml));
+      editor.commands.setContent(html, { emitUpdate: false });
+      setViewMode('wysiwyg');
+    }
+
+    const payload = syncContentToParent();
+    await onFlushRef.current?.(payload);
+  }, [editor, syncContentToParent]);
+
+  useEffect(() => {
+    if (!editorFlushRef) return;
+    editorFlushRef.current = requestFlush;
+    return () => {
+      editorFlushRef.current = null;
+    };
+  }, [editorFlushRef, requestFlush]);
 
   useEffect(() => {
     if (editor && onEditorReady) onEditorReady(editor);
@@ -174,7 +232,9 @@ export function MayaEditor({
 
   useEffect(() => {
     if (!editor || !onFlush) return;
-    const onDestroy = () => requestFlush();
+    const onDestroy = () => {
+      void requestFlush();
+    };
     editor.on('destroy', onDestroy);
     return () => {
       editor.off('destroy', onDestroy);
@@ -306,8 +366,8 @@ export function MayaEditor({
       .run();
   };
 
-  const enterSource = (target: 'html' | 'markdown') => {
-    requestFlush();
+  const enterSource = async (target: 'html' | 'markdown') => {
+    syncContentToParent();
     const currentHtml = editor.getHTML();
     const text = target === 'html' ? currentHtml : htmlToMarkdown(currentHtml);
     setSourceText(text);
@@ -336,7 +396,7 @@ export function MayaEditor({
       const html = sanitizeEditorHtml(markdownToHtml(sourceText));
       setSourceText(html);
       setViewMode('html');
-    } else enterSource('html');
+    } else void enterSource('html');
   };
 
   const toggleMarkdown = () => {
@@ -345,7 +405,7 @@ export function MayaEditor({
       const md = htmlToMarkdown(sourceText);
       setSourceText(md);
       setViewMode('markdown');
-    } else enterSource('markdown');
+    } else void enterSource('markdown');
   };
 
   return (
@@ -356,7 +416,7 @@ export function MayaEditor({
         if (!onFlush) return;
         const next = e.relatedTarget as Node | null;
         if (next && wrapperRef.current?.contains(next)) return;
-        requestFlush();
+        void requestFlush();
       }}
     >
       {editorReady && (

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 {
@@ -32,6 +34,7 @@ export {
   isSemanticallyEmptyEditorHtml,
   isSemanticallyEmptyTiptapContent,
   normalizeTiptapContentForCompare,
+  normalizeTiptapContentForPersistence,
   normalizeTiptapDocPayload,
   tiptapContentEquals,
 } from './lib/tiptapContentSemantics';

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.test.ts

@@ -3,6 +3,7 @@ import {
   canonicalTiptapContentJson,
   isSemanticallyEmptyTiptapContent,
   normalizeTiptapContentForCompare,
+  normalizeTiptapContentForPersistence,
   tiptapContentEquals,
 } from './tiptapContentSemantics';
 
@@ -33,4 +34,183 @@ describe('tiptapContentSemantics', () => {
     const nodes = [{ type: 'image', attrs: { src: 'https://example.com/x.png' } }];
     expect(isSemanticallyEmptyTiptapContent(nodes)).toBe(false);
   });
+
+  it('ignores table colwidth attrs added by the editor on open', () => {
+    const fromTemplate = [
+      {
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    const afterEditor = [
+      {
+        type: 'table',
+        content: [
+          {
+            type: 'tableRow',
+            content: [
+              {
+                type: 'tableCell',
+                attrs: { colwidth: [120] },
+                content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+              },
+            ],
+          },
+        ],
+      },
+    ];
+    expect(tiptapContentEquals(fromTemplate, afterEditor)).toBe(true);
+  });
+
+  it('ignores volatile image attrs added by the editor on open', () => {
+    const fromTemplate = [{ type: 'image', attrs: { src: 'https://example.com/x.png', alt: 'Logo' } }];
+    const afterEditor = [{
+      type: 'image',
+      attrs: {
+        src: 'https://example.com/x.png',
+        alt: 'Logo',
+        width: 400,
+        height: 200,
+        class: 'ProseMirror-selectednode',
+      },
+    }];
+    expect(tiptapContentEquals(fromTemplate, afterEditor)).toBe(true);
+  });
+
+  it('treats tableHeader cells as tableCell for template parity', () => {
+    const fromTemplate = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableCell',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+        }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableHeader',
+          attrs: { colwidth: [90] },
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }],
+        }],
+      }],
+    }];
+    expect(tiptapContentEquals(fromTemplate, afterEditor)).toBe(true);
+  });
+
+  it('does not treat paragraph with nested image as semantically empty', () => {
+    const nodes = [{
+      type: 'paragraph',
+      content: [{ type: 'image', attrs: { src: 'https://example.com/x.png' } }],
+    }];
+    expect(isSemanticallyEmptyTiptapContent(nodes)).toBe(false);
+  });
+
+  it('preserves heading level and text for persistence', () => {
+    const heading = [{
+      type: 'heading',
+      attrs: { level: 1 },
+      content: [{ type: 'text', text: 'Título H1' }],
+    }];
+    expect(normalizeTiptapContentForPersistence(heading)).toEqual(heading);
+  });
+
+  it('compare normalization keeps text on inline nodes', () => {
+    const nodes = [{
+      type: 'heading',
+      attrs: { level: 1 },
+      content: [{ type: 'text', text: 'Hola' }],
+    }];
+    expect(normalizeTiptapContentForCompare(nodes)).toEqual(nodes);
+  });
+
+  it('ignores phantom empty paragraphs inside table cells', () => {
+    const template = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableCell',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'c' }] }],
+        }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'table',
+      content: [{
+        type: 'tableRow',
+        content: [{
+          type: 'tableCell',
+          attrs: { colwidth: [100] },
+          content: [
+            { type: 'paragraph', content: [{ type: 'text', text: 'c' }] },
+            { type: 'paragraph', content: [] },
+          ],
+        }],
+      }],
+    }];
+    expect(tiptapContentEquals(template, afterEditor)).toBe(true);
+  });
+
+  it('ignores empty list items added by pressing Enter without content', () => {
+    const template = [{
+      type: 'bulletList',
+      content: [{
+        type: 'listItem',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'bulletList',
+      content: [
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [] }],
+        },
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+        },
+      ],
+    }];
+    expect(tiptapContentEquals(template, afterEditor)).toBe(true);
+  });
+
+  it('ignores trailing empty list item at end of list', () => {
+    const template = [{
+      type: 'bulletList',
+      content: [{
+        type: 'listItem',
+        content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+      }],
+    }];
+    const afterEditor = [{
+      type: 'bulletList',
+      content: [
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Uno' }] }],
+        },
+        {
+          type: 'listItem',
+          content: [{ type: 'paragraph', content: [] }],
+        },
+      ],
+    }];
+    expect(tiptapContentEquals(template, afterEditor)).toBe(true);
+  });
 });

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 {
@@ -36,6 +36,29 @@ function inlineTextLength(nodes: unknown): number {
   return length;
 }
 
+/** True when inline/block children carry text or non-empty media (e.g. image in paragraph). */
+function blockChildrenHaveMeaningfulContent(nodes: unknown): boolean {
+  if (!Array.isArray(nodes)) return false;
+
+  for (const raw of nodes) {
+    const node = asNode(raw);
+    if (!node) continue;
+    if (node.type === 'text' && typeof node.text === 'string') {
+      if (node.text.replace(/\u00a0/g, ' ').trim().length > 0) return true;
+      continue;
+    }
+    if (node.type === 'hardBreak') continue;
+    if (MEANINGFUL_BLOCK_TYPES.has(node.type) && !isEmptyTiptapBlockNode(node)) {
+      return true;
+    }
+    if (Array.isArray(node.content) && blockChildrenHaveMeaningfulContent(node.content)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /** True for TipTap/BlockNote blocks with no visible text and no embedded media. */
 export function isEmptyTiptapBlockNode(node: unknown): boolean {
   const n = asNode(node);
@@ -68,7 +91,7 @@ export function isEmptyTiptapBlockNode(node: unknown): boolean {
   }
 
   // paragraph, heading, legacy BlockNote blocks, etc.
-  return inlineTextLength(n.content ?? []) === 0;
+  return !blockChildrenHaveMeaningfulContent(n.content ?? []);
 }
 
 function toContentArray(value: unknown): unknown[] {
@@ -80,11 +103,101 @@ function toContentArray(value: unknown): unknown[] {
   return [];
 }
 
+/** Atributos que TipTap añade al abrir/guardar y no representan edición del usuario. */
+const VOLATILE_NODE_ATTR_KEYS = new Set([
+  'colwidth',
+  'columnSizing',
+  'data-colwidth',
+  'width',
+  'height',
+  'style',
+  'class',
+  'title',
+]);
+
+const IMAGE_COMPARE_ATTR_KEYS = ['src', 'alt'] as const;
+
+function stripTrailingEmptyBlocks(nodes: unknown[]): unknown[] {
+  const out = JSON.parse(JSON.stringify(nodes));
+
+  return out;
+}
+
+function canonicalizeNodeAttrs(type: string, rawAttrs: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(rawAttrs)) return undefined;
+
+  let attrs: Record<string, unknown> = { ...rawAttrs };
+  if (type === 'image') {
+    const picked: Record<string, unknown> = {};
+    for (const key of IMAGE_COMPARE_ATTR_KEYS) {
+      const value = attrs[key];
+      if (value != null && String(value).trim() !== '') {
+        picked[key] = value;
+      }
+    }
+    return Object.keys(picked).length > 0 ? picked : undefined;
+  }
+
+  for (const key of VOLATILE_NODE_ATTR_KEYS) {
+    delete attrs[key];
+  }
+  if (type === 'tableCell' && attrs.colspan === 1) delete attrs.colspan;
+  if (type === 'tableCell' && attrs.rowspan === 1) delete attrs.rowspan;
+
+  return Object.keys(attrs).length > 0 ? attrs : undefined;
+}
+
+/** Canonicalize and drop phantom empty nodes at every depth (cells, list items, etc.). */
+function canonicalizeNodeForCompare(node: unknown): unknown | null {
+  const n = asNode(node);
+  if (!n?.type) return null;
+
+  if (n.type === 'text') {
+    const text = typeof n.text === 'string' ? n.text : '';
+    const hasMarks = Array.isArray(n.marks) && n.marks.length > 0;
+    if (text.replace(/\u00a0/g, ' ').trim() === '' && !hasMarks) {
+      return null;
+    }
+    return {
+      type: 'text',
+      ...(typeof n.text === 'string' ? { text: n.text } : {}),
+      ...(hasMarks ? { marks: n.marks } : {}),
+    };
+  }
+
+  // TipTap may emit tableHeader where the template stored tableCell.
+  const rawType = n.type;
+  const type = rawType === 'tableHeader' ? 'tableCell' : rawType;
+  const attrs = canonicalizeNodeAttrs(type, n.attrs);
+
+  let content: unknown[] | undefined;
+  if (Array.isArray(n.content)) {
+    let children = n.content
+      .map((child) => canonicalizeNodeForCompare(child))
+      .filter((child): child is unknown => child != null);
+
+    if (rawType === 'bulletList' || rawType === 'orderedList' || rawType === 'taskList') {
+      children = children.filter((child) => !isEmptyTiptapBlockNode(child));
+    }
+      
+    children = stripTrailingEmptyBlocks(children);
+    content = children.length > 0 ? children : undefined;
+  }
+
+  const out = {
+    type,
+    ...(attrs ? { attrs } : {}),
+    ...(content !== undefined ? { content } : {}),
+  };
+
+  return isEmptyTiptapBlockNode(out) ? null : out;
+}
+
 /**
  * Strips trailing empty paragraphs TipTap adds for cursor placement.
- * Returns a new array; does not mutate the input.
+ * Preserves the full node tree (text, marks, heading levels) for persistence.
  */
-export function normalizeTiptapContentForCompare(value: unknown): unknown[] {
+export function normalizeTiptapContentForPersistence(value: unknown): unknown[] {
   const nodes = [...toContentArray(value)];
   while (nodes.length > 0 && isEmptyTiptapBlockNode(nodes[nodes.length - 1])) {
     nodes.pop();
@@ -92,6 +205,18 @@ export function normalizeTiptapContentForCompare(value: unknown): unknown[] {
   return nodes;
 }
 
+/**
+ * Canonical form for semantic diff/compare (strips volatile attrs, trailing empties).
+ * Returns a new array; does not mutate the input.
+ */
+export function normalizeTiptapContentForCompare(value: unknown): unknown[] {
+  const nodes = toContentArray(value)
+    .map((node) => canonicalizeNodeForCompare(node))
+    .filter((node): node is unknown => node != null);
+
+  return stripTrailingEmptyBlocks(nodes);
+}
+
 /**
  * True when content has no meaningful text or media (e.g. only `<p></p>` / `paragraph: []`).
  */
@@ -136,6 +261,6 @@ export function normalizeTiptapDocPayload(payload: string | TiptapDoc): string |
   if (typeof payload === 'string') return payload;
   return {
     ...payload,
-    content: normalizeTiptapContentForCompare(payload.content) as TiptapDoc['content'],
+    content: normalizeTiptapContentForPersistence(payload.content) as TiptapDoc['content'],
   };
 }

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]);
+    });
+  }
+});