@oh-my-pi/pi-coding-agent 1.337.0

package/docs/theme.md

@@ -0,0 +1,637 @@
+> pi can create themes. Ask it to build one for your use case.
+
+# Pi Coding Agent Themes
+
+Themes allow you to customize the colors used throughout the coding agent TUI.
+
+## Color Tokens
+
+Every theme must define all color tokens. There are no optional colors.
+
+### Core UI (10 colors)
+
+| Token          | Purpose               | Examples                             |
+| -------------- | --------------------- | ------------------------------------ |
+| `accent`       | Primary accent color  | Logo, selected items, cursor (›)     |
+| `border`       | Normal borders        | Selector borders, horizontal lines   |
+| `borderAccent` | Highlighted borders   | Changelog borders, special panels    |
+| `borderMuted`  | Subtle borders        | Editor borders, secondary separators |
+| `success`      | Success states        | Success messages, diff additions     |
+| `error`        | Error states          | Error messages, diff deletions       |
+| `warning`      | Warning states        | Warning messages                     |
+| `muted`        | Secondary/dimmed text | Metadata, descriptions, output       |
+| `dim`          | Very dimmed text      | Less important info, placeholders    |
+| `text`         | Default text color    | Main content (usually `""`)          |
+| `thinkingText` | Thinking block text   | Assistant reasoning traces           |
+
+### Backgrounds & Content Text (11 colors)
+
+| Token                | Purpose                                                           |
+| -------------------- | ----------------------------------------------------------------- |
+| `selectedBg`         | Selected/active line background (e.g., tree selector)             |
+| `userMessageBg`      | User message background                                           |
+| `userMessageText`    | User message text color                                           |
+| `customMessageBg`    | Hook custom message background                                    |
+| `customMessageText`  | Hook custom message text color                                    |
+| `customMessageLabel` | Hook custom message label/type text                               |
+| `toolPendingBg`      | Tool execution box (pending state)                                |
+| `toolSuccessBg`      | Tool execution box (success state)                                |
+| `toolErrorBg`        | Tool execution box (error state)                                  |
+| `toolTitle`          | Tool execution title/heading (e.g., `$ command`, `read file.txt`) |
+| `toolOutput`         | Tool execution output text                                        |
+
+### Markdown (10 colors)
+
+| Token               | Purpose                       |
+| ------------------- | ----------------------------- |
+| `mdHeading`         | Heading text (`#`, `##`, etc) |
+| `mdLink`            | Link text                     |
+| `mdLinkUrl`         | Link URL (in parentheses)     |
+| `mdCode`            | Inline code (backticks)       |
+| `mdCodeBlock`       | Code block content            |
+| `mdCodeBlockBorder` | Code block fences (```)       |
+| `mdQuote`           | Blockquote text               |
+| `mdQuoteBorder`     | Blockquote border (`│`)       |
+| `mdHr`              | Horizontal rule (`---`)       |
+| `mdListBullet`      | List bullets/numbers          |
+
+### Tool Diffs (3 colors)
+
+| Token             | Purpose                     |
+| ----------------- | --------------------------- |
+| `toolDiffAdded`   | Added lines in tool diffs   |
+| `toolDiffRemoved` | Removed lines in tool diffs |
+| `toolDiffContext` | Context lines in tool diffs |
+
+Note: Diff colors are specific to tool execution boxes and must work with tool background colors.
+
+### Syntax Highlighting (9 colors)
+
+Future-proofing for syntax highlighting support:
+
+| Token               | Purpose                          |
+| ------------------- | -------------------------------- |
+| `syntaxComment`     | Comments                         |
+| `syntaxKeyword`     | Keywords (`if`, `function`, etc) |
+| `syntaxFunction`    | Function names                   |
+| `syntaxVariable`    | Variable names                   |
+| `syntaxString`      | String literals                  |
+| `syntaxNumber`      | Number literals                  |
+| `syntaxType`        | Type names                       |
+| `syntaxOperator`    | Operators (`+`, `-`, etc)        |
+| `syntaxPunctuation` | Punctuation (`;`, `,`, etc)      |
+
+### Thinking Level Borders (6 colors)
+
+Editor border colors that indicate the current thinking/reasoning level:
+
+| Token             | Purpose                                                           |
+| ----------------- | ----------------------------------------------------------------- |
+| `thinkingOff`     | Border when thinking is off (most subtle)                         |
+| `thinkingMinimal` | Border for minimal thinking                                       |
+| `thinkingLow`     | Border for low thinking                                           |
+| `thinkingMedium`  | Border for medium thinking                                        |
+| `thinkingHigh`    | Border for high thinking                                          |
+| `thinkingXhigh`   | Border for xhigh thinking (most prominent, OpenAI codex-max only) |
+
+These create a visual hierarchy: off → minimal → low → medium → high → xhigh
+
+### Bash Mode (1 color)
+
+| Token      | Purpose                                          |
+| ---------- | ------------------------------------------------ |
+| `bashMode` | Editor border color when in bash mode (! prefix) |
+
+**Total: 50 color tokens** (all required)
+
+### HTML Export Colors (optional)
+
+The `export` section is optional and controls colors used when exporting sessions to HTML via `/export`. If not specified, these colors are automatically derived from `userMessageBg` based on luminance detection.
+
+| Token    | Purpose                                                       |
+| -------- | ------------------------------------------------------------- |
+| `pageBg` | Page background color                                         |
+| `cardBg` | Card/container background (headers, stats boxes)              |
+| `infoBg` | Info sections background (system prompt, notices, compaction) |
+
+Example:
+
+```json
+{
+	"export": {
+		"pageBg": "#18181e",
+		"cardBg": "#1e1e24",
+		"infoBg": "#3c3728"
+	}
+}
+```
+
+## Theme Format
+
+Themes are defined in JSON files with the following structure:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json",
+  "name": "my-theme",
+  "vars": {
+    "blue": "#0066cc",
+    "gray": 242,
+    "brightCyan": 51
+  },
+  "colors": {
+    "accent": "blue",
+    "muted": "gray",
+    "thinkingText": "gray",
+    "text": "",
+    ...
+  }
+}
+```
+
+### Color Values
+
+Four formats are supported:
+
+1. **Hex colors**: `"#ff0000"` (6-digit hex RGB)
+2. **256-color palette**: `39` (number 0-255, xterm 256-color palette)
+3. **Color references**: `"blue"` (must be defined in `vars`)
+4. **Terminal default**: `""` (empty string, uses terminal's default color)
+
+### The `vars` Section
+
+The optional `vars` section allows you to define reusable colors:
+
+```json
+{
+	"vars": {
+		"nord0": "#2E3440",
+		"nord1": "#3B4252",
+		"nord8": "#88C0D0",
+		"brightBlue": 39
+	},
+	"colors": {
+		"accent": "nord8",
+		"muted": "nord1",
+		"mdLink": "brightBlue"
+	}
+}
+```
+
+Benefits:
+
+- Reuse colors across multiple tokens
+- Easier to maintain theme consistency
+- Can reference standard color palettes
+
+Variables can be hex colors (`"#ff0000"`), 256-color indices (`42`), or references to other variables.
+
+### Terminal Default (empty string)
+
+Use `""` (empty string) to inherit the terminal's default foreground/background color:
+
+```json
+{
+	"colors": {
+		"text": "" // Uses terminal's default text color
+	}
+}
+```
+
+This is useful for:
+
+- Main text color (adapts to user's terminal theme)
+- Creating themes that blend with terminal appearance
+
+## Built-in Themes
+
+Pi comes with two built-in themes:
+
+### `dark` (default)
+
+Optimized for dark terminal backgrounds with bright, saturated colors.
+
+### `light`
+
+Optimized for light terminal backgrounds with darker, muted colors.
+
+## Selecting a Theme
+
+Themes are configured in the settings (accessible via `/settings`):
+
+```json
+{
+	"theme": "dark"
+}
+```
+
+Or use the `/theme` command interactively.
+
+On first run, Pi detects your terminal's background and sets a sensible default (`dark` or `light`).
+
+## Custom Themes
+
+### Theme Locations
+
+Custom themes are loaded from `~/.pi/agent/themes/*.json`.
+
+### Creating a Custom Theme
+
+1. **Create theme directory:**
+
+   ```bash
+   mkdir -p ~/.pi/agent/themes
+   ```
+
+2. **Create theme file:**
+
+   ```bash
+   vim ~/.pi/agent/themes/my-theme.json
+   ```
+
+3. **Define all colors:**
+
+   ```json
+   {
+   	"$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json",
+   	"name": "my-theme",
+   	"vars": {
+   		"primary": "#00aaff",
+   		"secondary": 242,
+   		"brightGreen": 46
+   	},
+   	"colors": {
+   		"accent": "primary",
+   		"border": "primary",
+   		"borderAccent": "#00ffff",
+   		"borderMuted": "secondary",
+   		"success": "brightGreen",
+   		"error": "#ff0000",
+   		"warning": "#ffff00",
+   		"muted": "secondary",
+   		"text": "",
+
+   		"userMessageBg": "#2d2d30",
+   		"userMessageText": "",
+   		"toolPendingBg": "#1e1e2e",
+   		"toolSuccessBg": "#1e2e1e",
+   		"toolErrorBg": "#2e1e1e",
+   		"toolText": "",
+
+   		"mdHeading": "#ffaa00",
+   		"mdLink": "primary",
+   		"mdCode": "#00ffff",
+   		"mdCodeBlock": "#00ff00",
+   		"mdCodeBlockBorder": "secondary",
+   		"mdQuote": "secondary",
+   		"mdQuoteBorder": "secondary",
+   		"mdHr": "secondary",
+   		"mdListBullet": "#00ffff",
+
+   		"toolDiffAdded": "#00ff00",
+   		"toolDiffRemoved": "#ff0000",
+   		"toolDiffContext": "secondary",
+
+   		"syntaxComment": "secondary",
+   		"syntaxKeyword": "primary",
+   		"syntaxFunction": "#00aaff",
+   		"syntaxVariable": "#ffaa00",
+   		"syntaxString": "#00ff00",
+   		"syntaxNumber": "#ff00ff",
+   		"syntaxType": "#00aaff",
+   		"syntaxOperator": "primary",
+   		"syntaxPunctuation": "secondary",
+
+   		"thinkingOff": "secondary",
+   		"thinkingMinimal": "primary",
+   		"thinkingLow": "#00aaff",
+   		"thinkingMedium": "#00ffff",
+   		"thinkingHigh": "#ff00ff"
+   	}
+   }
+   ```
+
+4. **Select your theme:**
+   - Use `/settings` command and set `"theme": "my-theme"`
+   - Or use `/theme` command interactively
+
+## Tips
+
+### Light vs Dark Themes
+
+**For dark terminals:**
+
+- Use bright, saturated colors
+- Higher contrast
+- Example: `#00ffff` (bright cyan)
+
+**For light terminals:**
+
+- Use darker, muted colors
+- Lower contrast to avoid eye strain
+- Example: `#008888` (dark cyan)
+
+### Color Harmony
+
+- Start with a base palette (e.g., Nord, Gruvbox, Tokyo Night)
+- Define your palette in `defs`
+- Reference colors consistently
+
+### Testing
+
+Test your theme with:
+
+- Different message types (user, assistant, errors)
+- Tool executions (success and error states)
+- Markdown content (headings, code, lists, etc)
+- Long text that wraps
+
+## Color Format Reference
+
+### Hex Colors
+
+Standard 6-digit hex format:
+
+- `"#ff0000"` - Red
+- `"#00ff00"` - Green
+- `"#0000ff"` - Blue
+- `"#808080"` - Gray
+- `"#ffffff"` - White
+- `"#000000"` - Black
+
+RGB values: `#RRGGBB` where each component is `00-ff` (0-255)
+
+### 256-Color Palette
+
+Use numeric indices (0-255) to reference the xterm 256-color palette:
+
+**Colors 0-15:** Basic ANSI colors (terminal-dependent, may be themed)
+
+- `0` - Black
+- `1` - Red
+- `2` - Green
+- `3` - Yellow
+- `4` - Blue
+- `5` - Magenta
+- `6` - Cyan
+- `7` - White
+- `8-15` - Bright variants
+
+**Colors 16-231:** 6×6×6 RGB cube (standardized)
+
+- Formula: `16 + 36×R + 6×G + B` where R, G, B are 0-5
+- Example: `39` = bright cyan, `196` = bright red
+
+**Colors 232-255:** Grayscale ramp (standardized)
+
+- `232` - Darkest gray
+- `255` - Near white
+
+Example usage:
+
+```json
+{
+	"vars": {
+		"gray": 242,
+		"brightCyan": 51,
+		"darkBlue": 18
+	},
+	"colors": {
+		"muted": "gray",
+		"accent": "brightCyan"
+	}
+}
+```
+
+**Benefits:**
+
+- Works everywhere (`TERM=xterm-256color`)
+- No truecolor detection needed
+- Standardized RGB cube (16-231) looks the same on all terminals
+
+### Terminal Compatibility
+
+Pi uses 24-bit RGB colors (`\x1b[38;2;R;G;Bm`). Most modern terminals support this:
+
+- ✅ iTerm2, Alacritty, Kitty, WezTerm
+- ✅ Windows Terminal
+- ✅ VS Code integrated terminal
+- ✅ Modern GNOME Terminal, Konsole
+
+For older terminals with only 256-color support, Pi automatically falls back to the nearest 256-color approximation.
+
+To check if your terminal supports truecolor:
+
+```bash
+echo $COLORTERM  # Should output "truecolor" or "24bit"
+```
+
+## Example Themes
+
+See the built-in themes for complete examples:
+
+- [Dark theme](../src/themes/dark.json)
+- [Light theme](../src/themes/light.json)
+
+## Schema Validation
+
+Themes are validated on load using [TypeBox](https://github.com/sinclairzx81/typebox) + [Ajv](https://ajv.js.org/).
+
+Invalid themes will show an error with details about what's wrong:
+
+```
+Error loading theme 'my-theme':
+  - colors.accent: must be string or number
+  - colors.mdHeading: required property missing
+```
+
+For editor support, the JSON schema is available at:
+
+```
+https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json
+```
+
+Add to your theme file for auto-completion and validation:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json",
+  ...
+}
+```
+
+## Implementation
+
+### Theme Class
+
+Themes are loaded and converted to a `Theme` class that provides type-safe color methods:
+
+```typescript
+class Theme {
+	// Apply foreground color
+	fg(color: ThemeColor, text: string): string;
+
+	// Apply background color
+	bg(color: ThemeBg, text: string): string;
+
+	// Text attributes (preserve current colors)
+	bold(text: string): string;
+	italic(text: string): string;
+	underline(text: string): string;
+}
+```
+
+### Global Theme Instance
+
+The active theme is available as a global singleton in `coding-agent`:
+
+```typescript
+// theme.ts
+export let theme: Theme;
+
+export function setTheme(name: string) {
+	theme = loadTheme(name);
+}
+
+// Usage throughout coding-agent
+import { theme } from "./theme.js";
+
+theme.fg("accent", "Selected");
+theme.bg("userMessageBg", content);
+```
+
+### TUI Component Theming
+
+TUI components (like `Markdown`, `SelectList`, `Editor`) are in the `@oh-my-pi/pi-tui` package and don't have direct access to the theme. Instead, they define interfaces for the colors they need:
+
+```typescript
+// In @oh-my-pi/pi-tui
+export interface MarkdownTheme {
+	heading: (text: string) => string;
+	link: (text: string) => string;
+	linkUrl: (text: string) => string;
+	code: (text: string) => string;
+	codeBlock: (text: string) => string;
+	codeBlockBorder: (text: string) => string;
+	quote: (text: string) => string;
+	quoteBorder: (text: string) => string;
+	hr: (text: string) => string;
+	listBullet: (text: string) => string;
+	bold: (text: string) => string;
+	italic: (text: string) => string;
+	strikethrough: (text: string) => string;
+	underline: (text: string) => string;
+}
+```
+
+The `coding-agent` provides themed functions when creating components:
+
+```typescript
+// In coding-agent
+import { theme } from "./theme.js";
+import { Markdown } from "@oh-my-pi/pi-tui";
+
+// Helper to create markdown theme functions
+function getMarkdownTheme(): MarkdownTheme {
+	return {
+		heading: (text) => theme.fg("mdHeading", text),
+		link: (text) => theme.fg("mdLink", text),
+		linkUrl: (text) => theme.fg("mdLinkUrl", text),
+		code: (text) => theme.fg("mdCode", text),
+		codeBlock: (text) => theme.fg("mdCodeBlock", text),
+		codeBlockBorder: (text) => theme.fg("mdCodeBlockBorder", text),
+		quote: (text) => theme.fg("mdQuote", text),
+		quoteBorder: (text) => theme.fg("mdQuoteBorder", text),
+		hr: (text) => theme.fg("mdHr", text),
+		listBullet: (text) => theme.fg("mdListBullet", text),
+		bold: (text) => theme.bold(text),
+		italic: (text) => theme.italic(text),
+		underline: (text) => theme.underline(text),
+		strikethrough: (text) => chalk.strikethrough(text),
+	};
+}
+
+// Create markdown with theme
+const md = new Markdown(text, 1, 1, { bgColor: theme.bg("userMessageBg") }, getMarkdownTheme());
+```
+
+This approach:
+
+- Keeps TUI components theme-agnostic (reusable in other projects)
+- Maintains type safety via interfaces
+- Allows components to have sensible defaults if no theme provided
+- Centralizes theme access in `coding-agent`
+
+**Example usage:**
+
+```typescript
+const theme = loadTheme("dark");
+
+// Apply foreground colors
+theme.fg("accent", "Selected");
+theme.fg("success", "✓ Done");
+theme.fg("error", "Failed");
+
+// Apply background colors
+theme.bg("userMessageBg", content);
+theme.bg("toolSuccessBg", output);
+
+// Combine styles
+theme.bold(theme.fg("accent", "Title"));
+theme.italic(theme.fg("muted", "metadata"));
+
+// Nested foreground + background
+const userMsg = theme.bg("userMessageBg", theme.fg("userMessageText", "Hello"));
+```
+
+**Color resolution:**
+
+1. **Detect terminal capabilities:**
+
+   - Check `$COLORTERM` env var (`truecolor` or `24bit` → truecolor support)
+   - Check `$TERM` env var (`*-256color` → 256-color support)
+   - Fallback to 256-color mode if detection fails
+
+2. **Load JSON theme file**
+
+3. **Resolve `vars` references recursively:**
+
+   ```json
+   {
+   	"vars": {
+   		"primary": "#0066cc",
+   		"accent": "primary"
+   	},
+   	"colors": {
+   		"accent": "accent" // → "primary" → "#0066cc"
+   	}
+   }
+   ```
+
+4. **Convert colors to ANSI codes based on terminal capability:**
+
+   **Truecolor mode (24-bit):**
+
+   - Hex (`"#ff0000"`) → `\x1b[38;2;255;0;0m`
+   - 256-color (`42`) → `\x1b[38;5;42m` (keep as-is)
+   - Empty string (`""`) → `\x1b[39m`
+
+   **256-color mode:**
+
+   - Hex (`"#ff0000"`) → convert to nearest RGB cube color → `\x1b[38;5;196m`
+   - 256-color (`42`) → `\x1b[38;5;42m` (keep as-is)
+   - Empty string (`""`) → `\x1b[39m`
+
+   **Hex to 256-color conversion:**
+
+   ```typescript
+   // Convert RGB to 6x6x6 cube (colors 16-231)
+   r_index = Math.round((r / 255) * 5);
+   g_index = Math.round((g / 255) * 5);
+   b_index = Math.round((b / 255) * 5);
+   color_index = 16 + 36 * r_index + 6 * g_index + b_index;
+   ```
+
+5. **Cache as `Theme` instance**
+
+This ensures themes work correctly regardless of terminal capabilities, with graceful degradation from truecolor to 256-color.