From caf24494a7e5edf160d43095b4f855b372915190 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 11:23:07 -0700 Subject: [PATCH] feat(core): komorebi-core with Container generic over the platform window New crate crates/komorebi-core, a member of the root workspace (KDE and macOS take it by path when they adopt it). It holds Container, moved from komorebi-for-kde/komorebi/src/container.rs (KDE is the base) and made generic: W is any type that implements ContainerWindow, a small trait for what the container asks of a platform window (its id, the executable name, hide and restore, and the hide and restore that load_focused_window uses, which on Windows leave the border alone). Container keeps no Backend calls; hiding and restoring is the window's own business. The serialised form is unchanged: id, locked (which may be missing when read, as on Windows), windows with elements and focused. The schemars schema of Container is named Container whatever W is (schemars(rename)), so schema.json keeps its definition name; a test checks it. The tests of container.rs that need no daemon moved with it, over a stub window, plus tests for the JSON, the hide/restore calls and the missing locked field. No daemon uses it yet: the next revisions converge KDE and Windows. Verified: cargo test -p komorebi-core --features schemars (native): 13 passed, 0 failed. Not run: Windows, KDE, macOS builds (nothing depends on the crate yet). --- Cargo.lock | 12 + Cargo.toml | 1 + crates/komorebi-core/Cargo.toml | 19 ++ crates/komorebi-core/src/container.rs | 450 ++++++++++++++++++++++++++ crates/komorebi-core/src/lib.rs | 15 + 5 files changed, 497 insertions(+) create mode 100644 crates/komorebi-core/Cargo.toml create mode 100644 crates/komorebi-core/src/container.rs create mode 100644 crates/komorebi-core/src/lib.rs diff --git a/Cargo.lock b/Cargo.lock index fb13da7c..f4fcb610 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3490,6 +3490,18 @@ dependencies = [ "strum", ] +[[package]] +name = "komorebi-core" +version = "0.1.42" +dependencies = [ + "komorebi-collections", + "nanoid", + "schemars 1.2.3", + "serde", + "serde_json_lenient", + "tracing", +] + [[package]] name = "komorebi-e2e-agent" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 32f95367..9bd2fe84 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,6 +7,7 @@ members = [ "komorebi-gui", "crates/komorebi-backend", "crates/komorebi-collections", + "crates/komorebi-core", "crates/komorebi-config", "komorebi-layouts", "komorebi-scrolling", diff --git a/crates/komorebi-core/Cargo.toml b/crates/komorebi-core/Cargo.toml new file mode 100644 index 00000000..5dd1d918 --- /dev/null +++ b/crates/komorebi-core/Cargo.toml @@ -0,0 +1,19 @@ +[package] +name = "komorebi-core" +version = "0.1.42" +description = "The model every komorebi daemon shares, generic over the platform's window: containers first, then monitors, workspaces and the window manager" +edition = "2024" + +[dependencies] +komorebi-collections = { path = "../komorebi-collections" } +nanoid = "0.5" +schemars = { workspace = true, optional = true } +serde = { workspace = true } +tracing = { workspace = true } + +[dev-dependencies] +serde_json = { workspace = true, features = ["preserve_order"] } + +[features] +# derives `schemars::JsonSchema` for the model types +schemars = ["dep:schemars", "komorebi-collections/schemars"] diff --git a/crates/komorebi-core/src/container.rs b/crates/komorebi-core/src/container.rs new file mode 100644 index 00000000..3b48d2f6 --- /dev/null +++ b/crates/komorebi-core/src/container.rs @@ -0,0 +1,450 @@ +//! [`Container`], the windows that share one tile of a workspace's layout. +//! +//! A container is a ring of windows. The layout gives each container a tile, and every window of +//! the container is put on that tile. A new window gets a container of its own. +//! +//! A container with more than one window is a stack: the focused window is the one in front, and +//! the others are hidden ([`ContainerWindow::hide_window`]) until they are given the tile +//! ([`Container::load_focused_window`]). +//! +//! A container can be locked ([`Lockable`]): a locked container keeps its index in the workspace +//! while others are inserted, removed or swapped around it. + +use komorebi_collections::Lockable; +use komorebi_collections::ring::Ring; +use nanoid::nanoid; +use serde::Deserialize; +use serde::Serialize; +use std::collections::VecDeque; + +/// What a container needs of a platform's window. +/// +/// The window is a small `Copy` handle (Windows: an `HWND`; KDE: the compositor's id). Showing and +/// hiding it is the platform's business, so the container calls these four operations and nothing +/// else; none of them reports a failure, because a window that cannot be hidden is left where it is. +pub trait ContainerWindow: Copy + PartialEq { + /// What names a window to the rest of the daemon: `isize` on Windows, `u32` on KDE. + type Id: Copy + PartialEq; + + /// The window's id. + fn id(&self) -> Self::Id; + + /// The file name of the executable that owns the window, if it can be told. + fn exe_name(&self) -> Option; + + /// Takes the window out of sight, as a window that is not in front of its stack is. + fn hide_window(&self); + + /// Brings the window back into sight. + fn restore_window(&self); + + /// Hides the window as [`Container::load_focused_window`] does, which on Windows leaves the + /// window's border alone; elsewhere it is [`ContainerWindow::hide_window`]. + fn hide_stacked(&self); + + /// Restores the window as [`Container::load_focused_window`] does, which on Windows leaves the + /// window's border alone; elsewhere it is [`ContainerWindow::restore_window`]. + fn restore_stacked(&self); +} + +/// A ring of windows that share one tile of a workspace's layout. +/// +/// The serialised form is `{"id", "locked", "windows": {"elements", "focused"}}`, which is what +/// `komorebic state` prints for a container whatever the platform; `locked` may be missing when it +/// is read. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[cfg_attr(feature = "schemars", schemars(rename = "Container"))] +pub struct Container { + /// The container's id, `PRESELECT` for the place a preselection reserved. + pub id: String, + /// Whether the container keeps its index while others are inserted, removed or swapped. + #[serde(default)] + pub locked: bool, + /// The windows, with the one in front focused. + pub windows: Ring, +} + +impl Container { + /// The windows of the container. + pub const fn windows(&self) -> &VecDeque { + self.windows.elements() + } + + /// The windows of the container, mutably. + pub fn windows_mut(&mut self) -> &mut VecDeque { + self.windows.elements_mut() + } + + /// The window in front, if there is one. + pub fn focused_window(&self) -> Option<&W> { + self.windows.focused() + } + + /// The index of the window in front. + pub const fn focused_window_idx(&self) -> usize { + self.windows.focused_idx() + } + + /// The window in front, mutably. + pub fn focused_window_mut(&mut self) -> Option<&mut W> { + self.windows.focused_mut() + } +} + +impl Default for Container { + fn default() -> Self { + Self { + id: nanoid!(), + locked: false, + windows: Ring::default(), + } + } +} + +impl Lockable for Container { + fn locked(&self) -> bool { + self.locked + } + + fn set_locked(&mut self, locked: bool) -> &mut Self { + self.locked = locked; + self + } +} + +impl Container { + /// Returns the empty container that holds the place a preselection reserved. + pub fn preselect() -> Self { + Self { + id: "PRESELECT".to_string(), + locked: false, + windows: Default::default(), + } + } + + /// Returns true if and only if this is the container of a preselection + pub fn is_preselect(&self) -> bool { + self.id == "PRESELECT" + } + + /// Hides every window of the container but `omit`, or every window when it is `None` + pub fn hide(&self, omit: Option) { + for window in self.windows().iter().rev() { + let mut should_hide = omit.is_none(); + + if !should_hide + && let Some(omit) = omit + && omit != window.id() + { + should_hide = true + } + + if should_hide { + window.hide_window(); + } + } + } + + /// Restores the focused window of the container, which is the one that is in front when the + /// container is a stack + pub fn restore(&self) { + if let Some(window) = self.focused_window() { + window.restore_window(); + } + } + + /// Hides the unfocused windows of the container and restores the focused one. This function + /// is used to make sure we update the window that should be shown on a stack. If the container + /// isn't a stack this function won't change anything. + pub fn load_focused_window(&mut self) { + let focused_idx = self.focused_window_idx(); + + for (i, window) in self.windows_mut().iter_mut().enumerate() { + if i == focused_idx { + window.restore_stacked(); + } else { + window.hide_stacked(); + } + } + } + + /// The index of the first window of the executable `exe` in this container + pub fn idx_from_exe(&self, exe: &str) -> Option { + for (idx, window) in self.windows().iter().enumerate() { + if let Some(window_exe) = window.exe_name() + && exe == window_exe + { + return Option::from(idx); + } + } + + None + } + + /// Returns true if and only if the container has the window + pub fn contains_window(&self, window_id: W::Id) -> bool { + for window in self.windows() { + if window.id() == window_id { + return true; + } + } + + false + } + + /// The index of the window in the container + pub fn idx_for_window(&self, window_id: W::Id) -> Option { + for (i, window) in self.windows().iter().enumerate() { + if window.id() == window_id { + return Option::from(i); + } + } + + None + } + + /// Takes a window out of the container and focuses the one before it + pub fn remove_window_by_idx(&mut self, idx: usize) -> Option { + let window = self.windows_mut().remove(idx); + self.focus_window(idx.saturating_sub(1)); + window + } + + /// Takes the window in front out of the container + pub fn remove_focused_window(&mut self) -> Option { + let focused_idx = self.focused_window_idx(); + self.remove_window_by_idx(focused_idx) + } + + /// Puts a window at the back of the container and gives it the front, hiding every other + /// window of the container ([`ContainerWindow::hide_window`]) + pub fn add_window(&mut self, window: W) { + self.windows_mut().push_back(window); + self.focus_window(self.windows().len().saturating_sub(1)); + + let focused_window_idx = self.focused_window_idx(); + + for (i, window) in self.windows().iter().enumerate() { + if i != focused_window_idx { + window.hide_window(); + } + } + } + + /// Gives the front to the window at `idx` + #[tracing::instrument(skip(self))] + pub fn focus_window(&mut self, idx: usize) { + tracing::info!("focusing window"); + self.windows.focus(idx); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use std::cell::RefCell; + + #[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)] + struct Stub(u32); + + thread_local! { + static LOG: RefCell> = const { RefCell::new(Vec::new()) }; + } + + fn log() -> Vec { + LOG.with(|log| std::mem::take(&mut *log.borrow_mut())) + } + + impl ContainerWindow for Stub { + type Id = u32; + + fn id(&self) -> u32 { + self.0 + } + + fn exe_name(&self) -> Option { + Some(format!("exe{}", self.0)) + } + + fn hide_window(&self) { + LOG.with(|log| log.borrow_mut().push(format!("hide {}", self.0))); + } + + fn restore_window(&self) { + LOG.with(|log| log.borrow_mut().push(format!("restore {}", self.0))); + } + + fn hide_stacked(&self) { + LOG.with(|log| log.borrow_mut().push(format!("hide-stacked {}", self.0))); + } + + fn restore_stacked(&self) { + LOG.with(|log| log.borrow_mut().push(format!("restore-stacked {}", self.0))); + } + } + + fn container_of(ids: &[u32]) -> Container { + let mut container = Container::default(); + for id in ids { + container.add_window(Stub(*id)); + } + log(); + container + } + + #[test] + fn test_contains_window() { + let container = container_of(&[0, 1, 2]); + + assert!(container.contains_window(1)); + assert_eq!(container.idx_for_window(1), Some(1)); + assert!(!container.contains_window(4)); + assert_eq!(container.idx_for_window(4), None); + } + + #[test] + fn test_remove_window_by_idx() { + let mut container = container_of(&[0, 1, 2]); + + container.remove_window_by_idx(1); + + assert_eq!(container.windows().len(), 2); + assert!(!container.contains_window(1)); + } + + #[test] + fn test_remove_focused_window() { + let mut container = container_of(&[0, 1, 2]); + + assert_eq!(container.focused_window_idx(), 2); + container.remove_focused_window(); + assert_eq!(container.focused_window_idx(), 1); + assert_eq!(container.windows().len(), 2); + } + + #[test] + fn test_add_window() { + let container = container_of(&[1]); + + assert_eq!(container.windows().len(), 1); + assert_eq!(container.focused_window_idx(), 0); + assert!(container.contains_window(1)); + } + + #[test] + fn test_focus_window() { + let mut container = container_of(&[0, 1, 2]); + + assert_eq!(container.focused_window_idx(), 2); + container.focus_window(1); + assert_eq!(container.focused_window_idx(), 1); + container.focus_window(0); + assert_eq!(container.focused_window_idx(), 0); + } + + #[test] + fn a_window_added_is_in_front_and_the_others_are_hidden() { + let mut container = Container::default(); + container.add_window(Stub(1)); + container.add_window(Stub(2)); + + assert_eq!(container.focused_window(), Some(&Stub(2))); + assert_eq!(log(), ["hide 1"]); + } + + #[test] + fn loading_the_focused_window_restores_it_and_hides_the_rest_the_stacked_way() { + let mut container = container_of(&[1, 2, 3]); + container.focus_window(0); + + container.load_focused_window(); + + assert_eq!( + log(), + ["restore-stacked 1", "hide-stacked 2", "hide-stacked 3"] + ); + } + + #[test] + fn hiding_leaves_out_the_window_it_is_told_to_and_restoring_shows_the_focused_one() { + let mut container = container_of(&[7, 8, 9]); + container.focus_window(1); + + container.hide(Some(9)); + assert_eq!(log(), ["hide 8", "hide 7"]); + + container.hide(None); + assert_eq!(log(), ["hide 9", "hide 8", "hide 7"]); + + container.restore(); + assert_eq!(log(), ["restore 8"]); + } + + #[test] + fn the_first_window_of_an_executable_is_found_by_its_index() { + let container = container_of(&[4, 5]); + + assert_eq!(container.idx_from_exe("exe5"), Some(1)); + assert_eq!(container.idx_from_exe("nothing"), None); + } + + #[test] + fn the_json_of_a_container_is_its_id_whether_it_is_locked_and_the_ring_of_windows() { + let mut container: Container = Container { + id: "c1".to_string(), + locked: true, + windows: Ring::default(), + }; + + assert_eq!( + serde_json::to_string(&container).unwrap(), + r#"{"id":"c1","locked":true,"windows":{"elements":[],"focused":0}}"# + ); + + container.add_window(Stub(5)); + container.add_window(Stub(9)); + container.focus_window(0); + + assert_eq!( + serde_json::to_string(&container).unwrap(), + r#"{"id":"c1","locked":true,"windows":{"elements":[5,9],"focused":0}}"# + ); + } + + #[test] + fn locked_may_be_missing_when_a_container_is_read() { + let container: Container = + serde_json::from_str(r#"{"id":"test-1","windows":{"elements":[],"focused":0}}"#) + .unwrap(); + + assert!(!container.locked); + assert_eq!(container.id, "test-1"); + assert!(container.windows().is_empty()); + } + + #[test] + fn a_container_is_a_preselect_by_its_id() { + assert!(Container::::preselect().is_preselect()); + assert!(!Container::::default().is_preselect()); + } + + #[cfg(feature = "schemars")] + impl schemars::JsonSchema for Stub { + fn schema_name() -> std::borrow::Cow<'static, str> { + "Stub".into() + } + + fn json_schema(_: &mut schemars::SchemaGenerator) -> schemars::Schema { + schemars::json_schema!({ "type": "integer" }) + } + } + + #[cfg(feature = "schemars")] + #[test] + fn the_schema_of_a_container_is_called_container_whatever_the_window() { + use schemars::JsonSchema; + + assert_eq!(Container::::schema_name(), "Container"); + } +} diff --git a/crates/komorebi-core/src/lib.rs b/crates/komorebi-core/src/lib.rs new file mode 100644 index 00000000..e96cf123 --- /dev/null +++ b/crates/komorebi-core/src/lib.rs @@ -0,0 +1,15 @@ +//! The model every komorebi daemon shares: the windows, containers, workspaces and monitors that +//! the layout works on, generic over what a platform's window is. +//! +//! The model never talks to a compositor or to Win32. It holds the platform's window as a value of +//! a type `W` and asks it, through [`ContainerWindow`], only what it cannot know itself. See +//! `docs/dev/core-model.md` for the layers and the order they move in. + +#![deny(missing_docs)] + +mod container; + +pub use container::Container; +pub use container::ContainerWindow; +pub use komorebi_collections::Lockable; +pub use komorebi_collections::ring;