openwriter 0.13.0 → 0.15.0

package/dist/server/index.js

@@ -7,11 +7,11 @@ import { createServer } from 'http';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { existsSync, readFileSync } from 'fs';
-import { setupWebSocket, broadcastAgentStatus, broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastSyncStatus, broadcastWritingStarted, broadcastWritingFinished, broadcastMarksChanged } from './ws.js';
+import { setupWebSocket, broadcastAgentStatus, broadcastDocumentSwitched, broadcastDocumentsChanged, broadcastWorkspacesChanged, broadcastMetadataChanged, broadcastPendingDocsChanged, broadcastSyncStatus, broadcastWritingStarted, broadcastWritingFinished, broadcastCommentsChanged } from './ws.js';
 import { TOOL_REGISTRY } from './mcp.js';
 import { z } from 'zod';
 import { zodToJsonSchema } from 'zod-to-json-schema';
-import { save, cancelDebouncedSave, load, getDocument, getTitle, getFilePath, getDocId, getMetadata, getStatus, updateDocument, setMetadata, applyTextEdits, isAgentLocked, getPendingDocInfo, getDocTagsByFilename, addDocTag, removeDocTag, markAllNodesAsPending, updatePendingCacheForActiveDoc, removePendingCacheEntry, clearAllCaches, stripPendingAttrs, stripPendingAttrsFromFile, setAutoAcceptOnFile } from './state.js';
+import { save, cancelDebouncedSave, load, getDocument, getTitle, getFilePath, getDocId, getMetadata, getStatus, updateDocument, setMetadata, applyTextEdits, isAgentLocked, getPendingDocInfo, getDocTagsByFilename, addDocTag, removeDocTag, markAllNodesAsPending, updatePendingCacheForActiveDoc, removePendingCacheEntry, clearAllCaches, stripPendingAttrs, stripPendingAttrsFromFile, setAutoAcceptOnFile, markAsAgentStub } from './state.js';
 import { syncPostHistory } from './post-sync.js';
 import { listDocuments, switchDocument, createDocument, deleteDocument, duplicateDocument, reloadDocument, updateDocumentTitle, openFile, reorderDocs, searchDocuments, listArchivedDocuments, archiveDocument, unarchiveDocument, getActiveFilename, batchResolve } from './documents.js';
 import { createWorkspaceRouter } from './workspace-routes.js';
@@ -34,11 +34,18 @@ import { createTaskRouter } from './task-routes.js';
 import { platformFetch, isAuthenticated } from './connections.js';
 import { PluginManager } from './plugin-manager.js';
 import { checkForUpdate, getUpdateInfo, getCurrentVersion } from './update-check.js';
-import { addMark, getMarks, resolveMarks, editMark } from './marks.js';
+import { addComment, getComments, resolveComments, unresolveComments, deleteComments, editComment } from './comments.js';
+import { initLogger, logger, generateRequestId, withRequestId } from './logger.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 export async function startHttpServer(options = {}) {
     const port = options.port || 5050;
+    // Initialize structured logging first — every subsequent module call can
+    // emit events from this point. Config file lives at ~/.openwriter/
+    // log-config.json (missing = safe public defaults: error-only, no text).
+    // adr: adr/logging-system.md
+    initLogger();
+    logger.info('state', 'server-boot', `OpenWriter starting on port ${port}`, { port });
     const app = express();
     app.use(express.json({ limit: '10mb' }));
     // API routes for direct HTTP access (fallback if WS not available)
@@ -56,26 +63,33 @@ export async function startHttpServer(options = {}) {
     });
     // MCP-over-HTTP: allows client-mode terminals to proxy tool calls
     app.post('/api/mcp-call', async (req, res) => {
-        try {
-            const { tool: toolName, arguments: args } = req.body;
-            const tool = TOOL_REGISTRY.find((t) => t.name === toolName);
-            if (!tool) {
-                res.status(404).json({ error: `Unknown tool: ${toolName}` });
-                return;
+        const { tool: toolName, arguments: args } = req.body;
+        // Wrap the call in a request ID scope so every event logged during
+        // this tool invocation correlates. adr: adr/logging-system.md
+        const reqId = generateRequestId(`mcp-http-${toolName || 'unknown'}`);
+        await withRequestId(reqId, async () => {
+            try {
+                const tool = TOOL_REGISTRY.find((t) => t.name === toolName);
+                if (!tool) {
+                    res.status(404).json({ error: `Unknown tool: ${toolName}` });
+                    return;
+                }
+                // Validate arguments against the tool's Zod schema (mirrors McpServer.validateToolInput)
+                const schema = z.object(tool.schema);
+                const parsed = schema.safeParse(args || {});
+                if (!parsed.success) {
+                    res.status(400).json({ content: [{ type: 'text', text: `Validation error: ${parsed.error.message}` }] });
+                    return;
+                }
+                logger.debug('mcp', 'tool-call-http', tool.name, { tool: tool.name });
+                const result = await tool.handler(parsed.data);
+                res.json(result);
             }
-            // Validate arguments against the tool's Zod schema (mirrors McpServer.validateToolInput)
-            const schema = z.object(tool.schema);
-            const parsed = schema.safeParse(args || {});
-            if (!parsed.success) {
-                res.status(400).json({ content: [{ type: 'text', text: `Validation error: ${parsed.error.message}` }] });
-                return;
+            catch (err) {
+                logger.error('mcp', 'tool-error-http', `${toolName}: ${err.message}`, { tool: toolName }, err);
+                res.status(500).json({ content: [{ type: 'text', text: `Error: ${err.message}` }] });
             }
-            const result = await tool.handler(parsed.data);
-            res.json(result);
-        }
-        catch (err) {
-            res.status(500).json({ content: [{ type: 'text', text: `Error: ${err.message}` }] });
-        }
+        });
     });
     app.get('/api/update-info', (_req, res) => {
         const latestVersion = getUpdateInfo();
@@ -167,12 +181,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());
@@ -248,7 +259,7 @@ export async function startHttpServer(options = {}) {
     // Client sends as application/json Blob (non-CORS-safelisted, so cross-origin sendBeacon is blocked)
     app.post('/api/flush', (req, res) => {
         try {
-            if (isAgentLocked()) {
+            if (isAgentLocked(getActiveFilename())) {
                 console.log('[Flush] Blocked (agent write lock active)');
                 res.status(204).end();
                 return;
@@ -394,8 +405,9 @@ export async function startHttpServer(options = {}) {
                 save();
             }
             if (req.body.agentCreated) {
-                setMetadata({ agentCreated: true });
-                save();
+                // In-memory stub registry — not persisted to disk frontmatter.
+                // adr: adr/agent-stub-model.md
+                markAsAgentStub(result.filename);
             }
             broadcastDocumentSwitched(result.document, result.title, result.filename);
             if (req.body.markPending || req.body.agentCreated) {
@@ -614,64 +626,103 @@ export async function startHttpServer(options = {}) {
             res.status(400).json({ error: err.message });
         }
     });
-    // Agent marks
-    app.post('/api/marks', (req, res) => {
+    // Comments (formerly "agent marks")
+    app.post('/api/comments', (req, res) => {
         try {
             const { filename, text, note, nodeId, nodeIds } = req.body;
             if (!filename || !text || !nodeId) {
                 res.status(400).json({ error: 'filename, text, and nodeId are required' });
                 return;
             }
-            const mark = addMark(filename, text, note || '', nodeId, nodeIds);
-            broadcastMarksChanged(filename);
-            res.json({ success: true, mark });
+            const comment = addComment(filename, text, note || '', nodeId, nodeIds);
+            broadcastCommentsChanged(filename);
+            res.json({ success: true, comment });
         }
         catch (err) {
             res.status(500).json({ error: err.message });
         }
     });
-    app.get('/api/marks/:filename', (req, res) => {
+    app.get('/api/comments/:filename', (req, res) => {
         try {
-            const marks = getMarks(req.params.filename);
-            res.json({ marks: marks[req.params.filename] || [] });
+            const byFile = getComments(req.params.filename);
+            res.json({ comments: byFile[req.params.filename] || [] });
         }
         catch (err) {
             res.status(500).json({ error: err.message });
         }
     });
-    app.patch('/api/marks', (req, res) => {
+    app.patch('/api/comments', (req, res) => {
         try {
             const { filename, id, note } = req.body;
             if (!filename || !id || typeof note !== 'string') {
                 res.status(400).json({ error: 'filename, id, and note are required' });
                 return;
             }
-            const mark = editMark(filename, id, note);
-            if (!mark) {
-                res.status(404).json({ error: 'mark not found' });
+            const comment = editComment(filename, id, note);
+            if (!comment) {
+                res.status(404).json({ error: 'comment not found' });
+                return;
+            }
+            broadcastCommentsChanged(filename);
+            res.json({ success: true, comment });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // Permanently delete comments. Different from /resolve — this is the
+    // "remove this record" path; resolve is the "addressed, archive it" path.
+    app.delete('/api/comments', (req, res) => {
+        try {
+            const { ids } = req.body;
+            if (!Array.isArray(ids)) {
+                res.status(400).json({ error: 'ids must be an array' });
                 return;
             }
-            broadcastMarksChanged(filename);
-            res.json({ success: true, mark });
+            const deleted = deleteComments(ids);
+            const activeFilename = getActiveFilename();
+            broadcastCommentsChanged(activeFilename);
+            res.json({ success: true, deleted });
         }
         catch (err) {
             res.status(500).json({ error: err.message });
         }
     });
-    app.delete('/api/marks', (req, res) => {
+    // Mark comments as resolved (state change, not deletion). The records
+    // stay on disk; only the decoration disappears.
+    app.post('/api/comments/resolve', (req, res) => {
         try {
             const { ids } = req.body;
             if (!Array.isArray(ids)) {
                 res.status(400).json({ error: 'ids must be an array' });
                 return;
             }
-            const resolved = resolveMarks(ids);
+            const resolved = resolveComments(ids);
+            const activeFilename = getActiveFilename();
+            broadcastCommentsChanged(activeFilename);
             res.json({ success: true, resolved });
         }
         catch (err) {
             res.status(500).json({ error: err.message });
         }
     });
+    // Clear the resolved flag — the comment surfaces again and re-decorates.
+    app.post('/api/comments/unresolve', (req, res) => {
+        try {
+            const { ids } = req.body;
+            if (!Array.isArray(ids)) {
+                res.status(400).json({ error: 'ids must be an array' });
+                return;
+            }
+            const cleared = unresolveComments(ids);
+            const activeFilename = getActiveFilename();
+            broadcastCommentsChanged(activeFilename);
+            res.json({ success: true, cleared });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
     // Mount workspace CRUD + doc/container routes
     app.use(createWorkspaceRouter({ broadcastWorkspacesChanged }));
     // Mount link-doc routes (create-link-doc, auto-tag-link)

package/dist/server/logger.js

@@ -0,0 +1,246 @@
+/**
+ * Structured event logger for openwriter.
+ *
+ * Architectural model:
+ *   - One JSON-per-line file at `~/.openwriter/profiles/<profile>/events.log`.
+ *     One file (not per-category) so grep/jq covers everything in one place.
+ *   - Levels: error < warn < info < debug < trace. Default `error` — safe
+ *     for public installs. Travis's machine overrides to `trace` via
+ *     `~/.openwriter/log-config.json`.
+ *   - Document text is redacted unless `includeText: true` is set in the
+ *     config file. Public users never have text content land in logs.
+ *   - Request IDs flow through async chains via AsyncLocalStorage. One
+ *     external trigger (MCP tool call, WS message) gets one ID; every
+ *     event emitted while processing inherits it. "What did this request
+ *     cause" is a single jq query.
+ *   - 50 MB rotation, keep last 5. No manual cleanup ever needed.
+ *   - File handle owned by us (not stdout) so logs survive MCP kill+
+ *     restart. The current `diagnostic.log` proved this works.
+ *
+ * Public users see: errors only, no text, small file, share freely for
+ * bug reports without privacy concern. Travis sees: everything, with text.
+ *
+ * adr: adr/logging-system.md
+ */
+import { existsSync, mkdirSync, statSync, renameSync, unlinkSync, appendFileSync, readFileSync, watch } from 'fs';
+import { join } from 'path';
+import { AsyncLocalStorage } from 'async_hooks';
+import { homedir } from 'os';
+import { getDataDir } from './helpers.js';
+const LEVEL_RANK = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+    trace: 4,
+};
+// ============================================================================
+// CONFIG
+// ============================================================================
+const CONFIG_PATH = join(homedir(), '.openwriter', 'log-config.json');
+const DEFAULT_CONFIG = {
+    level: 'error', // safe-for-public: errors only
+    includeText: false, // safe-for-public: no document content
+};
+let currentConfig = { ...DEFAULT_CONFIG };
+let configWatcher = null;
+function readConfig() {
+    if (!existsSync(CONFIG_PATH))
+        return { ...DEFAULT_CONFIG };
+    try {
+        const raw = readFileSync(CONFIG_PATH, 'utf-8');
+        const data = JSON.parse(raw);
+        const level = (typeof data.level === 'string' && data.level in LEVEL_RANK) ? data.level : DEFAULT_CONFIG.level;
+        const includeText = data.includeText === true;
+        return { level, includeText };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+/** Initialize the logger. Reads config file, sets up live-reload watcher. */
+export function initLogger() {
+    currentConfig = readConfig();
+    // Live-reload on config changes — flip verbosity without restarting.
+    if (existsSync(CONFIG_PATH)) {
+        try {
+            configWatcher?.close();
+            configWatcher = watch(CONFIG_PATH, { persistent: false }, () => {
+                const next = readConfig();
+                const changed = next.level !== currentConfig.level || next.includeText !== currentConfig.includeText;
+                currentConfig = next;
+                if (changed) {
+                    // Log the config change itself so it's traceable in the log.
+                    writeEvent({
+                        ts: new Date().toISOString(),
+                        level: 'info',
+                        category: 'state',
+                        event: 'log-config-reloaded',
+                        fields: { level: next.level, includeText: next.includeText },
+                    });
+                }
+            });
+        }
+        catch { /* best-effort */ }
+    }
+}
+export function getLogConfig() {
+    return { ...currentConfig };
+}
+// ============================================================================
+// REQUEST ID CONTEXT
+// ============================================================================
+const requestContext = new AsyncLocalStorage();
+/** Generate a short, greppable request ID. */
+export function generateRequestId(prefix) {
+    return `${prefix}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/** Run an async chain with a request ID attached. Every log call within
+ *  fn (and its async descendants) automatically inherits the requestId. */
+export function withRequestId(requestId, fn) {
+    return requestContext.run({ requestId }, fn);
+}
+/** Current request ID, if any. Undefined outside a withRequestId scope. */
+export function getCurrentRequestId() {
+    return requestContext.getStore()?.requestId;
+}
+// ============================================================================
+// TEXT REDACTION
+// ============================================================================
+/** Wrap any text content that should be redacted in public logs. When
+ *  `includeText: true` in config, returns the original. Otherwise returns
+ *  `<redacted:Nchars>`. Use this for any document text excerpt before
+ *  passing it to a log call's `fields`. */
+export function redactText(text) {
+    if (text == null)
+        return '<null>';
+    if (currentConfig.includeText)
+        return text;
+    return `<redacted:${text.length}chars>`;
+}
+// ============================================================================
+// FILE I/O + ROTATION
+// ============================================================================
+const MAX_FILE_BYTES = 50 * 1024 * 1024; // 50 MB
+const KEEP_ROTATIONS = 5;
+function getLogPath() {
+    return join(getDataDir(), 'events.log');
+}
+function ensureLogDir() {
+    const dir = getDataDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+}
+function rotateIfNeeded() {
+    const path = getLogPath();
+    if (!existsSync(path))
+        return;
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        return;
+    }
+    if (size < MAX_FILE_BYTES)
+        return;
+    try {
+        // Shift events.log.4 → .5 → discard, .3 → .4, ..., .log → .log.1
+        for (let i = KEEP_ROTATIONS; i >= 1; i--) {
+            const oldPath = i === 1 ? path : `${path}.${i - 1}`;
+            const newPath = `${path}.${i}`;
+            if (existsSync(oldPath)) {
+                if (i === KEEP_ROTATIONS && existsSync(newPath)) {
+                    try {
+                        unlinkSync(newPath);
+                    }
+                    catch { /* best-effort */ }
+                }
+                if (existsSync(oldPath)) {
+                    try {
+                        renameSync(oldPath, newPath);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+        }
+    }
+    catch { /* best-effort */ }
+}
+function writeEvent(evt) {
+    try {
+        ensureLogDir();
+        rotateIfNeeded();
+        appendFileSync(getLogPath(), JSON.stringify(evt) + '\n');
+    }
+    catch { /* logging must never throw — swallow */ }
+}
+// ============================================================================
+// CORE LOG FUNCTIONS
+// ============================================================================
+function shouldLog(level) {
+    // Errors always log regardless of level (a crash trace is non-negotiable).
+    if (level === 'error')
+        return true;
+    return LEVEL_RANK[level] <= LEVEL_RANK[currentConfig.level];
+}
+function log(level, category, event, msg, fields, err) {
+    if (!shouldLog(level))
+        return;
+    const evt = {
+        ts: new Date().toISOString(),
+        level,
+        category,
+        event,
+    };
+    const reqId = getCurrentRequestId();
+    if (reqId)
+        evt.requestId = reqId;
+    if (msg)
+        evt.msg = msg;
+    if (fields && Object.keys(fields).length > 0)
+        evt.fields = fields;
+    if (err)
+        evt.err = { message: err.message, stack: err.stack };
+    writeEvent(evt);
+}
+export const logger = {
+    error(category, event, msg, fields, err) {
+        log('error', category, event, msg, fields, err);
+    },
+    warn(category, event, msg, fields) {
+        log('warn', category, event, msg, fields);
+    },
+    info(category, event, msg, fields) {
+        log('info', category, event, msg, fields);
+    },
+    debug(category, event, msg, fields) {
+        log('debug', category, event, msg, fields);
+    },
+    trace(category, event, msg, fields) {
+        log('trace', category, event, msg, fields);
+    },
+};
+// ============================================================================
+// MIGRATION SHIM — `diagLog` callsites get a clean migration path
+// ============================================================================
+/** Legacy shim — preserves the diagLog(line) API but routes through the
+ *  structured logger as a plain `info`-level event. New code should use
+ *  `logger.info/warn/etc(category, event, ...)` directly. */
+export function diagLog(line) {
+    // Categorize based on prefix heuristics for free re-tagging.
+    let category = 'state';
+    if (line.startsWith('[Overlay]'))
+        category = 'overlay';
+    else if (line.startsWith('[WS]'))
+        category = 'ws';
+    else if (line.startsWith('[Lock]'))
+        category = 'lock';
+    else if (line.startsWith('[MCP]'))
+        category = 'mcp';
+    else if (line.startsWith('[Save]') || line.startsWith('[Disk]'))
+        category = 'save';
+    else if (line.startsWith('[Watch]') || line.startsWith('[fs.watch]'))
+        category = 'watch';
+    logger.info(category, 'legacy-diag', line);
+}

package/dist/server/markdown-parse.js

@@ -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.