@peaske7/readit 0.1.4 → 0.1.5

package/docs/plans/2026-03-13-multi-document-design.md

@@ -0,0 +1,183 @@
+# Multi-Document Support Design
+
+**Date:** 2026-03-13
+**Status:** Approved
+
+## Overview
+
+Evolve readit from single-document to multi-document support with tabbed navigation, full state preservation across tab switches, and Zustand for state management.
+
+## Motivation
+
+readit currently opens one file per session. Reviewers often need to cross-reference multiple documents — reviewing a spec alongside its implementation notes, or scanning an entire docs directory. Multi-document support makes readit useful for real review workflows.
+
+## Invocation
+
+```bash
+npx readit file1.md file2.md           # Multiple files
+npx readit ./docs/                      # Directory (all .md and .html files)
+npx readit README.md ./docs/ notes.html # Mixed
+npx readit file.md                      # Single file (unchanged)
+```
+
+## Interaction Model
+
+- **Tabbed view** — one document visible at a time, tab bar to switch
+- **Full state preservation** — selection, half-typed comments, scroll position all restored on tab switch
+- **Lazy loading** — document content fetched on first tab activation, not all at once
+- **Split view deferred** — tabs are the foundation; split view ships later
+
+## Store Design (Zustand)
+
+### Why Zustand
+
+"Preserve everything on tab switch" means state must survive component unmounting. With tabs, only one document renders — inactive documents' React trees are gone. React Context dies with the tree. Zustand stores state outside React, solving this naturally.
+
+### Shape
+
+```ts
+interface DocumentState {
+  // Document data
+  document: Document;
+
+  // Comments
+  comments: Comment[];
+  commentsError: string | null;
+
+  // Selection & input
+  selection: SelectionRange | null;
+  pendingSelectionTop: number | undefined;
+  pendingCommentText: string;
+
+  // Highlight positions (DOM-derived, recomputed on mount)
+  highlightPositions: Record<string, number>;
+  documentPositions: Record<string, number>;
+
+  // Navigation
+  scrollY: number;
+  hoveredCommentId: string | undefined;
+
+  // Re-anchor
+  reanchorTarget: { commentId: string } | null;
+}
+
+interface AppStore {
+  documents: Map<string, DocumentState>;
+  activeDocumentPath: string | null;
+
+  // Global actions
+  openDocument: (doc: Document) => void;
+  closeDocument: (filePath: string) => void;
+  setActiveDocument: (filePath: string) => void;
+
+  // Per-document actions (default to active document)
+  addComment: (
+    text: string,
+    comment: string,
+    start: number,
+    end: number,
+  ) => void;
+  editComment: (id: string, newText: string) => void;
+  deleteComment: (id: string) => void;
+  setSelection: (selection: SelectionRange | null) => void;
+  setHoveredComment: (id: string | undefined) => void;
+  // ...
+}
+```
+
+`highlightPositions` and `documentPositions` are DOM-derived — stale when unmounted, recomputed on mount. `scrollY` is the critical value to preserve; highlight positions are ephemeral.
+
+Per-document actions take an optional `filePath` parameter but default to `activeDocumentPath`. This keeps call sites simple while enabling future split-view.
+
+## Component Architecture
+
+```
+<App>                                    # Thin shell: store init, tab bar, active DocumentView
+  +- <Toaster />
+  +- <TabBar />                          # NEW - tab strip
+  +- <Header />                          # Simplified - reads from store, ~8 props down from 14
+  +- <DocumentView>                      # NEW - per-document layout
+  |   +- <TableOfContents /> or <TOCPopover />   # Renamed from FloatingTOC
+  |   +- <DocumentViewer />
+  |   +- Margin area
+  |   |   +- <ReanchorConfirmation />    # NEW - extracted from inline JSX
+  |   |   +- <NewCommentForm />          # Renamed from CommentInputArea
+  |   |   +- <MarginNotes />             # Renamed from MarginNotesContainer
+  |   |       +- <MarginNote />          # Reads actions from store directly
+  |   +- <CommentMinimap />
+  |   +- <CommentNavigator />
+  +- <footer />
+```
+
+### Component changes
+
+- **App**: God component (~520 lines) becomes thin shell
+- **DocumentView** (new): Owns per-document layout. On mount: restores scroll, re-applies highlights. On unmount: saves scrollY to store
+- **MarginNote**: 6 callback props eliminated — calls `useAppStore()` directly
+- **Header**: 14 props reduced to ~8 — reads comment data from store
+- **CommentListDropdown** (renamed from CommentManagerDropdown): Reads from store directly
+- **TabBar** (new): Renders open document tabs, close buttons, active indicator
+
+## Server API Changes
+
+| Endpoint              | Before                  | After                                      |
+| --------------------- | ----------------------- | ------------------------------------------ |
+| `GET /api/document`   | Returns single document | Requires `?path=` query param              |
+| `GET /api/documents`  | (new)                   | Returns list of open file paths + metadata |
+| `POST /api/documents` | (new, deferred)         | Add document at runtime (add-from-browser) |
+| `GET /api/comments`   | Single file scoped      | Requires `?path=` query param              |
+| `POST /api/comments`  | Single file scoped      | Requires `path` in body                    |
+
+`GET /api/documents` returns only metadata (path, fileName, type) — lightweight enough to populate the tab bar immediately. Content loads lazily via `GET /api/document?path=`.
+
+Comment storage unchanged — already per-file in `~/.readit/comments/`.
+
+## Tab Switch Lifecycle
+
+### Saving (unmount)
+
+Most state is already in the store as it changes. The only explicit "save on unmount" is `scrollY`, since scroll isn't React-controlled.
+
+### Restoring (mount)
+
+1. Read document content from store (or fetch if first visit)
+2. Highlighter applies marks, emits fresh highlightPositions
+3. `window.scrollTo(0, scrollY)` after highlights are painted
+4. If selection exists, highlight pending selection
+5. If pendingCommentText, NewCommentForm renders pre-filled
+6. If reanchorTarget, show re-anchor UI
+
+Scroll restoration uses the existing double-rAF pattern extended with scrollTo as the final step.
+
+### Edge cases
+
+| Scenario                                      | Behavior                                                                     |
+| --------------------------------------------- | ---------------------------------------------------------------------------- |
+| Close active tab                              | Activate nearest tab (right, then left). Last tab shows empty state          |
+| Close tab with unsaved comment text           | Close immediately — ephemeral state, expected behavior                       |
+| Document changes on disk while on another tab | SSE live-reload updates store for that path; content is fresh on switch-back |
+| Same file via different paths                 | Deduplicate by resolved absolute path in CLI                                 |
+
+## Deferrals
+
+| Feature                                | Reason                                              |
+| -------------------------------------- | --------------------------------------------------- |
+| Split view                             | Separate feature; tabs are the foundation           |
+| Add-from-browser                       | CLI + directory mode covers primary use cases first |
+| Tab reordering                         | Polish, not essential                               |
+| Cross-document comment search          | No current demand                                   |
+| Tab persistence across server restarts | Overkill for a dev tool                             |
+| Bulk export across documents           | Per-document export works; bulk is convenience      |
+
+## Migration Path
+
+Incremental — store introduced alongside existing hooks, components migrate one at a time:
+
+1. Create store with `openDocument` / `setActiveDocument`
+2. Add `TabBar`, wrap existing App content in `DocumentView`
+3. Migrate `useComments` into store (biggest change)
+4. Migrate selection, scroll, hover state into store
+5. Remove emptied hooks, rename components
+6. Add multi-file CLI + server endpoints
+
+Each step is independently shippable and testable.

package/docs/plans/2026-03-13-performance-benchmarks-design.md

@@ -0,0 +1,121 @@
+# Performance Benchmarks Design
+
+## Context
+
+readit feels slow across startup, rendering, and interactions. The main JS bundle is 748 KB (230 KB gzipped), with no code splitting. Heavy libraries (react-markdown, mermaid, react-syntax-highlighter) load upfront.
+
+## Goal
+
+Establish Vitest bench benchmarks for critical server-side and library operations, with a <50ms target per operation. CI-gated to prevent regressions.
+
+## Scope
+
+Benchmark the four core user flows:
+
+1. **Adding comments** — anchor resolution, comment serialization, file I/O
+2. **Copying/exporting comments** — export formatting, context extraction
+3. **Startup** — time-to-first-byte once server is up (exception: process spawn, browser open)
+4. **Rendering/reading** — margin layout calculations
+
+Client-side rendering (react-markdown, syntax highlighting) is out of scope for Vitest bench — those require Playwright, which can be added later.
+
+## Approach: Vitest Bench
+
+Use Vitest's built-in `bench` mode (powered by tinybench). Benchmark files are co-located with source, following the existing `*.test.ts` pattern.
+
+### Benchmark files
+
+```
+src/lib/
+├── anchor.bench.ts          # findAnchorWithFallback
+├── comment-storage.bench.ts # parse, serialize, computeHash
+├── margin-layout.bench.ts   # position calculations
+├── export.bench.ts          # export formatting
+├── context.bench.ts         # LLM context extraction
+└── __fixtures__/
+    └── bench-data.ts        # shared synthetic test data
+```
+
+### What each benchmark measures
+
+#### `anchor.bench.ts` — hottest path
+
+- `findAnchorWithFallback()` with exact match (best case)
+- `findAnchorWithFallback()` with fuzzy match (worst case)
+- Both against a ~300-line synthetic Markdown document
+
+#### `comment-storage.bench.ts`
+
+- `parseCommentFile()` with 1, 10, 50 comments
+- `serializeComments()` with 1, 10, 50 comments
+- `computeHash()` on a ~300-line document
+
+#### `margin-layout.bench.ts`
+
+- Position resolution with 1, 10, 50 comments
+- Overlap resolution (worst case: all comments on adjacent lines)
+
+#### `export.bench.ts` + `context.bench.ts`
+
+- Export to JSON format with 10, 50 comments
+- Export to prompt format with 10, 50 comments
+- Context extraction for a ~300-line document
+
+### Test fixtures (`__fixtures__/bench-data.ts`)
+
+Shared synthetic data:
+
+- A ~300-line Markdown document representative of real usage
+- Comment sets at various sizes (1, 10, 50)
+- Pre-computed anchors for deterministic benchmarks
+
+### Running benchmarks
+
+```bash
+pnpm bench    # vitest bench
+```
+
+Package.json script:
+
+```json
+"bench": "vitest bench"
+```
+
+### CI integration
+
+GitHub Actions runs `pnpm bench` after tests pass. Vitest bench outputs timing statistics (min, max, mean, p99).
+
+For hard CI gating, each benchmark file includes a companion assertion in the existing test file:
+
+```ts
+test("anchor resolution completes under 50ms", () => {
+  const start = performance.now();
+  for (let i = 0; i < 100; i++) {
+    findAnchorWithFallback({
+      source: doc,
+      selectedText: text,
+      lineHint: "L150",
+    });
+  }
+  const elapsed = (performance.now() - start) / 100;
+  expect(elapsed).toBeLessThan(50);
+});
+```
+
+This gives both:
+
+- **Benchmark data** (vitest bench) — for tracking performance over time
+- **Hard assertions** (vitest test) — for CI gating at <50ms
+
+## Performance target
+
+| Operation                                             | Target              |
+| ----------------------------------------------------- | ------------------- |
+| All benchmarked operations                            | < 50ms              |
+| Exceptions: process spawn, browser open, port binding | As fast as possible |
+
+## Future work
+
+- Playwright benchmarks for client-side rendering (react-markdown, syntax highlighting, comment highlight positioning)
+- Bundle size budgets if bundle growth becomes a concern
+- `Server-Timing` headers on API routes for production observability

package/e2e/comments.spec.ts

@@ -0,0 +1,125 @@
+import { existsSync, rmSync } from "node:fs";
+import * as os from "node:os";
+import { join, resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+import { spawnCli } from "./utils/cli";
+import {
+  addComment,
+  selectTextInArticle,
+  selectTextInIframe,
+} from "./utils/selection";
+
+const FIXTURES_DIR = resolve(import.meta.dirname, "fixtures");
+
+/**
+ * Get the expected comment file path for a source file.
+ */
+function getCommentPath(sourcePath: string): string {
+  const absolute = resolve(sourcePath);
+  const normalized = absolute.replace(/^\//, "").replace(/^[A-Z]:[\\/]/, "");
+  const ext = normalized.lastIndexOf(".");
+  const withoutExt = ext > 0 ? normalized.slice(0, ext) : normalized;
+  return join(os.homedir(), ".readit", "comments", `${withoutExt}.comments.md`);
+}
+
+/**
+ * Clean up comment file for a source file.
+ */
+function cleanupCommentFile(sourcePath: string): void {
+  const commentPath = getCommentPath(sourcePath);
+  if (existsSync(commentPath)) {
+    rmSync(commentPath);
+  }
+}
+
+test.describe("Comment Creation", () => {
+  const sampleMdPath = resolve(FIXTURES_DIR, "sample.md");
+  const sampleHtmlPath = resolve(FIXTURES_DIR, "sample.html");
+
+  test.beforeEach(() => {
+    // Clean up any existing comment files before each test
+    cleanupCommentFile(sampleMdPath);
+    cleanupCommentFile(sampleHtmlPath);
+  });
+
+  test.afterEach(() => {
+    // Clean up after each test
+    cleanupCommentFile(sampleMdPath);
+    cleanupCommentFile(sampleHtmlPath);
+  });
+
+  test("adds comment to selected text in markdown document", async ({
+    page,
+  }) => {
+    const { url, cleanup } = await spawnCli(sampleMdPath, { port: 4572 });
+
+    try {
+      await page.goto(url);
+
+      // Wait for document to load
+      const article = page.locator("article");
+      await expect(article).toBeVisible();
+
+      // Select text in the article
+      const textToSelect = "testing text selection";
+      await selectTextInArticle(page, textToSelect);
+
+      // Add a comment
+      const commentText = "This is my test comment";
+      await addComment(page, commentText);
+
+      // Verify: highlight exists with data-comment-id
+      const highlight = article.locator("mark[data-comment-id]").first();
+      await expect(highlight).toBeVisible();
+      await expect(highlight).toContainText(textToSelect);
+
+      // Verify: margin note shows the comment
+      await expect(page.locator("body")).toContainText(commentText);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("adds comment to selected text in HTML document (iframe)", async ({
+    page,
+  }) => {
+    const { url, cleanup } = await spawnCli(sampleHtmlPath, { port: 4573 });
+
+    try {
+      await page.goto(url);
+
+      // Wait for iframe to load and its script to initialize
+      const iframe = page.frameLocator("iframe");
+      await expect(iframe.locator("body")).toBeVisible();
+
+      // Wait for iframe script to execute and send iframeReady
+      await page.waitForTimeout(500);
+
+      // Select text inside iframe - use test event which bypasses tree walking
+      // The test event directly sends offsets to the parent
+      const textToSelect = "testing text selection";
+      await selectTextInIframe(page, iframe, textToSelect);
+
+      // Verify pending highlight exists in iframe
+      const pendingMark = iframe.locator("mark[data-pending]");
+      await expect(pendingMark).toBeVisible({ timeout: 5000 });
+
+      // Add a comment (input is in parent frame)
+      const commentText = "Comment on HTML content";
+      await addComment(page, commentText);
+
+      // Wait for the comment to be saved via API and highlights to be applied
+      await page.waitForTimeout(500);
+
+      // Verify: highlight exists inside iframe with comment ID
+      const highlight = iframe.locator("mark[data-comment-id]").first();
+      await expect(highlight).toBeVisible();
+      await expect(highlight).toContainText(textToSelect);
+
+      // Verify: margin note shows the comment (in parent frame)
+      await expect(page.locator("body")).toContainText(commentText);
+    } finally {
+      await cleanup();
+    }
+  });
+});

package/e2e/document-load.spec.ts

@@ -0,0 +1,54 @@
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+import { spawnCli } from "./utils/cli";
+
+const FIXTURES_DIR = resolve(import.meta.dirname, "fixtures");
+
+test.describe("Document Loading", () => {
+  test("loads markdown document and displays content", async ({ page }) => {
+    const { url, cleanup } = await spawnCli(
+      resolve(FIXTURES_DIR, "sample.md"),
+      { port: 4570 },
+    );
+
+    try {
+      await page.goto(url);
+
+      // Wait for document to load - use article scope to avoid header h1
+      const article = page.locator("article");
+      await expect(article.locator("h1")).toContainText("Test Document");
+
+      // Verify paragraph content is rendered
+      await expect(article).toContainText(
+        "This is a paragraph for testing text selection",
+      );
+
+      // Verify second section is visible
+      await expect(article.locator("h2")).toContainText("Second Section");
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("loads HTML document in iframe", async ({ page }) => {
+    const { url, cleanup } = await spawnCli(
+      resolve(FIXTURES_DIR, "sample.html"),
+      { port: 4571 },
+    );
+
+    try {
+      await page.goto(url);
+
+      // Wait for iframe to exist
+      const iframe = page.frameLocator("iframe");
+
+      // Verify content inside iframe
+      await expect(iframe.locator("h1")).toContainText("Test Document");
+      await expect(iframe.locator("p").first()).toContainText(
+        "This is a paragraph for testing text selection",
+      );
+    } finally {
+      await cleanup();
+    }
+  });
+});

package/e2e/export.spec.ts

@@ -0,0 +1,58 @@
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+import { spawnCli } from "./utils/cli";
+import { addComment, selectTextInArticle } from "./utils/selection";
+
+const FIXTURES_DIR = resolve(import.meta.dirname, "fixtures");
+
+test.describe("Comment Export", () => {
+  test("Copy All generates valid prompt format", async ({ page, context }) => {
+    // Grant clipboard permissions
+    await context.grantPermissions(["clipboard-read", "clipboard-write"]);
+
+    const { url, cleanup } = await spawnCli(
+      resolve(FIXTURES_DIR, "sample.md"),
+      { port: 4590 },
+    );
+
+    try {
+      await page.goto(url);
+
+      // Wait for document to load
+      const article = page.locator("article");
+      await expect(article).toBeVisible();
+
+      // Add a comment
+      const textToSelect = "testing text selection";
+      const commentText = "This is my review comment";
+      await selectTextInArticle(page, textToSelect);
+      await addComment(page, commentText);
+
+      // Verify comment was added
+      await expect(page.locator("body")).toContainText(commentText);
+
+      // Open the actions menu and click "Copy All"
+      const menuButton = page.getByRole("button", { name: /actions menu/i });
+      await menuButton.click();
+
+      const copyButton = page.getByRole("menuitem", { name: /copy all/i });
+      await copyButton.click();
+
+      // Read clipboard content
+      const clipboardContent = await page.evaluate(() =>
+        navigator.clipboard.readText(),
+      );
+
+      // Verify the format contains expected parts
+      expect(clipboardContent).toContain("# Review Comments for sample.md");
+      expect(clipboardContent).toContain(textToSelect);
+      expect(clipboardContent).toContain(commentText);
+
+      // Verify it follows the prompt format (selected text + comment structure)
+      expect(clipboardContent).toContain("Selected text:");
+      expect(clipboardContent).toContain("Comment:");
+    } finally {
+      await cleanup();
+    }
+  });
+});

package/e2e/fixtures/sample.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Test Document</title>
+</head>
+<body>
+  <h1>Test Document</h1>
+  <p>This is a paragraph for testing text selection.</p>
+  <h2>Second Section</h2>
+  <p>Here is another paragraph with some more text to select and comment on.</p>
+</body>
+</html>

package/e2e/fixtures/sample.md

@@ -0,0 +1,7 @@
+# Test Document
+
+This is a paragraph for testing text selection.
+
+## Second Section
+
+Here is another paragraph with some more text to select and comment on.