@phuong-tran-redoc/document-engine-core 0.0.41 → 0.1.0

package/package.json

@@ -1,51 +1,55 @@
 {
   "name": "@phuong-tran-redoc/document-engine-core",
-  "version": "0.0.41",
+  "version": "0.1.0",
   "type": "module",
   "license": "MIT",
-  "author": "Duc Phuong (Jack) <tdp99.business@gmail.com>",
+  "author": "Realestatedoc (Redoc)",
+  "contributors": [
+    "Duc Phuong (Jack) <tdp99.business@gmail.com>"
+  ],
   "description": "Framework-agnostic core library for Document Engine",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "https://github.com/phuong-tran-redoc/document-engine"
+    "url": "git+https://github.com/phuong-tran-redoc/document-engine.git"
   },
   "publishConfig": {
     "directory": "../../dist/libs/document-engine-core",
     "access": "public"
   },
   "dependencies": {
-    "tslib": "^2.3.0",
-    "@tiptap/core": "^3.10.5",
-    "@tiptap/extension-blockquote": "^3.10.5",
-    "@tiptap/extension-bold": "^3.10.5",
-    "@tiptap/extension-bubble-menu": "^3.10.5",
-    "@tiptap/extension-code": "^3.10.5",
-    "@tiptap/extension-code-block": "^3.10.5",
-    "@tiptap/extension-document": "^3.10.5",
-    "@tiptap/extension-floating-menu": "^3.10.5",
-    "@tiptap/extension-hard-break": "^3.10.5",
-    "@tiptap/extension-heading": "^3.10.5",
-    "@tiptap/extension-horizontal-rule": "^3.10.5",
-    "@tiptap/extension-image": "^3.10.5",
-    "@tiptap/extension-italic": "^3.10.5",
-    "@tiptap/extension-link": "^3.10.5",
-    "@tiptap/extension-list": "^3.10.5",
-    "@tiptap/extension-paragraph": "^3.10.5",
-    "@tiptap/extension-strike": "^3.10.5",
-    "@tiptap/extension-subscript": "^3.10.5",
-    "@tiptap/extension-superscript": "^3.10.5",
-    "@tiptap/extension-table": "^3.10.5",
-    "@tiptap/extension-text": "^3.10.5",
-    "@tiptap/extension-text-align": "^3.10.5",
-    "@tiptap/extension-text-style": "^3.10.5",
-    "@tiptap/extension-underline": "^3.10.5",
-    "@tiptap/extensions": "^3.10.5",
-    "@tiptap/pm": "^3.10.5"
+    "@tiptap/core": "^3.26.0",
+    "@tiptap/extension-blockquote": "^3.26.0",
+    "@tiptap/extension-bold": "^3.26.0",
+    "@tiptap/extension-bubble-menu": "^3.26.0",
+    "@tiptap/extension-code": "^3.26.0",
+    "@tiptap/extension-code-block": "^3.26.0",
+    "@tiptap/extension-document": "^3.26.0",
+    "@tiptap/extension-floating-menu": "^3.26.0",
+    "@tiptap/extension-hard-break": "^3.26.0",
+    "@tiptap/extension-heading": "^3.26.0",
+    "@tiptap/extension-horizontal-rule": "^3.26.0",
+    "@tiptap/extension-image": "^3.26.0",
+    "@tiptap/extension-italic": "^3.26.0",
+    "@tiptap/extension-link": "^3.26.0",
+    "@tiptap/extension-list": "^3.26.0",
+    "@tiptap/extension-paragraph": "^3.26.0",
+    "@tiptap/extension-strike": "^3.26.0",
+    "@tiptap/extension-subscript": "^3.26.0",
+    "@tiptap/extension-superscript": "^3.26.0",
+    "@tiptap/extension-table": "^3.26.0",
+    "@tiptap/extension-text": "^3.26.0",
+    "@tiptap/extension-text-align": "^3.26.0",
+    "@tiptap/extension-text-style": "^3.26.0",
+    "@tiptap/extension-underline": "^3.26.0",
+    "@tiptap/extensions": "^3.26.0",
+    "@tiptap/html": "^3.26.0",
+    "@tiptap/pm": "^3.26.0",
+    "tslib": "^2.3.0"
   },
   "peerDependencies": {
     "lodash-es": "^4.17.10"
   },
   "module": "./src/index.js"
-}
+}

package/src/extensions/restricted-editing.extension.js

@@ -10,13 +10,13 @@ export const EditableRegion = Node.create({
     parseHTML () {
         return [
             // ----------------------------------------------------------
-            // RULE 1: Standard Tiptap Format (Ưu tiên cao nhất)
+            // RULE 1: Standard Tiptap Format (highest priority)
             // ----------------------------------------------------------
             {
                 tag: 'span[data-editable-region]'
             },
             // ----------------------------------------------------------
-            // RULE 2: CKEditor Format (Ưu tiên thấp nhất)
+            // RULE 2: CKEditor Format (lowest priority)
             // ----------------------------------------------------------
             {
                 tag: 'span.restricted-editing-exception'

package/src/extensions/table-resizing.extension.d.ts

@@ -1,6 +1,6 @@
 import { Extension } from '@tiptap/core';
 /**
  * Extension PercentageColumnResizing
- * * Thay thế logic resize cột mặc định bằng logic dựa trên %.
+ * * Replaces the default column-resize logic with percentage-based logic.
  */
 export declare const PercentageColumnResizing: Extension<any, any>;

package/src/extensions/table-resizing.extension.js

@@ -4,55 +4,55 @@ import { tableNodeTypes } from '@tiptap/pm/tables';
 import { Decoration, DecorationSet } from '@tiptap/pm/view';
 import { getTableDOMFromView } from '../utils';
 /**
- * Hàm xử lý khi di chuột (kéo)
+ * Handler for mouse move (dragging)
  */ function handleMouseMoveEvent(event, dragInfo) {
     if (!dragInfo.isDragging) return;
     event.preventDefault();
     const { startX, tableWidthPx, initialLeftWidth, initialRightWidth, leftColIndex, tablePos, tableNode, view } = dragInfo;
-    // 1. Tính toán delta (pixel)
+    // 1. Compute the delta (pixels)
     const deltaX = event.clientX - startX;
-    // 2. Chuyển delta pixel sang delta percentage
-    // Đây là logic quan trọng nhất
+    // 2. Convert the pixel delta into a percentage delta
+    // This is the most important piece of logic
     const deltaPercent = deltaX / tableWidthPx * 100;
-    // 3. Tính toán width mới
+    // 3. Compute the new widths
     let newLeftWidth = initialLeftWidth + deltaPercent;
     let newRightWidth = initialRightWidth - deltaPercent;
-    // 4. Áp dụng ràng buộc (ví dụ: min-width 5%)
-    const minWidth = 5; // Cấu hình min-width
+    // 4. Apply constraints (e.g. min-width 5%)
+    const minWidth = 5; // min-width configuration
     if (newLeftWidth < minWidth) {
         const diff = minWidth - newLeftWidth;
         newLeftWidth = minWidth;
-        newRightWidth = newRightWidth - diff; // Cột phải bù phần bị thiếu
+        newRightWidth = newRightWidth - diff; // Right column absorbs the shortfall
     } else if (newRightWidth < minWidth) {
         const diff = minWidth - newRightWidth;
         newRightWidth = minWidth;
-        newLeftWidth = newLeftWidth - diff; // Cột trái bù phần bị thiếu
+        newLeftWidth = newLeftWidth - diff; // Left column absorbs the shortfall
     }
-    // Đảm bảo không có cột nào bị âm (nếu kéo quá nhanh)
+    // Make sure no column goes negative (in case of a very fast drag)
     if (newLeftWidth < 0) newLeftWidth = 0;
     if (newRightWidth < 0) newRightWidth = 0;
-    // 5. Tạo mảng colwidths mới
+    // 5. Build the new colwidths array
     const newColWidths = [
         ...tableNode?.attrs?.['colwidths']
     ];
     newColWidths[leftColIndex] = newLeftWidth;
     newColWidths[leftColIndex + 1] = newRightWidth;
-    // 6. Dispatch transaction để cập nhật state
+    // 6. Dispatch a transaction to update the state
     if (tableNode && view) {
         const tr = view.state.tr.setNodeMarkup(tablePos, null, {
             ...tableNode.attrs,
             colwidths: newColWidths
         });
-        // Dùng dispatchTransaction để Tiptap/ProseMirror tự cập nhật UI
+        // Use dispatchTransaction so Tiptap/ProseMirror updates the UI itself
         view.dispatch(tr);
     }
 }
 /**
- * Hàm xử lý khi nhả chuột (kết thúc kéo)
+ * Handler for mouse up (end of drag)
  */ function handleMouseUpEvent(event, dragInfo) {
     if (!dragInfo.isDragging) return;
     event.preventDefault();
-    // Reset trạng thái
+    // Reset the state
     dragInfo = {
         isDragging: false,
         startX: 0,
@@ -67,12 +67,12 @@ import { getTableDOMFromView } from '../utils';
 }
 /**
  * Extension PercentageColumnResizing
- * * Thay thế logic resize cột mặc định bằng logic dựa trên %.
+ * * Replaces the default column-resize logic with percentage-based logic.
  */ export const PercentageColumnResizing = Extension.create({
     name: 'percentageColumnResizing',
     addProseMirrorPlugins () {
-        // Một đối tượng tạm thời để lưu trữ trạng thái kéo-thả
-        // Chúng ta không dùng Plugin State vì nó không cần thiết phải "undo"
+        // A temporary object to hold the drag-and-drop state
+        // We don't use Plugin State because this state never needs to be "undone"
         let dragInfo = {
             isDragging: false,
             startX: 0,
@@ -90,40 +90,40 @@ import { getTableDOMFromView } from '../utils';
                 key: new PluginKey('percentageColumnResizing'),
                 props: {
                     /**
-           * Vẽ các resize handles vào DOM
+           * Draw the resize handles into the DOM
            */ decorations (state) {
                         if (!editorInstance?.isEditable) return;
                         const decorations = [];
                         const { doc } = state;
                         const tableTypes = tableNodeTypes(state.schema);
-                        // Duyệt qua tất cả node trong document
+                        // Walk every node in the document
                         doc.descendants((node, pos)=>{
                             if (node.type.name !== tableTypes.table.name) return;
                             const colwidths = node.attrs['colwidths'];
                             if (!colwidths || colwidths.length === 0) return;
                             let accumulatedWidth = 0;
-                            // Tạo handle cho N-1 cột (không cần cho cột cuối)
+                            // Create a handle for N-1 columns (the last column doesn't need one)
                             for(let i = 0; i < colwidths.length - 1; i++){
                                 accumulatedWidth += colwidths[i] ?? 0;
-                                // Tạo một widget 'div' để làm handle
+                                // Create a 'div' widget to act as the handle
                                 const handle = document.createElement('div');
                                 handle.className = 'pm-col-resizer';
                                 handle.style.left = `calc(${accumulatedWidth}% - 2px)`;
-                                // Lưu vị trí cột để biết đang resize cột nào
+                                // Store the column position so we know which column is being resized
                                 handle.setAttribute('data-col-index', i.toString());
                                 handle.setAttribute('data-table-pos', pos.toString());
-                                // Đặt widget ngay sau thẻ <table> (pos + 1)
+                                // Place the widget right after the <table> tag (pos + 1)
                                 decorations.push(Decoration.widget(pos + 1, handle));
                             }
                         });
                         return DecorationSet.create(doc, decorations);
                     },
                     /**
-           * Xử lý sự kiện mousedown trên handle
+           * Handle the mousedown event on a handle
            */ handleDOMEvents: {
                         mousedown (view, event) {
                             const target = event.target;
-                            // Chỉ kích hoạt khi click vào handle
+                            // Only trigger when clicking on a handle
                             if (!target.classList.contains('pm-col-resizer')) return false;
                             event.preventDefault();
                             const colIndex = parseInt(target.getAttribute('data-col-index') ?? '0', 10);
@@ -134,7 +134,7 @@ import { getTableDOMFromView } from '../utils';
                             // Get table DOM element (handles NodeView wrappers and nested tables)
                             const tableDOM = getTableDOMFromView(view, tablePos);
                             if (!tableDOM) return false;
-                            // Lưu thông tin cần thiết cho việc kéo
+                            // Store the info needed for dragging
                             dragInfo = {
                                 isDragging: true,
                                 startX: event.clientX,
@@ -154,7 +154,7 @@ import { getTableDOMFromView } from '../utils';
                             };
                             window.addEventListener('mousemove', handleMouseMove, true);
                             window.addEventListener('mouseup', handleMouseUp, true);
-                            return true; // Đã xử lý event
+                            return true; // Event handled
                         }
                     }
                 }

package/src/extensions/table-style.extension.d.ts

@@ -36,5 +36,7 @@ declare module '@tiptap/core' {
         };
     }
 }
-export declare const StyledTable: Node<TableOptions, any>;
+export declare const StyledTable: Node<TableOptions & {
+    enableNodeView?: boolean;
+}, any>;
 export declare const StyledTableKit: Extension<TableKitOptions, any>;

package/src/extensions/table-style.extension.js

@@ -168,7 +168,7 @@ export const StyledTable = Table.extend({
                 default: null,
                 renderHTML: (attributes)=>{
                     if (!attributes['colwidths']) {
-                        return {}; // Không có gì để render
+                        return {}; // Nothing to render
                     }
                     return {
                         'data-colwidths': JSON.stringify(attributes['colwidths'])
@@ -198,7 +198,7 @@ export const StyledTable = Table.extend({
     renderHTML ({ node, HTMLAttributes }) {
         const colwidths = node.attrs?.['colwidths'];
         const domNodes = [];
-        // Render <colgroup> nếu có colwidths
+        // Render <colgroup> when colwidths are present
         if (colwidths) {
             const colgroup = [
                 'colgroup',
@@ -214,13 +214,13 @@ export const StyledTable = Table.extend({
             });
             domNodes.push(colgroup);
         }
-        // Thêm <tbody> (0 là 'content hole')
+        // Add <tbody> (0 is the 'content hole')
         domNodes.push([
             'tbody',
             0
         ]);
-        // Merge các HTML attributes (bao gồm cả global attributes)
-        // HTMLAttributes đã được Tiptap merge sẵn từ getRenderedAttributes
+        // Merge the HTML attributes (including global attributes)
+        // HTMLAttributes has already been merged by Tiptap via getRenderedAttributes
         return [
             'table',
             HTMLAttributes,
@@ -257,30 +257,30 @@ export const StyledTable = Table.extend({
                 },
             insertTable: ({ rows, cols, withHeaderRow })=>({ tr, dispatch, editor })=>{
                     const { schema } = editor.state;
-                    // --- BƯỚC 1: Tính toán colWidths ---
+                    // --- STEP 1: Compute colWidths ---
                     const calculatedColWidths = [];
                     const defaultWidth = 100 / cols;
                     for(let i = 0; i < cols; i += 1){
                         calculatedColWidths.push(defaultWidth);
                     }
-                    // Ví dụ: cols = 3 -> calculatedColWidths = [33.33, 33.33, 33.33]
-                    // --- BƯỚC 2: Tạo nội dung bảng (rows, cells) ---
-                    // Chúng ta phải tự xây dựng các node con
+                    // Example: cols = 3 -> calculatedColWidths = [33.33, 33.33, 33.33]
+                    // --- STEP 2: Build the table content (rows, cells) ---
+                    // We have to build the child nodes ourselves
                     const cellType = schema.nodes['tableCell'];
                     const headerType = schema.nodes['tableHeader'];
                     const rowType = schema.nodes['tableRow'];
                     const tableRows = [];
-                    // Hàm trợ giúp tạo 1 cell rỗng
+                    // Helper to create a single empty cell
                     const createEmptyCell = (type)=>{
                         const emptyParagraph = schema.nodes['paragraph'].create();
                         return type.create(null, emptyParagraph);
                     };
-                    // Tạo các hàng
+                    // Create the rows
                     for(let r = 0; r < rows; r += 1){
                         const tableCells = [];
                         for(let c = 0; c < cols; c += 1){
                             let cellNode;
-                            // Nếu là hàng đầu tiên và có 'withHeaderRow'
+                            // If this is the first row and 'withHeaderRow' is set
                             if (r === 0 && withHeaderRow) {
                                 cellNode = createEmptyCell(headerType);
                             } else {
@@ -288,23 +288,23 @@ export const StyledTable = Table.extend({
                             }
                             tableCells.push(cellNode);
                         }
-                        // Thêm hàng mới vào mảng các hàng
+                        // Add the new row to the rows array
                         tableRows.push(rowType.create(null, tableCells));
                     }
-                    // --- BƯỚC 3: Tạo node Table chính VỚI ATTRIBUTE 'colwidths' ---
+                    // --- STEP 3: Create the main Table node WITH the 'colwidths' ATTRIBUTE ---
                     const tableNode = schema.nodes['table'].create({
-                        // Đây là mấu chốt: gán mảng % của chúng ta vào đây
+                        // This is the key part: assign our percentage array here
                         colwidths: calculatedColWidths
-                    }, tableRows // Nội dung (các node 'tableRow')
+                    }, tableRows // Content (the 'tableRow' nodes)
                     );
-                    // --- BƯỚC 4: Dispatch transaction (Original code)---
+                    // --- STEP 4: Dispatch transaction (Original code)---
                     if (dispatch) {
                         const offset = tr.selection.from + 1;
                         tr.replaceSelectionWith(tableNode).scrollIntoView().setSelection(TextSelection.near(tr.doc.resolve(offset)));
                     }
                     return true;
                 },
-            // 2. LỆNH ADDCOLUMNAFTER
+            // 2. ADDCOLUMNAFTER COMMAND
             addColumnAfter: ()=>({ state, dispatch })=>{
                     const $cell = selectionCell(state);
                     if (!$cell) return false;
@@ -334,7 +334,7 @@ export const StyledTable = Table.extend({
                     }
                     return true;
                 },
-            // 3. LỆNH ADDCOLUMNBEFORE
+            // 3. ADDCOLUMNBEFORE COMMAND
             addColumnBefore: ()=>({ state, dispatch })=>{
                     const $cell = selectionCell(state);
                     if (!$cell) return false;
@@ -360,7 +360,7 @@ export const StyledTable = Table.extend({
                     }
                     return true;
                 },
-            // 4. LỆNH DELETECOLUMN
+            // 4. DELETECOLUMN COMMAND
             deleteColumn: ()=>({ state, dispatch })=>{
                     const $cell = selectionCell(state);
                     if (!$cell) return false;
@@ -439,7 +439,7 @@ export const StyledTable = Table.extend({
     addNodeView () {
         const options = this.options;
         if (options.enableNodeView === false) {
-            return undefined;
+            return null;
         }
         // Only use custom NodeView (with handle) when editor is editable
         return (props)=>{

package/src/index.d.ts

@@ -1,5 +1,7 @@
 export * from './constants';
 export * from './extensions';
+export * from './kit';
+export * from './migrations';
 export * from './models';
 export * from './nodes';
 export * from './types';

package/src/index.js

@@ -1,5 +1,7 @@
 export * from './constants';
 export * from './extensions';
+export * from './kit';
+export * from './migrations';
 export * from './models';
 export * from './nodes';
 export * from './types';

package/src/kit/default-extensions.d.ts

@@ -0,0 +1,22 @@
+import type { Extensions } from '@tiptap/core';
+/**
+ * Canonical default extension list for headless (Node-safe) serialization.
+ *
+ * This is the schema half of the editor's runtime kit (`DocumentEngineKit` in
+ * the Angular wrapper): every node, mark, and HTML-affecting attribute the
+ * editor can persist, so {@link generateHTML} can turn stored document JSON back
+ * into HTML without a browser.
+ *
+ * It deliberately omits editing-only plugins (history/undo-redo, drop/gap
+ * cursors, placeholder, character count, list keymaps, trailing node). Those
+ * shape the live editing experience but contribute nothing to serialized
+ * output, and some attach view-level behavior that has no meaning headless.
+ *
+ * Only `renderHTML` is exercised during serialization — node views (which touch
+ * the DOM, e.g. `DynamicField.addNodeView`) are never invoked here, so this list
+ * is safe to import and run in Node.
+ *
+ * Callers needing a different schema (e.g. restricted-editing regions, or a
+ * trimmed set) should pass their own array to {@link generateHTML} instead.
+ */
+export declare const defaultExtensions: Extensions;

package/src/kit/default-extensions.js

@@ -0,0 +1,86 @@
+import Blockquote from '@tiptap/extension-blockquote';
+import Bold from '@tiptap/extension-bold';
+import Code from '@tiptap/extension-code';
+import CodeBlock from '@tiptap/extension-code-block';
+import { Document } from '@tiptap/extension-document';
+import { HardBreak } from '@tiptap/extension-hard-break';
+import { HorizontalRule } from '@tiptap/extension-horizontal-rule';
+import { Image } from '@tiptap/extension-image';
+import Italic from '@tiptap/extension-italic';
+import Link from '@tiptap/extension-link';
+import { BulletList, ListItem } from '@tiptap/extension-list';
+import { Paragraph } from '@tiptap/extension-paragraph';
+import Strike from '@tiptap/extension-strike';
+import { Subscript } from '@tiptap/extension-subscript';
+import { Superscript } from '@tiptap/extension-superscript';
+import { Text } from '@tiptap/extension-text';
+import { TextAlign } from '@tiptap/extension-text-align';
+import { TextStyleKit } from '@tiptap/extension-text-style';
+import Underline from '@tiptap/extension-underline';
+import { CustomOrderedList } from '../extensions/ordered-list.extension';
+import { StyledTableKit } from '../extensions/table-style.extension';
+import { DynamicField } from '../nodes/dynamic-field.node';
+import { NotumHeading } from '../nodes/heading.node';
+import { ImageRef } from '../nodes/image-ref.node';
+import { PageBreak } from '../nodes/page-break.node';
+/**
+ * Canonical default extension list for headless (Node-safe) serialization.
+ *
+ * This is the schema half of the editor's runtime kit (`DocumentEngineKit` in
+ * the Angular wrapper): every node, mark, and HTML-affecting attribute the
+ * editor can persist, so {@link generateHTML} can turn stored document JSON back
+ * into HTML without a browser.
+ *
+ * It deliberately omits editing-only plugins (history/undo-redo, drop/gap
+ * cursors, placeholder, character count, list keymaps, trailing node). Those
+ * shape the live editing experience but contribute nothing to serialized
+ * output, and some attach view-level behavior that has no meaning headless.
+ *
+ * Only `renderHTML` is exercised during serialization — node views (which touch
+ * the DOM, e.g. `DynamicField.addNodeView`) are never invoked here, so this list
+ * is safe to import and run in Node.
+ *
+ * Callers needing a different schema (e.g. restricted-editing regions, or a
+ * trimmed set) should pass their own array to {@link generateHTML} instead.
+ */ export const defaultExtensions = [
+    // Structure
+    Document,
+    Paragraph,
+    Text,
+    NotumHeading,
+    HardBreak,
+    HorizontalRule,
+    Blockquote,
+    CodeBlock,
+    // Lists
+    BulletList,
+    ListItem,
+    CustomOrderedList,
+    // Marks
+    Bold,
+    Italic,
+    Underline,
+    Strike,
+    Code,
+    Link,
+    Subscript,
+    Superscript,
+    TextStyleKit,
+    // Block-level alignment (emits `text-align` only when explicitly set).
+    // NOTE: `Indent` is intentionally excluded — its `renderHTML` emits an empty
+    // `style=""` on every block even when unset, which pollutes otherwise-semantic
+    // output. Consumers that persist indentation can pass a custom extension array.
+    TextAlign.configure({
+        types: [
+            'paragraph',
+            'heading'
+        ]
+    }),
+    // Content nodes
+    Image,
+    ImageRef,
+    PageBreak,
+    DynamicField,
+    // Tables (table / row / header / cell nodes)
+    StyledTableKit
+];

package/src/kit/generate-html.d.ts

@@ -0,0 +1,23 @@
+import type { Extensions, JSONContent } from '@tiptap/core';
+/**
+ * Serialize a Tiptap/ProseMirror document (JSON) to an HTML string.
+ *
+ * Environment-aware and Node-safe. Tiptap ships two serializers and the wrong
+ * one throws:
+ * - `@tiptap/html` needs a real `document` (browser / jsdom).
+ * - `@tiptap/html/server` is backed by happy-dom and runs headlessly in Node.
+ *
+ * The serializer is chosen at call time from whether a DOM is present, and
+ * imported lazily — so the heavy happy-dom build is never pulled into a browser
+ * editor bundle that only ever edits (and never serializes server-side), and
+ * Node backends never touch the browser-only build. This is why the function is
+ * async.
+ *
+ * @param doc        The document as ProseMirror JSON (a `doc` node).
+ * @param extensions Schema to serialize against. Defaults to
+ *                   {@link defaultExtensions} (the editor's canonical kit). Pass
+ *                   a custom array when your documents use a different schema.
+ * @returns Semantic HTML. Presentation styling and sanitization (e.g. DOMPurify)
+ *          are the consumer's responsibility — this helper does neither.
+ */
+export declare function generateHTML(doc: JSONContent, extensions?: Extensions): Promise<string>;

package/src/kit/generate-html.js

@@ -0,0 +1,40 @@
+import { defaultExtensions } from './default-extensions';
+/**
+ * Serialize a Tiptap/ProseMirror document (JSON) to an HTML string.
+ *
+ * Environment-aware and Node-safe. Tiptap ships two serializers and the wrong
+ * one throws:
+ * - `@tiptap/html` needs a real `document` (browser / jsdom).
+ * - `@tiptap/html/server` is backed by happy-dom and runs headlessly in Node.
+ *
+ * The serializer is chosen at call time from whether a DOM is present, and
+ * imported lazily — so the heavy happy-dom build is never pulled into a browser
+ * editor bundle that only ever edits (and never serializes server-side), and
+ * Node backends never touch the browser-only build. This is why the function is
+ * async.
+ *
+ * @param doc        The document as ProseMirror JSON (a `doc` node).
+ * @param extensions Schema to serialize against. Defaults to
+ *                   {@link defaultExtensions} (the editor's canonical kit). Pass
+ *                   a custom array when your documents use a different schema.
+ * @returns Semantic HTML. Presentation styling and sanitization (e.g. DOMPurify)
+ *          are the consumer's responsibility — this helper does neither.
+ */ export async function generateHTML(doc, extensions = defaultExtensions) {
+    if (typeof document !== 'undefined') {
+        // browser / jsdom: uses the ambient DOM
+        const serializer = await import('@tiptap/html');
+        return serializer.generateHTML(doc, extensions);
+    }
+    // Node: happy-dom backed, no real DOM needed. The specifier is built at runtime
+    // (not a static string literal) and flagged for webpack/vite so browser
+    // bundlers (esbuild/webpack/vite) can't statically resolve it and therefore
+    // never pull happy-dom — and its Node built-ins — into a client bundle. The
+    // `typeof document` guard means this branch never executes in a browser anyway.
+    const serverEntry = [
+        '@tiptap',
+        'html',
+        'server'
+    ].join('/');
+    const serializer = await import(/* webpackIgnore: true */ /* @vite-ignore */ serverEntry);
+    return serializer.generateHTML(doc, extensions);
+}

package/src/kit/index.d.ts

@@ -0,0 +1,2 @@
+export * from './default-extensions';
+export * from './generate-html';

package/src/kit/index.js

@@ -0,0 +1,2 @@
+export * from './default-extensions';
+export * from './generate-html';

package/src/migrations/doc-migrations.d.ts

@@ -0,0 +1,27 @@
+import type { DocMigrationRegistry } from './types';
+/**
+ * The current schema version. `EditorDocument`s authored by this build of the
+ * editor carry this value, and {@link migrateDoc} upgrades older documents up to
+ * it.
+ *
+ * Bump this by exactly one whenever a schema change requires transforming stored
+ * content, and add the matching entry (keyed by the previous version) to
+ * {@link docMigrations}.
+ */
+export declare const LATEST_SCHEMA_VERSION = 1;
+/**
+ * Ordered migration steps, keyed by the source version they upgrade from.
+ *
+ * v0.1.0 ships an identity (empty) set: there is nothing to migrate yet, but the
+ * registry, walker ({@link migrateDoc}), and version field exist so future
+ * schema bumps are non-breaking. To add one, e.g. for the 1 -> 2 bump:
+ *
+ * ```ts
+ * export const docMigrations: DocMigrationRegistry = {
+ *   1: (doc) => ({ schemaVersion: 2, content: transformV1ToV2(doc.content) }),
+ * };
+ * ```
+ *
+ * Each entry must be pure (no mutation, no browser APIs).
+ */
+export declare const docMigrations: DocMigrationRegistry;

package/src/migrations/doc-migrations.js

@@ -0,0 +1,24 @@
+/**
+ * The current schema version. `EditorDocument`s authored by this build of the
+ * editor carry this value, and {@link migrateDoc} upgrades older documents up to
+ * it.
+ *
+ * Bump this by exactly one whenever a schema change requires transforming stored
+ * content, and add the matching entry (keyed by the previous version) to
+ * {@link docMigrations}.
+ */ export const LATEST_SCHEMA_VERSION = 1;
+/**
+ * Ordered migration steps, keyed by the source version they upgrade from.
+ *
+ * v0.1.0 ships an identity (empty) set: there is nothing to migrate yet, but the
+ * registry, walker ({@link migrateDoc}), and version field exist so future
+ * schema bumps are non-breaking. To add one, e.g. for the 1 -> 2 bump:
+ *
+ * ```ts
+ * export const docMigrations: DocMigrationRegistry = {
+ *   1: (doc) => ({ schemaVersion: 2, content: transformV1ToV2(doc.content) }),
+ * };
+ * ```
+ *
+ * Each entry must be pure (no mutation, no browser APIs).
+ */ export const docMigrations = {};

package/src/migrations/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './doc-migrations';
+export * from './migrate-doc';

package/src/migrations/index.js

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './doc-migrations';
+export * from './migrate-doc';

package/src/migrations/migrate-doc.d.ts

@@ -0,0 +1,16 @@
+import type { DocMigrationRegistry, EditorDocument } from './types';
+/**
+ * Upgrade a stored document to {@link LATEST_SCHEMA_VERSION} by applying each
+ * registered migration in order.
+ *
+ * Pure and idempotent: a document already at the latest version is returned
+ * unchanged (a re-stamped copy), so batch runs are safe to re-run. A document
+ * with a missing/invalid `schemaVersion` is treated as version 1 (the earliest).
+ *
+ * @param doc        The document to migrate.
+ * @param migrations Registry to apply. Defaults to {@link docMigrations}; the
+ *                   override exists for testing the walker in isolation.
+ * @param latest     Target version. Defaults to {@link LATEST_SCHEMA_VERSION}.
+ * @returns A new `EditorDocument` at `latest`.
+ */
+export declare function migrateDoc(doc: EditorDocument, migrations?: DocMigrationRegistry, latest?: number): EditorDocument;

package/src/migrations/migrate-doc.js

@@ -0,0 +1,32 @@
+import { docMigrations, LATEST_SCHEMA_VERSION } from './doc-migrations';
+/**
+ * Upgrade a stored document to {@link LATEST_SCHEMA_VERSION} by applying each
+ * registered migration in order.
+ *
+ * Pure and idempotent: a document already at the latest version is returned
+ * unchanged (a re-stamped copy), so batch runs are safe to re-run. A document
+ * with a missing/invalid `schemaVersion` is treated as version 1 (the earliest).
+ *
+ * @param doc        The document to migrate.
+ * @param migrations Registry to apply. Defaults to {@link docMigrations}; the
+ *                   override exists for testing the walker in isolation.
+ * @param latest     Target version. Defaults to {@link LATEST_SCHEMA_VERSION}.
+ * @returns A new `EditorDocument` at `latest`.
+ */ export function migrateDoc(doc, migrations = docMigrations, latest = LATEST_SCHEMA_VERSION) {
+    let current = {
+        ...doc,
+        schemaVersion: Number.isInteger(doc.schemaVersion) && doc.schemaVersion >= 1 ? doc.schemaVersion : 1
+    };
+    while(current.schemaVersion < latest){
+        const migrate = migrations[current.schemaVersion];
+        if (!migrate) {
+            throw new Error(`[migrateDoc] No migration registered for schema version ${current.schemaVersion} ` + `(target ${latest}).`);
+        }
+        const next = migrate(current);
+        if (next.schemaVersion <= current.schemaVersion) {
+            throw new Error(`[migrateDoc] Migration from version ${current.schemaVersion} did not advance the ` + `version (got ${next.schemaVersion}); migrations must be strictly increasing.`);
+        }
+        current = next;
+    }
+    return current;
+}

package/src/migrations/types.d.ts

@@ -0,0 +1,25 @@
+import type { JSONContent } from '@tiptap/core';
+/**
+ * A stored document plus the schema version its `content` was authored against.
+ *
+ * Documents are persisted as this thin wrapper (rather than stamping a version
+ * attribute onto the ProseMirror `doc` node) so versioning stays a storage-layer
+ * concern: the editor schema is untouched, and a backend can read/migrate the
+ * version without instantiating an editor.
+ */
+export interface EditorDocument {
+    /** Schema version `content` conforms to. See {@link LATEST_SCHEMA_VERSION}. */
+    schemaVersion: number;
+    /** The document body as ProseMirror/Tiptap JSON. */
+    content: JSONContent;
+}
+/**
+ * A single, pure migration step: upgrade a document from version `N` to `N + 1`.
+ * Must not mutate its input and must not depend on browser APIs.
+ */
+export type DocMigration = (doc: EditorDocument) => EditorDocument;
+/**
+ * Ordered registry of migration steps, keyed by the *source* version each step
+ * upgrades from. Entry `N` takes a v`N` document and returns a v`N + 1` one.
+ */
+export type DocMigrationRegistry = Record<number, DocMigration>;

package/src/migrations/types.js

@@ -0,0 +1,4 @@
+/**
+ * Ordered registry of migration steps, keyed by the *source* version each step
+ * upgrades from. Entry `N` takes a v`N` document and returns a v`N + 1` one.
+ */ export { };

package/src/nodes/image-ref.node.d.ts

@@ -0,0 +1,40 @@
+import { Node } from '@tiptap/core';
+/**
+ * Where the caption sits relative to the image.
+ */
+export type ImageRefCaptionPosition = 'top' | 'bottom';
+/**
+ * Attributes carried by an `image-ref` node.
+ *
+ * Only `imageId` is required. The node is intentionally **presentation-free**:
+ * it stores an opaque media id, never a URL or width/style. The real responsive
+ * image is resolved downstream (consumer side) from `imageId`.
+ */
+export interface ImageRefAttributes {
+    imageId: string;
+    /** Plain text only — serialized as `<figcaption>` text content; any nested markup is flattened on round-trip. */
+    caption?: string | null;
+    captionPosition?: ImageRefCaptionPosition | null;
+}
+export interface ImageRefOptions {
+    HTMLAttributes: Record<string, unknown>;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        imageRef: {
+            /** Insert an `image-ref` block. `imageId` is required. */
+            insertImageRef: (attributes: ImageRefAttributes) => ReturnType;
+        };
+    }
+}
+/**
+ * `image-ref` — a semantic, URL-free reference to a media asset.
+ *
+ * Renders a `<figure data-block="image-ref" data-image-id="…">` (with an optional
+ * `<figcaption>`), decoupling document content from the resolved image URL. The
+ * consumer hydrates the figure by attribute (`data-image-id`) at render time —
+ * the document itself never embeds a URL or any presentation. In the editor the
+ * node shows a placeholder (it has no URL to display); resolving and showing the
+ * real image is the consumer's / media-picker's job.
+ */
+export declare const ImageRef: Node<ImageRefOptions, any>;

package/src/nodes/image-ref.node.js

@@ -0,0 +1,138 @@
+import { Node, mergeAttributes } from '@tiptap/core';
+/**
+ * `image-ref` — a semantic, URL-free reference to a media asset.
+ *
+ * Renders a `<figure data-block="image-ref" data-image-id="…">` (with an optional
+ * `<figcaption>`), decoupling document content from the resolved image URL. The
+ * consumer hydrates the figure by attribute (`data-image-id`) at render time —
+ * the document itself never embeds a URL or any presentation. In the editor the
+ * node shows a placeholder (it has no URL to display); resolving and showing the
+ * real image is the consumer's / media-picker's job.
+ */ export const ImageRef = Node.create({
+    name: 'imageRef',
+    group: 'block',
+    atom: true,
+    selectable: true,
+    draggable: true,
+    addOptions () {
+        return {
+            HTMLAttributes: {}
+        };
+    },
+    addAttributes () {
+        return {
+            imageId: {
+                default: null,
+                parseHTML: (element)=>element.getAttribute('data-image-id'),
+                renderHTML: (attributes)=>{
+                    if (!attributes['imageId']) return {};
+                    return {
+                        'data-image-id': attributes['imageId']
+                    };
+                }
+            },
+            caption: {
+                default: null,
+                // Caption is rendered as <figcaption> text content (below), not a data
+                // attribute — so parse it back from the figcaption child for round-trip.
+                parseHTML: (element)=>{
+                    const figcaption = element.querySelector(':scope > figcaption');
+                    return figcaption?.textContent?.trim() || null;
+                },
+                renderHTML: ()=>({})
+            },
+            captionPosition: {
+                default: null,
+                // Normalize to the typed union: absent attribute stays `null` (preserves
+                // the byte-identical round-trip), any present-but-unknown value coerces to
+                // `'bottom'` so a non-`'top' | 'bottom'` string can never leak through.
+                parseHTML: (element)=>{
+                    const raw = element.getAttribute('data-caption-position');
+                    if (raw === null) return null;
+                    return raw === 'top' ? 'top' : 'bottom';
+                },
+                renderHTML: (attributes)=>{
+                    if (!attributes['captionPosition']) return {};
+                    return {
+                        'data-caption-position': attributes['captionPosition']
+                    };
+                }
+            }
+        };
+    },
+    parseHTML () {
+        return [
+            {
+                tag: 'figure[data-block="image-ref"]'
+            }
+        ];
+    },
+    renderHTML ({ HTMLAttributes, node }) {
+        const { caption } = node.attrs;
+        const figure = mergeAttributes(this.options.HTMLAttributes, HTMLAttributes, {
+            'data-block': 'image-ref'
+        });
+        // No <img> is emitted — the asset is URL-free. The caption order relative to
+        // the (not-yet-resolved) image is carried by `data-caption-position` for the
+        // consumer to honor at hydration time; the figure itself just holds the text.
+        if (!caption) {
+            return [
+                'figure',
+                figure
+            ];
+        }
+        const figcaption = [
+            'figcaption',
+            {},
+            caption
+        ];
+        return [
+            'figure',
+            figure,
+            figcaption
+        ];
+    },
+    /**
+   * Editor-only placeholder. The DOM here is chrome (never serialized — that is
+   * `renderHTML`'s job); it just shows which media the block references.
+   */ addNodeView () {
+        return ({ node })=>{
+            const { imageId, caption, captionPosition } = node.attrs;
+            const dom = document.createElement('figure');
+            dom.classList.add('image-ref-placeholder');
+            dom.setAttribute('data-block', 'image-ref');
+            if (imageId) dom.setAttribute('data-image-id', imageId);
+            if (captionPosition) dom.setAttribute('data-caption-position', captionPosition);
+            dom.style.cssText = 'margin:1rem 0;display:flex;flex-direction:column;gap:.5rem;';
+            const box = document.createElement('div');
+            box.style.cssText = 'display:flex;align-items:center;gap:.5rem;padding:1rem;border:1px dashed currentColor;' + 'border-radius:.5rem;opacity:.65;font-size:.875rem;justify-content:center;';
+            box.textContent = `🖼  image-ref · id: ${imageId || '—'}`;
+            const figcaption = document.createElement('figcaption');
+            figcaption.style.cssText = 'font-size:.8125rem;opacity:.7;text-align:center;';
+            if (caption) figcaption.textContent = caption;
+            if (caption && captionPosition === 'top') {
+                dom.append(figcaption, box);
+            } else {
+                dom.append(box);
+                if (caption) dom.append(figcaption);
+            }
+            return {
+                dom
+            };
+        };
+    },
+    addCommands () {
+        return {
+            insertImageRef: (attributes)=>({ chain })=>{
+                    if (!attributes.imageId) {
+                        console.error('[ImageRef] imageId is required.');
+                        return false;
+                    }
+                    return chain().insertContent({
+                        type: this.name,
+                        attrs: attributes
+                    }).run();
+                }
+        };
+    }
+});

package/src/nodes/index.d.ts

@@ -1,3 +1,4 @@
 export * from './heading.node';
 export * from './dynamic-field.node';
 export * from './page-break.node';
+export * from './image-ref.node';

package/src/nodes/index.js

@@ -1,3 +1,4 @@
 export * from './heading.node';
 export * from './dynamic-field.node';
 export * from './page-break.node';
+export * from './image-ref.node';

package/src/types/tiptap-html-server.d.js

@@ -0,0 +1,10 @@
+/**
+ * Type shim for the `@tiptap/html/server` subpath.
+ *
+ * `@tiptap/html` only exposes its Node-safe (`/server`) entry through the
+ * package `exports` map. This library compiles under `moduleResolution: node10`,
+ * which ignores `exports` for type resolution, so TypeScript cannot find the
+ * subpath's declarations on its own. The runtime (Jest/Node) resolves `/server`
+ * via the exports map fine — this declaration only satisfies the type checker by
+ * pointing it at the same public types as the bare package.
+ */