@peaske7/readit 0.1.5 → 0.1.6

package/docs/plans/2026-03-13-client-mode-design.md

@@ -0,0 +1,86 @@
+# Client Mode: `readit open`
+
+## Problem
+
+readit starts a long-running server per invocation. When used as a Claude Code PostToolUse hook, every Write/Edit on a `.md` file would spawn a new server instance. We need a way to send files to an already-running server.
+
+## Design
+
+### Overview
+
+Add a `readit open <files...>` CLI command that hot-adds files to a running readit server via HTTP, or starts a new server if none exists. Uses a PID file for server discovery and the existing SSE infrastructure for browser notifications.
+
+### 1. PID File (`~/.readit/server.json`)
+
+**On server start** (in `startServer`):
+```json
+{ "port": 4567, "pid": 12345 }
+```
+
+**On shutdown** (SIGINT handler): delete the file.
+
+**Client discovery:**
+1. Read `~/.readit/server.json`
+2. Verify PID is alive (`process.kill(pid, 0)`)
+3. Confirm via `GET /api/health`
+4. Any failure → treat as no server running
+
+### 2. Server Endpoint: `POST /api/files`
+
+Request body: `{ "path": "/absolute/path/to/file.md" }`
+
+Behavior:
+- **File already loaded** → re-read from disk, update `fileMap` content, broadcast SSE `{ type: "update", path }`
+- **New file** → validate type, read content, add to `fileMap` + `fileOrder`, set up file watcher, broadcast SSE `{ type: "file-added", path, fileName, fileType }`
+
+Response: `200 { path, fileName, type }`
+
+### 3. Frontend: Handle `file-added` SSE Event
+
+The Zustand store's SSE listener handles a new event type:
+- `file-added` → add document to store, render new tab (lazy content fetch via existing pattern)
+
+### 4. CLI Command: `readit open`
+
+```
+readit open <files...>          # Add files to running server or start new one
+```
+
+Logic:
+1. Resolve and validate file paths (must exist, must be supported type)
+2. Discover running server via PID file + health check
+3. If server found → `POST /api/files` for each file
+4. If no server → start server in foreground with the given files (same as default command)
+
+### 5. Hook Configuration
+
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash -c 'FILE=$(cat | jq -r \".tool_input.file_path\"); if [[ \"$FILE\" == *.md ]]; then bunx readit open \"$FILE\"; fi; exit 0'"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Files to Modify
+
+- `src/server/index.ts` — PID file write/cleanup, `POST /api/files` endpoint, file watcher setup for hot-added files
+- `src/cli/index.ts` — new `open` subcommand with server discovery logic
+- Frontend store — handle `file-added` SSE event type
+
+## Verification
+
+1. Start `readit test.md`
+2. Run `readit open other.md` in another terminal
+3. Confirm new tab appears in browser with `other.md`
+4. Edit `other.md` on disk → confirm live reload works
+5. Kill server, run `readit open test.md` → confirm new server starts
+6. Run `readit open test.md` again (already loaded) → confirm content refreshes without duplicate tab

package/docs/plans/2026-03-13-client-mode-plan.md

@@ -0,0 +1,605 @@
+# Client Mode (`readit open`) Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add a `readit open` CLI command that hot-adds files to a running readit server, or starts a new one if none exists.
+
+**Architecture:** PID file (`~/.readit/server.json`) for server discovery. New `POST /api/files` endpoint on the existing Bun.serve() for hot-adding files. Existing SSE infrastructure broadcasts `file-added` events to the frontend. Extract `getFileType` to shared lib to avoid duplication.
+
+**Tech Stack:** Bun, Commander.js, existing SSE, Zustand store
+
+---
+
+### Task 1: Extract `getFileType` to shared lib
+
+`getFileType` is currently defined in `src/cli/index.ts` and will be needed in both CLI and server code.
+
+**Files:**
+- Modify: `src/lib/utils.ts`
+- Modify: `src/cli/index.ts`
+
+**Step 1: Add `getFileType` to `src/lib/utils.ts`**
+
+```ts
+import type { DocumentType } from "../types";
+
+export function getFileType(filePath: string): DocumentType | null {
+  if (filePath.endsWith(".md") || filePath.endsWith(".markdown")) {
+    return "markdown";
+  }
+  if (filePath.endsWith(".html") || filePath.endsWith(".htm")) {
+    return "html";
+  }
+  return null;
+}
+```
+
+**Step 2: Update `src/cli/index.ts` to import from shared lib**
+
+Replace the local `getFileType` function with:
+```ts
+import { getFileType } from "../lib/utils.js";
+```
+
+Remove the local `getFileType` function definition (lines 22-30).
+
+**Step 3: Verify build passes**
+
+Run: `bun run typecheck`
+Expected: No errors
+
+**Step 4: Commit**
+
+```bash
+git add src/lib/utils.ts src/cli/index.ts
+git commit -m "refactor: extract getFileType to shared lib"
+```
+
+---
+
+### Task 2: Add PID file write/cleanup to server
+
+**Files:**
+- Modify: `src/server/index.ts` — write `~/.readit/server.json` on start, delete on shutdown
+- Modify: `src/cli/index.ts` — clean up PID file in SIGINT handler
+
+**Step 1: Add PID file helpers to `src/server/index.ts`**
+
+Add near the top of the file, after the existing helpers:
+
+```ts
+const SERVER_INFO_PATH = path.join(os.homedir(), ".readit", "server.json");
+
+async function writeServerInfo(port: number): Promise<void> {
+  await fs.mkdir(path.dirname(SERVER_INFO_PATH), { recursive: true });
+  await fs.writeFile(
+    SERVER_INFO_PATH,
+    JSON.stringify({ port, pid: process.pid }),
+    "utf-8",
+  );
+}
+
+async function removeServerInfo(): Promise<void> {
+  try {
+    await fs.unlink(SERVER_INFO_PATH);
+  } catch (err) {
+    if (!isErrnoException(err) || err.code !== "ENOENT") {
+      console.error("Failed to remove server info:", err);
+    }
+  }
+}
+```
+
+**Step 2: Call `writeServerInfo` at end of `startServer`**
+
+In the `startServer` function, after the server is successfully created, before the `return`:
+
+```ts
+await writeServerInfo(actualPort);
+```
+
+**Step 3: Export `removeServerInfo` and `SERVER_INFO_PATH`**
+
+Export both so the CLI can use them in its SIGINT handler:
+
+```ts
+export { SERVER_INFO_PATH, removeServerInfo };
+```
+
+**Step 4: Update SIGINT handler in `src/cli/index.ts`**
+
+```ts
+import { removeServerInfo } from "../server/index.js";
+
+// In the SIGINT handler:
+process.on("SIGINT", async () => {
+  console.log("\n\nShutting down...");
+  server.stop();
+  await removeServerInfo();
+  process.exit(0);
+});
+```
+
+**Step 5: Verify build passes**
+
+Run: `bun run typecheck`
+Expected: No errors
+
+**Step 6: Commit**
+
+```bash
+git add src/server/index.ts src/cli/index.ts
+git commit -m "feat: write/cleanup PID file on server start/stop"
+```
+
+---
+
+### Task 3: Add `POST /api/files` endpoint to server
+
+This endpoint hot-adds or refreshes files in a running server.
+
+**Files:**
+- Modify: `src/server/index.ts`
+
+**Step 1: Extract watcher setup into a reusable function**
+
+The file watcher logic (lines 686-719) needs to be callable for hot-added files too. Extract it within `createServer`:
+
+```ts
+function watchFile(filePath: string): FSWatcher | null {
+  try {
+    const watcher = watch(filePath, async (eventType) => {
+      if (eventType !== "change") return;
+
+      const state = fileMap.get(filePath);
+      if (!state) return;
+
+      if (state.debounceTimer) clearTimeout(state.debounceTimer);
+      state.debounceTimer = setTimeout(async () => {
+        try {
+          const newContent = await fs.readFile(filePath, "utf-8");
+          if (newContent !== state.content) {
+            state.content = newContent;
+            console.log(`File changed: ${basename(filePath)}`);
+
+            const message = `data: ${JSON.stringify({ type: "update", path: filePath })}\n\n`;
+            for (const controller of sseClients) {
+              try {
+                controller.enqueue(message);
+              } catch {
+                sseClients.delete(controller);
+              }
+            }
+          }
+        } catch (err) {
+          console.error(`Failed to read updated file ${filePath}:`, err);
+        }
+      }, 100);
+    });
+    return watcher;
+  } catch (err) {
+    console.warn(`File watching not available for ${filePath}:`, err);
+    return null;
+  }
+}
+```
+
+Replace the inline watcher loop with:
+```ts
+for (const filePath of fileOrder) {
+  const watcher = watchFile(filePath);
+  if (watcher) watchers.push(watcher);
+}
+```
+
+**Step 2: Add `POST /api/files` route**
+
+Add inside the `fetch` handler in `createServer`, after the `/api/documents` route:
+
+```ts
+if (pathname === "/api/files" && method === "POST") {
+  try {
+    const { path: requestedPath } = await req.json();
+
+    if (!requestedPath || typeof requestedPath !== "string") {
+      return errorResponse("Missing 'path' field", 400);
+    }
+
+    const filePath = path.resolve(requestedPath);
+    const fileType = getFileType(filePath);
+
+    if (!fileType) {
+      return errorResponse(
+        `Unsupported file type: ${filePath} (expected .md, .markdown, .html, or .htm)`,
+        400,
+      );
+    }
+
+    let content: string;
+    try {
+      content = await fs.readFile(filePath, "utf-8");
+    } catch (err) {
+      if (isErrnoException(err) && err.code === "ENOENT") {
+        return errorResponse(`File not found: ${filePath}`, 404);
+      }
+      throw err;
+    }
+
+    const existingState = fileMap.get(filePath);
+
+    if (existingState) {
+      // File already loaded — refresh content
+      existingState.content = content;
+      const message = `data: ${JSON.stringify({ type: "update", path: filePath })}\n\n`;
+      for (const controller of sseClients) {
+        try {
+          controller.enqueue(message);
+        } catch {
+          sseClients.delete(controller);
+        }
+      }
+    } else {
+      // New file — add to server
+      fileMap.set(filePath, {
+        content,
+        type: fileType,
+        debounceTimer: null,
+      });
+      fileOrder.push(filePath);
+
+      // Set up file watcher for the new file
+      const watcher = watchFile(filePath);
+      if (watcher) watchers.push(watcher);
+
+      const message = `data: ${JSON.stringify({
+        type: "file-added",
+        path: filePath,
+        fileName: basename(filePath),
+        fileType,
+      })}\n\n`;
+      for (const controller of sseClients) {
+        try {
+          controller.enqueue(message);
+        } catch {
+          sseClients.delete(controller);
+        }
+      }
+    }
+
+    return json({
+      path: filePath,
+      fileName: basename(filePath),
+      type: fileType,
+    });
+  } catch (err) {
+    console.error("Failed to add file:", err);
+    return errorResponse("Failed to add file", 500);
+  }
+}
+```
+
+**Step 3: Add the `getFileType` import**
+
+```ts
+import { getFileType } from "../lib/utils.js";
+```
+
+**Step 4: Verify build passes**
+
+Run: `bun run typecheck`
+Expected: No errors
+
+**Step 5: Commit**
+
+```bash
+git add src/server/index.ts
+git commit -m "feat: add POST /api/files endpoint for hot-adding files"
+```
+
+---
+
+### Task 4: Handle `file-added` SSE event in frontend
+
+**Files:**
+- Modify: `src/hooks/useDocument.ts`
+
+**Step 1: Add `file-added` handling to SSE listener**
+
+In the `eventSource.onmessage` handler (around line 90), add a branch for `file-added`:
+
+```ts
+eventSource.onmessage = async (e) => {
+  try {
+    const data = JSON.parse(e.data);
+
+    if (data.type === "file-added" && data.path) {
+      appStore.getState().openDocument({
+        content: "", // Lazy-loaded when tab activated
+        type: data.fileType,
+        filePath: data.path,
+        fileName: data.fileName,
+        clean: false,
+      });
+      return;
+    }
+
+    if (data.type === "update" && data.path) {
+      // ... existing update logic unchanged
+    }
+  } catch {
+    // Ignore non-JSON messages ("connected", "ping")
+  }
+};
+```
+
+**Step 2: Verify build passes**
+
+Run: `bun run typecheck`
+Expected: No errors
+
+**Step 3: Commit**
+
+```bash
+git add src/hooks/useDocument.ts
+git commit -m "feat: handle file-added SSE event for hot-added documents"
+```
+
+---
+
+### Task 5: Add `readit open` CLI command
+
+**Files:**
+- Modify: `src/cli/index.ts`
+
+**Step 1: Add server discovery function**
+
+Add after the imports:
+
+```ts
+import { readFileSync as readFileSyncNode } from "node:fs";
+
+interface ServerInfo {
+  port: number;
+  pid: number;
+}
+
+async function discoverServer(): Promise<ServerInfo | null> {
+  const serverInfoPath = join(os.homedir(), ".readit", "server.json");
+
+  try {
+    const content = readFileSyncNode(serverInfoPath, "utf-8");
+    const info: ServerInfo = JSON.parse(content);
+
+    // Verify the process is alive
+    try {
+      process.kill(info.pid, 0);
+    } catch {
+      return null;
+    }
+
+    // Verify health endpoint responds
+    try {
+      const res = await fetch(`http://127.0.0.1:${info.port}/api/health`);
+      if (!res.ok) return null;
+    } catch {
+      return null;
+    }
+
+    return info;
+  } catch {
+    return null;
+  }
+}
+```
+
+**Step 2: Add `open` subcommand**
+
+Add before `program.parse()`:
+
+```ts
+program
+  .command("open")
+  .argument("<files...>", "Markdown or HTML files to add to running server")
+  .description("Add files to a running readit server, or start a new one")
+  .option("-p, --port <number>", "Port for new server (if starting)", "4567")
+  .option("--host <address>", "Host for new server (if starting)", "127.0.0.1")
+  .action(
+    async (
+      fileArgs: string[],
+      options: { port: string; host: string },
+    ) => {
+      // Resolve and validate files
+      const resolvedFiles: { path: string; type: DocumentType }[] = [];
+      for (const arg of fileArgs) {
+        const filePath = resolve(process.cwd(), arg);
+
+        if (!existsSync(filePath)) {
+          console.error(`error: not found: ${filePath}`);
+          process.exit(1);
+        }
+
+        const type = getFileType(filePath);
+        if (!type) {
+          console.error(
+            `error: unsupported file type: ${arg} (expected .md, .markdown, .html, or .htm)`,
+          );
+          process.exit(1);
+        }
+
+        resolvedFiles.push({ path: filePath, type });
+      }
+
+      // Try to find running server
+      const server = await discoverServer();
+
+      if (server) {
+        // Send files to running server
+        for (const file of resolvedFiles) {
+          try {
+            const res = await fetch(
+              `http://127.0.0.1:${server.port}/api/files`,
+              {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ path: file.path }),
+              },
+            );
+
+            if (!res.ok) {
+              const data = await res.json();
+              console.error(
+                `error: failed to add ${file.path}: ${data.error}`,
+              );
+              process.exit(1);
+            }
+
+            const data = await res.json();
+            console.log(`Added: ${data.fileName} (${data.type})`);
+          } catch (err) {
+            console.error(
+              `error: failed to connect to server:`,
+              err instanceof Error ? err.message : err,
+            );
+            process.exit(1);
+          }
+        }
+
+        console.log(
+          `\nServer: http://127.0.0.1:${server.port}`,
+        );
+        return;
+      }
+
+      // No running server — start one
+      console.log("No running server found, starting new one...\n");
+
+      const files = resolvedFiles.map((f) => ({
+        content: readFileSync(f.path, "utf-8"),
+        type: f.type,
+        filePath: f.path,
+      }));
+
+      const preferredPort = Number.parseInt(options.port, 10);
+      try {
+        const { url, server: newServer } = await startServer({
+          files,
+          port: preferredPort,
+          host: options.host,
+        });
+
+        const fileList = files.map((f) => `  ${f.filePath} (${f.type})`);
+        console.log(`
+readit - Document Review Tool
+
+  ${files.length === 1 ? "File:" : "Files:"}
+${fileList.join("\n")}
+  URL:  ${url}
+
+  Server running. Close browser tab to stop.
+  Press Ctrl+C to force stop.
+`);
+
+        open(url);
+
+        process.on("SIGINT", async () => {
+          console.log("\n\nShutting down...");
+          newServer.stop();
+          await removeServerInfo();
+          process.exit(0);
+        });
+      } catch (error) {
+        console.error(
+          "error: failed to start server:",
+          error instanceof Error ? error.message : error,
+        );
+        process.exit(1);
+      }
+    },
+  );
+```
+
+**Step 3: Add missing imports**
+
+Make sure these imports are at the top of the file:
+
+```ts
+import { getFileType } from "../lib/utils.js";
+import { removeServerInfo } from "../server/index.js";
+import type { DocumentType } from "../types/index.js";
+```
+
+**Step 4: Verify build passes**
+
+Run: `bun run typecheck`
+Expected: No errors
+
+**Step 5: Commit**
+
+```bash
+git add src/cli/index.ts
+git commit -m "feat: add readit open command for client mode"
+```
+
+---
+
+### Task 6: Update the hook configuration
+
+**Files:**
+- Modify: `/Users/jay/.claude/settings.json`
+
+**Step 1: Update the PostToolUse hook**
+
+Change the command from `open -a Arto` to `bunx readit open`:
+
+```json
+"PostToolUse": [
+  {
+    "matcher": "Write|Edit",
+    "hooks": [
+      {
+        "type": "command",
+        "command": "bash -c 'FILE=$(cat | jq -r \".tool_input.file_path\"); if [[ \"$FILE\" == *.md ]]; then bunx readit open \"$FILE\"; fi; exit 0'"
+      }
+    ]
+  }
+]
+```
+
+**Step 2: Verify the hook fires correctly**
+
+Write or edit any `.md` file and confirm the hook runs without error.
+
+---
+
+### Task 7: End-to-end verification
+
+**Step 1: Build the project**
+
+Run: `bun run build`
+Expected: Successful build
+
+**Step 2: Start server with a test file**
+
+Run: `bunx readit test.md`
+Expected: Server starts, browser opens
+
+**Step 3: Open another file via client mode**
+
+In another terminal:
+Run: `bunx readit open README.md`
+Expected: "Added: README.md (markdown)" printed, new tab appears in browser
+
+**Step 4: Verify live reload for hot-added file**
+
+Edit `README.md` on disk, confirm the browser updates automatically.
+
+**Step 5: Verify reload for already-loaded file**
+
+Run: `bunx readit open test.md`
+Expected: Content refreshes, no duplicate tab
+
+**Step 6: Verify auto-start when no server running**
+
+Stop the server (Ctrl+C), then:
+Run: `bunx readit open test.md`
+Expected: New server starts with `test.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peaske7/readit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "A CLI tool to review Markdown documents with inline comments",
   "author": "Jay Shimada <peaske@pm.me>",
   "license": "MIT",

package/src/cli/index.ts

@@ -13,22 +13,13 @@ import { join, resolve } from "node:path";
 import { Command } from "commander";
 import open from "open";
 import { getCommentPath, parseCommentFile } from "../lib/comment-storage.js";
+import { getFileType } from "../lib/utils.js";
 import type { FileEntry } from "../server/index.js";
-import { startServer } from "../server/index.js";
+import { removeServerInfo, startServer } from "../server/index.js";
 import type { DocumentType } from "../types/index.js";
 
 const program = new Command();
 
-function getFileType(filePath: string): DocumentType | null {
-  if (filePath.endsWith(".md") || filePath.endsWith(".markdown")) {
-    return "markdown";
-  }
-  if (filePath.endsWith(".html") || filePath.endsWith(".htm")) {
-    return "html";
-  }
-  return null;
-}
-
 function isPermissionError(err: unknown): boolean {
   return (
     err instanceof Error &&
@@ -37,6 +28,39 @@ function isPermissionError(err: unknown): boolean {
   );
 }
 
+interface ServerInfo {
+  port: number;
+  pid: number;
+}
+
+async function discoverServer(): Promise<ServerInfo | null> {
+  const serverInfoPath = join(os.homedir(), ".readit", "server.json");
+
+  try {
+    const content = readFileSync(serverInfoPath, "utf-8");
+    const info: ServerInfo = JSON.parse(content);
+
+    // Verify the process is alive
+    try {
+      process.kill(info.pid, 0);
+    } catch {
+      return null;
+    }
+
+    // Verify health endpoint responds
+    try {
+      const res = await fetch(`http://127.0.0.1:${info.port}/api/health`);
+      if (!res.ok) return null;
+    } catch {
+      return null;
+    }
+
+    return info;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Recursively find all .comments.md files in a directory.
  */
@@ -310,9 +334,124 @@ ${fileList.join("\n")}
         }
 
         // Graceful shutdown on Ctrl+C
-        process.on("SIGINT", () => {
+        process.on("SIGINT", async () => {
           console.log("\n\nShutting down...");
           server.stop();
+          await removeServerInfo();
+          process.exit(0);
+        });
+      } catch (error) {
+        console.error(
+          "error: failed to start server:",
+          error instanceof Error ? error.message : error,
+        );
+        process.exit(1);
+      }
+    },
+  );
+
+// Open command: add files to running server or start new one
+program
+  .command("open")
+  .argument("<files...>", "Markdown or HTML files to add to running server")
+  .description("Add files to a running readit server, or start a new one")
+  .option("-p, --port <number>", "Port for new server (if starting)", "4567")
+  .option("--host <address>", "Host for new server (if starting)", "127.0.0.1")
+  .action(
+    async (fileArgs: string[], options: { port: string; host: string }) => {
+      // Resolve and validate files
+      const resolvedFiles: { path: string; type: DocumentType }[] = [];
+      for (const arg of fileArgs) {
+        const filePath = resolve(process.cwd(), arg);
+
+        if (!existsSync(filePath)) {
+          console.error(`error: not found: ${filePath}`);
+          process.exit(1);
+        }
+
+        const type = getFileType(filePath);
+        if (!type) {
+          console.error(
+            `error: unsupported file type: ${arg} (expected .md, .markdown, .html, or .htm)`,
+          );
+          process.exit(1);
+        }
+
+        resolvedFiles.push({ path: filePath, type });
+      }
+
+      // Try to find running server
+      const server = await discoverServer();
+
+      if (server) {
+        // Send files to running server
+        for (const file of resolvedFiles) {
+          try {
+            const res = await fetch(
+              `http://127.0.0.1:${server.port}/api/files`,
+              {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ path: file.path }),
+              },
+            );
+
+            if (!res.ok) {
+              const data = await res.json();
+              console.error(`error: failed to add ${file.path}: ${data.error}`);
+              process.exit(1);
+            }
+
+            const data = await res.json();
+            console.log(`Added: ${data.fileName} (${data.type})`);
+          } catch (err) {
+            console.error(
+              "error: failed to connect to server:",
+              err instanceof Error ? err.message : err,
+            );
+            process.exit(1);
+          }
+        }
+
+        console.log(`\nServer: http://127.0.0.1:${server.port}`);
+        return;
+      }
+
+      // No running server — start one
+      console.log("No running server found, starting new one...\n");
+
+      const files = resolvedFiles.map((f) => ({
+        content: readFileSync(f.path, "utf-8"),
+        type: f.type,
+        filePath: f.path,
+      }));
+
+      const preferredPort = Number.parseInt(options.port, 10);
+      try {
+        const { url, server: newServer } = await startServer({
+          files,
+          port: preferredPort,
+          host: options.host,
+        });
+
+        const fileList = files.map((f) => `  ${f.filePath} (${f.type})`);
+        console.log(`
+readit - Document Review Tool
+
+  ${files.length === 1 ? "File:" : "Files:"}
+${fileList.join("\n")}
+  URL:  ${url}
+
+  Server running. Close browser tab to stop.
+  Press Ctrl+C to force stop.
+`);
+
+        open(url);
+
+        process.on("SIGINT", async () => {
+          console.log("\n\nShutting down...");
+          newServer.stop();
+          await removeServerInfo();
           process.exit(0);
         });
       } catch (error) {

package/src/hooks/useDocument.ts

@@ -90,6 +90,16 @@ export function useDocument(): UseDocumentResult {
     eventSource.onmessage = async (e) => {
       try {
         const data = JSON.parse(e.data);
+        if (data.type === "file-added" && data.path) {
+          appStore.getState().openDocument({
+            content: "", // Lazy-loaded when tab activated
+            type: data.fileType,
+            filePath: data.path,
+            fileName: data.fileName,
+            clean: false,
+          });
+          return;
+        }
         if (data.type === "update" && data.path) {
           // Only reload if content was previously loaded
           const state = appStore.getState().documents.get(data.path);

package/src/lib/utils.ts

@@ -1,6 +1,17 @@
 import { type ClassValue, clsx } from "clsx";
 import type { ReactNode } from "react";
 import { twMerge } from "tailwind-merge";
+import type { DocumentType } from "../types";
+
+export function getFileType(filePath: string): DocumentType | null {
+  if (filePath.endsWith(".md") || filePath.endsWith(".markdown")) {
+    return "markdown";
+  }
+  if (filePath.endsWith(".html") || filePath.endsWith(".htm")) {
+    return "html";
+  }
+  return null;
+}
 
 export function cn(...inputs: ReadonlyArray<ClassValue>) {
   return twMerge(clsx(inputs));

package/src/server/index.ts

@@ -13,6 +13,7 @@ import {
   serializeComments,
   truncateSelection,
 } from "../lib/comment-storage.js";
+import { getFileType } from "../lib/utils.js";
 import {
   AnchorConfidences,
   type Comment,
@@ -171,6 +172,33 @@ function isValidFontFamily(value: unknown): value is FontFamily {
   return value === FontFamilies.SERIF || value === FontFamilies.SANS_SERIF;
 }
 
+// ─── PID file helpers ───────────────────────────────────────────────
+
+export const SERVER_INFO_PATH = path.join(
+  os.homedir(),
+  ".readit",
+  "server.json",
+);
+
+async function writeServerInfo(port: number): Promise<void> {
+  await fs.mkdir(path.dirname(SERVER_INFO_PATH), { recursive: true });
+  await fs.writeFile(
+    SERVER_INFO_PATH,
+    JSON.stringify({ port, pid: process.pid }),
+    "utf-8",
+  );
+}
+
+export async function removeServerInfo(): Promise<void> {
+  try {
+    await fs.unlink(SERVER_INFO_PATH);
+  } catch (err) {
+    if (!isErrnoException(err) || err.code !== "ENOENT") {
+      console.error("Failed to remove server info:", err);
+    }
+  }
+}
+
 // ─── Response helpers ───────────────────────────────────────────────
 
 function json(data: unknown, status = 200): Response {
@@ -560,6 +588,43 @@ function createServer(options: ServerOptions): ServerWithWatchers {
   const isDev = process.env.NODE_ENV === "development";
   const distPath = import.meta.dir;
 
+  function watchFile(targetPath: string): FSWatcher | null {
+    try {
+      const watcher = watch(targetPath, async (eventType) => {
+        if (eventType !== "change") return;
+
+        const state = fileMap.get(targetPath);
+        if (!state) return;
+
+        if (state.debounceTimer) clearTimeout(state.debounceTimer);
+        state.debounceTimer = setTimeout(async () => {
+          try {
+            const newContent = await fs.readFile(targetPath, "utf-8");
+            if (newContent !== state.content) {
+              state.content = newContent;
+              console.log(`File changed: ${basename(targetPath)}`);
+
+              const message = `data: ${JSON.stringify({ type: "update", path: targetPath })}\n\n`;
+              for (const controller of sseClients) {
+                try {
+                  controller.enqueue(message);
+                } catch {
+                  sseClients.delete(controller);
+                }
+              }
+            }
+          } catch (err) {
+            console.error(`Failed to read updated file ${targetPath}:`, err);
+          }
+        }, 100);
+      });
+      return watcher;
+    } catch (err) {
+      console.warn(`File watching not available for ${targetPath}:`, err);
+      return null;
+    }
+  }
+
   const server = Bun.serve({
     port: options.port,
     hostname: options.host,
@@ -584,6 +649,87 @@ function createServer(options: ServerOptions): ServerWithWatchers {
         return json({ files, clean: options.clean || false });
       }
 
+      // Hot-add or refresh a file
+      if (pathname === "/api/files" && method === "POST") {
+        try {
+          const { path: requestedPath } = await req.json();
+
+          if (!requestedPath || typeof requestedPath !== "string") {
+            return errorResponse("Missing 'path' field", 400);
+          }
+
+          const filePath = path.resolve(requestedPath);
+          const fileType = getFileType(filePath);
+
+          if (!fileType) {
+            return errorResponse(
+              `Unsupported file type: ${filePath} (expected .md, .markdown, .html, or .htm)`,
+              400,
+            );
+          }
+
+          let content: string;
+          try {
+            content = await fs.readFile(filePath, "utf-8");
+          } catch (err) {
+            if (isErrnoException(err) && err.code === "ENOENT") {
+              return errorResponse(`File not found: ${filePath}`, 404);
+            }
+            throw err;
+          }
+
+          const existingState = fileMap.get(filePath);
+
+          if (existingState) {
+            // File already loaded — refresh content
+            existingState.content = content;
+            const message = `data: ${JSON.stringify({ type: "update", path: filePath })}\n\n`;
+            for (const controller of sseClients) {
+              try {
+                controller.enqueue(message);
+              } catch {
+                sseClients.delete(controller);
+              }
+            }
+          } else {
+            // New file — add to server
+            fileMap.set(filePath, {
+              content,
+              type: fileType,
+              debounceTimer: null,
+            });
+            fileOrder.push(filePath);
+
+            // Set up file watcher for the new file
+            const watcher = watchFile(filePath);
+            if (watcher) watchers.push(watcher);
+
+            const message = `data: ${JSON.stringify({
+              type: "file-added",
+              path: filePath,
+              fileName: basename(filePath),
+              fileType,
+            })}\n\n`;
+            for (const controller of sseClients) {
+              try {
+                controller.enqueue(message);
+              } catch {
+                sseClients.delete(controller);
+              }
+            }
+          }
+
+          return json({
+            path: filePath,
+            fileName: basename(filePath),
+            type: fileType,
+          });
+        } catch (err) {
+          console.error("Failed to add file:", err);
+          return errorResponse("Failed to add file", 500);
+        }
+      }
+
       // Single document (backward compat + path-aware)
       if (pathname === "/api/document" && method === "GET") {
         const ctxOrRes = requireContext(url);
@@ -682,40 +828,9 @@ function createServer(options: ServerOptions): ServerWithWatchers {
   // Set up per-file watchers after Bun.serve() succeeds to avoid
   // leaking FSWatcher handles if the server fails to bind.
   const watchers: FSWatcher[] = [];
-  for (const filePath of fileOrder) {
-    try {
-      const watcher = watch(filePath, async (eventType) => {
-        if (eventType !== "change") return;
-
-        const state = fileMap.get(filePath);
-        if (!state) return;
-
-        if (state.debounceTimer) clearTimeout(state.debounceTimer);
-        state.debounceTimer = setTimeout(async () => {
-          try {
-            const newContent = await fs.readFile(filePath, "utf-8");
-            if (newContent !== state.content) {
-              state.content = newContent;
-              console.log(`File changed: ${basename(filePath)}`);
-
-              const message = `data: ${JSON.stringify({ type: "update", path: filePath })}\n\n`;
-              for (const controller of sseClients) {
-                try {
-                  controller.enqueue(message);
-                } catch {
-                  sseClients.delete(controller);
-                }
-              }
-            }
-          } catch (err) {
-            console.error(`Failed to read updated file ${filePath}:`, err);
-          }
-        }, 100);
-      });
-      watchers.push(watcher);
-    } catch (err) {
-      console.warn(`File watching not available for ${filePath}:`, err);
-    }
+  for (const fp of fileOrder) {
+    const watcher = watchFile(fp);
+    if (watcher) watchers.push(watcher);
   }
 
   return { server, watchers };
@@ -745,6 +860,8 @@ export async function startServer(
 
       const actualPort = server.port ?? port;
 
+      await writeServerInfo(actualPort);
+
       return {
         port: actualPort,
         url: `http://${displayHost}:${actualPort}`,