# Visual Profiles

Threadwell uses visual profiles only for terminal capability and surrounding UI polish. The chat transcript itself uses the barebones Pi-like renderer by default.

## Current direction

Threadwell's accepted interactive model is:

- simple transcript rendering for user messages, assistant thinking/text, and tool output;
- Threadwell startup header, footer/inputbox, selectors, and settings overlays around that transcript;
- optional safe or Nerd Font glyphs for surrounding UI;
- terminal-capability gates for image attachments, paste handling, and editor features;
- internal transcript viewport/cache for fixed footer/input and fast long sessions.

The old enhanced chat-card path has been removed from the default chat body. The startup header is surrounding chrome and remains separate from assistant/tool/message rendering. Do not reintroduce framed assistant/tool/message cards without a separate design and acceptance pass.

## Profiles

| Profile | Purpose |
|---------|---------|
| `auto` | Default. Chooses enhanced surrounding UI on capable terminals. |
| `enhanced` | Force enhanced surrounding UI/capability gates. |
| `baseline` | Force legacy/simple surrounding UI for troubleshooting or limited terminals. |

Run with a temporary override:

```bash
threadwell --visual-profile baseline
threadwell --visual-profile enhanced
threadwell --visual-profile auto
```

Persist a profile and glyph set in settings:

```json
{
  "interface": {
    "visualProfile": "auto",
    "glyphSet": "safe"
  }
}
```

## Glyph sets

Windows Terminal and many default terminal setups support truecolor and Unicode box drawing, but they do not ship with Nerd Fonts configured. Threadwell therefore defaults to portable glyphs.

If your terminal is configured with a Nerd Font, enable icons from `/settings` → `Interface` → `Nerd Font icons`, or set:

```json
{
  "interface": {
    "glyphSet": "nerd"
  }
}
```

Use `"safe"` to return to portable glyphs.

## Viewport, selection, and streaming

Threadwell uses a TUI renderer with an internal transcript viewport so the editor/footer can stay fixed and long sessions remain fast. This is not stdout-only terminal output, so normal mouse text selection may require Shift in terminals that route mouse input to the app.

During streaming, the viewport cache preserves historical child component caches while invalidating only rendered transcript lines that changed. This keeps active turns responsive while still showing live assistant and tool-call progress.

If a terminal leaves stale lines after shrinking content, users can opt into a full redraw on shrink:

```json
{
  "terminal": {
    "clearOnShrink": true
  }
}
```

or temporarily:

```bash
THREADWELL_CLEAR_ON_SHRINK=1 threadwell
```
