H5: banner-aligned themes, diagnostic and VCS tokens

Both themes follow the README banner without taking it over: calm,
near-neutral surfaces (cream-tinted light, faintly plum-tinted dark),
the raspberry only as the accent, retuned syntax colours and the
terminal on the editor surface. Approved by the owner from before/after
screenshots.

New tokens `--lt-diag-error|warning|info|hint` (lint underlines, gutter,
tooltips, Problems icons) and `--lt-vcs-added|modified|deleted|untracked|
ignored|conflicted` (for M4.4), listed in `theme::DIAGNOSTIC_TOKENS` and
`theme::VCS_TOKENS`. Completion kind icons take the syntax colour of
their kind. The contrast test checks every new colour (4.5:1 text,
3:1 icons) in both themes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 13:50:38 +01:00
parent e73bdbbbbc
commit 9801a346b6
13 changed files with 345 additions and 175 deletions

View file

@ -1,6 +1,6 @@
# Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4) · **Last updated:** 2026-10-24
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands, the palette, the settings dialog, the app icon and the syntax layer documented; M2 highlighting and `editor.reveal`, plus the search backend, the Find tool window, the symbol index, the Structure tool window and the go-to popup; M3 CLI and single instance, LSP client library, toolchain (PHP detection, Phpactor download), the app menu, MCP server, autosave and `flushDirty`, integrated terminal; engine ↔ Phpactor wiring and diagnostics (M3.3), pending outcomes (M3.5), completion, hover and signature help (M3.4); C5 child process groups (H1), settings dialog string and path controls and assist settings (H4), the banner-aligned themes and diagnostic/VCS tokens (H5) · **Last updated:** 2026-10-25
## Overview
@ -142,7 +142,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- **Languages:** `ui/src/components/editor/language.ts` picks a language once per tab from the file extension (`languageOf`): PHP (`php`, `phtml`, `inc`, `php3`–`php8`, `phps`) through `@codemirror/lang-php`, whose Lezer grammar also parses the HTML, CSS and JavaScript around `<?php … ?>` blocks; HTML, CSS, JavaScript/TypeScript (with JSX), JSON, YAML and Markdown through their `@codemirror/lang-*` packages (all MIT). Other files stay plain text. The editor store passes the tab's path to `editorExtensions(path)` when it creates the tab's state.
- **Colours:** the highlighter is a `tagHighlighter` that only sets classes: a span gets `lt-syntax-<token>` for one of the eleven tokens `keyword`, `string`, `number`, `comment`, `variable`, `function`, `type`, `constant`, `tag`, `attribute`, `operator`. The editor theme (`extensions.ts`) colours each class with its `--lt-syntax-<token>` variable. Lezer tags that are not mapped fall back to their parent tag (`controlKeyword` → `keyword`); tags without a mapped ancestor (punctuation, plain names such as the class after `extends`) keep `--lt-fg`. CodeMirror's default highlight style is never active, so no colour bypasses the tokens.
- **Tokens:** `lutra_engine::theme::SYNTAX_TOKENS` lists the names; both themes define `syntax-*` values. It is Lutra's own palette, derived from the copper accent and the warm neutrals (keyword = accent, comment near `fg-muted`, operator = `statusbar-fg`). The contrast test checks each one at 4.5:1 on `editor-bg` and on `editor-active-line-bg` in both themes, and that the themes define no syntax token it does not check. Lowest ratios: dark comment 5.42 on the editor background and 4.86 on the active line; light keyword 5.32 and 4.84. Text on the selection colour is not held to 4.5:1 (syntax colours reach 3.06–5.96 there).
- **Tokens:** `lutra_engine::theme::SYNTAX_TOKENS` lists the names; both themes define `syntax-*` values. It is Lutra's own palette, tuned to the raspberry accent (H5: keyword = a muted raspberry, comment near `fg-muted`, operator = `statusbar-fg`). The contrast test checks each one at 4.5:1 on `editor-bg` and on `editor-active-line-bg` in both themes, and that the themes define no syntax token it does not check. Lowest ratios: dark comment 5.42 on the editor background and 4.86 on the active line; light keyword 5.32 and 4.84. Text on the selection colour is not held to 4.5:1 (syntax colours reach 3.06–5.96 there).
- **Two highlighters:** Lezer in the UI highlights on every keystroke without IPC; tree-sitter in `crates/syntax` (M2.1) drives outline, folding and the index. They can disagree on broken code; that is accepted (see Decisions).
- **Performance:** keystroke to highlight on a 1 MB PHP file (30k lines), measured with `LUTRA_PERF=1 pnpm vitest run tests/editor/highlightPerf.test.ts` in jsdom (the JavaScript work of one `view.dispatch`, no layout or paint), Windows 11, three runs while other builds ran: median 3.0–3.8 ms near the top of the file and 6.3–11.4 ms in the middle; p95 10–16 ms in two runs (one disturbed run: 82 ms). The plain-text baseline is 0.4–0.6 ms. The initial full parse takes 0.7–1.5 s, which CodeMirror spreads over idle slices after the visible part. Not measured in the WebView itself yet (follow-up for `lutra perf`).
- **`editor.reveal {path, line, column}`** (`reveal.ts`; a UI command registered through `ui.registerCommands`, label `command.editor.reveal`, provided by `EditorArea.vue`):
@ -184,12 +184,14 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
### Themes (M1.10)
- `lutra_engine::theme` defines `DARK` (`lutra-dark`) and `LIGHT` (`lutra-light`) with the same token names, plus shared font tokens. Besides the base colours (`bg`, `editor-bg`, `fg`, `fg-muted`, `border`, `accent`, `error`, `statusbar-*`) both define `editor-selection-bg`, `editor-active-line-bg`, `editor-cursor`, `editor-gutter-bg`, `editor-gutter-fg`, `editor-match-bg`, `tab-active-bg`, `tab-modified`, `notice-bg`; `font-size-editor` is shared (14px). Values are opaque `#rrggbb` derived from the palette (selection, match and notice are the accent mixed into the background); the designer may change values, never names.
- **Brand alignment (H5, approved by the owner 2026-10-25):** the palettes follow the README banner (raspberry #bc3c79, plum #83224b, cream #f2ecd7) without taking it over: surfaces stay calm and near-neutral (light: cream-tinted, `bg` #f3efe3; dark: a faint plum tint, `bg` #1e1b1e, cream `fg`), the raspberry is only the accent (light #a32c66, dark #e27ba6: cursor, modified dot, focus, active tab, selection and match tints), and the terminal follows the editor surface (ANSI magenta = accent). No new UI fonts.
- **Diagnostic and VCS tokens (H5):** `theme::DIAGNOSTIC_TOKENS` → `--lt-diag-error|warning|info|hint` (lint underlines, gutter dots, tooltip stripes, Problems icons; warning is amber, info blue, hint muted) and `theme::VCS_TOKENS` → `--lt-vcs-added|modified|deleted|untracked|ignored|conflicted` (tree and tab file names, change markers; M4.4). Each reaches 4.5:1 on `editor-bg`, `editor-active-line-bg` and `bg` (lowest: `vcs-ignored` 4.67 dark, 4.73 light on the active line). Completion kind icons (Lucide) take `--lt-syntax-*` by kind (`assist/icons.ts` `KIND_COLOURS`), at least 3:1 on the popup and the selected row.
- `appearance.theme` selects the theme: a theme id or `system`. `theme::resolve(setting, system_dark)` picks the theme; `system` follows the OS preference the frontend reports, and counts as dark until it has.
- Commands: `theme.list` → `[{id, label, dark}]` (`label` is a catalog key, `theme.lutraDark`/`theme.lutraLight`); `theme.systemPreference {dark}` stores the OS preference and returns the resolved theme `{id, dark, tokens}`. Switching goes through `settings.set appearance.theme` (or `settings.reset`).
- Event: `themeChanged {id, dark, tokens: {"--lt-…": value}}` (every token, shared ones included) whenever the resolved theme changes: after `settingsChanged` for `appearance.theme`, or after `theme.systemPreference` in system mode. A change that resolves to the same theme (`lutra-dark` → `system` on a dark OS) emits nothing.
- First frame: the desktop reads `appearance.theme` before creating the window and passes `theme::init_script(setting)`, which installs `<style id="lt-theme">`. For `system` the CSS is the dark theme plus the light one inside `@media (prefers-color-scheme: light)`, so the first frame follows the OS without a round trip; the native window background is set from the resolved theme (`Window::theme()` for system).
- Live switch: `ui/src/theme.ts` (`startTheme`, called by `App.vue`) reports `matchMedia("(prefers-color-scheme: dark)")` now and on every change, applies the result and every `themeChanged`: tokens go onto `:root`'s inline style (which wins over the injected style element), `color-scheme` is set, and `data-theme` holds the id. No reload.
- Accessibility: `ui/tests/theme/contrast.test.ts` checks every text/background pair the components draw with against WCAG AA (4.5:1 text, 3:1 cursor and modified dot) in both themes. It reads `ui/tests/theme/themes.json`, which the Rust test `theme::tests::ui_snapshot_is_current` keeps equal to the Rust definition (`LUTRA_UPDATE_SNAPSHOTS=1` rewrites it). `ui/tests/theme/theme.test.ts` fails on a `var(--lt-x)` the themes lack and on a fallback for a token they define.
- Accessibility: `ui/tests/theme/contrast.test.ts` checks every text/background pair the components draw with against WCAG AA (4.5:1 text, 3:1 cursor and modified dot) in both themes, plus the diagnostic, VCS and completion-icon colours (H5). It reads `ui/tests/theme/themes.json`, which the Rust test `theme::tests::ui_snapshot_is_current` keeps equal to the Rust definition (`LUTRA_UPDATE_SNAPSHOTS=1` rewrites it). `ui/tests/theme/theme.test.ts` fails on a `var(--lt-x)` the themes lack and on a fallback for a token they define.
- Not themed yet: the native title bar follows the OS, not the Lutra theme; spacing and size tokens (`--lt-space-*`, `--lt-radius`, `--lt-row-height`…) are still CSS fallbacks in components. `editor.fontSize` drives `--lt-font-size-editor` since M1.9b (see Settings dialog).
### Recovery journal (M1.7)
@ -385,7 +387,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- Diagnostics are cleared (an empty `diagnosticsChanged` per file) when the session ends or the server fails, so stale ones never stay. The pump handles at most 2,000 server events per call.
- **UI:**
- **Editor:** `ui/src/components/editor/lint.ts` feeds CodeMirror's lint extension (`@codemirror/lint`, MIT) with wavy underlines, a gutter dot, and the message with source and code on hover.
- Colours come only from tokens: error `--lt-error`, warning `--lt-accent`, info/hint `--lt-fg-muted`. Dedicated diagnostic tokens are a design follow-up.
- Colours come only from the severity tokens `--lt-diag-error`, `--lt-diag-warning`, `--lt-diag-info`, `--lt-diag-hint` (H5).
- A view plugin per editor state applies its path's list when the view shows the state and on every change. CodeMirror maps ranges through edits until the next publication.
- **Problems:** `ui/src/components/problems/` holds the store and the tab.
- The store loads `diagnostics.list` and `lsp.status` on start and on project open, follows the events, and hands each file to `lint.ts`.
@ -560,6 +562,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 2026-10-24 | minor | H4: string and path controls in the settings dialog (`pick_file` IPC), assist settings (auto popup, completion delay, hover delay) read live |
| 2026-10-25 | minor | H5: banner-aligned light and dark palettes, `DIAGNOSTIC_TOKENS` and `VCS_TOKENS`, completion icon colours by kind, contrast test extended |
| 2026-10-25 | minor | H6: isolated data directory (`--data-dir`, `LUTRA_DATA_DIR`, `--control` temp dir), shared tools dir, rendezvous order |
| 2026-10-24 | minor | H1: `crates/proc` (L0), child processes in kill-on-close groups (Windows job objects, Unix process groups with a watchdog); Phpactor and the PHP probe use it |
| 2026-10-22 | minor | M3.5: definition, references, rename (`lsp_nav`, workspace edits, undoable remote edits, nav UI) |