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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ceedcv-maya/shared-editor-react",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/components/MayaEditor.tsx

@@ -1,8 +1,10 @@
-import { 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';
 
 import { buildMayaEditorExtensions } from '../lib/editorExtensions';
+import { normalizeTiptapDocPayload } from '../lib/tiptapContentSemantics';
+import { isEditorReady } from '../lib/isEditorReady';
 import { useEditorContent, type EditorOutput } from '../hooks/useEditorContent';
 import { sanitizeEditorHtml } from '../lib/dompurifyConfig';
 import { markdownToHtml } from '../lib/markdownToHtml';
@@ -28,6 +30,16 @@ export interface MayaEditorProps {
   mode?: EditorMode;
   /** Debounced change callback (300ms). Payload depends on `output`. */
   onChange?: (payload: string | TiptapDoc) => void;
+  /**
+   * 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?: (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:[…]}`,
@@ -94,6 +106,8 @@ export function MayaEditor({
   onCreateComment,
   onExportDocx,
   commentsById,
+  onFlush,
+  editorFlushRef,
 }: MayaEditorProps) {
   const effectiveOutput: EditorOutput = output ?? (mode === 'full' ? 'json' : 'html');
   const [isFullscreen, setIsFullscreen] = useState(false);
@@ -115,6 +129,15 @@ export function MayaEditor({
   const [viewReady, setViewReady] = useState(false);
   const fileInputRef = useRef<HTMLInputElement | null>(null);
   const docxInputRef = useRef<HTMLInputElement | null>(null);
+  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]);
 
@@ -135,26 +158,93 @@ export function MayaEditor({
 
   useEditorContent(editor, onChange, { output: effectiveOutput });
 
+  const readPayloadFromEditor = useCallback((): string | TiptapDoc | undefined => {
+    if (!editor) return undefined;
+    const rawPayload =
+      effectiveOutput === 'json'
+        ? (editor.getJSON() as TiptapDoc)
+        : editor.getHTML();
+    return effectiveOutput === 'json'
+      ? normalizeTiptapDocPayload(rawPayload)
+      : rawPayload;
+  }, [editor, effectiveOutput]);
+
+  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);
   }, [editor, onEditorReady]);
 
   useEffect(() => {
+    if (!editor || !onFlush) return;
+    const onDestroy = () => {
+      void requestFlush();
+    };
+    editor.on('destroy', onDestroy);
+    return () => {
+      editor.off('destroy', onDestroy);
+    };
+  }, [editor, onFlush, requestFlush]);
+
+  useEffect(() => {
+    setViewReady(false);
     if (!editor) return;
-    const bump = () => setSelectionVersion((v) => v + 1);
+
+    const bump = () => {
+      if (!isEditorReady(editor)) return;
+      setSelectionVersion((v) => v + 1);
+    };
     const markReady = () => setViewReady(true);
+    const markNotReady = () => setViewReady(false);
+
     editor.on('selectionUpdate', bump);
     editor.on('transaction', bump);
     editor.on('create', markReady);
-    // The editor may have already fired `create` before we got here
-    // (useEditor sometimes returns an instance that's already mounted).
+    editor.on('destroy', markNotReady);
+
     try {
-      if (editor.view && editor.view.dom) setViewReady(true);
-    } catch { /* view not ready yet — markReady will fire it */ }
+      if (editor.view?.dom) setViewReady(true);
+    } catch {
+      /* view not ready yet — markReady will fire on create */
+    }
+
     return () => {
       editor.off('selectionUpdate', bump);
       editor.off('transaction', bump);
       editor.off('create', markReady);
+      editor.off('destroy', markNotReady);
+      setViewReady(false);
     };
   }, [editor]);
 
@@ -214,6 +304,8 @@ export function MayaEditor({
 
   if (!editor) return null;
 
+  const editorReady = viewReady && isEditorReady(editor);
+
   const handlePickImage = async (file: File) => {
     if (!uploadFile) return;
     try {
@@ -250,7 +342,8 @@ export function MayaEditor({
       .run();
   };
 
-  const enterSource = (target: 'html' | 'markdown') => {
+  const enterSource = async (target: 'html' | 'markdown') => {
+    syncContentToParent();
     const currentHtml = editor.getHTML();
     const text = target === 'html' ? currentHtml : htmlToMarkdown(currentHtml);
     setSourceText(text);
@@ -279,7 +372,7 @@ export function MayaEditor({
       const html = sanitizeEditorHtml(markdownToHtml(sourceText));
       setSourceText(html);
       setViewMode('html');
-    } else enterSource('html');
+    } else void enterSource('html');
   };
 
   const toggleMarkdown = () => {
@@ -288,13 +381,21 @@ export function MayaEditor({
       const md = htmlToMarkdown(sourceText);
       setSourceText(md);
       setViewMode('markdown');
-    } else enterSource('markdown');
+    } else void enterSource('markdown');
   };
 
   return (
     <div
+      ref={wrapperRef}
       className={`maya-editor-wrapper${isFullscreen ? ' is-fullscreen' : ''}${isDark ? ' is-dark' : ''}`}
+      onBlur={(e) => {
+        if (!onFlush) return;
+        const next = e.relatedTarget as Node | null;
+        if (next && wrapperRef.current?.contains(next)) return;
+        void requestFlush();
+      }}
     >
+      {editorReady && (
       <EditorToolbar
         editor={editor}
         mode={mode}
@@ -312,7 +413,8 @@ export function MayaEditor({
         onToggleFind={mode === 'full' ? () => setFindOpen((v) => !v) : undefined}
         labels={toolbarLabels}
       />
-      {mode === 'full' && (
+      )}
+      {mode === 'full' && editorReady && (
         <FindReplaceBar
           editor={editor}
           open={findOpen}

package/src/hooks/useEditorContent.ts

@@ -1,6 +1,11 @@
 import { useEffect, useRef } from 'react';
 import type { Editor } from '@tiptap/react';
 import type { TiptapDoc } from '../types';
+import {
+  canonicalTiptapContentJson,
+  isSemanticallyEmptyEditorHtml,
+  normalizeTiptapDocPayload,
+} from '../lib/tiptapContentSemantics';
 
 export type EditorOutput = 'html' | 'json';
 
@@ -24,16 +29,38 @@ export function useEditorContent(
   const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const handlerRef = useRef(onChange);
   handlerRef.current = onChange;
+  const lastEmittedRef = useRef<string | null>(null);
 
   useEffect(() => {
     if (!editor) return;
+    lastEmittedRef.current = null;
 
     const handleUpdate = () => {
       if (timeoutRef.current) clearTimeout(timeoutRef.current);
       timeoutRef.current = setTimeout(() => {
-        const payload = output === 'json'
+        const rawPayload = output === 'json'
           ? (editor.getJSON() as TiptapDoc)
           : editor.getHTML();
+        const payload = output === 'json'
+          ? normalizeTiptapDocPayload(rawPayload)
+          : rawPayload;
+
+        const fingerprint = output === 'json'
+          ? canonicalTiptapContentJson((payload as TiptapDoc).content)
+          : payload;
+
+        if (typeof fingerprint === 'string' && fingerprint === lastEmittedRef.current) {
+          return;
+        }
+
+        if (output === 'html' && typeof payload === 'string' && isSemanticallyEmptyEditorHtml(payload)) {
+          if (lastEmittedRef.current === '') return;
+          lastEmittedRef.current = '';
+          handlerRef.current?.(payload);
+          return;
+        }
+
+        lastEmittedRef.current = typeof fingerprint === 'string' ? fingerprint : null;
         handlerRef.current?.(payload);
       }, delayMs);
     };

package/src/index.ts

@@ -24,6 +24,18 @@ export { splitHtmlIntoBlocks } from './lib/splitHtmlIntoBlocks';
 export type { BlockChunk, BlockChunkType } from './lib/splitHtmlIntoBlocks';
 export { htmlToTiptapDoc } from './lib/htmlToTiptapDoc';
 export { buildMayaEditorExtensions } from './lib/editorExtensions';
+export { isEditorReady } from './lib/isEditorReady';
+export {
+  canonicalTiptapContentJson,
+  htmlVisibleTextLength,
+  isEmptyTiptapBlockNode,
+  isSemanticallyEmptyEditorHtml,
+  isSemanticallyEmptyTiptapContent,
+  normalizeTiptapContentForCompare,
+  normalizeTiptapContentForPersistence,
+  normalizeTiptapDocPayload,
+  tiptapContentEquals,
+} from './lib/tiptapContentSemantics';
 export { docxToHtml, docxToHtmlResult } from './lib/docxToHtml';
 export type { DocxConversionMessage, DocxConversionResult } from './lib/docxToHtml';
 export { SourceInputDialog } from './components/SourceInputDialog';

package/src/lib/isEditorReady.ts

@@ -0,0 +1,13 @@
+import type { Editor } from '@tiptap/react';
+
+/**
+ * TipTap puede exponer una instancia con `commandManager === null` tras destroy
+ * o antes del evento `create`. Solo la UI que invoca comandos debe usar esto.
+ */
+export function isEditorReady(editor: Editor | null | undefined): editor is Editor {
+  if (!editor) {
+    return false;
+  }
+
+  return !editor.isDestroyed;
+}

package/src/lib/tiptapContentSemantics.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect } from 'vitest';
+import {
+  canonicalTiptapContentJson,
+  isSemanticallyEmptyTiptapContent,
+  normalizeTiptapContentForCompare,
+  normalizeTiptapContentForPersistence,
+  tiptapContentEquals,
+} from './tiptapContentSemantics';
+
+describe('tiptapContentSemantics', () => {
+  it('treats a lone empty paragraph as semantically empty', () => {
+    const empty = [{ type: 'paragraph', content: [] }];
+    expect(isSemanticallyEmptyTiptapContent(empty)).toBe(true);
+    expect(normalizeTiptapContentForCompare(empty)).toEqual([]);
+  });
+
+  it('strips trailing empty paragraph so phantom TipTap nodes do not differ', () => {
+    const withText = [{ type: 'paragraph', content: [{ type: 'text', text: 'Hola' }] }];
+    const withPhantom = [
+      ...withText,
+      { type: 'paragraph', content: [] },
+    ];
+    expect(tiptapContentEquals(withText, withPhantom)).toBe(true);
+    expect(canonicalTiptapContentJson(withPhantom)).toBe(canonicalTiptapContentJson(withText));
+  });
+
+  it('detects real edits after normalization', () => {
+    const a = [{ type: 'paragraph', content: [{ type: 'text', text: 'A' }] }];
+    const b = [{ type: 'paragraph', content: [{ type: 'text', text: 'B' }] }];
+    expect(tiptapContentEquals(a, b)).toBe(false);
+  });
+
+  it('keeps non-empty images as filled', () => {
+    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

@@ -0,0 +1,266 @@
+import type { TiptapDoc, TiptapNode } from '../types';
+
+const MEANINGFUL_BLOCK_TYPES = new Set([
+  'image',
+  'table',
+  'iframeBlock',
+  'alertBlock',
+  'horizontalRule',
+  'codeBlock',
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function asNode(value: unknown): TiptapNode | null {
+  return isRecord(value) && typeof value.type === 'string' ? (value as TiptapNode) : null;
+}
+
+function inlineTextLength(nodes: unknown): number {
+  if (!Array.isArray(nodes)) return 0;
+
+  let length = 0;
+  for (const raw of nodes) {
+    const node = asNode(raw);
+    if (!node) continue;
+    if (node.type === 'text' && typeof node.text === 'string') {
+      length += node.text.replace(/\u00a0/g, ' ').trim().length;
+    } else if (node.type === 'hardBreak') {
+      continue;
+    } else if (Array.isArray(node.content)) {
+      length += inlineTextLength(node.content);
+    }
+  }
+
+  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);
+  if (!n?.type) return true;
+
+  if (MEANINGFUL_BLOCK_TYPES.has(n.type)) {
+    if (n.type === 'horizontalRule') return false;
+    if (n.type === 'image') {
+      return !String(n.attrs?.src ?? '').trim();
+    }
+    if (n.type === 'codeBlock') {
+      return inlineTextLength(n.content ?? []) === 0;
+    }
+    return false;
+  }
+
+  if (n.type === 'bulletList' || n.type === 'orderedList' || n.type === 'taskList') {
+    const items = Array.isArray(n.content) ? n.content : [];
+    return items.length === 0 || items.every((item) => isEmptyTiptapBlockNode(item));
+  }
+
+  if (n.type === 'listItem' || n.type === 'taskItem') {
+    const inner = Array.isArray(n.content) ? n.content : [];
+    return inner.length === 0 || inner.every((child) => isEmptyTiptapBlockNode(child));
+  }
+
+  if (n.type === 'blockquote') {
+    const inner = Array.isArray(n.content) ? n.content : [];
+    return inner.length === 0 || inner.every((child) => isEmptyTiptapBlockNode(child));
+  }
+
+  // paragraph, heading, legacy BlockNote blocks, etc.
+  return !blockChildrenHaveMeaningfulContent(n.content ?? []);
+}
+
+function toContentArray(value: unknown): unknown[] {
+  if (value == null) return [];
+  if (Array.isArray(value)) return value;
+  if (isRecord(value) && value.type === 'doc' && Array.isArray(value.content)) {
+    return value.content;
+  }
+  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.
+ * Preserves the full node tree (text, marks, heading levels) for persistence.
+ */
+export function normalizeTiptapContentForPersistence(value: unknown): unknown[] {
+  const nodes = [...toContentArray(value)];
+  while (nodes.length > 0 && isEmptyTiptapBlockNode(nodes[nodes.length - 1])) {
+    nodes.pop();
+  }
+  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: []`).
+ */
+export function isSemanticallyEmptyTiptapContent(value: unknown): boolean {
+  const nodes = normalizeTiptapContentForCompare(value);
+  if (nodes.length === 0) return true;
+  return nodes.every((node) => isEmptyTiptapBlockNode(node));
+}
+
+export function canonicalTiptapContentJson(value: unknown): string {
+  try {
+    return JSON.stringify(normalizeTiptapContentForCompare(value));
+  } catch {
+    return '';
+  }
+}
+
+export function tiptapContentEquals(a: unknown, b: unknown): boolean {
+  return canonicalTiptapContentJson(a) === canonicalTiptapContentJson(b);
+}
+
+/**
+ * Visible character count of editor HTML (ignores tags). Matches logs comment validation.
+ */
+export function htmlVisibleTextLength(html: string): number {
+  const text = html
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .trim();
+  return text.length;
+}
+
+export function isSemanticallyEmptyEditorHtml(html: string): boolean {
+  return htmlVisibleTextLength(html) === 0;
+}
+
+/** Payload shape for MayaEditor `output="json"`. */
+export function normalizeTiptapDocPayload(payload: string | TiptapDoc): string | TiptapDoc {
+  if (typeof payload === 'string') return payload;
+  return {
+    ...payload,
+    content: normalizeTiptapContentForPersistence(payload.content) as TiptapDoc['content'],
+  };
+}