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<W>, 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<W> 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).
This commit is contained in:
LGUG2Z committed 2026-10-31 11:36:54 -07:00
1 parent 27b84796e5
commit caf24494a7
5 files changed
+497

No files matched your search

Generated
+12
View File
@@ -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"
+1
View File
@@ -7,6 +7,7 @@ members = [
"komorebi-gui",
"crates/komorebi-backend",
"crates/komorebi-collections",
"crates/komorebi-core",
"crates/komorebi-config",
"komorebi-layouts",
"komorebi-scrolling",
+19
View File
@@ -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"]
+450
View File
@@ -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<String>;
/// 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<W> {
/// 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<W>,
}
impl<W> Container<W> {
/// The windows of the container.
pub const fn windows(&self) -> &VecDeque<W> {
self.windows.elements()
}
/// The windows of the container, mutably.
pub fn windows_mut(&mut self) -> &mut VecDeque<W> {
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<W> Default for Container<W> {
fn default() -> Self {
Self {
id: nanoid!(),
locked: false,
windows: Ring::default(),
}
}
}
impl<W> Lockable for Container<W> {
fn locked(&self) -> bool {
self.locked
}
fn set_locked(&mut self, locked: bool) -> &mut Self {
self.locked = locked;
self
}
}
impl<W: ContainerWindow> Container<W> {
/// 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<W::Id>) {
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<usize> {
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<usize> {
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<W> {
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<W> {
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<Vec<String>> = const { RefCell::new(Vec::new()) };
}
fn log() -> Vec<String> {
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<String> {
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<Stub> {
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<Stub> = 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<Stub> =
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::<Stub>::preselect().is_preselect());
assert!(!Container::<Stub>::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::<Stub>::schema_name(), "Container");
}
}
+15
View File
@@ -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;