@peaske7/readit 0.2.1 → 0.3.0-rc.1

package/.agents/skills/vercel-react-best-practices/rules/server-cache-react.md

@@ -1,76 +0,0 @@
----
-title: Per-Request Deduplication with React.cache()
-impact: MEDIUM
-impactDescription: deduplicates within request
-tags: server, cache, react-cache, deduplication
----
-
-## Per-Request Deduplication with React.cache()
-
-Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
-
-**Usage:**
-
-```typescript
-import { cache } from 'react'
-
-export const getCurrentUser = cache(async () => {
-  const session = await auth()
-  if (!session?.user?.id) return null
-  return await db.user.findUnique({
-    where: { id: session.user.id }
-  })
-})
-```
-
-Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
-
-**Avoid inline objects as arguments:**
-
-`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
-
-**Incorrect (always cache miss):**
-
-```typescript
-const getUser = cache(async (params: { uid: number }) => {
-  return await db.user.findUnique({ where: { id: params.uid } })
-})
-
-// Each call creates new object, never hits cache
-getUser({ uid: 1 })
-getUser({ uid: 1 })  // Cache miss, runs query again
-```
-
-**Correct (cache hit):**
-
-```typescript
-const getUser = cache(async (uid: number) => {
-  return await db.user.findUnique({ where: { id: uid } })
-})
-
-// Primitive args use value equality
-getUser(1)
-getUser(1)  // Cache hit, returns cached result
-```
-
-If you must pass objects, pass the same reference:
-
-```typescript
-const params = { uid: 1 }
-getUser(params)  // Query runs
-getUser(params)  // Cache hit (same reference)
-```
-
-**Next.js-Specific Note:**
-
-In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
-
-- Database queries (Prisma, Drizzle, etc.)
-- Heavy computations
-- Authentication checks
-- File system operations
-- Any non-fetch async work
-
-Use `React.cache()` to deduplicate these operations across your component tree.
-
-Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/.agents/skills/vercel-react-best-practices/rules/server-dedup-props.md

@@ -1,65 +0,0 @@
----
-title: Avoid Duplicate Serialization in RSC Props
-impact: LOW
-impactDescription: reduces network payload by avoiding duplicate serialization
-tags: server, rsc, serialization, props, client-components
----
-
-## Avoid Duplicate Serialization in RSC Props
-
-**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
-
-RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
-
-**Incorrect (duplicates array):**
-
-```tsx
-// RSC: sends 6 strings (2 arrays × 3 items)
-<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
-```
-
-**Correct (sends 3 strings):**
-
-```tsx
-// RSC: send once
-<ClientList usernames={usernames} />
-
-// Client: transform there
-'use client'
-const sorted = useMemo(() => [...usernames].sort(), [usernames])
-```
-
-**Nested deduplication behavior:**
-
-Deduplication works recursively. Impact varies by data type:
-
-- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
-- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
-
-```tsx
-// string[] - duplicates everything
-usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
-
-// object[] - duplicates array structure only
-users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
-```
-
-**Operations breaking deduplication (create new references):**
-
-- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
-- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
-
-**More examples:**
-
-```tsx
-// ❌ Bad
-<C users={users} active={users.filter(u => u.active)} />
-<C product={product} productName={product.name} />
-
-// ✅ Good
-<C users={users} />
-<C product={product} />
-// Do filtering/destructuring in client
-```
-
-**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/.agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md

@@ -1,142 +0,0 @@
----
-title: Hoist Static I/O to Module Level
-impact: HIGH
-impactDescription: avoids repeated file/network I/O per request
-tags: server, io, performance, next.js, route-handlers, og-image
----
-
-## Hoist Static I/O to Module Level
-
-**Impact: HIGH (avoids repeated file/network I/O per request)**
-
-When loading static assets (fonts, logos, images, config files) in route handlers or server functions, hoist the I/O operation to module level. Module-level code runs once when the module is first imported, not on every request. This eliminates redundant file system reads or network fetches that would otherwise run on every invocation.
-
-**Incorrect: reads font file on every request**
-
-```typescript
-// app/api/og/route.tsx
-import { ImageResponse } from 'next/og'
-
-export async function GET(request: Request) {
-  // Runs on EVERY request - expensive!
-  const fontData = await fetch(
-    new URL('./fonts/Inter.ttf', import.meta.url)
-  ).then(res => res.arrayBuffer())
-  
-  const logoData = await fetch(
-    new URL('./images/logo.png', import.meta.url)
-  ).then(res => res.arrayBuffer())
-
-  return new ImageResponse(
-    <div style={{ fontFamily: 'Inter' }}>
-      <img src={logoData} />
-      Hello World
-    </div>,
-    { fonts: [{ name: 'Inter', data: fontData }] }
-  )
-}
-```
-
-**Correct: loads once at module initialization**
-
-```typescript
-// app/api/og/route.tsx
-import { ImageResponse } from 'next/og'
-
-// Module-level: runs ONCE when module is first imported
-const fontData = fetch(
-  new URL('./fonts/Inter.ttf', import.meta.url)
-).then(res => res.arrayBuffer())
-
-const logoData = fetch(
-  new URL('./images/logo.png', import.meta.url)
-).then(res => res.arrayBuffer())
-
-export async function GET(request: Request) {
-  // Await the already-started promises
-  const [font, logo] = await Promise.all([fontData, logoData])
-
-  return new ImageResponse(
-    <div style={{ fontFamily: 'Inter' }}>
-      <img src={logo} />
-      Hello World
-    </div>,
-    { fonts: [{ name: 'Inter', data: font }] }
-  )
-}
-```
-
-**Alternative: synchronous file reads with Node.js fs**
-
-```typescript
-// app/api/og/route.tsx
-import { ImageResponse } from 'next/og'
-import { readFileSync } from 'fs'
-import { join } from 'path'
-
-// Synchronous read at module level - blocks only during module init
-const fontData = readFileSync(
-  join(process.cwd(), 'public/fonts/Inter.ttf')
-)
-
-const logoData = readFileSync(
-  join(process.cwd(), 'public/images/logo.png')
-)
-
-export async function GET(request: Request) {
-  return new ImageResponse(
-    <div style={{ fontFamily: 'Inter' }}>
-      <img src={logoData} />
-      Hello World
-    </div>,
-    { fonts: [{ name: 'Inter', data: fontData }] }
-  )
-}
-```
-
-**General Node.js example: loading config or templates**
-
-```typescript
-// Incorrect: reads config on every call
-export async function processRequest(data: Data) {
-  const config = JSON.parse(
-    await fs.readFile('./config.json', 'utf-8')
-  )
-  const template = await fs.readFile('./template.html', 'utf-8')
-  
-  return render(template, data, config)
-}
-
-// Correct: loads once at module level
-const configPromise = fs.readFile('./config.json', 'utf-8')
-  .then(JSON.parse)
-const templatePromise = fs.readFile('./template.html', 'utf-8')
-
-export async function processRequest(data: Data) {
-  const [config, template] = await Promise.all([
-    configPromise,
-    templatePromise
-  ])
-  
-  return render(template, data, config)
-}
-```
-
-**When to use this pattern:**
-
-- Loading fonts for OG image generation
-- Loading static logos, icons, or watermarks
-- Reading configuration files that don't change at runtime
-- Loading email templates or other static templates
-- Any static asset that's the same across all requests
-
-**When NOT to use this pattern:**
-
-- Assets that vary per request or user
-- Files that may change during runtime (use caching with TTL instead)
-- Large files that would consume too much memory if kept loaded
-- Sensitive data that shouldn't persist in memory
-
-**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** Module-level caching is especially effective because multiple concurrent requests share the same function instance. The static assets stay loaded in memory across requests without cold start penalties.
-
-**In traditional serverless:** Each cold start re-executes module-level code, but subsequent warm invocations reuse the loaded assets until the instance is recycled.

package/.agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -1,83 +0,0 @@
----
-title: Parallel Data Fetching with Component Composition
-impact: CRITICAL
-impactDescription: eliminates server-side waterfalls
-tags: server, rsc, parallel-fetching, composition
----
-
-## Parallel Data Fetching with Component Composition
-
-React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
-
-**Incorrect (Sidebar waits for Page's fetch to complete):**
-
-```tsx
-export default async function Page() {
-  const header = await fetchHeader()
-  return (
-    <div>
-      <div>{header}</div>
-      <Sidebar />
-    </div>
-  )
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-```
-
-**Correct (both fetch simultaneously):**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader()
-  return <div>{data}</div>
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-
-export default function Page() {
-  return (
-    <div>
-      <Header />
-      <Sidebar />
-    </div>
-  )
-}
-```
-
-**Alternative with children prop:**
-
-```tsx
-async function Header() {
-  const data = await fetchHeader()
-  return <div>{data}</div>
-}
-
-async function Sidebar() {
-  const items = await fetchSidebarItems()
-  return <nav>{items.map(renderItem)}</nav>
-}
-
-function Layout({ children }: { children: ReactNode }) {
-  return (
-    <div>
-      <Header />
-      {children}
-    </div>
-  )
-}
-
-export default function Page() {
-  return (
-    <Layout>
-      <Sidebar />
-    </Layout>
-  )
-}
-```

package/.agents/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -1,38 +0,0 @@
----
-title: Minimize Serialization at RSC Boundaries
-impact: HIGH
-impactDescription: reduces data transfer size
-tags: server, rsc, serialization, props
----
-
-## Minimize Serialization at RSC Boundaries
-
-The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
-
-**Incorrect (serializes all 50 fields):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser()  // 50 fields
-  return <Profile user={user} />
-}
-
-'use client'
-function Profile({ user }: { user: User }) {
-  return <div>{user.name}</div>  // uses 1 field
-}
-```
-
-**Correct (serializes only 1 field):**
-
-```tsx
-async function Page() {
-  const user = await fetchUser()
-  return <Profile name={user.name} />
-}
-
-'use client'
-function Profile({ name }: { name: string }) {
-  return <div>{name}</div>
-}
-```

package/.claude/CLAUDE.md

@@ -1,184 +0,0 @@
-# CLAUDE.md
-
-## Project Overview
-
-**readit** is a CLI tool for reviewing Markdown and HTML documents with inline comments. It serves documents in a local web interface and allows users to add comments to selected text. Comments appear as margin notes next to highlighted text (similar to Google Docs). Comments can be exported for use with AI coding assistants or applied back to the source document.
-
-Inspired by [difit](https://github.com/yoshiko-pg/difit) - a local code review tool for the AI era.
-
-## Quick Reference
-
-```bash
-# Development
-bun install           # Install dependencies
-bun dev               # Start dev server (CLI with --watch)
-bun run dev:client    # Start Vite dev server only
-bun run build         # Build for production (Vite + CLI)
-bun run test          # Run unit tests (Vitest)
-bun run test:e2e      # Run e2e tests (Playwright)
-bun run test:perf     # Run performance tests
-bun run bench         # Run benchmarks
-bun run typecheck     # Run TypeScript checks
-bun run check         # Run Biome (lint + format check)
-bun run check:fix     # Fix lint + format issues
-bun run format        # Format with Biome
-
-# Go server (production binary)
-make dev              # Go server + Vite HMR
-make build            # Build single binary (dist/readit)
-make test             # Run Go tests
-make clean            # Clean build artifacts
-
-# Usage
-bunx readit <file.md>               # Review Markdown file
-bunx readit <file.html>             # Review HTML file
-bunx readit <file.md> --port 3000   # Custom port
-bunx readit <file.md> --host 0.0.0.0  # Custom host address
-bunx readit <file.md> --no-open     # Don't auto-open browser
-bunx readit <file.md> --clean       # Clear existing comments
-
-bunx readit list                    # List all files with comments
-bunx readit show <file.md>          # Show comments for a file
-bunx readit open <files...>         # Add files to running server
-bunx readit completion zsh          # Output shell integration script
-```
-
-## Architecture
-
-```
-readit/
-├── src/
-│   ├── cli.ts                 # CLI entry point (Commander.js)
-│   ├── server.ts              # Bun.serve() server + API routes
-│   ├── App.svelte             # Main Svelte component
-│   ├── main.ts                # Svelte entry point
-│   ├── schema.ts              # TypeScript types
-│   ├── template.ts            # HTML template rendering
-│   ├── index.css              # Tailwind styles + CSS custom properties
-│   ├── components/
-│   │   ├── Header.svelte
-│   │   ├── DocumentViewer.svelte  # Renders document HTML
-│   │   ├── CommentInput.svelte    # Comment input area
-│   │   ├── CommentNav.svelte      # Navigate between comments
-│   │   ├── CommentListItem.svelte # Comment item in manager
-│   │   ├── CommentManager.svelte  # Comment management panel
-│   │   ├── CommentBadge.svelte    # Comment count badge
-│   │   ├── MarginNote.svelte      # Individual margin note
-│   │   ├── MarginNotesContainer.svelte
-│   │   ├── ActionsMenu.svelte     # Actions dropdown menu
-│   │   ├── InlineEditor.svelte    # Inline text editing
-│   │   ├── RawModal.svelte        # View raw .comments.md file
-│   │   ├── ReanchorConfirm.svelte # Re-anchor confirmation dialog
-│   │   ├── SettingsModal.svelte   # Settings modal
-│   │   ├── ShortcutCapture.svelte # Keyboard shortcut capture
-│   │   ├── ShortcutList.svelte    # Keyboard shortcuts list
-│   │   ├── TabBar.svelte          # Multi-file tab bar
-│   │   ├── TableOfContents.svelte # Document headings navigation
-│   │   └── ui/                    # Primitive UI components
-│   │       ├── ActionLink.svelte
-│   │       ├── Button.svelte
-│   │       ├── Dialog.svelte
-│   │       ├── DropdownMenu.svelte
-│   │       ├── DropdownMenuItem.svelte
-│   │       ├── DropdownMenuSeparator.svelte
-│   │       └── Text.svelte
-│   ├── stores/                # Svelte 5 reactive stores
-│   │   ├── app.svelte.ts      # Application state
-│   │   ├── settings.svelte.ts # User settings
-│   │   ├── shortcuts.svelte.ts # Keyboard shortcuts
-│   │   ├── locale.svelte.ts   # i18n state
-│   │   └── ui.svelte.ts       # UI state
-│   └── lib/
-│       ├── anchor.ts          # Anchor-based comment resolution
-│       ├── comment-storage.ts # File-based comment storage
-│       ├── export.ts          # Export utilities (JSON, prompt format)
-│       ├── headings.ts        # Heading extraction
-│       ├── html-text.ts       # HTML text extraction
-│       ├── margin-layout.ts   # Margin note position resolution
-│       ├── markdown-renderer.ts # Server-side markdown rendering
-│       ├── mermaid-renderer.ts  # Mermaid diagram rendering
-│       ├── mermaid-config.ts  # Mermaid configuration
-│       ├── mermaid-worker.ts  # Mermaid worker thread
-│       ├── positions.ts       # Position calculations
-│       ├── shortcut-registry.ts # Keyboard shortcut registry
-│       ├── utils.ts           # Common utilities (cn, etc.)
-│       ├── highlight/         # Text highlighting system
-│       │   ├── highlighter.ts # Highlight manager
-│       │   ├── highlight-registry.ts # Highlight registry
-│       │   ├── resolver.ts    # Highlight resolution
-│       │   ├── dom.ts         # DOM manipulation
-│       │   └── types.ts       # Type definitions
-│       └── i18n/              # Internationalization
-│           ├── index.ts
-│           ├── translations.ts
-│           ├── types.ts
-│           ├── en.ts          # English translations
-│           └── ja.ts          # Japanese translations
-├── go/                        # Go server (production binary)
-│   ├── cmd/readit/main.go     # Go CLI entry point
-│   └── internal/server/       # HTTP server, markdown, comments, SSE
-├── shell/                     # Shell integration
-│   ├── readit.zsh             # Zsh plugin (@ file picker + completions)
-│   └── _readit                # Zsh compdef completion function
-├── nvim-readit/               # Neovim plugin
-│   ├── lua/readit/init.lua    # Core plugin (server mgmt, commands, keymaps)
-│   ├── lua/readit/health.lua  # :checkhealth support
-│   └── plugin/readit.lua      # Auto-loader
-├── vscode-readit/             # VS Code extension
-│   └── src/                   # Extension source (TypeScript)
-├── e2e/                       # Playwright e2e tests
-├── docs/                      # Design docs and specs
-├── dist/                      # Built output
-├── .claude/                   # AI agent docs
-│   ├── user-stories.md
-│   ├── roadmap.md
-│   └── settings.json
-├── Makefile                   # Go build targets (make dev, make build)
-├── CLAUDE.md                  # This file
-└── AGENTS.md                  # AI agent instructions
-```
-
-## Key Design Decisions
-
-1. **markdown-it for Markdown**: Server-side rendering with shiki for syntax highlighting
-2. **Mermaid for diagrams**: Server-side Mermaid diagram rendering
-3. **Margin notes UX**: Comments appear as margin notes next to highlighted text (Google Docs style)
-4. **File-based comments**: Human-readable `.comments.md` files stored in `~/.readit/comments/`
-5. **difit-style UX**: CLI → local server → browser, familiar pattern
-6. **Svelte 5 stores for state**: Reactive stores (`.svelte.ts`) for state management
-7. **i18n support**: English and Japanese translations
-8. **Live reload**: fs.watch() on documents + SSE push to browser; handles rename-style saves (Vim/Neovim/Emacs)
-9. **Editor integrations**: Neovim plugin (Lua), VS Code extension, shell completions with `@` fzf file picker
-
-## Tech Stack
-
-- **Runtime**: Bun
-- **CLI**: Commander.js for argument parsing
-- **Server**: Bun.serve() for API, SSE, and static files
-- **Markdown Rendering**: markdown-it (server-side) + shiki (syntax highlighting)
-- **Frontend**: Svelte 5 + TypeScript + Vite
-- **Styling**: Tailwind CSS v4
-- **Icons**: lucide-svelte
-- **Testing**: Vitest (unit) + Playwright (e2e)
-- **Production Binary**: Go (embeds frontend via go:embed)
-- **Quality**: Biome (lint + format), lefthook
-- **Shell Integration**: Zsh/Bash/Fish completions, fzf-powered `@` file picker
-- **Editor Plugins**: Neovim (Lua), VS Code (TypeScript)
-
-## Current Limitations
-
-- Comments use anchor-based text matching, may break if document changes significantly
-- No comment status tracking yet (resolved/unresolved planned for v0.3.0)
-
-## User Stories
-
-See `.claude/user-stories.md` for detailed user stories and acceptance criteria.
-
-## Code Style
-
-- TypeScript strict mode
-- Svelte 5 components with reactive stores
-- Tailwind for styling
-- ESM modules throughout
-- Co-located test files (`*.test.ts`, `*.bench.ts`)
-- E2E tests in `e2e/`