@peaske7/readit 0.1.4 → 0.1.6

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

@@ -0,0 +1,76 @@
+---
+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

@@ -0,0 +1,65 @@
+---
+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

@@ -0,0 +1,142 @@
+---
+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

@@ -0,0 +1,83 @@
+---
+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

@@ -0,0 +1,38 @@
+---
+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

@@ -0,0 +1,142 @@
+# 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 (Vite + CLI)
+bun run build         # Build for production
+bun run test          # Run tests
+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
+
+# 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
+```
+
+## Architecture
+
+```
+readit/
+├── src/
+│   ├── cli/
+│   │   └── index.ts           # CLI entry point (Commander.js)
+│   ├── server/
+│   │   └── index.ts           # Bun.serve() server + API routes
+│   ├── components/
+│   │   ├── Header.tsx
+│   │   ├── DocumentViewer.tsx # Renders MD (react-markdown) or HTML (IframeContainer)
+│   │   ├── IframeContainer.tsx # Isolated HTML rendering with comment support
+│   │   ├── CodeBlock.tsx      # Syntax-highlighted code blocks
+│   │   ├── CommentInputArea.tsx
+│   │   ├── CommentListItem.tsx # Comment item in manager dropdown
+│   │   ├── CommentManagerDropdown.tsx # Dropdown menu for managing comments
+│   │   ├── CommentMinimap.tsx # Visual minimap of comment positions
+│   │   ├── CommentNavigator.tsx # Navigate between comments
+│   │   ├── FloatingTOC.tsx    # Floating TOC button (fullscreen mode)
+│   │   ├── MarginNote.tsx     # Individual margin note
+│   │   ├── MarginNotesContainer.tsx
+│   │   ├── MermaidDiagram.tsx # Mermaid diagram rendering
+│   │   ├── RawCommentsModal.tsx # View raw .comments.md file
+│   │   ├── SettingsModal.tsx  # Settings modal (font preferences)
+│   │   ├── TableOfContents.tsx # Document headings navigation
+│   │   └── index.ts
+│   ├── hooks/
+│   │   ├── useComments.ts     # Comment state management
+│   │   ├── useCommentNavigation.ts # Navigate between comments
+│   │   ├── useDocument.ts     # Document fetching and state
+│   │   ├── useFontPreference.ts # Font preference with server persistence
+│   │   ├── useHeadings.ts     # Extract headings from document
+│   │   ├── useLayoutMode.ts   # Layout mode toggle (centered/fullscreen)
+│   │   ├── useReanchorMode.ts # Re-anchor mode for unresolved comments
+│   │   ├── useScrollMetrics.ts # Scroll position tracking
+│   │   ├── useScrollSpy.ts    # Track scroll position for TOC
+│   │   ├── useTextSelection.ts # Text selection handling
+│   │   └── index.ts
+│   ├── lib/
+│   │   ├── anchor.ts          # Anchor-based comment resolution
+│   │   ├── comment-storage.ts # File-based comment storage
+│   │   ├── context.ts         # LLM context extraction
+│   │   ├── export.ts          # Export utilities (JSON, prompt format)
+│   │   ├── layout-constants.ts # Layout dimensions and breakpoints
+│   │   ├── margin-layout.ts   # Margin note position resolution
+│   │   ├── scroll.ts          # Scroll calculation utilities
+│   │   ├── utils.ts           # Common utilities (cn, etc.)
+│   │   └── highlight/         # Text highlighting system
+│   │       ├── index.ts
+│   │       ├── highlighter.ts # Unified highlighter factory
+│   │       ├── core.ts        # Core highlight logic
+│   │       ├── dom.ts         # DOM manipulation
+│   │       ├── colors.ts      # Comment color palette
+│   │       ├── types.ts       # Type definitions
+│   │       └── script-builder.ts
+│   ├── types/
+│   │   └── index.ts           # Shared types
+│   ├── App.tsx                # Main React component
+│   ├── main.tsx               # React entry point
+│   └── index.css              # Tailwind styles
+├── dist/                      # Built output
+├── .claude/                   # AI agent docs
+│   ├── user-stories.md
+│   ├── roadmap.md
+│   └── settings.json
+├── CLAUDE.md                  # This file
+├── AGENTS.md                  # AI agent instructions
+└── CHANGELOG.md               # Version changelog
+```
+
+## Key Design Decisions
+
+1. **react-markdown for Markdown**: Client-side rendering, no external dependencies
+2. **unified/rehype for HTML**: Safe HTML rendering with XSS protection via html-processor
+3. **IframeContainer for HTML isolation**: Renders HTML in sandboxed iframe to prevent style/script leakage
+4. **Margin notes UX**: Comments appear as margin notes next to highlighted text (Google Docs style)
+5. **File-based comments**: Human-readable `.comments.md` files stored in `~/.readit/comments/`
+6. **difit-style UX**: CLI → local server → browser, familiar pattern
+7. **Hooks for state**: Custom hooks for comment management
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **CLI**: Commander.js for argument parsing
+- **Server**: Bun.serve() for API and static files
+- **Markdown Rendering**: react-markdown
+- **HTML Rendering**: unified + rehype-parse + rehype-react (with XSS sanitization)
+- **Frontend**: React 19 + TypeScript + Vite
+- **Styling**: Tailwind CSS v4
+- **Testing**: Vitest
+- **Quality**: Biome (lint + format), lefthook
+
+## Current Limitations
+
+- Comments use text offset, 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
+- Functional React components with hooks
+- Tailwind for styling (no CSS-in-JS)
+- ESM modules throughout
+- Co-located test files (`*.test.ts`)

package/.claude/commands/review.md

@@ -0,0 +1,120 @@
+# Code Review: 本質的な課題発見と解決
+
+Review code in $ARGUMENTS for **fundamental design issues**, not surface-level cleanup. Use extended thinking (ultrathink).
+
+**Philosophy**: Find root causes, but respect the codebase's simplicity-first approach. From `style-guide.md`:
+
+- "Obvious over clever" - Can you understand it in 5 seconds?
+- "Duplication over wrong abstraction" - Write it twice, abstract on the third
+- "Simple over complex" - Prefer imperative solutions over abstractions
+- "Do not model state machines or data with classes" - Use discriminated unions sparingly
+
+**CRITICAL**: Do NOT suggest new abstractions (state machines, wrapper classes, generic utilities) unless the same pattern appears 3+ times. Prefer inline, obvious code.
+
+## What to Look For
+
+Reference `.claude/rules/style-guide.md` for detailed examples.
+
+### 1. Abstractions & Decomposition
+
+- §9.2 Refactoring & Anti-Patterns - Premature abstraction, wrong boundaries
+- §3.2 Balanced Function Decomposition - When to extract vs inline
+
+### 2. Type Design
+
+- §2.1 Parse, Don't Validate - Transform at boundaries, don't re-validate
+- §2.2 Discriminated Unions Over Classes - Exhaustive checking, no inheritance
+- §6.3 No Enums - Use const object pattern
+
+### 3. Control Flow
+
+- §3.3 Early Returns and Guard Clauses - Happy path at root indentation
+- §3.3.1 Prefer Early Returns Over `let` Accumulation
+- §7.2 Sequential vs Parallel Processing - Right async pattern for the job
+- §4.1 Single Try-Catch for Related Operations
+
+### 4. Function Design
+
+- §3.5 Object Destructuring for Opaque Parameters
+- §3.1 Simple Over Complex - Prefer imperative over functional abstractions
+
+### 5. Code Hygiene (Always Check)
+
+- §3.4 Naming Conventions - No generic names, Hungarian notation, abbreviations
+- §3.2 Superfluous abstractions - Inline trivial one-liners
+- Comments - Delete restating JSDoc, commented-out code, TODOs without tickets
+- Dead code - Remove unused imports, uncalled methods, unread variables
+
+## Review Process
+
+1. **Understand the use case** - What is this code trying to accomplish?
+2. **Trace the data flow** - Follow the data from input to output
+3. **Question abstractions** - Does this class/function earn its existence? Could it be simpler?
+4. **Resist adding complexity** - The fix should simplify, not add layers
+
+## Output Format
+
+```markdown
+## 本質的な課題 (Fundamental Issues)
+
+### [Critical/High/Medium] Issue Title
+**Root Cause**: Why this problem exists at the design level
+**Symptom**: What you observe in the code
+**Location**: `path/to/file.ts:123`
+**Proposed Fix**: How to simplify (prefer removal/inlining over adding new abstractions)
+
+## Surface Issues (Lower Priority)
+- Brief list of naming, formatting, comment issues (fix these only after fundamental issues)
+```
+
+## Fix Approach
+
+**For fundamental issues:**
+
+1. Propose the simplest fix first (often: inline, remove, or merge)
+2. Ask for confirmation if the change affects multiple files or public interfaces
+3. Implement the fix
+
+**For surface issues:**
+
+1. Fix silently after addressing fundamental issues
+2. Run `pnpm turbo run fix` to format
+
+## Anti-patterns to Flag
+
+- **Adding abstraction to fix a bug** - Symptom-fixing vs root cause
+- **Creating a "utils" function** - Find the right home or inline it
+- **Wrapper functions that just pass through** - No value added, remove them
+- **Extracting trivial operations** - `name.replace(/_id_seq$/, "")` should stay inline
+- **Boolean parameters** - Should often be two separate functions
+
+## When Abstractions ARE Appropriate
+
+**State machines** - Use when:
+
+- There are distinct, named states (e.g., VOID → EVENT_CREATED → BOT_SCHEDULED)
+- Transitions between states have specific actions
+- The switch statement covers all state combinations exhaustively
+
+**Don't use** state machines for:
+
+- Simple if/else that can be early returns
+- Boolean flags that don't represent true states
+- "Just in case" future flexibility
+
+**New types/classes** - Use when:
+
+- Pattern repeats 3+ times
+- Encapsulates meaningful domain complexity
+- Makes invalid states unrepresentable
+
+## Anti-patterns to AVOID Suggesting
+
+- Generic utility wrappers
+- New abstraction layers for 1-2 use cases
+- "Future-proofing" changes
+- State machines for simple conditional logic
+
+---
+
+Now analyze: $ARGUMENTS