tandem-editor 0.7.1 → 0.9.0

package/README.md

@@ -6,8 +6,6 @@ Have you ever been working on a piece of writing with an LLM and caught yourself
 
 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.
@@ -29,7 +27,7 @@ Requires **Node.js 22+** ([download](https://nodejs.org)) and **Claude Code** (`
 ```bash
 npm install -g tandem-editor
 tandem setup     # registers MCP tools + installs Claude Code skill
-tandem           # starts server + opens browser
+tandem           # starts server + opens editor
 ```
 
 `tandem setup` auto-detects Claude Code and Claude Desktop, writes MCP configuration, and installs a skill (`~/.claude/skills/tandem/SKILL.md`) that teaches Claude how to use Tandem's tools effectively. Re-run after upgrading (`npm update -g tandem-editor && tandem setup`).
@@ -73,7 +71,7 @@ claude --dangerously-load-development-channels server:tandem-channel
 
 This is the magic-sauce mode — and it's the one I'd recommend you run with. The channel shim pushes events (selections, annotations, chat) to Claude over SSE the moment they happen, so Tandem genuinely feels like there's another person on the other end of the document: someone watching what you highlight, reacting to edits you accept, and chiming in on a paragraph the instant you select it, the way a collaborator on a Google Doc would. The `--dangerously-load-development-channels` flag is an experimental Claude Code feature, which is why it isn't on by default — but turning it on is what makes the whole experience click.
 
-**Recommended layout:** snap the Claude Code terminal to one side of your screen and the Tandem browser window to the other. You'll be flipping attention between them constantly, and having both visible is what makes the side-by-side-collaborator feeling land.
+**Recommended layout:** snap the Claude Code terminal to one side of your screen and the Tandem editor window to the other. You'll be flipping attention between them constantly, and having both visible is what makes the side-by-side-collaborator feeling land.
 
 Then try:
 
@@ -81,11 +79,11 @@ Then try:
 "Open sample/welcome.md and review it with me"
 ```
 
-Claude calls `tandem_open`, the document appears in the browser, and you're ready to collaborate.
+Claude calls `tandem_open`, the document appears in the editor, and you're ready to collaborate.
 
 #### The core loop — no copy/paste
 
-1. Highlight a paragraph in the browser editor.
+1. Highlight a paragraph in the editor.
 2. With channels on, Claude often reacts before you even say anything. Otherwise, just type what you want in the terminal: *"what do you think of this paragraph?"* or *"rewrite this to be more concise"*.
 3. Claude reads your selection directly from the shared Tandem state (via `activity.selectedText` on `tandem_checkInbox`). You never paste the passage into the terminal.
 4. Claude replies in the Tandem chat sidebar (`tandem_reply`) or drops annotations on the document (`tandem_annotate` / `tandem_suggestEdit`), which you can accept, dismiss, or edit in the side panel.
@@ -119,7 +117,7 @@ Or check the raw health endpoint:
 
 ```bash
 curl http://localhost:3479/health
-# → {"status":"ok","version":"0.4.0","transport":"http","hasSession":false}
+# → {"status":"ok","version":"0.8.0","transport":"http","hasSession":false}
 ```
 
 `hasSession` becomes `true` once Claude Code connects.
@@ -131,7 +129,7 @@ curl http://localhost:3479/health
 git clone https://github.com/bloknayrb/tandem.git
 cd tandem
 npm install
-npm run dev:standalone   # starts server (:3478/:3479) + browser client (:5173)
+npm run dev:standalone   # starts server (:3478/:3479) + editor client (:5173)
 ```
 
 Open http://localhost:5173 — you'll see `sample/welcome.md` loaded automatically on first run. The `.mcp.json` in the repo configures Claude Code automatically when run from this directory.
@@ -142,7 +140,7 @@ Open http://localhost:5173 — you'll see `sample/welcome.md` loaded automatical
 
 You point at text, Claude sees it. Here's how that plays out day-to-day:
 
-- **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.
+- **Open a document.** Ask Claude (`"let's work on notes.md in tandem"`), drag a file onto the editor, 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.
@@ -154,20 +152,14 @@ Everything in Tandem is built around one idea: you work in the document, Claude
 
 ### Chat
 
-![Chat sidebar showing messages, typing indicator, and panel toggle](docs/screenshots/02-chat-sidebar.png)
-
 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
 
-![Review mode with dimmed editor and active annotation highlighted](docs/screenshots/05-review-mode.png)
-
 Press **Ctrl+Shift+R** to enter keyboard review mode. Navigate with **Tab**, accept with **Y**, dismiss with **N**, examine with **E**. A 10-second undo window with a visual countdown lets you reverse accidental accepts. Shortcut hints appear below the Review button.
 
 ### More
@@ -183,42 +175,52 @@ Press **Ctrl+Shift+R** to enter keyboard review mode. Navigate with **Tab**, acc
 - **Configurable display name** — set your name so Claude knows who's reviewing
 - **Atomic file saves** — write to temp, then rename, preventing partial writes
 - **E2E tested** — Playwright tests cover the annotation lifecycle end-to-end
+- **Authorship text coloring** — blue for your edits, orange for Claude's, toggled per-document
+- **Threaded annotation replies** — back-and-forth conversation on any annotation
+- **Auto-save** — documents save on change; Ctrl+S for manual trigger
+- **Settings popover** — Light/Dark/System theme, text size (S/M/L), reduce motion, display name (Ctrl+,)
+- **Auth tokens for LAN exposure** — bind to `0.0.0.0` with auto-generated tokens; `tandem rotate-token` for rotation
+- **Durable annotation persistence** — annotations survive server restarts independently of session files
+- **Claude Code plugin** — `tandem mcp-stdio` + `tandem channel` bridge Tandem into Cowork and Claude Desktop
 
 ## Where Tandem is headed
 
-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:
+Since the v0.4.0 desktop app launch, Tandem has added auth tokens for LAN exposure (v0.7.0), a Claude Code plugin bridge for Cowork and Claude Desktop (v0.6.0+), durable annotation persistence, settings with Light/Dark/System theming, authorship text coloring, and coordinate system correctness fixes with semantic token enforcement (v0.8.0). A few directions on the radar for later releases:
 
-- **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.
+- **High-fidelity .docx round-trip** — current `.docx` support is review-only; production export is planned so you can stay in Tandem through the final draft.
 - **Exportable annotated documents** — PDF (and eventually `.docx`) with annotations baked in, so you can share reviewed drafts outside Tandem.
 - **Code editing mode** — CodeMirror 6 surface for reviewing code the same way you review prose.
-- **Standalone mode** — direct Anthropic API connection so Tandem can run without Claude Code in the loop, for users who want a pure browser-based experience.
+- **Standalone mode** — direct Anthropic API connection so Tandem can run without Claude Code in the loop, for users who want a pure standalone experience.
 
 See the full [Roadmap](docs/roadmap.md) and [Known Limitations](docs/roadmap.md#known-limitations-v1) for the complete picture, including items that are explicitly out of scope for v1.
 
 ## 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) — 31 MCP tools + channel API endpoints
+- **[User Guide](docs/user-guide.md)** — How to use Tandem: editor UI, annotations, chat, review mode, keyboard shortcuts
+- [MCP Tool Reference](docs/mcp-tools.md) — 28 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: 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-022
-- [Lessons Learned](docs/lessons-learned.md) — 37 implementation lessons
+- [Design Decisions](docs/decisions.md) — ADR-001 through ADR-024
+- [Lessons Learned](docs/lessons-learned.md) — 48 implementation lessons
 
 ## CLI Commands
 
 | Command | What it does |
 |---------|-------------|
-| `tandem` | Start server and open browser (global install) |
+| `tandem` | Start server and open editor (global install) |
 | `tandem setup` | Register MCP tools with Claude Code / Claude Desktop |
 | `tandem setup --force` | Register to default paths regardless of auto-detection |
 | `tandem --version` | Show installed version |
 | `tandem --help` | Show usage |
+| `tandem setup --with-channel-shim` | Also register the stdio channel shim |
+| `tandem rotate-token` | Rotate auth token (60-second grace window) |
+| `tandem mcp-stdio` | Run as stdio MCP server (proxy to local HTTP, for plugin bridge) |
+| `tandem channel` | Run the channel shim (stdio MCP for plugin's tandem-channel entry) |
 
 ## MCP Configuration
 
-Tandem registers two MCP connections: **HTTP** for document tools (30 tools including annotation editing — always on), and a **channel shim** for real-time push notifications. The channel shim is what enables the live-collaborator experience described in [Connect Claude Code](#connect-claude-code) and is recommended; it activates when you start Claude Code with `--dangerously-load-development-channels server:tandem-channel`. If you'd rather not pass that experimental flag, the entry sits idle and everything still works through polling on the HTTP connection — you just lose spontaneous reactions.
+Tandem registers two MCP connections: **HTTP** for document tools (28 tools including annotation editing — always on), and a **channel shim** for real-time push notifications. The channel shim is what enables the live-collaborator experience described in [Connect Claude Code](#connect-claude-code) and is recommended; it activates when you start Claude Code with `--dangerously-load-development-channels server:tandem-channel`. If you'd rather not pass that experimental flag, the entry sits idle and everything still works through polling on the HTTP connection — you just lose spontaneous reactions.
 
 **Global install** (`tandem setup`): Automatically writes both entries to `~/.claude/mcp_settings.json` (Claude Code) and/or `claude_desktop_config.json` (Claude Desktop) with absolute paths. No manual configuration needed.
 
@@ -254,6 +256,13 @@ All optional — defaults work out of the box.
 | `TANDEM_TRANSPORT` | `http` | Transport mode (`http` or `stdio`) |
 | `TANDEM_NO_SAMPLE` | unset | Set to `1` to skip auto-opening `sample/welcome.md` |
 | `TANDEM_CLAUDE_CMD` | `claude` | Claude Code executable name (for `tandem setup` auto-detection) |
+| `TANDEM_BIND_HOST` | `127.0.0.1` | Bind address for MCP HTTP (`0.0.0.0` for LAN) |
+| `TANDEM_AUTH_TOKEN` | auto-generated | Override auth token (set by Tauri; manual use rare) |
+| `TANDEM_ALLOW_UNAUTHENTICATED_LAN` | unset | Set to `1` to skip token requirement on LAN bind |
+| `TANDEM_LAN_IP` | auto-detected | Explicit LAN IP for multi-homed machines |
+| `TANDEM_REQUEST_TIMEOUT_MS` | `30000` | Per-request timeout in stdio bridge (ms) |
+| `TANDEM_APP_DATA_DIR` | platform default | Override app-data root (sessions, auth-token, annotations) |
+| `TANDEM_ANNOTATION_STORE` | unset | Set to `off` to disable durable annotation persistence |
 
 See `.env.example` for a copy-paste template.
 
@@ -270,10 +279,10 @@ Tandem kills stale processes on :3478/:3479 at startup. If another app uses thos
 **Channel shim fails to start**
 The `tandem-channel` entry spawns a subprocess. For global installs, `tandem setup` writes absolute paths to the bundled `dist/channel/index.js` — re-run `tandem setup` after upgrading. For dev setup, if you see `MODULE_NOT_FOUND` with a production config (`node dist/channel/index.js`), run `npm run build`. The default dev config uses `npx tsx` and doesn't require a build step.
 
-**Browser shows "Cannot reach the Tandem server"**
-The browser connects to the server via WebSocket. For global installs, run `tandem` to start the server. For dev setup, use `npm run dev:standalone` (or `npm run dev:server`). The message appears after 3 seconds of failed connection.
+**Editor shows "Cannot reach the Tandem server"**
+The editor connects to the server via WebSocket. For global installs, run `tandem` to start the server. For dev setup, use `npm run dev:standalone` (or `npm run dev:server`). The message appears after 3 seconds of failed connection.
 
-**Empty browser with no document**
+**Empty editor with no document**
 On first run, `sample/welcome.md` auto-opens. If you've cleared sessions or deleted the sample file, click the **+** button in the tab bar or drop a file onto the editor.
 
 ## Development

package/dist/channel/index.js

@@ -17945,7 +17945,7 @@ async function authFetch(url, init) {
   return fetch(url, init);
 }
 
-// src/server/events/types.ts
+// src/shared/events/types.ts
 var VALID_EVENT_TYPES = /* @__PURE__ */ new Set([
   "annotation:created",
   "annotation:accepted",
@@ -18005,6 +18005,7 @@ function formatEventContent(event) {
     }
     default: {
       const _exhaustive = event;
+      void _exhaustive;
       return `Unknown event${doc}`;
     }
   }
@@ -18034,6 +18035,7 @@ function formatEventMeta(event) {
       break;
     default: {
       const _exhaustive = event;
+      void _exhaustive;
       break;
     }
   }
@@ -18103,7 +18105,11 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
         status: "idle",
         active: false
       })
-    }).catch(() => {
+    }).catch((err) => {
+      console.error(
+        "[Channel] clearAwareness failed (non-fatal):",
+        err instanceof Error ? err.message : err
+      );
     });
   }
   function flushAwareness() {
@@ -18149,11 +18155,21 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
       try {
         event = parseTandemEvent(JSON.parse(data));
       } catch {
-        console.error("[Channel] Malformed SSE event data (skipping):", data.slice(0, 200));
+        console.error(
+          "[Channel] Malformed SSE event data (skipping), eventId=%s:",
+          eventId,
+          data.slice(0, 200)
+        );
+        if (eventId) onEventId(eventId);
         continue;
       }
       if (!event) {
-        console.error("[Channel] Received invalid SSE event, skipping");
+        console.error(
+          "[Channel] Invalid SSE event structure (skipping), eventId=%s:",
+          eventId,
+          data.slice(0, 200)
+        );
+        if (eventId) onEventId(eventId);
         continue;
       }
       if (event.type !== "chat:message") {
@@ -18164,7 +18180,6 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
           continue;
         }
       }
-      if (eventId) onEventId(eventId);
       try {
         await mcp.notification({
           method: "notifications/claude/channel",
@@ -18177,6 +18192,7 @@ async function connectAndStream(mcp, tandemUrl, lastEventId, onEventId) {
         console.error("[Channel] MCP notification failed (transport broken?):", err);
         throw err;
       }
+      if (eventId) onEventId(eventId);
       scheduleAwareness(event);
     }
   }