CLAUDE.md update, closes #108

CLAUDE.md

@@ -14,15 +14,15 @@ ccstatusline is a customizable status line formatter for Claude Code CLI that di
 # Install dependencies
 bun install
 
-# Run with patch (TUI mode)
+# Run in interactive TUI mode
 bun run start
 
-# Run directly (TUI mode)
-bun run statusline
-
 # Test with piped input (use [1m] suffix for 1M context models)
 echo '{"model":{"id":"claude-sonnet-4-5-20250929[1m]"},"transcript_path":"test.jsonl"}' | bun run src/ccstatusline.ts
 
+# Or use example payload
+bun run example
+
 # Build for npm distribution
 bun run build   # Creates dist/ccstatusline.js with Node.js 14+ compatibility
 
@@ -75,13 +75,34 @@ The project has dual runtime compatibility - works with both Bun and Node.js:
   - Legacy models: 200k tokens (160k usable at 80%)
 
 ### Widgets (src/widgets/)
-Custom widgets implementing the StatusItemWidget interface:
+Custom widgets implementing the Widget interface defined in src/types/Widget.ts:
+
+**Widget Interface:**
+All widgets must implement:
+- `getDefaultColor()`: Default color for the widget
+- `getDescription()`: Description shown in TUI
+- `getDisplayName()`: Display name shown in TUI
+- `getEditorDisplay()`: How the widget appears in the editor
+- `render()`: Core rendering logic that produces the widget output
+- `supportsRawValue()`: Whether widget supports raw value mode
+- `supportsColors()`: Whether widget supports color customization
+- Optional: `renderEditor()`, `getCustomKeybinds()`, `handleEditorAction()`
+
+**Widget Registry Pattern:**
+- Located in src/utils/widgets.ts
+- Uses a Map-based registry (`widgetRegistry`) that maps widget type strings to widget instances
+- `getWidget(type)`: Retrieves widget instance by type
+- `getAllWidgetTypes()`: Returns all available widget types
+- `isKnownWidgetType()`: Validates if a type is registered
+
+**Available Widgets:**
 - Model, Version, OutputStyle - Claude Code metadata display
-- GitBranch, GitChanges - Git repository status
+- GitBranch, GitChanges, GitWorktree - Git repository status
 - TokensInput, TokensOutput, TokensCached, TokensTotal - Token usage metrics
 - ContextLength, ContextPercentage, ContextPercentageUsable - Context window metrics (uses dynamic model-based context windows: 1M for Sonnet 4.5 with [1m] suffix, 200k for all other models)
-- BlockTimer, SessionClock - Time tracking
+- BlockTimer, SessionClock, SessionCost - Time and cost tracking
 - CurrentWorkingDir, TerminalWidth - Environment info
+- CustomText, CustomCommand - User-defined widgets
 
 ## Key Implementation Details
 
@@ -105,10 +126,23 @@ Default to using Bun instead of Node.js:
 
 ## Important Notes
 
-- **patch-package**: The project uses patch-package to fix ink-gradient compatibility. Always run `bun run patch` before starting development
+- **ink@6.2.0 patch**: The project uses a patch for ink@6.2.0 to fix backspace key handling on macOS
+  - Issue: ink treats `\x7f` (backspace on macOS) as delete key instead of backspace
+  - Fix: Patches `build/parse-keypress.js` to correctly map `\x7f` to backspace
+  - Applied automatically during `bun install` via `patchedDependencies` in package.json
+  - Patch file: `patches/ink@6.2.0.patch`
+- **Build process**: Two-step build using `bun run build`
+  1. `bun build`: Bundles src/ccstatusline.ts into dist/ccstatusline.js targeting Node.js 14+
+  2. `postbuild`: Runs scripts/replace-version.ts to replace `__PACKAGE_VERSION__` placeholder with actual version from package.json
 - **ESLint configuration**: Uses flat config format (eslint.config.js) with TypeScript and React plugins
-- **Build target**: When building for distribution, target Node.js 14+ for maximum compatibility
 - **Dependencies**: All runtime dependencies are bundled using `--packages=external` for npm package
 - **Type checking and linting**: Only run via `bun run lint` command, never using `npx eslint` or `eslint` directly. Never run `tsx`, `bun tsc` or any other variation
 - **Lint rules**: Never disable a lint rule via a comment, no matter how benign the lint warning or error may seem
-- **Testing**: Uses Bun's built-in test framework. Run tests with `bun test` (36 tests covering model context, widgets, and rendering). Manual testing also available via piped input and TUI interaction
+- **Testing**: Uses Vitest (via Bun) with 6 test files and ~40 test cases covering:
+  - Model context detection and token calculation (src/utils/__tests__/model-context.test.ts)
+  - Context percentage calculations (src/utils/__tests__/context-percentage.test.ts)
+  - JSONL transcript parsing (src/utils/__tests__/jsonl.test.ts)
+  - Widget rendering (src/widgets/__tests__/*.test.ts)
+  - Run tests with `bun test` or `bun test --watch` for watch mode
+  - Test configuration: vitest.config.ts
+  - Manual testing also available via piped input and TUI interaction