@diffexai/diffex 0.2.4 → 0.2.5

package/docs/terminal-setup.md

@@ -1,152 +0,0 @@
-# Terminal Setup
-
-Diffex uses the [Kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) for reliable modifier key detection. Most modern terminals support this protocol, but some require configuration.
-
-## Terminal focus and tmux
-
-Diffex uses terminal focus reporting to pause cursor animation when its terminal window or pane is not active. When reliable focus reporting is unavailable, the placeholder cursor remains static. To receive pane focus changes inside tmux and keep the focused-pane animation, add this to `~/.tmux.conf`:
-
-```tmux
-set -g focus-events on
-```
-
-Detach and reattach existing tmux clients after changing this option.
-
-## Kitty, iTerm2
-
-Work out of the box.
-
-## Apple Terminal
-
-Diffex enables enhanced key reporting when available. If Terminal.app still sends plain Return for `Shift+Enter`, Diffex uses a local macOS modifier fallback to treat that Return as `Shift+Enter`.
-
-This fallback only works when Diffex runs on the same Mac as Terminal.app. It cannot detect the local keyboard over remote SSH.
-
-## Ghostty
-
-Add to your Ghostty config (`~/Library/Application Support/com.mitchellh.ghostty/config` on macOS, `~/.config/ghostty/config` on Linux):
-
-```
-keybind = alt+backspace=text:\x1b\x7f
-```
-
-Older Claude Code versions may have added this Ghostty mapping:
-
-```
-keybind = shift+enter=text:\n
-```
-
-That mapping sends a raw linefeed byte. Inside Diffex, that is indistinguishable from `Ctrl+J`, so tmux and Diffex no longer see a real `shift+enter` key event.
-
-If Claude Code 2.x or newer is the only reason you added that mapping, you can remove it, unless you want to use Claude Code in tmux, where it still requires that Ghostty mapping.
-
-Diffex binds `Ctrl+J` as a default newline alias, so `Shift+Enter` keeps working in tmux via that remap without extra Diffex configuration.
-
-## WezTerm
-
-WezTerm usually works out of the box for `Shift+Enter` via xterm modifyOtherKeys. To use the Kitty keyboard protocol explicitly, create `~/.wezterm.lua`:
-
-```lua
-local wezterm = require 'wezterm'
-local config = wezterm.config_builder()
-config.enable_kitty_keyboard = true
-return config
-```
-
-On macOS, WezTerm binds `Option+Enter` to fullscreen by default. To use `Option+Enter` for Diffex follow-up queueing, add this key override:
-
-```lua
-local wezterm = require 'wezterm'
-local config = wezterm.config_builder()
-config.keys = {
-  {
-    key = 'Enter',
-    mods = 'ALT',
-    action = wezterm.action.SendString('\x1b[13;3u'),
-  },
-}
-return config
-```
-
-If you already have a `config.keys` table, add the entry to it.
-
-On WSL, WezTerm may require a visible hardware cursor for IME candidate window positioning. If CJK IME candidates do not follow the text cursor, set `DIFFEX_HARDWARE_CURSOR=1` before running Diffex or set `showHardwareCursor` to `true` in settings.
-
-## Alacritty
-
-Alacritty usually works out of the box for `Shift+Enter`. On macOS, `Option+Enter` may arrive as plain `Enter`. To use `Option+Enter` for Diffex follow-up queueing, add to `~/.config/alacritty/alacritty.toml`:
-
-```toml
-[[keyboard.bindings]]
-key = "Enter"
-mods = "Alt"
-chars = "\u001b[13;3u"
-```
-
-Restart Alacritty after changing the config.
-
-## VS Code (Integrated Terminal)
-
-VS Code 1.109.5 and newer enable Kitty keyboard protocol in the integrated terminal by default, so `Shift+Enter` should work out of the box.
-
-VS Code versions older than 1.109.5 need an explicit terminal keybinding for `Shift+Enter`.
-
-`keybindings.json` locations:
-- macOS: `~/Library/Application Support/Code/User/keybindings.json`
-- Linux: `~/.config/Code/User/keybindings.json`
-- Windows: `%APPDATA%\\Code\\User\\keybindings.json`
-
-Add to `keybindings.json`:
-
-```json
-{
-  "key": "shift+enter",
-  "command": "workbench.action.terminal.sendSequence",
-  "args": { "text": "\u001b[13;2u" },
-  "when": "terminalFocus"
-}
-```
-
-## Windows Terminal
-
-Add to `settings.json` (Ctrl+Shift+, or Settings → Open JSON file) to forward the modified Enter keys Diffex uses:
-
-```json
-{
-  "actions": [
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
-      "keys": "shift+enter"
-    },
-    {
-      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
-      "keys": "alt+enter"
-    }
-  ]
-}
-```
-
-- `Shift+Enter` inserts a new line.
-- Windows Terminal binds `Alt+Enter` to fullscreen by default. That prevents Diffex from receiving `Alt+Enter` for follow-up queueing.
-- Remapping `Alt+Enter` to `sendInput` forwards the real key chord to Diffex instead.
-
-If you already have an `actions` array, add the objects to it. If the old fullscreen behavior persists, fully close and reopen Windows Terminal.
-
-## xfce4-terminal, terminator
-
-These terminals have limited escape sequence support. Modified Enter keys like `Ctrl+Enter` and `Shift+Enter` cannot be distinguished from plain `Enter`, preventing custom keybindings such as `submit: ["ctrl+enter"]` from working.
-
-For the best experience, use a terminal that supports the Kitty keyboard protocol:
-- [Kitty](https://sw.kovidgoyal.net/kitty/)
-- [Ghostty](https://ghostty.org/)
-- [WezTerm](https://wezfurlong.org/wezterm/)
-- [iTerm2](https://iterm2.com/)
-- [Alacritty](https://github.com/alacritty/alacritty) (requires compilation with Kitty protocol support)
-
-## IntelliJ IDEA (Integrated Terminal)
-
-The built-in terminal has limited escape sequence support. Shift+Enter cannot be distinguished from Enter in IntelliJ's terminal.
-
-If you want the hardware cursor visible, set `DIFFEX_HARDWARE_CURSOR=1` before running Diffex (disabled by default for compatibility).
-
-Consider using a dedicated terminal emulator for the best experience.

package/docs/themes.md

@@ -1,326 +0,0 @@
-> Diffex can create themes. Ask it to build one for your setup.
-
-# Themes
-
-Themes are JSON files that define colors for the TUI.
-
-## Table of Contents
-
-- [Locations](#locations)
-- [Selecting a Theme](#selecting-a-theme)
-- [Creating a Custom Theme](#creating-a-custom-theme)
-- [Theme Format](#theme-format)
-- [Color Tokens](#color-tokens)
-- [Color Values](#color-values)
-- [Tips](#tips)
-
-## Locations
-
-Diffex loads themes from:
-
-- Built-in: `dark`, `light`
-- Global: `~/.diffex/agent/themes/*.json`
-- Project: `.diffex/themes/*.json` (only after the project is trusted)
-- Packages: `themes/` directories or `diffex.themes` entries in `package.json`
-- Settings: `themes` array with files or directories
-- CLI: `--theme <path>` (repeatable)
-
-Disable discovery with `--no-themes`.
-
-## Selecting a Theme
-
-Select a theme via `/settings` or in `settings.json`:
-
-```json
-{
-  "theme": "my-theme"
-}
-```
-
-On first run, Diffex detects your terminal background and defaults to `dark` or `light`.
-
-## Creating a Custom Theme
-
-1. Create a theme file:
-
-```bash
-mkdir -p ~/.diffex/agent/themes
-vim ~/.diffex/agent/themes/my-theme.json
-```
-
-2. Define the theme with all required colors (see [Color Tokens](#color-tokens)):
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/diffexai/diffex/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
-  "name": "my-theme",
-  "vars": {
-    "primary": "#00aaff",
-    "secondary": 242
-  },
-  "colors": {
-    "accent": "primary",
-    "border": "primary",
-    "borderAccent": "#00ffff",
-    "borderMuted": "secondary",
-    "success": "#00ff00",
-    "error": "#ff0000",
-    "warning": "#ffff00",
-    "muted": "secondary",
-    "dim": 240,
-    "text": "",
-    "thinkingText": "secondary",
-    "footerModel": "#F7ED4F",
-    "footerContext": "#F5B427",
-    "footerWindow": "#3A75F2",
-    "startupIntroText": "#CDD6F4",
-    "startupIntroAccent": "#89B4FA",
-    "selectionAccent": "#89B4FA",
-    "selectedBg": "#2d2d30",
-    "scrollbarThumb": "#555566",
-    "userMessageBg": "#2d2d30",
-    "userMessageText": "",
-    "customMessageBg": "#2d2d30",
-    "customMessageText": "",
-    "customMessageLabel": "primary",
-    "toolPendingBg": "#1e1e2e",
-    "toolSuccessBg": "#1e2e1e",
-    "toolErrorBg": "#2e1e1e",
-    "toolTitle": "primary",
-    "toolOutput": "",
-    "mdHeading": "#ffaa00",
-    "mdLink": "primary",
-    "mdLinkUrl": "secondary",
-    "mdCode": "#00ffff",
-    "mdCodeBlock": "",
-    "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",
-    "thinkingXhigh": "#ff0000",
-    "thinkingMax": "#ff0088",
-    "bashMode": "#ffaa00"
-  }
-}
-```
-
-3. Select the theme via `/settings`.
-
-**Hot reload:** When you edit the currently active custom theme file, Diffex reloads it automatically for immediate visual feedback.
-
-## Theme Format
-
-```json
-{
-  "$schema": "https://raw.githubusercontent.com/diffexai/diffex/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
-  "name": "my-theme",
-  "vars": {
-    "blue": "#0066cc",
-    "gray": 242
-  },
-  "colors": {
-    "accent": "blue",
-    "muted": "gray",
-    "text": "",
-    ...
-  }
-}
-```
-
-- `name` is required, must be unique, and must not contain `/`.
-- `vars` is optional. Define reusable colors here, then reference them in `colors`.
-- `colors` must define all 54 required tokens.
-  `editorBorder`, `thinkingMax`, `scrollbarThumb`, `startupIntroText`, `startupIntroAccent`, `selectionAccent`, and `autocompleteSelected` are optional compatibility tokens with fallbacks.
-
-The `$schema` field enables editor auto-completion and validation.
-
-## Color Tokens
-
-Every theme must define all 54 required color tokens.
-`editorBorder`, `thinkingMax`, `scrollbarThumb`, `startupIntroText`, `startupIntroAccent`, `selectionAccent`, and `autocompleteSelected` are optional for compatibility with existing themes.
-Their fallbacks are `borderMuted`, `thinkingXhigh`, `selectedBg`, `text`, `mdLink`, `autocompleteSelected` or `startupIntroAccent`, and `selectionAccent`, respectively.
-
-### Core UI (11 required, 1 optional)
-
-| Token | Purpose |
-|-------|---------|
-| `accent` | Primary accent for titles, active controls, and status elements |
-| `border` | Normal borders |
-| `borderAccent` | Highlighted borders |
-| `borderMuted` | Subtle borders (editor) |
-| `editorBorder` | Editor border; optional, falls back to `borderMuted` |
-| `success` | Success states |
-| `error` | Error states |
-| `warning` | Warning states |
-| `muted` | Secondary text |
-| `dim` | Tertiary text |
-| `text` | Default text (usually `""`) |
-| `thinkingText` | Thinking block text |
-
-### Footer Status (3 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `footerModel` | Model name |
-| `footerContext` | Context usage percentage |
-| `footerWindow` | Context window size |
-
-### Startup Intro And Selection (4 optional)
-
-| Token | Purpose |
-|-------|---------|
-| `startupIntroText` | Startup logo art, version, directory, and changelog preview text; optional, falls back to `text` |
-| `startupIntroAccent` | Startup title and boundary box; optional, falls back to `mdLink` |
-| `selectionAccent` | Selected row prefix and primary text; optional, falls back to `autocompleteSelected`, then `startupIntroAccent` |
-| `autocompleteSelected` | Legacy autocomplete selection color; optional, falls back to `selectionAccent` |
-
-### Backgrounds & Content (11 required, 1 optional)
-
-| Token | Purpose |
-|-------|---------|
-| `selectedBg` | Selected line background |
-| `scrollbarThumb` | Fullscreen scrollbar thumb background; optional, falls back to `selectedBg` |
-| `userMessageBg` | User message background |
-| `userMessageText` | User message text |
-| `customMessageBg` | Extension message background |
-| `customMessageText` | Extension message text |
-| `customMessageLabel` | Extension message label |
-| `toolPendingBg` | Tool box (pending) |
-| `toolSuccessBg` | Tool box (success) |
-| `toolErrorBg` | Tool box (error) |
-| `toolTitle` | Tool title |
-| `toolOutput` | Tool output text |
-
-### Markdown (10 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `mdHeading` | Headings |
-| `mdLink` | Link text |
-| `mdLinkUrl` | Link URL |
-| `mdCode` | Inline code |
-| `mdCodeBlock` | Code block content |
-| `mdCodeBlockBorder` | Code block fences |
-| `mdQuote` | Blockquote text |
-| `mdQuoteBorder` | Blockquote border |
-| `mdHr` | Horizontal rule |
-| `mdListBullet` | List bullets |
-
-### Tool Diffs (3 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `toolDiffAdded` | Added lines |
-| `toolDiffRemoved` | Removed lines |
-| `toolDiffContext` | Context lines |
-
-### Syntax Highlighting (9 colors)
-
-| Token | Purpose |
-|-------|---------|
-| `syntaxComment` | Comments |
-| `syntaxKeyword` | Keywords |
-| `syntaxFunction` | Function names |
-| `syntaxVariable` | Variables |
-| `syntaxString` | Strings |
-| `syntaxNumber` | Numbers |
-| `syntaxType` | Types |
-| `syntaxOperator` | Operators |
-| `syntaxPunctuation` | Punctuation |
-
-### Thinking Level Borders (6 required, 1 optional)
-
-Editor border colors indicating thinking level (visual hierarchy from subtle to prominent):
-
-| Token | Purpose |
-|-------|---------|
-| `thinkingOff` | Thinking off |
-| `thinkingMinimal` | Minimal thinking |
-| `thinkingLow` | Low thinking |
-| `thinkingMedium` | Medium thinking |
-| `thinkingHigh` | High thinking |
-| `thinkingXhigh` | Extra high thinking |
-| `thinkingMax` | Maximum thinking; optional, falls back to `thinkingXhigh` |
-
-### Bash Mode (1 color)
-
-| Token | Purpose |
-|-------|---------|
-| `bashMode` | Editor border in bash mode (`!` prefix) |
-
-### HTML Export (optional)
-
-The `export` section controls colors for `/export` HTML output. If omitted, colors are derived from `userMessageBg`.
-
-```json
-{
-  "export": {
-    "pageBg": "#18181e",
-    "cardBg": "#1e1e24",
-    "infoBg": "#3c3728"
-  }
-}
-```
-
-## Color Values
-
-Four formats are supported:
-
-| Format | Example | Description |
-|--------|---------|-------------|
-| Hex | `"#ff0000"` | 6-digit hex RGB |
-| 256-color | `39` | xterm 256-color palette index (0-255) |
-| Variable | `"primary"` | Reference to a `vars` entry |
-| Default | `""` | Terminal's default color |
-
-### 256-Color Palette
-
-- `0-15`: Basic ANSI colors (terminal-dependent)
-- `16-231`: 6×6×6 RGB cube (`16 + 36×R + 6×G + B` where R,G,B are 0-5)
-- `232-255`: Grayscale ramp
-
-### Terminal Compatibility
-
-Diffex uses 24-bit RGB colors. Most modern terminals support this (iTerm2, Kitty, WezTerm, Windows Terminal, VS Code). For older terminals with only 256-color support, Diffex falls back to the nearest approximation.
-
-Check truecolor support:
-
-```bash
-echo $COLORTERM  # Should output "truecolor" or "24bit"
-```
-
-## Tips
-
-**Dark terminals:** Use bright, saturated colors with higher contrast.
-
-**Light terminals:** Use darker, muted colors with lower contrast.
-
-**Color harmony:** Start with a base palette (Nord, Gruvbox, Tokyo Night), define it in `vars`, and reference consistently.
-
-**Testing:** Check your theme with different message types, tool states, markdown content, and long wrapped text.
-
-**VS Code:** Set `terminal.integrated.minimumContrastRatio` to `1` for accurate colors.
-
-## Examples
-
-See the built-in themes:
-- [dark.json](../src/modes/interactive/theme/dark.json)
-- [light.json](../src/modes/interactive/theme/light.json)

package/docs/tmux.md

@@ -1,63 +0,0 @@
-# tmux Setup
-
-Diffex works inside tmux, but tmux strips modifier information from certain keys by default. Without configuration, `Shift+Enter` and `Ctrl+Enter` are usually indistinguishable from plain `Enter`.
-
-## Recommended Configuration
-
-Add to `~/.tmux.conf`:
-
-```tmux
-set -g extended-keys on
-set -g extended-keys-format csi-u
-```
-
-Then restart tmux fully:
-
-```bash
-tmux kill-server
-tmux
-```
-
-Diffex requests extended key reporting automatically when Kitty keyboard protocol is not available. With `extended-keys-format csi-u`, tmux forwards modified keys in CSI-u format, which is the most reliable configuration. The `extended-keys-format` option requires tmux 3.5 or later.
-
-## Why `csi-u` Is Recommended
-
-With only:
-
-```tmux
-set -g extended-keys on
-```
-
-tmux defaults to `extended-keys-format xterm`. When an application requests extended key reporting, modified keys are forwarded in xterm `modifyOtherKeys` format such as:
-
-- `Ctrl+C` → `\x1b[27;5;99~`
-- `Ctrl+D` → `\x1b[27;5;100~`
-- `Ctrl+Enter` → `\x1b[27;5;13~`
-
-With `extended-keys-format csi-u`, the same keys are forwarded as:
-
-- `Ctrl+C` → `\x1b[99;5u`
-- `Ctrl+D` → `\x1b[100;5u`
-- `Ctrl+Enter` → `\x1b[13;5u`
-
-Diffex supports both formats, but `csi-u` is the recommended tmux setup.
-
-## What This Fixes
-
-Without tmux extended keys, modified Enter keys collapse to legacy sequences:
-
-| Key | Without extkeys | With `csi-u` |
-|-----|-----------------|--------------|
-| Enter | `\r` | `\r` |
-| Shift+Enter | `\r` | `\x1b[13;2u` |
-| Ctrl+Enter | `\r` | `\x1b[13;5u` |
-| Alt/Option+Enter | `\x1b\r` | `\x1b[13;3u` |
-
-This affects the default keybindings (`Enter` to submit, `Shift+Enter` for newline) and any custom keybindings using modified Enter.
-
-## Requirements
-
-- tmux 3.5 or later for `extended-keys-format csi-u` (run `tmux -V` to check)
-- A terminal emulator that supports extended keys (Ghostty, Kitty, iTerm2, WezTerm, Windows Terminal)
-
-With tmux 3.2 through 3.4, omit `extended-keys-format csi-u`; Diffex still supports tmux's default xterm `modifyOtherKeys` format.