refactor(layouts): extract independent komorebi-layouts crate

This commit moves layout-related code into a new workspace crate
komorebi-layouts, with the intention of re-using it all in komorebi for
Mac instead of maintaining two separate implementations.

komorebi-layouts/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "komorebi-layouts"
+version = "0.1.40"
+edition = "2024"
+
+[dependencies]
+clap = { workspace = true }
+color-eyre = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+serde_yaml = { workspace = true }
+strum = { workspace = true }
+tracing = { workspace = true }
+
+# Optional dependencies
+schemars = { workspace = true, optional = true }
+windows = { workspace = true, optional = true }
+
+[features]
+schemars = ["dep:schemars"]
+win32 = ["dep:windows"]

komorebi-layouts/src/custom_layout.rs

@@ -0,0 +1,278 @@
+use color_eyre::eyre;
+use color_eyre::eyre::bail;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::HashMap;
+use std::fs::File;
+use std::io::BufReader;
+use std::ops::Deref;
+use std::ops::DerefMut;
+use std::path::Path;
+
+use super::Rect;
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub struct CustomLayout(Vec<Column>);
+
+impl Deref for CustomLayout {
+    type Target = Vec<Column>;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl DerefMut for CustomLayout {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.0
+    }
+}
+
+impl CustomLayout {
+    pub fn from_path<P: AsRef<Path>>(path: P) -> eyre::Result<Self> {
+        let path = path.as_ref();
+        let layout: Self = match path.extension() {
+            Some(extension) if extension == "yaml" || extension == "yml" => {
+                serde_json::from_reader(BufReader::new(File::open(path)?))?
+            }
+            Some(extension) if extension == "json" => {
+                serde_json::from_reader(BufReader::new(File::open(path)?))?
+            }
+            _ => bail!("custom layouts must be json or yaml files"),
+        };
+
+        if !layout.is_valid() {
+            bail!("the layout file provided was invalid");
+        }
+
+        Ok(layout)
+    }
+
+    #[must_use]
+    pub fn column_with_idx(&self, idx: usize) -> (usize, Option<&Column>) {
+        let column_idx = self.column_for_container_idx(idx);
+        let column = self.get(column_idx);
+        (column_idx, column)
+    }
+
+    #[must_use]
+    pub fn primary_idx(&self) -> Option<usize> {
+        for (i, column) in self.iter().enumerate() {
+            if let Column::Primary(_) = column {
+                return Option::from(i);
+            }
+        }
+
+        None
+    }
+
+    #[must_use]
+    pub fn primary_width_percentage(&self) -> Option<f32> {
+        for column in self.iter() {
+            if let Column::Primary(Option::Some(ColumnWidth::WidthPercentage(percentage))) = column
+            {
+                return Option::from(*percentage);
+            }
+        }
+
+        None
+    }
+
+    pub fn set_primary_width_percentage(&mut self, percentage: f32) {
+        for column in self.iter_mut() {
+            if let Column::Primary(Option::Some(ColumnWidth::WidthPercentage(current))) = column {
+                *current = percentage;
+            }
+        }
+    }
+
+    #[must_use]
+    pub fn is_valid(&self) -> bool {
+        // A valid layout must have at least one column
+        if self.is_empty() {
+            return false;
+        };
+
+        // Vertical column splits aren't supported at the moment
+        for column in self.iter() {
+            match column {
+                Column::Tertiary(ColumnSplit::Vertical)
+                | Column::Secondary(Some(ColumnSplitWithCapacity::Vertical(_))) => return false,
+                _ => {}
+            }
+        }
+
+        // The final column must not have a fixed capacity
+        match self.last() {
+            Some(Column::Tertiary(_)) => {}
+            _ => return false,
+        }
+
+        let mut primaries = 0;
+        let mut tertiaries = 0;
+
+        for column in self.iter() {
+            match column {
+                Column::Primary(_) => primaries += 1,
+                Column::Tertiary(_) => tertiaries += 1,
+                Column::Secondary(_) => {}
+            }
+        }
+
+        // There must only be one primary and one tertiary column
+        matches!(primaries, 1) && matches!(tertiaries, 1)
+    }
+
+    pub(crate) fn column_container_counts(&self) -> HashMap<usize, usize> {
+        let mut count_map = HashMap::new();
+
+        for (idx, column) in self.iter().enumerate() {
+            match column {
+                Column::Primary(_) | Column::Secondary(None) => {
+                    count_map.insert(idx, 1);
+                }
+                Column::Secondary(Some(split)) => {
+                    count_map.insert(
+                        idx,
+                        match split {
+                            ColumnSplitWithCapacity::Vertical(n)
+                            | ColumnSplitWithCapacity::Horizontal(n) => *n,
+                        },
+                    );
+                }
+                Column::Tertiary(_) => {}
+            }
+        }
+
+        count_map
+    }
+
+    #[must_use]
+    pub fn first_container_idx(&self, col_idx: usize) -> usize {
+        let count_map = self.column_container_counts();
+        let mut container_idx_accumulator = 0;
+
+        for i in 0..col_idx {
+            if let Some(n) = count_map.get(&i) {
+                container_idx_accumulator += n;
+            }
+        }
+
+        container_idx_accumulator
+    }
+
+    #[must_use]
+    pub fn column_for_container_idx(&self, idx: usize) -> usize {
+        let count_map = self.column_container_counts();
+        let mut container_idx_accumulator = 0;
+
+        // always -1 because we don't insert the tertiary column in the count_map
+        for i in 0..self.len() - 1 {
+            if let Some(n) = count_map.get(&i) {
+                container_idx_accumulator += n;
+
+                // The accumulator becomes greater than the window container index
+                // for the first time when we reach a column that contains that
+                // window container index
+                if container_idx_accumulator > idx {
+                    return i;
+                }
+            }
+        }
+
+        // If the accumulator never reaches a point where it is greater than the
+        // window container index, then the only remaining possibility is the
+        // final tertiary column
+        self.len() - 1
+    }
+
+    #[must_use]
+    pub fn column_area(&self, work_area: &Rect, idx: usize, offset: Option<usize>) -> Rect {
+        let divisor = offset.map_or_else(|| self.len(), |offset| self.len() - offset);
+
+        #[allow(clippy::cast_possible_wrap, clippy::cast_possible_truncation)]
+        let equal_width = work_area.right / divisor as i32;
+        let mut left = work_area.left;
+        let right = equal_width;
+
+        for _ in 0..idx {
+            left += right;
+        }
+
+        Rect {
+            left,
+            top: work_area.top,
+            right,
+            bottom: work_area.bottom,
+        }
+    }
+
+    #[must_use]
+    pub fn column_area_with_last(
+        len: usize,
+        work_area: &Rect,
+        primary_right: i32,
+        last_column: Option<Rect>,
+        offset: Option<usize>,
+    ) -> Rect {
+        let divisor = offset.map_or_else(|| len - 1, |offset| len - offset - 1);
+
+        #[allow(clippy::cast_possible_wrap, clippy::cast_possible_truncation)]
+        let equal_width = (work_area.right - primary_right) / divisor as i32;
+        let left = last_column.map_or(work_area.left, |last| last.left + last.right);
+        let right = equal_width;
+
+        Rect {
+            left,
+            top: work_area.top,
+            right,
+            bottom: work_area.bottom,
+        }
+    }
+
+    #[must_use]
+    pub fn main_column_area(
+        work_area: &Rect,
+        primary_right: i32,
+        last_column: Option<Rect>,
+    ) -> Rect {
+        let left = last_column.map_or(work_area.left, |last| last.left + last.right);
+
+        Rect {
+            left,
+            top: work_area.top,
+            right: primary_right,
+            bottom: work_area.bottom,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+#[serde(tag = "column", content = "configuration")]
+pub enum Column {
+    Primary(Option<ColumnWidth>),
+    Secondary(Option<ColumnSplitWithCapacity>),
+    Tertiary(ColumnSplit),
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub enum ColumnWidth {
+    WidthPercentage(f32),
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub enum ColumnSplit {
+    Horizontal,
+    Vertical,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub enum ColumnSplitWithCapacity {
+    Horizontal(usize),
+    Vertical(usize),
+}

komorebi-layouts/src/cycle_direction.rs

@@ -0,0 +1,36 @@
+use std::num::NonZeroUsize;
+
+use clap::ValueEnum;
+use serde::Deserialize;
+use serde::Serialize;
+use strum::Display;
+use strum::EnumString;
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Display, EnumString, ValueEnum)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub enum CycleDirection {
+    Previous,
+    Next,
+}
+
+impl CycleDirection {
+    #[must_use]
+    pub const fn next_idx(&self, idx: usize, len: NonZeroUsize) -> usize {
+        match self {
+            Self::Previous => {
+                if idx == 0 {
+                    len.get() - 1
+                } else {
+                    idx - 1
+                }
+            }
+            Self::Next => {
+                if idx == len.get() - 1 {
+                    0
+                } else {
+                    idx + 1
+                }
+            }
+        }
+    }
+}

komorebi-layouts/src/default_layout.rs

@@ -0,0 +1,778 @@
+use clap::ValueEnum;
+use serde::Deserialize;
+use serde::Serialize;
+use strum::Display;
+use strum::EnumString;
+
+use super::OperationDirection;
+use super::Rect;
+use super::Sizing;
+
+/// Maximum number of ratio values that can be specified for column_ratios and row_ratios
+pub const MAX_RATIOS: usize = 5;
+
+/// Minimum allowed ratio value (prevents zero-sized windows)
+pub const MIN_RATIO: f32 = 0.1;
+
+/// Maximum allowed ratio value (ensures space for remaining windows)
+pub const MAX_RATIO: f32 = 0.9;
+
+/// Default ratio value when none is specified
+pub const DEFAULT_RATIO: f32 = 0.5;
+
+/// Default secondary ratio value for UltrawideVerticalStack layout
+pub const DEFAULT_SECONDARY_RATIO: f32 = 0.25;
+
+#[derive(
+    Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq, Display, EnumString, ValueEnum,
+)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+/// A predefined komorebi layout
+pub enum DefaultLayout {
+    /// BSP Layout
+    ///
+    /// ```text
+    /// +-------+-----+
+    /// |       |     |
+    /// |       +--+--+
+    /// |       |  |--|
+    /// +-------+--+--+
+    /// ```
+    BSP,
+    /// Columns Layout
+    ///
+    /// ```text
+    /// +--+--+--+--+
+    /// |  |  |  |  |
+    /// |  |  |  |  |
+    /// |  |  |  |  |
+    /// +--+--+--+--+
+    /// ```
+    Columns,
+    /// Rows Layout
+    ///
+    /// ```text
+    /// +-----------+
+    /// |-----------|
+    /// |-----------|
+    /// |-----------|
+    /// +-----------+
+    /// ```
+    Rows,
+    /// Vertical Stack Layout
+    ///
+    /// ```text
+    /// +-------+-----+
+    /// |       |     |
+    /// |       +-----+
+    /// |       |     |
+    /// +-------+-----+
+    /// ```
+    VerticalStack,
+    /// Horizontal Stack Layout
+    ///
+    /// ```text
+    /// +------+------+
+    /// |             |
+    /// |------+------+
+    /// |      |      |
+    /// +------+------+
+    /// ```
+    HorizontalStack,
+    /// Ultrawide Vertical Stack Layout
+    ///
+    /// ```text
+    /// +-----+-----------+-----+
+    /// |     |           |     |
+    /// |     |           +-----+
+    /// |     |           |     |
+    /// |     |           +-----+
+    /// |     |           |     |
+    /// +-----+-----------+-----+
+    /// ```
+    UltrawideVerticalStack,
+    /// Grid Layout
+    ///
+    /// ```text
+    /// +-----+-----+   +---+---+---+   +---+---+---+   +---+---+---+
+    /// |     |     |   |   |   |   |   |   |   |   |   |   |   |   |
+    /// |     |     |   |   |   |   |   |   |   |   |   |   |   +---+
+    /// +-----+-----+   |   +---+---+   +---+---+---+   +---+---|   |
+    /// |     |     |   |   |   |   |   |   |   |   |   |   |   +---+
+    /// |     |     |   |   |   |   |   |   |   |   |   |   |   |   |
+    /// +-----+-----+   +---+---+---+   +---+---+---+   +---+---+---+
+    ///   4 windows       5 windows       6 windows       7 windows
+    /// ```
+    Grid,
+    /// Right Main Vertical Stack Layout
+    ///
+    /// ```text
+    /// +-----+-------+
+    /// |     |       |
+    /// +-----+       |
+    /// |     |       |
+    /// +-----+-------+
+    /// ```
+    RightMainVerticalStack,
+    /// Scrolling Layout
+    ///
+    /// ```text
+    /// +--+--+--+--+--+--+
+    /// |     |     |     |
+    /// |     |     |     |
+    /// |     |     |     |
+    /// +--+--+--+--+--+--+
+    /// ```
+    Scrolling,
+    // NOTE: If any new layout is added, please make sure to register the same in `DefaultLayout::cycle`
+}
+
+/// Helper to deserialize a variable-length array into a fixed [Option<f32>; MAX_RATIOS]
+/// Ratios are truncated when their cumulative sum reaches or exceeds 1.0 to ensure
+/// there's always remaining space for additional windows.
+fn deserialize_ratios<'de, D>(
+    deserializer: D,
+) -> Result<Option<[Option<f32>; MAX_RATIOS]>, D::Error>
+where
+    D: serde::Deserializer<'de>,
+{
+    let opt: Option<Vec<f32>> = Option::deserialize(deserializer)?;
+    Ok(opt.map(|vec| {
+        let mut arr = [None; MAX_RATIOS];
+        let mut cumulative_sum = 0.0_f32;
+
+        for (i, &val) in vec.iter().take(MAX_RATIOS).enumerate() {
+            let clamped_val = val.clamp(MIN_RATIO, MAX_RATIO);
+
+            // Only add this ratio if cumulative sum stays below 1.0
+            if cumulative_sum + clamped_val < 1.0 {
+                arr[i] = Some(clamped_val);
+                cumulative_sum += clamped_val;
+            } else {
+                // Stop adding ratios - cumulative sum would reach or exceed 1.0
+                tracing::debug!(
+                    "Truncating ratios at index {} - cumulative sum {} + {} would reach/exceed 1.0",
+                    i,
+                    cumulative_sum,
+                    clamped_val
+                );
+                break;
+            }
+        }
+        arr
+    }))
+}
+
+/// Helper to serialize [Option<f32>; MAX_RATIOS] as a compact array (without trailing nulls)
+fn serialize_ratios<S>(
+    value: &Option<[Option<f32>; MAX_RATIOS]>,
+    serializer: S,
+) -> Result<S::Ok, S::Error>
+where
+    S: serde::Serializer,
+{
+    match value {
+        None => serializer.serialize_none(),
+        Some(arr) => {
+            // Find last non-None index
+            let last_idx = arr
+                .iter()
+                .rposition(|x| x.is_some())
+                .map(|i| i + 1)
+                .unwrap_or(0);
+            let vec: Vec<f32> = arr.iter().take(last_idx).filter_map(|&x| x).collect();
+            serializer.serialize_some(&vec)
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+/// Options for specific layouts
+pub struct LayoutOptions {
+    /// Options related to the Scrolling layout
+    pub scrolling: Option<ScrollingLayoutOptions>,
+    /// Options related to the Grid layout
+    pub grid: Option<GridLayoutOptions>,
+    /// Column width ratios (up to MAX_RATIOS values between 0.1 and 0.9)
+    ///
+    /// - Used by Columns layout: ratios for each column width
+    /// - Used by Grid layout: ratios for column widths
+    /// - Used by BSP, VerticalStack, RightMainVerticalStack: column_ratios[0] as primary split ratio
+    /// - Used by HorizontalStack: column_ratios[0] as primary split ratio (top area height)
+    /// - Used by UltrawideVerticalStack: column_ratios[0] as center ratio, column_ratios[1] as left ratio
+    ///
+    /// Columns without a ratio share remaining space equally.
+    /// Example: `[0.3, 0.4, 0.3]` for 30%-40%-30% columns
+    #[serde(
+        default,
+        deserialize_with = "deserialize_ratios",
+        serialize_with = "serialize_ratios"
+    )]
+    pub column_ratios: Option<[Option<f32>; MAX_RATIOS]>,
+    /// Row height ratios (up to MAX_RATIOS values between 0.1 and 0.9)
+    ///
+    /// - Used by Rows layout: ratios for each row height
+    /// - Used by Grid layout: ratios for row heights
+    ///
+    /// Rows without a ratio share remaining space equally.
+    /// Example: `[0.5, 0.5]` for 50%-50% rows
+    #[serde(
+        default,
+        deserialize_with = "deserialize_ratios",
+        serialize_with = "serialize_ratios"
+    )]
+    pub row_ratios: Option<[Option<f32>; MAX_RATIOS]>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+/// Options for the Scrolling layout
+pub struct ScrollingLayoutOptions {
+    /// Desired number of visible columns (default: 3)
+    pub columns: usize,
+    /// With an odd number of visible columns, keep the focused window column centered
+    pub center_focused_column: Option<bool>,
+}
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+/// Options for the Grid layout
+pub struct GridLayoutOptions {
+    /// Maximum number of rows per grid column
+    pub rows: usize,
+}
+
+impl DefaultLayout {
+    pub fn leftmost_index(&self, len: usize) -> usize {
+        match self {
+            Self::UltrawideVerticalStack | Self::RightMainVerticalStack => match len {
+                n if n > 1 => 1,
+                _ => 0,
+            },
+            Self::Scrolling => 0,
+            DefaultLayout::BSP
+            | DefaultLayout::Columns
+            | DefaultLayout::Rows
+            | DefaultLayout::VerticalStack
+            | DefaultLayout::HorizontalStack
+            | DefaultLayout::Grid => 0,
+        }
+    }
+
+    pub fn rightmost_index(&self, len: usize) -> usize {
+        match self {
+            DefaultLayout::BSP
+            | DefaultLayout::Columns
+            | DefaultLayout::Rows
+            | DefaultLayout::VerticalStack
+            | DefaultLayout::HorizontalStack
+            | DefaultLayout::Grid => len.saturating_sub(1),
+            DefaultLayout::UltrawideVerticalStack => match len {
+                2 => 0,
+                _ => len.saturating_sub(1),
+            },
+            DefaultLayout::RightMainVerticalStack => 0,
+            DefaultLayout::Scrolling => len.saturating_sub(1),
+        }
+    }
+
+    #[must_use]
+    #[allow(clippy::cast_precision_loss, clippy::only_used_in_recursion)]
+    pub fn resize(
+        &self,
+        unaltered: &Rect,
+        resize: &Option<Rect>,
+        edge: OperationDirection,
+        sizing: Sizing,
+        delta: i32,
+    ) -> Option<Rect> {
+        if !matches!(
+            self,
+            Self::BSP
+                | Self::Columns
+                | Self::Rows
+                | Self::VerticalStack
+                | Self::RightMainVerticalStack
+                | Self::HorizontalStack
+                | Self::UltrawideVerticalStack
+                | Self::Scrolling
+        ) {
+            return None;
+        };
+
+        let mut r = resize.unwrap_or_default();
+
+        let resize_delta = delta;
+
+        match edge {
+            OperationDirection::Left => match sizing {
+                Sizing::Increase => {
+                    // Some final checks to make sure the user can't infinitely resize to
+                    // the point of pushing other windows out of bounds
+
+                    // Note: These checks cannot take into account the changes made to the
+                    // edges of adjacent windows at operation time, so it is still possible
+                    // to push windows out of bounds by maxing out an Increase Left on a
+                    // Window with index 1, and then maxing out a Decrease Right on a Window
+                    // with index 0. I don't think it's worth trying to defensively program
+                    // against this; if people end up in this situation they are better off
+                    // just hitting the retile command
+                    let diff = ((r.left + -resize_delta) as f32).abs();
+                    if diff < unaltered.right as f32 {
+                        r.left += -resize_delta;
+                    }
+                }
+                Sizing::Decrease => {
+                    let diff = ((r.left - -resize_delta) as f32).abs();
+                    if diff < unaltered.right as f32 {
+                        r.left -= -resize_delta;
+                    }
+                }
+            },
+            OperationDirection::Up => match sizing {
+                Sizing::Increase => {
+                    let diff = ((r.top + resize_delta) as f32).abs();
+                    if diff < unaltered.bottom as f32 {
+                        r.top += -resize_delta;
+                    }
+                }
+                Sizing::Decrease => {
+                    let diff = ((r.top - resize_delta) as f32).abs();
+                    if diff < unaltered.bottom as f32 {
+                        r.top -= -resize_delta;
+                    }
+                }
+            },
+            OperationDirection::Right => match sizing {
+                Sizing::Increase => {
+                    let diff = ((r.right + resize_delta) as f32).abs();
+                    if diff < unaltered.right as f32 {
+                        r.right += resize_delta;
+                    }
+                }
+                Sizing::Decrease => {
+                    let diff = ((r.right - resize_delta) as f32).abs();
+                    if diff < unaltered.right as f32 {
+                        r.right -= resize_delta;
+                    }
+                }
+            },
+            OperationDirection::Down => match sizing {
+                Sizing::Increase => {
+                    let diff = ((r.bottom + resize_delta) as f32).abs();
+                    if diff < unaltered.bottom as f32 {
+                        r.bottom += resize_delta;
+                    }
+                }
+                Sizing::Decrease => {
+                    let diff = ((r.bottom - resize_delta) as f32).abs();
+                    if diff < unaltered.bottom as f32 {
+                        r.bottom -= resize_delta;
+                    }
+                }
+            },
+        };
+
+        if r.eq(&Rect::default()) {
+            None
+        } else {
+            Option::from(r)
+        }
+    }
+
+    #[must_use]
+    pub const fn cycle_next(self) -> Self {
+        match self {
+            Self::BSP => Self::Columns,
+            Self::Columns => Self::Rows,
+            Self::Rows => Self::VerticalStack,
+            Self::VerticalStack => Self::HorizontalStack,
+            Self::HorizontalStack => Self::UltrawideVerticalStack,
+            Self::UltrawideVerticalStack => Self::Grid,
+            Self::Grid => Self::RightMainVerticalStack,
+            Self::RightMainVerticalStack => Self::Scrolling,
+            Self::Scrolling => Self::BSP,
+        }
+    }
+
+    #[must_use]
+    pub const fn cycle_previous(self) -> Self {
+        match self {
+            Self::Scrolling => Self::RightMainVerticalStack,
+            Self::RightMainVerticalStack => Self::Grid,
+            Self::Grid => Self::UltrawideVerticalStack,
+            Self::UltrawideVerticalStack => Self::HorizontalStack,
+            Self::HorizontalStack => Self::VerticalStack,
+            Self::VerticalStack => Self::Rows,
+            Self::Rows => Self::Columns,
+            Self::Columns => Self::BSP,
+            Self::BSP => Self::RightMainVerticalStack,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Helper to create LayoutOptions with column ratios
+    fn layout_options_with_column_ratios(ratios: &[f32]) -> LayoutOptions {
+        let mut arr = [None; MAX_RATIOS];
+        for (i, &r) in ratios.iter().take(MAX_RATIOS).enumerate() {
+            arr[i] = Some(r);
+        }
+        LayoutOptions {
+            scrolling: None,
+            grid: None,
+            column_ratios: Some(arr),
+            row_ratios: None,
+        }
+    }
+
+    // Helper to create LayoutOptions with row ratios
+    fn layout_options_with_row_ratios(ratios: &[f32]) -> LayoutOptions {
+        let mut arr = [None; MAX_RATIOS];
+        for (i, &r) in ratios.iter().take(MAX_RATIOS).enumerate() {
+            arr[i] = Some(r);
+        }
+        LayoutOptions {
+            scrolling: None,
+            grid: None,
+            column_ratios: None,
+            row_ratios: Some(arr),
+        }
+    }
+
+    // Helper to create LayoutOptions with both column and row ratios
+    fn layout_options_with_ratios(column_ratios: &[f32], row_ratios: &[f32]) -> LayoutOptions {
+        let mut col_arr = [None; MAX_RATIOS];
+        for (i, &r) in column_ratios.iter().take(MAX_RATIOS).enumerate() {
+            col_arr[i] = Some(r);
+        }
+        let mut row_arr = [None; MAX_RATIOS];
+        for (i, &r) in row_ratios.iter().take(MAX_RATIOS).enumerate() {
+            row_arr[i] = Some(r);
+        }
+        LayoutOptions {
+            scrolling: None,
+            grid: None,
+            column_ratios: Some(col_arr),
+            row_ratios: Some(row_arr),
+        }
+    }
+
+    mod deserialize_ratios_tests {
+        use super::*;
+
+        #[test]
+        fn test_deserialize_valid_ratios() {
+            let json = r#"{"column_ratios": [0.3, 0.4, 0.2]}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            let ratios = opts.column_ratios.unwrap();
+            assert_eq!(ratios[0], Some(0.3));
+            assert_eq!(ratios[1], Some(0.4));
+            assert_eq!(ratios[2], Some(0.2));
+            assert_eq!(ratios[3], None);
+            assert_eq!(ratios[4], None);
+        }
+
+        #[test]
+        fn test_deserialize_clamps_values_to_min() {
+            // Values below MIN_RATIO should be clamped
+            let json = r#"{"column_ratios": [0.05]}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            let ratios = opts.column_ratios.unwrap();
+            assert_eq!(ratios[0], Some(MIN_RATIO)); // Clamped to 0.1
+        }
+
+        #[test]
+        fn test_deserialize_clamps_values_to_max() {
+            // Values above MAX_RATIO should be clamped
+            let json = r#"{"column_ratios": [0.95]}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            let ratios = opts.column_ratios.unwrap();
+            // 0.9 is the max, so it should be clamped
+            assert!(ratios[0].unwrap() <= MAX_RATIO);
+        }
+
+        #[test]
+        fn test_deserialize_truncates_when_sum_exceeds_one() {
+            // Sum of ratios should not reach 1.0
+            // [0.5, 0.4] = 0.9, then 0.3 would make it 1.2, so it should be truncated
+            let json = r#"{"column_ratios": [0.5, 0.4, 0.3]}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            let ratios = opts.column_ratios.unwrap();
+            assert_eq!(ratios[0], Some(0.5));
+            assert_eq!(ratios[1], Some(0.4));
+            // Third ratio should be truncated because 0.5 + 0.4 + 0.3 >= 1.0
+            assert_eq!(ratios[2], None);
+        }
+
+        #[test]
+        fn test_deserialize_truncates_at_max_ratios() {
+            // More than MAX_RATIOS values should be truncated
+            let json = r#"{"column_ratios": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            let ratios = opts.column_ratios.unwrap();
+            // Only MAX_RATIOS (5) values should be stored
+            for i in 0..MAX_RATIOS {
+                assert_eq!(ratios[i], Some(0.1));
+            }
+        }
+
+        #[test]
+        fn test_deserialize_empty_array() {
+            let json = r#"{"column_ratios": []}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            let ratios = opts.column_ratios.unwrap();
+            for i in 0..MAX_RATIOS {
+                assert_eq!(ratios[i], None);
+            }
+        }
+
+        #[test]
+        fn test_deserialize_null() {
+            let json = r#"{"column_ratios": null}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+            assert!(opts.column_ratios.is_none());
+        }
+
+        #[test]
+        fn test_deserialize_row_ratios() {
+            let json = r#"{"row_ratios": [0.3, 0.5]}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            let ratios = opts.row_ratios.unwrap();
+            assert_eq!(ratios[0], Some(0.3));
+            assert_eq!(ratios[1], Some(0.5));
+            assert_eq!(ratios[2], None);
+        }
+    }
+
+    mod serialize_ratios_tests {
+        use super::*;
+
+        #[test]
+        fn test_serialize_ratios_compact() {
+            let opts = layout_options_with_column_ratios(&[0.3, 0.4]);
+            let json = serde_json::to_string(&opts).unwrap();
+
+            // Should serialize ratios as compact array without trailing nulls in the ratios array
+            assert!(json.contains("0.3") && json.contains("0.4"));
+        }
+
+        #[test]
+        fn test_serialize_none_ratios() {
+            let opts = LayoutOptions {
+                scrolling: None,
+                grid: None,
+                column_ratios: None,
+                row_ratios: None,
+            };
+            let json = serde_json::to_string(&opts).unwrap();
+
+            // None values should serialize as null or be omitted
+            assert!(!json.contains("["));
+        }
+
+        #[test]
+        fn test_roundtrip_serialization() {
+            let original = layout_options_with_column_ratios(&[0.3, 0.4, 0.2]);
+            let json = serde_json::to_string(&original).unwrap();
+            let deserialized: LayoutOptions = serde_json::from_str(&json).unwrap();
+
+            assert_eq!(original.column_ratios, deserialized.column_ratios);
+        }
+
+        #[test]
+        fn test_serialize_row_ratios() {
+            let opts = layout_options_with_row_ratios(&[0.3, 0.5]);
+            let json = serde_json::to_string(&opts).unwrap();
+
+            assert!(json.contains("row_ratios"));
+            assert!(json.contains("0.3") && json.contains("0.5"));
+        }
+
+        #[test]
+        fn test_roundtrip_row_ratios() {
+            let original = layout_options_with_row_ratios(&[0.4, 0.3]);
+            let json = serde_json::to_string(&original).unwrap();
+            let deserialized: LayoutOptions = serde_json::from_str(&json).unwrap();
+
+            assert_eq!(original.row_ratios, deserialized.row_ratios);
+            assert!(original.column_ratios.is_none());
+        }
+
+        #[test]
+        fn test_roundtrip_both_ratios() {
+            let original = layout_options_with_ratios(&[0.3, 0.4], &[0.5, 0.3]);
+            let json = serde_json::to_string(&original).unwrap();
+            let deserialized: LayoutOptions = serde_json::from_str(&json).unwrap();
+
+            assert_eq!(original.column_ratios, deserialized.column_ratios);
+            assert_eq!(original.row_ratios, deserialized.row_ratios);
+        }
+    }
+
+    mod ratio_constants_tests {
+        use super::*;
+
+        #[test]
+        fn test_constants_valid_ranges() {
+            assert!(MIN_RATIO > 0.0);
+            assert!(MIN_RATIO < MAX_RATIO);
+            assert!(MAX_RATIO < 1.0);
+            assert!(DEFAULT_RATIO >= MIN_RATIO && DEFAULT_RATIO <= MAX_RATIO);
+            assert!(DEFAULT_SECONDARY_RATIO >= MIN_RATIO && DEFAULT_SECONDARY_RATIO <= MAX_RATIO);
+            assert!(MAX_RATIOS >= 1);
+        }
+
+        #[test]
+        fn test_default_ratio_is_half() {
+            assert_eq!(DEFAULT_RATIO, 0.5);
+        }
+
+        #[test]
+        fn test_max_ratios_is_five() {
+            assert_eq!(MAX_RATIOS, 5);
+        }
+    }
+
+    mod layout_options_tests {
+        use super::*;
+
+        #[test]
+        fn test_layout_options_default_values() {
+            let json = r#"{}"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            assert!(opts.scrolling.is_none());
+            assert!(opts.grid.is_none());
+            assert!(opts.column_ratios.is_none());
+            assert!(opts.row_ratios.is_none());
+        }
+
+        #[test]
+        fn test_layout_options_with_all_fields() {
+            let json = r#"{
+                "scrolling": {"columns": 3},
+                "grid": {"rows": 2},
+                "column_ratios": [0.3, 0.4],
+                "row_ratios": [0.5]
+            }"#;
+            let opts: LayoutOptions = serde_json::from_str(json).unwrap();
+
+            assert!(opts.scrolling.is_some());
+            assert_eq!(opts.scrolling.unwrap().columns, 3);
+            assert!(opts.grid.is_some());
+            assert_eq!(opts.grid.unwrap().rows, 2);
+            assert!(opts.column_ratios.is_some());
+            assert!(opts.row_ratios.is_some());
+        }
+    }
+
+    mod default_layout_tests {
+        use super::*;
+
+        #[test]
+        fn test_cycle_next_covers_all_layouts() {
+            let start = DefaultLayout::BSP;
+            let mut current = start;
+            let mut visited = vec![current];
+
+            loop {
+                current = current.cycle_next();
+                if current == start {
+                    break;
+                }
+                assert!(
+                    !visited.contains(&current),
+                    "Cycle contains duplicate: {:?}",
+                    current
+                );
+                visited.push(current);
+            }
+
+            // Should have visited all layouts
+            assert_eq!(visited.len(), 9); // 9 layouts total
+        }
+
+        #[test]
+        fn test_cycle_previous_is_inverse_of_next() {
+            // Note: cycle_previous has some inconsistencies in the current implementation
+            // This test documents the expected behavior for most layouts
+            let layouts_with_correct_inverse = [
+                DefaultLayout::Columns,
+                DefaultLayout::Rows,
+                DefaultLayout::VerticalStack,
+                DefaultLayout::HorizontalStack,
+                DefaultLayout::UltrawideVerticalStack,
+                DefaultLayout::Grid,
+                DefaultLayout::RightMainVerticalStack,
+            ];
+
+            for layout in layouts_with_correct_inverse {
+                let next = layout.cycle_next();
+                assert_eq!(
+                    next.cycle_previous(),
+                    layout,
+                    "cycle_previous should be inverse of cycle_next for {:?}",
+                    layout
+                );
+            }
+        }
+
+        #[test]
+        fn test_leftmost_index_standard_layouts() {
+            assert_eq!(DefaultLayout::BSP.leftmost_index(5), 0);
+            assert_eq!(DefaultLayout::Columns.leftmost_index(5), 0);
+            assert_eq!(DefaultLayout::Rows.leftmost_index(5), 0);
+            assert_eq!(DefaultLayout::VerticalStack.leftmost_index(5), 0);
+            assert_eq!(DefaultLayout::HorizontalStack.leftmost_index(5), 0);
+            assert_eq!(DefaultLayout::Grid.leftmost_index(5), 0);
+        }
+
+        #[test]
+        fn test_leftmost_index_ultrawide() {
+            assert_eq!(DefaultLayout::UltrawideVerticalStack.leftmost_index(1), 0);
+            assert_eq!(DefaultLayout::UltrawideVerticalStack.leftmost_index(2), 1);
+            assert_eq!(DefaultLayout::UltrawideVerticalStack.leftmost_index(5), 1);
+        }
+
+        #[test]
+        fn test_leftmost_index_right_main() {
+            assert_eq!(DefaultLayout::RightMainVerticalStack.leftmost_index(1), 0);
+            assert_eq!(DefaultLayout::RightMainVerticalStack.leftmost_index(2), 1);
+            assert_eq!(DefaultLayout::RightMainVerticalStack.leftmost_index(5), 1);
+        }
+
+        #[test]
+        fn test_rightmost_index_standard_layouts() {
+            assert_eq!(DefaultLayout::BSP.rightmost_index(5), 4);
+            assert_eq!(DefaultLayout::Columns.rightmost_index(5), 4);
+            assert_eq!(DefaultLayout::Rows.rightmost_index(5), 4);
+            assert_eq!(DefaultLayout::VerticalStack.rightmost_index(5), 4);
+        }
+
+        #[test]
+        fn test_rightmost_index_right_main() {
+            assert_eq!(DefaultLayout::RightMainVerticalStack.rightmost_index(1), 0);
+            assert_eq!(DefaultLayout::RightMainVerticalStack.rightmost_index(5), 0);
+        }
+
+        #[test]
+        fn test_rightmost_index_ultrawide() {
+            assert_eq!(DefaultLayout::UltrawideVerticalStack.rightmost_index(1), 0);
+            assert_eq!(DefaultLayout::UltrawideVerticalStack.rightmost_index(2), 0);
+            assert_eq!(DefaultLayout::UltrawideVerticalStack.rightmost_index(3), 2);
+            assert_eq!(DefaultLayout::UltrawideVerticalStack.rightmost_index(5), 4);
+        }
+    }
+}

komorebi-layouts/src/direction.rs

@@ -0,0 +1,549 @@
+use super::DefaultLayout;
+use super::OperationDirection;
+use super::custom_layout::Column;
+use super::custom_layout::ColumnSplit;
+use super::custom_layout::ColumnSplitWithCapacity;
+use super::custom_layout::CustomLayout;
+use crate::default_layout::LayoutOptions;
+
+pub trait Direction {
+    fn index_in_direction(
+        &self,
+        op_direction: OperationDirection,
+        idx: usize,
+        count: usize,
+        layout_options: Option<LayoutOptions>,
+    ) -> Option<usize>;
+
+    fn is_valid_direction(
+        &self,
+        op_direction: OperationDirection,
+        idx: usize,
+        count: usize,
+        layout_options: Option<LayoutOptions>,
+    ) -> bool;
+    fn up_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize;
+    fn down_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize;
+    fn left_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize;
+    fn right_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize;
+}
+
+impl Direction for DefaultLayout {
+    fn index_in_direction(
+        &self,
+        op_direction: OperationDirection,
+        idx: usize,
+        count: usize,
+        layout_options: Option<LayoutOptions>,
+    ) -> Option<usize> {
+        match op_direction {
+            OperationDirection::Left => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.left_index(
+                        Some(op_direction),
+                        idx,
+                        Some(count),
+                        layout_options,
+                    ))
+                } else {
+                    None
+                }
+            }
+            OperationDirection::Right => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.right_index(
+                        Some(op_direction),
+                        idx,
+                        Some(count),
+                        layout_options,
+                    ))
+                } else {
+                    None
+                }
+            }
+            OperationDirection::Up => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.up_index(
+                        Some(op_direction),
+                        idx,
+                        Some(count),
+                        layout_options,
+                    ))
+                } else {
+                    None
+                }
+            }
+            OperationDirection::Down => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.down_index(
+                        Some(op_direction),
+                        idx,
+                        Some(count),
+                        layout_options,
+                    ))
+                } else {
+                    None
+                }
+            }
+        }
+    }
+
+    fn is_valid_direction(
+        &self,
+        op_direction: OperationDirection,
+        idx: usize,
+        count: usize,
+        layout_options: Option<LayoutOptions>,
+    ) -> bool {
+        if count < 2 {
+            return false;
+        }
+
+        match op_direction {
+            OperationDirection::Up => match self {
+                Self::BSP => idx != 0 && idx != 1,
+                Self::Columns => false,
+                Self::Rows | Self::HorizontalStack => idx != 0,
+                Self::VerticalStack | Self::RightMainVerticalStack => idx != 0 && idx != 1,
+                Self::UltrawideVerticalStack => idx > 2,
+                Self::Grid => !is_grid_edge(op_direction, idx, count, layout_options),
+                Self::Scrolling => false,
+            },
+            OperationDirection::Down => match self {
+                Self::BSP => idx != count - 1 && !idx.is_multiple_of(2),
+                Self::Columns => false,
+                Self::Rows => idx != count - 1,
+                Self::VerticalStack | Self::RightMainVerticalStack => idx != 0 && idx != count - 1,
+                Self::HorizontalStack => idx == 0,
+                Self::UltrawideVerticalStack => idx > 1 && idx != count - 1,
+                Self::Grid => !is_grid_edge(op_direction, idx, count, layout_options),
+                Self::Scrolling => false,
+            },
+            OperationDirection::Left => match self {
+                Self::BSP => idx != 0,
+                Self::Columns | Self::VerticalStack => idx != 0,
+                Self::RightMainVerticalStack => idx == 0,
+                Self::Rows => false,
+                Self::HorizontalStack => idx != 0 && idx != 1,
+                Self::UltrawideVerticalStack => idx != 1,
+                Self::Grid => !is_grid_edge(op_direction, idx, count, layout_options),
+                Self::Scrolling => idx != 0,
+            },
+            OperationDirection::Right => match self {
+                Self::BSP => idx.is_multiple_of(2) && idx != count - 1,
+                Self::Columns => idx != count - 1,
+                Self::Rows => false,
+                Self::VerticalStack => idx == 0,
+                Self::RightMainVerticalStack => idx != 0,
+                Self::HorizontalStack => idx != 0 && idx != count - 1,
+                Self::UltrawideVerticalStack => match count {
+                    2 => idx != 0,
+                    _ => idx < 2,
+                },
+                Self::Grid => !is_grid_edge(op_direction, idx, count, layout_options),
+                Self::Scrolling => idx != count - 1,
+            },
+        }
+    }
+
+    fn up_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        match self {
+            Self::BSP => {
+                if idx.is_multiple_of(2) {
+                    idx - 1
+                } else {
+                    idx - 2
+                }
+            }
+            Self::Columns => unreachable!(),
+            Self::Rows
+            | Self::VerticalStack
+            | Self::UltrawideVerticalStack
+            | Self::RightMainVerticalStack => idx - 1,
+            Self::HorizontalStack => 0,
+            Self::Grid => grid_neighbor(op_direction, idx, count, layout_options),
+            Self::Scrolling => unreachable!(),
+        }
+    }
+
+    fn down_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        match self {
+            Self::BSP
+            | Self::Rows
+            | Self::VerticalStack
+            | Self::UltrawideVerticalStack
+            | Self::RightMainVerticalStack => idx + 1,
+            Self::Columns => unreachable!(),
+            Self::HorizontalStack => 1,
+            Self::Grid => grid_neighbor(op_direction, idx, count, layout_options),
+            Self::Scrolling => unreachable!(),
+        }
+    }
+
+    fn left_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        match self {
+            Self::BSP => {
+                if idx.is_multiple_of(2) {
+                    idx - 2
+                } else {
+                    idx - 1
+                }
+            }
+            Self::Columns | Self::HorizontalStack => idx - 1,
+            Self::Rows => unreachable!(),
+            Self::VerticalStack => 0,
+            Self::RightMainVerticalStack => 1,
+            Self::UltrawideVerticalStack => match idx {
+                0 => 1,
+                1 => unreachable!(),
+                _ => 0,
+            },
+            Self::Grid => grid_neighbor(op_direction, idx, count, layout_options),
+            Self::Scrolling => idx - 1,
+        }
+    }
+
+    fn right_index(
+        &self,
+        op_direction: Option<OperationDirection>,
+        idx: usize,
+        count: Option<usize>,
+        layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        match self {
+            Self::BSP | Self::Columns | Self::HorizontalStack => idx + 1,
+            Self::Rows => unreachable!(),
+            Self::VerticalStack => 1,
+            Self::RightMainVerticalStack => 0,
+            Self::UltrawideVerticalStack => match idx {
+                1 => 0,
+                0 => 2,
+                _ => unreachable!(),
+            },
+            Self::Grid => grid_neighbor(op_direction, idx, count, layout_options),
+            Self::Scrolling => idx + 1,
+        }
+    }
+}
+
+struct GridItem {
+    state: GridItemState,
+    row: usize,
+    num_rows: usize,
+    touching_edges: GridTouchingEdges,
+}
+
+enum GridItemState {
+    Valid,
+    Invalid,
+}
+
+#[allow(clippy::struct_excessive_bools)]
+struct GridTouchingEdges {
+    left: bool,
+    right: bool,
+    up: bool,
+    down: bool,
+}
+
+#[allow(
+    clippy::cast_possible_truncation,
+    clippy::cast_precision_loss,
+    clippy::cast_sign_loss
+)]
+fn get_grid_item(idx: usize, count: usize, layout_options: Option<LayoutOptions>) -> GridItem {
+    let row_constraint = layout_options.and_then(|o| o.grid.map(|g| g.rows));
+    let num_cols = if let Some(rows) = row_constraint {
+        ((count as f32) / (rows as f32)).ceil() as i32
+    } else {
+        (count as f32).sqrt().ceil() as i32
+    };
+
+    let mut iter = 0;
+
+    for col in 0..num_cols {
+        let remaining_windows = (count - iter) as i32;
+        let remaining_columns = num_cols - col;
+
+        let num_rows_in_this_col = if let Some(rows) = row_constraint {
+            (remaining_windows / remaining_columns).min(rows as i32)
+        } else {
+            remaining_windows / remaining_columns
+        };
+
+        for row in 0..num_rows_in_this_col {
+            if iter == idx {
+                return GridItem {
+                    state: GridItemState::Valid,
+                    row: (row + 1) as usize,
+                    num_rows: num_rows_in_this_col as usize,
+                    touching_edges: GridTouchingEdges {
+                        left: col == 0,
+                        right: col == num_cols - 1,
+                        up: row == 0,
+                        down: row == num_rows_in_this_col - 1,
+                    },
+                };
+            }
+
+            iter += 1;
+        }
+    }
+
+    GridItem {
+        state: GridItemState::Invalid,
+        row: 0,
+        num_rows: 0,
+        touching_edges: GridTouchingEdges {
+            left: true,
+            right: true,
+            up: true,
+            down: true,
+        },
+    }
+}
+
+fn is_grid_edge(
+    op_direction: OperationDirection,
+    idx: usize,
+    count: usize,
+    layout_options: Option<LayoutOptions>,
+) -> bool {
+    let item = get_grid_item(idx, count, layout_options);
+
+    match item.state {
+        GridItemState::Invalid => false,
+        GridItemState::Valid => match op_direction {
+            OperationDirection::Left => item.touching_edges.left,
+            OperationDirection::Right => item.touching_edges.right,
+            OperationDirection::Up => item.touching_edges.up,
+            OperationDirection::Down => item.touching_edges.down,
+        },
+    }
+}
+
+fn grid_neighbor(
+    op_direction: Option<OperationDirection>,
+    idx: usize,
+    count: Option<usize>,
+    layout_options: Option<LayoutOptions>,
+) -> usize {
+    let Some(op_direction) = op_direction else {
+        return 0;
+    };
+
+    let Some(count) = count else {
+        return 0;
+    };
+
+    let item = get_grid_item(idx, count, layout_options);
+
+    match op_direction {
+        OperationDirection::Left => {
+            let item_from_prev_col = get_grid_item(idx - item.row, count, layout_options);
+
+            if item.touching_edges.up && item.num_rows != item_from_prev_col.num_rows {
+                return idx - (item.num_rows - 1);
+            }
+
+            if item.num_rows != item_from_prev_col.num_rows && !item.touching_edges.down {
+                return idx - (item.num_rows - 1);
+            }
+
+            idx - item.num_rows
+        }
+        OperationDirection::Right => idx + item.num_rows,
+        OperationDirection::Up => idx - 1,
+        OperationDirection::Down => idx + 1,
+    }
+}
+
+impl Direction for CustomLayout {
+    fn index_in_direction(
+        &self,
+        op_direction: OperationDirection,
+        idx: usize,
+        count: usize,
+        layout_options: Option<LayoutOptions>,
+    ) -> Option<usize> {
+        if count <= self.len() {
+            return DefaultLayout::Columns.index_in_direction(
+                op_direction,
+                idx,
+                count,
+                layout_options,
+            );
+        }
+
+        match op_direction {
+            OperationDirection::Left => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.left_index(None, idx, None, layout_options))
+                } else {
+                    None
+                }
+            }
+            OperationDirection::Right => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.right_index(None, idx, None, layout_options))
+                } else {
+                    None
+                }
+            }
+            OperationDirection::Up => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.up_index(None, idx, None, layout_options))
+                } else {
+                    None
+                }
+            }
+            OperationDirection::Down => {
+                if self.is_valid_direction(op_direction, idx, count, layout_options) {
+                    Option::from(self.down_index(None, idx, None, layout_options))
+                } else {
+                    None
+                }
+            }
+        }
+    }
+
+    fn is_valid_direction(
+        &self,
+        op_direction: OperationDirection,
+        idx: usize,
+        count: usize,
+        layout_options: Option<LayoutOptions>,
+    ) -> bool {
+        if count <= self.len() {
+            return DefaultLayout::Columns.is_valid_direction(
+                op_direction,
+                idx,
+                count,
+                layout_options,
+            );
+        }
+
+        match op_direction {
+            OperationDirection::Left => idx != 0 && self.column_for_container_idx(idx) != 0,
+            OperationDirection::Right => {
+                idx != count - 1 && self.column_for_container_idx(idx) != self.len() - 1
+            }
+            OperationDirection::Up => {
+                if idx == 0 {
+                    return false;
+                }
+
+                let (column_idx, column) = self.column_with_idx(idx);
+                column.is_some_and(|column| match column {
+                    Column::Secondary(Some(ColumnSplitWithCapacity::Horizontal(_)))
+                    | Column::Tertiary(ColumnSplit::Horizontal) => {
+                        self.column_for_container_idx(idx - 1) == column_idx
+                    }
+                    _ => false,
+                })
+            }
+            OperationDirection::Down => {
+                if idx == count - 1 {
+                    return false;
+                }
+
+                let (column_idx, column) = self.column_with_idx(idx);
+                column.is_some_and(|column| match column {
+                    Column::Secondary(Some(ColumnSplitWithCapacity::Horizontal(_)))
+                    | Column::Tertiary(ColumnSplit::Horizontal) => {
+                        self.column_for_container_idx(idx + 1) == column_idx
+                    }
+                    _ => false,
+                })
+            }
+        }
+    }
+
+    fn up_index(
+        &self,
+        _op_direction: Option<OperationDirection>,
+        idx: usize,
+        _count: Option<usize>,
+        _layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        idx - 1
+    }
+
+    fn down_index(
+        &self,
+        _op_direction: Option<OperationDirection>,
+        idx: usize,
+        _count: Option<usize>,
+        _layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        idx + 1
+    }
+
+    fn left_index(
+        &self,
+        _op_direction: Option<OperationDirection>,
+        idx: usize,
+        _count: Option<usize>,
+        _layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        let column_idx = self.column_for_container_idx(idx);
+        if column_idx - 1 == 0 {
+            0
+        } else {
+            self.first_container_idx(column_idx - 1)
+        }
+    }
+
+    fn right_index(
+        &self,
+        _op_direction: Option<OperationDirection>,
+        idx: usize,
+        _count: Option<usize>,
+        _layout_options: Option<LayoutOptions>,
+    ) -> usize {
+        let column_idx = self.column_for_container_idx(idx);
+        self.first_container_idx(column_idx + 1)
+    }
+}

komorebi-layouts/src/layout.rs

@@ -0,0 +1,32 @@
+use serde::Deserialize;
+use serde::Serialize;
+
+use super::Arrangement;
+use super::CustomLayout;
+use super::DefaultLayout;
+use super::Direction;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub enum Layout {
+    Default(DefaultLayout),
+    Custom(CustomLayout),
+}
+
+impl Layout {
+    #[must_use]
+    pub fn as_boxed_direction(&self) -> Box<dyn Direction> {
+        match self {
+            Layout::Default(layout) => Box::new(*layout),
+            Layout::Custom(layout) => Box::new(layout.clone()),
+        }
+    }
+
+    #[must_use]
+    pub fn as_boxed_arrangement(&self) -> Box<dyn Arrangement> {
+        match self {
+            Layout::Default(layout) => Box::new(*layout),
+            Layout::Custom(layout) => Box::new(layout.clone()),
+        }
+    }
+}

komorebi-layouts/src/lib.rs

@@ -0,0 +1,28 @@
+#![warn(clippy::all)]
+#![allow(clippy::missing_errors_doc, clippy::use_self, clippy::doc_markdown)]
+
+//! Layout system for the komorebi window manager.
+//!
+//! This crate provides the core layout algorithms and types for arranging windows
+//! in various configurations. It includes optional Windows-specific functionality
+//! behind the `win32` feature flag.
+
+pub mod arrangement;
+pub mod custom_layout;
+pub mod cycle_direction;
+pub mod default_layout;
+pub mod direction;
+pub mod layout;
+pub mod operation_direction;
+pub mod rect;
+pub mod sizing;
+
+pub use arrangement::*;
+pub use custom_layout::*;
+pub use cycle_direction::*;
+pub use default_layout::*;
+pub use direction::*;
+pub use layout::*;
+pub use operation_direction::*;
+pub use rect::*;
+pub use sizing::*;

komorebi-layouts/src/operation_direction.rs

@@ -0,0 +1,64 @@
+use std::num::NonZeroUsize;
+
+use super::Axis;
+use super::direction::Direction;
+use crate::default_layout::LayoutOptions;
+use clap::ValueEnum;
+use serde::Deserialize;
+use serde::Serialize;
+use strum::Display;
+use strum::EnumString;
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Display, EnumString, ValueEnum)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+pub enum OperationDirection {
+    Left,
+    Right,
+    Up,
+    Down,
+}
+
+impl OperationDirection {
+    #[must_use]
+    pub const fn opposite(self) -> Self {
+        match self {
+            Self::Left => Self::Right,
+            Self::Right => Self::Left,
+            Self::Up => Self::Down,
+            Self::Down => Self::Up,
+        }
+    }
+
+    fn flip(self, layout_flip: Option<Axis>) -> Self {
+        layout_flip.map_or(self, |flip| match self {
+            Self::Left => match flip {
+                Axis::Horizontal | Axis::HorizontalAndVertical => Self::Right,
+                Axis::Vertical => self,
+            },
+            Self::Right => match flip {
+                Axis::Horizontal | Axis::HorizontalAndVertical => Self::Left,
+                Axis::Vertical => self,
+            },
+            Self::Up => match flip {
+                Axis::Vertical | Axis::HorizontalAndVertical => Self::Down,
+                Axis::Horizontal => self,
+            },
+            Self::Down => match flip {
+                Axis::Vertical | Axis::HorizontalAndVertical => Self::Up,
+                Axis::Horizontal => self,
+            },
+        })
+    }
+
+    #[must_use]
+    pub fn destination(
+        self,
+        layout: &dyn Direction,
+        layout_flip: Option<Axis>,
+        idx: usize,
+        len: NonZeroUsize,
+        layout_options: Option<LayoutOptions>,
+    ) -> Option<usize> {
+        layout.index_in_direction(self.flip(layout_flip), idx, len.get(), layout_options)
+    }
+}

komorebi-layouts/src/rect.rs

@@ -0,0 +1,113 @@
+use serde::Deserialize;
+use serde::Serialize;
+
+#[cfg(feature = "win32")]
+use windows::Win32::Foundation::RECT;
+
+#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize, Eq, PartialEq)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+/// Rectangle dimensions
+pub struct Rect {
+    /// Left point of the rectangle
+    pub left: i32,
+    /// Top point of the rectangle
+    pub top: i32,
+    /// Width of the recentangle (from the left point)
+    pub right: i32,
+    /// Height of the rectangle (from the top point)
+    pub bottom: i32,
+}
+
+#[cfg(feature = "win32")]
+impl From<RECT> for Rect {
+    fn from(rect: RECT) -> Self {
+        Self {
+            left: rect.left,
+            top: rect.top,
+            right: rect.right - rect.left,
+            bottom: rect.bottom - rect.top,
+        }
+    }
+}
+
+#[cfg(feature = "win32")]
+impl From<Rect> for RECT {
+    fn from(rect: Rect) -> Self {
+        Self {
+            left: rect.left,
+            top: rect.top,
+            right: rect.right,
+            bottom: rect.bottom,
+        }
+    }
+}
+
+impl Rect {
+    pub fn is_same_size_as(&self, rhs: &Self) -> bool {
+        self.right == rhs.right && self.bottom == rhs.bottom
+    }
+
+    pub fn has_same_position_as(&self, rhs: &Self) -> bool {
+        self.left == rhs.left && self.top == rhs.top
+    }
+}
+
+impl Rect {
+    /// decrease the size of self by the padding amount.
+    pub fn add_padding<T>(&mut self, padding: T)
+    where
+        T: Into<Option<i32>>,
+    {
+        if let Some(padding) = padding.into() {
+            self.left += padding;
+            self.top += padding;
+            self.right -= padding * 2;
+            self.bottom -= padding * 2;
+        }
+    }
+
+    /// increase the size of self by the margin amount.
+    pub fn add_margin(&mut self, margin: i32) {
+        self.left -= margin;
+        self.top -= margin;
+        self.right += margin * 2;
+        self.bottom += margin * 2;
+    }
+
+    pub fn left_padding(&mut self, padding: i32) {
+        self.left += padding;
+    }
+
+    pub fn right_padding(&mut self, padding: i32) {
+        self.right -= padding;
+    }
+
+    #[must_use]
+    pub const fn contains_point(&self, point: (i32, i32)) -> bool {
+        point.0 >= self.left
+            && point.0 <= self.left + self.right
+            && point.1 >= self.top
+            && point.1 <= self.top + self.bottom
+    }
+
+    #[must_use]
+    pub const fn scale(&self, system_dpi: i32, rect_dpi: i32) -> Rect {
+        Rect {
+            left: (self.left * rect_dpi) / system_dpi,
+            top: (self.top * rect_dpi) / system_dpi,
+            right: (self.right * rect_dpi) / system_dpi,
+            bottom: (self.bottom * rect_dpi) / system_dpi,
+        }
+    }
+
+    #[cfg(feature = "win32")]
+    #[must_use]
+    pub const fn rect(&self) -> RECT {
+        RECT {
+            left: self.left,
+            top: self.top,
+            right: self.left + self.right,
+            bottom: self.top + self.bottom,
+        }
+    }
+}

komorebi-layouts/src/sizing.rs

@@ -0,0 +1,31 @@
+use clap::ValueEnum;
+use serde::Deserialize;
+use serde::Serialize;
+use strum::Display;
+use strum::EnumString;
+
+#[derive(Clone, Copy, Debug, Serialize, Deserialize, Display, EnumString, ValueEnum)]
+#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
+/// Sizing
+pub enum Sizing {
+    /// Increase
+    Increase,
+    /// Decrease
+    Decrease,
+}
+
+impl Sizing {
+    #[must_use]
+    pub const fn adjust_by(&self, value: i32, adjustment: i32) -> i32 {
+        match self {
+            Self::Increase => value + adjustment,
+            Self::Decrease => {
+                if value > 0 && value - adjustment >= 0 {
+                    value - adjustment
+                } else {
+                    value
+                }
+            }
+        }
+    }
+}