From 4cb1852ad354302aa21b5abc17bae2c8a3e710a0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 20 Jul 2026 12:23:04 +0000
Subject: [PATCH 1/5] Add design doc for dirview, a lightweight local directory
 viewer server

Research and design (no implementation) for a single-file web server that
serves a two-pane directory browser with GitHub-flavored markdown, Shiki
code highlighting, git status/diff integration, live file watching, and
Catppuccin Latte/Mocha theming.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DJieA2dNDXVv7P3Q6HpCNB
---
 docs/dirview-design.md | 275 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 275 insertions(+)
 create mode 100644 docs/dirview-design.md

diff --git a/docs/dirview-design.md b/docs/dirview-design.md
new file mode 100644
index 0000000..48b5f7a
--- /dev/null
+++ b/docs/dirview-design.md
@@ -0,0 +1,275 @@
+# dirview — Design for a Lightweight Local Directory Viewer
+
+**Status:** Design only — not yet implemented.
+
+A small web server you run in any local directory that gives you a two-column
+browsing UI: directory tree on the left, rendered file on the right, with
+first-class markdown rendering, syntax-highlighted code, git status awareness,
+inline change indicators with click-through diffs, and live updates as files
+change on disk. Catppuccin themed (Latte light / Mocha dark).
+
+```
+uv run dirview.py            # serve the current directory at http://127.0.0.1:7440
+```
+
+---
+
+## 1. Requirements
+
+1. Two-column layout: directory tree (left), viewed file (right)
+2. GOOD markdown rendering (GitHub-flavored)
+3. GOOD code rendering (real syntax highlighting, not an afterthought)
+4. Git status shown in the tree; filter to changed/new files
+5. For changed files, a *subtle* indication of *where* changes are, with
+   click-through to a standard diff representation
+6. Watches the directory tree and keeps open views up to date
+
+Constraints: as little code as possible — assemble best-in-class existing
+solutions rather than building anything from scratch. Catppuccin light + dark.
+
+## 2. Research: what already exists
+
+No single existing tool covers all six requirements; each covers a slice:
+
+| Tool | Tree | Markdown | Code | Git status | Inline diffs | Watch | Verdict |
+|---|---|---|---|---|---|---|---|
+| [markserv](https://github.com/markserv/markserv) / [mdserver](https://github.com/deepdadou/mdserver) / [gh-markdown-preview](https://github.com/yusukebe/gh-markdown-preview) | dir index only | ✅ | partial | ❌ | ❌ | ✅ | Markdown + live reload, no git at all |
+| [difit](https://github.com/yoshiko-pg/difit) | changed files only | ❌ | ✅ | ✅ | ✅ (GitHub-style) | partial | Excellent diff review UI, but not a directory *browser* — no markdown, no unchanged files |
+| [diffhub](https://github.com/mblode/diffhub) | changed files only | ❌ | ✅ | ✅ | ✅ | ❌ | Same category as difit |
+| `code serve-web` / code-server | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Covers everything but is a full IDE: heavyweight, editing-oriented, not a calm reading view |
+| [Ferrite](https://github.com/OlaProeis/Ferrite) | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | Native desktop app (Rust/egui), not a web server |
+| klaus / gitweb / Gitea | ✅ | ✅ | ✅ | commit-oriented | commit-oriented | ❌ | Browse *commits*, not the live working tree |
+
+**Conclusion:** the gap is real but narrow — every individual capability is a
+solved problem with a clear best-in-class library. The right build is a thin
+glue server (~200–300 lines) plus one HTML page that composes those libraries,
+not a new app.
+
+## 3. Recommended architecture
+
+**A single-file Python server + a single static HTML page.** All rendering
+happens in the browser; the server only serves files, answers git questions,
+and pushes change events. Total new code target: **under ~800 lines.**
+
+### Why this shape
+
+- The server stays trivial (static files + 4 JSON endpoints + 1 SSE stream) —
+  no template engine, no server-side rendering, no build step.
+- The heavy lifting (markdown, highlighting, diff HTML) is done by mature JS
+  libraries loaded as ES modules — exactly the "pull from best-in-class"
+  requirement.
+- Python + `uv` matches this repo's existing tooling. With
+  [PEP 723 inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/),
+  `dirview.py` declares its own dependencies and `uv run dirview.py` just works
+  in any directory, no venv setup.
+
+### Component choices (all best-in-class, all boring)
+
+| Concern | Choice | Why |
+|---|---|---|
+| HTTP server | **Starlette + uvicorn** (Python) | Minimal async framework; SSE and static files out of the box. (FastAPI works too but adds nothing we need.) |
+| File watching | **[watchfiles](https://github.com/samuelcolvin/watchfiles)** | Rust `notify`-based, the watcher behind `uvicorn --reload`; `awatch()` gives an async iterator of debounced change batches — feeds SSE directly |
+| Git interrogation | **`git` subprocess** (`status --porcelain=v2`, `diff`) | Zero dependencies, always agrees with the user's git; porcelain v2 is a stable machine format. GitPython/pygit2 add weight for no benefit here |
+| Markdown | **[markdown-it](https://github.com/markdown-it/markdown-it)** (client-side) + task-list/anchor plugins | The de-facto standard CommonMark+GFM renderer (VS Code uses it). Critically, its token `map` gives **source line ranges per block** — which is what makes requirement 5 work on *rendered* markdown |
+| Code highlighting | **[Shiki](https://shiki.style)** | TextMate-grammar highlighting (identical quality to VS Code). Ships **Catppuccin Latte/Frappé/Macchiato/Mocha as bundled themes**, and its [dual-theme mode](https://shiki.style/guide/dual-themes) emits CSS-variable output so light/dark switching is pure CSS |
+| Diff rendering | **[diff2html](https://github.com/rtfpessoa/diff2html)** | The standard "GitHub-style diff from raw `git diff` text" library; line-by-line and side-by-side; colors overridable via CSS variables → Catppuccin-able |
+| UI reactivity | **Alpine.js** | Already used by this repo's viewer; no build step; a recursive `<template>` renders the tree in ~30 lines |
+| Theme | **[@catppuccin/palette](https://github.com/catppuccin/palette)** CSS variables | Official palette as CSS custom properties; Latte = light, Mocha = dark; follow `prefers-color-scheme` with a manual toggle persisted in `localStorage` |
+
+JS libraries load from a CDN (esm.sh / jsdelivr) pinned to exact versions.
+*Trade-off:* first load needs internet. If offline use matters, a `--vendor`
+flag (or a tiny fetch-on-first-run cache) can mirror the five files locally —
+noted as an open question below.
+
+### Layout
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ dirview — ~/some/directory        [changed only ⌥] [☾/☀]       │
+├──────────────────┬─────────────────────────────────────────────┤
+│ ▸ docs           │  README.md                    [Diff] [Raw]  │
+│ ▾ scripts        │ ┌─────────────────────────────────────────┐ │
+│    gen_efl.py  M │ │                                         │ │
+│    gen_ipl.py    │ │   # Rendered markdown / highlighted     │ │
+│ ▾ viewer         │ ▌│   code, with a subtle accent bar in    │ │
+│    app.js      M │ │ │  the gutter beside changed regions    │ │
+│    index.html    │ │                                         │ │
+│  README.md     M │ └─────────────────────────────────────────┘ │
+│  new_file.md   U │                                             │
+└──────────────────┴─────────────────────────────────────────────┘
+```
+
+- Tree: collapsible directories, git status letter + Catppuccin color per file
+  (M = yellow, A/U = green, D = red, renamed = teal). A header toggle filters
+  the tree to changed/untracked files only (requirement 4).
+- Right pane header: file path, git status badge, `[Diff]` button (only when
+  the file has changes), `[Raw]` toggle for markdown source view.
+
+## 4. Server design
+
+One file, `dirview.py`, with PEP 723 metadata:
+
+```python
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["starlette", "uvicorn", "watchfiles"]
+# ///
+```
+
+CLI: `dirview.py [path] [--port 7440] [--host 127.0.0.1] [--no-open]`.
+Binds to localhost only by default. Every request path is resolved and
+verified to live under the served root (path-traversal guard). `.git/` is
+never listed or served.
+
+### Endpoints
+
+| Endpoint | Returns |
+|---|---|
+| `GET /` | The static `index.html` |
+| `GET /api/tree` | Nested JSON tree of the directory (skipping `.git`), each node annotated with git status from one `git status --porcelain=v2 --untracked-files=all` call; also flags gitignored files so the UI can dim or hide them |
+| `GET /api/file?path=` | JSON: text content, detected language (by extension), size, binary flag, git status, and `changed_ranges` — a list of `{start, end, kind}` line ranges parsed from `git diff -U0 -- <path>` hunk headers (`kind` = added/modified; deletions become zero-width markers) |
+| `GET /api/diff?path=` | Raw unified `git diff` text for that file (worktree vs HEAD, so staged + unstaged both show; untracked files are diffed against `/dev/null` via `git diff --no-index`) — fed straight to diff2html client-side |
+| `GET /raw/<path>` | Raw bytes with correct MIME type — used for images and for relative links/images inside rendered markdown |
+| `GET /api/events` | SSE stream of change events |
+
+### Watching → SSE (requirement 6)
+
+A single `watchfiles.awatch(root)` task feeds a broadcast queue consumed by
+`/api/events` subscribers. Events are debounced batches (watchfiles does this
+natively, ~50ms; we add a 200ms coalesce):
+
+```json
+{ "changed": ["scripts/gen_efl.py", "README.md"], "git": true }
+```
+
+- Changes under `.git/` (index, HEAD, refs) are **not** forwarded as file
+  events; they set `"git": true`, meaning "statuses may have moved" (e.g. the
+  user committed or staged something in a terminal).
+- Client behavior: on any event, re-fetch `/api/tree` (cheap; the tree JSON for
+  a normal project is small). If the currently open file is in `changed`, or
+  `git` is true and the open file has status, re-fetch it and re-render **while
+  preserving scroll position**. `EventSource` reconnects automatically; on
+  reconnect the client does one full refresh to resync.
+
+This is deliberately dumb — no granular cache invalidation, no tree diffing.
+At local-directory scale, re-fetching JSON is faster than being clever.
+
+## 5. Frontend design
+
+One `index.html` (Alpine.js + inline module script + inline CSS). No build.
+
+### Markdown rendering (requirement 2)
+
+- markdown-it with GFM affordances: tables, strikethrough, autolinks,
+  task-list checkboxes, heading anchors, footnotes.
+- Fenced code blocks are highlighted with the **same Shiki instance** used for
+  code files — so code inside markdown and standalone code files look
+  identical.
+- A ~10-line markdown-it core rule copies each block token's `map` (source
+  line range) onto the rendered element as `data-lines="12-18"` — the standard
+  trick from live-preview editors, reused here for change indicators (§6).
+- Relative links between files are intercepted and opened *inside* dirview
+  (tree selection follows); relative image sources are rewritten to `/raw/…`.
+  External links open in a new tab.
+- Optional (v1.1): Mermaid diagram blocks and KaTeX math, each ~5 lines of
+  glue with their standard CDN builds. Omitted from v1 to keep the page lean.
+
+### Code rendering (requirement 3)
+
+- Shiki `codeToHtml` with
+  `themes: { light: "catppuccin-latte", dark: "catppuccin-mocha" }` —
+  dual-theme CSS-variable output, so theme switching never re-highlights.
+- Language chosen by extension (Shiki's bundled grammar set covers everything
+  in a typical project; unknown extensions fall back to plain text).
+- Line numbers via CSS counters in the gutter. Large-file guard: above ~1 MB
+  or ~10k lines, skip highlighting and show plain text with a notice.
+- Binary files: images render via `/raw/`; other binaries show a metadata
+  card (name, size, status) instead of content.
+
+### Git change indication (requirements 4 & 5)
+
+Tree level: status letters + colors as in §3; "changed only" filter collapses
+the tree to changed/untracked files (directories auto-expanded).
+
+In-file, the *subtle* indicator is the familiar editor gutter bar, driven by
+`changed_ranges` from the server:
+
+- **Code files:** a 3px vertical bar in the gutter beside changed lines —
+  Catppuccin green for added, yellow for modified — plus a small red triangle
+  marker where lines were deleted. Exactly the VS Code / JetBrains gutter
+  convention, so it reads instantly and stays out of the way.
+- **Rendered markdown:** any block whose `data-lines` range intersects a
+  changed range gets a 3px accent left-border. Subtle, and it survives the
+  source→rendered transformation because of the line-map plumbing above.
+- **Click-through:** clicking any gutter bar/border, or the `[Diff]` button,
+  opens a diff panel for that file: raw `git diff` text from `/api/diff`
+  rendered by diff2html, with a line-by-line ⇄ side-by-side toggle, styled via
+  diff2html's CSS variables mapped onto Catppuccin colors. Where possible the
+  panel scrolls to the hunk containing the clicked line.
+
+### Theming
+
+`@catppuccin/palette` CSS variables define both palettes; a `data-theme`
+attribute on `<html>` selects Latte or Mocha (default follows
+`prefers-color-scheme`, toggle persisted in `localStorage`). Shiki dual themes
+and diff2html variable overrides key off the same attribute, so one attribute
+flip restyles everything with zero re-rendering.
+
+## 6. Repository layout & size budget
+
+```
+tools/dirview/
+  dirview.py        # server: CLI + endpoints + watcher   (~250 lines)
+  static/
+    index.html      # layout + Alpine templates + CSS     (~250 lines)
+    app.js          # tree/view/diff/SSE logic            (~300 lines)
+  README.md         # usage
+```
+
+If it proves generally useful it can graduate to its own repo /
+`uv tool install` package later; nothing in the design ties it to this repo.
+
+## 7. Alternatives considered and rejected
+
+1. **Just run `code serve-web`** — genuinely zero code and covers all six
+   requirements, but it's an IDE: heavy process, editing-focused chrome,
+   markdown preview is a secondary pane, and the reading experience the
+   requirements describe (calm two-pane viewer) isn't what you get. Worth
+   knowing it exists as the fallback.
+2. **Extend markserv or difit** — each would need the *other half* of the
+   feature set bolted on (git for markserv, browsing/markdown for difit),
+   inside someone else's architecture. More code than the glue server, less
+   control.
+3. **Node/Bun server instead of Python** — perfectly viable (chokidar +
+   simple-git + the same client libraries), and would allow server-side Shiki.
+   Chosen against only because this repo is uv/Python-first and PEP 723 makes
+   the Python version a self-contained single file. The frontend is identical
+   either way, so switching later is cheap.
+4. **Server-side rendering (Python-Markdown + Pygments)** — fewer moving
+   parts in the browser, but worse output quality than markdown-it + Shiki,
+   no dual-theme CSS trick, and the line-map plumbing for change indicators
+   gets harder. The client-side stack is where the best-in-class tools are.
+
+## 8. Open questions
+
+1. **Gitignored files:** hidden by default with a toggle, or always shown but
+   dimmed? (Design assumes shown-but-dimmed, toggle to hide.)
+2. **Diff baseline:** worktree vs `HEAD` (staged + unstaged together — the
+   design default) or a staged/unstaged distinction like `git diff` vs
+   `git diff --staged`? A dropdown is cheap but is it wanted?
+3. **Offline use:** is CDN-loaded JS acceptable, or should v1 vendor the five
+   libraries locally?
+4. **Mermaid/KaTeX in v1?** Cheap to add; excluded only for leanness.
+5. **Non-git directories:** everything except requirements 4–5 still works;
+   the design degrades gracefully (no status column, no diff button). Confirm
+   that's the desired behavior rather than an error.
+
+## Sources
+
+- [markserv](https://github.com/markserv/markserv), [mdserver](https://github.com/deepdadou/mdserver), [gh-markdown-preview](https://github.com/yusukebe/gh-markdown-preview), [markdown-proxy](https://github.com/patakuti/markdown-proxy) — markdown + live-reload servers survey
+- [difit](https://github.com/yoshiko-pg/difit) ([npm](https://www.npmjs.com/package/difit)), [diffhub](https://github.com/mblode/diffhub) — local GitHub-style diff viewers
+- [Ferrite](https://github.com/OlaProeis/Ferrite) — native-app near-miss
+- [Shiki dual themes](https://shiki.style/guide/dual-themes), [Shiki bundled themes](https://shiki.style/themes) — Catppuccin Latte/Mocha bundled, CSS-variable dual-theme output
+- [diff2html](https://github.com/rtfpessoa/diff2html) ([site](https://diff2html.xyz/)) — diff → HTML rendering
+- [watchfiles](https://github.com/samuelcolvin/watchfiles) ([docs](https://watchfiles.helpmanual.io/)) — Rust-backed file watching with async API
+- [Catppuccin palette](https://catppuccin.com/palette/), [catppuccin/palette](https://github.com/catppuccin/palette) — official CSS variables

From c382464540232d897cfec90fb12751f71761e9a9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 20 Jul 2026 12:29:49 +0000
Subject: [PATCH 2/5] Revise dirview design: Node stack, inline per-hunk diffs,
 standalone repo

- Switch server from Python/Starlette to Node (Hono + chokidar), since all
  rendering deps are npm-native and npx is the natural distribution channel
- Replace whole-page diff view with in-place per-hunk expansion panels
- Restructure as a standalone repository layout

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DJieA2dNDXVv7P3Q6HpCNB
---
 docs/dirview-design.md | 267 ++++++++++++++++++++++++-----------------
 1 file changed, 159 insertions(+), 108 deletions(-)

diff --git a/docs/dirview-design.md b/docs/dirview-design.md
index 48b5f7a..39d740d 100644
--- a/docs/dirview-design.md
+++ b/docs/dirview-design.md
@@ -1,15 +1,16 @@
 # dirview — Design for a Lightweight Local Directory Viewer
 
-**Status:** Design only — not yet implemented.
+**Status:** Design only — not yet implemented. Will live in its own repository;
+this copy is parked here while the design is being discussed.
 
 A small web server you run in any local directory that gives you a two-column
 browsing UI: directory tree on the left, rendered file on the right, with
 first-class markdown rendering, syntax-highlighted code, git status awareness,
-inline change indicators with click-through diffs, and live updates as files
-change on disk. Catppuccin themed (Latte light / Mocha dark).
+inline per-hunk diffs, and live updates as files change on disk. Catppuccin
+themed (Latte light / Mocha dark).
 
 ```
-uv run dirview.py            # serve the current directory at http://127.0.0.1:7440
+npx dirview            # serve the current directory at http://127.0.0.1:7440
 ```
 
 ---
@@ -20,8 +21,9 @@ uv run dirview.py            # serve the current directory at http://127.0.0.1:7
 2. GOOD markdown rendering (GitHub-flavored)
 3. GOOD code rendering (real syntax highlighting, not an afterthought)
 4. Git status shown in the tree; filter to changed/new files
-5. For changed files, a *subtle* indication of *where* changes are, with
-   click-through to a standard diff representation
+5. For changed files, a *subtle* indication of *where* changes are; clicking an
+   individual change expands that **individual hunk's diff inline, in place** —
+   never a whole-page diff view
 6. Watches the directory tree and keeps open views up to date
 
 Constraints: as little code as possible — assemble best-in-class existing
@@ -42,81 +44,82 @@ No single existing tool covers all six requirements; each covers a slice:
 
 **Conclusion:** the gap is real but narrow — every individual capability is a
 solved problem with a clear best-in-class library. The right build is a thin
-glue server (~200–300 lines) plus one HTML page that composes those libraries,
-not a new app.
+glue server plus one page that composes those libraries, not a new app.
 
 ## 3. Recommended architecture
 
-**A single-file Python server + a single static HTML page.** All rendering
-happens in the browser; the server only serves files, answers git questions,
-and pushes change events. Total new code target: **under ~800 lines.**
-
-### Why this shape
-
-- The server stays trivial (static files + 4 JSON endpoints + 1 SSE stream) —
-  no template engine, no server-side rendering, no build step.
-- The heavy lifting (markdown, highlighting, diff HTML) is done by mature JS
-  libraries loaded as ES modules — exactly the "pull from best-in-class"
-  requirement.
-- Python + `uv` matches this repo's existing tooling. With
-  [PEP 723 inline script metadata](https://packaging.python.org/en/latest/specifications/inline-script-metadata/),
-  `dirview.py` declares its own dependencies and `uv run dirview.py` just works
-  in any directory, no venv setup.
+**A small Node.js package: a ~5-route server plus one static page.** All
+rendering happens in the browser; the server only serves files, answers git
+questions, and pushes change events. Total new code target: **under ~900
+lines**, distributed as an npm package so `npx dirview` works anywhere with no
+setup.
+
+### Why Node (and not Python)
+
+An earlier draft proposed a Python/Starlette single-file server, anchored on
+the host repo's uv tooling. For a standalone tool the trade-offs point the
+other way:
+
+- **Every rendering dependency is npm-native.** markdown-it, Shiki, diff2html,
+  Alpine — the best-in-class stack *is* the JS ecosystem. With a Node package
+  they're normal pinned dependencies, bundled at publish time. The Python
+  version could only reach them via CDN at runtime (online requirement,
+  version drift) or awkward vendoring.
+- **Distribution:** `npx dirview` is the established idiom for exactly this
+  kind of tool (difit, serve, vite preview…). "First install uv" is a real
+  barrier for anyone else who wants it.
+- **One language** across server and client; the server half is trivial in
+  either language anyway (the watcher, git subprocess, and SSE all have
+  equally good Node equivalents).
+
+Bun would allow a single compiled binary and is noted as a future option
+(§7); Node ≥ 20 is chosen for ubiquity.
 
 ### Component choices (all best-in-class, all boring)
 
 | Concern | Choice | Why |
 |---|---|---|
-| HTTP server | **Starlette + uvicorn** (Python) | Minimal async framework; SSE and static files out of the box. (FastAPI works too but adds nothing we need.) |
-| File watching | **[watchfiles](https://github.com/samuelcolvin/watchfiles)** | Rust `notify`-based, the watcher behind `uvicorn --reload`; `awatch()` gives an async iterator of debounced change batches — feeds SSE directly |
-| Git interrogation | **`git` subprocess** (`status --porcelain=v2`, `diff`) | Zero dependencies, always agrees with the user's git; porcelain v2 is a stable machine format. GitPython/pygit2 add weight for no benefit here |
-| Markdown | **[markdown-it](https://github.com/markdown-it/markdown-it)** (client-side) + task-list/anchor plugins | The de-facto standard CommonMark+GFM renderer (VS Code uses it). Critically, its token `map` gives **source line ranges per block** — which is what makes requirement 5 work on *rendered* markdown |
+| HTTP server | **[Hono](https://hono.dev)** + `@hono/node-server` | Tiny, modern router with built-in static file serving and an SSE streaming helper; the whole server stays one small file |
+| File watching | **[chokidar](https://github.com/paulmillr/chokidar)** | The de-facto standard Node watcher (powers Vite et al.); handles recursive watching, debouncing quirks, and platform differences |
+| Git interrogation | **`git` subprocess** (`status --porcelain=v2`, `diff`) | Zero dependencies, always agrees with the user's git; porcelain v2 is a stable machine format. simple-git/nodegit add weight for no benefit |
+| Markdown | **[markdown-it](https://github.com/markdown-it/markdown-it)** + task-list/anchor plugins | The de-facto CommonMark+GFM renderer (VS Code uses it). Critically, its token `map` gives **source line ranges per block** — which is what makes requirement 5 work on *rendered* markdown |
 | Code highlighting | **[Shiki](https://shiki.style)** | TextMate-grammar highlighting (identical quality to VS Code). Ships **Catppuccin Latte/Frappé/Macchiato/Mocha as bundled themes**, and its [dual-theme mode](https://shiki.style/guide/dual-themes) emits CSS-variable output so light/dark switching is pure CSS |
-| Diff rendering | **[diff2html](https://github.com/rtfpessoa/diff2html)** | The standard "GitHub-style diff from raw `git diff` text" library; line-by-line and side-by-side; colors overridable via CSS variables → Catppuccin-able |
-| UI reactivity | **Alpine.js** | Already used by this repo's viewer; no build step; a recursive `<template>` renders the tree in ~30 lines |
+| Hunk diff rendering | **[diff2html](https://github.com/rtfpessoa/diff2html)** (per-hunk) | The standard "GitHub-style diff from raw `git diff` text" library; we feed it one hunk at a time (§5); colors overridable via CSS variables → Catppuccin-able |
+| UI reactivity | **Alpine.js** | No framework build; a recursive `<template>` renders the tree in ~30 lines. (If the inline-hunk DOM juggling outgrows it, preact+htm is the fallback — still buildless) |
+| Client bundling | **esbuild**, one-shot at publish | End users never build; `npx dirview` ships prebuilt assets. Solves offline use — no CDN anywhere |
 | Theme | **[@catppuccin/palette](https://github.com/catppuccin/palette)** CSS variables | Official palette as CSS custom properties; Latte = light, Mocha = dark; follow `prefers-color-scheme` with a manual toggle persisted in `localStorage` |
 
-JS libraries load from a CDN (esm.sh / jsdelivr) pinned to exact versions.
-*Trade-off:* first load needs internet. If offline use matters, a `--vendor`
-flag (or a tiny fetch-on-first-run cache) can mirror the five files locally —
-noted as an open question below.
-
 ### Layout
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
 │ dirview — ~/some/directory        [changed only ⌥] [☾/☀]       │
 ├──────────────────┬─────────────────────────────────────────────┤
-│ ▸ docs           │  README.md                    [Diff] [Raw]  │
+│ ▸ docs           │  scripts/gen_efl.py            M   [Raw]    │
 │ ▾ scripts        │ ┌─────────────────────────────────────────┐ │
-│    gen_efl.py  M │ │                                         │ │
-│    gen_ipl.py    │ │   # Rendered markdown / highlighted     │ │
-│ ▾ viewer         │ ▌│   code, with a subtle accent bar in    │ │
-│    app.js      M │ │ │  the gutter beside changed regions    │ │
-│    index.html    │ │                                         │ │
-│  README.md     M │ └─────────────────────────────────────────┘ │
-│  new_file.md   U │                                             │
+│    gen_efl.py  M │ │  12  def load_sheet(path):              │ │
+│    gen_ipl.py    │ │▌ 13      wb = openpyxl.load_workbook(   │ │
+│ ▾ viewer         │ │▌ 14      sheet = wb.active              │ │
+│    app.js      M │ │  15      return sheet                   │ │
+│    index.html    │ │      ⌄ (clicked — hunk expands inline)  │ │
+│  README.md     M │ │ ┌─────────────────────────────────────┐ │ │
+│  new_file.md   U │ │ │ - 13  wb = load_workbook(path, ro)  │ │ │
+│                  │ │ │ + 13  wb = openpyxl.load_workbook(  │ │ │
+│                  │ │ │ + 14  sheet = wb.active             │ │ │
+│                  │ │ └─────────────────────────────────────┘ │ │
+│                  │ └─────────────────────────────────────────┘ │
 └──────────────────┴─────────────────────────────────────────────┘
 ```
 
 - Tree: collapsible directories, git status letter + Catppuccin color per file
   (M = yellow, A/U = green, D = red, renamed = teal). A header toggle filters
   the tree to changed/untracked files only (requirement 4).
-- Right pane header: file path, git status badge, `[Diff]` button (only when
-  the file has changes), `[Raw]` toggle for markdown source view.
+- Right pane header: file path, git status badge, `[Raw]` toggle for markdown
+  source view.
 
 ## 4. Server design
 
-One file, `dirview.py`, with PEP 723 metadata:
-
-```python
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["starlette", "uvicorn", "watchfiles"]
-# ///
-```
-
-CLI: `dirview.py [path] [--port 7440] [--host 127.0.0.1] [--no-open]`.
+`npx dirview [path] [--port 7440] [--host 127.0.0.1] [--no-open]`.
 Binds to localhost only by default. Every request path is resolved and
 verified to live under the served root (path-traversal guard). `.git/` is
 never listed or served.
@@ -125,18 +128,38 @@ never listed or served.
 
 | Endpoint | Returns |
 |---|---|
-| `GET /` | The static `index.html` |
+| `GET /` | The prebuilt static page |
 | `GET /api/tree` | Nested JSON tree of the directory (skipping `.git`), each node annotated with git status from one `git status --porcelain=v2 --untracked-files=all` call; also flags gitignored files so the UI can dim or hide them |
-| `GET /api/file?path=` | JSON: text content, detected language (by extension), size, binary flag, git status, and `changed_ranges` — a list of `{start, end, kind}` line ranges parsed from `git diff -U0 -- <path>` hunk headers (`kind` = added/modified; deletions become zero-width markers) |
-| `GET /api/diff?path=` | Raw unified `git diff` text for that file (worktree vs HEAD, so staged + unstaged both show; untracked files are diffed against `/dev/null` via `git diff --no-index`) — fed straight to diff2html client-side |
+| `GET /api/file?path=` | JSON: text content, detected language (by extension), size, binary flag, git status, and `hunks` (below) |
 | `GET /raw/<path>` | Raw bytes with correct MIME type — used for images and for relative links/images inside rendered markdown |
 | `GET /api/events` | SSE stream of change events |
 
+### Hunk data (requirement 5)
+
+`/api/file` runs `git diff --no-color -U3 -- <path>` (worktree vs `HEAD`, so
+staged and unstaged changes both show; untracked files are diffed against
+empty via `--no-index`) and parses it **once, server-side** into:
+
+```json
+"hunks": [
+  {
+    "newStart": 13, "newLines": 2,      // where the bar goes in the current file
+    "oldStart": 13, "oldLines": 1,
+    "kind": "modified",                  // added | modified | deleted
+    "patch": "@@ -13,1 +13,2 @@ def load_sheet\n-...\n+...\n+..."
+  }
+]
+```
+
+`newStart`/`newLines` drive the gutter indicators; `patch` is the exact raw
+hunk text, ready to be handed to diff2html client-side with a synthesized file
+header. No whole-file diff endpoint exists — the hunk is the unit of diffing
+throughout, matching the interaction model.
+
 ### Watching → SSE (requirement 6)
 
-A single `watchfiles.awatch(root)` task feeds a broadcast queue consumed by
-`/api/events` subscribers. Events are debounced batches (watchfiles does this
-natively, ~50ms; we add a 200ms coalesce):
+One chokidar watcher on the root feeds a broadcast queue consumed by
+`/api/events` subscribers, coalesced into ~200ms batches:
 
 ```json
 { "changed": ["scripts/gen_efl.py", "README.md"], "git": true }
@@ -148,16 +171,15 @@ natively, ~50ms; we add a 200ms coalesce):
 - Client behavior: on any event, re-fetch `/api/tree` (cheap; the tree JSON for
   a normal project is small). If the currently open file is in `changed`, or
   `git` is true and the open file has status, re-fetch it and re-render **while
-  preserving scroll position**. `EventSource` reconnects automatically; on
-  reconnect the client does one full refresh to resync.
+  preserving scroll position and any expanded hunks that still exist**.
+  `EventSource` reconnects automatically; on reconnect the client does one full
+  refresh to resync.
 
 This is deliberately dumb — no granular cache invalidation, no tree diffing.
 At local-directory scale, re-fetching JSON is faster than being clever.
 
 ## 5. Frontend design
 
-One `index.html` (Alpine.js + inline module script + inline CSS). No build.
-
 ### Markdown rendering (requirement 2)
 
 - markdown-it with GFM affordances: tables, strikethrough, autolinks,
@@ -167,12 +189,12 @@ One `index.html` (Alpine.js + inline module script + inline CSS). No build.
   identical.
 - A ~10-line markdown-it core rule copies each block token's `map` (source
   line range) onto the rendered element as `data-lines="12-18"` — the standard
-  trick from live-preview editors, reused here for change indicators (§6).
+  trick from live-preview editors, reused here for change indicators (below).
 - Relative links between files are intercepted and opened *inside* dirview
   (tree selection follows); relative image sources are rewritten to `/raw/…`.
   External links open in a new tab.
 - Optional (v1.1): Mermaid diagram blocks and KaTeX math, each ~5 lines of
-  glue with their standard CDN builds. Omitted from v1 to keep the page lean.
+  glue with their standard npm builds. Omitted from v1 to keep the page lean.
 
 ### Code rendering (requirement 3)
 
@@ -180,7 +202,9 @@ One `index.html` (Alpine.js + inline module script + inline CSS). No build.
   `themes: { light: "catppuccin-latte", dark: "catppuccin-mocha" }` —
   dual-theme CSS-variable output, so theme switching never re-highlights.
 - Language chosen by extension (Shiki's bundled grammar set covers everything
-  in a typical project; unknown extensions fall back to plain text).
+  in a typical project; unknown extensions fall back to plain text). To keep
+  the client bundle sane, a curated grammar subset is bundled eagerly and the
+  long tail lazy-loads from the package's own assets.
 - Line numbers via CSS counters in the gutter. Large-file guard: above ~1 MB
   or ~10k lines, skip highlighting and show plain text with a notice.
 - Binary files: images render via `/raw/`; other binaries show a metadata
@@ -191,21 +215,37 @@ One `index.html` (Alpine.js + inline module script + inline CSS). No build.
 Tree level: status letters + colors as in §3; "changed only" filter collapses
 the tree to changed/untracked files (directories auto-expanded).
 
-In-file, the *subtle* indicator is the familiar editor gutter bar, driven by
-`changed_ranges` from the server:
+In-file, the *subtle* indicator is the familiar editor gutter mark, driven by
+the server's `hunks`:
 
-- **Code files:** a 3px vertical bar in the gutter beside changed lines —
-  Catppuccin green for added, yellow for modified — plus a small red triangle
-  marker where lines were deleted. Exactly the VS Code / JetBrains gutter
-  convention, so it reads instantly and stays out of the way.
+- **Code files:** a 3px vertical bar in the gutter beside each hunk's
+  `newStart..newStart+newLines` — Catppuccin green for added, yellow for
+  modified — plus a small red triangle marker where lines were deleted.
+  Exactly the VS Code / JetBrains gutter convention: legible, ignorable.
 - **Rendered markdown:** any block whose `data-lines` range intersects a
-  changed range gets a 3px accent left-border. Subtle, and it survives the
-  source→rendered transformation because of the line-map plumbing above.
-- **Click-through:** clicking any gutter bar/border, or the `[Diff]` button,
-  opens a diff panel for that file: raw `git diff` text from `/api/diff`
-  rendered by diff2html, with a line-by-line ⇄ side-by-side toggle, styled via
-  diff2html's CSS variables mapped onto Catppuccin colors. Where possible the
-  panel scrolls to the hunk containing the clicked line.
+  hunk's new-file range gets a 3px accent left-border.
+
+**Click → inline hunk expansion.** Clicking a gutter bar (or a marked
+markdown block) expands **that hunk only**, in place — the page never
+navigates away:
+
+- An expansion panel is inserted into the document flow directly below the
+  last line of the hunk (below the marked block, for markdown). Content
+  stays put above; content below shifts down, exactly like VS Code's
+  dirty-diff peek or GitHub's expanded comment threads.
+- The panel body is diff2html rendering *just that hunk*: the client wraps
+  the hunk's `patch` in a minimal synthesized diff header and calls
+  `Diff2HtmlUI` on it. Unified view by default; a per-panel toggle offers
+  side-by-side. Deleted lines therefore appear only inside the panel —
+  the main view always shows the current file.
+- Toggle behavior: click again (or the panel's ✕, or `Esc`) collapses it.
+  Multiple hunks can be open at once. A subtle "N changes" chip in the
+  header offers expand-all/collapse-all for review-the-whole-file flow.
+- On SSE-driven re-render, expanded panels re-attach to the hunk nearest
+  their old `newStart` if it still exists; vanished hunks close silently.
+
+There is deliberately **no whole-page diff mode** — the hunk panel is the
+only diff representation, so the reading context is never lost.
 
 ### Theming
 
@@ -217,38 +257,48 @@ flip restyles everything with zero re-rendering.
 
 ## 6. Repository layout & size budget
 
+Standalone repo (name TBD — working title `dirview`):
+
 ```
-tools/dirview/
-  dirview.py        # server: CLI + endpoints + watcher   (~250 lines)
-  static/
-    index.html      # layout + Alpine templates + CSS     (~250 lines)
-    app.js          # tree/view/diff/SSE logic            (~300 lines)
-  README.md         # usage
+dirview/
+  package.json          # bin: {"dirview": "bin/dirview.js"}; publishes dist/
+  bin/dirview.js        # CLI arg parsing, open browser        (~40 lines)
+  server/index.js       # Hono app: routes, git, chokidar→SSE  (~280 lines)
+  web/
+    index.html          # layout + Alpine templates            (~120 lines)
+    app.js              # tree/view/hunk/SSE logic             (~350 lines)
+    style.css           # Catppuccin variables + layout        (~150 lines)
+  scripts/build.js      # esbuild one-shot → dist/             (~30 lines)
+  dist/                 # prebuilt client (generated, published to npm)
 ```
 
-If it proves generally useful it can graduate to its own repo /
-`uv tool install` package later; nothing in the design ties it to this repo.
+Plain modern ESM JavaScript, no TypeScript compile step (JSDoc types where
+they pay for themselves); esbuild exists only to bundle the client libraries.
 
 ## 7. Alternatives considered and rejected
 
 1. **Just run `code serve-web`** — genuinely zero code and covers all six
-   requirements, but it's an IDE: heavy process, editing-focused chrome,
-   markdown preview is a secondary pane, and the reading experience the
-   requirements describe (calm two-pane viewer) isn't what you get. Worth
-   knowing it exists as the fallback.
+   requirements, but it's an IDE: heavy process, editing-focused chrome, and
+   the reading experience the requirements describe isn't what you get.
 2. **Extend markserv or difit** — each would need the *other half* of the
    feature set bolted on (git for markserv, browsing/markdown for difit),
    inside someone else's architecture. More code than the glue server, less
    control.
-3. **Node/Bun server instead of Python** — perfectly viable (chokidar +
-   simple-git + the same client libraries), and would allow server-side Shiki.
-   Chosen against only because this repo is uv/Python-first and PEP 723 makes
-   the Python version a self-contained single file. The frontend is identical
-   either way, so switching later is cheap.
-4. **Server-side rendering (Python-Markdown + Pygments)** — fewer moving
-   parts in the browser, but worse output quality than markdown-it + Shiki,
-   no dual-theme CSS trick, and the line-map plumbing for change indicators
-   gets harder. The client-side stack is where the best-in-class tools are.
+3. **Python (Starlette + uvicorn + watchfiles), PEP 723 single file** — the
+   first draft of this design. Rejected for a standalone tool: all client
+   libraries are npm-native (Python could only reach them via CDN at runtime),
+   `npx` is the natural distribution channel for this category, and one
+   language beats two. watchfiles/Starlette were fine; the ecosystem seam
+   was the problem.
+4. **Bun instead of Node** — attractive (single compiled binary via
+   `bun build --compile`, built-in server and watcher), deliberately kept as
+   a *future packaging option* rather than a requirement: the code is plain
+   ESM and doesn't preclude it, but Node ≥ 20 is what everyone already has.
+5. **Server-side rendering (markdown/highlighting on the server)** — fewer
+   moving parts in the browser and Shiki can run in Node, but the dual-theme
+   CSS trick, scroll-preserving in-place re-renders, and markdown line-map
+   plumbing are all simpler with client-side rendering. The server stays a
+   dumb file/git/events API.
 
 ## 8. Open questions
 
@@ -257,12 +307,12 @@ If it proves generally useful it can graduate to its own repo /
 2. **Diff baseline:** worktree vs `HEAD` (staged + unstaged together — the
    design default) or a staged/unstaged distinction like `git diff` vs
    `git diff --staged`? A dropdown is cheap but is it wanted?
-3. **Offline use:** is CDN-loaded JS acceptable, or should v1 vendor the five
-   libraries locally?
-4. **Mermaid/KaTeX in v1?** Cheap to add; excluded only for leanness.
-5. **Non-git directories:** everything except requirements 4–5 still works;
-   the design degrades gracefully (no status column, no diff button). Confirm
-   that's the desired behavior rather than an error.
+3. **Mermaid/KaTeX in v1?** Cheap to add; excluded only for leanness.
+4. **Non-git directories:** everything except requirements 4–5 still works;
+   the design degrades gracefully (no status column, no gutter marks).
+   Confirm that's the desired behavior rather than an error.
+5. **Name:** `dirview` is a working title (npm has crowded namespaces here —
+   check availability before publishing).
 
 ## Sources
 
@@ -271,5 +321,6 @@ If it proves generally useful it can graduate to its own repo /
 - [Ferrite](https://github.com/OlaProeis/Ferrite) — native-app near-miss
 - [Shiki dual themes](https://shiki.style/guide/dual-themes), [Shiki bundled themes](https://shiki.style/themes) — Catppuccin Latte/Mocha bundled, CSS-variable dual-theme output
 - [diff2html](https://github.com/rtfpessoa/diff2html) ([site](https://diff2html.xyz/)) — diff → HTML rendering
-- [watchfiles](https://github.com/samuelcolvin/watchfiles) ([docs](https://watchfiles.helpmanual.io/)) — Rust-backed file watching with async API
+- [chokidar](https://github.com/paulmillr/chokidar) — file watching
+- [Hono](https://hono.dev) — minimal HTTP framework with SSE helper
 - [Catppuccin palette](https://catppuccin.com/palette/), [catppuccin/palette](https://github.com/catppuccin/palette) — official CSS variables

From d667c6f0bfeeef2add63e00176b52d0e4321223e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 20 Jul 2026 12:35:11 +0000
Subject: [PATCH 3/5] Rename tool to peruse; note scoped npm package
 @talkasab/peruse

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DJieA2dNDXVv7P3Q6HpCNB
---
 docs/{dirview-design.md => peruse-design.md} | 33 +++++++++++---------
 1 file changed, 19 insertions(+), 14 deletions(-)
 rename docs/{dirview-design.md => peruse-design.md} (94%)

diff --git a/docs/dirview-design.md b/docs/peruse-design.md
similarity index 94%
rename from docs/dirview-design.md
rename to docs/peruse-design.md
index 39d740d..1d68dd9 100644
--- a/docs/dirview-design.md
+++ b/docs/peruse-design.md
@@ -1,4 +1,4 @@
-# dirview — Design for a Lightweight Local Directory Viewer
+# peruse — Design for a Lightweight Local Directory Viewer
 
 **Status:** Design only — not yet implemented. Will live in its own repository;
 this copy is parked here while the design is being discussed.
@@ -10,9 +10,14 @@ inline per-hunk diffs, and live updates as files change on disk. Catppuccin
 themed (Latte light / Mocha dark).
 
 ```
-npx dirview            # serve the current directory at http://127.0.0.1:7440
+npx @talkasab/peruse   # serve the current directory at http://127.0.0.1:7440
 ```
 
+(The bare npm name `peruse` is squatted by an abandoned 2017 package, so the
+package publishes under a scope; the installed command is still `peruse`.
+Until it's published, `npx github:talkasab/peruse` works straight from the
+repo.)
+
 ---
 
 ## 1. Requirements
@@ -51,7 +56,7 @@ glue server plus one page that composes those libraries, not a new app.
 **A small Node.js package: a ~5-route server plus one static page.** All
 rendering happens in the browser; the server only serves files, answers git
 questions, and pushes change events. Total new code target: **under ~900
-lines**, distributed as an npm package so `npx dirview` works anywhere with no
+lines**, distributed as an npm package so `npx @talkasab/peruse` works anywhere with no
 setup.
 
 ### Why Node (and not Python)
@@ -65,7 +70,7 @@ other way:
   they're normal pinned dependencies, bundled at publish time. The Python
   version could only reach them via CDN at runtime (online requirement,
   version drift) or awkward vendoring.
-- **Distribution:** `npx dirview` is the established idiom for exactly this
+- **Distribution:** `npx <package>` is the established idiom for exactly this
   kind of tool (difit, serve, vite preview…). "First install uv" is a real
   barrier for anyone else who wants it.
 - **One language** across server and client; the server half is trivial in
@@ -86,14 +91,14 @@ Bun would allow a single compiled binary and is noted as a future option
 | Code highlighting | **[Shiki](https://shiki.style)** | TextMate-grammar highlighting (identical quality to VS Code). Ships **Catppuccin Latte/Frappé/Macchiato/Mocha as bundled themes**, and its [dual-theme mode](https://shiki.style/guide/dual-themes) emits CSS-variable output so light/dark switching is pure CSS |
 | Hunk diff rendering | **[diff2html](https://github.com/rtfpessoa/diff2html)** (per-hunk) | The standard "GitHub-style diff from raw `git diff` text" library; we feed it one hunk at a time (§5); colors overridable via CSS variables → Catppuccin-able |
 | UI reactivity | **Alpine.js** | No framework build; a recursive `<template>` renders the tree in ~30 lines. (If the inline-hunk DOM juggling outgrows it, preact+htm is the fallback — still buildless) |
-| Client bundling | **esbuild**, one-shot at publish | End users never build; `npx dirview` ships prebuilt assets. Solves offline use — no CDN anywhere |
+| Client bundling | **esbuild**, one-shot at publish | End users never build; `npx` ships prebuilt assets. Solves offline use — no CDN anywhere |
 | Theme | **[@catppuccin/palette](https://github.com/catppuccin/palette)** CSS variables | Official palette as CSS custom properties; Latte = light, Mocha = dark; follow `prefers-color-scheme` with a manual toggle persisted in `localStorage` |
 
 ### Layout
 
 ```
 ┌────────────────────────────────────────────────────────────────┐
-│ dirview — ~/some/directory        [changed only ⌥] [☾/☀]       │
+│ peruse — ~/some/directory        [changed only ⌥] [☾/☀]       │
 ├──────────────────┬─────────────────────────────────────────────┤
 │ ▸ docs           │  scripts/gen_efl.py            M   [Raw]    │
 │ ▾ scripts        │ ┌─────────────────────────────────────────┐ │
@@ -119,7 +124,7 @@ Bun would allow a single compiled binary and is noted as a future option
 
 ## 4. Server design
 
-`npx dirview [path] [--port 7440] [--host 127.0.0.1] [--no-open]`.
+`peruse [path] [--port 7440] [--host 127.0.0.1] [--no-open]`.
 Binds to localhost only by default. Every request path is resolved and
 verified to live under the served root (path-traversal guard). `.git/` is
 never listed or served.
@@ -190,7 +195,7 @@ At local-directory scale, re-fetching JSON is faster than being clever.
 - A ~10-line markdown-it core rule copies each block token's `map` (source
   line range) onto the rendered element as `data-lines="12-18"` — the standard
   trick from live-preview editors, reused here for change indicators (below).
-- Relative links between files are intercepted and opened *inside* dirview
+- Relative links between files are intercepted and opened *inside* peruse
   (tree selection follows); relative image sources are rewritten to `/raw/…`.
   External links open in a new tab.
 - Optional (v1.1): Mermaid diagram blocks and KaTeX math, each ~5 lines of
@@ -257,12 +262,12 @@ flip restyles everything with zero re-rendering.
 
 ## 6. Repository layout & size budget
 
-Standalone repo (name TBD — working title `dirview`):
+Standalone repo (name TBD — working title `peruse`):
 
 ```
-dirview/
-  package.json          # bin: {"dirview": "bin/dirview.js"}; publishes dist/
-  bin/dirview.js        # CLI arg parsing, open browser        (~40 lines)
+peruse/
+  package.json          # bin: {"peruse": "bin/peruse.js"}; publishes dist/
+  bin/peruse.js        # CLI arg parsing, open browser        (~40 lines)
   server/index.js       # Hono app: routes, git, chokidar→SSE  (~280 lines)
   web/
     index.html          # layout + Alpine templates            (~120 lines)
@@ -311,8 +316,8 @@ they pay for themselves); esbuild exists only to bundle the client libraries.
 4. **Non-git directories:** everything except requirements 4–5 still works;
    the design degrades gracefully (no status column, no gutter marks).
    Confirm that's the desired behavior rather than an error.
-5. **Name:** `dirview` is a working title (npm has crowded namespaces here —
-   check availability before publishing).
+5. ~~**Name**~~ Resolved: `peruse`, repo `talkasab/peruse`, published as
+   `@talkasab/peruse` (bare npm name is squatted); installed bin is `peruse`.
 
 ## Sources
 

From 8c4aeed2567044af4f87248994095c33b4f4557f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 20 Jul 2026 12:37:14 +0000
Subject: [PATCH 4/5] Switch peruse design runtime from Node to Bun

Bun.serve replaces Hono, bun build replaces esbuild, and bun build
--compile adds standalone per-platform binaries; chokidar remains the
sole server dependency due to Bun native watcher reliability gaps.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DJieA2dNDXVv7P3Q6HpCNB
---
 docs/peruse-design.md | 84 ++++++++++++++++++++++---------------------
 1 file changed, 44 insertions(+), 40 deletions(-)

diff --git a/docs/peruse-design.md b/docs/peruse-design.md
index 1d68dd9..2c72a80 100644
--- a/docs/peruse-design.md
+++ b/docs/peruse-design.md
@@ -10,13 +10,14 @@ inline per-hunk diffs, and live updates as files change on disk. Catppuccin
 themed (Latte light / Mocha dark).
 
 ```
-npx @talkasab/peruse   # serve the current directory at http://127.0.0.1:7440
+bunx @talkasab/peruse   # serve the current directory at http://127.0.0.1:7440
 ```
 
 (The bare npm name `peruse` is squatted by an abandoned 2017 package, so the
 package publishes under a scope; the installed command is still `peruse`.
-Until it's published, `npx github:talkasab/peruse` works straight from the
-repo.)
+Until it's published, `bunx github:talkasab/peruse` works straight from the
+repo, and `bun build --compile` produces standalone per-platform binaries for
+GitHub releases — no Bun required by the end user.)
 
 ---
 
@@ -53,45 +54,44 @@ glue server plus one page that composes those libraries, not a new app.
 
 ## 3. Recommended architecture
 
-**A small Node.js package: a ~5-route server plus one static page.** All
+**A small Bun package: a ~5-route server plus one static page.** All
 rendering happens in the browser; the server only serves files, answers git
 questions, and pushes change events. Total new code target: **under ~900
-lines**, distributed as an npm package so `npx @talkasab/peruse` works anywhere with no
-setup.
+lines**, distributed as an npm package (`bunx @talkasab/peruse`) and as
+standalone compiled binaries.
 
-### Why Node (and not Python)
+### Why Bun
 
-An earlier draft proposed a Python/Starlette single-file server, anchored on
-the host repo's uv tooling. For a standalone tool the trade-offs point the
-other way:
+An earlier draft proposed a Python/Starlette single-file server (anchored on
+the host repo's uv tooling — see §7), then Node. Bun is the better fit for
+the "as little code as possible" constraint:
 
 - **Every rendering dependency is npm-native.** markdown-it, Shiki, diff2html,
-  Alpine — the best-in-class stack *is* the JS ecosystem. With a Node package
-  they're normal pinned dependencies, bundled at publish time. The Python
-  version could only reach them via CDN at runtime (online requirement,
-  version drift) or awkward vendoring.
-- **Distribution:** `npx <package>` is the established idiom for exactly this
-  kind of tool (difit, serve, vite preview…). "First install uv" is a real
-  barrier for anyone else who wants it.
-- **One language** across server and client; the server half is trivial in
-  either language anyway (the watcher, git subprocess, and SSE all have
-  equally good Node equivalents).
-
-Bun would allow a single compiled binary and is noted as a future option
-(§7); Node ≥ 20 is chosen for ubiquity.
+  Alpine — the best-in-class stack *is* the JS ecosystem, and Bun consumes it
+  directly as normal pinned dependencies, bundled at publish time.
+- **Bun's built-ins replace three dependencies.** `Bun.serve` (HTTP + routing
+  + streaming SSE via `ReadableStream`) replaces Hono; the built-in
+  `bun build` bundler replaces esbuild; `Bun.spawn` covers the git
+  subprocess. The server ends up with **one** external runtime dependency
+  (the file watcher).
+- **Distribution:** `bunx @talkasab/peruse` for Bun users, and
+  `bun build --compile` cross-compiles standalone single-file executables
+  (macOS arm64/x64, Linux, Windows) for GitHub releases — end users need
+  nothing installed at all, not even Bun.
+- **One language** across server and client.
 
 ### Component choices (all best-in-class, all boring)
 
 | Concern | Choice | Why |
 |---|---|---|
-| HTTP server | **[Hono](https://hono.dev)** + `@hono/node-server` | Tiny, modern router with built-in static file serving and an SSE streaming helper; the whole server stays one small file |
-| File watching | **[chokidar](https://github.com/paulmillr/chokidar)** | The de-facto standard Node watcher (powers Vite et al.); handles recursive watching, debouncing quirks, and platform differences |
+| HTTP server | **`Bun.serve`** (built-in) | Five routes need no framework: Bun.serve's `routes` map + `Bun.file` static serving + a `ReadableStream` for SSE keep the server one small zero-framework file |
+| File watching | **[chokidar](https://github.com/paulmillr/chokidar)** | The de-facto standard watcher (powers Vite et al.), runs fine on Bun. Bun's native `fs.watch` has [known event-reliability gaps](https://github.com/oven-sh/bun/discussions/1571), so the battle-tested library earns its place as the server's only dependency; revisit if Bun's watcher matures |
 | Git interrogation | **`git` subprocess** (`status --porcelain=v2`, `diff`) | Zero dependencies, always agrees with the user's git; porcelain v2 is a stable machine format. simple-git/nodegit add weight for no benefit |
 | Markdown | **[markdown-it](https://github.com/markdown-it/markdown-it)** + task-list/anchor plugins | The de-facto CommonMark+GFM renderer (VS Code uses it). Critically, its token `map` gives **source line ranges per block** — which is what makes requirement 5 work on *rendered* markdown |
 | Code highlighting | **[Shiki](https://shiki.style)** | TextMate-grammar highlighting (identical quality to VS Code). Ships **Catppuccin Latte/Frappé/Macchiato/Mocha as bundled themes**, and its [dual-theme mode](https://shiki.style/guide/dual-themes) emits CSS-variable output so light/dark switching is pure CSS |
 | Hunk diff rendering | **[diff2html](https://github.com/rtfpessoa/diff2html)** (per-hunk) | The standard "GitHub-style diff from raw `git diff` text" library; we feed it one hunk at a time (§5); colors overridable via CSS variables → Catppuccin-able |
 | UI reactivity | **Alpine.js** | No framework build; a recursive `<template>` renders the tree in ~30 lines. (If the inline-hunk DOM juggling outgrows it, preact+htm is the fallback — still buildless) |
-| Client bundling | **esbuild**, one-shot at publish | End users never build; `npx` ships prebuilt assets. Solves offline use — no CDN anywhere |
+| Client bundling | **`bun build`** (built-in), one-shot at publish | End users never build; the package ships prebuilt assets. Solves offline use — no CDN anywhere |
 | Theme | **[@catppuccin/palette](https://github.com/catppuccin/palette)** CSS variables | Official palette as CSS custom properties; Latte = light, Mocha = dark; follow `prefers-color-scheme` with a manual toggle persisted in `localStorage` |
 
 ### Layout
@@ -262,23 +262,24 @@ flip restyles everything with zero re-rendering.
 
 ## 6. Repository layout & size budget
 
-Standalone repo (name TBD — working title `peruse`):
+Standalone repo `talkasab/peruse`:
 
 ```
 peruse/
-  package.json          # bin: {"peruse": "bin/peruse.js"}; publishes dist/
-  bin/peruse.js        # CLI arg parsing, open browser        (~40 lines)
-  server/index.js       # Hono app: routes, git, chokidar→SSE  (~280 lines)
+  package.json          # name @talkasab/peruse; bin {"peruse": "bin/peruse.js"}
+  bin/peruse.js         # CLI arg parsing, open browser        (~40 lines)
+  server/index.js       # Bun.serve routes, git, chokidar→SSE  (~280 lines)
   web/
     index.html          # layout + Alpine templates            (~120 lines)
     app.js              # tree/view/hunk/SSE logic             (~350 lines)
     style.css           # Catppuccin variables + layout        (~150 lines)
-  scripts/build.js      # esbuild one-shot → dist/             (~30 lines)
-  dist/                 # prebuilt client (generated, published to npm)
+  dist/                 # prebuilt client (bun build; published to npm)
 ```
 
 Plain modern ESM JavaScript, no TypeScript compile step (JSDoc types where
-they pay for themselves); esbuild exists only to bundle the client libraries.
+they pay for themselves). `bun build` bundles the client libraries into
+`dist/` at publish time; a release script runs `bun build --compile` per
+target platform to attach standalone binaries to GitHub releases.
 
 ## 7. Alternatives considered and rejected
 
@@ -292,15 +293,17 @@ they pay for themselves); esbuild exists only to bundle the client libraries.
 3. **Python (Starlette + uvicorn + watchfiles), PEP 723 single file** — the
    first draft of this design. Rejected for a standalone tool: all client
    libraries are npm-native (Python could only reach them via CDN at runtime),
-   `npx` is the natural distribution channel for this category, and one
+   `npx`/`bunx` is the natural distribution channel for this category, and one
    language beats two. watchfiles/Starlette were fine; the ecosystem seam
    was the problem.
-4. **Bun instead of Node** — attractive (single compiled binary via
-   `bun build --compile`, built-in server and watcher), deliberately kept as
-   a *future packaging option* rather than a requirement: the code is plain
-   ESM and doesn't preclude it, but Node ≥ 20 is what everyone already has.
+4. **Node instead of Bun** — the second draft (Node ≥ 20 + Hono + chokidar +
+   esbuild). Node's ubiquity is real, but it costs two extra dependencies
+   (Hono, esbuild) that Bun provides built-in, and it has no answer to
+   `bun build --compile` standalone binaries — which cover the "I don't have
+   Bun" case better than Node ubiquity covers the "I don't have Node" case.
+   The code stays plain ESM, so a Node port remains cheap if ever needed.
 5. **Server-side rendering (markdown/highlighting on the server)** — fewer
-   moving parts in the browser and Shiki can run in Node, but the dual-theme
+   moving parts in the browser and Shiki runs fine in Bun, but the dual-theme
    CSS trick, scroll-preserving in-place re-renders, and markdown line-map
    plumbing are all simpler with client-side rendering. The server stays a
    dumb file/git/events API.
@@ -327,5 +330,6 @@ they pay for themselves); esbuild exists only to bundle the client libraries.
 - [Shiki dual themes](https://shiki.style/guide/dual-themes), [Shiki bundled themes](https://shiki.style/themes) — Catppuccin Latte/Mocha bundled, CSS-variable dual-theme output
 - [diff2html](https://github.com/rtfpessoa/diff2html) ([site](https://diff2html.xyz/)) — diff → HTML rendering
 - [chokidar](https://github.com/paulmillr/chokidar) — file watching
-- [Hono](https://hono.dev) — minimal HTTP framework with SSE helper
+- [Bun](https://bun.sh) — runtime; `Bun.serve`, `bun build`, `bun build --compile`
+- [Bun watcher reliability discussion](https://github.com/oven-sh/bun/discussions/1571) — why chokidar stays
 - [Catppuccin palette](https://catppuccin.com/palette/), [catppuccin/palette](https://github.com/catppuccin/palette) — official CSS variables

From 9a97167eb9aa7d687588f1be82a66baef669e0b9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 21 Jul 2026 12:18:35 +0000
Subject: [PATCH 5/5] Remove peruse design doc; moved to its own repository
 (talkasab/peruse)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DJieA2dNDXVv7P3Q6HpCNB
---
 docs/peruse-design.md | 335 ------------------------------------------
 1 file changed, 335 deletions(-)
 delete mode 100644 docs/peruse-design.md

diff --git a/docs/peruse-design.md b/docs/peruse-design.md
deleted file mode 100644
index 2c72a80..0000000
--- a/docs/peruse-design.md
+++ /dev/null
@@ -1,335 +0,0 @@
-# peruse — Design for a Lightweight Local Directory Viewer
-
-**Status:** Design only — not yet implemented. Will live in its own repository;
-this copy is parked here while the design is being discussed.
-
-A small web server you run in any local directory that gives you a two-column
-browsing UI: directory tree on the left, rendered file on the right, with
-first-class markdown rendering, syntax-highlighted code, git status awareness,
-inline per-hunk diffs, and live updates as files change on disk. Catppuccin
-themed (Latte light / Mocha dark).
-
-```
-bunx @talkasab/peruse   # serve the current directory at http://127.0.0.1:7440
-```
-
-(The bare npm name `peruse` is squatted by an abandoned 2017 package, so the
-package publishes under a scope; the installed command is still `peruse`.
-Until it's published, `bunx github:talkasab/peruse` works straight from the
-repo, and `bun build --compile` produces standalone per-platform binaries for
-GitHub releases — no Bun required by the end user.)
-
----
-
-## 1. Requirements
-
-1. Two-column layout: directory tree (left), viewed file (right)
-2. GOOD markdown rendering (GitHub-flavored)
-3. GOOD code rendering (real syntax highlighting, not an afterthought)
-4. Git status shown in the tree; filter to changed/new files
-5. For changed files, a *subtle* indication of *where* changes are; clicking an
-   individual change expands that **individual hunk's diff inline, in place** —
-   never a whole-page diff view
-6. Watches the directory tree and keeps open views up to date
-
-Constraints: as little code as possible — assemble best-in-class existing
-solutions rather than building anything from scratch. Catppuccin light + dark.
-
-## 2. Research: what already exists
-
-No single existing tool covers all six requirements; each covers a slice:
-
-| Tool | Tree | Markdown | Code | Git status | Inline diffs | Watch | Verdict |
-|---|---|---|---|---|---|---|---|
-| [markserv](https://github.com/markserv/markserv) / [mdserver](https://github.com/deepdadou/mdserver) / [gh-markdown-preview](https://github.com/yusukebe/gh-markdown-preview) | dir index only | ✅ | partial | ❌ | ❌ | ✅ | Markdown + live reload, no git at all |
-| [difit](https://github.com/yoshiko-pg/difit) | changed files only | ❌ | ✅ | ✅ | ✅ (GitHub-style) | partial | Excellent diff review UI, but not a directory *browser* — no markdown, no unchanged files |
-| [diffhub](https://github.com/mblode/diffhub) | changed files only | ❌ | ✅ | ✅ | ✅ | ❌ | Same category as difit |
-| `code serve-web` / code-server | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Covers everything but is a full IDE: heavyweight, editing-oriented, not a calm reading view |
-| [Ferrite](https://github.com/OlaProeis/Ferrite) | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | Native desktop app (Rust/egui), not a web server |
-| klaus / gitweb / Gitea | ✅ | ✅ | ✅ | commit-oriented | commit-oriented | ❌ | Browse *commits*, not the live working tree |
-
-**Conclusion:** the gap is real but narrow — every individual capability is a
-solved problem with a clear best-in-class library. The right build is a thin
-glue server plus one page that composes those libraries, not a new app.
-
-## 3. Recommended architecture
-
-**A small Bun package: a ~5-route server plus one static page.** All
-rendering happens in the browser; the server only serves files, answers git
-questions, and pushes change events. Total new code target: **under ~900
-lines**, distributed as an npm package (`bunx @talkasab/peruse`) and as
-standalone compiled binaries.
-
-### Why Bun
-
-An earlier draft proposed a Python/Starlette single-file server (anchored on
-the host repo's uv tooling — see §7), then Node. Bun is the better fit for
-the "as little code as possible" constraint:
-
-- **Every rendering dependency is npm-native.** markdown-it, Shiki, diff2html,
-  Alpine — the best-in-class stack *is* the JS ecosystem, and Bun consumes it
-  directly as normal pinned dependencies, bundled at publish time.
-- **Bun's built-ins replace three dependencies.** `Bun.serve` (HTTP + routing
-  + streaming SSE via `ReadableStream`) replaces Hono; the built-in
-  `bun build` bundler replaces esbuild; `Bun.spawn` covers the git
-  subprocess. The server ends up with **one** external runtime dependency
-  (the file watcher).
-- **Distribution:** `bunx @talkasab/peruse` for Bun users, and
-  `bun build --compile` cross-compiles standalone single-file executables
-  (macOS arm64/x64, Linux, Windows) for GitHub releases — end users need
-  nothing installed at all, not even Bun.
-- **One language** across server and client.
-
-### Component choices (all best-in-class, all boring)
-
-| Concern | Choice | Why |
-|---|---|---|
-| HTTP server | **`Bun.serve`** (built-in) | Five routes need no framework: Bun.serve's `routes` map + `Bun.file` static serving + a `ReadableStream` for SSE keep the server one small zero-framework file |
-| File watching | **[chokidar](https://github.com/paulmillr/chokidar)** | The de-facto standard watcher (powers Vite et al.), runs fine on Bun. Bun's native `fs.watch` has [known event-reliability gaps](https://github.com/oven-sh/bun/discussions/1571), so the battle-tested library earns its place as the server's only dependency; revisit if Bun's watcher matures |
-| Git interrogation | **`git` subprocess** (`status --porcelain=v2`, `diff`) | Zero dependencies, always agrees with the user's git; porcelain v2 is a stable machine format. simple-git/nodegit add weight for no benefit |
-| Markdown | **[markdown-it](https://github.com/markdown-it/markdown-it)** + task-list/anchor plugins | The de-facto CommonMark+GFM renderer (VS Code uses it). Critically, its token `map` gives **source line ranges per block** — which is what makes requirement 5 work on *rendered* markdown |
-| Code highlighting | **[Shiki](https://shiki.style)** | TextMate-grammar highlighting (identical quality to VS Code). Ships **Catppuccin Latte/Frappé/Macchiato/Mocha as bundled themes**, and its [dual-theme mode](https://shiki.style/guide/dual-themes) emits CSS-variable output so light/dark switching is pure CSS |
-| Hunk diff rendering | **[diff2html](https://github.com/rtfpessoa/diff2html)** (per-hunk) | The standard "GitHub-style diff from raw `git diff` text" library; we feed it one hunk at a time (§5); colors overridable via CSS variables → Catppuccin-able |
-| UI reactivity | **Alpine.js** | No framework build; a recursive `<template>` renders the tree in ~30 lines. (If the inline-hunk DOM juggling outgrows it, preact+htm is the fallback — still buildless) |
-| Client bundling | **`bun build`** (built-in), one-shot at publish | End users never build; the package ships prebuilt assets. Solves offline use — no CDN anywhere |
-| Theme | **[@catppuccin/palette](https://github.com/catppuccin/palette)** CSS variables | Official palette as CSS custom properties; Latte = light, Mocha = dark; follow `prefers-color-scheme` with a manual toggle persisted in `localStorage` |
-
-### Layout
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│ peruse — ~/some/directory        [changed only ⌥] [☾/☀]       │
-├──────────────────┬─────────────────────────────────────────────┤
-│ ▸ docs           │  scripts/gen_efl.py            M   [Raw]    │
-│ ▾ scripts        │ ┌─────────────────────────────────────────┐ │
-│    gen_efl.py  M │ │  12  def load_sheet(path):              │ │
-│    gen_ipl.py    │ │▌ 13      wb = openpyxl.load_workbook(   │ │
-│ ▾ viewer         │ │▌ 14      sheet = wb.active              │ │
-│    app.js      M │ │  15      return sheet                   │ │
-│    index.html    │ │      ⌄ (clicked — hunk expands inline)  │ │
-│  README.md     M │ │ ┌─────────────────────────────────────┐ │ │
-│  new_file.md   U │ │ │ - 13  wb = load_workbook(path, ro)  │ │ │
-│                  │ │ │ + 13  wb = openpyxl.load_workbook(  │ │ │
-│                  │ │ │ + 14  sheet = wb.active             │ │ │
-│                  │ │ └─────────────────────────────────────┘ │ │
-│                  │ └─────────────────────────────────────────┘ │
-└──────────────────┴─────────────────────────────────────────────┘
-```
-
-- Tree: collapsible directories, git status letter + Catppuccin color per file
-  (M = yellow, A/U = green, D = red, renamed = teal). A header toggle filters
-  the tree to changed/untracked files only (requirement 4).
-- Right pane header: file path, git status badge, `[Raw]` toggle for markdown
-  source view.
-
-## 4. Server design
-
-`peruse [path] [--port 7440] [--host 127.0.0.1] [--no-open]`.
-Binds to localhost only by default. Every request path is resolved and
-verified to live under the served root (path-traversal guard). `.git/` is
-never listed or served.
-
-### Endpoints
-
-| Endpoint | Returns |
-|---|---|
-| `GET /` | The prebuilt static page |
-| `GET /api/tree` | Nested JSON tree of the directory (skipping `.git`), each node annotated with git status from one `git status --porcelain=v2 --untracked-files=all` call; also flags gitignored files so the UI can dim or hide them |
-| `GET /api/file?path=` | JSON: text content, detected language (by extension), size, binary flag, git status, and `hunks` (below) |
-| `GET /raw/<path>` | Raw bytes with correct MIME type — used for images and for relative links/images inside rendered markdown |
-| `GET /api/events` | SSE stream of change events |
-
-### Hunk data (requirement 5)
-
-`/api/file` runs `git diff --no-color -U3 -- <path>` (worktree vs `HEAD`, so
-staged and unstaged changes both show; untracked files are diffed against
-empty via `--no-index`) and parses it **once, server-side** into:
-
-```json
-"hunks": [
-  {
-    "newStart": 13, "newLines": 2,      // where the bar goes in the current file
-    "oldStart": 13, "oldLines": 1,
-    "kind": "modified",                  // added | modified | deleted
-    "patch": "@@ -13,1 +13,2 @@ def load_sheet\n-...\n+...\n+..."
-  }
-]
-```
-
-`newStart`/`newLines` drive the gutter indicators; `patch` is the exact raw
-hunk text, ready to be handed to diff2html client-side with a synthesized file
-header. No whole-file diff endpoint exists — the hunk is the unit of diffing
-throughout, matching the interaction model.
-
-### Watching → SSE (requirement 6)
-
-One chokidar watcher on the root feeds a broadcast queue consumed by
-`/api/events` subscribers, coalesced into ~200ms batches:
-
-```json
-{ "changed": ["scripts/gen_efl.py", "README.md"], "git": true }
-```
-
-- Changes under `.git/` (index, HEAD, refs) are **not** forwarded as file
-  events; they set `"git": true`, meaning "statuses may have moved" (e.g. the
-  user committed or staged something in a terminal).
-- Client behavior: on any event, re-fetch `/api/tree` (cheap; the tree JSON for
-  a normal project is small). If the currently open file is in `changed`, or
-  `git` is true and the open file has status, re-fetch it and re-render **while
-  preserving scroll position and any expanded hunks that still exist**.
-  `EventSource` reconnects automatically; on reconnect the client does one full
-  refresh to resync.
-
-This is deliberately dumb — no granular cache invalidation, no tree diffing.
-At local-directory scale, re-fetching JSON is faster than being clever.
-
-## 5. Frontend design
-
-### Markdown rendering (requirement 2)
-
-- markdown-it with GFM affordances: tables, strikethrough, autolinks,
-  task-list checkboxes, heading anchors, footnotes.
-- Fenced code blocks are highlighted with the **same Shiki instance** used for
-  code files — so code inside markdown and standalone code files look
-  identical.
-- A ~10-line markdown-it core rule copies each block token's `map` (source
-  line range) onto the rendered element as `data-lines="12-18"` — the standard
-  trick from live-preview editors, reused here for change indicators (below).
-- Relative links between files are intercepted and opened *inside* peruse
-  (tree selection follows); relative image sources are rewritten to `/raw/…`.
-  External links open in a new tab.
-- Optional (v1.1): Mermaid diagram blocks and KaTeX math, each ~5 lines of
-  glue with their standard npm builds. Omitted from v1 to keep the page lean.
-
-### Code rendering (requirement 3)
-
-- Shiki `codeToHtml` with
-  `themes: { light: "catppuccin-latte", dark: "catppuccin-mocha" }` —
-  dual-theme CSS-variable output, so theme switching never re-highlights.
-- Language chosen by extension (Shiki's bundled grammar set covers everything
-  in a typical project; unknown extensions fall back to plain text). To keep
-  the client bundle sane, a curated grammar subset is bundled eagerly and the
-  long tail lazy-loads from the package's own assets.
-- Line numbers via CSS counters in the gutter. Large-file guard: above ~1 MB
-  or ~10k lines, skip highlighting and show plain text with a notice.
-- Binary files: images render via `/raw/`; other binaries show a metadata
-  card (name, size, status) instead of content.
-
-### Git change indication (requirements 4 & 5)
-
-Tree level: status letters + colors as in §3; "changed only" filter collapses
-the tree to changed/untracked files (directories auto-expanded).
-
-In-file, the *subtle* indicator is the familiar editor gutter mark, driven by
-the server's `hunks`:
-
-- **Code files:** a 3px vertical bar in the gutter beside each hunk's
-  `newStart..newStart+newLines` — Catppuccin green for added, yellow for
-  modified — plus a small red triangle marker where lines were deleted.
-  Exactly the VS Code / JetBrains gutter convention: legible, ignorable.
-- **Rendered markdown:** any block whose `data-lines` range intersects a
-  hunk's new-file range gets a 3px accent left-border.
-
-**Click → inline hunk expansion.** Clicking a gutter bar (or a marked
-markdown block) expands **that hunk only**, in place — the page never
-navigates away:
-
-- An expansion panel is inserted into the document flow directly below the
-  last line of the hunk (below the marked block, for markdown). Content
-  stays put above; content below shifts down, exactly like VS Code's
-  dirty-diff peek or GitHub's expanded comment threads.
-- The panel body is diff2html rendering *just that hunk*: the client wraps
-  the hunk's `patch` in a minimal synthesized diff header and calls
-  `Diff2HtmlUI` on it. Unified view by default; a per-panel toggle offers
-  side-by-side. Deleted lines therefore appear only inside the panel —
-  the main view always shows the current file.
-- Toggle behavior: click again (or the panel's ✕, or `Esc`) collapses it.
-  Multiple hunks can be open at once. A subtle "N changes" chip in the
-  header offers expand-all/collapse-all for review-the-whole-file flow.
-- On SSE-driven re-render, expanded panels re-attach to the hunk nearest
-  their old `newStart` if it still exists; vanished hunks close silently.
-
-There is deliberately **no whole-page diff mode** — the hunk panel is the
-only diff representation, so the reading context is never lost.
-
-### Theming
-
-`@catppuccin/palette` CSS variables define both palettes; a `data-theme`
-attribute on `<html>` selects Latte or Mocha (default follows
-`prefers-color-scheme`, toggle persisted in `localStorage`). Shiki dual themes
-and diff2html variable overrides key off the same attribute, so one attribute
-flip restyles everything with zero re-rendering.
-
-## 6. Repository layout & size budget
-
-Standalone repo `talkasab/peruse`:
-
-```
-peruse/
-  package.json          # name @talkasab/peruse; bin {"peruse": "bin/peruse.js"}
-  bin/peruse.js         # CLI arg parsing, open browser        (~40 lines)
-  server/index.js       # Bun.serve routes, git, chokidar→SSE  (~280 lines)
-  web/
-    index.html          # layout + Alpine templates            (~120 lines)
-    app.js              # tree/view/hunk/SSE logic             (~350 lines)
-    style.css           # Catppuccin variables + layout        (~150 lines)
-  dist/                 # prebuilt client (bun build; published to npm)
-```
-
-Plain modern ESM JavaScript, no TypeScript compile step (JSDoc types where
-they pay for themselves). `bun build` bundles the client libraries into
-`dist/` at publish time; a release script runs `bun build --compile` per
-target platform to attach standalone binaries to GitHub releases.
-
-## 7. Alternatives considered and rejected
-
-1. **Just run `code serve-web`** — genuinely zero code and covers all six
-   requirements, but it's an IDE: heavy process, editing-focused chrome, and
-   the reading experience the requirements describe isn't what you get.
-2. **Extend markserv or difit** — each would need the *other half* of the
-   feature set bolted on (git for markserv, browsing/markdown for difit),
-   inside someone else's architecture. More code than the glue server, less
-   control.
-3. **Python (Starlette + uvicorn + watchfiles), PEP 723 single file** — the
-   first draft of this design. Rejected for a standalone tool: all client
-   libraries are npm-native (Python could only reach them via CDN at runtime),
-   `npx`/`bunx` is the natural distribution channel for this category, and one
-   language beats two. watchfiles/Starlette were fine; the ecosystem seam
-   was the problem.
-4. **Node instead of Bun** — the second draft (Node ≥ 20 + Hono + chokidar +
-   esbuild). Node's ubiquity is real, but it costs two extra dependencies
-   (Hono, esbuild) that Bun provides built-in, and it has no answer to
-   `bun build --compile` standalone binaries — which cover the "I don't have
-   Bun" case better than Node ubiquity covers the "I don't have Node" case.
-   The code stays plain ESM, so a Node port remains cheap if ever needed.
-5. **Server-side rendering (markdown/highlighting on the server)** — fewer
-   moving parts in the browser and Shiki runs fine in Bun, but the dual-theme
-   CSS trick, scroll-preserving in-place re-renders, and markdown line-map
-   plumbing are all simpler with client-side rendering. The server stays a
-   dumb file/git/events API.
-
-## 8. Open questions
-
-1. **Gitignored files:** hidden by default with a toggle, or always shown but
-   dimmed? (Design assumes shown-but-dimmed, toggle to hide.)
-2. **Diff baseline:** worktree vs `HEAD` (staged + unstaged together — the
-   design default) or a staged/unstaged distinction like `git diff` vs
-   `git diff --staged`? A dropdown is cheap but is it wanted?
-3. **Mermaid/KaTeX in v1?** Cheap to add; excluded only for leanness.
-4. **Non-git directories:** everything except requirements 4–5 still works;
-   the design degrades gracefully (no status column, no gutter marks).
-   Confirm that's the desired behavior rather than an error.
-5. ~~**Name**~~ Resolved: `peruse`, repo `talkasab/peruse`, published as
-   `@talkasab/peruse` (bare npm name is squatted); installed bin is `peruse`.
-
-## Sources
-
-- [markserv](https://github.com/markserv/markserv), [mdserver](https://github.com/deepdadou/mdserver), [gh-markdown-preview](https://github.com/yusukebe/gh-markdown-preview), [markdown-proxy](https://github.com/patakuti/markdown-proxy) — markdown + live-reload servers survey
-- [difit](https://github.com/yoshiko-pg/difit) ([npm](https://www.npmjs.com/package/difit)), [diffhub](https://github.com/mblode/diffhub) — local GitHub-style diff viewers
-- [Ferrite](https://github.com/OlaProeis/Ferrite) — native-app near-miss
-- [Shiki dual themes](https://shiki.style/guide/dual-themes), [Shiki bundled themes](https://shiki.style/themes) — Catppuccin Latte/Mocha bundled, CSS-variable dual-theme output
-- [diff2html](https://github.com/rtfpessoa/diff2html) ([site](https://diff2html.xyz/)) — diff → HTML rendering
-- [chokidar](https://github.com/paulmillr/chokidar) — file watching
-- [Bun](https://bun.sh) — runtime; `Bun.serve`, `bun build`, `bun build --compile`
-- [Bun watcher reliability discussion](https://github.com/oven-sh/bun/discussions/1571) — why chokidar stays
-- [Catppuccin palette](https://catppuccin.com/palette/), [catppuccin/palette](https://github.com/catppuccin/palette) — official CSS variables