# Display Design Notes

The ESP32 display now follows the Ember visual system from
`/Users/jameslopez/projects/CodexBarRedesign/HANDOFF.md`. The macOS foreground
and widget-specific behavior from that handoff is intentionally not part of this
firmware surface.

## Goals

Each gauge answers two questions:

- How much quota do I have left?
- Is my current burn rate sustainable until the window resets?

The center number and fuel tank answer the first question. The outer arc answers
the second.

## Layout

For two providers, the 170x320 panel stacks two provider sections with a 1px
divider. Each section has:

- A top-left attention chip lane.
- A small provider glyph in the top-right corner.
- A centered gauge row with a large 5h gauge and a smaller 7d/Opus gauge.
- A window label and reset countdown below each gauge.

The 5h gauge gets the most space because it is the active-session limit most
likely to matter during a work session. The long-window gauge stays smaller but
readable.

## Ember Palette

The screen background is warm near-black (`#0c0a08`). The pace arc uses a
green-to-gold-to-rust heat ramp:

- `#54b173` under pace.
- `#d6a341` approaching the limit.
- `#dc8b34` at the sustainable line.
- `#c8643a` and `#bd4329` when over pace.

Type and the redline tick use warm cream (`#f3ecdc` / `#f4eede`). Actual fuel is
blue (`#4f93c9`), ahead-of-pace bonus fuel is green (`#55b572`), and missing
fuel is a muted red ghost.

## Pace Arc

The outer arc is a tachometer, not a raw usage meter.

```text
usage      = 100 - remaining
elapsed    = time elapsed / window duration
expUsage   = elapsed * 100
paceRatio  = usage / expUsage
```

Geometry uses clock degrees: `0°` is 12 o'clock and degrees increase clockwise.

- Arc start: `213°`
- Redline tick: `360°`
- Arc end: `507°`

Pace maps linearly across that span:

- `0.0` starts at lower-left.
- `1.0` lands at the 12 o'clock tick.
- `2.0` ends at lower-right.

The arc fill is a single solid heat color chosen from the pace ratio. This is
intentionally quieter than a per-degree gradient on the tiny TFT.

## Fuel Tank

The inner circle is remaining capacity:

```text
expected remaining = resets_in_sec / duration_sec
actual remaining   = 1 - pct_used
```

The tank always shows actual fuel in blue.

If actual remaining is above the expected line, a green bonus cap appears between
the expected line and the actual level.

If actual remaining is below the expected line, a muted red ghost appears between
the actual level and expected line. The blue fuel still means "what you actually
have"; the red ghost means "what you are missing relative to an even burn."

The expected line is dashed so it reads as a reference mark rather than another
filled region.

## Attention

Attention remains separate from quota. When a provider needs user input:

- A thin teal rail pulses on the left edge.
- A quiet teal chip shows the project name or `N waiting`.
- Gauges remain visible.

The pulse repaint only updates the rail region, keeping the device responsive
without redrawing the whole TFT every 500 ms.