feat(flavor): komorebi for KDE, with rules written from its source

Flavor::Kde is the flavor of a Linux host. Its rules are checked against a log and events
of komorebi for KDE's in-memory desktop, but not against a real desktop, so an analysis
of a KDE session says so. There are no ghost tiles for it yet.
This commit is contained in:
LGUG2Z committed 2026-10-28 22:50:40 -07:00
1 parent 1d80eb0272
commit bbd374ae24
8 files changed
+637 -4

No files matched your search

@@ -146,6 +146,7 @@ pub fn of(flavor: Flavor) -> &'static Catalog {
match flavor {
Flavor::Macos => &MAC,
Flavor::Windows => &WINDOWS,
Flavor::Kde => &KDE,
}
}
@@ -776,6 +777,7 @@ pub fn skew(flavor: Flavor, versions: &[KomorebiVersion], root: Option<&std::pat
match flavor {
Flavor::Macos => "KOMOREBI_MAC_SRC",
Flavor::Windows => "KOMOREBI_WINDOWS_SRC",
Flavor::Kde => "KOMOREBI_KDE_SRC",
}
));
}
@@ -0,0 +1,471 @@
//! komorebi for KDE, as it describes itself.
//!
//! [`KdeRules`] is the [`Rules`] of [`Flavor::Kde`]. It keeps the defaults of
//! [`Rules::window_is_unreadable`] and answers `false` to [`Rules::verified`]: it was written from
//! komorebi for KDE's source, and has not been checked against a recording of it. What the rules
//! rely on:
//!
//! - A window event serializes as `{"type": "Show", "content": [{"type": "KWin", "content":
//! "WindowAdded"}, <window>]}`, where the first part is the compositor signal the bridge script
//! heard (`{"type": "Manual", ...}` is komorebi making one up) and the window is `{"id": ...,
//! "rect": ..., "details": {"title": ..., "exe": ..., "class": ..., "path": ...}}`. `Manage` and
//! `Unmanage` carry the window alone, and a `WorkspaceChange` carries a monitor id and a
//! workspace index in the place of the window. There is no process id.
//! - A monitor notification is a one-entry object (`{"Resize": 0}`,
//! `{"DisplayConnectionChange": 0}`), or the bare string `"Wake"`.
//! - A window in the `State` is known by its `id`, a number komorebi gave it (not KWin's UUID).
//! - The log has a header line for each handler, `processing event: <Name> for window <id> with
//! notification <notification>` inside a `handle_event` span, and `processing command: <Name>`
//! inside a `process_command` span, where a command ends with `processed command: <Name>`. An
//! event's handler is timed by a debug line, `handled <Name> in <time>`.
//! - komorebi hides a window by moving it to the virtual desktop it calls `komorebi-park`, and
//! does not move it, so a hidden window is not told from a visible one by where it is.
use super::BlockHeader;
use super::Flavor;
use super::Rules;
use crate::analysis::blocks::Block;
use crate::analysis::blocks::BlockKind;
use crate::analysis::catalog::Role;
use crate::analysis::classify::Class;
use crate::analysis::events::EventInfo;
use crate::analysis::events::EventRecord;
use crate::analysis::events::Family;
use crate::analysis::logparse::Line;
use crate::analysis::state::Monitor;
use crate::analysis::state::Rect;
use serde_json::Value;
/// The [`Rules`] of komorebi for KDE: what its events, `State`, log and modules say.
///
/// A unit struct with no state. [`Flavor::rules`] returns a reference to one for
/// [`Flavor::Kde`].
pub struct KdeRules;
/// The names komorebi for KDE gives the events that are about a window, or a workspace.
const WINDOW_MANAGER_EVENTS: [&str; 18] = [
"FocusChange",
"Show",
"Destroy",
"Minimize",
"Restore",
"TitleUpdate",
"FullscreenChange",
"OutputChange",
"MaximizeChange",
"Manage",
"Unmanage",
"MoveStart",
"MoveEnd",
"ResizeStart",
"ResizeEnd",
"ResizeStep",
"WorkspaceChange",
"WorkspaceMove",
];
/// The names of the notifications about the monitors.
const MONITOR_NOTIFICATIONS: [&str; 3] = ["Resize", "DisplayConnectionChange", "Wake"];
const GEOMETRY_EVENTS: [&str; 4] = ["MoveStart", "MoveEnd", "ResizeStart", "ResizeEnd"];
const EVENT_HEADER: &str = "processing event: ";
const COMMAND_HEADER: &str = "processing command: ";
const COMMAND_FINISHED: &str = "processed command: ";
const EVENT_FINISHED: &str = "handled ";
/// `Show for window 12 with notification WindowAdded`
fn parse_event_header(rest: &str) -> (String, Option<u32>, Option<String>) {
let (name, tail) = rest.split_once(" for window ").unwrap_or((rest, ""));
let (id, notification) = tail.split_once(" with notification ").unwrap_or((tail, ""));
(
name.trim().to_string(),
id.trim().parse().ok(),
Some(notification.trim().to_string()).filter(|text| !text.is_empty()),
)
}
impl Rules for KdeRules {
fn flavor(&self) -> Flavor {
Flavor::Kde
}
fn verified(&self) -> bool {
false
}
fn classify_monitor(&self, event: &EventRecord) -> (Class, &'static str) {
if event.info.name == "Wake" {
(
Class::Lock,
"the machine woke up or the screen was unlocked",
)
} else {
(Class::Monitor, "a display changed")
}
}
fn window_id(&self, window: &Value) -> Option<u64> {
window.get("id")?.as_u64()
}
fn hides_windows_by_position(&self) -> bool {
false
}
fn describe_event(&self, event: &Value) -> EventInfo {
let unknown = |name: &str| EventInfo {
family: Family::Unknown,
name: name.to_string(),
notification: None,
pid: None,
window_id: None,
exe: None,
argument: None,
};
// a monitor notification is a one-entry object: {"Resize": 0}
if event.get("type").is_none()
&& let Some(object) = event.as_object()
&& object.len() == 1
&& let Some((name, value)) = object.iter().next()
{
return EventInfo {
family: Family::Monitor,
name: name.clone(),
argument: Some(crate::analysis::events::compact(value)),
..unknown(name)
};
}
// a unit-variant command is a bare string, and so is `Wake`, the one monitor notification
// with nothing to say but itself
if let Some(name) = event.as_str() {
let family = if MONITOR_NOTIFICATIONS.contains(&name) {
Family::Monitor
} else {
Family::Command
};
return EventInfo {
family,
..unknown(name)
};
}
let Some(name) = event.get("type").and_then(Value::as_str) else {
return unknown("unreadable");
};
let content = event.get("content");
if WINDOW_MANAGER_EVENTS.contains(&name) {
// `Manage` and `Unmanage` carry the window alone; the others an array that starts
// with the notification, and then has the window or the monitor
let parts = content.and_then(Value::as_array);
let at = |index: usize| parts.and_then(|parts| parts.get(index));
let window = match parts {
Some(_) => at(1).filter(|part| part.is_object()),
None => content.filter(|part| part.is_object()),
};
return EventInfo {
family: Family::WindowManager,
name: name.to_string(),
notification: at(0)
.and_then(|notification| notification.get("content"))
.and_then(Value::as_str)
.map(str::to_string),
pid: None,
window_id: window
.and_then(|window| window.get("id"))
.and_then(Value::as_u64)
.and_then(|id| u32::try_from(id).ok()),
exe: window
.and_then(|window| window.get("details"))
.and_then(|details| details.get("exe"))
.and_then(Value::as_str)
.map(str::to_string),
argument: None,
};
}
EventInfo {
family: Family::Command,
name: name.to_string(),
argument: content
.filter(|value| !value.is_null())
.map(crate::analysis::events::compact),
..unknown(name)
}
}
fn is_geometry_event(&self, name: &str) -> bool {
GEOMETRY_EVENTS.contains(&name)
}
fn classify_window_manager(&self, event: &EventRecord) -> (Class, &'static str) {
match event.info.name.as_str() {
"FocusChange" => (Class::Focus, "focus moved"),
"Show" | "Destroy" | "Minimize" | "Restore" | "Manage" | "Unmanage" | "TitleUpdate"
| "FullscreenChange" | "MaximizeChange" | "OutputChange" => {
(Class::Lifecycle, "a window or its state changed")
}
name if GEOMETRY_EVENTS.contains(&name) => (
Class::Drag,
"the user moved or resized a window with the pointer",
),
"ResizeStep" => (
Class::Drag,
"the user is part way through resizing a window",
),
"WorkspaceChange" | "WorkspaceMove" => (Class::Lock, "a virtual desktop changed"),
_ => (Class::Other, "not a known kind of event"),
}
}
/// Never: komorebi for KDE hides a window by putting it on another virtual desktop, and leaves
/// where it is alone.
fn is_hidden_position(&self, _rect: &Rect, _monitor: &Monitor) -> bool {
false
}
fn block_header(&self, line: &Line, _open: Option<&Block>) -> Option<BlockHeader> {
match line.root_span() {
Some("handle_event") if line.message.starts_with(EVENT_HEADER) => {
let (name, window_id, notification) =
parse_event_header(&line.message[EVENT_HEADER.len()..]);
Some(BlockHeader {
kind: BlockKind::Event,
name,
pid: None,
window_id,
notification,
})
}
Some("process_command") if line.message.starts_with(COMMAND_HEADER) => {
Some(BlockHeader {
kind: BlockKind::Command,
name: line.message[COMMAND_HEADER.len()..].trim().to_string(),
pid: None,
window_id: None,
notification: None,
})
}
_ => None,
}
}
fn is_block_end(&self, line: &Line, kind: BlockKind) -> bool {
match kind {
BlockKind::Command => line.message.starts_with(COMMAND_FINISHED),
BlockKind::Event => {
line.target.as_deref() == Some("komorebi::process_event")
&& line.message.starts_with(EVENT_FINISHED)
}
}
}
fn role(&self, target: &str) -> Role {
crate::analysis::catalog::role_in(ROLES, target)
}
fn slow_handler_cause(&self) -> &'static str {
"slow calls to KWin over D-Bus, or waiting for the lock another handler held"
}
}
/// The modules of komorebi for KDE and what each does, for [`Rules::role`].
///
/// Each entry is `(module, summary, changes_state_silently)`, as in the Mac and Windows tables. A
/// target is matched to the entry with the longest module that is a prefix of it.
pub const ROLES: &[(&str, &str, bool)] = &[
(
"komorebi::process_event",
"handles events from the compositor one at a time under the window-manager lock; a notification is sent to subscribers after a handled event about a managed window",
false,
),
(
"komorebi::process_command",
"handles commands from komorebic or a hotkey one at a time under the lock",
false,
),
(
"komorebi::window_manager_event_listener",
"receives the bridge script's events and queues them for the event handler",
false,
),
(
"komorebi::window_manager",
"window-manager operations, called from the handlers",
false,
),
(
"komorebi::workspace",
"operations on a workspace's containers: layout, focus, adding and removing",
false,
),
(
"komorebi::container",
"operations on a container and its stacked windows",
false,
),
(
"komorebi::monitor_reconciliator",
"reacts to outputs connecting, disconnecting and resizing, and to a wake",
false,
),
(
"komorebi::monitor",
"operations on a monitor and its workspaces",
false,
),
(
"komorebi::window",
"operations on one window, through the backend",
false,
),
(
"komorebi::reconcile",
"brings komorebi's state and KWin's windows back into agreement",
false,
),
(
"komorebi::kwin",
"talks to the KWin bridge script over D-Bus; a failure here is KWin's or the script's, not the layout's",
false,
),
(
"komorebi::backend",
"what komorebi needs from a compositor, behind one trait",
false,
),
(
"komorebi::desktop",
"virtual desktops, including the parking desktop that hidden windows are put on",
false,
),
(
"komorebi::border_manager",
"draws window borders through a KWin effect; cosmetic, never changes the layout state",
false,
),
(
"komorebi::animation",
"animates window moves through a KWin effect",
false,
),
(
"komorebi::transparency_manager",
"sets how see-through unfocused windows are",
false,
),
(
"komorebi::static_config",
"loads and applies komorebi.json",
false,
),
("komorebi::theme_manager", "applies border themes", false),
];
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
fn describe(event: &Value) -> EventInfo {
KdeRules.describe_event(event)
}
#[test]
fn a_window_event_has_its_window_program_and_notification() {
let info = describe(&json!({
"type": "Show",
"content": [
{"type": "KWin", "content": "WindowAdded"},
{"id": 12, "rect": {"left": 0, "top": 0, "right": 10, "bottom": 10},
"details": {"title": "t", "exe": "konsole", "class": "org.kde.konsole", "path": "/usr/bin/konsole"}}
]
}));
assert_eq!(info.family, Family::WindowManager);
assert_eq!(info.name, "Show");
assert_eq!(info.notification.as_deref(), Some("WindowAdded"));
assert_eq!(info.pid, None);
assert_eq!(info.window_id, Some(12));
assert_eq!(info.exe.as_deref(), Some("konsole"));
assert_eq!(info.summary(), "Show konsole window 12 WindowAdded");
}
#[test]
fn manage_carries_the_window_alone_and_a_workspace_change_has_none() {
let manage = describe(&json!({
"type": "Manage",
"content": {"id": 7, "details": {"exe": "dolphin"}}
}));
assert_eq!(manage.family, Family::WindowManager);
assert_eq!(manage.window_id, Some(7));
assert_eq!(manage.exe.as_deref(), Some("dolphin"));
let change = describe(&json!({
"type": "WorkspaceChange",
"content": [{"type": "KWin", "content": "WorkspaceChanged"}, 1, 2]
}));
assert_eq!(change.family, Family::WindowManager);
assert_eq!(change.notification.as_deref(), Some("WorkspaceChanged"));
assert_eq!(change.window_id, None);
}
#[test]
fn commands_carry_their_argument() {
let info = describe(&json!({"type": "FocusWorkspaceNumber", "content": 2}));
assert_eq!(info.family, Family::Command);
assert_eq!(info.argument.as_deref(), Some("2"));
assert_eq!(describe(&json!("Retile")).family, Family::Command);
}
#[test]
fn monitor_notifications_are_objects_and_a_bare_wake() {
let info = describe(&json!({"DisplayConnectionChange": 0}));
assert_eq!(info.family, Family::Monitor);
assert_eq!(info.name, "DisplayConnectionChange");
let wake = describe(&json!("Wake"));
assert_eq!(wake.family, Family::Monitor);
assert_eq!(wake.name, "Wake");
}
#[test]
fn nonsense_is_unknown_not_a_panic() {
assert_eq!(describe(&json!(12)).family, Family::Unknown);
assert_eq!(describe(&json!({"a": 1, "b": 2})).family, Family::Unknown);
assert_eq!(describe(&json!({"type": 3})).family, Family::Unknown);
}
#[test]
fn a_header_line_is_read_into_its_parts() {
assert_eq!(
parse_event_header("Show for window 12 with notification WindowAdded"),
(
"Show".to_string(),
Some(12),
Some("WindowAdded".to_string())
)
);
}
#[test]
fn windows_are_not_hidden_by_position() {
assert!(!KdeRules.hides_windows_by_position());
assert!(!KdeRules.verified());
}
#[test]
fn roles_are_found_by_the_longest_module_prefix() {
let role = |target: &str| KdeRules.role(target);
assert!(role("komorebi::kwin::bridge").summary.contains("KWin"));
assert!(
role("komorebi::monitor_reconciliator")
.summary
.contains("outputs")
);
assert_eq!(role("komorebi::brand_new").summary, "komorebi internals");
}
}
+9 -2
View File
@@ -94,6 +94,7 @@
//! [`Family`]: super::events::Family
//! [`Family::Unknown`]: super::events::Family::Unknown
pub mod kde;
pub mod mac;
pub mod windows;
@@ -189,14 +190,16 @@ pub enum Flavor {
Macos,
/// komorebi for Windows.
Windows,
/// komorebi for KDE Plasma.
Kde,
}
impl Flavor {
/// Returns the flavor of the komorebi that runs on this machine: there is one per OS, and a
/// recorder watches the one on its own host.
///
/// This is [`Flavor::Windows`] when the crate is built for Windows and [`Flavor::Macos`] for
/// every other target, including the `unsupported` host. Use it to say which komorebi a
/// This is [`Flavor::Windows`] when the crate is built for Windows, [`Flavor::Kde`] when it is built
/// for Linux and [`Flavor::Macos`] for every other target, including the `unsupported` host. Use it to say which komorebi a
/// recording made *here* is of; to read a session, use the flavor in its manifest.
///
/// # Example
@@ -210,6 +213,8 @@ impl Flavor {
pub fn of_host() -> Self {
if cfg!(windows) {
Flavor::Windows
} else if cfg!(target_os = "linux") {
Flavor::Kde
} else {
Flavor::Macos
}
@@ -239,6 +244,7 @@ impl Flavor {
match self {
Flavor::Macos => &mac::MacRules,
Flavor::Windows => &windows::WindowsRules,
Flavor::Kde => &kde::KdeRules,
}
}
@@ -251,6 +257,7 @@ impl Flavor {
match self {
Flavor::Macos => "macOS",
Flavor::Windows => "Windows",
Flavor::Kde => "KDE",
}
}
}
+3
View File
@@ -236,6 +236,9 @@ impl Analysis {
/// Returns an error when a state of the recording cannot be read.
pub fn ghost_tiles(&self) -> eyre::Result<Vec<GhostTile>> {
let (platform, seen) = match self.flavor() {
// ghost tiles are found by probing windows (Windows) or by looking at the video (Mac);
// neither is written for KDE yet
Flavor::Kde => return Ok(Vec::new()),
Flavor::Windows => (Platform::Windows, self.sightings_by_probe()?),
Flavor::Macos => (Platform::Macos, self.sightings_by_frame()?),
};
+4
View File
@@ -1176,6 +1176,10 @@ pub fn default_code_root(flavor: Flavor) -> Option<PathBuf> {
"KOMOREBI_WINDOWS_SRC",
option_env!("KOMOREBI_WINDOWS_ROOT").map(PathBuf::from),
),
Flavor::Kde => (
"KOMOREBI_KDE_SRC",
option_env!("KOMOREBI_KDE_ROOT").map(PathBuf::from),
),
};
[variable, "KOMOREBI_SOURCE"]
+3 -1
View File
@@ -40,7 +40,9 @@ impl Platform {
pub fn of(flavor: Flavor) -> Self {
match flavor {
Flavor::Windows => Self::Windows,
Flavor::Macos => Self::Macos,
// komorebi for KDE has no rule file here yet, and no ghost tiles are found for it
// (see `Analysis::ghost_tiles`), so nothing asks for the platform of one
Flavor::Macos | Flavor::Kde => Self::Macos,
}
}
@@ -99,7 +99,7 @@ pub fn log_file_name(date: NaiveDate) -> String {
#[must_use]
pub fn log_dir_candidates(flavor: Flavor, data_dir: &Path, temp_dir: &Path) -> Vec<PathBuf> {
match flavor {
Flavor::Macos => vec![data_dir.to_path_buf()],
Flavor::Macos | Flavor::Kde => vec![data_dir.to_path_buf()],
Flavor::Windows => vec![temp_dir.to_path_buf(), data_dir.to_path_buf()],
}
}
+144
View File
@@ -0,0 +1,144 @@
//! A session recorded against komorebi for KDE, read end to end through the real commands.
//!
//! The command lines of the log and the commands' events are what a recording of komorebi for KDE
//! running against its in-memory desktop (`komorebi --fake-backend`) contained. The window events
//! are written from komorebi for KDE's source, because that run has no windows: no recording of a
//! real desktop has been read yet, and the rules say so (`verified` is `false`).
use komorebi_recorder::analysis::flavor::Flavor;
use komorebi_recorder::testkit::SessionBuilder;
use serde_json::Value;
use serde_json::json;
use std::process::Command;
fn run(args: &[&str]) -> Value {
let output = Command::new(env!("CARGO_BIN_EXE_komorebi-recorder"))
.args(args)
.output()
.expect("run komorebi-recorder");
assert!(
output.status.success(),
"{args:?} failed: {}",
String::from_utf8_lossy(&output.stderr)
);
serde_json::from_slice(&output.stdout).expect("json")
}
/// The spans komorebi for KDE opens for a command and for an event.
const COMMAND: &str = "process_command: komorebi::process_command:";
const EVENT: &str = "handle_event: komorebi::process_event:";
fn window(id: u64, exe: &str) -> Value {
json!({
"id": id,
"rect": {"left": 0, "top": 0, "right": 960, "bottom": 1040},
"details": {"title": "a title", "exe": exe, "class": exe, "path": format!("/usr/bin/{exe}")}
})
}
fn session(name: &str) -> String {
let builder = SessionBuilder::new(name)
.flavor(Flavor::Kde)
.log(
1.0,
"INFO",
&format!("{COMMAND} processing command: Retile"),
)
.log(
1.01,
"INFO",
&format!("{COMMAND} processed command: Retile"),
)
.event(1.02, json!({"type": "Retile"}), None)
.log(
2.0,
"INFO",
&format!("{EVENT} processing event: Show for window 12 with notification WindowAdded"),
)
.log(
2.005,
"INFO",
"handle_event: komorebi::workspace: adding window",
);
let (session, _) = builder
.event(
2.01,
json!({"type": "Show", "content": [{"type": "KWin", "content": "WindowAdded"}, window(12, "konsole")]}),
None,
)
.log(
5.0,
"INFO",
&format!("{EVENT} processing event: MoveEnd for window 12 with notification InteractiveMoveFinished"),
)
.event(
5.02,
json!({"type": "MoveEnd", "content": [{"type": "KWin", "content": "InteractiveMoveFinished"}, window(12, "konsole")]}),
None,
)
.event(7.0, json!("Wake"), None)
.event(8.0, json!({"DisplayConnectionChange": 0}), None)
.build();
session.dir.display().to_string()
}
#[test]
fn events_are_read_with_their_window_and_program() {
let dir = session("kde-flavor-events");
let answer = run(&["events", &dir, "--json"]);
let events = answer["data"]["events"].as_array().expect("events");
assert_eq!(events.len(), 5);
assert_eq!(events[0]["name"], "Retile");
assert_eq!(events[0]["family"], "command");
let show = &events[1];
assert_eq!(show["name"], "Show");
assert_eq!(show["family"], "window-manager");
assert_eq!(show["window_id"], 12);
assert_eq!(show["exe"], "konsole");
assert_eq!(show["notification"], "WindowAdded");
assert_eq!(show["class"], "lifecycle");
assert_eq!(events[2]["name"], "MoveEnd");
assert_eq!(events[2]["class"], "drag");
// a wake is a notification about the machine, not a command
assert_eq!(events[3]["name"], "Wake");
assert_eq!(events[3]["family"], "monitor");
assert_eq!(events[3]["class"], "lock");
assert_eq!(events[4]["family"], "monitor");
assert_eq!(events[4]["class"], "monitor");
}
#[test]
fn a_handler_is_found_from_its_span_and_its_header_line() {
let dir = session("kde-flavor-handlers");
let answer = run(&["events", &dir, "--json"]);
let events = answer["data"]["events"].as_array().expect("events");
// a command's block ends at `processed command`
assert_eq!(events[0]["handler"]["lines"], 2, "{}", events[0]);
// an event's block is the header and what komorebi logged while handling it
assert!(events[1]["handler"].is_object(), "{}", events[1]);
assert_eq!(events[1]["handler"]["lines"], 2, "{}", events[1]);
assert_ne!(
events[1]["handler"]["header_line"],
events[2]["handler"]["header_line"]
);
}
#[test]
fn the_analysis_says_the_kde_rules_are_not_yet_checked_against_a_recording() {
let dir = session("kde-flavor-warning");
let answer = run(&["events", &dir, "--json"]);
let warnings = answer["warnings"].as_array().expect("warnings");
assert!(
warnings
.iter()
.any(|warning| warning.as_str().is_some_and(
|text| text.contains("komorebi for KDE") && text.contains("not yet checked")
)),
"{warnings:?}"
);
}