T1: four more themes, theme picker, theme file import, editor font settings

Plum Night, River, Paper and Reed (designed by Amy, approved by Daniel)
join the brand pair. theme.list/current/select/import, a picker with
live preview (view.selectTheme) and "Import Theme…" (view.importTheme);
imported themes are validated and stored in <data_dir>/themes. Editor
font family and line height settings apply live. Docs: docs/themes.md.

Gate: fmt, clippy and the rest pass up to cargo test, where only the
unrelated lutra-terminal PTY test a_full_buffer_stops_the_shell timed
out under load; to be re-run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-11-02 19:47:58 +01:00
parent 872b5cb258
commit 086bc8a925
26 changed files with 2881 additions and 100 deletions

View file

@ -1,6 +1,6 @@
# Gaps
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal, autosave); G3 M1 part done (project tree, palette, settings dialog with string and path controls, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download, engine wiring and diagnostics, completion and hover, definition, references and rename, Phpactor dies with Lutra, faster indexing, progress and messages, `php -l` on Windows); G7 under way (`lutra` CLI and single instance, MCP server, integrated terminal); G8 under way (Git backend, M4.1; Changes window, M4.2; gutter markers and status colours, M4.4; diff viewer, M4.3; branch widget and popup, M4.5; merge conflicts, M4.8; remotes, M4.10; stash, M4.9; chunk staging, C8 C3); G14 English UI catalog in place · **Last updated:** 2026-11-01
> **Status:** M0 closed G1; G2 under way (text buffer, engine buffers, tabs and editor in the app, recovery journal, autosave); G3 M1 part done (project tree, palette, settings dialog with string and path controls, themes) plus the app menu (M3.9); G4 under way (tree-sitter outline and folding library, Lezer highlighting, Structure tool window); G5 under way (search backend, Find tool window, symbol index, go-to popup); G6 under way (LSP client library, PHP detection, Phpactor download, engine wiring and diagnostics, completion and hover, definition, references and rename, Phpactor dies with Lutra, faster indexing, progress and messages, `php -l` on Windows); G7 under way (`lutra` CLI and single instance, MCP server, integrated terminal); G8 under way (Git backend, M4.1; Changes window, M4.2; gutter markers and status colours, M4.4; diff viewer, M4.3; branch widget and popup, M4.5; merge conflicts, M4.8; remotes, M4.10; stash, M4.9; chunk staging, C8 C3); G14 English UI catalog in place · **Last updated:** 2026-11-06
Every known shortfall, ranked. This is the work list: unless the owner gives a task, take the highest open gap. Hours are agent wall-clock hours for one agent, all estimated.
@ -8,7 +8,7 @@ Every known shortfall, ranked. This is the work list: unless the owner gives a t
|---|---|---|---|
| G1 | ~~Foundation: workspace, quality gate, command registry, guard, control channel~~ closed 2026-10-14 | M0 | done (~2 h measured) |
| G2 | Editor core: ~~engine buffers, save~~ (M1.3), ~~editor UI with tabs, undo, multi-caret~~ (M1.6, CodeMirror basics), ~~recovery journal~~ (M1.7), tab management (preview, pin, split, close others, reopen), conflict UI for files changed on disk, ~~autosave~~ (M3.10), local history | M1 | ~14 h |
| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, ~~showing truncated listings~~ (M1.13), ~~error notifications for the folder picker~~ (M1.12), ~~tabs~~ (M1.6), ~~command palette~~ (M1.8: commands only, global keymap, UI commands over the control channel); ~~settings~~ (backend: M1.9a; dialog with search: M1.9b; string and path controls: H4), ~~theme switching~~ (M1.10: light/dark, live, system mode; picker in the dialog, M1.9b), ~~main menu~~ (M3.9: hamburger dropdown from `menuPath`s; native macOS menu bar: A1 adds the system menus (Lutra, Edit, Window; ⌘W and ⌘Q stay Lutra's), mirroring Lutra's own menus natively and display modes open) | M1 | ~24 h |
| G3 | Project model: ~~VFS~~ (M1.2: listing, ignore rules, native file watching with polling fallback, safe file IO), ~~project tree wiring~~ (M1.5 UI, M1.3 engine, M1.4 bridge: folder picker, live tree), tree toolbar and options, ~~showing truncated listings~~ (M1.13), ~~error notifications for the folder picker~~ (M1.12), ~~tabs~~ (M1.6), ~~command palette~~ (M1.8: commands only, global keymap, UI commands over the control channel); ~~settings~~ (backend: M1.9a; dialog with search: M1.9b; string and path controls: H4), ~~theme switching~~ (M1.10: light/dark, live, system mode; picker in the dialog, M1.9b; C9 T1: six built-in themes, picker with live preview, theme file import, editor font family and line height), ~~main menu~~ (M3.9: hamburger dropdown from `menuPath`s; native macOS menu bar: A1 adds the system menus (Lutra, Edit, Window; ⌘W and ⌘Q stay Lutra's), mirroring Lutra's own menus natively and display modes open) | M1 | ~24 h |
| G4 | Syntax and structure: tree-sitter PHP, ~~Lezer highlighting~~ (M2.2: PHP with embedded HTML plus HTML, CSS, JS/TS, JSON, YAML, Markdown; `--lt-syntax-*` tokens; `editor.reveal`), ~~file structure~~ (M2.7: Structure tool window, `syntax.outline`), semantic highlighting, folding in the editor | M2 | ~8 h |
| G5 | Search and navigation: find in files, go to file/class/symbol, first index | M2 | ~35 h |
| G6 | Language server: completion, definition, hover, rename via Phpactor (~~PHP detection and Phpactor download~~, M3.1; ~~engine wiring and diagnostics~~, M3.3; ~~completion, hover, signature help~~, M3.4; ~~definition, references, rename~~, M3.5) | M3 | ~15 h |
@ -56,6 +56,7 @@ G6 progress: M3.2 landed the LSP client library in `crates/lsp`: JSON-RPC framin
| Date | Change | Summary |
|---|---|---|
| 2026-11-06 | patch | G17: deployment v1 (C9 D1); remote browser, compare and sync left for D2 |
| 2026-11-06 | minor | G3: more themes, theme import, editor font settings (C9 T1) |
| 2026-11-01 | patch | G8: chunk staging, unstaging and revert from the gutter and the diff viewer (C8 C3) |
| 2026-10-31 | patch | C7 review: stray revision rows moved here; installers (B1, B2) and the alpha checklist (A2) change no gap |
| 2026-10-31 | patch | A1: macOS system menus (G3), Retina region for the macOS screenshot fallback |

158
docs/themes.md Normal file
View file

@ -0,0 +1,158 @@
# Themes
> **Status:** six built-in themes, theme files with import, editor font settings (C9 T1) · **Last updated:** 2026-11-02
Every colour and font in Lutra comes from theme tokens: CSS custom properties `--lt-<name>` that `crates/engine/src/theme.rs` defines and the UI reads with `var(--lt-…)`. Nothing in the UI hard-codes a colour.
## Built-in themes
| Id | Name | Kind | Character |
|---|---|---|---|
| `lutra-dark` | Lutra Dark | dark | The brand theme (H5): near-neutral, faintly plum surfaces, raspberry accent. |
| `lutra-light` | Lutra Light | light | The brand theme (H5): cream-tinted surfaces, raspberry accent. |
| `lutra-plum-night` | Plum Night | dark | Deep, warm plum surfaces with a soft cream-gold accent. |
| `lutra-river` | River | dark | Cool slate and river teal; raspberry keywords keep the family link. |
| `lutra-paper` | Paper | light | Almost white paper with the banner plum as the accent; the quietest theme. |
| `lutra-reed` | Reed | light | Soft sand and sage surfaces with a muted pine accent. |
Amy designed the four C9 themes from the README banner and the brand tokens; Daniel approved them on 2026-11-02. All colours are Lutra's own (no copied editor or IDE scheme). Every text colour reaches WCAG AA (4.5:1) on the backgrounds it is drawn on, and every icon and cursor colour reaches 3:1. `ui/tests/theme/contrast.test.ts` checks this for every built-in theme on each run of the gate.
## Choosing a theme
- **Settings ▸ Appearance ▸ Theme** lists every built-in and imported theme and "Same as system".
- **View ▸ Select Theme…** (`view.selectTheme`, also in the command palette) opens a picker. Up/Down previews a theme live, Enter keeps it, Escape goes back to the one you had.
- **Same as system** follows the light or dark preference of the operating system, using Lutra Dark and Lutra Light.
- Agents and scripts: `theme.list`, `theme.current`, `theme.select { id }` (an id from `theme.list`, or `system`), or `settings.set` with `appearance.theme`. Every switch is live: the engine sends `themeChanged` with all tokens.
## Editor font
The **Editor** section of the settings has three font settings. They apply live and stay when you switch themes.
| Setting | Default | Meaning |
|---|---|---|
| `editor.fontFamily` | empty | A CSS font list such as `"JetBrains Mono", monospace`. Empty uses Lutra's monospace stack (`ui-monospace, "Cascadia Code", Menlo, Consolas, monospace`), which also stays behind your choice as a fallback. The font must be installed. The characters `; { } < > \` are refused. Applies to the editor and other code text at once, and to terminals opened afterwards (it drives `--lt-font-mono`). |
| `editor.fontSize` | 14 | Size in pixels, 8 to 48. |
| `editor.lineHeight` | 150 | Line height in percent of the font size, 100 to 300. |
## Theme files
A theme file is a UTF-8 JSON file of at most 256 KiB:
```json
{
"lutraTheme": 1,
"id": "my-river",
"name": "My River",
"dark": true,
"description": "River with a warmer accent",
"author": "you",
"tokens": {
"bg": "#1a2125",
"editor-bg": "#151b1e",
"fg": "#e2e8e6",
"fg-muted": "#8e9ca3",
"border": "#2c373d",
"accent": "#e8a87c",
"error": "#f08a7a",
"statusbar-bg": "#1e272b",
"statusbar-fg": "#adbbc0",
"editor-selection-bg": "#28434a",
"editor-active-line-bg": "#1b2327",
"editor-cursor": "#6fc6b8",
"editor-gutter-bg": "#151b1e",
"editor-gutter-fg": "#8e9ca3",
"editor-match-bg": "#24393b",
"tab-active-bg": "#151b1e",
"tab-modified": "#6fc6b8",
"notice-bg": "#223a3c",
"syntax-keyword": "#e392b6",
"syntax-string": "#9fcb94",
"syntax-number": "#e8ae86",
"syntax-comment": "#87959c",
"syntax-variable": "#d2dcd9",
"syntax-function": "#e4cb7c",
"syntax-type": "#74c3d1",
"syntax-constant": "#b4aaea",
"syntax-tag": "#e6957c",
"syntax-attribute": "#c9bd86",
"syntax-operator": "#adbbc0",
"diag-error": "#f08a7a",
"diag-warning": "#e2b65c",
"diag-info": "#8fb6ec",
"diag-hint": "#8e9ca3",
"vcs-added": "#93c98a",
"vcs-modified": "#8fb6ec",
"vcs-deleted": "#d69a92",
"vcs-untracked": "#e3aa6a",
"vcs-ignored": "#86939a",
"vcs-conflicted": "#f27a90",
"terminal-bg": "#151b1e",
"terminal-fg": "#e2e8e6",
"terminal-cursor": "#6fc6b8",
"terminal-selection-bg": "#28434a",
"terminal-ansi-black": "#263035",
"terminal-ansi-red": "#ee8172",
"terminal-ansi-green": "#9fcb94",
"terminal-ansi-yellow": "#e4cb7c",
"terminal-ansi-blue": "#8cb0e8",
"terminal-ansi-magenta": "#e392b6",
"terminal-ansi-cyan": "#74c3d1",
"terminal-ansi-white": "#c6d0cd",
"terminal-ansi-bright-black": "#8e9ca3",
"terminal-ansi-bright-red": "#f6a597",
"terminal-ansi-bright-green": "#bfdeb2",
"terminal-ansi-bright-yellow": "#f0dc9c",
"terminal-ansi-bright-blue": "#afc6f2",
"terminal-ansi-bright-magenta": "#f0b0cd",
"terminal-ansi-bright-cyan": "#a6dbe3",
"terminal-ansi-bright-white": "#f3f6f5"
}
}
```
| Key | Required | Meaning |
|---|---|---|
| `lutraTheme` | yes | The format version, `1`. |
| `id` | yes | 1 to 64 lowercase letters, digits and dashes, starting with a letter. It must not be a built-in id or `system`. Importing a file with the same id again replaces that theme. |
| `name` | yes | Display name, 1 to 64 characters, no control characters. |
| `dark` | yes | `true` for a dark theme. It sets the window's `color-scheme`, so scroll bars and form controls match. |
| `tokens` | yes | Every colour token below, as `"#rrggbb"`. Names may be written with or without the `--lt-` prefix. |
| `description`, `author` | no | Free text; Lutra ignores it. |
Lutra refuses any other key, an unknown or repeated token, a missing token and a colour that is not `#rrggbb`. The error names the problem (for example "59 tokens are missing: bg, editor-bg, … and 51 more"). Fonts and sizes are not part of a theme; they are the settings above.
### Importing
**View ▸ Import Theme…** (`view.importTheme`) asks for a file, checks it and switches to the theme. A broken file shows an error with the reason and changes nothing. Lutra stores a checked, normalised copy in its data directory under `themes/<id>.json` and loads it at every start. If a stored file is broken later, Lutra skips it with a warning and starts normally. To remove an imported theme, delete its file there and restart Lutra.
Agents and scripts: `theme.import { path, select?: true }`. It returns `{ id, name, dark, replaced }` and fails with the reason.
Lutra does not check the contrast of an imported theme. To check it the way the built-in themes are checked, keep text at 4.5:1 or more against the backgrounds listed below.
### Colour tokens
| Tokens | Used for |
|---|---|
| `bg`, `fg`, `fg-muted`, `border` | Window surface, text, secondary text and lines (tool windows, dialogs, popups). |
| `accent`, `error` | Focus rings, active tab and tool-window markers, buttons; error text. |
| `statusbar-bg`, `statusbar-fg` | Status bar. |
| `editor-bg`, `editor-selection-bg`, `editor-active-line-bg`, `editor-cursor`, `editor-gutter-bg`, `editor-gutter-fg`, `editor-match-bg` | The editor. Selection and active line sit under text, so text must stay readable on them. |
| `tab-active-bg`, `tab-modified`, `notice-bg` | The active tab, the unsaved-changes dot, and highlighted rows (current problem, notices). |
| `syntax-keyword`, `syntax-string`, `syntax-number`, `syntax-comment`, `syntax-variable`, `syntax-function`, `syntax-type`, `syntax-constant`, `syntax-tag`, `syntax-attribute`, `syntax-operator` | Syntax highlighting; also the colours of completion kind icons and the Structure window. Text on `editor-bg` and `editor-active-line-bg`. |
| `diag-error`, `diag-warning`, `diag-info`, `diag-hint` | Underlines, gutter markers and Problems icons; text on `editor-bg`, `editor-active-line-bg` and `bg`. |
| `vcs-added`, `vcs-modified`, `vcs-deleted`, `vcs-untracked`, `vcs-ignored`, `vcs-conflicted` | Git status colours of file names in the tree and tabs and of the change markers; text on `bg`, `editor-bg`, `editor-active-line-bg` and `tab-active-bg`. |
| `terminal-bg`, `terminal-fg`, `terminal-cursor`, `terminal-selection-bg` | The terminal. |
| `terminal-ansi-black` … `terminal-ansi-white`, `terminal-ansi-bright-black` … `terminal-ansi-bright-white` (16) | ANSI colours in the order black, red, green, yellow, blue, magenta, cyan, white. They are text on `terminal-bg`, except the one meant to vanish into it (black in a dark theme, white and bright white in a light one). |
## For contributors
- A built-in theme is a `Theme` constant in `crates/engine/src/theme.rs`, listed in `BUILTIN`, with its name in `ui/src/i18n/en.json` (`theme.<camelId>` and `settings.appearance.theme.value.<camelId>`).
- Every built-in theme defines exactly the tokens of `DARK` (a Rust test checks it). After changing a token, run the engine tests with `LUTRA_UPDATE_SNAPSHOTS=1` to rewrite `ui/tests/theme/themes.json`. The Vitest contrast test reads that file.
- A new token needs a value in every theme, a row above, and a contrast pair in `contrast.test.ts` if text or marks are drawn with it.
- Bundling JetBrains Mono as the default (waiting for the owner to approve OFL-1.1 in `xtask/src/licences.rs` and `deny.toml`) takes three steps: add `@fontsource/jetbrains-mono` to `ui/package.json` and import it in `ui/src/main.ts`; put `"JetBrains Mono"` first in `font-mono` (`COMMON` in `theme.rs`) and in `MONO_FALLBACK` (`ui/src/stores/settings.ts`); then update the default described above.
## Revision history
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | major | First version: four new built-in themes, theme file format and import, editor font settings (C9 T1) |

View file

@ -1,6 +1,6 @@
# UI parity checklist
> **Status:** main window layout (M1.5), project tree running against the engine (M1.4), editor tabs with a CodeMirror editor (M1.6), light and dark themes (M1.10), restore dialog for unsaved changes (M1.7), notification toasts (M1.12), command palette and global keymap (M1.8), settings dialog with search (M1.9b), syntax highlighting and `editor.reveal` (M2.2), Find tool window in the bottom panel (M2.4), go-to popup (M2.6), left stripe and Structure tool window (M2.7), app menu (M3.9), Terminal tool window and bottom panel tabs (M3.6), Problems tool window and editor diagnostics (M3.3), completion, quick documentation and parameter info (M3.4), string and path settings with completion and tooltip settings (H4), banner-aligned themes with diagnostic and VCS colours (H5), Changes tool window (M4.2), Git change markers and status colours (M4.4), diff viewer and the project tree's context menu (M4.3), branch widget and popup (M4.5), fetch/pull/push progress, the clone and remotes dialogs (M4.10) · **Last updated:** 2026-11-01
> **Status:** main window layout (M1.5), project tree running against the engine (M1.4), editor tabs with a CodeMirror editor (M1.6), light and dark themes (M1.10), restore dialog for unsaved changes (M1.7), notification toasts (M1.12), command palette and global keymap (M1.8), settings dialog with search (M1.9b), syntax highlighting and `editor.reveal` (M2.2), Find tool window in the bottom panel (M2.4), go-to popup (M2.6), left stripe and Structure tool window (M2.7), app menu (M3.9), Terminal tool window and bottom panel tabs (M3.6), Problems tool window and editor diagnostics (M3.3), completion, quick documentation and parameter info (M3.4), string and path settings with completion and tooltip settings (H4), banner-aligned themes with diagnostic and VCS colours (H5), Changes tool window (M4.2), Git change markers and status colours (M4.4), diff viewer and the project tree's context menu (M4.3), branch widget and popup (M4.5), fetch/pull/push progress, the clone and remotes dialogs (M4.10), four more themes, theme import and editor font settings (C9 T1) · **Last updated:** 2026-11-02
- [ ] Main window: tool window stripes, editor area, status bar, navigation bar
- M2.7 (2026-10-17): a left stripe with one tab per left tool window (Project, Structure); the shown one is marked, clicking it again hides the window. Still missing: right docking, several bottom tool windows, drag to rearrange, navigation bar, layout persistence.
@ -24,8 +24,9 @@
- [ ] Keymap editor (Lutra's own default keymap; no copied keymaps)
- M1.8 (2026-10-16): the global keymap built from the default shortcuts of engine and UI commands; no user keymap and no editor yet.
- [ ] Light and dark themes from theme tokens
- M1.10 (2026-10-16): Lutra Dark and Lutra Light from Rust tokens, switched live through `appearance.theme` (no reload), `system` follows the OS preference, the first frame uses the stored theme; the editor (selection, active line, cursor, gutter, matches), tabs and notices have their own tokens; WCAG AA contrast checked by Vitest for every text pair in both themes. Covered by Vitest DOM and control-channel tests; live check pending (gaming mode). M1.9b: theme picker in the settings dialog, editor font size from `editor.fontSize`. Missing: a theme command in the palette, the native title bar following the theme, colour scheme editor, high-contrast theme.
- M1.10 (2026-10-16): Lutra Dark and Lutra Light from Rust tokens, switched live through `appearance.theme` (no reload), `system` follows the OS preference, the first frame uses the stored theme; the editor (selection, active line, cursor, gutter, matches), tabs and notices have their own tokens; WCAG AA contrast checked by Vitest for every text pair in both themes. Covered by Vitest DOM and control-channel tests; live check pending (gaming mode). M1.9b: theme picker in the settings dialog, editor font size from `editor.fontSize`. Missing: the native title bar following the theme, colour scheme editor, high-contrast theme (the palette command came with C9 T1).
- H5 (2026-10-25): both themes follow the README banner, approved by the owner from before/after screenshots (tree, PHP editor, Problems, terminal, palette, settings; Windows 11, bundled UI, control port 7955): cream-tinted light theme, faintly plum-tinted dark theme, raspberry only as the accent, retuned syntax colours, the terminal on the editor surface. Diagnostics get their own colours (`--lt-diag-*`: error, amber warning, blue info, muted hint) in the underline, gutter dot, tooltip stripe and Problems icon; `--lt-vcs-*` status colours for M4.4; completion kind icons coloured by kind. Every text colour ≥ 4.5:1 and icon colour ≥ 3:1 in both themes (Vitest contrast test).
- C9 T1 (2026-11-02): four more built-in themes designed by Amy and approved by the owner: Plum Night and River (dark), Paper and Reed (light), each with the full token set and AA contrast checked by the Vitest contrast test. "Select Theme…" (`view.selectTheme`, View menu, palette) opens a picker that previews live while moving and restores on Escape; `theme.select`, `theme.current` and `theme.list` serve agents. Theme files (JSON, every colour token, validated; `docs/themes.md`) come in through "Import Theme…" (`view.importTheme`) or `theme.import`, are stored in Lutra's data directory and appear in the picker and the settings; a broken file gives the reason, a broken stored file is skipped with a warning. Editor font family and line height settings join the font size, all live. Missing: a colour scheme editor, exporting and removing themes in the UI, per-token font styles, a high-contrast theme, a bundled JetBrains Mono (needs the OFL licence approved for the frontend check).
- [ ] Notifications and background task indicator
- M1.12 (2026-10-16): toasts at the bottom right for engine and host notifications (corrupt settings and journal entries at startup, folder that cannot be opened, `unsaved_changes` when switching projects, file watching stopped, failed commands without their own UI): info dismissed after 5 s, warnings and errors stay until closed, close button and Escape, at most 5 visible with "+n more", `role="status"`/`role="alert"`; startup notifications are replayed when the page starts listening. Vitest (19 store and component tests); live check pending (gaming mode). Missing: a notification log / Notifications tool window, actions inside a toast, balloon grouping, "don't show again", background task indicator with progress.
- [ ] Structure tool window
@ -51,6 +52,7 @@
| Date | Change | Summary |
|---|---|---|
| 2026-11-02 | minor | Four more themes, theme picker, theme file import, editor font family and line height (C9 T1) |
| 2026-11-01 | patch | Chunk popup from the gutter and the diff viewer, staged markers, partly staged rows (C8 C3) |
| 2026-10-31 | patch | Changes context menu with Add to .gitignore and the merge message prefill (C7 A3) |
| 2026-10-28 | minor | Fetch/pull/push with progress, clone and remotes dialogs (M4.10) |