# Theme and Header Reference

## Sakura Macaron theme

Theme file:

```text
themes/sakura-macaron.json
```

Theme name:

```text
sakura-macaron
```

Select this theme from Pi's `/settings` menu.

## Palette

| Variable | Value | Intended use |
| --- | --- | --- |
| `bg` | `#14111A` | Page background |
| `surface` | `#1E1826` | Cards and primary surfaces |
| `surfaceSoft` | `#251D2D` | Soft secondary surfaces |
| `surfaceRaised` | `#2D2438` | Selected and raised regions |
| `text` | `#F7EEF8` | Primary response text |
| `textSoft` | `#D8CADC` | Secondary text |
| `muted` | `#A99BAE` | Muted metadata and model thinking text |
| `dim` | `#716879` | Lowest-emphasis text |
| `sakura` | `#F2A7C6` | Primary accent |
| `sakuraIro` | `#FCC9B9` | Warm Sakura accent |
| `petal` | `#EFC3E6` | Petal accent |
| `peach` | `#F6BC9A` | Types and code accents |
| `lavender` | `#C7B8F5` | Variables and high thinking levels |
| `sky` | `#9FD3F2` | Links, functions, and tool titles |
| `mint` | `#AEE5C5` | Success states and strings |
| `butter` | `#F3D98B` | Warnings and numbers |
| `coral` | `#FF8FA3` | Errors and removed lines |

Following Pi's built-in `dark` theme, model thinking uses the muted text color while the response body uses the brighter primary text color.

The theme covers Pi's:

- General borders, text, accents, success, warning, and error states
- User and custom messages
- Tool titles, output, and backgrounds
- Markdown headings, links, code, quotes, lists, and horizontal rules
- Added, removed, and context diff lines
- Syntax highlighting
- Thinking levels from off through max
- Bash mode
- HTML and page export backgrounds

The theme can be used independently or combined with any Pi UI extension that does not replace the same header region.

## Header

Entry point:

```text
extensions/header/index.ts
```

### Lifecycle

- On `session_start`, the extension calls `ctx.ui.setHeader()` when a UI is available.
- On `session_shutdown`, it calls `ctx.ui.setHeader(undefined)`.
- The extension does not install the header in headless or other non-UI modes.

### Rendering

The header contains:

1. Nine lines of Unicode artwork.
2. A per-character 24-bit RGB Sakura-to-Sky gradient.
3. A gradient divider rail.
4. A bold `SAKURA CYBERDECK` label with a Lavender-to-Peach gradient.
5. Width-aware clipping and horizontal centering.
6. Additional top spacing based on available terminal rows for approximate vertical centering.

The renderer returns no content when `width <= 0`. If terminal row detection fails, it falls back to zero available rows without interrupting the session.

## Brand customization

### Changing the label

Edit the telemetry string in `extensions/header/index.ts`:

```ts
const telemetry = "◈  SAKURA CYBERDECK  ◈";
```

After replacing the text, verify its appearance with the terminal's actual Unicode glyph widths.

### Changing the gradients

The header uses four RGB values:

```ts
const sakura = [242, 167, 198];
const peach = [252, 201, 185];
const lavender = [199, 184, 245];
const sky = [159, 211, 242];
```

The artwork uses Sakura to Sky, while the label uses Lavender to Peach.

### Changing the artwork

Replace the `ANIME_ART` array. For reliable rendering:

- Keep line widths similar.
- Test clipping in narrow terminals.
- Avoid glyphs that are missing from common terminal fonts.
- Remember that the current clipping logic counts Unicode code points rather than terminal cells.

### Changing the theme

Edit `themes/sakura-macaron.json`:

1. Prefer changing values in `vars`.
2. Reference variable names from `colors`.
3. Preserve every color key required by the Pi theme schema.
4. Run `npm run check`.
5. Verify messages, Markdown, tools, diffs, and all thinking levels in a real Pi TUI.

## Truecolor and font compatibility

- The header emits `38;2;r;g;b` ANSI sequences and requires Truecolor support.
- Hex colors in the theme also depend on terminal Truecolor support.
- The artwork does not require a Nerd Font, but the selected terminal font must contain its Unicode characters.