Make the Trac window in the app's theme, and remove the patch window nothing opens - #649

…tor's own (#650)

## Why

The prototype's dialog has a fourth theme, and the dark theme of
#642 left it out: a
background and an accent colour of the contributor's own, from which the
design system builds every other colour as it builds the dark theme from
its one seed. This adds it, under the name the design system gives the
second colour: primary. Part of #560.

## What changes

**Custom, on the General tab.** Under **Theme**, a fourth answer;
chosen, two fields appear beneath it: **Background** and **Primary**,
each typed as hex or picked with the system's colour picker, which is
the swatch before the field. A colour is kept as six lowercase hex
digits from three or six as typed; one that is not a colour is refused
in main's words and the field goes back to what is kept. The picker's
choice is kept when the picker is done, not at every step of a drag,
since each keep is a write to the store; the field shows the colour
under the pointer meanwhile. The colours start as the light theme's.

**A custom theme is a scheme too.** Main gives Electron light or dark by
whether the background reads better with white text than with black, the
crossover the design system's own ramp turns at, so the native form
controls and the window's chrome match the page; and the window is made
and painted in the background chosen, as is the Trac window, which main
now hands its colour. The window reads the settings above the design
system's provider, since the theme is one of them, and gives the
provider the two colours; the terminal re-reads its colours whenever the
theme as painted changes, by a name that changes with it.

**When the colours do not read.** The design system says when it could
not reach the contrast it wants between two of the colours it built, and
under Custom the dialog passes that on in one sentence. The colours are
kept all the same: a contributor who chose them can read them, and the
sentence is for the one who did not mean to.

**Not in this pull request:**

- The moment before the settings arrive: a custom theme shows the
standard theme of its scheme for one round trip to main at launch, then
its own. Removing it means handing the renderer the theme before its
first paint, new bridge surface for a separate change.
- Mail rendering is unchanged here and tracked separately.

## How to test this

Platforms: any. The journeys drive this on macOS and Windows. From the
repository root, after `npm ci` and `npm run build:once`:

```
npx playwright test --project=journeys settings.spec i18n.spec
```

- `settings.spec.js`, the custom theme journey: the colours are asked
for under Custom alone and start as the light theme's; a dark background
typed and entered is kept, Electron is told the scheme, and the page,
the body and the window are painted in it at once; a primary colour in
three digits is kept in six and the brand surface is built from it; a
colour spelled another way shows as kept; a colour picked with the
picker is kept; a colour that is not one is refused in main's words and
what is kept stays; a light background makes a light theme again;
started again, the window is made in the background and the fields show
the colours kept.
- `i18n.spec.js`: the control in the pseudo-locale.

Six claims were broken one at a time and each turned the journey red:
the page not seeded from the colours, Electron not told the scheme, a
refusal leaving the typed text, three digits not expanded, the window
not painted in the background, and the picker driven from what is kept
rather than the draft, which was the bug the first review pass found.
`tests/unit/theme.test.cjs` holds the resolution, the crossover and the
hex forms; `settings.test.cjs` what is accepted; `ipc-wiring.test.cjs`
what Electron, the window and the Trac window are given.

**Worth a look by hand** (any platform, the current head): Settings →
General → Theme → **Custom**. Type `102030` into Background and press
Enter: the whole window is navy, the dialog included, and the native
controls (the folder field's button, a select's list) are dark. Press
the Primary swatch, drag in the picker: the field follows the pointer;
close the picker: the buttons take the colour. Type `navy`: refused
under the fields, the field back to the colour kept. Type `fff8e1`: a
cream theme with dark text and light controls. Quit and open the app: it
opens in the cream, after a moment of the standard light theme.

**What must not have happened:** the standard themes looking any
different (the guide's pictures are the reference); a picker drag
writing the store at every step; a colour kept that the field does not
show; a server or build touched by a change.

**What I could not test:** Windows and Linux pickers, which the OS
draws; the journeys drive the picker through its value, as a picker does
when it is done.

## Risks and limitations

- Review: 2 passes, 6 findings fixed here, 1 follow-up left (the flash
at launch), every style note applied. Details below.
- **A custom theme flashes the standard theme of its scheme at launch**,
for one round trip to main. See above.
- **The pre-paint of a dark window** is the dark seed, not the custom
background, for the moment before the page's script runs; then the
standard dark theme, then the custom one.
- **Two colours can be chosen that read badly together.** The dialog
says so and keeps them; the standard themes are one press away.

## Related

Part of #560, which is part of #542. Follows
#642 and
#649.

---

<details>
<summary>Design decisions and alternatives considered</summary>

- **"Primary", not the prototype's "accent".** It is what the design
system calls the seed, and what the provider's prop is named.
- **The scheme from the background's luminance**, by the rule the design
system's ramp uses to pick its text direction: white where it contrasts
better than black. One rule, so the native controls and the ramp agree
except within a hair of the crossover.
- **The picker commits when done, not as it is dragged.** A drag is tens
of events a second; each keep is a store write and an IPC round trip.
- **The picker driven from the draft.** A controlled input is put back
to its prop after every step of a drag, and the picker's closing then
reads the old colour: the first review pass found the picker never
saving.
- **The settings read above the provider.** The theme is a setting, so
the component that reads the settings has to sit above the one that
paints with them; the app is handed what was read.
- **The warning passed on, the colours kept.** The design system's
answer is the authority on contrast; the contributor is the authority on
what they want to look at.

</details>

<details>
<summary>Review outcome (required — see AGENTS.md)</summary>

**Pass 1: 4 [fix here] · 1 [follow-up] · 4 style notes. Pass 2 (on the
fix-up): 2 [fix here] · 0 [follow-up] · 3 style notes. All 6 fixed here,
every style note applied, 1 follow-up left.**

- **Review:** completed — a separate agent context, read-only; head
`8b3658a` / base `59afb0c`; the store rule against the changed handlers,
the theme's ordering in main against Electron's `themeSource`, the
luminance maths against the design system's own ramp direction, React's
controlled-input restore against the colour picker's `change`, the
design system's input and the provider's warnings; ESLint and the unit
files run; 4 [fix here], 1 [follow-up].
- Fixed: a colour picked with the picker was never kept, since a
controlled input is put back to its prop after every step of a drag and
the picker's closing read the old colour; the wiring test's Trac
assertion never opened a Trac window; the fallback before the settings
arrive was a branch in the component; the hex fields' monospace rule
reached nothing.
- Follow-up left: the standard theme of the scheme shows for one round
trip at launch.
- Style notes, applied: the crossover pinned; a colour spelled another
way shown as kept; a dead prop; the translator comment checked.
- **Review:** completed — a second separate agent context, read-only;
head `7fdf4e0` / base `59afb0c`; the picker's event order on a real
picker and under Playwright's fill, the listener's double-commit, the
accent ramp's first step for the journey's exact colours, the crossover
recomputed; ESLint and the unit files run; 2 [fix here].
- Fixed: a keep that finished late overwrote newer typing in the field;
what the field shows after a keep, and what the picker holds while the
field holds no colour, were decided in the component.
- Style notes, applied: the Trac assertion built a repository it never
opened; the journey's two exact colours say where they come from; a
comment on the swatch.
- **Since review:** `7fdf4e0 → 0a9965d` is those two and the notes, not
reviewed again; `31c125c` stands the swatch in the design system's
prefix slot as a centred square, from the maintainer's look at the
dialog, not reviewed again. On `0a9965d`: `npm run lint`, `npm test`,
`npm run test:electron`, all 133 journeys, the packaged smoke and the
docs build pass; on the head: `npm run lint`, `npm run test:electron`
(2045) and all 133 journeys, the packaged smoke not run since the
maintainer's own app held the single-instance lock. The commit after it
fixes a Windows-only cleanup race in `tests/unit/log-tail.test.cjs`, a
test this branch does not otherwise touch, which failed the Windows unit
job on `31c125c`: the read helper now settles on the stream's `close`,
so the folder is removed after the file is.

</details>

<details>
<summary>Implementation notes</summary>

- `src/theme.cjs`: `THEMES` with 'custom', `THEME_KEYS`, `resolveTheme`,
`nativeThemeSource`, `normalizeHexColor`, `isHexColor`, `isDarkColor`,
`PRIMARY`. `src/settings.cjs`: `customBackground`, `customPrimary`,
`acceptColor`.
- `src/main.js`: `themeSettings`, `applyTheme`, `currentTheme`,
`paintWindowForTheme`; `settings:set` applies for any theme key; the
Trac window is handed `backgroundColor`. `src/trac-view.js`:
`deps.backgroundColor`.
- `src/renderer/components/app-theme.jsx`: `AppTheme({ settings })`,
`useThemeKey`, `useThemeWarnings`. `src/renderer/index.jsx`: `Root`
reads the settings above the provider.
`src/renderer/hooks/use-site-terminal.jsx`: re-reads on the theme's
name.
- `src/renderer/components/settings-dialog.jsx`: `ColorField`, the
fourth option, the warning. `src/renderer/settings-view.cjs`:
`themeItems`. `src/renderer/shell.css`: `.theme-colors`, `.color-field`,
`.color-swatch`.
- Tests: `tests/unit/theme.test.cjs`, `settings.test.cjs`,
`settings-view.test.cjs`, `ipc-wiring.test.cjs`, `trac-view.test.cjs`;
`tests/e2e/journeys/settings.spec.js`.

</details>

<details>
<summary>Screenshots or recording</summary>

Not attached: I have no way to upload images from the command line. The
custom theme journey drives everything that changed; `SHOTS_THEME` takes
light or dark only, so a picture of a custom theme is a hand's work.

</details>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>