openwriter 0.6.1 → 0.6.3

package/dist/server/install-skill.js

@@ -112,6 +112,16 @@ export function installSkill() {
     fs.mkdirSync(targetDir, { recursive: true });
     fs.copyFileSync(source, target);
     log(`  ✓ Skill installed to ${target}`);
+    // Copy docs/ directory (welcome doc, etc.)
+    const docsSource = path.join(__dirname, '../../skill/docs');
+    const docsTarget = path.join(targetDir, 'docs');
+    if (fs.existsSync(docsSource)) {
+        fs.mkdirSync(docsTarget, { recursive: true });
+        for (const file of fs.readdirSync(docsSource)) {
+            fs.copyFileSync(path.join(docsSource, file), path.join(docsTarget, file));
+        }
+        log(`  ✓ Skill docs copied to ${docsTarget}`);
+    }
     // Step 2: Global install (skip if already installed)
     const alreadyInstalled = isGloballyInstalled();
     if (alreadyInstalled) {

package/dist/server/markdown-serialize.js

@@ -215,7 +215,9 @@ export function inlineToMarkdown(nodes) {
         }
         if (node.type !== 'text')
             continue;
-        const targetMarks = (node.marks || []).filter((m) => SERIALIZED_MARKS.includes(m.type));
+        const targetMarks = (node.marks || [])
+            .filter((m) => SERIALIZED_MARKS.includes(m.type))
+            .sort((a, b) => SERIALIZED_MARKS.indexOf(a.type) - SERIALIZED_MARKS.indexOf(b.type));
         // Find common prefix of marks between open and target
         let commonLen = 0;
         while (commonLen < openMarks.length && commonLen < targetMarks.length) {

package/dist/server/state.js

@@ -3,7 +3,7 @@
  * Each document is a .md file in ~/.openwriter/ with YAML frontmatter.
  * Title lives in frontmatter metadata. Filenames are stable identifiers.
  */
-import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, readdirSync, statSync, utimesSync } from 'fs';
 import { join } from 'path';
 import matter from 'gray-matter';
 import { tiptapToMarkdown, markdownToTiptap } from './markdown.js';
@@ -984,6 +984,23 @@ function cleanupEmptyTempFiles() {
     catch { /* ignore errors during cleanup */ }
 }
 // ============================================================================
+// MTIME HELPERS (preserve file modification time for metadata-only writes)
+// ============================================================================
+function safeGetMtime(filePath) {
+    try {
+        return statSync(filePath).mtime;
+    }
+    catch {
+        return null;
+    }
+}
+function safeRestoreMtime(filePath, mtime) {
+    try {
+        utimesSync(filePath, new Date(), mtime);
+    }
+    catch { /* best-effort */ }
+}
+// ============================================================================
 // DOCUMENT-LEVEL TAG OPERATIONS
 // ============================================================================
 /** Get tags for the active document from its metadata. */
@@ -1023,7 +1040,11 @@ export function addDocTag(filename, tag) {
         if (!tags.includes(tag)) {
             tags.push(tag);
             state.metadata.tags = tags;
+            // Preserve mtime — tag changes shouldn't affect sidebar sort order
+            const mtime = state.filePath ? safeGetMtime(state.filePath) : null;
             save();
+            if (mtime && state.filePath)
+                safeRestoreMtime(state.filePath, mtime);
         }
     }
     else {
@@ -1038,8 +1059,11 @@ export function addDocTag(filename, tag) {
             if (!tags.includes(tag)) {
                 tags.push(tag);
                 parsed.metadata.tags = tags;
+                const mtime = safeGetMtime(targetPath);
                 const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
                 atomicWriteFileSync(targetPath, markdown);
+                if (mtime)
+                    safeRestoreMtime(targetPath, mtime);
             }
         }
         catch { /* best-effort */ }
@@ -1056,7 +1080,11 @@ export function removeDocTag(filename, tag) {
         if (idx >= 0) {
             tags.splice(idx, 1);
             state.metadata.tags = tags.length > 0 ? tags : undefined;
+            // Preserve mtime — tag changes shouldn't affect sidebar sort order
+            const mtime = state.filePath ? safeGetMtime(state.filePath) : null;
             save();
+            if (mtime && state.filePath)
+                safeRestoreMtime(state.filePath, mtime);
         }
     }
     else {
@@ -1071,8 +1099,11 @@ export function removeDocTag(filename, tag) {
             if (idx >= 0) {
                 tags.splice(idx, 1);
                 parsed.metadata.tags = tags.length > 0 ? tags : undefined;
+                const mtime = safeGetMtime(targetPath);
                 const markdown = tiptapToMarkdown(parsed.document, parsed.title, parsed.metadata);
                 atomicWriteFileSync(targetPath, markdown);
+                if (mtime)
+                    safeRestoreMtime(targetPath, mtime);
             }
         }
         catch { /* best-effort */ }

package/dist/server/ws.js

@@ -46,10 +46,41 @@ export function setupWebSocket(server) {
     });
     // Push agent changes to all browser clients
     onChanges((changes) => {
-        const msg = JSON.stringify({ type: 'node-changes', changes });
-        for (const ws of clients) {
-            if (ws.readyState === WebSocket.OPEN) {
-                ws.send(msg);
+        // Check if changes include HR nodes in a tweet thread document.
+        // Tweet editors don't support horizontalRule in their schema, so individual
+        // node-changes with HRs silently fail. Send a full document resync instead,
+        // which triggers splitContentAtHr in TweetComposeView to create new editors.
+        const metadata = getMetadata();
+        const isTweetThread = metadata?.tweetContext != null;
+        const hasHrChange = isTweetThread && changes.some((c) => {
+            if (!c.content)
+                return false;
+            const contentArr = Array.isArray(c.content) ? c.content : [c.content];
+            return contentArr.some((n) => n.type === 'horizontalRule');
+        });
+        if (hasHrChange) {
+            const doc = getDocument();
+            console.log(`[WS] HR detected in tweet thread → sending document-switched (${doc?.content?.length || 0} nodes)`);
+            const filePath = getFilePath();
+            const filename = filePath ? filePath.split(/[/\\]/).pop() || '' : '';
+            const msg = JSON.stringify({
+                type: 'document-switched',
+                document: getDocument(),
+                title: getTitle(),
+                filename,
+                docId: getDocId(),
+                metadata,
+            });
+            for (const ws of clients) {
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.send(msg);
+            }
+        }
+        else {
+            const msg = JSON.stringify({ type: 'node-changes', changes });
+            for (const ws of clients) {
+                if (ws.readyState === WebSocket.OPEN)
+                    ws.send(msg);
             }
         }
         // Notify browser of updated pending docs list (debounced)
@@ -85,8 +116,11 @@ export function setupWebSocket(server) {
             try {
                 const msg = JSON.parse(data.toString());
                 if (msg.type === 'doc-update' && msg.document) {
+                    const docContent = msg.document?.content || [];
+                    const nodeCount = docContent.length;
+                    const currentNodeCount = getDocument()?.content?.length || 0;
                     if (isAgentLocked()) {
-                        // Agent write in progress — ignore browser doc-updates
+                        console.log(`[WS] doc-update BLOCKED by agent lock (browser: ${nodeCount} nodes, server: ${currentNodeCount} nodes)`);
                     }
                     else if (msg.filename && msg.filename !== getActiveFilename()) {
                         // Browser sent a doc-update for a different document (race: server switched away).
@@ -94,6 +128,7 @@ export function setupWebSocket(server) {
                         saveDocToFile(msg.filename, msg.document);
                     }
                     else {
+                        console.log(`[WS] doc-update ACCEPTED (browser: ${nodeCount} nodes, server: ${currentNodeCount} nodes)`);
                         updateDocument(msg.document);
                         updatePendingCacheForActiveDoc(); // Keep cache in sync after browser edits/reject-all
                         debouncedSave();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.server.json",
-    "prepublishOnly": "cp ../../skills/openwriter/SKILL.md skill/SKILL.md",
+    "prepublishOnly": "node -e \"const fs=require('fs'),p=require('path');fs.copyFileSync(p.resolve('../../skills/openwriter/SKILL.md'),'skill/SKILL.md');fs.mkdirSync('skill/docs',{recursive:true});fs.copyFileSync(p.resolve('../../skills/openwriter/docs/welcome.md'),'skill/docs/welcome.md')\"",
     "preview": "node dist/bin/pad.js",
     "lint": "eslint src server bin --ext .ts,.tsx"
   },

package/skill/SKILL.md

@@ -15,7 +15,7 @@ description: |
   Requires: OpenWriter MCP server configured. Browser UI at localhost:5050.
 metadata:
   author: travsteward
-  version: "0.2.0"
+  version: "0.2.3"
   repository: https://github.com/travsteward/openwriter
 license: MIT
 ---
@@ -41,6 +41,15 @@ The user already has OpenWriter configured. You're good to go.
 **First action:** Share the browser URL:
 > OpenWriter is at **http://localhost:5050** — open it in your browser to see and review changes.
 
+**Onboarding (first use only):** Call `list_documents`. If the workspace is empty (zero documents), create a welcome doc to orient the user:
+
+1. Read the welcome template from this skill's `docs/welcome.md`
+2. `create_document` with title "Welcome to OpenWriter"
+3. `populate_document` with the template content (arrives as pending changes — green highlights)
+4. Tell the user: "I've created a welcome doc in your browser. Check it out — the green highlights are my changes. Use the review panel to accept or reject them."
+
+This teaches the user the core workflow (pending changes, review panel) by experiencing it. After the first run, docs exist and this step is skipped forever.
+
 Skip to [Writing Strategy](#writing-strategy) below.
 
 ### MCP tools are NOT available (needs setup)
@@ -182,6 +191,7 @@ For making changes to existing documents — rewrites, insertions, deletions:
 - Respect `pendingChanges > 0` — wait for the user to accept/reject before sending more
 - Content accepts markdown strings (preferred) or TipTap JSON
 - Decoration colors: **blue** = rewrite, **green** = insert, **red** = delete
+- **Never re-populate a document to fix it.** `populate_document` re-sends the entire document body — extremely token-expensive. To remove nodes, use `write_to_pad` with `{ operation: "delete", nodeId: "..." }`. To fix content, use `rewrite`. Only use `populate_document` once during initial creation, or as a last resort if the document is severely broken.
 
 ### Creating New Documents (two-step flow)
 
@@ -362,6 +372,72 @@ This restores the normal editor view and removes the "x" tag.
 
 Users set their X handle by clicking the avatar circle in the compose area. The handle is saved to localStorage and the pfp loads from `unavatar.io/twitter/{handle}`.
 
+### Creating Tweet Threads
+
+Threads are single documents with `horizontalRule` nodes separating each tweet. The compose view splits at HRs into separate tweet editors.
+
+**Critical: threads MUST use TipTap JSON, not markdown.** Markdown `---` does NOT create proper `horizontalRule` nodes — the thread will render as a single tweet.
+
+```
+1. create_document({ title: "Thread title" })
+2. set_metadata({ tweetContext: { mode: "tweet" } })
+3. populate_document({ tpiTapJson: {
+     type: "doc",
+     content: [
+       { type: "paragraph", content: [{ type: "text", text: "Tweet 1 text" }] },
+       { type: "horizontalRule" },
+       { type: "paragraph", content: [{ type: "text", text: "Tweet 2 text" }] },
+       { type: "horizontalRule" },
+       { type: "paragraph", content: [{ type: "text", text: "Tweet 3 text" }] }
+     ]
+   }})
+```
+
+### Paragraph Spacing in Tweets
+
+Tweet compose uses `<br>` (hardBreak) for line breaks within a paragraph. Double Enter in the browser creates a new `<p>` node (paragraph split) with visual spacing.
+
+**For agents writing via `write_to_pad`:** use separate paragraph nodes for paragraph spacing. Each paragraph gets its own node ID, enabling independent editing.
+
+```
+// Correct: separate paragraph nodes for paragraph spacing
+write_to_pad({ docId: "...", changes: [
+  { operation: "insert", afterNodeId: "end", content: "First paragraph of tweet." },
+  { operation: "insert", afterNodeId: "end", content: "Second paragraph — separate node, visual gap." }
+]})
+```
+
+For line breaks WITHIN a single paragraph (no gap), use TipTap JSON with hardBreak:
+
+```
+{
+  type: "paragraph",
+  content: [
+    { type: "text", text: "Line one" },
+    { type: "hardBreak" },
+    { type: "text", text: "Line two (same node, no gap)" }
+  ]
+}
+```
+
+This applies to all tweet modes — single tweets, replies, quotes, and individual tweets within threads.
+
+### Inserting Images into Thread Tweets
+
+After creating a thread, use `read_pad` to get node IDs, then `insert_image` to add images after specific tweets:
+
+```
+1. read_pad()                    → shows [p:abc123] for each tweet paragraph
+2. insert_image({
+     docId: "...",
+     afterNodeId: "abc123",      ← paragraph node ID from read_pad
+     prompt: "...",
+     aspect_ratio: "16:9"
+   })
+```
+
+All `insert_image` calls can run **in parallel** — no dependencies between them. Images appear with green pending decorations for user review.
+
 ## Review Etiquette
 
 1. **Share the URL.** Always tell the user: http://localhost:5050

package/skill/docs/welcome.md

@@ -0,0 +1,21 @@
+# Welcome to OpenWriter
+
+What you're looking at right now is how we collaborate. These green highlights are my proposed changes — I write, you review. Use the review panel on the right to navigate (j/k), accept (a), or reject (r) each change. Try it now.
+
+## Create Documents
+
+Hit the **+** button in the sidebar to create different document types: blog posts, newsletters, tweets, LinkedIn posts, and articles. Each type has its own compose view tailored to that format. Or just ask me to write something and I'll create the right doc type for you.
+
+## Workspaces
+
+Organize your documents into workspaces with containers and tags. This is especially powerful for book writing — each chapter is a document, grouped into sections as containers. I can see your full workspace structure and work across multiple docs.
+
+## Plugins
+
+**Author's Voice** — Feed me your writing samples and I'll write in your voice. Not an approximation — I pull your actual patterns, cadence, and word choices from your corpus.
+
+**Publish** — Send newsletters to your subscriber list, post to X/Twitter, publish blog posts to GitHub, and schedule content. All from inside the editor, no copy-pasting to other platforms.
+
+## What's Next
+
+Ask me to write something. A blog post, a tweet thread, a newsletter — whatever you're working on. I'll create a doc for it and we'll iterate together.