feat: add architecture documentation for Clean Architecture overview

Cargo.lock

@@ -2060,7 +2060,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "ctrlc",
  "dirs",
@@ -2084,7 +2084,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-config"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "dirs",
  "k-launcher-domain",
@@ -2096,7 +2096,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-domain"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "serde",
@@ -2104,7 +2104,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-kernel"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "futures",
@@ -2118,7 +2118,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-os-bridge"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "k-launcher-domain",
  "libc",
@@ -2127,7 +2127,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-plugin-host"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "k-launcher-domain",
@@ -2140,7 +2140,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-ui"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "iced",
  "k-launcher-config",
@@ -2153,7 +2153,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-ui-core"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "k-launcher-config",
  "k-launcher-domain",
@@ -2162,7 +2162,7 @@ dependencies = [
 
 [[package]]
 name = "k-launcher-ui-egui"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "eframe",
  "egui",
@@ -3168,7 +3168,7 @@ checksum = "b4596b6d070b27117e987119b4dac604f3c58cfb0b191112e24771b2faeac1a6"
 
 [[package]]
 name = "plugin-apps"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "bincode",
@@ -3186,7 +3186,7 @@ dependencies = [
 
 [[package]]
 name = "plugin-calc"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "evalexpr",
@@ -3196,7 +3196,7 @@ dependencies = [
 
 [[package]]
 name = "plugin-cmd"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "k-launcher-domain",
@@ -3205,7 +3205,7 @@ dependencies = [
 
 [[package]]
 name = "plugin-files"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "async-trait",
  "k-launcher-domain",
@@ -3214,7 +3214,7 @@ dependencies = [
 
 [[package]]
 name = "plugin-url"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "serde",
  "serde_json",

Makefile

@@ -13,6 +13,9 @@ build-egui:
 dev:
 	RUST_LOG=debug cargo run
 
+dev-egui:
+	RUST_LOG=debug cargo run -p k-launcher --features egui --bin k-launcher-egui
+
 check:
 	cargo fmt --all -- --check
 	cargo clippy --workspace -- -D warnings

README.md

@@ -77,6 +77,29 @@ timeout_secs = 5
 
 See [Plugin Development](docs/plugin-development.md) for the full protocol.
 
+## Architecture
+
+Clean Architecture (Domain → Application → Infrastructure → Main):
+
+```
+domain              — pure value types (ResultId, ResultTitle, Score, LaunchAction, SearchResult),
+                      port traits (Plugin, AppLauncher), shared constants
+kernel              — application use case: Kernel orchestrator (fan-out search, sort, truncate)
+config              — TOML config loading with typed errors (ConfigError)
+ui-core             — framework-agnostic UI state machine (LauncherState, Action, Effect)
+ui                  — iced 0.14 rendering adapter
+ui-egui             — egui rendering adapter (optional)
+os-bridge           — UnixAppLauncher (process spawning, terminal detection, clipboard)
+plugin-host         — ExternalPlugin (JSON stdin/stdout protocol with typed PluginError)
+plugins/
+  plugin-apps         — XDG .desktop search, frecency ranking, nucleo fuzzy matching, bincode cache
+  plugin-calc         — evalexpr math evaluator (supports sqrt, sin, cos, ln, pi, e, etc.)
+  plugin-cmd          — shell command runner (> prefix, launches in terminal)
+  plugin-files        — filesystem browser (/ and ~/ paths)
+  plugin-url          — URL detection (external binary, tests the external plugin protocol)
+k-launcher          — entry point: DI wiring, logging, signal handling
+```
+
 ## Docs
 
 - [Installation](docs/install.md)

architecture.mmd

@@ -0,0 +1,81 @@
+---
+title: k-launcher — Clean Architecture
+---
+graph TB
+    subgraph Main["Main (Composition Root)"]
+        BIN["k-launcher<br/><i>DI wiring, logging,<br/>signal handling, --version</i>"]
+        BIN_EGUI["k-launcher-egui<br/><i>Optional egui binary</i>"]
+    end
+
+    subgraph Application["Application Layer"]
+        KERNEL["kernel<br/><i>Kernel orchestrator</i><br/>Fan-out search, sort by score,<br/>truncate to max_results,<br/>catch_unwind per plugin"]
+    end
+
+    subgraph Domain["Domain Layer (0 external deps)"]
+        direction TB
+        subgraph Types["Value Types"]
+            VT_ID["ResultId(String)"]
+            VT_TITLE["ResultTitle(String)"]
+            VT_SCORE["Score(u32)"]
+            VT_ACTION["LaunchAction<br/><i>SpawnProcess, SpawnInTerminal,<br/>OpenPath, CopyToClipboard</i>"]
+            VT_RESULT["SearchResult<br/><i>id, title, description,<br/>icon, score, action</i>"]
+        end
+        subgraph Ports["Port Traits"]
+            P_PLUGIN["Plugin<br/><i>name, search, on_selected,<br/>shutdown</i>"]
+            P_LAUNCHER["AppLauncher<br/><i>execute(LaunchAction)</i>"]
+        end
+        CONSTANTS["constants<br/><i>APP_NAME, APP_TITLE,<br/>CONFIG_FILENAME, LOG_*,<br/>FRECENCY_SNAPSHOT_FILENAME</i>"]
+    end
+
+    subgraph Infrastructure["Infrastructure Layer"]
+        direction TB
+        subgraph UI["UI"]
+            UI_CORE["ui-core<br/><i>LauncherState, Action, Effect</i><br/>Framework-agnostic state machine"]
+            UI_ICED["ui (iced)<br/><i>style, view, update</i><br/>Rendering adapter"]
+            UI_EGUI["ui-egui<br/><i>style, input, render</i><br/>Rendering adapter"]
+        end
+        subgraph Plugins["Plugins (implement Plugin trait)"]
+            PL_APPS["plugin-apps<br/><i>XDG .desktop search</i><br/>Frecency, nucleo fuzzy,<br/>bincode cache"]
+            PL_CALC["plugin-calc<br/><i>evalexpr math</i><br/>sqrt, sin, cos, ln, pi, e"]
+            PL_CMD["plugin-cmd<br/><i>Shell commands</i><br/>> prefix → terminal"]
+            PL_FILES["plugin-files<br/><i>Filesystem browser</i><br/>/ and ~/ paths"]
+            PL_URL["plugin-url<br/><i>URL detection</i><br/>External binary (JSON protocol)"]
+        end
+        subgraph Platform["Platform"]
+            OS_BRIDGE["os-bridge<br/><i>UnixAppLauncher</i><br/>shell, terminal, spawn"]
+            PLUGIN_HOST["plugin-host<br/><i>ExternalPlugin</i><br/>JSON stdin/stdout protocol"]
+            CONFIG["config<br/><i>TOML loading</i><br/>ConfigError, try_load"]
+        end
+    end
+
+    %% Dependency arrows
+    BIN -->|"wires"| Application
+    BIN -->|"wires"| Infrastructure
+    BIN_EGUI -->|"wires"| Application
+    BIN_EGUI -->|"wires"| Infrastructure
+
+    Application -->|"depends on"| Domain
+
+    UI_ICED -->|"delegates to"| UI_CORE
+    UI_EGUI -->|"delegates to"| UI_CORE
+    UI_CORE -->|"uses"| KERNEL
+
+    Plugins -.->|"implements"| P_PLUGIN
+    OS_BRIDGE -.->|"implements"| P_LAUNCHER
+    PLUGIN_HOST -.->|"implements"| P_PLUGIN
+
+    KERNEL -->|"fan-out"| P_PLUGIN
+
+    %% Key data flows
+    UI_CORE ===|"Action → Effect"| KERNEL
+    PL_APPS ===|"frecency log"| CONSTANTS
+
+    classDef domain fill:#1a1a2e,stroke:#e94560,color:#fff
+    classDef app fill:#16213e,stroke:#0f3460,color:#fff
+    classDef infra fill:#0f3460,stroke:#533483,color:#fff
+    classDef binary fill:#533483,stroke:#e94560,color:#fff
+
+    class Domain domain
+    class Application app
+    class Infrastructure infra
+    class Main binary

contrib/PKGBUILD

@@ -3,7 +3,7 @@
 # Copy this file as PKGBUILD to your AUR repo
 
 pkgname=k-launcher
-pkgver=0.2.0
+pkgver=0.2.1
 pkgrel=1
 pkgdesc='Wayland command palette launcher with fuzzy search, frecency, and plugin support'
 arch=('x86_64')

crates/k-launcher-config/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-config"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/k-launcher-config/src/types.rs

@@ -93,7 +93,10 @@ pub struct AppearanceCfg {
     pub row_radius: f32,
     pub placeholder: String,
     pub selected_row_rgba: Rgba,
+    pub selected_text_rgba: Rgba,
+    pub selected_description_rgba: Rgba,
     pub unselected_row_rgba: Rgba,
+    pub text_rgba: Rgba,
     pub description_rgba: Rgba,
     pub no_results_rgba: Rgba,
     pub error_rgba: Rgba,
@@ -113,7 +116,10 @@ impl Default for AppearanceCfg {
             row_radius: 4.0,
             placeholder: "Search apps, type > for commands, = for math".to_string(),
             selected_row_rgba: Rgba::new(229.0, 125.0, 33.0, 1.0),
+            selected_text_rgba: Rgba::new(255.0, 255.0, 255.0, 1.0),
+            selected_description_rgba: Rgba::new(240.0, 240.0, 240.0, 0.9),
             unselected_row_rgba: Rgba::new(255.0, 255.0, 255.0, 0.07),
+            text_rgba: Rgba::new(255.0, 255.0, 255.0, 1.0),
             description_rgba: Rgba::new(210.0, 215.0, 230.0, 1.0),
             no_results_rgba: Rgba::new(180.0, 180.0, 200.0, 0.5),
             error_rgba: Rgba::new(255.0, 80.0, 80.0, 1.0),

crates/k-launcher-domain/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-domain"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [dependencies]

crates/k-launcher-kernel/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-kernel"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [dependencies]

crates/k-launcher-os-bridge/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-os-bridge"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [dependencies]

crates/k-launcher-os-bridge/src/terminal.rs

@@ -9,6 +9,10 @@ struct KnownTerminal {
 }
 
 const KNOWN_TERMINALS: &[KnownTerminal] = &[
+    KnownTerminal {
+        bin: "ghostty",
+        exec_flag: "-e",
+    },
     KnownTerminal {
         bin: "foot",
         exec_flag: "-e",

crates/k-launcher-plugin-host/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-plugin-host"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/k-launcher-ui-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-ui-core"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [dependencies]

crates/k-launcher-ui-egui/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-ui-egui"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/k-launcher-ui-egui/src/render.rs

@@ -43,14 +43,25 @@ pub fn render_result_list(
 }
 
 fn render_result_row(ui: &mut Ui, result: &SearchResult, is_selected: bool, cfg: &AppearanceCfg) {
+    let title_color = if is_selected {
+        to_color32(&cfg.selected_text_rgba)
+    } else {
+        to_color32(&cfg.text_rgba)
+    };
+    let desc_color = if is_selected {
+        to_color32(&cfg.selected_description_rgba)
+    } else {
+        to_color32(&cfg.description_rgba)
+    };
+
     style::result_row_frame(is_selected, cfg).show(ui, |ui| {
         ui.set_width(ui.available_width());
         ui.horizontal(|ui| {
             ui.add_space(8.0);
             ui.vertical(|ui| {
-                ui.label(result.title.as_str());
+                ui.colored_label(title_color, result.title.as_str());
                 if let Some(desc) = &result.description {
-                    ui.colored_label(to_color32(&cfg.description_rgba), desc.as_ref());
+                    ui.colored_label(desc_color, desc.as_ref());
                 }
             });
         });

crates/k-launcher-ui/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher-ui"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/k-launcher-ui/src/view.rs

@@ -113,9 +113,12 @@ fn result_row<'a>(
     };
 
     container(
-        row![result_icon(&result.icon, cfg), title_column(result, cfg)]
+        row![
-            .spacing(style::CONTENT_SPACING)
+            result_icon(&result.icon, cfg),
-            .align_y(iced::Center),
+            title_column(result, is_selected, cfg)
+        ]
+        .spacing(style::CONTENT_SPACING)
+        .align_y(iced::Center),
     )
     .width(Length::Fill)
     .padding(style::ROW_PADDING)
@@ -138,17 +141,35 @@ fn result_icon<'a>(icon_path: &'a Option<Arc<str>>, cfg: &AppearanceCfg) -> Elem
     }
 }
 
-fn title_column<'a>(result: &'a SearchResult, cfg: &AppearanceCfg) -> Element<'a, Message> {
+fn title_column<'a>(
+    result: &'a SearchResult,
+    is_selected: bool,
+    cfg: &AppearanceCfg,
+) -> Element<'a, Message> {
+    let title_color = if is_selected {
+        style::rgba(&cfg.selected_text_rgba)
+    } else {
+        style::rgba(&cfg.text_rgba)
+    };
+    let desc_color = if is_selected {
+        style::rgba(&cfg.selected_description_rgba)
+    } else {
+        style::rgba(&cfg.description_rgba)
+    };
+
     if let Some(desc) = &result.description {
         column![
-            text(result.title.as_str()).size(cfg.title_size),
+            text(result.title.as_str())
-            text(desc.as_ref())
+                .size(cfg.title_size)
-                .size(cfg.desc_size)
+                .color(title_color),
-                .color(style::rgba(&cfg.description_rgba)),
+            text(desc.as_ref()).size(cfg.desc_size).color(desc_color),
         ]
         .into()
     } else {
-        text(result.title.as_str()).size(cfg.title_size).into()
+        text(result.title.as_str())
+            .size(cfg.title_size)
+            .color(title_color)
+            .into()
     }
 }
 

crates/k-launcher/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "k-launcher"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 default-run = "k-launcher"
 

crates/plugins/plugin-apps/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "plugin-apps"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/plugins/plugin-calc/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "plugin-calc"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/plugins/plugin-cmd/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "plugin-cmd"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/plugins/plugin-files/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "plugin-files"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

crates/plugins/plugin-url/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "plugin-url"
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 
 [lib]

man/k-launcher.1

@@ -1,4 +1,4 @@
-.TH K\-LAUNCHER 1 "2026-07-24" "k-launcher 0.2.0" "User Commands"
+.TH K\-LAUNCHER 1 "2026-07-24" "k-launcher 0.2.1" "User Commands"
 .SH NAME
 k\-launcher \- Wayland command palette launcher
 .SH SYNOPSIS