From 9801a346b617918a0f7acb993c71a94302b82dd7 Mon Sep 17 00:00:00 2001 From: danny Date: Sun, 25 Oct 2026 13:50:38 +0100 Subject: [PATCH] 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 --- apps/lutra-desktop/src/main.rs | 2 +- crates/control/tests/theme.rs | 2 +- crates/engine/src/theme.rs | 207 ++++++++++++------ crates/engine/tests/theme.rs | 4 +- docs/architecture.md | 11 +- docs/target-app-parity.md | 5 +- docs/ui-parity.md | 6 +- ui/src/components/editor/assist/icons.ts | 38 +++- ui/src/components/editor/lint.ts | 32 +-- .../problems/ProblemsToolWindow.vue | 11 +- ui/tests/theme/contrast.test.ts | 42 +++- ui/tests/theme/theme.test.ts | 8 +- ui/tests/theme/themes.json | 152 +++++++------ 13 files changed, 345 insertions(+), 175 deletions(-) diff --git a/apps/lutra-desktop/src/main.rs b/apps/lutra-desktop/src/main.rs index 7a865e5..7e7380e 100644 --- a/apps/lutra-desktop/src/main.rs +++ b/apps/lutra-desktop/src/main.rs @@ -281,7 +281,7 @@ mod tests { fn reads_theme_colours() { assert_eq!( token_color(&theme::DARK, "bg"), - Some(Color(0x1f, 0x1d, 0x1b, 255)) + Some(Color(0x1e, 0x1b, 0x1e, 255)) ); assert_eq!(token_color(&theme::DARK, "missing"), None); } diff --git a/crates/control/tests/theme.rs b/crates/control/tests/theme.rs index 76b9402..f19e2b5 100644 --- a/crates/control/tests/theme.rs +++ b/crates/control/tests/theme.rs @@ -130,5 +130,5 @@ fn switching_streams_theme_changed_with_tokens() { changed["id"], "lutra-light", "switching from dark to system on an unreported (dark) OS must not emit" ); - assert_eq!(changed["tokens"]["--lt-editor-selection-bg"], "#e5d7c9"); + assert_eq!(changed["tokens"]["--lt-editor-selection-bg"], "#ecd6dc"); } diff --git a/crates/engine/src/theme.rs b/crates/engine/src/theme.rs index 6cb98af..a5f7192 100644 --- a/crates/engine/src/theme.rs +++ b/crates/engine/src/theme.rs @@ -2,9 +2,10 @@ //! //! Themes are defined here in Rust and rendered as CSS custom properties //! (`--lt-`). Frontend components use only `var(--lt-…)`. The palettes -//! are Lutra's own: warm otter browns with a copper accent. Text and -//! background pairs meet WCAG AA in both themes; `ui/tests/theme` checks it -//! against the snapshot `ui/tests/theme/themes.json`, which the test +//! are Lutra's own and follow the README banner: calm, near-neutral surfaces +//! (cream-tinted in the light theme, faintly plum-tinted in the dark one) +//! with the banner's raspberry as the only accent. Text and background pairs +//! meet WCAG AA in both themes; `ui/tests/theme` checks it against the snapshot `ui/tests/theme/themes.json`, which the test //! `ui_snapshot_is_current` keeps in step with this file. //! //! The setting `appearance.theme` holds a theme id or [`SYSTEM`]. "System" @@ -47,7 +48,8 @@ const COMMON: &[(&str, &str)] = &[ /// Syntax token names (`--lt-syntax-`) every theme defines. The /// editor's highlighter reads only these; each reaches 4.5:1 on the editor /// background (`ui/tests/theme/contrast.test.ts`). The colours are Lutra's -/// own, derived from the theme's copper accent and warm neutrals. +/// own, tuned to sit next to the raspberry accent without repeating it +/// (only keywords take a muted raspberry). pub const SYNTAX_TOKENS: &[&str] = &[ "keyword", "string", @@ -91,61 +93,91 @@ pub const TERMINAL_TOKENS: &[&str] = &[ "ansi-bright-white", ]; +/// Diagnostic severity token names (`--lt-diag-`) every theme +/// defines. They colour the editor's lint underlines, gutter markers and +/// tooltip stripes and the Problems window's severity icons; each reaches +/// 4.5:1 on the editor background, the active line and the window +/// background (`ui/tests/theme/contrast.test.ts`). +pub const DIAGNOSTIC_TOKENS: &[&str] = &["error", "warning", "info", "hint"]; + +/// Version-control status token names (`--lt-vcs-`) every theme +/// defines, for file names in the project tree and tabs and for the +/// editor's change markers. Each reaches 4.5:1 as text on the editor +/// background, the active line and the window background. +pub const VCS_TOKENS: &[&str] = &[ + "added", + "modified", + "deleted", + "untracked", + "ignored", + "conflicted", +]; + /// The default dark theme. pub const DARK: Theme = Theme { id: "lutra-dark", label_key: "theme.lutraDark", dark: true, tokens: &[ - ("bg", "#1f1d1b"), - ("editor-bg", "#191817"), - ("fg", "#e6e1da"), - ("fg-muted", "#9a928a"), - ("border", "#34302c"), - ("accent", "#d39a5c"), - ("error", "#ef7b6c"), - ("statusbar-bg", "#24211f"), - ("statusbar-fg", "#b8afa6"), - ("editor-selection-bg", "#513f2c"), - ("editor-active-line-bg", "#232221"), - ("editor-cursor", "#d39a5c"), - ("editor-gutter-bg", "#191817"), - ("editor-gutter-fg", "#9a928a"), - ("editor-match-bg", "#3a2f23"), - ("tab-active-bg", "#191817"), - ("tab-modified", "#d39a5c"), - ("notice-bg", "#3a3025"), - ("syntax-keyword", "#d39a5c"), + ("bg", "#1e1b1e"), + ("editor-bg", "#181618"), + ("fg", "#ebe5dc"), + ("fg-muted", "#9e9499"), + ("border", "#362f35"), + ("accent", "#e27ba6"), + ("error", "#f2836b"), + ("statusbar-bg", "#231f23"), + ("statusbar-fg", "#bdb3b8"), + ("editor-selection-bg", "#4c2d3d"), + ("editor-active-line-bg", "#221f22"), + ("editor-cursor", "#e27ba6"), + ("editor-gutter-bg", "#181618"), + ("editor-gutter-fg", "#9e9499"), + ("editor-match-bg", "#3a2632"), + ("tab-active-bg", "#181618"), + ("tab-modified", "#e27ba6"), + ("notice-bg", "#382632"), + ("syntax-keyword", "#d98aab"), ("syntax-string", "#a9bd7e"), - ("syntax-number", "#e3a1a8"), - ("syntax-comment", "#958d84"), - ("syntax-variable", "#d8bba6"), + ("syntax-number", "#e8a87c"), + ("syntax-comment", "#978e93"), + ("syntax-variable", "#dcc6b2"), ("syntax-function", "#e6c46f"), ("syntax-type", "#7fbac6"), - ("syntax-constant", "#c4a0d6"), + ("syntax-constant", "#b9a5e2"), ("syntax-tag", "#e08b70"), ("syntax-attribute", "#cdb87e"), - ("syntax-operator", "#b8afa6"), - ("terminal-bg", "#191817"), - ("terminal-fg", "#e6e1da"), - ("terminal-cursor", "#d39a5c"), - ("terminal-selection-bg", "#513f2c"), - ("terminal-ansi-black", "#2e2b28"), + ("syntax-operator", "#bdb3b8"), + ("diag-error", "#f2836b"), + ("diag-warning", "#e6b450"), + ("diag-info", "#8fb0e8"), + ("diag-hint", "#9e9499"), + ("vcs-added", "#9cc27a"), + ("vcs-modified", "#8fb0e8"), + ("vcs-deleted", "#d4908a"), + ("vcs-untracked", "#e3a464"), + ("vcs-ignored", "#8f878b"), + ("vcs-conflicted", "#f26d82"), + ("terminal-bg", "#181618"), + ("terminal-fg", "#ebe5dc"), + ("terminal-cursor", "#e27ba6"), + ("terminal-selection-bg", "#4c2d3d"), + ("terminal-ansi-black", "#2e2a2e"), ("terminal-ansi-red", "#ef7b6c"), ("terminal-ansi-green", "#a9bd7e"), ("terminal-ansi-yellow", "#e6c46f"), ("terminal-ansi-blue", "#8fa8e0"), - ("terminal-ansi-magenta", "#c4a0d6"), + ("terminal-ansi-magenta", "#e27ba6"), ("terminal-ansi-cyan", "#7fbac6"), - ("terminal-ansi-white", "#d0c9c1"), - ("terminal-ansi-bright-black", "#9a928a"), + ("terminal-ansi-white", "#d3cbc4"), + ("terminal-ansi-bright-black", "#9e9499"), ("terminal-ansi-bright-red", "#f59a8d"), ("terminal-ansi-bright-green", "#c2d69a"), ("terminal-ansi-bright-yellow", "#f2d88e"), ("terminal-ansi-bright-blue", "#aebff0"), - ("terminal-ansi-bright-magenta", "#dbbde8"), + ("terminal-ansi-bright-magenta", "#f0a6c6"), ("terminal-ansi-bright-cyan", "#a2d3dc"), - ("terminal-ansi-bright-white", "#f5f1ec"), + ("terminal-ansi-bright-white", "#f7f2ea"), ], }; @@ -155,55 +187,65 @@ pub const LIGHT: Theme = Theme { label_key: "theme.lutraLight", dark: false, tokens: &[ - ("bg", "#f4f1ec"), - ("editor-bg", "#fbfaf8"), - ("fg", "#2a2622"), - ("fg-muted", "#6b625a"), - ("border", "#ddd6cd"), - ("accent", "#965a22"), + ("bg", "#f3efe3"), + ("editor-bg", "#fbf9f3"), + ("fg", "#2a2427"), + ("fg-muted", "#675d61"), + ("border", "#ddd5c4"), + ("accent", "#a32c66"), ("error", "#b23a29"), - ("statusbar-bg", "#ece7e0"), - ("statusbar-fg", "#5a5149"), - ("editor-selection-bg", "#e5d7c9"), - ("editor-active-line-bg", "#f1efed"), - ("editor-cursor", "#965a22"), - ("editor-gutter-bg", "#fbfaf8"), - ("editor-gutter-fg", "#6b625a"), - ("editor-match-bg", "#ece2d8"), - ("tab-active-bg", "#fbfaf8"), - ("tab-modified", "#965a22"), - ("notice-bg", "#e9dfd4"), - ("syntax-keyword", "#965a22"), + ("statusbar-bg", "#ebe5d5"), + ("statusbar-fg", "#554c50"), + ("editor-selection-bg", "#ecd6dc"), + ("editor-active-line-bg", "#f3f0e8"), + ("editor-cursor", "#a32c66"), + ("editor-gutter-bg", "#fbf9f3"), + ("editor-gutter-fg", "#675d61"), + ("editor-match-bg", "#f2e1e3"), + ("tab-active-bg", "#fbf9f3"), + ("tab-modified", "#a32c66"), + ("notice-bg", "#eedcdc"), + ("syntax-keyword", "#9a2d61"), ("syntax-string", "#4e6a24"), - ("syntax-number", "#a03a4e"), - ("syntax-comment", "#6e665e"), + ("syntax-number", "#9c4519"), + ("syntax-comment", "#6b6367"), ("syntax-variable", "#7f4a34"), ("syntax-function", "#7a5808"), ("syntax-type", "#24697a"), - ("syntax-constant", "#73479a"), + ("syntax-constant", "#5e489e"), ("syntax-tag", "#a5432a"), ("syntax-attribute", "#695d1a"), - ("syntax-operator", "#5a5149"), - ("terminal-bg", "#fbfaf8"), - ("terminal-fg", "#2a2622"), - ("terminal-cursor", "#965a22"), - ("terminal-selection-bg", "#e5d7c9"), - ("terminal-ansi-black", "#2a2622"), + ("syntax-operator", "#554c50"), + ("diag-error", "#b23a29"), + ("diag-warning", "#865500"), + ("diag-info", "#2f5aa8"), + ("diag-hint", "#675d61"), + ("vcs-added", "#3d7526"), + ("vcs-modified", "#2f5aa8"), + ("vcs-deleted", "#a3463b"), + ("vcs-untracked", "#93560c"), + ("vcs-ignored", "#71686c"), + ("vcs-conflicted", "#b01f45"), + ("terminal-bg", "#fbf9f3"), + ("terminal-fg", "#2a2427"), + ("terminal-cursor", "#a32c66"), + ("terminal-selection-bg", "#ecd6dc"), + ("terminal-ansi-black", "#2a2427"), ("terminal-ansi-red", "#b23a29"), ("terminal-ansi-green", "#4e6a24"), ("terminal-ansi-yellow", "#7a5808"), ("terminal-ansi-blue", "#2f55a4"), - ("terminal-ansi-magenta", "#73479a"), + ("terminal-ansi-magenta", "#a32c66"), ("terminal-ansi-cyan", "#24697a"), - ("terminal-ansi-white", "#ddd6cd"), - ("terminal-ansi-bright-black", "#6b625a"), + ("terminal-ansi-white", "#ddd5c4"), + ("terminal-ansi-bright-black", "#675d61"), ("terminal-ansi-bright-red", "#8f2a1c"), ("terminal-ansi-bright-green", "#3b5418"), ("terminal-ansi-bright-yellow", "#5f4404"), ("terminal-ansi-bright-blue", "#233f7f"), - ("terminal-ansi-bright-magenta", "#5a3480"), + ("terminal-ansi-bright-magenta", "#7c1f4d"), ("terminal-ansi-bright-cyan", "#1a5260"), - ("terminal-ansi-bright-white", "#f4f1ec"), + ("terminal-ansi-bright-white", "#f3efe3"), ], }; @@ -363,6 +405,27 @@ mod tests { } } + #[test] + fn themes_define_the_diagnostic_and_vcs_tokens() { + for theme in BUILTIN { + let tokens = token_map(theme); + for name in DIAGNOSTIC_TOKENS { + assert!( + tokens.contains_key(&format!("--lt-diag-{name}")), + "{} lacks diag-{name}", + theme.id + ); + } + for name in VCS_TOKENS { + assert!( + tokens.contains_key(&format!("--lt-vcs-{name}")), + "{} lacks vcs-{name}", + theme.id + ); + } + } + } + #[test] fn resolves_settings() { assert_eq!(resolve("lutra-light", Some(true)), LIGHT); @@ -377,7 +440,7 @@ mod tests { fn renders_css_variables() { let css = css_variables(&DARK); assert!(css.starts_with(":root {")); - assert!(css.contains(" --lt-bg: #1f1d1b;\n")); + assert!(css.contains(" --lt-bg: #1e1b1e;\n")); assert!(css.contains(" --lt-font-size-ui: 13px;\n")); assert!(css.contains("color-scheme: dark;")); } @@ -397,7 +460,7 @@ mod tests { let js = init_script("lutra-light"); assert!(js.contains("\\\"Segoe UI\\\"")); assert!(js.contains("lt-theme")); - assert!(js.contains("--lt-bg: #f4f1ec;")); + assert!(js.contains("--lt-bg: #f3efe3;")); assert_eq!(by_id("lutra-light"), Some(LIGHT)); assert_eq!(by_id("nope"), None); } diff --git a/crates/engine/tests/theme.rs b/crates/engine/tests/theme.rs index b1f085e..086a9fd 100644 --- a/crates/engine/tests/theme.rs +++ b/crates/engine/tests/theme.rs @@ -73,7 +73,7 @@ fn switching_the_setting_emits_the_new_tokens() { assert_eq!(id, "lutra-light"); assert!(!dark); assert_eq!(tokens, &theme::token_map(&theme::LIGHT)); - assert_eq!(tokens["--lt-bg"], "#f4f1ec"); + assert_eq!(tokens["--lt-bg"], "#f3efe3"); assert_eq!(tokens["--lt-font-size-editor"], "14px"); assert!(matches!( outcome.events.first(), @@ -105,7 +105,7 @@ fn system_mode_follows_the_reported_preference() { assert_eq!(events, []); assert_eq!(value["id"], "lutra-dark"); assert_eq!(value["dark"], true); - assert_eq!(value["tokens"]["--lt-bg"], "#1f1d1b"); + assert_eq!(value["tokens"]["--lt-bg"], "#1e1b1e"); assert!(value.get("kind").is_none()); let (value, events) = report(&mut e, false); diff --git a/docs/architecture.md b/docs/architecture.md index 19f6f2c..b19e1a6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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 `` 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-` 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-` 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 `