# Terminal Compatibility Guide

This guide covers display compatibility issues and solutions for Kollabor CLI across different terminal emulators.

## Line Spacing / Border Gap Issues

If you see gaps or detached borders in the UI (borders appear separated from content), this is caused by your terminal's line spacing settings or font rendering.

### Quick Fix: Change Border Style

Add this to your `~/.kollabor-cli/config.json`:

```json
{
  "core": {
    "ui": {
      "border_style": "lines"
    }
  }
}
```

### Available Border Styles

| Style | Characters | Description |
|-------|------------|-------------|
| `half_blocks` | `▄▀` | Default. Best visual quality but may have gaps in some terminals |
| `lines` | `─│┌┐└┘` | Unicode box-drawing. Most compatible, no gap issues |
| `lines_rounded` | `─│╭╮╰╯` | Box-drawing with rounded corners |
| `lines_heavy` | `━┃┏┓┗┛` | Heavy/thick box-drawing |
| `lines_double` | `═║╔╗╚╝` | Double-line box-drawing |
| `ascii` | `-|++++` | Simple ASCII. Universal fallback |
| `none` | (spaces) | No visible borders |

### Terminal-Specific Line Height Settings

If you prefer the half-block style and want to fix the gaps at the source:

#### iTerm2 (macOS)

1. Open Preferences (Cmd + ,)
2. Go to Profiles > Text
3. Find "n/n" line spacing setting (usually shows "100%")
4. Reduce to 90-95% or adjust until gaps disappear

#### VS Code Integrated Terminal

Add to your settings.json:

```json
{
  "terminal.integrated.lineHeight": 1.0
}
```

Or try values like 0.95 if gaps persist.

#### Kitty

Add to `~/.config/kitty/kitty.conf`:

```
modify_font cell_height -1px
```

Or adjust the value until gaps disappear.

#### Alacritty

Add to `~/.config/alacritty/alacritty.yml`:

```yaml
font:
  offset:
    y: -1
```

Adjust the `y` value as needed.

#### GNOME Terminal

1. Right-click > Preferences
2. Select your profile
3. Click "Custom font"
4. Choose a font with good block character support

#### Windows Terminal

Add to your settings.json profile:

```json
{
  "profiles": {
    "defaults": {
      "padding": "0, 0, 0, 0"
    }
  }
}
```

#### Hyper

Add to `.hyper.js`:

```javascript
module.exports = {
  config: {
    lineHeight: 1.0,
  }
};
```

### Recommended Fonts

Some fonts render Unicode block characters better than others. These fonts are known to work well:

- **JetBrains Mono** - Excellent block character support
- **Fira Code** - Good ligatures and block rendering
- **Cascadia Code** - Microsoft's modern monospace font
- **SF Mono** - macOS system monospace
- **Menlo** - Classic macOS monospace
- **DejaVu Sans Mono** - Good cross-platform option
- **Iosevka** - Customizable with good Unicode support
- **Hack** - Clean design with good Unicode coverage

### Color Mode Compatibility

If colors look wrong, you may need to set the color mode:

```bash
# Force 256-color mode (for terminals that don't support true color)
export KOLLABOR_COLOR_MODE=256

# Force true color (24-bit RGB)
export KOLLABOR_COLOR_MODE=truecolor

# Disable colors entirely
export KOLLABOR_COLOR_MODE=none
```

Add the export to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) for persistence.

### Testing Your Configuration

You can test border rendering by running Kollabor and checking if:

1. The input box borders connect properly
2. Message boxes have seamless edges
3. Status widgets display without gaps

If issues persist after trying these solutions, switch to `border_style: "lines"` for guaranteed compatibility.

## Troubleshooting

### Borders still have gaps after changing line height

1. Try a different font from the recommended list
2. Use `border_style: "lines"` instead
3. Check if your terminal has a separate "cell height" or "character spacing" setting

### Characters appear as boxes or question marks

Your terminal font doesn't support the required Unicode characters:

1. Install a font with good Unicode support (see recommended fonts)
2. Set your terminal to use that font
3. Or use `border_style: "ascii"` for universal ASCII characters

### Performance issues with borders

If rendering feels slow:

1. Use `border_style: "none"` to disable border rendering entirely
2. Reduce the render FPS in config: `"terminal": { "render_fps": 10 }`

## Configuration Reference

Full config example with all UI options:

```json
{
  "core": {
    "ui": {
      "theme": "lime",
      "border_style": "lines"
    }
  },
  "terminal": {
    "render_fps": 20,
    "thinking_effect": "shimmer"
  }
}
```

Available themes: `lime`, `ocean`, `sunset`, `mono`

Available border styles: `half_blocks`, `lines`, `lines_rounded`, `lines_heavy`, `lines_double`, `ascii`, `none`
