tandem-editor 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to Tandem will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-04-13
+
+### Added
+
+- **Authorship tracking** — Y.Map overlay marks text as user-written or Claude-written, with text-color styling (blue for user, orange for Claude) (#190)
+- **Threaded annotation replies** — reply to annotations with back-and-forth conversation threads (#187)
+- **Claude cursor decoration** — character-level cursor shows where Claude is editing in real time (#209)
+- **Auto-save** — documents save automatically on change; Ctrl+S triggers immediate manual save (#272)
+- **Text zoom** — keyboard shortcuts (Ctrl+=/Ctrl+-) for adjusting text size in the Tauri desktop app (#273)
+- **Three-panel default layout** — editor, side panel, and chat visible by default (#264)
+- **Selection event suppression** — selection events only fire after a chat message is sent, reducing noise (#270)
+- V1.0 release plan added to roadmap (#279)
+
+### Fixed
+
+- Session persistence, tab bar horizontal scrollbar, and tab cycling keyboard shortcuts (#278)
+- Authorship styling uses text color instead of background highlight; reopen sync corrected
+- Annotation replies renamed from Acknowledge/Dismiss to Accept/Reject for clarity
+
+### Changed
+
+- Pinned Hocuspocus and Y.js dependency versions to prevent upstream breakage (#271)
+- EOL normalizer added to lint-staged for .yml and .md files (#263)
+- Lessons learned applied to codebase and tooling (#280)
+
 ## [0.4.0] - 2026-04-12
 
 ### Added

package/README.md

@@ -2,18 +2,29 @@
   <img src="docs/assets/banner.png" alt="Tandem — Collaborative AI-Human Document Editor" width="800">
 </p>
 
-Have you ever been working on a document (or any multi-paragraph piece of text) with Claude and wondered aloud, "Why isn't there an easier way to do this?" Well look no further, because now there is! My goal with this was to try to create an experience kind of similar to editing a Google doc with another person except that that other person is Claude Code. 
+Have you ever been working on a piece of writing with an LLM and caught yourself copy-pasting the same paragraph into the chat for the fifth time just so the model knows what you're talking about? That's the friction Tandem eliminates. Open a file directly, or just tell Claude "let's work on my draft in tandem" — the document appears in the editor, and from that point on you highlight text and Claude sees it directly. No pasting, no "here's the paragraph I mean," no losing your place.
+
+And because Tandem hooks into Claude as an MCP server, you're not stuck in some stripped-down document-editing silo. It's the full Claude — with all its knowledge, your conversation context, and every tool it has access to — just now it can also see and edit your document.
 
 ![Tandem editor showing a document with annotations, side panel, and Claude's presence](docs/screenshots/01-editor-overview.png)
 
+## Why Tandem?
+
+- **No more copy-paste ping-pong.** Select text in the editor, and Claude reads your selection directly. Ask "what do you think of this?" or "make this more concise" — Claude knows exactly which text you mean.
+- **Your full LLM, not a toy editor.** Tandem connects via MCP, so Claude keeps all its knowledge, all its tools, and your full conversation context. Need it to cross-reference your document against a codebase, a URL, or another file? It can — it's still Claude.
+- **Iterate in place.** Claude can suggest rewrites, leave comments, flag issues, and edit text — all appearing as annotations you accept, dismiss, or tweak right in the document.
+
 ## Quick Start
 
-### Prerequisites
+### Option A: Desktop App
+
+Download the installer for your platform from the [latest release](https://github.com/bloknayrb/tandem/releases/latest).
 
-- **Node.js 22+** ([download](https://nodejs.org))
-- **Claude Code** (`irm https://claude.ai/install.ps1 | iex`)
+The desktop app bundles everything — no Node.js required. It auto-configures Claude Code on launch, manages the server as a background process, and updates itself automatically. Just install and open.
 
-### Install and Run
+### Option B: npm Global Install
+
+Requires **Node.js 22+** ([download](https://nodejs.org)) and **Claude Code** (`npm install -g @anthropic-ai/claude-code`).
 
 ```bash
 npm install -g tandem-editor
@@ -27,6 +38,8 @@ tandem           # starts server + opens browser
 
 For the full Tandem experience, start Claude Code with the **channel push** flag:
 
+> **Desktop app users:** Claude Code is configured automatically on every launch — skip `tandem setup` and just start Claude Code. The `tandem_*` tools will be available immediately.
+
 ```bash
 claude --dangerously-load-development-channels server:tandem-channel
 ```
@@ -79,7 +92,7 @@ Or check the raw health endpoint:
 
 ```bash
 curl http://localhost:3479/health
-# → {"status":"ok","version":"0.3.0","transport":"http","hasSession":false}
+# → {"status":"ok","version":"0.4.0","transport":"http","hasSession":false}
 ```
 
 `hasSession` becomes `true` once Claude Code connects.
@@ -100,27 +113,29 @@ Open http://localhost:5173 — you'll see `sample/welcome.md` loaded automatical
 
 ## Using Tandem
 
-A one-minute mental model of the daily loop:
+You point at text, Claude sees it. Here's how that plays out day-to-day:
 
-- **Open a document.** Ask Claude (`"open notes.md"`), drag a file onto the browser, or click the **+** in the tab bar. `.md`, `.txt`, `.html`, and `.docx` (review-only) are supported.
-- **Talk about specific text.** Select it in the browser editor, then ask Claude about "this paragraph" in the terminal. Claude reads your selection from `tandem_checkInbox` — no copy/paste. Hold the selection still for about a second so it registers (dwell-time gating filters out incidental clicks).
-- **Review what Claude suggests.** Annotations appear in the side panel. Press **Ctrl+Shift+R** to enter keyboard review mode: **Tab** to navigate, **Y** accept, **N** dismiss, **E** edit, **Z** undo within a 10-second window.
+- **Open a document.** Ask Claude (`"let's work on notes.md in tandem"`), drag a file onto the browser, or click the **+** in the tab bar. `.md`, `.txt`, `.html`, and `.docx` (review-only) are supported.
+- **Point at what you mean.** Select text in the editor and ask Claude about "this paragraph" in the terminal — or just wait for Claude to react if you have channels on. Claude reads your selection directly, no copy-paste needed. Hold the selection for about a second so it registers (dwell-time gating filters out incidental clicks).
+- **Iterate on Claude's response.** Claude's suggestions appear as annotations in the side panel — accept, dismiss, edit, or ask follow-up questions. Each round refines the text without you ever leaving the document. Press **Ctrl+Shift+R** for keyboard review mode: **Tab** to navigate, **Y** accept, **N** dismiss, **E** edit, **Z** undo within a 10-second window.
 - **Heads-down vs collaborative.** Toggle **Solo** mode when you want to write without interruptions — Tandem queues non-urgent annotations until you flip back to **Tandem** mode. Both `tandem_status` and `tandem_checkInbox` return the current mode so Claude adapts its behavior automatically.
 - **Save.** Ask Claude ("save the file"), press the save button, or let session auto-persistence take over — your documents and annotations survive server restarts either way.
 
 ## Features
 
-### Annotations
-
-![Side panel showing annotation cards with filtering, bulk actions, and text previews](docs/screenshots/03-side-panel.png)
-
-Claude adds highlights, comments, suggestions, and flags directly in the document. Suggestion cards show a visual diff — original text in red strikethrough, replacement in green. The side panel lists all annotations with filtering by type, author, and status. Accept, dismiss, or edit each one individually — or use bulk actions to process them in batches.
+Everything in Tandem is built around one idea: you work in the document, Claude works alongside you, and neither of you has to leave your surface to stay in sync.
 
 ### Chat
 
 ![Chat sidebar showing messages, typing indicator, and panel toggle](docs/screenshots/02-chat-sidebar.png)
 
-Send freeform messages to Claude alongside annotation review. Select text before sending to attach it as a clickable anchor — clicking it later scrolls back to that passage.
+Send messages to Claude alongside your document. Select text before sending to attach it as context — Claude sees exactly what you mean. Clicking an anchored selection later scrolls back to that passage.
+
+### Annotations
+
+![Side panel showing annotation cards with filtering, bulk actions, and text previews](docs/screenshots/03-side-panel.png)
+
+This is how Claude's feedback shows up in the document. Claude adds highlights, comments, suggestions, and flags directly on the text. Suggestion cards show a visual diff — original text in red strikethrough, replacement in green. The side panel lists all annotations with filtering by type, author, and status. Accept, dismiss, or edit each one individually — or use bulk actions to process them in batches.
 
 ### Review Mode
 
@@ -130,11 +145,11 @@ Press **Ctrl+Shift+R** to enter keyboard review mode. Navigate with **Tab**, acc
 
 ### More
 
+- **Full LLM via MCP** — Claude connects through MCP tools, so it retains all its knowledge, conversation context, and tool access while working on your document
 - **Multi-document tabs** — open `.md`, `.txt`, `.html`, `.docx` files side by side; drag to reorder
 - **.docx review-only mode** — open Word documents for annotation; imported Word comments appear alongside Claude's
 - **Session persistence** — documents and annotations survive server restarts
 - **Solo / Tandem mode** — flip to Solo when you want to write heads-down; Tandem queues non-urgent annotations until you're ready
-- **Selection-aware chat** — highlight text in the browser, ask Claude about "this" in the terminal; Claude reads your selection directly, no copy/paste
 - **Real-time channel push** *(recommended)* — with the `--dangerously-load-development-channels` Claude Code flag, selections, annotations, and chat push to Claude instantly, making Tandem feel like a live collaborator watching over your shoulder
 - **Keyboard shortcuts** — press `?` for the full reference
 - **Unsaved-changes indicator** — dot on tab title when a document has pending edits
@@ -144,9 +159,8 @@ Press **Ctrl+Shift+R** to enter keyboard review mode. Navigate with **Tab**, acc
 
 ## Where Tandem is headed
 
-Tandem v1 covers the core loop well — single user editing prose with Claude, with `.md`/`.txt`/`.html` round-trip and `.docx` review. A few directions on the radar for later releases:
+Tandem v0.4.0 ships a native desktop app (macOS, Linux, Windows) alongside the existing npm CLI. A few directions on the radar for later releases:
 
-- **Progressive Web App** — install Tandem from the browser for a real app window, taskbar icon, and offline-capable shell.
 - **High-fidelity .docx round-trip** — current `.docx` support is review-only; LibreOffice-headless-based production export is planned so you can stay in Tandem through the final draft.
 - **Claude Desktop parity** — the MCP server already works with Claude Desktop; polish and documentation for a first-class experience there is in the works.
 - **Exportable annotated documents** — PDF (and eventually `.docx`) with annotations baked in, so you can share reviewed drafts outside Tandem.
@@ -158,12 +172,12 @@ See the full [Roadmap](docs/roadmap.md) and [Known Limitations](docs/roadmap.md#
 ## Documentation
 
 - **[User Guide](docs/user-guide.md)** — How to use Tandem: browser UI, annotations, chat, review mode, keyboard shortcuts
-- [MCP Tool Reference](docs/mcp-tools.md) — 30 MCP tools + channel API endpoints
+- [MCP Tool Reference](docs/mcp-tools.md) — 31 MCP tools + channel API endpoints
 - [Architecture](docs/architecture.md) — System design, data flows, coordinate systems, channel push
-- [Workflows](docs/workflows.md) — Claude Code usage patterns: document review, cross-referencing, multi-model
+- [Workflows](docs/workflows.md) — Claude Code usage patterns: text iteration, cross-referencing, multi-model
 - [Roadmap](docs/roadmap.md) — Phase 2+ roadmap, known issues, future extensions
-- [Design Decisions](docs/decisions.md) — ADR-001 through ADR-021
-- [Lessons Learned](docs/lessons-learned.md) — 31 implementation lessons
+- [Design Decisions](docs/decisions.md) — ADR-001 through ADR-022
+- [Lessons Learned](docs/lessons-learned.md) — 37 implementation lessons
 
 ## CLI Commands
 
@@ -246,5 +260,9 @@ On first run, `sample/welcome.md` auto-opens. If you've cleared sessions or dele
 | `npm test` | Run vitest (unit tests) |
 | `npm run test:e2e` | Run Playwright E2E tests |
 | `npm run test:e2e:ui` | Playwright UI mode |
+| `cargo tauri dev` | Tauri desktop app (dev mode with hot-reload) |
+| `cargo tauri build` | Tauri production build (installer output) |
+
+**Tauri development** requires the [Rust toolchain](https://www.rust-lang.org/tools/install) and [Tauri CLI](https://v2.tauri.app/start/prerequisites/). Web-only development (`npm run dev:standalone`) does not require Rust.
 
 **Tech Stack:** React 19, Tiptap, Vite, TypeScript | Node.js, Hocuspocus (Yjs WebSocket), MCP SDK, Express | Yjs (CRDT), y-prosemirror | mammoth.js (.docx), unified/remark (.md)

package/dist/channel/index.js

@@ -17920,8 +17920,8 @@ var VALID_EVENT_TYPES = /* @__PURE__ */ new Set([
   "annotation:created",
   "annotation:accepted",
   "annotation:dismissed",
+  "annotation:reply",
   "chat:message",
-  "selection:changed",
   "document:opened",
   "document:closed",
   "document:switched"
@@ -17949,15 +17949,17 @@ function formatEventContent(event) {
       const { annotationId, textSnippet } = event.payload;
       return `User dismissed annotation ${annotationId}${textSnippet ? ` ("${textSnippet}")` : ""}${doc}`;
     }
+    case "annotation:reply": {
+      const { annotationId, replyAuthor, replyText, textSnippet } = event.payload;
+      const who = replyAuthor === "claude" ? "Claude" : "User";
+      const snippet = textSnippet ? ` (on "${textSnippet}")` : "";
+      return `${who} replied to annotation ${annotationId}${snippet}: ${replyText}${doc}`;
+    }
     case "chat:message": {
-      const { text, replyTo } = event.payload;
+      const { text, replyTo, selection } = event.payload;
       const reply = replyTo ? ` (replying to ${replyTo})` : "";
-      return `User says${reply}: ${text}${doc}`;
-    }
-    case "selection:changed": {
-      const { from, to, selectedText } = event.payload;
-      if (!selectedText) return `User cleared selection${doc}`;
-      return `User is pointing at text (${from}-${to}): "${selectedText}"${doc} \u2014 respond via tandem_reply`;
+      const sel = selection && selection.selectedText ? ` [selection: "${selection.selectedText}"${"from" in selection ? ` (${selection.from}-${selection.to})` : ""}]` : "";
+      return `User says${reply}: ${text}${sel}${doc}`;
     }
     case "document:opened": {
       const { fileName, format } = event.payload;
@@ -17988,11 +17990,13 @@ function formatEventMeta(event) {
     case "annotation:dismissed":
       meta.annotation_id = event.payload.annotationId;
       break;
+    case "annotation:reply":
+      meta.annotation_id = event.payload.annotationId;
+      meta.reply_id = event.payload.replyId;
+      break;
     case "chat:message":
       meta.message_id = event.payload.messageId;
-      break;
-    case "selection:changed":
-      meta.respond_via = "tandem_reply";
+      if (event.payload.selection?.selectedText) meta.has_selection = "true";
       break;
     case "document:opened":
     case "document:closed":
@@ -18008,7 +18012,6 @@ function formatEventMeta(event) {
 
 // src/channel/event-bridge.ts
 var AWARENESS_DEBOUNCE_MS = 500;
-var SELECTION_DEBOUNCE_MS = 300;
 var MODE_CACHE_TTL_MS = 2e3;
 async function startEventBridge(mcp2, tandemUrl) {
   let retries = 0;
@@ -18096,35 +18099,7 @@ async function connectAndStream(mcp2, tandemUrl, lastEventId, onEventId) {
     if (awarenessTimer) clearTimeout(awarenessTimer);
     awarenessTimer = setTimeout(flushAwareness, AWARENESS_DEBOUNCE_MS);
   }
-  let selectionTimer = null;
-  let pendingSelection = null;
-  let transportBroken = false;
-  async function flushSelection() {
-    if (!pendingSelection) return;
-    const { event, eventId } = pendingSelection;
-    pendingSelection = null;
-    if (eventId) onEventId(eventId);
-    try {
-      await mcp2.notification({
-        method: "notifications/claude/channel",
-        params: {
-          content: formatEventContent(event),
-          meta: formatEventMeta(event)
-        }
-      });
-    } catch (err) {
-      console.error("[Channel] MCP notification failed (transport broken?):", err);
-      transportBroken = true;
-      return;
-    }
-    scheduleAwareness(event);
-  }
-  function isSelectionCleared(event) {
-    const p = event.payload;
-    return !p || p.from === p.to && !p.selectedText;
-  }
   while (true) {
-    if (transportBroken) throw new Error("MCP transport broken (detected in debounced flush)");
     const { done, value } = await reader.read();
     if (done) throw new Error("SSE stream ended");
     buffer += decoder.decode(value, { stream: true });
@@ -18159,14 +18134,6 @@ async function connectAndStream(mcp2, tandemUrl, lastEventId, onEventId) {
           continue;
         }
       }
-      if (event.type === "selection:changed") {
-        if (eventId) onEventId(eventId);
-        if (isSelectionCleared(event)) continue;
-        pendingSelection = { event, eventId };
-        if (selectionTimer) clearTimeout(selectionTimer);
-        selectionTimer = setTimeout(flushSelection, SELECTION_DEBOUNCE_MS);
-        continue;
-      }
       if (eventId) onEventId(eventId);
       try {
         await mcp2.notification({
@@ -18254,8 +18221,9 @@ var mcp = new Server(
     instructions: [
       'Events from Tandem arrive as <channel source="tandem-channel" event_type="..." document_id="...">.',
       "These are real-time push notifications of user actions in the collaborative document editor.",
-      "Event types: annotation:created, annotation:accepted, annotation:dismissed,",
-      "chat:message, selection:changed, document:opened, document:closed, document:switched.",
+      "Event types: annotation:created, annotation:accepted, annotation:dismissed, annotation:reply,",
+      "chat:message, document:opened, document:closed, document:switched.",
+      "Chat messages may include a 'selection' field with buffered selection context.",
       "Use your tandem MCP tools (tandem_getTextContent, tandem_comment, tandem_highlight, etc.) to act on them.",
       "Reply to chat messages using tandem_reply. Pass document_id from the tag attributes.",
       "Do not reply to non-chat events \u2014 just act on them using tools.",