openwriter 0.14.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();
@@ -245,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;
@@ -391,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) {
@@ -611,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;
             }
-            broadcastMarksChanged(filename);
-            res.json({ success: true, mark });
+            broadcastCommentsChanged(filename);
+            res.json({ success: true, comment });
         }
         catch (err) {
             res.status(500).json({ error: err.message });
         }
     });
-    app.delete('/api/marks', (req, res) => {
+    // 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;
             }
-            const resolved = resolveMarks(ids);
+            const deleted = deleteComments(ids);
+            const activeFilename = getActiveFilename();
+            broadcastCommentsChanged(activeFilename);
+            res.json({ success: true, deleted });
+        }
+        catch (err) {
+            res.status(500).json({ error: err.message });
+        }
+    });
+    // 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 = 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-serialize.js

@@ -137,16 +137,19 @@ function collectBlockIds(doc) {
  */
 export function tiptapToMarkdown(doc, title, metadata) {
     const meta = { ...metadata, title };
-    // Collect pending state from node attrs into frontmatter
-    const pendingState = collectPendingState(doc);
-    if (pendingState) {
-        meta.pending = pendingState;
-    }
-    else {
-        delete meta.pending;
-    }
+    // Disk is canonical only — never emit `pending:` frontmatter. Pending
+    // state lives in the sidecar at `_pending/{docId}.json`, separated from
+    // the .md file so external markdown editors see clean canonical content.
+    //
+    // If the caller passed a doc that still has in-memory pending attrs,
+    // serialize from a reverted clone so the body is canonical. Callers
+    // that have already done the split (writeToDisk's overlay path) pass
+    // an already-canonical doc; this revert is a no-op for them.
+    // adr: adr/pending-overlay-model.md
+    delete meta.pending;
+    const canonicalDoc = revertPendingForSerialization(doc);
     // Collect node identity graph (id + fingerprint per block) for next-load matcher
-    const nodes = collectNodesFrontmatter(doc);
+    const nodes = collectNodesFrontmatter(canonicalDoc);
     if (nodes.length > 0) {
         meta.nodes = nodes;
     }
@@ -169,12 +172,58 @@ export function tiptapToMarkdown(doc, title, metadata) {
             delete meta[key];
     }
     const frontmatter = `---\n${JSON.stringify(meta)}\n---\n\n`;
-    const body = nodesToMarkdown(doc.content || []);
+    // Serialize the body from the canonical (reverted) clone — never from the
+    // pending-modified live doc, otherwise the on-disk body would contain
+    // rewritten prose without the original anywhere to revert to.
+    const body = nodesToMarkdown(canonicalDoc.content || []);
     return frontmatter + body;
 }
-/** Convert TipTap document to markdown body only (no frontmatter). */
+/** Convert TipTap document to markdown body only (no frontmatter).
+ *  Like tiptapToMarkdown, the body is canonical (pending reverted). */
 export function tiptapToBody(doc) {
-    return nodesToMarkdown(doc.content || []);
+    const canonicalDoc = revertPendingForSerialization(doc);
+    return nodesToMarkdown(canonicalDoc.content || []);
+}
+/**
+ * Deep clone of `doc` with pending decorations reverted, used by the
+ * markdown serializer to ensure disk content is canonical. Mirrors
+ * state.cloneWithPendingReverted but is local to the serializer to
+ * avoid a state.ts → markdown-serialize.ts cycle.
+ *
+ * - status='insert' → drop the node
+ * - status='rewrite' → restore from pendingOriginalContent (or drop if absent)
+ * - status='delete' → keep but clear pending attrs
+ * - no status → keep, strip stray pending attrs
+ */
+const PENDING_KEYS = ['pendingStatus', 'pendingOriginalContent', 'pendingGroupId', 'pendingTextEdits', 'pendingSelectionFrom', 'pendingSelectionTo', 'pendingOriginalFrom', 'pendingOriginalTo', 'pendingOrphan', 'pendingStaleBaseline'];
+function revertPendingForSerialization(doc) {
+    function clean(node) {
+        const clone = JSON.parse(JSON.stringify(node));
+        if (clone.attrs) {
+            for (const k of PENDING_KEYS)
+                delete clone.attrs[k];
+        }
+        if (clone.content)
+            clone.content = walk(clone.content);
+        return clone;
+    }
+    function walk(nodes) {
+        const result = [];
+        for (const node of nodes || []) {
+            const status = node?.attrs?.pendingStatus;
+            if (status === 'insert')
+                continue;
+            if (status === 'rewrite') {
+                const original = node.attrs?.pendingOriginalContent;
+                if (original)
+                    result.push(clean(original));
+                continue;
+            }
+            result.push(clean(node));
+        }
+        return result;
+    }
+    return { type: 'doc', content: walk(doc?.content || []) };
 }
 function nodesToMarkdown(nodes) {
     let result = '';
@@ -275,28 +324,76 @@ function taskListToMarkdown(items, indent) {
     }
     return result + '\n';
 }
+/**
+ * Serialize a TipTap table node to GFM markdown.
+ *
+ * Critical invariants (each one's absence causes silent table → paragraph
+ * loss on round-trip — observed live as `sync-check FAIL: expected table,
+ * got paragraph` on the Beat Sheet doc):
+ *
+ *   1. ALWAYS emit the header-separator row `| --- | --- |` after the first
+ *      row, regardless of whether any cell is a `tableHeader`. GFM table
+ *      recognition requires the delimiter row — without it, markdown-it
+ *      parses each `| ... |` line as a paragraph and the entire table is
+ *      dropped. (One-time consequence: a header-less table's first row
+ *      becomes `tableHeader` cells after the first round-trip. Stable
+ *      thereafter.)
+ *
+ *   2. Escape `|` inside cell text as `\|` so it doesn't terminate the cell
+ *      column.
+ *
+ *   3. Collapse multi-paragraph cells with `<br>` joiners. The inline
+ *      cell format can't represent multiple block paragraphs; without
+ *      collapsing, only the first paragraph round-trips and the rest are
+ *      silently lost.
+ *
+ *   4. Ensure a blank line precedes the table block (caller does `\n\n`
+ *      tailing on prior nodes; we keep the leading newline minimal).
+ */
 function tableToMarkdown(node) {
     const rows = node.content || [];
     if (rows.length === 0)
         return '';
+    function cellContentToText(cell) {
+        const content = cell.content || [];
+        if (content.length === 0)
+            return '';
+        // Each cell typically holds one paragraph, but a TipTap table can carry
+        // multi-paragraph cells (and arbitrary blocks). Concatenate paragraphs
+        // with <br> so no inline content is dropped.
+        const parts = [];
+        for (const child of content) {
+            if (child.type === 'paragraph') {
+                parts.push(inlineToMarkdown(child.content));
+            }
+            else if (child.content) {
+                // Non-paragraph block (rare in tables) — fall through to inline.
+                parts.push(inlineToMarkdown(child.content));
+            }
+        }
+        // Escape pipes and replace newlines with <br>.
+        return parts.join('<br>').replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+    }
     const lines = [];
-    let isFirstRow = true;
-    for (const row of rows) {
+    const firstRowCells = rows[0]?.content || [];
+    const columnCount = firstRowCells.length;
+    for (let r = 0; r < rows.length; r++) {
+        const row = rows[r];
         const cells = row.content || [];
-        const cellTexts = cells.map((cell) => {
-            const para = cell.content?.[0];
-            return para ? inlineToMarkdown(para.content) : '';
-        });
+        const cellTexts = cells.map(cellContentToText);
+        // Pad short rows so the markdown table has consistent column count.
+        while (cellTexts.length < columnCount)
+            cellTexts.push('');
         lines.push(`| ${cellTexts.join(' | ')} |`);
-        if (isFirstRow) {
-            const hasHeaders = cells.some((c) => c.type === 'tableHeader');
-            if (hasHeaders) {
-                lines.push(`| ${cellTexts.map(() => '---').join(' | ')} |`);
-            }
-            isFirstRow = false;
+        if (r === 0) {
+            // ALWAYS emit the separator — GFM parsing requires it for table
+            // recognition. This is the load-bearing invariant.
+            lines.push(`| ${Array(columnCount).fill('---').join(' | ')} |`);
         }
     }
-    return lines.join('\n') + '\n\n';
+    // Leading blank line ensures we're not glued to the prior block (which
+    // would cause the table to be consumed as a paragraph continuation).
+    return '\n' + lines.join('\n') + '\n\n';
 }
 // ---- Inline mark serialization ----
 const SERIALIZED_MARKS = ['bold', 'italic', 'code', 'strike', 'underline', 'highlight', 'subscript', 'superscript', 'link'];