feat: KDE Plasma (Breeze) theme preset and native KDE theming

.claude/CLAUDE.review.md

@@ -86,6 +86,11 @@ These are the explicit rules the codebase is meant to follow. Flag deviations.
 - **Error types:** `thiserror` (`#[derive(thiserror::Error)]` with `#[error("...")]` per variant;
   `#[from]` for transparent conversions, `#[source]` for nested chains). Do not hand-roll
   `Display` / `std::error::Error` / `From`.
+- **Clean-room KDE code:** `teksilo-kde-scheme` is written from
+  `engineering/docs/kde-breeze-spec.md` only, never from KDE or Qt source.
+  `crates/teksilo-kde-scheme/tests/clean_room_vocabulary.rs` fails on upstream identifiers in
+  the scanned directories; flag a new KDE crate missing from its `SCANNED` list, a word removed
+  from its list, and code whose structure mirrors upstream rather than the specification.
 
 ---
 
@@ -128,8 +133,10 @@ teksilo-preview-ui      Reusable 3-pane previewer GUI
 teksilo-widgets-previewer   Bundle binary for the stock catalog
 teksilo-terminal        Embeddable terminal-emulator widget; PTY + VT delegated behind a
                         TerminalEngine trait. Renders into the wgpu surface (unlike webview)
-teksilo-theme-material3 / teksilo-theme-fluent / teksilo-theme-macos
+teksilo-theme-material3 / teksilo-theme-fluent / teksilo-theme-macos / teksilo-theme-kde
                         Sibling design-language presets (tokens + Tier-3 chrome), feature-gated
+teksilo-kde-scheme      KDE Plasma colour-scheme model and desktop settings; no I/O (environment and
+                        files passed in); read by teksilo-platform and teksilo-theme-kde
 teksilo-inspector       In-app debug introspection panel; cfg(debug_assertions) only
 teksilo-automation      GUI-free automation toolkit (DTOs, execute(), tool catalog, wire protocol)
 teksilo-automation-mcp  MCP server binary driving it
@@ -143,7 +150,7 @@ Stated dependency flow (verify):
 `canvas → render → platform → app`, `settings → app`, `i18n-macros → i18n`,
 `core → preview`, `preview-ui → preview + widgets`, `widgets → scene`, `core → webview`,
 `(app + core) → async → {tokio, async-std}`, `(core + tokens + canvas + platform) → terminal`,
-`(core + canvas) → automation → automation-mcp`.
+`(core + canvas) → automation → automation-mcp`, `tokens → kde-scheme → {platform, theme-kde}`.
 
 ---
 
@@ -196,7 +203,11 @@ axis at each child's final main size, then places. All in logical pixels. `Leadi
 `ThemeAppearance::{Light, Dark}` is a required field. Presets `presets::intui::{light, dark}` ship
 in `teksilo-core`. There is no `Theme::default()`. Per-widget style traits live in
 `teksilo-core/src/styles/`; default `Recipe*Style` impls in `teksilo-widgets/src/styles/`. Apps
-install styles per-call (`.style(...)`) or theme-wide (`theme.style_slots.<widget> = ...`).
+install styles per-call (`.style(...)`) or theme-wide (`theme.style_slots.<widget> = ...`). The
+sibling presets (Material 3, Fluent, macOS, KDE's Breeze) are separate crates behind umbrella
+features. `ThemeMode::Native` adopts the live desktop's colours through one function,
+`resolve_native_theme`; a theme change after a window is built re-tints and keeps the shapes the
+tree was built with, by design (`docs/native-theme.md`).
 
 ### App entry point
 
@@ -271,6 +282,7 @@ Core:
 - Accessibility: `crates/teksilo-core/src/accessibility.rs`
 - Animation: `crates/teksilo-core/src/animation.rs`, `animated_quad.rs`, `frame_tick_scheduler.rs`, `motion_visibility.rs`
 - Theme/styling: `crates/teksilo-core/src/styles/` (+ preset `presets/intui.rs`); default impls `crates/teksilo-widgets/src/styles/`
+- Native mode: `crates/teksilo-platform/src/os_theme.rs` (+ `os_theme/kde.rs`, `os_theme/watch.rs`), `crates/teksilo-app/src/native_theme.rs`
 - Actions/Intents/Shortcuts: `crates/teksilo-core/src/{action,intent,shortcut}.rs`; `IntentKind` derive in `crates/teksilo-macros/src/intent_kind.rs`
 - Drag-and-drop core: `crates/teksilo-core/src/drag_payload.rs`, `drag_state.rs`, `widget_tree/drag_drop_impl.rs`
 

.claude/skills/teksilo/SKILL.md

@@ -36,7 +36,7 @@ thread, persistence, file dialogs, the clipboard, notifications, menus, a
 terminal, a web view), run `cargo teksilo search "<what you need>"`. Several
 subsystems are off by default and invisible until you look: the async executor
 and its Tokio / async-std adapters (`teksilo-tokio`, `teksilo-async-std`),
-`web-view`, `terminal`, the automation bridge, the Material 3 / Fluent / macOS
+`web-view`, `terminal`, the automation bridge, the Material 3 / Fluent / macOS / KDE
 theme presets, and the separate `teksilo-charts` and `teksilo-scene` crates.
 
 ## Sources of truth — when they disagree, trust in THIS order
@@ -55,10 +55,11 @@ theme presets, and the separate `teksilo-charts` and `teksilo-scene` crates.
 If the version this app resolves (`cargo teksilo status`, or `Cargo.lock`) is
 not the one this copy ships with, the skill was installed for another release.
 Say so, and refresh it before relying on the prose: `cargo install
-cargo-teksilo --version <the app's teksilo version>`, then `cargo teksilo agent
-install claude --force` (add `--user` for a copy under the home directory).
-`cargo teksilo status` flags a user-scope copy that differs from the installed
-tool's.
+cargo-teksilo --version <the app's teksilo version> --locked`, then `cargo
+teksilo update` (`--user` for a copy under the home directory). `cargo teksilo
+status` flags a tool older than the app, a user-scope copy that differs from the
+installed tool's, and an automation server or formatter on PATH from an older
+release, each with the command that fixes it.
 
 ## The tool: `cargo teksilo`
 
@@ -96,6 +97,7 @@ cargo teksilo show docs/scroll-area.md      # read a search result in full, offl
 cargo teksilo show docs/scroll-area.md --lines 166-172
 cargo teksilo probe install                         # materialise the Python automation harness
 cargo teksilo init                         # the harness, plus a teksilo brief for every agent here
+cargo teksilo update                       # bring everything installed to this release
 ```
 
 - **`symbol`** replaces reading the widget source by hand. It emits the type's
@@ -132,6 +134,18 @@ cargo teksilo init                         # the harness, plus a teksilo brief f
   `--user` supports `claude`, `vibe`, and `opencode`; it writes no project harness.
   `--force` replaces conflicting generated files. Shared-file text outside the
   managed region is preserved. `agent list` reports supported targets and state.
+- **`update`** brings what is already installed to this release: the harness,
+  the project's agent instructions, and the `teksilo-automation-mcp` and
+  `cargo-teksilo-fmt` binaries on PATH (through `cargo install`). It lists the
+  changes and asks first; `-y` skips the question, `-i` asks per action and
+  shows the equivalent command, `--dry-run` only lists. `--agent` limits it to
+  the project's agent instructions, `--user` updates the ones under the home
+  directory instead. It installs nothing that is not there, and refuses when
+  the tool is older than the app. You cannot answer its question: run it with
+  `--dry-run`, show the user the list, and run it again with `-y` once they
+  agree. Afterwards, ask them to restart your session (and the MCP server, if
+  `teksilo-automation-mcp` was replaced), since this one still has the old
+  instructions.
 - **`model fetch`** explicitly downloads the semantic search model. Search uses
   BM25 until it is cached; a lookup never starts a download.
 - **`status --json`** reports the resolved version and installed tooling.

.claude/skills/teksilo/reference/automation.md

@@ -53,6 +53,9 @@ Install the server matching the framework version your app pins:
 cargo install teksilo-automation-mcp --version <the teksilo version your app pins>
 ```
 
+`cargo teksilo status` says when the server on PATH is from an older or another
+release, and `cargo teksilo update` replaces it.
+
 Then:
 
 ```bash

.claude/skills/teksilo/reference/teksilo_app_guide.md

@@ -67,7 +67,7 @@ opt-outs:
 | `async` / `tokio` / `async-std` | Optional main-thread async executor (`.install_async()`, `ctx.spawn_local`, `spawn_blocking`). `tokio` / `async-std` imply `async` and add the reactor (`.install_async_tokio()` / `.install_async_async_std()`) so a handler can `.await` that runtime's futures: timers, sockets, `reqwest`. Off by default. See `cargo teksilo show docs/async.md` |
 | `terminal` | Embeddable `Terminal` widget: a real shell over a PTY. Off by default |
 | `automation` | Debug-only automation bridge (`.install_automation_bridge_in_debug()`) for agents and tests. Off by default |
-| `theme-material3` / `theme-fluent` / `theme-macos` | Material 3, Fluent (Windows 11) and macOS Aqua presets, as `material3::light()` etc. from the prelude |
+| `theme-material3` / `theme-fluent` / `theme-macos` / `theme-kde` | Material 3, Fluent (Windows 11), macOS Aqua and KDE Plasma (Breeze) presets, as `material3::light()` etc. from the prelude. `theme-kde` also adds `.native_theme_kde()` (see Theming). Its font features (`bundled-fonts`, `system-fonts`) are not forwarded: depend on `teksilo-theme-kde` directly for Plasma's own faces |
 | `telemetry` | Privacy-respecting analytics wiring + `PrivacySettings` widget |
 | `fonts-cjk-sc` / `fonts-thai` / `fonts-all` / `system-emoji` | Extra bundled script fonts / runtime color-emoji fallback |
 
@@ -363,6 +363,17 @@ let theme = intui::light();   // or intui::dark()
 `ctx.set_theme(...)` updates an internal signal and dirty-marks nodes — no rebuild, and
 focus/scroll/interaction state survive.
 
+**Following the desktop.** `.theme_mode(ThemeMode::FollowSystem)` picks Int UI light or
+dark by the desktop's preference; `ThemeMode::Native` adopts the desktop's own colours
+(accent, surfaces, selection; on a KDE Plasma session its colour scheme) in Int UI's
+shapes, and both track the desktop while the app runs. A handler
+switches to Native with `ctx.follow_system_theme()` and back with `ctx.set_theme(..)`. With
+the `theme-kde` feature, `.native_theme_kde()` (the prelude's `TeksiloAppBuilderKdeExt`)
+makes a window *built* in Native mode on a Breeze desktop use the desktop's fonts and
+animation speed and Breeze's shapes as well; any other desktop keeps Int UI in its colours. A theme change after the window is built is a
+re-tint: the shapes stay those it was built with. `.native_theme(|request| ..)` installs
+a factory of your own. Reference: `cargo teksilo show docs/native-theme.md`.
+
 **Variants** select a widget's look (Tier 1):
 
 ```rust,ignore

.github/workflows/ci.yml

@@ -151,6 +151,18 @@ jobs:
       - name: Test
         run: cargo test --workspace
 
+      # teksilo-theme-kde's two font features are off by default and nothing
+      # in the workspace turns them on, so the workspace steps above build and
+      # test only the build without them. `bundled-fonts` embeds the faces and
+      # adds `font_registrar()`, `system-fonts` only names the families. With
+      # both on, every item and test gated on either feature compiles and
+      # runs (tests/fonts.rs checks the registrar's faces under the first);
+      # the workspace steps cover the ones gated on neither.
+      - name: Check and test teksilo-theme-kde (bundled-fonts, system-fonts)
+        run: |
+          cargo check -p teksilo-theme-kde --all-targets --features bundled-fonts,system-fonts
+          cargo test -p teksilo-theme-kde --features bundled-fonts,system-fonts
+
       # cargo-teksilo's `semantic` feature (search embeddings) pulls in
       # fastembed -> ort (ONNX Runtime) plus the onig_sys / esaxx-rs C/C++ sys
       # crates. If that build ever breaks on some platform, `cargo install
@@ -666,6 +678,96 @@ jobs:
           fi
           echo "package size within guard"
 
+      # The same guard for the two KDE crates. teksilo-theme-kde embeds
+      # Plasma's Noto Sans and Hack under `fonts/` (about 5.6 MB of faces,
+      # 3.2 MiB packaged), so a face added there moves it towards crates.io's
+      # 10 MB limit; the fallback, should it ever pass the guard, is Latin
+      # subsets of the faces. teksilo-kde-scheme is small, and is measured
+      # because it is packaged here anyway: teksilo-theme-kde depends on it at
+      # the same version, which crates.io has only once it is published, so
+      # the two are packaged together.
+      #
+      # `--exclude-lockfile`: cargo resolves a package's Cargo.lock against
+      # the crates.io index, with only the packages named on the command line
+      # supplied locally. On a release tag, where the Release workflow runs
+      # this file before publishing, teksilo-core and the other workspace
+      # crates at the new version are not on crates.io yet, so the resolution
+      # would fail and block every release. The lockfile adds about 40 KB to
+      # the compressed teksilo-theme-kde package, far inside the margin
+      # between the 9 MiB guard and the 10 MB limit.
+      #
+      # The listing then checks what the package holds: every tracked file
+      # under teksilo-theme-kde's `fonts/` (the faces and their licences, which
+      # the OFL and the Hack licence require to travel with the faces), and,
+      # in either crate, no test fixture (teksilo-kde-scheme's vendored Breeze
+      # schemes are LGPL and test-only), no `tools/` and no golden `vectors/`.
+      - name: KDE crates package guard
+        if: matrix.name == 'debug'
+        run: |
+          rm -f target/package/teksilo-theme-kde-*.crate target/package/teksilo-kde-scheme-*.crate
+          cargo package -p teksilo-theme-kde -p teksilo-kde-scheme --no-verify --allow-dirty --exclude-lockfile
+
+          shopt -s nullglob
+          guard_mib=9
+          guard=$((guard_mib * 1024 * 1024))
+          failed=0
+          for name in teksilo-theme-kde teksilo-kde-scheme; do
+            crates=(target/package/"$name"-*.crate)
+            if [ "${#crates[@]}" -ne 1 ]; then
+              echo "::error::expected exactly one $name .crate, found ${#crates[@]}: ${crates[*]}"
+              ls -la target/package/ || true
+              exit 1
+            fi
+            crate="${crates[0]}"
+            bytes=$(( $(wc -c < "$crate") ))
+            mib=$(awk -v b="$bytes" 'BEGIN { printf "%.2f", b / 1048576 }')
+            echo "$crate is ${bytes} bytes (${mib} MiB); guard ${guard_mib} MiB, crates.io limit 10 MB"
+            if [ "$bytes" -gt "$guard" ]; then
+              echo "::error::$name .crate is ${mib} MiB, over the ${guard_mib} MiB guard"
+              failed=1
+            fi
+          done
+
+          theme_list=$(cargo package -p teksilo-theme-kde --list --allow-dirty)
+          scheme_list=$(cargo package -p teksilo-kde-scheme --list --allow-dirty)
+
+          # The expected font files are the tracked ones, so adding or
+          # renaming a face needs no edit here; an emptied `fonts/` would pass
+          # that vacuously, hence the two counts.
+          mapfile -t fonts < <(git ls-files -- crates/teksilo-theme-kde/fonts | sed 's|^crates/teksilo-theme-kde/||')
+          faces=0
+          licences=0
+          for f in "${fonts[@]}"; do
+            case "$f" in
+              *.ttf) faces=$((faces + 1)) ;;
+              *LICENSE*) licences=$((licences + 1)) ;;
+            esac
+            if ! grep -qxF -- "$f" <<< "$theme_list"; then
+              echo "::error::teksilo-theme-kde's package is missing $f"
+              failed=1
+            fi
+          done
+          if [ "$faces" -eq 0 ] || [ "$licences" -eq 0 ]; then
+            echo "::error::crates/teksilo-theme-kde/fonts tracks ${faces} faces and ${licences} licences; expected at least one of each"
+            failed=1
+          fi
+          echo "teksilo-theme-kde packages ${faces} faces and ${licences} licences"
+
+          for name in teksilo-theme-kde teksilo-kde-scheme; do
+            if [ "$name" = teksilo-theme-kde ]; then list=$theme_list; else list=$scheme_list; fi
+            stray=$(grep -E '(^|/)(fixtures|tools|vectors)(/|$)' <<< "$list" || true)
+            if [ -n "$stray" ]; then
+              echo "::error::$name's package carries files that must stay in the repository:"
+              echo "$stray"
+              failed=1
+            fi
+          done
+
+          if [ "$failed" -ne 0 ]; then
+            exit 1
+          fi
+          echo "KDE packages within guard, with their fonts and licences and without fixtures, tools or vectors"
+
       # cargo-teksilo embeds two copies of files that also live elsewhere in
       # the repo, so an app that only depends on the `teksilo` crate — not
       # this checkout — still gets them. Nothing else enforces the copies