npm - openwriter - Versions diffs - 0.9.2 → 0.10.0 - Mend

openwriter 0.9.2 → 0.10.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 (15) hide show

package/dist/client/assets/{index-BbzNoMAw.css → index-CuPYxtxy.css} +1 -1
package/dist/client/assets/index-deMuWDiP.js +211 -0
package/dist/client/index.html +2 -2
package/dist/plugins/authors-voice/dist/index.js +13 -11
package/dist/plugins/publish/dist/helpers.d.ts +12 -0
package/dist/plugins/publish/dist/index.js +138 -0
package/dist/plugins/x-api/dist/index.js +23 -2
package/dist/server/documents.js +6 -0
package/dist/server/image-upload.js +35 -0
package/dist/server/index.js +18 -3
package/dist/server/marks.js +9 -2
package/dist/server/state.js +2 -1
package/package.json +1 -1
package/skill/SKILL.md +21 -12
package/dist/client/assets/index-BHiZqytt.js +0 -210

package/dist/client/index.html CHANGED Viewed

@@ -10,8 +10,8 @@
     <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-BHiZqytt.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BbzNoMAw.css">
+    <script type="module" crossorigin src="/assets/index-deMuWDiP.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CuPYxtxy.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/plugins/authors-voice/dist/index.js CHANGED Viewed

@@ -189,16 +189,18 @@ const plugin = {
             { label: 'Fill sentence', action: 'av:fill-sentence', condition: 'empty-node' },
         ];
     },
-    sidebarMenuItems() {
-        return [
-            { label: 'Vary', action: 'voice:vary', promptForFocus: true },
-            { label: 'Shrinkify', action: 'voice:shrinkify', promptForFocus: true },
-            { label: 'Expandify', action: 'voice:expandify', promptForFocus: true },
-            { label: 'Threadify', action: 'voice:threadify', promptForFocus: true },
-            { label: 'Storify', action: 'voice:storify', promptForFocus: true },
-            { label: 'Emailify', action: 'voice:emailify', promptForFocus: true },
-            { label: 'Postify', action: 'voice:postify', promptForFocus: true },
-        ];
-    },
+    // Sidebar transforms disabled — now handled by publish plugin.
+    // Kept commented for reference during transition.
+    // sidebarMenuItems() {
+    //   return [
+    //     { label: 'Vary', action: 'voice:vary', promptForFocus: true },
+    //     { label: 'Shrinkify', action: 'voice:shrinkify', promptForFocus: true },
+    //     { label: 'Expandify', action: 'voice:expandify', promptForFocus: true },
+    //     { label: 'Threadify', action: 'voice:threadify', promptForFocus: true },
+    //     { label: 'Storify', action: 'voice:storify', promptForFocus: true },
+    //     { label: 'Emailify', action: 'voice:emailify', promptForFocus: true },
+    //     { label: 'Postify', action: 'voice:postify', promptForFocus: true },
+    //   ];
+    // },
 };
 export default plugin;

package/dist/plugins/publish/dist/helpers.d.ts CHANGED Viewed

@@ -22,13 +22,25 @@ export interface PluginMcpTool {
     inputSchema: Record<string, unknown>;
     handler: (params: Record<string, unknown>) => Promise<unknown>;
 }
+export interface PluginRouteContext {
+    app: import('express').Router;
+    config: Record<string, string>;
+    dataDir: string;
+}
+export interface PluginSidebarMenuItem {
+    label: string;
+    action: string;
+    promptForFocus?: boolean;
+}
 export interface OpenWriterPlugin {
     name: string;
     version: string;
     description?: string;
     category?: 'writing' | 'social-media' | 'image-generation' | 'publishing' | 'productivity' | 'analytics';
     configSchema?: Record<string, PluginConfigField>;
+    registerRoutes?(ctx: PluginRouteContext): void | Promise<void>;
     mcpTools?(config: Record<string, string>): PluginMcpTool[];
+    sidebarMenuItems?(): PluginSidebarMenuItem[];
 }
 export declare const md: MarkdownIt;
 /** Strip YAML frontmatter and TipTap empty markers from markdown output */

package/dist/plugins/publish/dist/index.js CHANGED Viewed

@@ -2,6 +2,41 @@ import { getServerModules, publishFetch } from './helpers.js';
 import { newsletterTools } from './newsletter-tools.js';
 import { readFileSync, existsSync } from 'fs';
 import { join, extname } from 'path';
+/** Extract docId from raw markdown frontmatter (JSON or YAML) */
+function extractDocId(rawContent) {
+    // JSON frontmatter: "docId":"abc123"
+    const jsonMatch = rawContent.match(/"docId"\s*:\s*"([^"]+)"/);
+    if (jsonMatch)
+        return jsonMatch[1];
+    // YAML frontmatter: docId: abc123
+    const yamlMatch = rawContent.match(/^docId:\s*["']?(\S+?)["']?\s*$/m);
+    if (yamlMatch)
+        return yamlMatch[1];
+    return null;
+}
+/** Map transform action to variant content type */
+const ACTION_VARIANT_TYPE = {
+    vary: 'document',
+    shrinkify: 'document',
+    expandify: 'document',
+    threadify: 'tweet',
+    storify: 'document',
+    emailify: 'newsletter',
+    postify: 'tweet',
+};
+/** Simple HTML → markdown conversion for document creation */
+function htmlToMarkdown(html) {
+    let md = html;
+    md = md.replace(/<hr\s*\/?>/gi, '\n---\n');
+    md = md.replace(/<br\s*\/?>/gi, '\n');
+    md = md.replace(/<(strong|b)>([\s\S]*?)<\/\1>/gi, '**$2**');
+    md = md.replace(/<(em|i)>([\s\S]*?)<\/\1>/gi, '*$2*');
+    md = md.replace(/<p[^>]*>/gi, '');
+    md = md.replace(/<\/p>/gi, '\n\n');
+    md = md.replace(/<[^>]+>/g, '');
+    md = md.replace(/\n{3,}/g, '\n\n');
+    return md.trim();
+}
 const plugin = {
     name: '@openwriter/plugin-publish',
     version: '0.1.0',
@@ -988,5 +1023,108 @@ const plugin = {
             },
         ];
     },
+    registerRoutes(ctx) {
+        // Sidebar action handler for document transforms
+        ctx.app.post('/api/publish/sidebar-action', async (req, res) => {
+            try {
+                const { action, filename, title, instructions, content } = req.body;
+                console.log(`[Publish Plugin] Sidebar action: ${action} on "${title}"`);
+                if (!content) {
+                    res.status(400).json({ error: 'Document content is required' });
+                    return;
+                }
+                // Call publish worker /transforms endpoint
+                const transformRes = await publishFetch(ctx.config, '/transforms', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ action, content, title, instructions }),
+                });
+                if (!transformRes.ok) {
+                    const errData = await transformRes.json().catch(() => ({}));
+                    console.error('[Publish Plugin] Transform failed:', transformRes.status, errData);
+                    res.status(transformRes.status).json(errData);
+                    return;
+                }
+                const transformResult = await transformRes.json();
+                // Convert HTML output to markdown for document creation
+                let markdownContent = htmlToMarkdown(transformResult.html);
+                // Extract source doc's docId for variant relationship
+                const masterDocId = extractDocId(content);
+                const variantType = ACTION_VARIANT_TYPE[action] || 'document';
+                // Build document creation payload
+                const createBody = {
+                    title: transformResult.newTitle,
+                    content: markdownContent,
+                    markPending: true,
+                    agentCreated: true,
+                    ...(masterDocId ? { masterDocId, variantType } : {}),
+                };
+                if (action === 'threadify') {
+                    // Build TipTap JSON directly — markdown parser converts "- item" lines
+                    // to bulletList nodes the tweet editor can't render. Using paragraph +
+                    // hardBreak nodes keeps all tweet text as plain text.
+                    if (transformResult.thread?.tweets?.length) {
+                        const docContent = [];
+                        transformResult.thread.tweets.forEach((t, i) => {
+                            const lines = t.text.split('\n');
+                            const nodes = [];
+                            lines.forEach((line, j) => {
+                                if (j > 0)
+                                    nodes.push({ type: 'hardBreak' });
+                                if (line)
+                                    nodes.push({ type: 'text', text: line });
+                            });
+                            if (nodes.length) {
+                                docContent.push({ type: 'paragraph', content: nodes });
+                            }
+                            if (i < transformResult.thread.tweets.length - 1) {
+                                docContent.push({ type: 'horizontalRule' });
+                            }
+                        });
+                        createBody.content = { type: 'doc', content: docContent };
+                    }
+                    createBody.metadata = { tweetContext: { mode: 'tweet' } };
+                }
+                // Create new document via internal HTTP call
+                const host = req.get('host') || 'localhost:5050';
+                const protocol = req.protocol || 'http';
+                const createUrl = `${protocol}://${host}/api/documents`;
+                const createRes = await fetch(createUrl, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify(createBody),
+                });
+                if (!createRes.ok) {
+                    const errData = await createRes.json().catch(() => ({}));
+                    console.error('[Publish Plugin] Document creation failed:', errData);
+                    res.status(500).json({ error: 'Failed to create result document' });
+                    return;
+                }
+                const docResult = await createRes.json();
+                res.json({
+                    success: true,
+                    action,
+                    filename: docResult.filename,
+                    title: transformResult.newTitle,
+                    metadata: transformResult.metadata,
+                });
+            }
+            catch (err) {
+                console.error('[Publish Plugin] Sidebar action error:', err?.message || err);
+                res.status(500).json({ error: 'Sidebar action failed' });
+            }
+        });
+    },
+    sidebarMenuItems() {
+        return [
+            { label: 'Vary', action: 'publish:vary', promptForFocus: true },
+            { label: 'Shrinkify', action: 'publish:shrinkify', promptForFocus: true },
+            { label: 'Expandify', action: 'publish:expandify', promptForFocus: true },
+            { label: 'Threadify', action: 'publish:threadify', promptForFocus: true },
+            { label: 'Storify', action: 'publish:storify', promptForFocus: true },
+            { label: 'Emailify', action: 'publish:emailify', promptForFocus: true },
+            { label: 'Postify', action: 'publish:postify', promptForFocus: true },
+        ];
+    },
 };
 export default plugin;

package/dist/plugins/x-api/dist/index.js CHANGED Viewed

@@ -6,6 +6,7 @@
 import { Client, OAuth1 } from '@xdevplatform/xdk';
 import { join, extname } from 'path';
 import { readFileSync, existsSync } from 'fs';
+import sharp from 'sharp';
 import twitter from 'twitter-text';
 const { parseTweet } = twitter;
 function createXClient(config) {
@@ -196,9 +197,19 @@ const plugin = {
                     res.status(400).json({ success: false, error: 'X API credentials not configured' });
                     return;
                 }
-                const mediaBase64 = readFileSync(filePath).toString('base64');
+                let fileBuffer = readFileSync(filePath);
+                let uploadType = mediaType;
+                const origSize = fileBuffer.length;
+                // Compress large images or PNGs to JPEG to stay under X API limits
+                if (fileBuffer.length > 3 * 1024 * 1024 || ext === '.png') {
+                    fileBuffer = Buffer.from(await sharp(fileBuffer).jpeg({ quality: 85 }).toBuffer());
+                    uploadType = 'image/jpeg';
+                    console.log(`[X Plugin] Compressed ${filename}: ${(origSize / 1024 / 1024).toFixed(2)}MB → ${(fileBuffer.length / 1024 / 1024).toFixed(2)}MB`);
+                }
+                console.log(`[X Plugin] Uploading ${filename}: ${(fileBuffer.length / 1024 / 1024).toFixed(2)}MB, type: ${uploadType}`);
+                const mediaBase64 = fileBuffer.toString('base64');
                 const uploadResult = await client.media.upload({
-                    body: { media: mediaBase64, mediaCategory: 'tweet_image', mediaType },
+                    body: { media: mediaBase64, mediaCategory: 'tweet_image', mediaType: uploadType },
                 });
                 const mediaId = uploadResult?.data?.id
                     || uploadResult?.media_id_string;
@@ -211,6 +222,16 @@ const plugin = {
             }
             catch (err) {
                 console.error('[X Plugin] Media upload failed:', err.message);
+                if (err.response) {
+                    try {
+                        const body = await err.response.text();
+                        console.error('[X Plugin] X API response:', err.response.status, body);
+                    }
+                    catch { /* ignore */ }
+                }
+                if (err.data)
+                    console.error('[X Plugin] Error data:', JSON.stringify(err.data));
+                console.error('[X Plugin] Full error:', JSON.stringify(err, Object.getOwnPropertyNames(err)));
                 res.status(500).json({ success: false, error: err.message });
             }
         });

package/dist/server/documents.js CHANGED Viewed

@@ -120,6 +120,8 @@ export function listDocuments() {
                 ...(data.tweetContext?.lastPost?.tweetUrl ? { postedUrl: data.tweetContext.lastPost.tweetUrl } : {}),
                 ...(data.newsletterContext ? { isNewsletter: true } : {}),
                 ...(deriveContentType(data) ? { contentType: deriveContentType(data) } : {}),
+                ...(data.masterDocId ? { masterDocId: data.masterDocId } : {}),
+                ...(data.variantType ? { variantType: data.variantType } : {}),
             };
         }
         catch {
@@ -158,6 +160,8 @@ export function listDocuments() {
                 ...(data.tweetContext?.lastPost?.tweetUrl ? { postedUrl: data.tweetContext.lastPost.tweetUrl } : {}),
                 ...(data.newsletterContext ? { isNewsletter: true } : {}),
                 ...(deriveContentType(data) ? { contentType: deriveContentType(data) } : {}),
+                ...(data.masterDocId ? { masterDocId: data.masterDocId } : {}),
+                ...(data.variantType ? { variantType: data.variantType } : {}),
             });
         }
         catch { /* skip unreadable external files */ }
@@ -217,6 +221,8 @@ export function listArchivedDocuments() {
                 wordCount,
                 isActive: false,
                 ...(data.docId ? { docId: data.docId } : {}),
+                ...(data.masterDocId ? { masterDocId: data.masterDocId } : {}),
+                ...(data.variantType ? { variantType: data.variantType } : {}),
                 archivedAt: data.archivedAt,
             };
         }

package/dist/server/image-upload.js CHANGED Viewed

@@ -54,5 +54,40 @@ export function createImageRouter() {
         const src = `/_images/${req.file.filename}`;
         res.json({ src });
     });
+    // Download external URL and save locally
+    router.post('/api/download-image', async (req, res) => {
+        const { url } = req.body;
+        if (!url || typeof url !== 'string') {
+            res.status(400).json({ error: 'No URL provided' });
+            return;
+        }
+        try {
+            const response = await fetch(url);
+            if (!response.ok) {
+                res.status(400).json({ error: 'Failed to fetch image' });
+                return;
+            }
+            const contentType = response.headers.get('content-type') || 'image/png';
+            if (!contentType.startsWith('image/')) {
+                res.status(400).json({ error: 'URL is not an image' });
+                return;
+            }
+            const ext = contentType.includes('jpeg') || contentType.includes('jpg') ? '.jpg'
+                : contentType.includes('gif') ? '.gif'
+                    : contentType.includes('webp') ? '.webp'
+                        : '.png';
+            ensureImagesDir();
+            const filename = `${randomUUID().slice(0, 8)}${ext}`;
+            const filePath = join(getImagesDir(), filename);
+            const buffer = Buffer.from(await response.arrayBuffer());
+            const { writeFileSync } = await import('fs');
+            writeFileSync(filePath, buffer);
+            const src = `/_images/${filename}`;
+            res.json({ src });
+        }
+        catch {
+            res.status(500).json({ error: 'Download failed' });
+        }
+    });
     return router;
 }

package/dist/server/index.js CHANGED Viewed

@@ -230,6 +230,16 @@ export async function startHttpServer(options = {}) {
                 setMetadata(req.body.metadata);
                 save();
             }
+            // Variant relationship — set masterDocId and variantType in frontmatter
+            if (req.body.masterDocId || req.body.variantType) {
+                const variantMeta = {};
+                if (req.body.masterDocId)
+                    variantMeta.masterDocId = req.body.masterDocId;
+                if (req.body.variantType)
+                    variantMeta.variantType = req.body.variantType;
+                setMetadata(variantMeta);
+                save();
+            }
             // Plugin flags: mark all content as pending + tag as agent-created
             if (req.body.markPending) {
                 markAllNodesAsPending(getDocument(), 'insert');
@@ -460,12 +470,12 @@ export async function startHttpServer(options = {}) {
     // Agent marks
     app.post('/api/marks', (req, res) => {
         try {
-            const { filename, text, note, nodeId } = req.body;
+            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);
+            const mark = addMark(filename, text, note || '', nodeId, nodeIds);
             broadcastMarksChanged(filename);
             res.json({ success: true, mark });
         }
@@ -708,9 +718,14 @@ export async function startHttpServer(options = {}) {
                 }
             }
             catch { /* content stays empty */ }
+            // Extract source doc's docId for variant spinner positioning
+            let sourceDocId;
+            const docIdMatch = docContent.match(/"docId"\s*:\s*"([^"]+)"/);
+            if (docIdMatch)
+                sourceDocId = docIdMatch[1];
             // Show sidebar spinner while plugin processes
             const spinnerTitle = label ? `${label}: ${title}` : title;
-            broadcastWritingStarted(spinnerTitle);
+            broadcastWritingStarted(spinnerTitle, sourceDocId ? { wsFilename: '', containerId: null, parentDocId: sourceDocId } : undefined);
             // Intercept res.json to clear spinner when plugin handler responds
             const origJson = res.json.bind(res);
             res.json = (body) => {

package/dist/server/marks.js CHANGED Viewed

@@ -39,13 +39,14 @@ function writeMarkFile(filename, data) {
     }
     writeFileSync(path, JSON.stringify(data, null, 2));
 }
-export function addMark(filename, text, note, nodeId) {
+export function addMark(filename, text, note, nodeId, nodeIds) {
     const data = readMarkFile(filename);
     const mark = {
         id: randomUUID().slice(0, 8),
         text,
         note,
         nodeId,
+        ...(nodeIds && nodeIds.length > 1 ? { nodeIds } : {}),
         createdAt: new Date().toISOString(),
     };
     data.marks.push(mark);
@@ -150,7 +151,13 @@ export function pruneStaleMarks(filename, validNodeIds) {
         return 0;
     const validSet = new Set(validNodeIds);
     const before = data.marks.length;
-    data.marks = data.marks.filter((m) => validSet.has(m.nodeId));
+    data.marks = data.marks.filter((m) => {
+        // Multi-node mark: keep if ANY nodeId is still valid
+        if (m.nodeIds && m.nodeIds.length > 0) {
+            return m.nodeIds.some((id) => validSet.has(id));
+        }
+        return validSet.has(m.nodeId);
+    });
     const pruned = before - data.marks.length;
     if (pruned > 0)
         writeMarkFile(filename, data);

package/dist/server/state.js CHANGED Viewed

@@ -680,7 +680,8 @@ function applyChangesToDoc(doc, changes) {
             // Tweet thread: hard-delete paragraphs + adjacent HR immediately.
             // Tweet compose view can't handle pending deletes near HRs — hard-delete and resync.
             const delNode = found.parent[found.index];
-            if (delNode.type === 'paragraph' && state.metadata?.tweetContext) {
+            const hardDeleteTypes = ['paragraph', 'image', 'imageLoading'];
+            if (hardDeleteTypes.includes(delNode.type) && state.metadata?.tweetContext) {
                 const idx = found.index;
                 if (idx > 0 && found.parent[idx - 1].type === 'horizontalRule') {
                     found.parent.splice(idx, 1);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",

package/skill/SKILL.md CHANGED Viewed

@@ -16,7 +16,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.4.2"
+  version: "0.4.5"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -402,29 +402,38 @@ Threads are single documents with `horizontalRule` nodes separating each tweet.
 **Do NOT use `populate_document` for threads.** Use `create_document` with `content_type: "tweet"` + `empty: true`, then `write_to_pad` with `horizontalRule` JSON nodes between tweets. The `content_type` flag sets `tweetContext` metadata automatically.
-**Critical: `horizontalRule` separators MUST use TipTap JSON `{ type: "horizontalRule" }`.** Markdown `---` does NOT create proper HR nodes — the thread will render as a single tweet. Tweet text content can be plain markdown strings.
+**THREE RULES for thread HRs:**
+1. **`horizontalRule` separators MUST use TipTap JSON `{ type: "horizontalRule" }`.** Markdown `---` does NOT create proper HR nodes.
+2. **Each HR must be its own change.** Do NOT use content arrays `[{type: "horizontalRule"}, {type: "paragraph", ...}]` — this silently drops the HR.
+3. **Send the ENTIRE thread in ONE `write_to_pad` call.** Do NOT split across multiple calls. Multiple calls create race conditions — if the user accepts changes between calls, pending HRs can be dropped. One call = atomic = no race conditions.
 ```
 1. create_document({ title: "Thread title", content_type: "tweet", empty: true })
 2. write_to_pad({ docId: "<docId>", changes: [
-     { operation: "insert", afterNodeId: "end", content: "Tweet 1 text" },
+     { operation: "insert", afterNodeId: "end", content: "Tweet 1 paragraph 1" },
+     { operation: "insert", afterNodeId: "end", content: "Tweet 1 paragraph 2" },
      { operation: "insert", afterNodeId: "end", content: { type: "horizontalRule" } },
-     { operation: "insert", afterNodeId: "end", content: "Tweet 2 text" },
+     { operation: "insert", afterNodeId: "end", content: "Tweet 2 paragraph 1" },
+     { operation: "insert", afterNodeId: "end", content: "Tweet 2 paragraph 2" },
      { operation: "insert", afterNodeId: "end", content: { type: "horizontalRule" } },
-     { operation: "insert", afterNodeId: "end", content: "Tweet 3 text" }
+     { operation: "insert", afterNodeId: "end", content: "Tweet 3 paragraph 1" }
    ]})
 ```
+**For long threads (many tweets):** still send in ONE call. The changes array can hold dozens of items. Atomicity matters more than streaming feel for threads — a half-built thread with missing HRs is worse than waiting for the full thread to arrive.
 ### Inserting New Tweets into Existing Threads
-**Insert HR + paragraph as ONE change with a content array.** Two separate calls will fail — the browser resyncs on HR insertion and overwrites the second call.
+**Mid-thread insertion is unreliable.** `afterNodeId: "end"` always means document end, not after your last insert. Inserting after specific node IDs mid-document has edge cases with pending changes and image nodes.
-```
-write_to_pad({ docId: "...", changes: [
-  { operation: "insert", afterNodeId: "<last-node-of-previous-tweet>",
-    content: [{ type: "horizontalRule" }, { type: "paragraph", content: [{ type: "text", text: "New tweet" }] }] }
-]})
-```
+**Preferred approach: rebuild the full thread.** Delete the document and recreate with all tweets in one atomic `write_to_pad` call. This is the only pattern that reliably produces correct thread structure.
+**If you must insert mid-thread:** use a single `write_to_pad` call with the HR and all content targeting the same `afterNodeId` (the last node of the preceding tweet). Content inserts in reverse order when sharing an afterNodeId, so list changes in reverse. This is fragile — prefer full rebuild.
+**Do NOT delete empty paragraphs after images.** Images create empty `<p>` nodes after them. These look like junk but HRs (thread separators) are dependent on them. Deleting the empty paragraph kills the HR too, merging two tweets into one. Leave them alone.
+**NEVER bulk-delete text nodes in a thread that contains images.** Image nodes survive text deletion and become orphans — stranded in the wrong position with no surrounding content. The user must then manually delete every orphan image from the browser. This is catastrophic. If you need to reorder tweets, move text around the existing images, or delete the entire document and start fresh (which properly removes everything including images).
 ### Paragraph Spacing in Tweets