npm - openwriter - Versions diffs - 0.13.0 → 0.14.0 - Mend

openwriter 0.13.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/dist/client/assets/{index-BlLnLdoc.js → index-BxI3DazW.js} +2 -2
package/dist/client/index.html +1 -1
package/dist/server/documents.js +11 -11
package/dist/server/index.js +2 -5
package/dist/server/markdown-parse.js +144 -5
package/dist/server/markdown-serialize.js +96 -9
package/dist/server/markdown.js +32 -0
package/dist/server/node-blocks.js +256 -0
package/dist/server/node-fingerprint.js +264 -0
package/dist/server/node-matcher.js +564 -0
package/dist/server/node-sync-check.js +110 -0
package/dist/server/state.js +172 -46
package/package.json +1 -1
package/skill/SKILL.md +1 -0

package/dist/client/index.html CHANGED Viewed

@@ -10,7 +10,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Charter:ital,wght@0,400;0,700;1,400&family=Crimson+Pro:ital,wght@0,300;0,400;0,600;0,700;1,400&family=DM+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=DM+Serif+Display&family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600&family=Inter:wght@400;500;600;700&family=Libre+Baskerville:ital,wght@0,400;0,700;1,400&family=Literata:ital,opsz,wght@0,7..72,400;0,7..72,600;0,7..72,700;1,7..72,400&family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,600;1,6..72,400&family=Playfair+Display:wght@400;600;700;900&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;0,8..60,700;1,8..60,400&family=Space+Grotesk:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-BlLnLdoc.js"></script>
+    <script type="module" crossorigin src="/assets/index-BxI3DazW.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-OV13QtgQ.css">
   </head>
   <body>

package/dist/server/documents.js CHANGED Viewed

@@ -7,7 +7,7 @@ import { existsSync, readFileSync, writeFileSync, readdirSync, statSync, mkdirSy
 import { join } from 'path';
 import matter from 'gray-matter';
 import trash from 'trash';
-import { tiptapToMarkdown, markdownToTiptap } from './markdown.js';
+import { tiptapToMarkdownChecked, markdownToTiptap } from './markdown.js';
 import { parseMarkdownContent } from './compact.js';
 import { getDocument, getTitle, getFilePath, getIsTemp, getMetadata, save, cancelDebouncedSave, setActiveDocument, registerExternalDoc, unregisterExternalDoc, getExternalDocs, cacheActiveDocument, getCachedDocument, invalidateDocCache, removePendingCacheEntry, resetDocVersion, } from './state.js';
 import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, resolveDocPath, isExternalDoc, atomicWriteFileSync } from './helpers.js';
@@ -122,7 +122,7 @@ export function listDocuments() {
                 ...(deriveContentType(data) ? { contentType: deriveContentType(data) } : {}),
                 ...(data.masterDocId ? { masterDocId: data.masterDocId } : {}),
                 ...(data.variantType ? { variantType: data.variantType } : {}),
-                ...(data.autoAccept === true ? { autoAccept: true } : {}),
+                ...(typeof data.autoAccept === 'boolean' ? { autoAccept: data.autoAccept } : {}),
             };
         }
         catch {
@@ -163,7 +163,7 @@ export function listDocuments() {
                 ...(deriveContentType(data) ? { contentType: deriveContentType(data) } : {}),
                 ...(data.masterDocId ? { masterDocId: data.masterDocId } : {}),
                 ...(data.variantType ? { variantType: data.variantType } : {}),
-                ...(data.autoAccept === true ? { autoAccept: true } : {}),
+                ...(typeof data.autoAccept === 'boolean' ? { autoAccept: data.autoAccept } : {}),
             });
         }
         catch { /* skip unreadable external files */ }
@@ -276,7 +276,7 @@ export function archiveDocument(filename) {
             const next = remaining[0];
             const raw = readFileSync(next.path, 'utf-8');
             const parsed = markdownToTiptap(raw);
-            setActiveDocument(parsed.document, parsed.title, next.path, next.name.startsWith(TEMP_PREFIX), new Date(next.mtime), parsed.metadata);
+            setActiveDocument(parsed.document, parsed.title, next.path, next.name.startsWith(TEMP_PREFIX), new Date(next.mtime), parsed.metadata, undefined);
             return { switched: true, newDoc: { document: getDocument(), title: getTitle(), filename: next.name } };
         }
     }
@@ -471,7 +471,7 @@ export function createDocument(title, content, path) {
     const metadata = { title: docTitle, docId: generateNodeId() };
     setActiveDocument(newDoc, docTitle, filePath, isTemp, undefined, metadata);
     // Write doc to disk
-    const markdown = tiptapToMarkdown(newDoc, docTitle, metadata);
+    const { markdown } = tiptapToMarkdownChecked(newDoc, docTitle, metadata);
     ensureDataDir();
     atomicWriteFileSync(filePath, markdown);
     // Prepend to doc order so new docs appear at top and stay put after edits
@@ -519,7 +519,7 @@ export function createDocumentFile(title, path, extraMeta) {
     }
     const newDoc = { type: 'doc', content: [{ type: 'paragraph', attrs: { id: generateNodeId() }, content: [] }] };
     const metadata = { title: docTitle, docId: generateNodeId(), agentCreated: true, ...extraMeta };
-    const markdown = tiptapToMarkdown(newDoc, docTitle, metadata);
+    const { markdown } = tiptapToMarkdownChecked(newDoc, docTitle, metadata);
     ensureDataDir();
     atomicWriteFileSync(filePath, markdown);
     // Prepend to doc order so new docs appear at top and stay put after edits
@@ -557,7 +557,7 @@ export async function deleteDocument(filename) {
             const next = remaining[0];
             const raw = readFileSync(next.path, 'utf-8');
             const parsed = markdownToTiptap(raw);
-            setActiveDocument(parsed.document, parsed.title, next.path, next.name.startsWith(TEMP_PREFIX), new Date(next.mtime), parsed.metadata);
+            setActiveDocument(parsed.document, parsed.title, next.path, next.name.startsWith(TEMP_PREFIX), new Date(next.mtime), parsed.metadata, undefined);
             return { switched: true, newDoc: { document: getDocument(), title: getTitle(), filename: next.name } };
         }
     }
@@ -574,7 +574,7 @@ export function reloadDocument() {
     const raw = readFileSync(filePath, 'utf-8');
     const parsed = markdownToTiptap(raw);
     const mtime = new Date(statSync(filePath).mtimeMs);
-    setActiveDocument(parsed.document, parsed.title, filePath, filename.startsWith(TEMP_PREFIX), mtime, parsed.metadata);
+    setActiveDocument(parsed.document, parsed.title, filePath, filename.startsWith(TEMP_PREFIX), mtime, parsed.metadata, undefined);
     return { document: getDocument(), title: getTitle(), filename };
 }
 export function updateDocumentTitle(filename, newTitle) {
@@ -586,7 +586,7 @@ export function updateDocumentTitle(filename, newTitle) {
     const raw = readFileSync(filePath, 'utf-8');
     const parsed = markdownToTiptap(raw);
     const metadata = { ...parsed.metadata, title: newTitle };
-    const markdown = tiptapToMarkdown(parsed.document, newTitle, metadata);
+    const { markdown } = tiptapToMarkdownChecked(parsed.document, newTitle, metadata);
     atomicWriteFileSync(filePath, markdown);
     // Update state if this is the active document
     const baseName = filePath.split(/[/\\]/).pop() || '';
@@ -654,7 +654,7 @@ export function duplicateDocument(filename) {
     }
     const metadata = { ...parsed.metadata, title: newTitle, docId: generateNodeId() };
     setActiveDocument(parsed.document, newTitle, filePath, false, undefined, metadata);
-    const markdown = tiptapToMarkdown(parsed.document, newTitle, metadata);
+    const { markdown } = tiptapToMarkdownChecked(parsed.document, newTitle, metadata);
     ensureDataDir();
     atomicWriteFileSync(filePath, markdown);
     const newFilename = filePath.split(/[/\\]/).pop();
@@ -788,7 +788,7 @@ function resolveDocFile(filePath, action) {
     if (count === 0)
         return 0;
     // Re-serialize — pending attrs are cleared so pending key will be removed from frontmatter
-    const newRaw = tiptapToMarkdown(doc, parsed.title, parsed.metadata);
+    const { markdown: newRaw } = tiptapToMarkdownChecked(doc, parsed.title, parsed.metadata);
     atomicWriteFileSync(filePath, newRaw);
     return count;
 }

package/dist/server/index.js CHANGED Viewed

@@ -167,12 +167,9 @@ export async function startHttpServer(options = {}) {
             if (isActiveDoc) {
                 if (enabled) {
                     stripPendingAttrs(); // accept any pending changes
-                    setMetadata({ autoAccept: true });
-                }
-                else {
-                    const meta = getMetadata();
-                    delete meta.autoAccept;
                 }
+                // Explicit boolean (not delete) — false overrides workspace inheritance.
+                setMetadata({ autoAccept: enabled });
                 save();
                 updatePendingCacheForActiveDoc();
                 broadcastMetadataChanged(getMetadata());

package/dist/server/markdown-parse.js CHANGED Viewed

@@ -1,6 +1,15 @@
 /**
  * Markdown -> TipTap JSON parsing.
  * Parses markdown (with optional YAML frontmatter) into TipTap document JSON.
+ *
+ * Node identity is reassigned via the matcher when the frontmatter carries a
+ * `nodes` array (the new path). For legacy docs without `nodes`, trailing
+ * `^id` caret anchors and `<!-- ^id -->` empty-paragraph markers are still
+ * recognized as ID sources so existing files keep their identities through
+ * the migration. Once a migrated doc is saved, the body is clean and all
+ * identity lives in frontmatter.
+ *
+ * adr: adr/node-identity-matcher.md
  */
 import MarkdownIt from 'markdown-it';
 import matter from 'gray-matter';
@@ -10,6 +19,8 @@ import markdownItSub from 'markdown-it-sub';
 import markdownItSup from 'markdown-it-sup';
 import { generateNodeId, LEAF_BLOCK_TYPES } from './helpers.js';
 import { nodeText } from './markdown-serialize.js';
+import { tiptapToBlocks, applyIdsToTiptap } from './node-blocks.js';
+import { matchNodes } from './node-matcher.js';
 // ============================================================================
 // Markdown -> TipTap
 // ============================================================================
@@ -19,24 +30,152 @@ md.use(markdownItIns);
 md.use(markdownItMark);
 md.use(markdownItSub);
 md.use(markdownItSup);
+/**
+ * Normalize blank lines INSIDE markdown tables before parsing.
+ *
+ * Per CommonMark, a blank line terminates a table block. Agents writing
+ * markdown content frequently insert blank lines between table rows for
+ * readability (e.g. `| row |\n\n| row |`), which the strict parser then
+ * splits into "table with 1 header row" + N orphan paragraphs that happen
+ * to contain pipe characters. The broken structure persists across saves
+ * because every serialize → re-parse cycle re-breaks it.
+ *
+ * This pre-pass detects "table region" (saw a separator row `| --- |`,
+ * haven't hit a non-pipe-row yet) and strips blank lines between pipe-rows
+ * inside that region. Code fences (` ``` `, `~~~`) are honored — pipes
+ * inside them stay untouched.
+ *
+ * Self-healing: a doc on disk with blank-separated rows loads as a proper
+ * N-row table; the next save writes contiguous markdown. No migration
+ * script needed.
+ */
+function normalizeTableBlankLines(markdown) {
+    if (!markdown.includes('|'))
+        return markdown;
+    const lines = markdown.split('\n');
+    const out = [];
+    let inFence = false;
+    let inTable = false; // true between a separator row and the next non-pipe-row
+    const isPipeRow = (s) => /^\s*\|.*\|\s*$/.test(s);
+    const isSeparator = (s) => /^\s*\|[\s:|-]+\|\s*$/.test(s);
+    const isBlank = (s) => s.trim() === '';
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Code-fence toggle — pipes inside fences stay verbatim
+        if (/^[`~]{3,}/.test(line)) {
+            inFence = !inFence;
+            inTable = false;
+            out.push(line);
+            continue;
+        }
+        if (inFence) {
+            out.push(line);
+            continue;
+        }
+        if (isSeparator(line)) {
+            // Separator confirms we're in a table region from here on
+            inTable = true;
+            out.push(line);
+            continue;
+        }
+        if (inTable && isBlank(line)) {
+            // Look ahead past additional blanks for the next non-blank line
+            let j = i + 1;
+            while (j < lines.length && lines[j].trim() === '')
+                j++;
+            // If the next non-blank line is another pipe-row, it's EITHER a
+            // continuation row (merge across the blank) OR the header of a NEW
+            // table (the blank is the boundary, don't merge). We tell them apart
+            // by peeking one further: if line j+1 is a separator row, j is a new
+            // table's header — preserve the blank and exit the current table region.
+            if (j < lines.length && isPipeRow(lines[j])) {
+                if (j + 1 < lines.length && isSeparator(lines[j + 1])) {
+                    // New table starting — keep the boundary blank, end current region
+                    inTable = false;
+                    out.push(line);
+                    continue;
+                }
+                // Continuation row — drop the blank
+                continue;
+            }
+            // Lookahead found non-pipe content — table region is ending
+            inTable = false;
+            out.push(line);
+            continue;
+        }
+        if (inTable && !isPipeRow(line)) {
+            // Non-pipe content ends the table region
+            inTable = false;
+        }
+        out.push(line);
+    }
+    return out.join('\n');
+}
 export function markdownToTiptap(markdown) {
     const result = matter(markdown);
     const { data, content } = result;
     const title = data.title || 'Untitled';
-    const tokens = md.parse(content, {});
+    const normalizedContent = normalizeTableBlankLines(content);
+    const tokens = md.parse(normalizedContent, {});
     const docContent = tokensToTiptap(tokens);
     const doc = {
         type: 'doc',
         content: docContent.length > 0 ? docContent : [{ type: 'paragraph', attrs: { id: generateNodeId() }, content: [] }],
     };
+    // Extract identity graph from frontmatter — these become the matcher's
+    // previousNodes input on both the load-time pass below AND on every
+    // subsequent save-time pass while the doc stays loaded.
+    const previousNodes = normalizeNodeEntries(data.nodes);
+    const graveyard = normalizeNodeEntries(data.graveyard);
+    // Load-time matcher pass — when frontmatter carries `nodes`, reassign IDs
+    // based on fingerprint match. Legacy docs (no `nodes` field) keep whatever
+    // IDs the body parser extracted from caret anchors or minted fresh.
+    if (previousNodes.length > 0) {
+        applyMatcher(doc, previousNodes, graveyard);
+    }
     // Rehydrate pending state from frontmatter into node attrs
     if (data.pending) {
         rehydratePendingState(doc, data.pending);
     }
-    // Strip pending from returned metadata (consumed into node attrs)
+    // Strip consumed keys from returned metadata
     const metadata = { ...data };
     delete metadata.pending;
-    return { title, metadata, document: doc, rawFrontmatter: result.matter || null };
+    delete metadata.nodes;
+    delete metadata.graveyard;
+    return {
+        title,
+        metadata,
+        document: doc,
+        rawFrontmatter: result.matter || null,
+        graveyard,
+        previousNodes,
+    };
+}
+/** Defensive parse of frontmatter node entries — drops any malformed rows. */
+function normalizeNodeEntries(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw
+        .filter((entry) => entry && typeof entry === 'object' && entry.id && entry.fp)
+        .map((entry) => ({ id: String(entry.id), fingerprint: entry.fp }));
+}
+/**
+ * Run the matcher: compare frontmatter `nodes` (previous fingerprints) to
+ * the current TipTap tree's blocks, then apply pinned IDs back onto the tree.
+ *
+ * Graveyard is passed through so paste-back of recently-deleted content
+ * restores the original ID (matched by exact fingerprint).
+ */
+function applyMatcher(doc, previousNodes, graveyard) {
+    if (previousNodes.length === 0)
+        return;
+    const newBlocks = tiptapToBlocks(doc);
+    const matchResult = matchNodes(previousNodes, newBlocks, { graveyard });
+    const pinnedByPosition = new Map();
+    for (const p of matchResult.pinned) {
+        pinnedByPosition.set(p.position, p.id);
+    }
+    applyIdsToTiptap(doc, pinnedByPosition);
 }
 /**
  * Rehydrate pending state from frontmatter into leaf block node attrs.
@@ -453,8 +592,8 @@ function popMarkByType(stack, type) {
 /**
  * Extract a trailing nodeId anchor from inline content.
  * Format: ` ^abc12345` (space + caret + 8 lowercase hex chars at end of line).
- * Matches Obsidian's block-reference convention. Strips the marker from the
- * visible text and returns the captured id. Returns id=null if no anchor found.
+ * Strips the marker from the visible text and returns the captured id.
+ * Returns id=null if no anchor found.
  *
  * Known limit: prose ending with the literal pattern ` ^[8 lowercase hex]`
  * will be interpreted as an anchor. Vanishingly rare in real writing.

package/dist/server/markdown-serialize.js CHANGED Viewed

@@ -1,8 +1,24 @@
 /**
  * TipTap JSON -> Markdown serialization.
  * Converts TipTap document to markdown with YAML frontmatter.
+ *
+ * Node identity persistence:
+ *   - Frontmatter `nodes` array carries the (id, fingerprint) pair for every
+ *     block in the document. On load, markdown-parse.ts runs the matcher
+ *     against this array to reassign IDs to surviving blocks.
+ *   - Markdown body is COMPLETELY UNDISTURBED — no anchors, no comment
+ *     sentinels (except the legacy `<!-- -->` empty-paragraph marker which
+ *     has no semantic ID attached anymore).
+ *   - Legacy `^id` caret anchors are no longer emitted. Old docs that still
+ *     contain them are migrated transparently on the next save: parse reads
+ *     the anchors, matcher pins them, serialize emits the new `nodes`
+ *     frontmatter and a clean body.
+ *
+ * adr: adr/node-identity-matcher.md
  */
-import { LEAF_BLOCK_TYPES } from './helpers.js';
+import { generateNodeId, LEAF_BLOCK_TYPES } from './helpers.js';
+import { tiptapToBlocks } from './node-blocks.js';
+import { fingerprintAll } from './node-fingerprint.js';
 // ============================================================================
 // TipTap -> Markdown
 // ============================================================================
@@ -57,11 +73,67 @@ function collectPendingState(doc) {
     walk(doc.content || []);
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
+/**
+ * Build the `nodes` frontmatter entry — one (id, fingerprint) per block
+ * in pre-order traversal of the TipTap tree.
+ *
+ * Each block's ID comes from its TipTap node's `attrs.id`. Fingerprints are
+ * computed from the walker-style block list derived directly from the TipTap
+ * tree (no separate markdown re-parse — same source of truth that builds
+ * the visible doc).
+ */
+function collectNodesFrontmatter(doc) {
+    const blocks = tiptapToBlocks(doc);
+    const fingerprints = fingerprintAll(blocks);
+    const ids = collectBlockIds(doc);
+    // ids array is parallel to blocks array — same pre-order traversal.
+    const entries = [];
+    for (let i = 0; i < blocks.length; i++) {
+        const id = ids[i] || generateNodeId();
+        entries.push({ id, fp: fingerprints[i] });
+    }
+    return entries;
+}
+/**
+ * Cap graveyard size to avoid frontmatter bloat on docs with many edits.
+ * Newest entries (highest position) win — the ones most likely to be
+ * paste-back targets. Older entries expire silently.
+ */
+const GRAVEYARD_MAX = 50;
+/** Walk the TipTap tree in the SAME pre-order as tiptapToBlocks, collect IDs. */
+function collectBlockIds(doc) {
+    const ids = [];
+    const blockTypes = new Set([
+        'heading', 'paragraph', 'bulletList', 'orderedList', 'taskList',
+        'listItem', 'taskItem', 'blockquote', 'codeBlock', 'horizontalRule',
+        'table', 'image', 'tableRow', 'tableCell', 'tableHeader',
+    ]);
+    const containerTypes = new Set([
+        'bulletList', 'orderedList', 'taskList', 'listItem', 'taskItem', 'blockquote',
+    ]);
+    function walk(nodes) {
+        if (!nodes)
+            return;
+        for (const node of nodes) {
+            if (blockTypes.has(node.type)) {
+                ids.push(node.attrs?.id || '');
+                if (containerTypes.has(node.type) && node.content)
+                    walk(node.content);
+            }
+            else if (node.content) {
+                walk(node.content);
+            }
+        }
+    }
+    walk(doc.content || []);
+    return ids;
+}
 /**
  * Convert TipTap document to markdown with JSON frontmatter.
  * Metadata stored as minified JSON between --- delimiters (valid YAML).
  * Editor never sees frontmatter — it's stripped on load, regenerated on save.
  * Pending state is persisted in frontmatter `pending` key.
+ * Node identity persisted in frontmatter `nodes` key (id + fingerprint per block).
  */
 export function tiptapToMarkdown(doc, title, metadata) {
     const meta = { ...metadata, title };
@@ -73,6 +145,24 @@ export function tiptapToMarkdown(doc, title, metadata) {
     else {
         delete meta.pending;
     }
+    // Collect node identity graph (id + fingerprint per block) for next-load matcher
+    const nodes = collectNodesFrontmatter(doc);
+    if (nodes.length > 0) {
+        meta.nodes = nodes;
+    }
+    else {
+        delete meta.nodes;
+    }
+    // Graveyard: recently-orphaned (id, fingerprint) entries kept across saves so
+    // paste-back/undo can restore the original ID via exact fingerprint match.
+    // The caller (writeToDisk) puts the matcher's nextGraveyard into metadata.graveyard;
+    // we cap it here to keep the file small.
+    if (Array.isArray(meta.graveyard) && meta.graveyard.length > 0) {
+        meta.graveyard = meta.graveyard.slice(0, GRAVEYARD_MAX);
+    }
+    else {
+        delete meta.graveyard;
+    }
     // Strip undefined/null values
     for (const key of Object.keys(meta)) {
         if (meta[key] === undefined || meta[key] === null)
@@ -98,19 +188,16 @@ function nodeToMarkdown(node, indent) {
         case 'heading': {
             const level = node.attrs?.level || 1;
             const prefix = '#'.repeat(level);
-            const idSuffix = node.attrs?.id ? ` ^${node.attrs.id}` : '';
-            return `${prefix} ${inlineToMarkdown(node.content)}${idSuffix}\n\n`;
+            // Body stays undisturbed — node ID is persisted in frontmatter `nodes`, not as a trailing anchor.
+            return `${prefix} ${inlineToMarkdown(node.content)}\n\n`;
         }
         case 'paragraph': {
             const text = inlineToMarkdown(node.content);
-            const id = node.attrs?.id;
             if (text) {
-                const idSuffix = id ? ` ^${id}` : '';
-                return `${indent}${text}${idSuffix}\n\n`;
+                return `${indent}${text}\n\n`;
             }
-            // Empty paragraph: embed id in the existing sentinel comment
-            const emptyMarker = id ? `<!-- ^${id} -->` : '<!-- -->';
-            return `${indent}${emptyMarker}\n\n`;
+            // Empty paragraph: use plain sentinel (frontmatter `nodes` carries the ID).
+            return `${indent}<!-- -->\n\n`;
         }
         case 'bulletList':
             return listToMarkdown(node.content, '- ', indent);

package/dist/server/markdown.js CHANGED Viewed

@@ -1,6 +1,38 @@
 /**
  * Barrel re-export for markdown serialization and parsing.
  * All existing imports from './markdown.js' continue to work unchanged.
+ *
+ * Also exposes `tiptapToMarkdownChecked` — a sync-observed wrapper that
+ * verifies the TipTap → markdown → TipTap round-trip preserves document
+ * shape. Use this when you want to catch silent drift; the unchecked
+ * `tiptapToMarkdown` stays the cheap path for hot loops.
  */
+import { tiptapToMarkdown } from './markdown-serialize.js';
+import { markdownToTiptap } from './markdown-parse.js';
+import { shapeOfTiptap, compareShapes, formatSyncReport, } from './node-sync-check.js';
 export { tiptapToMarkdown, tiptapToBody, nodeText, inlineToMarkdown } from './markdown-serialize.js';
 export { markdownToTiptap, markdownToNodes } from './markdown-parse.js';
+export { shapeOfTiptap, computeShape, compareShapes, formatSyncReport, } from './node-sync-check.js';
+/**
+ * Serialize TipTap to markdown, then re-parse and verify that the round-trip
+ * preserved document shape. If the shapes diverge, a node was misapplied —
+ * content ended up in the wrong block on save, or the parse interpreted
+ * something differently than the serialize emitted.
+ *
+ * Returns the markdown AND the sync report. Callers decide whether a failed
+ * report should block the save (throw) or just log and continue.
+ *
+ * Cost: one extra parse + two shape computations per save. Acceptable for
+ * any user-driven save; consider the unchecked path inside tight loops.
+ */
+export function tiptapToMarkdownChecked(doc, title, metadata) {
+    const markdown = tiptapToMarkdown(doc, title, metadata);
+    const expectedShape = shapeOfTiptap(doc);
+    const reparsed = markdownToTiptap(markdown);
+    const actualShape = shapeOfTiptap(reparsed.document);
+    const syncReport = compareShapes(expectedShape, actualShape);
+    if (!syncReport.ok) {
+        console.error(formatSyncReport(syncReport, `serialize:${title}`));
+    }
+    return { markdown, syncReport };
+}