@peaske7/readit 0.2.0 → 0.3.0-rc.0

package/bunfig.toml

@@ -0,0 +1,2 @@
+[test]
+root = "src"

package/docs/perf-baseline.md

@@ -55,7 +55,62 @@ Build: production (`bun run build`)
 
 > Run with: `bun run bench`
 
-Results populated after running benchmarks. See `src/lib/*.bench.ts`.
+### Anchor Resolution
+
+| Benchmark | ops/sec | Mean | p99 |
+|-----------|---------|------|-----|
+| findAnchor — exact, medium doc | 340,789 | 0.003ms | 0.006ms |
+| findAnchor — exact, large doc | 348,679 | 0.003ms | 0.006ms |
+| findAnchorNormalized — large doc | 10,414 | 0.096ms | 0.406ms |
+| findAnchorFuzzy — mutated text, large doc | 163 | **6.13ms** | 6.41ms |
+| findAnchorWithFallback — 1 comment | 101 | **9.86ms** | 10.27ms |
+| findAnchorWithFallback — 10 comments | 39 | **25.66ms** | 26.10ms |
+| findAnchorWithFallback — 50 comments | 3 | **313.30ms** | 640.60ms |
+
+### Comment Storage
+
+| Benchmark | ops/sec | Mean | p99 |
+|-----------|---------|------|-----|
+| parseCommentFile — 1 comment | 881,595 | 0.001ms | 0.003ms |
+| parseCommentFile — 10 comments | 165,610 | 0.006ms | 0.009ms |
+| parseCommentFile — 50 comments | 34,588 | 0.029ms | 0.045ms |
+| serializeComments — 1 comment | 2,011,903 | 0.0005ms | 0.001ms |
+| serializeComments — 10 comments | 286,303 | 0.004ms | 0.005ms |
+| serializeComments — 50 comments | 59,027 | 0.017ms | 0.029ms |
+| computeHash — 300 lines | 169,082 | 0.006ms | 0.009ms |
+
+### Margin Layout
+
+| Benchmark | ops/sec | Mean | p99 |
+|-----------|---------|------|-----|
+| well-spaced — 1 comment | 6,192,537 | 0.0002ms | 0.0002ms |
+| well-spaced — 10 comments | 942,048 | 0.001ms | 0.002ms |
+| well-spaced — 50 comments | 167,170 | 0.006ms | 0.009ms |
+| clustered — 10 comments | 932,383 | 0.001ms | 0.002ms |
+| clustered — 50 comments | 165,792 | 0.006ms | 0.009ms |
+| with input zone — 50 comments | 143,787 | 0.007ms | 0.010ms |
+
+### Export
+
+| Benchmark | ops/sec | Mean |
+|-----------|---------|------|
+| formatComment — single | 17,270,891 | 0.00006ms |
+| generatePrompt — 10 comments | 927,600 | 0.001ms |
+| generatePrompt — 50 comments | 189,187 | 0.005ms |
+
+### Highlight System (DOM Operations) — *the optimization target*
+
+| Benchmark | ops/sec | Mean | p99 |
+|-----------|---------|------|-----|
+| findTextPosition — 1 comment | 61,802 | 0.016ms | 0.033ms |
+| findTextPosition — 10 comments | 17,713 | 0.057ms | 0.116ms |
+| findTextPosition — 50 comments | 4,555 | 0.220ms | 0.634ms |
+| getDOMTextContent — medium doc | 40,004 | 0.025ms | 0.055ms |
+| getDOMTextContent — large doc | 17,498 | 0.057ms | 0.222ms |
+| collectTextNodes — medium doc | 41,437 | 0.024ms | 0.070ms |
+| collectTextNodes — large doc | 21,645 | 0.046ms | 0.113ms |
+| **applyBatch + clear — 10 highlights, medium** | **2,308** | **0.433ms** | **2.156ms** |
+| **applyBatch + clear — 50 highlights, large** | **660** | **1.515ms** | **5.350ms** |
 
 ## Key Bottlenecks (from analysis)
 

package/docs/superpowers/specs/2026-03-27-go-server-rewrite-design.md

@@ -0,0 +1,284 @@
+# Go Server Rewrite Design Spec
+
+## Summary
+
+Rewrite readit's server and CLI from Bun/TypeScript to Go. The Svelte 5 frontend stays unchanged. Go handles all heavy computation (markdown rendering, syntax highlighting, comment storage, file watching, SSE) while Svelte handles client-side interactivity (highlights, margin notes, comment CRUD UI).
+
+## Motivation
+
+The current Bun server's cold-start path is dominated by Shiki WASM initialization (80-200ms) and the JSDOM mermaid worker (2-5s). A compiled Go binary with native libraries eliminates both bottlenecks:
+
+- Process startup: 30-50ms (Bun) → <1ms (Go binary)
+- Syntax highlighting init: 80-200ms (Shiki WASM) → 0ms (chroma, compiled in)
+- Markdown render (3000 lines): 5-20ms (markdown-it) → <1ms (goldmark)
+- Single binary distribution, no node_modules runtime dependency
+
+Target: 50-100x improvement on server-side TTFB.
+
+## Architecture
+
+```
+readit/
+├── go/
+│   ├── cmd/readit/main.go              # CLI entry point
+│   ├── internal/server/
+│   │   ├── server.go                   # Mux setup, static serving, dev proxy
+│   │   ├── documents.go                # Document routes + file state
+│   │   ├── comments.go                 # Comment CRUD routes
+│   │   ├── settings.go                 # Settings routes
+│   │   ├── sse.go                      # SSE broker, heartbeat, shutdown timer
+│   │   ├── markdown.go                 # goldmark + chroma rendering
+│   │   ├── headings.go                 # AST-based heading extraction
+│   │   ├── storage.go                  # .comments.md parse/serialize
+│   │   ├── anchor.go                   # Anchor resolution + fuzzy matching
+│   │   ├── watcher.go                  # fsnotify file watching + debounce
+│   │   ├── template.go                 # HTML page template
+│   │   ├── types.go                    # Shared types
+│   │   └── embed.go                    # go:embed dist/ assets
+│   ├── go.mod
+│   └── go.sum
+├── src/                                # Svelte frontend (unchanged)
+├── dist/                               # Vite build output (Go embeds this)
+├── Makefile
+├── vite.config.ts
+└── package.json
+```
+
+Single Go package (`internal/server`) with flat files. `cmd/readit/main.go` calls `server.Start(opts)`. No nested packages, no interface indirection.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Language | Go | goldmark+chroma ecosystem, fast dev velocity, single binary |
+| Repo structure | Monorepo (`go/` + `src/`) | Shared build pipeline, colocated frontend |
+| Asset serving | `go:embed` + `--assets-dir` override | Single binary for production, filesystem for dev |
+| Mermaid | Client-only with `<link rel="modulepreload">` | Eliminates JSDOM complexity, door open for server-side later |
+| Dev workflow | `make dev` — Go manages Vite child process | Single command, Go proxies to Vite for HMR |
+| Comment format | Keep `.comments.md` unchanged | Backward compatible, simple to parse in Go |
+| File support | Markdown only | Tight scope for v1 |
+| HTTP router | `net/http.ServeMux` (Go 1.22+) | Method+pattern routing, no framework dependency |
+| CLI parsing | `flag` package | Simple subcommands, no cobra overhead |
+
+## Server Core
+
+The `Server` struct holds all shared state:
+
+```go
+type Server struct {
+    mux        *http.ServeMux
+    files      map[string]*FileState
+    fileOrder  []string
+    sse        *SSEBroker
+    watcher    *Watcher
+    renderer   *Renderer
+    settings   Settings
+    workingDir string
+    clean      bool
+    assetsFS   fs.FS
+    template   *template.Template
+    mu         sync.RWMutex
+}
+```
+
+Routes registered as methods on `Server` — no handler interfaces, no middleware chain. Dev mode proxies non-API requests to Vite at `localhost:24678`.
+
+## API Contract
+
+The Go server implements the exact same API the Svelte frontend consumes. No changes to request/response shapes.
+
+### Document Routes (`documents.go`)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/documents` | List open files |
+| POST | `/api/documents` | Add file to session |
+| GET | `/api/document?path=` | Get rendered HTML + headings |
+
+### Comment Routes (`comments.go`)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/comments?path=` | List comments (with anchor resolution) |
+| POST | `/api/comments?path=` | Create comment |
+| PUT | `/api/comments/{id}?path=` | Update comment text |
+| DELETE | `/api/comments/{id}?path=` | Delete comment |
+| DELETE | `/api/comments?path=` | Delete all comments |
+| PUT | `/api/comments/{id}/reanchor?path=` | Reanchor comment |
+| GET | `/api/comments/raw?path=` | Raw .comments.md content |
+
+### Settings Routes (`settings.go`)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/settings` | Read settings |
+| PUT | `/api/settings` | Update font family |
+
+### SSE Endpoints (`sse.go`)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/document/stream` | Document change events |
+| GET | `/api/heartbeat` | Keep-alive, manages auto-shutdown |
+
+### Other
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/health` | Health check (`{"status":"ok"}`) |
+| GET | `/` | SSR page with inline data |
+| GET | `/assets/*` | Static assets (embedded or filesystem) |
+
+### Inline Data Shape
+
+The root page embeds JSON in `<script type="application/json" id="__readit">`:
+
+```json
+{
+  "files": [{"path": "...", "fileName": "..."}],
+  "activeFile": "...",
+  "clean": false,
+  "workingDirectory": "...",
+  "documents": {
+    "/path/to/file.md": {
+      "html": "...",
+      "headings": [{"id": "...", "text": "...", "level": 1}],
+      "comments": [...]
+    }
+  },
+  "settings": {"version": 1, "fontFamily": "serif"}
+}
+```
+
+## Markdown Pipeline (`markdown.go` + `headings.go`)
+
+goldmark with extensions, configured once at startup:
+
+- **GFM**: tables, strikethrough, autolinks, task lists
+- **Chroma highlighting**: `onedark` style, CSS classes (not inline styles)
+- **Auto heading IDs**: generated from heading text
+- **Unsafe HTML**: raw HTML passthrough (matches current behavior)
+
+Heading extraction walks the goldmark AST directly instead of regex.
+
+Mermaid fenced code blocks pass through as `<pre><code class="language-mermaid">`. The Svelte frontend's `DocumentViewer.svelte` hydrates these client-side via lazy `import("mermaid")`. A `<link rel="modulepreload">` hint in the template accelerates the mermaid chunk download.
+
+## Comment Storage (`storage.go` + `anchor.go`)
+
+Parses and serializes the existing `.comments.md` format unchanged:
+
+- Storage path: `~/.readit/comments/<mirrored-path>.comments.md`
+- Format: YAML frontmatter (`source`, `hash`, `version`) + comment blocks separated by `---`
+- Atomic writes: temp file + `os.Rename`
+- Hash: SHA-256 of source content, truncated to 16 hex chars
+
+Anchor resolution algorithm (direct port):
+
+1. Exact match near `lineHint` position
+2. Exact match anywhere in source
+3. Normalized match (collapse whitespace)
+4. Mark as `unresolved`
+
+Two-key cache: comment file mtime + source content hash. Skip re-parsing when neither changed.
+
+## SSE & File Watching (`sse.go` + `watcher.go`)
+
+SSE broker manages two client sets:
+
+- **Document stream clients**: receive `document-updated` and `document-added` events
+- **Heartbeat clients**: keep-alive pings, manage auto-shutdown timer (1.5s grace after last client disconnects, production only)
+
+File watcher uses `fsnotify` with 100ms debounce per file. On change: invalidate render cache → invalidate comment cache → broadcast SSE event.
+
+## CLI (`cmd/readit/main.go`)
+
+Subcommands:
+
+- `readit <file.md> [flags]` — start server + open browser
+- `readit list` — list files with comments (stdout)
+- `readit show <file.md>` — print comments for file (stdout)
+- `readit open <file.md>` — attach to running server or start new one
+
+Flags:
+
+- `--port` (default: random available)
+- `--host` (default: `127.0.0.1`)
+- `--no-open` (skip browser launch)
+- `--clean` (clear existing comments)
+- `--assets-dir` (override embedded assets)
+- `--dev` (spawn Vite child process, proxy to it)
+
+Server discovery: `~/.readit/server.json` with PID liveness check + HTTP health check. File lock (`server.lock`) prevents race conditions.
+
+## Build & Dev Workflow
+
+```makefile
+dev:           # Go spawns Vite child process, single command
+build:         # bun vite build → go build (embeds dist/)
+test:          # go test ./...
+test-client:   # bun run test
+test-e2e:      # playwright
+```
+
+Dev mode: `make dev` → Go runs with `--dev`, spawns `bunx vite` on port 24678, proxies non-API requests. Ctrl+C kills both.
+
+Production build: `make build` → Vite builds frontend into `dist/`, then `go build` embeds `dist/` into the binary.
+
+## Types (`types.go`)
+
+```go
+type Comment struct {
+    ID               string `json:"id"`
+    SelectedText     string `json:"selectedText"`
+    Comment          string `json:"comment"`
+    StartOffset      int    `json:"startOffset"`
+    EndOffset        int    `json:"endOffset"`
+    CreatedAt        string `json:"createdAt"`
+    LineHint         string `json:"lineHint,omitempty"`
+    AnchorConfidence string `json:"anchorConfidence,omitempty"`
+    AnchorPrefix     string `json:"anchorPrefix,omitempty"`
+}
+
+type Heading struct {
+    ID    string `json:"id"`
+    Text  string `json:"text"`
+    Level int    `json:"level"`
+}
+
+type FileState struct {
+    FilePath    string
+    FileName    string
+    Content     []byte
+    RenderedHTML string
+    Headings    []Heading
+    mu          sync.Mutex
+}
+
+type Settings struct {
+    Version    int    `json:"version"`
+    FontFamily string `json:"fontFamily"`
+}
+```
+
+JSON tags match the current API responses exactly.
+
+## Go Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `github.com/yuin/goldmark` | Markdown → HTML |
+| `github.com/yuin/goldmark-highlighting/v2` | Chroma integration for goldmark |
+| `github.com/alecthomas/chroma/v2` | Syntax highlighting (native Go) |
+| `github.com/fsnotify/fsnotify` | Cross-platform file watching |
+| `github.com/pkg/browser` | Cross-platform browser launch |
+
+Five dependencies total. No HTTP framework, no CLI framework.
+
+## Migration Path
+
+1. Build Go server implementing the full API contract
+2. Verify Svelte frontend works unchanged against Go server
+3. Run existing E2E perf tests, compare against React/Svelte baselines
+4. Remove `src/server.ts`, `src/cli.ts`, `src/lib/markdown-renderer.ts`, `src/lib/mermaid-worker.ts`, `src/lib/mermaid-renderer.ts`, `src/lib/comment-storage.ts`, `src/lib/anchor.ts`, related server-side code
+5. Update `package.json` scripts to use Makefile
+6. Remove server-side JS dependencies (`shiki`, `markdown-it`, `jsdom`, `mermaid`, `commander`)

package/e2e/comments.spec.ts

@@ -3,11 +3,7 @@ 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";
+import { addComment, selectTextInArticle } from "./utils/selection";
 
 const FIXTURES_DIR = resolve(import.meta.dirname, "fixtures");
 
@@ -34,18 +30,13 @@ function cleanupCommentFile(sourcePath: string): void {
 
 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 ({
@@ -57,7 +48,7 @@ test.describe("Comment Creation", () => {
       await page.goto(url);
 
       // Wait for document to load
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Select text in the article
@@ -68,55 +59,20 @@ test.describe("Comment Creation", () => {
       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: highlight exists via CSS Custom Highlight API observability hook
+      await page.waitForFunction(
+        () => {
+          const h = (window as unknown as Record<string, unknown>)
+            .__readitHighlights as { commentIds: string[] } | undefined;
+          return h && h.commentIds.length > 0;
+        },
+        { timeout: 10_000 },
+      );
 
-      // 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 });
+      // Verify the selected text is still visible in the article
+      await expect(article).toContainText(textToSelect);
 
-      // 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)
+      // Verify: margin note shows the comment
       await expect(page.locator("body")).toContainText(commentText);
     } finally {
       await cleanup();

package/e2e/document-load.spec.ts

@@ -15,7 +15,7 @@ test.describe("Document Loading", () => {
       await page.goto(url);
 
       // Wait for document to load - use article scope to avoid header h1
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article.locator("h1")).toContainText("Test Document");
 
       // Verify paragraph content is rendered
@@ -29,26 +29,4 @@ test.describe("Document Loading", () => {
       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

@@ -19,7 +19,7 @@ test.describe("Comment Export", () => {
       await page.goto(url);
 
       // Wait for document to load
-      const article = page.locator("article");
+      const article = page.locator("article#document-content");
       await expect(article).toBeVisible();
 
       // Add a comment
@@ -48,9 +48,9 @@ test.describe("Comment Export", () => {
       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:");
+      // Verify it follows the prompt format (quoted selected text + comment)
+      expect(clipboardContent).toMatch(/"testing text selection"/);
+      expect(clipboardContent).toContain("This is my review comment");
     } finally {
       await cleanup();
     }

package/e2e/perf/add-comment.spec.ts

@@ -23,9 +23,9 @@ test(`add-comment: ${tier.name} (${tier.lines} lines, ${tier.comments} comments)
 
     // Capture actual highlight count as baseline (may differ from tier.comments)
     const baselineCount = await page.evaluate(() => {
-      const marks = document.querySelectorAll("mark[data-comment-id]");
-      return new Set([...marks].map((m) => m.getAttribute("data-comment-id")))
-        .size;
+      const h = (window as unknown as Record<string, unknown>)
+        .__readitHighlights as { commentIds: string[] } | undefined;
+      return h?.commentIds?.length ?? 0;
     });
 
     // Find a text that isn't already highlighted — use a line near the end
@@ -90,11 +90,9 @@ test(`add-comment: ${tier.name} (${tier.lines} lines, ${tier.comments} comments)
       },
       async () => {
         await page.waitForFunction((expected) => {
-          const marks = document.querySelectorAll("mark[data-comment-id]");
-          const ids = new Set(
-            [...marks].map((m) => m.getAttribute("data-comment-id")),
-          );
-          return ids.size > expected;
+          const h = (window as unknown as Record<string, unknown>)
+            .__readitHighlights as { commentIds: string[] } | undefined;
+          return (h?.commentIds?.length ?? 0) > expected;
         }, baselineCount);
       },
     );
@@ -107,9 +105,9 @@ test(`add-comment: ${tier.name} (${tier.lines} lines, ${tier.comments} comments)
 
     // Verify the highlight actually appeared
     const finalCount = await page.evaluate(() => {
-      const marks = document.querySelectorAll("mark[data-comment-id]");
-      return new Set([...marks].map((m) => m.getAttribute("data-comment-id")))
-        .size;
+      const h = (window as unknown as Record<string, unknown>)
+        .__readitHighlights as { commentIds: string[] } | undefined;
+      return h?.commentIds?.length ?? 0;
     });
     expect(finalCount).toBeGreaterThan(tier.comments);
   } finally {

package/e2e/perf/fixtures/generate.ts

@@ -9,7 +9,6 @@ interface Comment {
   id: string;
   selectedText: string;
   comment: string;
-  createdAt: string;
   startOffset: number;
   endOffset: number;
   lineHint: string;
@@ -174,7 +173,6 @@ function makeComment(
     id: `perf${String(index).padStart(4, "0")}`,
     selectedText,
     comment: `Review comment #${index + 1}: This section needs attention regarding clarity and accuracy.`,
-    createdAt: "2025-01-01T00:00:00.000Z",
     startOffset,
     endOffset,
     lineHint,
@@ -199,9 +197,7 @@ function serializeComments(file: CommentFile): string {
 
   for (const comment of file.comments) {
     // Metadata
-    lines.push(
-      `<!-- c:${comment.id}|${comment.lineHint}|${comment.createdAt} -->`,
-    );
+    lines.push(`<!-- c:${comment.id}|${comment.lineHint} -->`);
 
     // Selected text as blockquote
     const quotedLines = comment.selectedText