From 23e280a6b4da267b522d5d87d66b153c43325a82 Mon Sep 17 00:00:00 2001
From: Samuel Onoja <samiodev@icloud.com>
Date: Thu, 22 Oct 2026 00:55:17 +0100
Subject: [PATCH] Separate library implementations from module declarations

---
 crates/ferese-activities/src/lib.rs           |  626 +-----
 crates/ferese-activities/src/store.rs         |  624 ++++++
 crates/ferese-animation/src/lib.rs            | 1171 +---------
 .../ferese-animation/src/window_geometry.rs   | 1166 ++++++++++
 .../src/{ => window_geometry}/traces.rs       |    0
 crates/ferese-config/src/activities.rs        |   29 +-
 crates/ferese-config/src/document.rs          | 1171 ++++++++++
 crates/ferese-config/src/lib.rs               | 1155 +---------
 crates/ferese-ipc/src/frame.rs                |  206 ++
 crates/ferese-ipc/src/lib.rs                  |  211 +-
 crates/ferese-layout/src/layout_tree.rs       | 1929 ++++++++++++++++
 crates/ferese-layout/src/lib.rs               | 1933 +----------------
 crates/ferese-layout/src/scrolling.rs         |   29 +-
 crates/ferese-panel/src/panel.rs              |  927 +-------
 crates/ferese-panel/src/panel/composition.rs  |  923 ++++++++
 crates/ferese-theme-model/src/lib.rs          |  180 +-
 .../ferese-theme-model/src/resolved_theme.rs  |  177 ++
 docs/animation-model.md                       |    4 +-
 feresectl/src/activities/setup.rs             |    2 +-
 19 files changed, 6250 insertions(+), 6213 deletions(-)
 create mode 100644 crates/ferese-activities/src/store.rs
 create mode 100644 crates/ferese-animation/src/window_geometry.rs
 rename crates/ferese-animation/src/{ => window_geometry}/traces.rs (100%)
 create mode 100644 crates/ferese-config/src/document.rs
 create mode 100644 crates/ferese-ipc/src/frame.rs
 create mode 100644 crates/ferese-layout/src/layout_tree.rs
 create mode 100644 crates/ferese-panel/src/panel/composition.rs
 create mode 100644 crates/ferese-theme-model/src/resolved_theme.rs

diff --git a/crates/ferese-activities/src/lib.rs b/crates/ferese-activities/src/lib.rs
index 500e4e3..893cad2 100644
--- a/crates/ferese-activities/src/lib.rs
+++ b/crates/ferese-activities/src/lib.rs
@@ -1,631 +1,9 @@
 //! Typed activity data and deterministic policy. The host supplies verified owners
 //! and suspend-aware milliseconds; this crate performs no I/O or rendering.
 pub mod pomodoro;
+mod store;
 
-use std::collections::BTreeMap;
-
-use serde::{Deserialize, Serialize};
-
-pub type Time = u64;
-const BOOST_MS: u64 = 5_000;
-pub const MAX_TEXT: usize = 256;
-pub const MAX_LEASE_MS: u64 = 300_000;
-
-#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Deserialize, Serialize)]
-#[serde(deny_unknown_fields)]
-pub struct Owner {
-    pub pid: u32,
-    pub birth: u64,
-}
-
-#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Deserialize, Serialize)]
-#[serde(deny_unknown_fields)]
-pub struct Id {
-    pub owner: Owner,
-    pub local: String,
-    pub generation: u64,
-    pub session: u64,
-}
-
-#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
-#[serde(
-    tag = "kind",
-    content = "value",
-    rename_all = "kebab-case",
-    deny_unknown_fields
-)]
-pub enum Value {
-    Indeterminate,
-    Progress(f32),
-    Text(String),
-    Countdown { remaining_ms: u64, sampled_at: Time },
-    PausedCountdown { remaining_ms: u64 },
-}
-
-impl Value {
-    pub fn remaining_ms(&self, now: Time) -> Option<u64> {
-        match self {
-            Self::Countdown {
-                remaining_ms,
-                sampled_at,
-            } => Some(remaining_ms.saturating_sub(now.saturating_sub(*sampled_at))),
-            Self::PausedCountdown { remaining_ms } => Some(*remaining_ms),
-            _ => None,
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
-#[serde(
-    tag = "kind",
-    content = "data",
-    rename_all = "kebab-case",
-    deny_unknown_fields
-)]
-pub enum Template {
-    Progress,
-    Timer,
-    Media { artist: String, playing: bool },
-    List { rows: Vec<String> },
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Deserialize, Serialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum Source {
-    Publisher,
-    Command,
-    Media,
-    Capture,
-    Download,
-    Timer,
-    Notification,
-    Process,
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq, Deserialize, Serialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum State {
-    Running,
-    Done,
-    Failed,
-    Cancelled,
-}
-
-#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
-#[serde(deny_unknown_fields)]
-pub struct Data {
-    pub source: Source,
-    pub output: Option<String>,
-    pub priority: u8,
-    pub icon: String,
-    pub title: String,
-    pub value: Value,
-    pub template: Template,
-}
-
-impl Data {
-    pub fn validate(&mut self, now: Time) -> Result<(), &'static str> {
-        text(&self.title)?;
-        if self
-            .output
-            .as_ref()
-            .is_some_and(|output| text(output).is_err())
-        {
-            return Err("invalid output name");
-        }
-        if self.icon.len() > 64
-            || !self
-                .icon
-                .bytes()
-                .all(|b| b.is_ascii_alphanumeric() || b == b'-')
-        {
-            return Err("icon must be a symbolic name");
-        }
-        if !matches!(
-            self.icon.as_str(),
-            "hammer"
-                | "timer"
-                | "download"
-                | "media"
-                | "microphone"
-                | "camera"
-                | "call"
-                | "notification"
-                | "ferese"
-        ) {
-            self.icon = "ferese".into();
-        }
-        match &mut self.value {
-            Value::Progress(progress)
-                if !progress.is_finite() || !(0.0..=1.0).contains(progress) =>
-            {
-                return Err("progress must be finite and between zero and one");
-            }
-            Value::Text(value) => text(value)?,
-            Value::PausedCountdown { remaining_ms } if *remaining_ms > 7 * 24 * 60 * 60 * 1_000 => {
-                return Err("countdown exceeds seven days");
-            }
-            Value::Countdown {
-                remaining_ms,
-                sampled_at,
-            } => {
-                if *remaining_ms > 7 * 24 * 60 * 60 * 1_000 {
-                    return Err("countdown exceeds seven days");
-                }
-                *sampled_at = now;
-            }
-            _ => {}
-        }
-        match &self.template {
-            Template::Timer
-                if !matches!(
-                    self.value,
-                    Value::Countdown { .. } | Value::PausedCountdown { .. }
-                ) =>
-            {
-                return Err("timer requires a countdown");
-            }
-            Template::Progress
-                if matches!(
-                    self.value,
-                    Value::Countdown { .. } | Value::PausedCountdown { .. }
-                ) =>
-            {
-                return Err("countdown requires timer template");
-            }
-            Template::Media { artist, .. } => {
-                text(artist)?;
-                if !matches!(
-                    self.value,
-                    Value::Text(_) | Value::Indeterminate | Value::Progress(_)
-                ) {
-                    return Err("invalid media value");
-                }
-            }
-            Template::List { rows } => {
-                if rows.len() > 8 {
-                    return Err("list exceeds eight rows");
-                }
-                for row in rows {
-                    text(row)?;
-                }
-                if !matches!(self.value, Value::Text(_) | Value::Indeterminate) {
-                    return Err("invalid list value");
-                }
-            }
-            _ => {}
-        }
-        Ok(())
-    }
-}
-
-fn text(value: &str) -> Result<(), &'static str> {
-    if value.len() > MAX_TEXT || value.chars().any(char::is_control) {
-        Err("text exceeds its budget or contains control characters")
-    } else {
-        Ok(())
-    }
-}
-
-#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
-#[serde(default, deny_unknown_fields)]
-pub struct Limits {
-    pub max_visible: usize,
-    pub show_badge: bool,
-    pub max_total: usize,
-    pub owner_ceiling: u8,
-    pub start_delay_ms: u64,
-    pub result_flash_ms: u64,
-}
-
-impl Default for Limits {
-    fn default() -> Self {
-        Self {
-            max_visible: 2,
-            show_badge: true,
-            max_total: 128,
-            owner_ceiling: 160,
-            start_delay_ms: 300,
-            result_flash_ms: 1_500,
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
-pub struct Activity {
-    pub id: Id,
-    pub data: Data,
-    pub state: State,
-    pub created_at: Time,
-    pub eligible_at: Time,
-    pub refreshed_at: Time,
-    pub lease_deadline: Option<Time>,
-    pub result_deadline: Option<Time>,
-    pub result_message: Option<String>,
-    pub flash_on_fail: bool,
-    pub result_flash_ms: u64,
-    /// A presentation group only; every invocation retains its own lifetime.
-    pub group: Option<String>,
-}
-
-impl Activity {
-    pub fn eligible(&self, now: Time, dnd: bool) -> bool {
-        now >= self.eligible_at
-            && match self.state {
-                State::Running => self.lease_deadline.is_none_or(|deadline| now < deadline),
-                State::Done | State::Failed => {
-                    !dnd && self.result_deadline.is_some_and(|deadline| now < deadline)
-                }
-                State::Cancelled => false,
-            }
-    }
-
-    pub fn score(&self, now: Time, ceiling: u8) -> u16 {
-        u16::from(self.data.priority.min(ceiling))
-            + if now < self.eligible_at.saturating_add(BOOST_MS) {
-                30
-            } else {
-                0
-            }
-            + match self.state {
-                State::Failed => 100,
-                State::Done => 40,
-                _ => 0,
-            }
-    }
-}
-
-#[derive(Debug)]
-pub struct Store {
-    pub limits: Limits,
-    session: u64,
-    generation: u64,
-    entries: BTreeMap<Id, Activity>,
-}
-
-impl Store {
-    pub fn new(session: u64) -> Self {
-        Self {
-            limits: Limits::default(),
-            session,
-            generation: 0,
-            entries: BTreeMap::new(),
-        }
-    }
-
-    pub fn session(&self) -> u64 {
-        self.session
-    }
-
-    pub fn entries(&self) -> impl Iterator<Item = &Activity> {
-        self.entries.values()
-    }
-
-    pub fn resolve(&self, owner: Owner, local: &str) -> Option<&Id> {
-        self.entries
-            .keys()
-            .find(|id| id.owner == owner && id.local == local)
-    }
-
-    #[allow(clippy::too_many_arguments)]
-    pub fn start(
-        &mut self,
-        owner: Owner,
-        local: String,
-        mut data: Data,
-        now: Time,
-        min_duration_ms: u64,
-        lease_ms: Option<u64>,
-        monitored: bool,
-        flash_on_fail: bool,
-        group: Option<String>,
-    ) -> Result<Id, &'static str> {
-        self.advance(now);
-        text(&local)?;
-        if local.is_empty() {
-            return Err("activity ID must not be empty");
-        }
-        data.validate(now)?;
-        validate_lease(lease_ms, monitored)?;
-        if self.resolve(owner, &local).is_some() {
-            return Err("duplicate activity ID");
-        }
-        if self.entries.len() >= self.limits.max_total {
-            return Err("session activity quota exceeded");
-        }
-        if self.entries.keys().filter(|id| id.owner == owner).count() >= 3 {
-            return Err("owner activity quota exceeded");
-        }
-        self.generation = self
-            .generation
-            .checked_add(1)
-            .ok_or("generation exhausted")?;
-        let id = Id {
-            owner,
-            local,
-            generation: self.generation,
-            session: self.session,
-        };
-        self.entries.insert(
-            id.clone(),
-            Activity {
-                id: id.clone(),
-                data,
-                state: State::Running,
-                created_at: now,
-                eligible_at: now.saturating_add(self.limits.start_delay_ms.max(min_duration_ms)),
-                refreshed_at: now,
-                lease_deadline: lease_ms.map(|ms| now.saturating_add(ms)),
-                result_deadline: None,
-                result_message: None,
-                flash_on_fail,
-                result_flash_ms: self.limits.result_flash_ms,
-                group,
-            },
-        );
-        Ok(id)
-    }
-
-    fn entry(&mut self, owner: Owner, id: &Id) -> Result<&mut Activity, &'static str> {
-        if id.session != self.session {
-            return Err("stale activity session; register again");
-        }
-        if id.owner != owner {
-            return Err("activity owner rejected");
-        }
-        self.entries.get_mut(id).ok_or("stale activity generation")
-    }
-
-    pub fn update(
-        &mut self,
-        owner: Owner,
-        id: &Id,
-        value: Option<Value>,
-        lease_ms: Option<u64>,
-        now: Time,
-    ) -> Result<(), &'static str> {
-        self.advance(now);
-        validate_lease(lease_ms, true)?;
-        let entry = self.entry(owner, id)?;
-        if entry.state != State::Running {
-            return Err("activity already completed");
-        }
-        if let Some(value) = value {
-            let mut candidate = entry.data.clone();
-            candidate.value = value;
-            candidate.validate(now)?;
-            entry.data = candidate;
-        }
-        if let Some(ms) = lease_ms {
-            validate_lease(Some(ms), true)?;
-            entry.lease_deadline = Some(now.saturating_add(ms));
-        } else if let Some(deadline) = entry.lease_deadline {
-            entry.lease_deadline =
-                Some(now.saturating_add(deadline.saturating_sub(entry.refreshed_at)));
-        }
-        entry.refreshed_at = now;
-        Ok(())
-    }
-
-    pub fn finish(
-        &mut self,
-        owner: Owner,
-        id: &Id,
-        state: State,
-        message: Option<String>,
-        now: Time,
-    ) -> Result<(), &'static str> {
-        self.advance(now);
-        if state == State::Running {
-            return Err("finish requires a terminal result");
-        }
-        if let Some(message) = &message {
-            text(message)?;
-        }
-        let entry = self.entry(owner, id)?;
-        if entry.state != State::Running {
-            return if entry.state == state {
-                Ok(())
-            } else {
-                Err("terminal result already accepted")
-            };
-        }
-        if state == State::Cancelled
-            || now < entry.eligible_at
-            || (state == State::Failed && !entry.flash_on_fail)
-        {
-            self.entries.remove(id);
-            return Ok(());
-        }
-        entry.state = state;
-        if let Some(message) = message {
-            entry.result_message = Some(message);
-        }
-        entry.result_deadline = Some(now.saturating_add(entry.result_flash_ms));
-        Ok(())
-    }
-
-    pub fn owner_exit(&mut self, owner: Owner) {
-        self.entries
-            .retain(|id, entry| id.owner != owner || entry.state != State::Running);
-    }
-
-    pub fn remove_output(&mut self, output: &str, fallback: Option<&str>) {
-        for entry in self
-            .entries
-            .values_mut()
-            .filter(|entry| entry.data.output.as_deref() == Some(output))
-        {
-            entry.data.output = fallback.map(str::to_owned);
-        }
-    }
-
-    pub fn attach_output(&mut self, output: &str) -> bool {
-        let mut changed = false;
-        for entry in self
-            .entries
-            .values_mut()
-            .filter(|entry| entry.data.output.is_none())
-        {
-            entry.data.output = Some(output.into());
-            changed = true;
-        }
-        changed
-    }
-    pub fn advance(&mut self, now: Time) -> bool {
-        let before = self.entries.len();
-        self.entries.retain(|_, entry| match entry.state {
-            State::Running => entry.lease_deadline.is_none_or(|deadline| now < deadline),
-            _ => entry.result_deadline.is_some_and(|deadline| now < deadline),
-        });
-        before != self.entries.len()
-    }
-
-    pub fn next_deadline(&self, now: Time) -> Option<Time> {
-        self.entries
-            .values()
-            .flat_map(|entry| {
-                [
-                    Some(entry.eligible_at),
-                    Some(entry.eligible_at.saturating_add(BOOST_MS)),
-                    entry.lease_deadline,
-                    entry.result_deadline,
-                    entry.result_deadline.map(|deadline| {
-                        deadline
-                            .saturating_sub(entry.result_flash_ms)
-                            .saturating_add(400)
-                    }),
-                ]
-            })
-            .flatten()
-            .filter(|deadline| *deadline > now)
-            .min()
-    }
-}
-
-fn validate_lease(lease: Option<u64>, monitored: bool) -> Result<(), &'static str> {
-    match lease {
-        Some(0) => Err("lease must be positive"),
-        Some(ms) if ms > MAX_LEASE_MS => Err("lease exceeds five minutes"),
-        None if !monitored => Err("unmonitored owner requires a lease"),
-        _ => Ok(()),
-    }
-}
-
-/// Recording/battery occupy a separate host-only class. Notifications always
-/// follow every other ordinary source, even when a result boost is active.
-pub fn ranked<'a>(
-    entries: impl IntoIterator<Item = &'a Activity>,
-    now: Time,
-    limits: Limits,
-    output: &str,
-    dnd: bool,
-) -> Vec<&'a Activity> {
-    let mut entries: Vec<_> = entries
-        .into_iter()
-        .filter(|entry| entry.eligible(now, dnd) && entry.data.output.as_deref() == Some(output))
-        .collect();
-    entries.sort_by(|a, b| {
-        (a.data.source == Source::Notification)
-            .cmp(&(b.data.source == Source::Notification))
-            .then_with(|| {
-                b.score(now, limits.owner_ceiling)
-                    .cmp(&a.score(now, limits.owner_ceiling))
-            })
-            .then_with(|| a.eligible_at.cmp(&b.eligible_at))
-            .then_with(|| a.id.cmp(&b.id))
-    });
-    entries
-}
-
-#[derive(Clone, Debug, Default)]
-pub struct Selection {
-    pinned: Option<Vec<Id>>,
-    pub visible: Vec<Id>,
-    pub hidden: usize,
-    policy: Option<(bool, usize, usize)>,
-}
-
-impl Selection {
-    pub fn enter(&mut self) {
-        self.pinned = Some(self.visible.clone());
-    }
-    pub fn leave(&mut self) {
-        self.pinned = None;
-    }
-    pub fn override_pin(&mut self) {
-        self.pinned = None;
-    }
-    pub fn select(
-        &mut self,
-        ranked: &[&Activity],
-        limits: Limits,
-        dnd: bool,
-        protected_slots: usize,
-    ) {
-        let policy = (dnd, protected_slots, limits.max_visible);
-        if self.policy != Some(policy) {
-            self.override_pin();
-            self.policy = Some(policy);
-        }
-        let count = limits
-            .max_visible
-            .clamp(1, 2)
-            .saturating_sub(protected_slots)
-            .min(if dnd { 1 } else { 2 });
-        let eligible: Vec<_> = ranked
-            .iter()
-            .filter(|entry| !dnd || entry.state == State::Running)
-            .collect();
-        let mut groups = std::collections::BTreeSet::new();
-        let ids: Vec<_> = eligible
-            .iter()
-            .filter(|entry| {
-                let Some(group) = &entry.group else {
-                    return true;
-                };
-                if entry.state != State::Running
-                    && eligible.iter().any(|other| {
-                        other.id.owner == entry.id.owner
-                            && other.group.as_ref() == Some(group)
-                            && other.state == State::Running
-                    })
-                {
-                    return false;
-                }
-                groups.insert((entry.id.owner, group.clone()))
-            })
-            .map(|entry| entry.id.clone())
-            .collect();
-        self.visible = match &mut self.pinned {
-            Some(pinned) => {
-                pinned.retain(|id| ids.contains(id));
-                pinned.iter().take(count).cloned().collect()
-            }
-            None => ids.iter().take(count).cloned().collect(),
-        };
-        self.hidden = if dnd || !limits.show_badge {
-            0
-        } else {
-            eligible.len().saturating_sub(self.visible.len())
-        };
-    }
-}
-
-/// Focus survives reordered/updated rows by identity; removal chooses the next
-/// surviving row at the former position.
-pub fn reconcile_focus(focus: &mut Option<Id>, previous: &[Id], current: &[Id]) {
-    if focus.as_ref().is_some_and(|id| current.contains(id)) {
-        return;
-    }
-    let index = focus
-        .as_ref()
-        .and_then(|id| previous.iter().position(|old| old == id))
-        .unwrap_or(0);
-    *focus = current
-        .get(index.min(current.len().saturating_sub(1)))
-        .cloned();
-}
+pub use store::*;
 
 #[cfg(test)]
 mod tests;
diff --git a/crates/ferese-activities/src/store.rs b/crates/ferese-activities/src/store.rs
new file mode 100644
index 0000000..83b357b
--- /dev/null
+++ b/crates/ferese-activities/src/store.rs
@@ -0,0 +1,624 @@
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+pub type Time = u64;
+const BOOST_MS: u64 = 5_000;
+pub const MAX_TEXT: usize = 256;
+pub const MAX_LEASE_MS: u64 = 300_000;
+
+#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Owner {
+    pub pid: u32,
+    pub birth: u64,
+}
+
+#[derive(Clone, Debug, Eq, Ord, PartialEq, PartialOrd, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Id {
+    pub owner: Owner,
+    pub local: String,
+    pub generation: u64,
+    pub session: u64,
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(
+    tag = "kind",
+    content = "value",
+    rename_all = "kebab-case",
+    deny_unknown_fields
+)]
+pub enum Value {
+    Indeterminate,
+    Progress(f32),
+    Text(String),
+    Countdown { remaining_ms: u64, sampled_at: Time },
+    PausedCountdown { remaining_ms: u64 },
+}
+
+impl Value {
+    pub fn remaining_ms(&self, now: Time) -> Option<u64> {
+        match self {
+            Self::Countdown {
+                remaining_ms,
+                sampled_at,
+            } => Some(remaining_ms.saturating_sub(now.saturating_sub(*sampled_at))),
+            Self::PausedCountdown { remaining_ms } => Some(*remaining_ms),
+            _ => None,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(
+    tag = "kind",
+    content = "data",
+    rename_all = "kebab-case",
+    deny_unknown_fields
+)]
+pub enum Template {
+    Progress,
+    Timer,
+    Media { artist: String, playing: bool },
+    List { rows: Vec<String> },
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Source {
+    Publisher,
+    Command,
+    Media,
+    Capture,
+    Download,
+    Timer,
+    Notification,
+    Process,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum State {
+    Running,
+    Done,
+    Failed,
+    Cancelled,
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Data {
+    pub source: Source,
+    pub output: Option<String>,
+    pub priority: u8,
+    pub icon: String,
+    pub title: String,
+    pub value: Value,
+    pub template: Template,
+}
+
+impl Data {
+    pub fn validate(&mut self, now: Time) -> Result<(), &'static str> {
+        text(&self.title)?;
+        if self
+            .output
+            .as_ref()
+            .is_some_and(|output| text(output).is_err())
+        {
+            return Err("invalid output name");
+        }
+        if self.icon.len() > 64
+            || !self
+                .icon
+                .bytes()
+                .all(|b| b.is_ascii_alphanumeric() || b == b'-')
+        {
+            return Err("icon must be a symbolic name");
+        }
+        if !matches!(
+            self.icon.as_str(),
+            "hammer"
+                | "timer"
+                | "download"
+                | "media"
+                | "microphone"
+                | "camera"
+                | "call"
+                | "notification"
+                | "ferese"
+        ) {
+            self.icon = "ferese".into();
+        }
+        match &mut self.value {
+            Value::Progress(progress)
+                if !progress.is_finite() || !(0.0..=1.0).contains(progress) =>
+            {
+                return Err("progress must be finite and between zero and one");
+            }
+            Value::Text(value) => text(value)?,
+            Value::PausedCountdown { remaining_ms } if *remaining_ms > 7 * 24 * 60 * 60 * 1_000 => {
+                return Err("countdown exceeds seven days");
+            }
+            Value::Countdown {
+                remaining_ms,
+                sampled_at,
+            } => {
+                if *remaining_ms > 7 * 24 * 60 * 60 * 1_000 {
+                    return Err("countdown exceeds seven days");
+                }
+                *sampled_at = now;
+            }
+            _ => {}
+        }
+        match &self.template {
+            Template::Timer
+                if !matches!(
+                    self.value,
+                    Value::Countdown { .. } | Value::PausedCountdown { .. }
+                ) =>
+            {
+                return Err("timer requires a countdown");
+            }
+            Template::Progress
+                if matches!(
+                    self.value,
+                    Value::Countdown { .. } | Value::PausedCountdown { .. }
+                ) =>
+            {
+                return Err("countdown requires timer template");
+            }
+            Template::Media { artist, .. } => {
+                text(artist)?;
+                if !matches!(
+                    self.value,
+                    Value::Text(_) | Value::Indeterminate | Value::Progress(_)
+                ) {
+                    return Err("invalid media value");
+                }
+            }
+            Template::List { rows } => {
+                if rows.len() > 8 {
+                    return Err("list exceeds eight rows");
+                }
+                for row in rows {
+                    text(row)?;
+                }
+                if !matches!(self.value, Value::Text(_) | Value::Indeterminate) {
+                    return Err("invalid list value");
+                }
+            }
+            _ => {}
+        }
+        Ok(())
+    }
+}
+
+fn text(value: &str) -> Result<(), &'static str> {
+    if value.len() > MAX_TEXT || value.chars().any(char::is_control) {
+        Err("text exceeds its budget or contains control characters")
+    } else {
+        Ok(())
+    }
+}
+
+#[derive(Clone, Copy, Debug, Deserialize, Serialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct Limits {
+    pub max_visible: usize,
+    pub show_badge: bool,
+    pub max_total: usize,
+    pub owner_ceiling: u8,
+    pub start_delay_ms: u64,
+    pub result_flash_ms: u64,
+}
+
+impl Default for Limits {
+    fn default() -> Self {
+        Self {
+            max_visible: 2,
+            show_badge: true,
+            max_total: 128,
+            owner_ceiling: 160,
+            start_delay_ms: 300,
+            result_flash_ms: 1_500,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+pub struct Activity {
+    pub id: Id,
+    pub data: Data,
+    pub state: State,
+    pub created_at: Time,
+    pub eligible_at: Time,
+    pub refreshed_at: Time,
+    pub lease_deadline: Option<Time>,
+    pub result_deadline: Option<Time>,
+    pub result_message: Option<String>,
+    pub flash_on_fail: bool,
+    pub result_flash_ms: u64,
+    /// A presentation group only; every invocation retains its own lifetime.
+    pub group: Option<String>,
+}
+
+impl Activity {
+    pub fn eligible(&self, now: Time, dnd: bool) -> bool {
+        now >= self.eligible_at
+            && match self.state {
+                State::Running => self.lease_deadline.is_none_or(|deadline| now < deadline),
+                State::Done | State::Failed => {
+                    !dnd && self.result_deadline.is_some_and(|deadline| now < deadline)
+                }
+                State::Cancelled => false,
+            }
+    }
+
+    pub fn score(&self, now: Time, ceiling: u8) -> u16 {
+        u16::from(self.data.priority.min(ceiling))
+            + if now < self.eligible_at.saturating_add(BOOST_MS) {
+                30
+            } else {
+                0
+            }
+            + match self.state {
+                State::Failed => 100,
+                State::Done => 40,
+                _ => 0,
+            }
+    }
+}
+
+#[derive(Debug)]
+pub struct Store {
+    pub limits: Limits,
+    session: u64,
+    generation: u64,
+    entries: BTreeMap<Id, Activity>,
+}
+
+impl Store {
+    pub fn new(session: u64) -> Self {
+        Self {
+            limits: Limits::default(),
+            session,
+            generation: 0,
+            entries: BTreeMap::new(),
+        }
+    }
+
+    pub fn session(&self) -> u64 {
+        self.session
+    }
+
+    pub fn entries(&self) -> impl Iterator<Item = &Activity> {
+        self.entries.values()
+    }
+
+    pub fn resolve(&self, owner: Owner, local: &str) -> Option<&Id> {
+        self.entries
+            .keys()
+            .find(|id| id.owner == owner && id.local == local)
+    }
+
+    #[allow(clippy::too_many_arguments)]
+    pub fn start(
+        &mut self,
+        owner: Owner,
+        local: String,
+        mut data: Data,
+        now: Time,
+        min_duration_ms: u64,
+        lease_ms: Option<u64>,
+        monitored: bool,
+        flash_on_fail: bool,
+        group: Option<String>,
+    ) -> Result<Id, &'static str> {
+        self.advance(now);
+        text(&local)?;
+        if local.is_empty() {
+            return Err("activity ID must not be empty");
+        }
+        data.validate(now)?;
+        validate_lease(lease_ms, monitored)?;
+        if self.resolve(owner, &local).is_some() {
+            return Err("duplicate activity ID");
+        }
+        if self.entries.len() >= self.limits.max_total {
+            return Err("session activity quota exceeded");
+        }
+        if self.entries.keys().filter(|id| id.owner == owner).count() >= 3 {
+            return Err("owner activity quota exceeded");
+        }
+        self.generation = self
+            .generation
+            .checked_add(1)
+            .ok_or("generation exhausted")?;
+        let id = Id {
+            owner,
+            local,
+            generation: self.generation,
+            session: self.session,
+        };
+        self.entries.insert(
+            id.clone(),
+            Activity {
+                id: id.clone(),
+                data,
+                state: State::Running,
+                created_at: now,
+                eligible_at: now.saturating_add(self.limits.start_delay_ms.max(min_duration_ms)),
+                refreshed_at: now,
+                lease_deadline: lease_ms.map(|ms| now.saturating_add(ms)),
+                result_deadline: None,
+                result_message: None,
+                flash_on_fail,
+                result_flash_ms: self.limits.result_flash_ms,
+                group,
+            },
+        );
+        Ok(id)
+    }
+
+    fn entry(&mut self, owner: Owner, id: &Id) -> Result<&mut Activity, &'static str> {
+        if id.session != self.session {
+            return Err("stale activity session; register again");
+        }
+        if id.owner != owner {
+            return Err("activity owner rejected");
+        }
+        self.entries.get_mut(id).ok_or("stale activity generation")
+    }
+
+    pub fn update(
+        &mut self,
+        owner: Owner,
+        id: &Id,
+        value: Option<Value>,
+        lease_ms: Option<u64>,
+        now: Time,
+    ) -> Result<(), &'static str> {
+        self.advance(now);
+        validate_lease(lease_ms, true)?;
+        let entry = self.entry(owner, id)?;
+        if entry.state != State::Running {
+            return Err("activity already completed");
+        }
+        if let Some(value) = value {
+            let mut candidate = entry.data.clone();
+            candidate.value = value;
+            candidate.validate(now)?;
+            entry.data = candidate;
+        }
+        if let Some(ms) = lease_ms {
+            validate_lease(Some(ms), true)?;
+            entry.lease_deadline = Some(now.saturating_add(ms));
+        } else if let Some(deadline) = entry.lease_deadline {
+            entry.lease_deadline =
+                Some(now.saturating_add(deadline.saturating_sub(entry.refreshed_at)));
+        }
+        entry.refreshed_at = now;
+        Ok(())
+    }
+
+    pub fn finish(
+        &mut self,
+        owner: Owner,
+        id: &Id,
+        state: State,
+        message: Option<String>,
+        now: Time,
+    ) -> Result<(), &'static str> {
+        self.advance(now);
+        if state == State::Running {
+            return Err("finish requires a terminal result");
+        }
+        if let Some(message) = &message {
+            text(message)?;
+        }
+        let entry = self.entry(owner, id)?;
+        if entry.state != State::Running {
+            return if entry.state == state {
+                Ok(())
+            } else {
+                Err("terminal result already accepted")
+            };
+        }
+        if state == State::Cancelled
+            || now < entry.eligible_at
+            || (state == State::Failed && !entry.flash_on_fail)
+        {
+            self.entries.remove(id);
+            return Ok(());
+        }
+        entry.state = state;
+        if let Some(message) = message {
+            entry.result_message = Some(message);
+        }
+        entry.result_deadline = Some(now.saturating_add(entry.result_flash_ms));
+        Ok(())
+    }
+
+    pub fn owner_exit(&mut self, owner: Owner) {
+        self.entries
+            .retain(|id, entry| id.owner != owner || entry.state != State::Running);
+    }
+
+    pub fn remove_output(&mut self, output: &str, fallback: Option<&str>) {
+        for entry in self
+            .entries
+            .values_mut()
+            .filter(|entry| entry.data.output.as_deref() == Some(output))
+        {
+            entry.data.output = fallback.map(str::to_owned);
+        }
+    }
+
+    pub fn attach_output(&mut self, output: &str) -> bool {
+        let mut changed = false;
+        for entry in self
+            .entries
+            .values_mut()
+            .filter(|entry| entry.data.output.is_none())
+        {
+            entry.data.output = Some(output.into());
+            changed = true;
+        }
+        changed
+    }
+    pub fn advance(&mut self, now: Time) -> bool {
+        let before = self.entries.len();
+        self.entries.retain(|_, entry| match entry.state {
+            State::Running => entry.lease_deadline.is_none_or(|deadline| now < deadline),
+            _ => entry.result_deadline.is_some_and(|deadline| now < deadline),
+        });
+        before != self.entries.len()
+    }
+
+    pub fn next_deadline(&self, now: Time) -> Option<Time> {
+        self.entries
+            .values()
+            .flat_map(|entry| {
+                [
+                    Some(entry.eligible_at),
+                    Some(entry.eligible_at.saturating_add(BOOST_MS)),
+                    entry.lease_deadline,
+                    entry.result_deadline,
+                    entry.result_deadline.map(|deadline| {
+                        deadline
+                            .saturating_sub(entry.result_flash_ms)
+                            .saturating_add(400)
+                    }),
+                ]
+            })
+            .flatten()
+            .filter(|deadline| *deadline > now)
+            .min()
+    }
+}
+
+fn validate_lease(lease: Option<u64>, monitored: bool) -> Result<(), &'static str> {
+    match lease {
+        Some(0) => Err("lease must be positive"),
+        Some(ms) if ms > MAX_LEASE_MS => Err("lease exceeds five minutes"),
+        None if !monitored => Err("unmonitored owner requires a lease"),
+        _ => Ok(()),
+    }
+}
+
+/// Recording/battery occupy a separate host-only class. Notifications always
+/// follow every other ordinary source, even when a result boost is active.
+pub fn ranked<'a>(
+    entries: impl IntoIterator<Item = &'a Activity>,
+    now: Time,
+    limits: Limits,
+    output: &str,
+    dnd: bool,
+) -> Vec<&'a Activity> {
+    let mut entries: Vec<_> = entries
+        .into_iter()
+        .filter(|entry| entry.eligible(now, dnd) && entry.data.output.as_deref() == Some(output))
+        .collect();
+    entries.sort_by(|a, b| {
+        (a.data.source == Source::Notification)
+            .cmp(&(b.data.source == Source::Notification))
+            .then_with(|| {
+                b.score(now, limits.owner_ceiling)
+                    .cmp(&a.score(now, limits.owner_ceiling))
+            })
+            .then_with(|| a.eligible_at.cmp(&b.eligible_at))
+            .then_with(|| a.id.cmp(&b.id))
+    });
+    entries
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct Selection {
+    pinned: Option<Vec<Id>>,
+    pub visible: Vec<Id>,
+    pub hidden: usize,
+    policy: Option<(bool, usize, usize)>,
+}
+
+impl Selection {
+    pub fn enter(&mut self) {
+        self.pinned = Some(self.visible.clone());
+    }
+    pub fn leave(&mut self) {
+        self.pinned = None;
+    }
+    pub fn override_pin(&mut self) {
+        self.pinned = None;
+    }
+    pub fn select(
+        &mut self,
+        ranked: &[&Activity],
+        limits: Limits,
+        dnd: bool,
+        protected_slots: usize,
+    ) {
+        let policy = (dnd, protected_slots, limits.max_visible);
+        if self.policy != Some(policy) {
+            self.override_pin();
+            self.policy = Some(policy);
+        }
+        let count = limits
+            .max_visible
+            .clamp(1, 2)
+            .saturating_sub(protected_slots)
+            .min(if dnd { 1 } else { 2 });
+        let eligible: Vec<_> = ranked
+            .iter()
+            .filter(|entry| !dnd || entry.state == State::Running)
+            .collect();
+        let mut groups = std::collections::BTreeSet::new();
+        let ids: Vec<_> = eligible
+            .iter()
+            .filter(|entry| {
+                let Some(group) = &entry.group else {
+                    return true;
+                };
+                if entry.state != State::Running
+                    && eligible.iter().any(|other| {
+                        other.id.owner == entry.id.owner
+                            && other.group.as_ref() == Some(group)
+                            && other.state == State::Running
+                    })
+                {
+                    return false;
+                }
+                groups.insert((entry.id.owner, group.clone()))
+            })
+            .map(|entry| entry.id.clone())
+            .collect();
+        self.visible = match &mut self.pinned {
+            Some(pinned) => {
+                pinned.retain(|id| ids.contains(id));
+                pinned.iter().take(count).cloned().collect()
+            }
+            None => ids.iter().take(count).cloned().collect(),
+        };
+        self.hidden = if dnd || !limits.show_badge {
+            0
+        } else {
+            eligible.len().saturating_sub(self.visible.len())
+        };
+    }
+}
+
+/// Focus survives reordered/updated rows by identity; removal chooses the next
+/// surviving row at the former position.
+pub fn reconcile_focus(focus: &mut Option<Id>, previous: &[Id], current: &[Id]) {
+    if focus.as_ref().is_some_and(|id| current.contains(id)) {
+        return;
+    }
+    let index = focus
+        .as_ref()
+        .and_then(|id| previous.iter().position(|old| old == id))
+        .unwrap_or(0);
+    *focus = current
+        .get(index.min(current.len().saturating_sub(1)))
+        .cloned();
+}
diff --git a/crates/ferese-animation/src/lib.rs b/crates/ferese-animation/src/lib.rs
index 948eea8..091fc97 100644
--- a/crates/ferese-animation/src/lib.rs
+++ b/crates/ferese-animation/src/lib.rs
@@ -1,1169 +1,8 @@
-use std::time::Duration;
-
-use ferese_layout::Rect;
-
+//! Spring-driven geometry and client presentation coordination.
+pub mod gesture;
 mod settings;
 mod spring;
+mod window_geometry;
+
 pub use settings::{MotionSettings, SpringSettings};
-pub mod gesture;
-
-/// Crossing behavior belongs to the property, not the physical solver.
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub enum CrossingPolicy {
-    NoCrossing,
-    AllowOvershoot,
-}
-
-const CLIENT_COMMIT_TIMEOUT: Duration = Duration::from_millis(500);
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct SpringConfig {
-    pub mass: f64,
-    pub stiffness: f64,
-    pub damping: f64,
-    pub position_tolerance: f64,
-    pub velocity_tolerance: f64,
-    pub crossing: CrossingPolicy,
-}
-
-impl Default for SpringConfig {
-    fn default() -> Self {
-        Self {
-            mass: 1.0,
-            stiffness: 700.0,
-            damping: 53.0,
-            position_tolerance: 0.1,
-            velocity_tolerance: 0.1,
-            crossing: CrossingPolicy::NoCrossing,
-        }
-    }
-}
-
-impl SpringConfig {
-    fn normalized(self) -> Self {
-        let defaults = Self::default();
-
-        Self {
-            mass: positive_or(self.mass, defaults.mass),
-            stiffness: positive_or(self.stiffness, defaults.stiffness),
-            damping: non_negative_or(self.damping, defaults.damping),
-            position_tolerance: positive_or(self.position_tolerance, defaults.position_tolerance),
-            velocity_tolerance: positive_or(self.velocity_tolerance, defaults.velocity_tolerance),
-            crossing: self.crossing,
-        }
-    }
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq)]
-pub struct RectVelocity {
-    pub x: f64,
-    pub y: f64,
-    pub width: f64,
-    pub height: f64,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct AnimatedRect {
-    pub current: Rect,
-    pub target: Rect,
-    pub velocity: RectVelocity,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct AnimatedValue {
-    pub current: f64,
-    pub target: f64,
-    pub velocity: f64,
-}
-
-impl AnimatedValue {
-    pub fn needs_update(&self, target: f64) -> bool {
-        self.target != target || self.is_animating()
-    }
-
-    pub fn is_animating(&self) -> bool {
-        self.current != self.target || self.velocity != 0.0
-    }
-
-    pub fn new(value: f64) -> Self {
-        let value = finite_or_zero(value);
-
-        Self {
-            current: value,
-            target: value,
-            velocity: 0.0,
-        }
-    }
-
-    pub fn set_target(&mut self, target: f64) {
-        self.target = finite_or_zero(target);
-    }
-
-    pub fn retarget_preserving_motion(&mut self, target: f64) {
-        self.set_target(target);
-    }
-
-    pub fn snap(&mut self) {
-        self.current = self.target;
-        self.velocity = 0.0;
-    }
-
-    /// Advance with the spring's configured crossing policy.
-    pub fn advance(&mut self, delta: Duration, config: SpringConfig) -> bool {
-        self.advance_with_policy(delta, config, config.crossing)
-    }
-
-    pub fn advance_with_policy(
-        &mut self,
-        delta: Duration,
-        config: SpringConfig,
-        policy: CrossingPolicy,
-    ) -> bool {
-        let config = config.normalized();
-        let settled = |value: &Self| {
-            (value.current - value.target).abs() <= config.position_tolerance
-                && value.velocity.abs() <= config.velocity_tolerance
-        };
-        if delta.is_zero() {
-            return !settled(self);
-        }
-
-        if settled(self) {
-            self.snap();
-            return false;
-        }
-
-        advance_property(
-            &mut self.current,
-            self.target,
-            &mut self.velocity,
-            delta.as_secs_f64(),
-            config,
-            policy,
-        );
-        if settled(self) {
-            self.snap();
-            false
-        } else {
-            true
-        }
-    }
-}
-
-impl AnimatedRect {
-    pub fn new(rect: Rect) -> Self {
-        Self {
-            current: rect,
-            target: rect,
-            velocity: RectVelocity::default(),
-        }
-    }
-
-    pub fn set_target(&mut self, target: Rect) {
-        self.target = normalized_rect(target);
-    }
-
-    pub fn snap(&mut self) {
-        self.current = self.target;
-        self.velocity = RectVelocity::default();
-    }
-
-    pub fn advance(&mut self, delta: Duration, config: SpringConfig) -> bool {
-        self.advance_with_policy(delta, config, config.crossing)
-    }
-
-    pub fn advance_with_policy(
-        &mut self,
-        delta: Duration,
-        config: SpringConfig,
-        policy: CrossingPolicy,
-    ) -> bool {
-        let config = config.normalized();
-        if delta.is_zero() {
-            return !self.is_settled(config);
-        }
-
-        if self.is_settled(config) {
-            self.snap();
-            return false;
-        }
-
-        // The old crossing clamp applied independently to each component.
-        let dt = delta.as_secs_f64();
-        advance_property(
-            &mut self.current.x,
-            self.target.x,
-            &mut self.velocity.x,
-            dt,
-            config,
-            policy,
-        );
-        advance_property(
-            &mut self.current.y,
-            self.target.y,
-            &mut self.velocity.y,
-            dt,
-            config,
-            policy,
-        );
-        advance_property(
-            &mut self.current.width,
-            self.target.width,
-            &mut self.velocity.width,
-            dt,
-            config,
-            policy,
-        );
-        advance_property(
-            &mut self.current.height,
-            self.target.height,
-            &mut self.velocity.height,
-            dt,
-            config,
-            policy,
-        );
-
-        if self.is_settled(config) {
-            self.snap();
-            false
-        } else {
-            true
-        }
-    }
-
-    pub fn is_settled(&self, config: SpringConfig) -> bool {
-        let config = config.normalized();
-        rect_distance(self.current, self.target) <= config.position_tolerance
-            && velocity_magnitude(self.velocity) <= config.velocity_tolerance
-    }
-}
-
-#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
-pub struct ClientSize {
-    pub width: i32,
-    pub height: i32,
-}
-
-impl ClientSize {
-    pub fn from_rect(rect: Rect) -> Self {
-        Self {
-            width: (rect.width.round() as i32).max(1),
-            height: (rect.height.round() as i32).max(1),
-        }
-    }
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq)]
-pub struct ClientGeometry {
-    pub last_configured_size: Option<ClientSize>,
-    pub committed_size: Option<ClientSize>,
-    waiting_since: Option<Duration>,
-}
-
-impl ClientGeometry {
-    pub fn request_size(&mut self, size: ClientSize, now: Duration) -> bool {
-        if self.last_configured_size == Some(size) {
-            return false;
-        }
-
-        self.last_configured_size = Some(size);
-        self.waiting_since.get_or_insert(now);
-        true
-    }
-
-    pub fn commit(&mut self, size: ClientSize) -> bool {
-        self.committed_size = Some(size);
-        let matches_target = self.last_configured_size == Some(size);
-
-        if matches_target {
-            self.waiting_since = None;
-        }
-
-        matches_target
-    }
-
-    pub fn waiting_for_commit(&self) -> bool {
-        self.waiting_since.is_some()
-    }
-
-    /// The hard bound for the current uninterrupted client-buffer wait.
-    pub fn commit_deadline(&self) -> Option<Duration> {
-        self.waiting_since
-            .map(|started| started + CLIENT_COMMIT_TIMEOUT)
-    }
-
-    pub fn timed_out(&self, now: Duration) -> bool {
-        self.waiting_since
-            .is_some_and(|started| now.saturating_sub(started) >= CLIENT_COMMIT_TIMEOUT)
-    }
-
-    pub fn expire_wait(&mut self, now: Duration) -> Option<ClientSize> {
-        if !self.timed_out(now) {
-            return None;
-        }
-
-        self.waiting_since = None;
-        self.last_configured_size
-    }
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub enum PresentationMode {
-    Normal,
-    Maximized,
-    Fullscreen,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct WindowGeometry {
-    pub logical: Rect,
-    pub visual: AnimatedRect,
-    pub client: ClientGeometry,
-    pub decorations: f64,
-    pub presentation_changed: bool,
-    mode: PresentationMode,
-    zoom: Option<ZoomTransition>,
-}
-
-/// Maximized/fullscreen geometry and decorations share a clock, including on reversal.
-#[derive(Clone, Copy, Debug, PartialEq)]
-struct ZoomTransition {
-    decorations: AnimatedValue,
-}
-
-impl WindowGeometry {
-    pub fn new(rect: Rect, committed_size: Option<ClientSize>) -> Self {
-        let rect = normalized_rect(rect);
-
-        Self {
-            logical: rect,
-            visual: AnimatedRect::new(rect),
-            client: ClientGeometry {
-                last_configured_size: committed_size,
-                committed_size,
-                waiting_since: None,
-            },
-            decorations: 1.0,
-            presentation_changed: true,
-            mode: PresentationMode::Normal,
-            zoom: None,
-        }
-    }
-
-    pub fn set_logical_target(&mut self, rect: Rect, now: Duration) -> Option<ClientSize> {
-        let rect = normalized_rect(rect);
-        if self.zoom.is_some() {
-            return self.set_presentation_mode(rect, self.mode, now);
-        }
-
-        let before = self.visual.current;
-        let size = ClientSize::from_rect(rect);
-        self.logical = rect;
-        self.visual.set_target(rect);
-        debug_assert_eq!(self.visual.current, before);
-
-        self.client.request_size(size, now).then_some(size)
-    }
-
-    pub fn set_presentation_target(
-        &mut self,
-        rect: Rect,
-        fullscreen: bool,
-        now: Duration,
-    ) -> Option<ClientSize> {
-        self.set_presentation_mode(
-            rect,
-            if fullscreen {
-                PresentationMode::Fullscreen
-            } else {
-                PresentationMode::Normal
-            },
-            now,
-        )
-    }
-
-    pub fn set_presentation_mode(
-        &mut self,
-        rect: Rect,
-        mode: PresentationMode,
-        now: Duration,
-    ) -> Option<ClientSize> {
-        let rect = normalized_rect(rect);
-        let before = (self.visual.current, self.decorations);
-        if self.mode != mode || (self.zoom.is_some() && self.logical != rect) {
-            let mut decorations = self
-                .zoom
-                .map(|zoom| zoom.decorations)
-                .unwrap_or_else(|| AnimatedValue::new(self.decorations));
-            decorations.set_target(if mode == PresentationMode::Fullscreen {
-                0.0
-            } else {
-                1.0
-            });
-            self.zoom = Some(ZoomTransition { decorations });
-        }
-        self.mode = mode;
-        self.logical = rect;
-        self.visual.set_target(rect);
-        debug_assert_eq!((self.visual.current, self.decorations), before);
-        self.presentation_size_request(now)
-    }
-
-    /// Request the destination once, independently of the presentation clock.
-    /// The compositor coordinates commits; delaying this until settlement
-    /// forces presentation to use an obsolete buffer for the entire resize.
-    pub fn presentation_size_request(&mut self, now: Duration) -> Option<ClientSize> {
-        let size = ClientSize::from_rect(self.logical);
-        self.client.request_size(size, now).then_some(size)
-    }
-
-    pub fn is_zooming(&self) -> bool {
-        self.zoom.is_some()
-    }
-
-    pub fn is_fullscreen(&self) -> bool {
-        self.mode == PresentationMode::Fullscreen
-    }
-
-    pub fn settle_presentation(&mut self) {
-        self.visual.snap();
-        self.zoom = None;
-        self.decorations = if self.is_fullscreen() { 0.0 } else { 1.0 };
-        self.presentation_changed = true;
-    }
-
-    pub fn follow_pointer(&mut self, rect: Rect, now: Duration) -> Option<ClientSize> {
-        self.zoom = None;
-        let requested_size = self.set_logical_target(rect, now);
-        self.visual.snap();
-        self.decorations = if self.is_fullscreen() { 0.0 } else { 1.0 };
-        self.presentation_changed = true;
-        requested_size
-    }
-
-    pub fn advance(
-        &mut self,
-        delta: Duration,
-        config: SpringConfig,
-        animations_enabled: bool,
-    ) -> bool {
-        let previous = (self.visual.current, self.decorations);
-        let active = self.advance_presentation(delta, config, animations_enabled);
-        self.presentation_changed = previous != (self.visual.current, self.decorations);
-        active
-    }
-
-    fn advance_presentation(
-        &mut self,
-        delta: Duration,
-        config: SpringConfig,
-        animations_enabled: bool,
-    ) -> bool {
-        if !animations_enabled {
-            self.visual.snap();
-            self.decorations = if self.is_fullscreen() { 0.0 } else { 1.0 };
-            self.zoom = None;
-            return false;
-        }
-
-        if delta.is_zero() {
-            return self.zoom.is_some() || !self.visual.is_settled(config);
-        }
-
-        // Retarget the existing rectangle directly: projecting four independent
-        // velocities onto a new scalar progress loses motion on interruption.
-        let geometry_active = self.visual.advance(delta, config);
-        if let Some(zoom) = &mut self.zoom {
-            let decoration_config = SpringConfig {
-                position_tolerance: 0.00001,
-                velocity_tolerance: 0.00001,
-                ..config
-            };
-            let decorations_active = zoom.decorations.advance(delta, decoration_config);
-            self.decorations = zoom.decorations.current.clamp(0.0, 1.0);
-            if !geometry_active && !decorations_active {
-                self.zoom = None;
-            }
-            return geometry_active || decorations_active;
-        }
-        geometry_active
-    }
-
-    pub fn inverse_visual_point(&self, x: f64, y: f64) -> Option<(f64, f64)> {
-        let visual = self.visual.current;
-        let (scale_x, scale_y) = self.visual_scale()?;
-
-        Some(((x - visual.x) / scale_x, (y - visual.y) / scale_y))
-    }
-
-    pub fn visual_scale(&self) -> Option<(f64, f64)> {
-        let source = self.client.committed_size?;
-        let visual = self.visual.current;
-        if source.width <= 0 || source.height <= 0 || visual.width <= 0.0 || visual.height <= 0.0 {
-            return None;
-        }
-
-        Some((
-            visual.width / f64::from(source.width),
-            visual.height / f64::from(source.height),
-        ))
-    }
-}
-
-fn advance_property(
-    current: &mut f64,
-    target: f64,
-    velocity: &mut f64,
-    dt: f64,
-    config: SpringConfig,
-    policy: CrossingPolicy,
-) {
-    if policy == CrossingPolicy::NoCrossing
-        && spring::crosses(*current, *velocity, target, dt, config)
-    {
-        *current = target;
-        *velocity = 0.0;
-    } else {
-        (*current, *velocity) = spring::solve(*current, *velocity, target, dt, config);
-    }
-}
-
-#[cfg(test)]
-fn advance_value(
-    current: &mut f64,
-    target: f64,
-    velocity: &mut f64,
-    dt: f64,
-    config: SpringConfig,
-) {
-    (*current, *velocity) = spring::solve(*current, *velocity, target, dt, config);
-}
-
-fn finite_or_zero(value: f64) -> f64 {
-    if value.is_finite() { value } else { 0.0 }
-}
-
-fn normalized_rect(rect: Rect) -> Rect {
-    Rect::new(
-        finite_or(rect.x, 0.0),
-        finite_or(rect.y, 0.0),
-        positive_or(rect.width, 1.0),
-        positive_or(rect.height, 1.0),
-    )
-}
-
-fn rect_distance(left: Rect, right: Rect) -> f64 {
-    (left.x - right.x)
-        .abs()
-        .max((left.y - right.y).abs())
-        .max((left.width - right.width).abs())
-        .max((left.height - right.height).abs())
-}
-
-fn velocity_magnitude(velocity: RectVelocity) -> f64 {
-    velocity
-        .x
-        .abs()
-        .max(velocity.y.abs())
-        .max(velocity.width.abs())
-        .max(velocity.height.abs())
-}
-
-fn positive_or(value: f64, fallback: f64) -> f64 {
-    if value.is_finite() && value > 0.0 {
-        value
-    } else {
-        fallback
-    }
-}
-
-fn non_negative_or(value: f64, fallback: f64) -> f64 {
-    if value.is_finite() && value >= 0.0 {
-        value
-    } else {
-        fallback
-    }
-}
-
-fn finite_or(value: f64, fallback: f64) -> f64 {
-    if value.is_finite() { value } else { fallback }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn replacing_size_requests_does_not_extend_a_stalled_client_wait() {
-        let mut client = ClientGeometry::default();
-        for width in 1..=50 {
-            assert!(client.request_size(
-                ClientSize { width, height: 100 },
-                Duration::from_millis((width as u64 - 1) * 10)
-            ));
-        }
-        assert_eq!(client.commit_deadline(), Some(Duration::from_millis(500)));
-        assert!(!client.commit(ClientSize {
-            width: 49,
-            height: 100
-        }));
-        assert!(client.expire_wait(Duration::from_millis(499)).is_none());
-        assert_eq!(
-            client.expire_wait(Duration::from_millis(500)),
-            Some(ClientSize {
-                width: 50,
-                height: 100
-            })
-        );
-        assert_eq!(client.commit_deadline(), None);
-        assert!(client.request_size(
-            ClientSize {
-                width: 51,
-                height: 100
-            },
-            Duration::from_millis(600)
-        ));
-        assert_eq!(client.commit_deadline(), Some(Duration::from_millis(1100)));
-        assert!(client.commit(ClientSize {
-            width: 51,
-            height: 100
-        }));
-        assert_eq!(client.commit_deadline(), None);
-    }
-
-    #[test]
-    fn returning_fullscreen_window_does_not_resume_hidden_zoom() {
-        let normal = Rect::new(100.0, 50.0, 900.0, 700.0);
-        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        let mut geometry = WindowGeometry::new(normal, None);
-        geometry.set_presentation_mode(fullscreen, PresentationMode::Fullscreen, Duration::ZERO);
-        geometry.advance(Duration::from_millis(16), SpringConfig::default(), true);
-        assert!(geometry.is_zooming());
-
-        geometry.settle_presentation();
-
-        assert_eq!(geometry.visual.current, fullscreen);
-        assert_eq!(geometry.decorations, 0.0);
-        assert!(!geometry.is_zooming());
-        assert!(!geometry.advance(Duration::from_millis(16), SpringConfig::default(), true));
-    }
-
-    #[test]
-    fn hiding_maximized_window_finishes_resize_without_hiding_decorations() {
-        let normal = Rect::new(100.0, 50.0, 900.0, 700.0);
-        let maximized = Rect::new(0.0, 40.0, 1920.0, 1040.0);
-        let mut geometry = WindowGeometry::new(normal, None);
-        geometry.set_presentation_mode(maximized, PresentationMode::Maximized, Duration::ZERO);
-        geometry.advance(Duration::from_millis(16), SpringConfig::default(), true);
-        assert!(geometry.is_zooming());
-
-        geometry.settle_presentation();
-
-        assert_eq!(geometry.visual.current, maximized);
-        assert_eq!(geometry.decorations, 1.0);
-        assert!(!geometry.is_zooming());
-    }
-
-    #[test]
-    fn maximized_zoom_keeps_decorations_and_restores_through_fullscreen() {
-        let normal = Rect::new(800.0, 50.0, 600.0, 700.0);
-        let maximized = Rect::new(10.0, 50.0, 1580.0, 740.0);
-        let fullscreen = Rect::new(0.0, 0.0, 1600.0, 800.0);
-        let mut geometry = WindowGeometry::new(normal, None);
-        for (mode, rect) in [
-            (PresentationMode::Maximized, maximized),
-            (PresentationMode::Fullscreen, fullscreen),
-            (PresentationMode::Maximized, maximized),
-            (PresentationMode::Normal, normal),
-        ] {
-            let before = geometry.visual.current;
-            let decorations = geometry.decorations;
-            geometry.set_presentation_mode(rect, mode, Duration::ZERO);
-            assert_eq!(geometry.visual.current, before);
-            assert_eq!(geometry.decorations, decorations);
-            for _ in 0..1000 {
-                if !geometry.advance(Duration::from_millis(8), SpringConfig::default(), true) {
-                    break;
-                }
-                if mode != PresentationMode::Fullscreen && decorations == 1.0 {
-                    assert_eq!(geometry.decorations, 1.0);
-                }
-            }
-            assert_eq!(geometry.visual.current, rect);
-            assert_eq!(
-                geometry.decorations,
-                if mode == PresentationMode::Fullscreen {
-                    0.0
-                } else {
-                    1.0
-                }
-            );
-            assert!(!geometry.is_zooming());
-            assert_eq!(
-                geometry.is_fullscreen(),
-                mode == PresentationMode::Fullscreen
-            );
-        }
-    }
-
-    #[test]
-    fn reversing_maximization_preserves_visual_position_and_decoration() {
-        let normal = Rect::new(800.0, 50.0, 600.0, 700.0);
-        let mut geometry = WindowGeometry::new(normal, None);
-        geometry.set_presentation_mode(
-            Rect::new(10.0, 50.0, 1580.0, 740.0),
-            PresentationMode::Maximized,
-            Duration::ZERO,
-        );
-        geometry.advance(Duration::from_millis(80), SpringConfig::default(), true);
-        let before = geometry.visual.current;
-        geometry.set_presentation_mode(normal, PresentationMode::Normal, Duration::from_millis(80));
-        assert_eq!(geometry.visual.current, before);
-        assert_eq!(geometry.decorations, 1.0);
-        geometry.advance(Duration::ZERO, SpringConfig::default(), false);
-        assert_eq!(geometry.visual.current, normal);
-        assert_eq!(geometry.decorations, 1.0);
-    }
-
-    #[test]
-    fn zoom_finishes_without_a_visible_final_edge_jump() {
-        let tiled = Rect::new(12.0, 12.0, 942.0, 1056.0);
-        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        for (start, target, fullscreen_target) in
-            [(tiled, fullscreen, true), (fullscreen, tiled, false)]
-        {
-            let mut geometry = WindowGeometry::new(start, None);
-            if !fullscreen_target {
-                geometry.set_presentation_target(start, true, Duration::ZERO);
-                geometry.advance(Duration::ZERO, SpringConfig::default(), false);
-            }
-            geometry.set_presentation_target(target, fullscreen_target, Duration::ZERO);
-            let mut finished = false;
-            for _ in 0..1000 {
-                let before = geometry.visual.current;
-                if !geometry.advance(
-                    Duration::from_secs_f64(1.0 / 144.0),
-                    SpringConfig::default(),
-                    true,
-                ) {
-                    let right_before = before.x + before.width;
-                    let right_after = target.x + target.width;
-                    assert!(
-                        (right_after - right_before).abs() < 0.5,
-                        "final right-edge jump: {} pixels",
-                        (right_after - right_before).abs()
-                    );
-                    finished = true;
-                    break;
-                }
-            }
-            assert!(finished);
-        }
-    }
-
-    #[test]
-    fn zoom_geometry_and_decorations_share_progress() {
-        let start = Rect::new(200.0, 40.0, 600.0, 800.0);
-        let end = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        let mut geometry = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
-        geometry.set_presentation_target(end, true, Duration::ZERO);
-        for _ in 0..20 {
-            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
-            let progress = 1.0 - geometry.decorations;
-            let visual = geometry.visual.current;
-            assert!((visual.x - (start.x + (end.x - start.x) * progress)).abs() < 1e-9);
-            assert!(
-                (visual.width - (start.width + (end.width - start.width) * progress)).abs() < 1e-9
-            );
-        }
-    }
-
-    #[test]
-    fn rapid_zoom_reversal_preserves_presented_frame_and_reaches_latest_target() {
-        let tiled = Rect::new(600.0, 20.0, 600.0, 900.0);
-        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        let mut geometry = WindowGeometry::new(tiled, None);
-        for enabled in [true, false, true, false] {
-            let before = (geometry.visual.current, geometry.decorations);
-            geometry.set_presentation_target(
-                if enabled { fullscreen } else { tiled },
-                enabled,
-                Duration::ZERO,
-            );
-            assert_eq!((geometry.visual.current, geometry.decorations), before);
-            geometry.advance(Duration::from_millis(48), SpringConfig::default(), true);
-        }
-        for _ in 0..240 {
-            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
-        }
-        assert_eq!(geometry.visual.current, tiled);
-        assert_eq!(geometry.decorations, 1.0);
-        assert!(!geometry.is_zooming());
-    }
-
-    #[test]
-    fn zoom_configures_destination_once_before_animating() {
-        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
-        let end = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        let mut geometry = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
-        assert_eq!(
-            geometry.set_presentation_target(end, true, Duration::ZERO),
-            Some(ClientSize::from_rect(end))
-        );
-        for frame in 0..240 {
-            let now = Duration::from_millis(frame * 8);
-            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
-            assert_eq!(geometry.presentation_size_request(now), None);
-        }
-        assert_eq!(geometry.visual.current, end);
-        assert_eq!(
-            geometry.set_presentation_target(start, false, Duration::from_secs(2)),
-            Some(ClientSize::from_rect(start))
-        );
-    }
-
-    #[test]
-    fn animated_resize_configures_each_new_target_without_framewise_requests() {
-        let start = Rect::new(10.0, 10.0, 600.0, 800.0);
-        let middle = Rect::new(10.0, 10.0, 900.0, 800.0);
-        let end = Rect::new(10.0, 10.0, 450.0, 800.0);
-        let mut geometry = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
-        assert_eq!(
-            geometry.set_presentation_mode(middle, PresentationMode::Normal, Duration::ZERO),
-            Some(ClientSize::from_rect(middle))
-        );
-        geometry.advance(Duration::from_millis(64), SpringConfig::default(), true);
-        assert_eq!(
-            geometry.presentation_size_request(Duration::from_millis(64)),
-            None
-        );
-        assert_eq!(
-            geometry.set_presentation_mode(
-                end,
-                PresentationMode::Normal,
-                Duration::from_millis(64)
-            ),
-            Some(ClientSize::from_rect(end))
-        );
-        let mut requests = Vec::new();
-        for frame in 1..240 {
-            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
-            if let Some(size) =
-                geometry.presentation_size_request(Duration::from_millis(64 + frame * 8))
-            {
-                assert_eq!(geometry.visual.current.width, end.width);
-                requests.push(size);
-            }
-        }
-        assert!(requests.is_empty());
-    }
-
-    #[test]
-    fn pointer_resize_stays_live_and_reduced_motion_configures_immediately() {
-        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
-        let end = Rect::new(0.0, 0.0, 900.0, 800.0);
-        let mut pointer = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
-        assert_eq!(
-            pointer.follow_pointer(end, Duration::ZERO),
-            Some(ClientSize::from_rect(end))
-        );
-        let mut reduced = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
-        assert_eq!(
-            reduced.set_presentation_target(end, true, Duration::ZERO),
-            Some(ClientSize::from_rect(end))
-        );
-        reduced.advance(Duration::ZERO, SpringConfig::default(), false);
-        assert_eq!(reduced.presentation_size_request(Duration::ZERO), None);
-    }
-
-    #[test]
-    fn left_and_right_zoom_edges_do_not_reverse_direction() {
-        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        for tiled in [
-            Rect::new(12.0, 12.0, 942.0, 1056.0),
-            Rect::new(966.0, 12.0, 942.0, 1056.0),
-        ] {
-            for rate in [60, 144] {
-                let mut geometry = WindowGeometry::new(tiled, Some(ClientSize::from_rect(tiled)));
-                for (target, enabled) in [(fullscreen, true), (tiled, false)] {
-                    geometry.set_presentation_target(target, enabled, Duration::ZERO);
-                    let mut previous = geometry.visual.current;
-                    for _ in 0..rate * 2 {
-                        geometry.advance(
-                            Duration::from_secs_f64(1.0 / f64::from(rate)),
-                            SpringConfig::default(),
-                            true,
-                        );
-                        let current = geometry.visual.current;
-                        let edges = |rect: Rect| {
-                            [rect.x, rect.y, rect.x + rect.width, rect.y + rect.height]
-                        };
-                        for ((before, after), end) in edges(previous)
-                            .into_iter()
-                            .zip(edges(current))
-                            .zip(edges(target))
-                        {
-                            assert!((after - end).abs() <= (before - end).abs() + 1e-9);
-                        }
-                        previous = current;
-                    }
-                    assert_eq!(geometry.visual.current, target);
-                }
-            }
-        }
-    }
-
-    #[test]
-    fn drag_takes_ownership_from_an_unfinished_zoom() {
-        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
-        let mut geometry = WindowGeometry::new(start, None);
-        geometry.set_presentation_target(Rect::new(0.0, 0.0, 1920.0, 1080.0), true, Duration::ZERO);
-        geometry.advance(Duration::from_millis(32), SpringConfig::default(), true);
-        geometry.set_presentation_target(start, false, Duration::ZERO);
-        let dragged = Rect::new(40.0, 50.0, 500.0, 700.0);
-        geometry.follow_pointer(dragged, Duration::ZERO);
-        assert!(!geometry.advance(Duration::from_millis(16), SpringConfig::default(), true));
-        assert_eq!(geometry.visual.current, dragged);
-    }
-
-    #[test]
-    fn reduced_motion_finishes_zoom_and_decorations_together() {
-        let mut geometry = WindowGeometry::new(Rect::new(100.0, 20.0, 600.0, 800.0), None);
-        let target = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        geometry.set_presentation_target(target, true, Duration::ZERO);
-        geometry.advance(Duration::ZERO, SpringConfig::default(), false);
-        assert_eq!(geometry.visual.current, target);
-        assert_eq!(geometry.decorations, 0.0);
-        assert!(!geometry.is_zooming());
-    }
-
-    #[test]
-    fn relayout_during_zoom_does_not_restart_its_clock() {
-        let start = Rect::new(600.0, 20.0, 600.0, 900.0);
-        let target = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        let mut uninterrupted = WindowGeometry::new(start, None);
-        uninterrupted.set_presentation_target(target, true, Duration::ZERO);
-        let mut relayout = uninterrupted;
-        for frame in 0..120 {
-            let now = Duration::from_millis(frame * 8);
-            relayout.set_presentation_target(target, true, now);
-            relayout.advance(Duration::from_millis(8), SpringConfig::default(), true);
-            uninterrupted.advance(Duration::from_millis(8), SpringConfig::default(), true);
-            assert_eq!(relayout.visual, uninterrupted.visual);
-            assert_eq!(relayout.decorations, uninterrupted.decorations);
-        }
-    }
-
-    #[test]
-    fn zoom_at_different_refresh_rates_has_comparable_progress() {
-        let start = Rect::new(600.0, 20.0, 600.0, 900.0);
-        let target = Rect::new(0.0, 0.0, 1920.0, 1080.0);
-        let mut progress = Vec::new();
-        for rate in [60, 120, 144] {
-            let mut geometry = WindowGeometry::new(start, None);
-            geometry.set_presentation_target(target, true, Duration::ZERO);
-            for _ in 0..rate / 6 {
-                geometry.advance(
-                    Duration::from_secs_f64(1.0 / f64::from(rate)),
-                    SpringConfig::default(),
-                    true,
-                );
-            }
-            progress.push(geometry.decorations);
-        }
-        assert!((progress[0] - progress[1]).abs() < 0.01);
-        assert!((progress[0] - progress[2]).abs() < 0.01);
-    }
-
-    #[test]
-    fn final_frame_invalidates_clip_even_when_zoom_has_settled() {
-        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
-        let mut geometry = WindowGeometry::new(start, None);
-        geometry.set_presentation_target(start, true, Duration::ZERO);
-        for _ in 0..1000 {
-            if !geometry.advance(Duration::from_millis(8), SpringConfig::default(), true) {
-                assert!(geometry.presentation_changed);
-                assert_eq!(geometry.decorations, 0.0);
-                geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
-                assert!(!geometry.presentation_changed);
-                return;
-            }
-        }
-        panic!("zoom failed to settle");
-    }
-
-    #[test]
-    fn scalar_spring_retargets_from_current_motion() {
-        let mut value = AnimatedValue::new(0.0);
-        value.set_target(1_000.0);
-        value.advance(Duration::from_millis(40), SpringConfig::default());
-        let current = value.current;
-        let velocity = value.velocity;
-
-        value.retarget_preserving_motion(2_000.0);
-
-        assert_eq!(value.current, current);
-        assert_eq!(value.velocity, velocity);
-        assert_eq!(value.target, 2_000.0);
-    }
-
-    #[test]
-    fn scalar_spring_preserves_opposing_velocity_on_reversal() {
-        let mut value = AnimatedValue::new(0.0);
-        value.set_target(1_000.0);
-        value.advance(Duration::from_millis(40), SpringConfig::default());
-        let current = value.current;
-        let velocity = value.velocity;
-
-        value.retarget_preserving_motion(-500.0);
-
-        assert!(value.velocity > 0.0);
-        assert_eq!(value.velocity, velocity);
-        assert_eq!(value.current, current);
-    }
-
-    #[test]
-    fn scalar_presentation_clamp_does_not_overshoot_and_clears_velocity() {
-        let mut value = AnimatedValue::new(0.0);
-        value.velocity = 20_000.0;
-        value.set_target(100.0);
-
-        for _ in 0..60 {
-            value.advance(Duration::from_secs_f64(1.0 / 60.0), SpringConfig::default());
-            assert!(value.current <= 100.0);
-            if value.current == value.target {
-                assert_eq!(value.velocity, 0.0);
-            }
-        }
-    }
-
-    #[test]
-    fn logical_target_changes_without_jumping_visual_geometry() {
-        let initial = Rect::new(0.0, 0.0, 400.0, 300.0);
-        let target = Rect::new(200.0, 100.0, 800.0, 600.0);
-        let mut geometry = WindowGeometry::new(initial, Some(ClientSize::from_rect(initial)));
-
-        assert_eq!(
-            geometry.set_logical_target(target, Duration::ZERO),
-            Some(ClientSize::from_rect(target))
-        );
-        assert_eq!(geometry.logical, target);
-        assert_eq!(geometry.visual.current, initial);
-        assert_eq!(geometry.visual.target, target);
-    }
-
-    #[test]
-    fn repeated_target_does_not_emit_another_configure() {
-        let rect = Rect::new(0.0, 0.0, 800.0, 600.0);
-        let mut geometry = WindowGeometry::new(rect, None);
-
-        assert!(geometry.set_logical_target(rect, Duration::ZERO).is_some());
-        assert!(
-            geometry
-                .set_logical_target(rect, Duration::from_millis(16))
-                .is_none()
-        );
-    }
-
-    #[test]
-    fn matching_commit_clears_timeout_without_restarting_visual_motion() {
-        let initial = Rect::new(0.0, 0.0, 400.0, 300.0);
-        let target = Rect::new(100.0, 50.0, 800.0, 600.0);
-        let mut geometry = WindowGeometry::new(initial, None);
-        let requested = geometry.set_logical_target(target, Duration::ZERO).unwrap();
-        geometry.advance(Duration::from_millis(100), SpringConfig::default(), true);
-        let visual_before_commit = geometry.visual;
-
-        assert!(geometry.client.commit(requested));
-        assert_eq!(geometry.visual, visual_before_commit);
-        assert!(!geometry.client.timed_out(Duration::from_secs(1)));
-    }
-
-    #[test]
-    fn slow_client_times_out_after_half_a_second() {
-        let rect = Rect::new(0.0, 0.0, 800.0, 600.0);
-        let mut client = ClientGeometry::default();
-        client.request_size(ClientSize::from_rect(rect), Duration::ZERO);
-
-        assert!(!client.timed_out(Duration::from_millis(499)));
-        assert!(client.timed_out(Duration::from_millis(500)));
-        assert_eq!(
-            client.expire_wait(Duration::from_millis(500)),
-            Some(ClientSize::from_rect(rect))
-        );
-        assert!(!client.timed_out(Duration::from_secs(1)));
-    }
-
-    #[test]
-    fn inverse_visual_point_matches_stretched_transform() {
-        let initial = Rect::new(100.0, 50.0, 400.0, 300.0);
-        let mut geometry = WindowGeometry::new(initial, Some(ClientSize::from_rect(initial)));
-        geometry.visual.current = Rect::new(200.0, 100.0, 600.0, 600.0);
-
-        assert_eq!(
-            geometry.inverse_visual_point(600.0, 500.0),
-            Some((400.0 * 2.0 / 3.0, 200.0))
-        );
-    }
-
-    #[test]
-    fn default_spring_is_stable_across_refresh_rates_and_does_not_overshoot() {
-        let start = Rect::new(0.0, 0.0, 100.0, 100.0);
-        let target = Rect::new(500.0, 300.0, 900.0, 700.0);
-        let mut sixty = AnimatedRect::new(start);
-        let mut one_forty_four = AnimatedRect::new(start);
-        sixty.set_target(target);
-        one_forty_four.set_target(target);
-
-        for _ in 0..120 {
-            sixty.advance(Duration::from_secs_f64(1.0 / 60.0), SpringConfig::default());
-            assert!(sixty.current.x <= target.x);
-            assert!(sixty.current.width <= target.width);
-        }
-        for _ in 0..288 {
-            one_forty_four.advance(
-                Duration::from_secs_f64(1.0 / 144.0),
-                SpringConfig::default(),
-            );
-        }
-
-        assert!(sixty.is_settled(SpringConfig::default()));
-        assert!(one_forty_four.is_settled(SpringConfig::default()));
-        assert_eq!(sixty.current, target);
-        assert_eq!(one_forty_four.current, target);
-    }
-
-    #[test]
-    fn default_spring_completes_most_motion_within_two_hundred_milliseconds() {
-        let start = Rect::new(0.0, 0.0, 100.0, 100.0);
-        let target = Rect::new(500.0, 300.0, 900.0, 700.0);
-        let mut animated = AnimatedRect::new(start);
-        animated.set_target(target);
-
-        for _ in 0..12 {
-            animated.advance(Duration::from_secs_f64(1.0 / 60.0), SpringConfig::default());
-        }
-
-        assert!(animated.current.x >= 475.0);
-        assert!(animated.current.y >= 285.0);
-        assert!(animated.current.width >= 860.0);
-        assert!(animated.current.height >= 670.0);
-        assert!(animated.current.x <= target.x);
-        assert!(animated.current.y <= target.y);
-        assert!(animated.current.width <= target.width);
-        assert!(animated.current.height <= target.height);
-    }
-
-    #[test]
-    fn disabled_animation_snaps_to_target() {
-        let mut geometry = WindowGeometry::new(Rect::new(0.0, 0.0, 100.0, 100.0), None);
-        let target = Rect::new(100.0, 100.0, 500.0, 400.0);
-        geometry.set_logical_target(target, Duration::ZERO);
-
-        assert!(!geometry.advance(Duration::from_millis(16), SpringConfig::default(), false));
-        assert_eq!(geometry.visual.current, target);
-    }
-}
-
-#[cfg(test)]
-mod traces;
+pub use window_geometry::*;
diff --git a/crates/ferese-animation/src/window_geometry.rs b/crates/ferese-animation/src/window_geometry.rs
new file mode 100644
index 0000000..ac45b47
--- /dev/null
+++ b/crates/ferese-animation/src/window_geometry.rs
@@ -0,0 +1,1166 @@
+use std::time::Duration;
+
+use ferese_layout::Rect;
+
+use crate::spring;
+
+/// Crossing behavior belongs to the property, not the physical solver.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum CrossingPolicy {
+    NoCrossing,
+    AllowOvershoot,
+}
+
+const CLIENT_COMMIT_TIMEOUT: Duration = Duration::from_millis(500);
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct SpringConfig {
+    pub mass: f64,
+    pub stiffness: f64,
+    pub damping: f64,
+    pub position_tolerance: f64,
+    pub velocity_tolerance: f64,
+    pub crossing: CrossingPolicy,
+}
+
+impl Default for SpringConfig {
+    fn default() -> Self {
+        Self {
+            mass: 1.0,
+            stiffness: 700.0,
+            damping: 53.0,
+            position_tolerance: 0.1,
+            velocity_tolerance: 0.1,
+            crossing: CrossingPolicy::NoCrossing,
+        }
+    }
+}
+
+impl SpringConfig {
+    pub(super) fn normalized(self) -> Self {
+        let defaults = Self::default();
+
+        Self {
+            mass: positive_or(self.mass, defaults.mass),
+            stiffness: positive_or(self.stiffness, defaults.stiffness),
+            damping: non_negative_or(self.damping, defaults.damping),
+            position_tolerance: positive_or(self.position_tolerance, defaults.position_tolerance),
+            velocity_tolerance: positive_or(self.velocity_tolerance, defaults.velocity_tolerance),
+            crossing: self.crossing,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct RectVelocity {
+    pub x: f64,
+    pub y: f64,
+    pub width: f64,
+    pub height: f64,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct AnimatedRect {
+    pub current: Rect,
+    pub target: Rect,
+    pub velocity: RectVelocity,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct AnimatedValue {
+    pub current: f64,
+    pub target: f64,
+    pub velocity: f64,
+}
+
+impl AnimatedValue {
+    pub fn needs_update(&self, target: f64) -> bool {
+        self.target != target || self.is_animating()
+    }
+
+    pub fn is_animating(&self) -> bool {
+        self.current != self.target || self.velocity != 0.0
+    }
+
+    pub fn new(value: f64) -> Self {
+        let value = finite_or_zero(value);
+
+        Self {
+            current: value,
+            target: value,
+            velocity: 0.0,
+        }
+    }
+
+    pub fn set_target(&mut self, target: f64) {
+        self.target = finite_or_zero(target);
+    }
+
+    pub fn retarget_preserving_motion(&mut self, target: f64) {
+        self.set_target(target);
+    }
+
+    pub fn snap(&mut self) {
+        self.current = self.target;
+        self.velocity = 0.0;
+    }
+
+    /// Advance with the spring's configured crossing policy.
+    pub fn advance(&mut self, delta: Duration, config: SpringConfig) -> bool {
+        self.advance_with_policy(delta, config, config.crossing)
+    }
+
+    pub fn advance_with_policy(
+        &mut self,
+        delta: Duration,
+        config: SpringConfig,
+        policy: CrossingPolicy,
+    ) -> bool {
+        let config = config.normalized();
+        let settled = |value: &Self| {
+            (value.current - value.target).abs() <= config.position_tolerance
+                && value.velocity.abs() <= config.velocity_tolerance
+        };
+        if delta.is_zero() {
+            return !settled(self);
+        }
+
+        if settled(self) {
+            self.snap();
+            return false;
+        }
+
+        advance_property(
+            &mut self.current,
+            self.target,
+            &mut self.velocity,
+            delta.as_secs_f64(),
+            config,
+            policy,
+        );
+        if settled(self) {
+            self.snap();
+            false
+        } else {
+            true
+        }
+    }
+}
+
+impl AnimatedRect {
+    pub fn new(rect: Rect) -> Self {
+        Self {
+            current: rect,
+            target: rect,
+            velocity: RectVelocity::default(),
+        }
+    }
+
+    pub fn set_target(&mut self, target: Rect) {
+        self.target = normalized_rect(target);
+    }
+
+    pub fn snap(&mut self) {
+        self.current = self.target;
+        self.velocity = RectVelocity::default();
+    }
+
+    pub fn advance(&mut self, delta: Duration, config: SpringConfig) -> bool {
+        self.advance_with_policy(delta, config, config.crossing)
+    }
+
+    pub fn advance_with_policy(
+        &mut self,
+        delta: Duration,
+        config: SpringConfig,
+        policy: CrossingPolicy,
+    ) -> bool {
+        let config = config.normalized();
+        if delta.is_zero() {
+            return !self.is_settled(config);
+        }
+
+        if self.is_settled(config) {
+            self.snap();
+            return false;
+        }
+
+        // The old crossing clamp applied independently to each component.
+        let dt = delta.as_secs_f64();
+        advance_property(
+            &mut self.current.x,
+            self.target.x,
+            &mut self.velocity.x,
+            dt,
+            config,
+            policy,
+        );
+        advance_property(
+            &mut self.current.y,
+            self.target.y,
+            &mut self.velocity.y,
+            dt,
+            config,
+            policy,
+        );
+        advance_property(
+            &mut self.current.width,
+            self.target.width,
+            &mut self.velocity.width,
+            dt,
+            config,
+            policy,
+        );
+        advance_property(
+            &mut self.current.height,
+            self.target.height,
+            &mut self.velocity.height,
+            dt,
+            config,
+            policy,
+        );
+
+        if self.is_settled(config) {
+            self.snap();
+            false
+        } else {
+            true
+        }
+    }
+
+    pub fn is_settled(&self, config: SpringConfig) -> bool {
+        let config = config.normalized();
+        rect_distance(self.current, self.target) <= config.position_tolerance
+            && velocity_magnitude(self.velocity) <= config.velocity_tolerance
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
+pub struct ClientSize {
+    pub width: i32,
+    pub height: i32,
+}
+
+impl ClientSize {
+    pub fn from_rect(rect: Rect) -> Self {
+        Self {
+            width: (rect.width.round() as i32).max(1),
+            height: (rect.height.round() as i32).max(1),
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct ClientGeometry {
+    pub last_configured_size: Option<ClientSize>,
+    pub committed_size: Option<ClientSize>,
+    waiting_since: Option<Duration>,
+}
+
+impl ClientGeometry {
+    pub fn request_size(&mut self, size: ClientSize, now: Duration) -> bool {
+        if self.last_configured_size == Some(size) {
+            return false;
+        }
+
+        self.last_configured_size = Some(size);
+        self.waiting_since.get_or_insert(now);
+        true
+    }
+
+    pub fn commit(&mut self, size: ClientSize) -> bool {
+        self.committed_size = Some(size);
+        let matches_target = self.last_configured_size == Some(size);
+
+        if matches_target {
+            self.waiting_since = None;
+        }
+
+        matches_target
+    }
+
+    pub fn waiting_for_commit(&self) -> bool {
+        self.waiting_since.is_some()
+    }
+
+    /// The hard bound for the current uninterrupted client-buffer wait.
+    pub fn commit_deadline(&self) -> Option<Duration> {
+        self.waiting_since
+            .map(|started| started + CLIENT_COMMIT_TIMEOUT)
+    }
+
+    pub fn timed_out(&self, now: Duration) -> bool {
+        self.waiting_since
+            .is_some_and(|started| now.saturating_sub(started) >= CLIENT_COMMIT_TIMEOUT)
+    }
+
+    pub fn expire_wait(&mut self, now: Duration) -> Option<ClientSize> {
+        if !self.timed_out(now) {
+            return None;
+        }
+
+        self.waiting_since = None;
+        self.last_configured_size
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum PresentationMode {
+    Normal,
+    Maximized,
+    Fullscreen,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct WindowGeometry {
+    pub logical: Rect,
+    pub visual: AnimatedRect,
+    pub client: ClientGeometry,
+    pub decorations: f64,
+    pub presentation_changed: bool,
+    mode: PresentationMode,
+    zoom: Option<ZoomTransition>,
+}
+
+/// Maximized/fullscreen geometry and decorations share a clock, including on reversal.
+#[derive(Clone, Copy, Debug, PartialEq)]
+struct ZoomTransition {
+    decorations: AnimatedValue,
+}
+
+impl WindowGeometry {
+    pub fn new(rect: Rect, committed_size: Option<ClientSize>) -> Self {
+        let rect = normalized_rect(rect);
+
+        Self {
+            logical: rect,
+            visual: AnimatedRect::new(rect),
+            client: ClientGeometry {
+                last_configured_size: committed_size,
+                committed_size,
+                waiting_since: None,
+            },
+            decorations: 1.0,
+            presentation_changed: true,
+            mode: PresentationMode::Normal,
+            zoom: None,
+        }
+    }
+
+    pub fn set_logical_target(&mut self, rect: Rect, now: Duration) -> Option<ClientSize> {
+        let rect = normalized_rect(rect);
+        if self.zoom.is_some() {
+            return self.set_presentation_mode(rect, self.mode, now);
+        }
+
+        let before = self.visual.current;
+        let size = ClientSize::from_rect(rect);
+        self.logical = rect;
+        self.visual.set_target(rect);
+        debug_assert_eq!(self.visual.current, before);
+
+        self.client.request_size(size, now).then_some(size)
+    }
+
+    pub fn set_presentation_target(
+        &mut self,
+        rect: Rect,
+        fullscreen: bool,
+        now: Duration,
+    ) -> Option<ClientSize> {
+        self.set_presentation_mode(
+            rect,
+            if fullscreen {
+                PresentationMode::Fullscreen
+            } else {
+                PresentationMode::Normal
+            },
+            now,
+        )
+    }
+
+    pub fn set_presentation_mode(
+        &mut self,
+        rect: Rect,
+        mode: PresentationMode,
+        now: Duration,
+    ) -> Option<ClientSize> {
+        let rect = normalized_rect(rect);
+        let before = (self.visual.current, self.decorations);
+        if self.mode != mode || (self.zoom.is_some() && self.logical != rect) {
+            let mut decorations = self
+                .zoom
+                .map(|zoom| zoom.decorations)
+                .unwrap_or_else(|| AnimatedValue::new(self.decorations));
+            decorations.set_target(if mode == PresentationMode::Fullscreen {
+                0.0
+            } else {
+                1.0
+            });
+            self.zoom = Some(ZoomTransition { decorations });
+        }
+        self.mode = mode;
+        self.logical = rect;
+        self.visual.set_target(rect);
+        debug_assert_eq!((self.visual.current, self.decorations), before);
+        self.presentation_size_request(now)
+    }
+
+    /// Request the destination once, independently of the presentation clock.
+    /// The compositor coordinates commits; delaying this until settlement
+    /// forces presentation to use an obsolete buffer for the entire resize.
+    pub fn presentation_size_request(&mut self, now: Duration) -> Option<ClientSize> {
+        let size = ClientSize::from_rect(self.logical);
+        self.client.request_size(size, now).then_some(size)
+    }
+
+    pub fn is_zooming(&self) -> bool {
+        self.zoom.is_some()
+    }
+
+    pub fn is_fullscreen(&self) -> bool {
+        self.mode == PresentationMode::Fullscreen
+    }
+
+    pub fn settle_presentation(&mut self) {
+        self.visual.snap();
+        self.zoom = None;
+        self.decorations = if self.is_fullscreen() { 0.0 } else { 1.0 };
+        self.presentation_changed = true;
+    }
+
+    pub fn follow_pointer(&mut self, rect: Rect, now: Duration) -> Option<ClientSize> {
+        self.zoom = None;
+        let requested_size = self.set_logical_target(rect, now);
+        self.visual.snap();
+        self.decorations = if self.is_fullscreen() { 0.0 } else { 1.0 };
+        self.presentation_changed = true;
+        requested_size
+    }
+
+    pub fn advance(
+        &mut self,
+        delta: Duration,
+        config: SpringConfig,
+        animations_enabled: bool,
+    ) -> bool {
+        let previous = (self.visual.current, self.decorations);
+        let active = self.advance_presentation(delta, config, animations_enabled);
+        self.presentation_changed = previous != (self.visual.current, self.decorations);
+        active
+    }
+
+    fn advance_presentation(
+        &mut self,
+        delta: Duration,
+        config: SpringConfig,
+        animations_enabled: bool,
+    ) -> bool {
+        if !animations_enabled {
+            self.visual.snap();
+            self.decorations = if self.is_fullscreen() { 0.0 } else { 1.0 };
+            self.zoom = None;
+            return false;
+        }
+
+        if delta.is_zero() {
+            return self.zoom.is_some() || !self.visual.is_settled(config);
+        }
+
+        // Retarget the existing rectangle directly: projecting four independent
+        // velocities onto a new scalar progress loses motion on interruption.
+        let geometry_active = self.visual.advance(delta, config);
+        if let Some(zoom) = &mut self.zoom {
+            let decoration_config = SpringConfig {
+                position_tolerance: 0.00001,
+                velocity_tolerance: 0.00001,
+                ..config
+            };
+            let decorations_active = zoom.decorations.advance(delta, decoration_config);
+            self.decorations = zoom.decorations.current.clamp(0.0, 1.0);
+            if !geometry_active && !decorations_active {
+                self.zoom = None;
+            }
+            return geometry_active || decorations_active;
+        }
+        geometry_active
+    }
+
+    pub fn inverse_visual_point(&self, x: f64, y: f64) -> Option<(f64, f64)> {
+        let visual = self.visual.current;
+        let (scale_x, scale_y) = self.visual_scale()?;
+
+        Some(((x - visual.x) / scale_x, (y - visual.y) / scale_y))
+    }
+
+    pub fn visual_scale(&self) -> Option<(f64, f64)> {
+        let source = self.client.committed_size?;
+        let visual = self.visual.current;
+        if source.width <= 0 || source.height <= 0 || visual.width <= 0.0 || visual.height <= 0.0 {
+            return None;
+        }
+
+        Some((
+            visual.width / f64::from(source.width),
+            visual.height / f64::from(source.height),
+        ))
+    }
+}
+
+fn advance_property(
+    current: &mut f64,
+    target: f64,
+    velocity: &mut f64,
+    dt: f64,
+    config: SpringConfig,
+    policy: CrossingPolicy,
+) {
+    if policy == CrossingPolicy::NoCrossing
+        && spring::crosses(*current, *velocity, target, dt, config)
+    {
+        *current = target;
+        *velocity = 0.0;
+    } else {
+        (*current, *velocity) = spring::solve(*current, *velocity, target, dt, config);
+    }
+}
+
+#[cfg(test)]
+fn advance_value(
+    current: &mut f64,
+    target: f64,
+    velocity: &mut f64,
+    dt: f64,
+    config: SpringConfig,
+) {
+    (*current, *velocity) = spring::solve(*current, *velocity, target, dt, config);
+}
+
+fn finite_or_zero(value: f64) -> f64 {
+    if value.is_finite() { value } else { 0.0 }
+}
+
+fn normalized_rect(rect: Rect) -> Rect {
+    Rect::new(
+        finite_or(rect.x, 0.0),
+        finite_or(rect.y, 0.0),
+        positive_or(rect.width, 1.0),
+        positive_or(rect.height, 1.0),
+    )
+}
+
+fn rect_distance(left: Rect, right: Rect) -> f64 {
+    (left.x - right.x)
+        .abs()
+        .max((left.y - right.y).abs())
+        .max((left.width - right.width).abs())
+        .max((left.height - right.height).abs())
+}
+
+fn velocity_magnitude(velocity: RectVelocity) -> f64 {
+    velocity
+        .x
+        .abs()
+        .max(velocity.y.abs())
+        .max(velocity.width.abs())
+        .max(velocity.height.abs())
+}
+
+fn positive_or(value: f64, fallback: f64) -> f64 {
+    if value.is_finite() && value > 0.0 {
+        value
+    } else {
+        fallback
+    }
+}
+
+fn non_negative_or(value: f64, fallback: f64) -> f64 {
+    if value.is_finite() && value >= 0.0 {
+        value
+    } else {
+        fallback
+    }
+}
+
+fn finite_or(value: f64, fallback: f64) -> f64 {
+    if value.is_finite() { value } else { fallback }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn replacing_size_requests_does_not_extend_a_stalled_client_wait() {
+        let mut client = ClientGeometry::default();
+        for width in 1..=50 {
+            assert!(client.request_size(
+                ClientSize { width, height: 100 },
+                Duration::from_millis((width as u64 - 1) * 10)
+            ));
+        }
+        assert_eq!(client.commit_deadline(), Some(Duration::from_millis(500)));
+        assert!(!client.commit(ClientSize {
+            width: 49,
+            height: 100
+        }));
+        assert!(client.expire_wait(Duration::from_millis(499)).is_none());
+        assert_eq!(
+            client.expire_wait(Duration::from_millis(500)),
+            Some(ClientSize {
+                width: 50,
+                height: 100
+            })
+        );
+        assert_eq!(client.commit_deadline(), None);
+        assert!(client.request_size(
+            ClientSize {
+                width: 51,
+                height: 100
+            },
+            Duration::from_millis(600)
+        ));
+        assert_eq!(client.commit_deadline(), Some(Duration::from_millis(1100)));
+        assert!(client.commit(ClientSize {
+            width: 51,
+            height: 100
+        }));
+        assert_eq!(client.commit_deadline(), None);
+    }
+
+    #[test]
+    fn returning_fullscreen_window_does_not_resume_hidden_zoom() {
+        let normal = Rect::new(100.0, 50.0, 900.0, 700.0);
+        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        let mut geometry = WindowGeometry::new(normal, None);
+        geometry.set_presentation_mode(fullscreen, PresentationMode::Fullscreen, Duration::ZERO);
+        geometry.advance(Duration::from_millis(16), SpringConfig::default(), true);
+        assert!(geometry.is_zooming());
+
+        geometry.settle_presentation();
+
+        assert_eq!(geometry.visual.current, fullscreen);
+        assert_eq!(geometry.decorations, 0.0);
+        assert!(!geometry.is_zooming());
+        assert!(!geometry.advance(Duration::from_millis(16), SpringConfig::default(), true));
+    }
+
+    #[test]
+    fn hiding_maximized_window_finishes_resize_without_hiding_decorations() {
+        let normal = Rect::new(100.0, 50.0, 900.0, 700.0);
+        let maximized = Rect::new(0.0, 40.0, 1920.0, 1040.0);
+        let mut geometry = WindowGeometry::new(normal, None);
+        geometry.set_presentation_mode(maximized, PresentationMode::Maximized, Duration::ZERO);
+        geometry.advance(Duration::from_millis(16), SpringConfig::default(), true);
+        assert!(geometry.is_zooming());
+
+        geometry.settle_presentation();
+
+        assert_eq!(geometry.visual.current, maximized);
+        assert_eq!(geometry.decorations, 1.0);
+        assert!(!geometry.is_zooming());
+    }
+
+    #[test]
+    fn maximized_zoom_keeps_decorations_and_restores_through_fullscreen() {
+        let normal = Rect::new(800.0, 50.0, 600.0, 700.0);
+        let maximized = Rect::new(10.0, 50.0, 1580.0, 740.0);
+        let fullscreen = Rect::new(0.0, 0.0, 1600.0, 800.0);
+        let mut geometry = WindowGeometry::new(normal, None);
+        for (mode, rect) in [
+            (PresentationMode::Maximized, maximized),
+            (PresentationMode::Fullscreen, fullscreen),
+            (PresentationMode::Maximized, maximized),
+            (PresentationMode::Normal, normal),
+        ] {
+            let before = geometry.visual.current;
+            let decorations = geometry.decorations;
+            geometry.set_presentation_mode(rect, mode, Duration::ZERO);
+            assert_eq!(geometry.visual.current, before);
+            assert_eq!(geometry.decorations, decorations);
+            for _ in 0..1000 {
+                if !geometry.advance(Duration::from_millis(8), SpringConfig::default(), true) {
+                    break;
+                }
+                if mode != PresentationMode::Fullscreen && decorations == 1.0 {
+                    assert_eq!(geometry.decorations, 1.0);
+                }
+            }
+            assert_eq!(geometry.visual.current, rect);
+            assert_eq!(
+                geometry.decorations,
+                if mode == PresentationMode::Fullscreen {
+                    0.0
+                } else {
+                    1.0
+                }
+            );
+            assert!(!geometry.is_zooming());
+            assert_eq!(
+                geometry.is_fullscreen(),
+                mode == PresentationMode::Fullscreen
+            );
+        }
+    }
+
+    #[test]
+    fn reversing_maximization_preserves_visual_position_and_decoration() {
+        let normal = Rect::new(800.0, 50.0, 600.0, 700.0);
+        let mut geometry = WindowGeometry::new(normal, None);
+        geometry.set_presentation_mode(
+            Rect::new(10.0, 50.0, 1580.0, 740.0),
+            PresentationMode::Maximized,
+            Duration::ZERO,
+        );
+        geometry.advance(Duration::from_millis(80), SpringConfig::default(), true);
+        let before = geometry.visual.current;
+        geometry.set_presentation_mode(normal, PresentationMode::Normal, Duration::from_millis(80));
+        assert_eq!(geometry.visual.current, before);
+        assert_eq!(geometry.decorations, 1.0);
+        geometry.advance(Duration::ZERO, SpringConfig::default(), false);
+        assert_eq!(geometry.visual.current, normal);
+        assert_eq!(geometry.decorations, 1.0);
+    }
+
+    #[test]
+    fn zoom_finishes_without_a_visible_final_edge_jump() {
+        let tiled = Rect::new(12.0, 12.0, 942.0, 1056.0);
+        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        for (start, target, fullscreen_target) in
+            [(tiled, fullscreen, true), (fullscreen, tiled, false)]
+        {
+            let mut geometry = WindowGeometry::new(start, None);
+            if !fullscreen_target {
+                geometry.set_presentation_target(start, true, Duration::ZERO);
+                geometry.advance(Duration::ZERO, SpringConfig::default(), false);
+            }
+            geometry.set_presentation_target(target, fullscreen_target, Duration::ZERO);
+            let mut finished = false;
+            for _ in 0..1000 {
+                let before = geometry.visual.current;
+                if !geometry.advance(
+                    Duration::from_secs_f64(1.0 / 144.0),
+                    SpringConfig::default(),
+                    true,
+                ) {
+                    let right_before = before.x + before.width;
+                    let right_after = target.x + target.width;
+                    assert!(
+                        (right_after - right_before).abs() < 0.5,
+                        "final right-edge jump: {} pixels",
+                        (right_after - right_before).abs()
+                    );
+                    finished = true;
+                    break;
+                }
+            }
+            assert!(finished);
+        }
+    }
+
+    #[test]
+    fn zoom_geometry_and_decorations_share_progress() {
+        let start = Rect::new(200.0, 40.0, 600.0, 800.0);
+        let end = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        let mut geometry = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
+        geometry.set_presentation_target(end, true, Duration::ZERO);
+        for _ in 0..20 {
+            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
+            let progress = 1.0 - geometry.decorations;
+            let visual = geometry.visual.current;
+            assert!((visual.x - (start.x + (end.x - start.x) * progress)).abs() < 1e-9);
+            assert!(
+                (visual.width - (start.width + (end.width - start.width) * progress)).abs() < 1e-9
+            );
+        }
+    }
+
+    #[test]
+    fn rapid_zoom_reversal_preserves_presented_frame_and_reaches_latest_target() {
+        let tiled = Rect::new(600.0, 20.0, 600.0, 900.0);
+        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        let mut geometry = WindowGeometry::new(tiled, None);
+        for enabled in [true, false, true, false] {
+            let before = (geometry.visual.current, geometry.decorations);
+            geometry.set_presentation_target(
+                if enabled { fullscreen } else { tiled },
+                enabled,
+                Duration::ZERO,
+            );
+            assert_eq!((geometry.visual.current, geometry.decorations), before);
+            geometry.advance(Duration::from_millis(48), SpringConfig::default(), true);
+        }
+        for _ in 0..240 {
+            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
+        }
+        assert_eq!(geometry.visual.current, tiled);
+        assert_eq!(geometry.decorations, 1.0);
+        assert!(!geometry.is_zooming());
+    }
+
+    #[test]
+    fn zoom_configures_destination_once_before_animating() {
+        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
+        let end = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        let mut geometry = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
+        assert_eq!(
+            geometry.set_presentation_target(end, true, Duration::ZERO),
+            Some(ClientSize::from_rect(end))
+        );
+        for frame in 0..240 {
+            let now = Duration::from_millis(frame * 8);
+            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
+            assert_eq!(geometry.presentation_size_request(now), None);
+        }
+        assert_eq!(geometry.visual.current, end);
+        assert_eq!(
+            geometry.set_presentation_target(start, false, Duration::from_secs(2)),
+            Some(ClientSize::from_rect(start))
+        );
+    }
+
+    #[test]
+    fn animated_resize_configures_each_new_target_without_framewise_requests() {
+        let start = Rect::new(10.0, 10.0, 600.0, 800.0);
+        let middle = Rect::new(10.0, 10.0, 900.0, 800.0);
+        let end = Rect::new(10.0, 10.0, 450.0, 800.0);
+        let mut geometry = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
+        assert_eq!(
+            geometry.set_presentation_mode(middle, PresentationMode::Normal, Duration::ZERO),
+            Some(ClientSize::from_rect(middle))
+        );
+        geometry.advance(Duration::from_millis(64), SpringConfig::default(), true);
+        assert_eq!(
+            geometry.presentation_size_request(Duration::from_millis(64)),
+            None
+        );
+        assert_eq!(
+            geometry.set_presentation_mode(
+                end,
+                PresentationMode::Normal,
+                Duration::from_millis(64)
+            ),
+            Some(ClientSize::from_rect(end))
+        );
+        let mut requests = Vec::new();
+        for frame in 1..240 {
+            geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
+            if let Some(size) =
+                geometry.presentation_size_request(Duration::from_millis(64 + frame * 8))
+            {
+                assert_eq!(geometry.visual.current.width, end.width);
+                requests.push(size);
+            }
+        }
+        assert!(requests.is_empty());
+    }
+
+    #[test]
+    fn pointer_resize_stays_live_and_reduced_motion_configures_immediately() {
+        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
+        let end = Rect::new(0.0, 0.0, 900.0, 800.0);
+        let mut pointer = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
+        assert_eq!(
+            pointer.follow_pointer(end, Duration::ZERO),
+            Some(ClientSize::from_rect(end))
+        );
+        let mut reduced = WindowGeometry::new(start, Some(ClientSize::from_rect(start)));
+        assert_eq!(
+            reduced.set_presentation_target(end, true, Duration::ZERO),
+            Some(ClientSize::from_rect(end))
+        );
+        reduced.advance(Duration::ZERO, SpringConfig::default(), false);
+        assert_eq!(reduced.presentation_size_request(Duration::ZERO), None);
+    }
+
+    #[test]
+    fn left_and_right_zoom_edges_do_not_reverse_direction() {
+        let fullscreen = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        for tiled in [
+            Rect::new(12.0, 12.0, 942.0, 1056.0),
+            Rect::new(966.0, 12.0, 942.0, 1056.0),
+        ] {
+            for rate in [60, 144] {
+                let mut geometry = WindowGeometry::new(tiled, Some(ClientSize::from_rect(tiled)));
+                for (target, enabled) in [(fullscreen, true), (tiled, false)] {
+                    geometry.set_presentation_target(target, enabled, Duration::ZERO);
+                    let mut previous = geometry.visual.current;
+                    for _ in 0..rate * 2 {
+                        geometry.advance(
+                            Duration::from_secs_f64(1.0 / f64::from(rate)),
+                            SpringConfig::default(),
+                            true,
+                        );
+                        let current = geometry.visual.current;
+                        let edges = |rect: Rect| {
+                            [rect.x, rect.y, rect.x + rect.width, rect.y + rect.height]
+                        };
+                        for ((before, after), end) in edges(previous)
+                            .into_iter()
+                            .zip(edges(current))
+                            .zip(edges(target))
+                        {
+                            assert!((after - end).abs() <= (before - end).abs() + 1e-9);
+                        }
+                        previous = current;
+                    }
+                    assert_eq!(geometry.visual.current, target);
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn drag_takes_ownership_from_an_unfinished_zoom() {
+        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
+        let mut geometry = WindowGeometry::new(start, None);
+        geometry.set_presentation_target(Rect::new(0.0, 0.0, 1920.0, 1080.0), true, Duration::ZERO);
+        geometry.advance(Duration::from_millis(32), SpringConfig::default(), true);
+        geometry.set_presentation_target(start, false, Duration::ZERO);
+        let dragged = Rect::new(40.0, 50.0, 500.0, 700.0);
+        geometry.follow_pointer(dragged, Duration::ZERO);
+        assert!(!geometry.advance(Duration::from_millis(16), SpringConfig::default(), true));
+        assert_eq!(geometry.visual.current, dragged);
+    }
+
+    #[test]
+    fn reduced_motion_finishes_zoom_and_decorations_together() {
+        let mut geometry = WindowGeometry::new(Rect::new(100.0, 20.0, 600.0, 800.0), None);
+        let target = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        geometry.set_presentation_target(target, true, Duration::ZERO);
+        geometry.advance(Duration::ZERO, SpringConfig::default(), false);
+        assert_eq!(geometry.visual.current, target);
+        assert_eq!(geometry.decorations, 0.0);
+        assert!(!geometry.is_zooming());
+    }
+
+    #[test]
+    fn relayout_during_zoom_does_not_restart_its_clock() {
+        let start = Rect::new(600.0, 20.0, 600.0, 900.0);
+        let target = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        let mut uninterrupted = WindowGeometry::new(start, None);
+        uninterrupted.set_presentation_target(target, true, Duration::ZERO);
+        let mut relayout = uninterrupted;
+        for frame in 0..120 {
+            let now = Duration::from_millis(frame * 8);
+            relayout.set_presentation_target(target, true, now);
+            relayout.advance(Duration::from_millis(8), SpringConfig::default(), true);
+            uninterrupted.advance(Duration::from_millis(8), SpringConfig::default(), true);
+            assert_eq!(relayout.visual, uninterrupted.visual);
+            assert_eq!(relayout.decorations, uninterrupted.decorations);
+        }
+    }
+
+    #[test]
+    fn zoom_at_different_refresh_rates_has_comparable_progress() {
+        let start = Rect::new(600.0, 20.0, 600.0, 900.0);
+        let target = Rect::new(0.0, 0.0, 1920.0, 1080.0);
+        let mut progress = Vec::new();
+        for rate in [60, 120, 144] {
+            let mut geometry = WindowGeometry::new(start, None);
+            geometry.set_presentation_target(target, true, Duration::ZERO);
+            for _ in 0..rate / 6 {
+                geometry.advance(
+                    Duration::from_secs_f64(1.0 / f64::from(rate)),
+                    SpringConfig::default(),
+                    true,
+                );
+            }
+            progress.push(geometry.decorations);
+        }
+        assert!((progress[0] - progress[1]).abs() < 0.01);
+        assert!((progress[0] - progress[2]).abs() < 0.01);
+    }
+
+    #[test]
+    fn final_frame_invalidates_clip_even_when_zoom_has_settled() {
+        let start = Rect::new(0.0, 0.0, 600.0, 800.0);
+        let mut geometry = WindowGeometry::new(start, None);
+        geometry.set_presentation_target(start, true, Duration::ZERO);
+        for _ in 0..1000 {
+            if !geometry.advance(Duration::from_millis(8), SpringConfig::default(), true) {
+                assert!(geometry.presentation_changed);
+                assert_eq!(geometry.decorations, 0.0);
+                geometry.advance(Duration::from_millis(8), SpringConfig::default(), true);
+                assert!(!geometry.presentation_changed);
+                return;
+            }
+        }
+        panic!("zoom failed to settle");
+    }
+
+    #[test]
+    fn scalar_spring_retargets_from_current_motion() {
+        let mut value = AnimatedValue::new(0.0);
+        value.set_target(1_000.0);
+        value.advance(Duration::from_millis(40), SpringConfig::default());
+        let current = value.current;
+        let velocity = value.velocity;
+
+        value.retarget_preserving_motion(2_000.0);
+
+        assert_eq!(value.current, current);
+        assert_eq!(value.velocity, velocity);
+        assert_eq!(value.target, 2_000.0);
+    }
+
+    #[test]
+    fn scalar_spring_preserves_opposing_velocity_on_reversal() {
+        let mut value = AnimatedValue::new(0.0);
+        value.set_target(1_000.0);
+        value.advance(Duration::from_millis(40), SpringConfig::default());
+        let current = value.current;
+        let velocity = value.velocity;
+
+        value.retarget_preserving_motion(-500.0);
+
+        assert!(value.velocity > 0.0);
+        assert_eq!(value.velocity, velocity);
+        assert_eq!(value.current, current);
+    }
+
+    #[test]
+    fn scalar_presentation_clamp_does_not_overshoot_and_clears_velocity() {
+        let mut value = AnimatedValue::new(0.0);
+        value.velocity = 20_000.0;
+        value.set_target(100.0);
+
+        for _ in 0..60 {
+            value.advance(Duration::from_secs_f64(1.0 / 60.0), SpringConfig::default());
+            assert!(value.current <= 100.0);
+            if value.current == value.target {
+                assert_eq!(value.velocity, 0.0);
+            }
+        }
+    }
+
+    #[test]
+    fn logical_target_changes_without_jumping_visual_geometry() {
+        let initial = Rect::new(0.0, 0.0, 400.0, 300.0);
+        let target = Rect::new(200.0, 100.0, 800.0, 600.0);
+        let mut geometry = WindowGeometry::new(initial, Some(ClientSize::from_rect(initial)));
+
+        assert_eq!(
+            geometry.set_logical_target(target, Duration::ZERO),
+            Some(ClientSize::from_rect(target))
+        );
+        assert_eq!(geometry.logical, target);
+        assert_eq!(geometry.visual.current, initial);
+        assert_eq!(geometry.visual.target, target);
+    }
+
+    #[test]
+    fn repeated_target_does_not_emit_another_configure() {
+        let rect = Rect::new(0.0, 0.0, 800.0, 600.0);
+        let mut geometry = WindowGeometry::new(rect, None);
+
+        assert!(geometry.set_logical_target(rect, Duration::ZERO).is_some());
+        assert!(
+            geometry
+                .set_logical_target(rect, Duration::from_millis(16))
+                .is_none()
+        );
+    }
+
+    #[test]
+    fn matching_commit_clears_timeout_without_restarting_visual_motion() {
+        let initial = Rect::new(0.0, 0.0, 400.0, 300.0);
+        let target = Rect::new(100.0, 50.0, 800.0, 600.0);
+        let mut geometry = WindowGeometry::new(initial, None);
+        let requested = geometry.set_logical_target(target, Duration::ZERO).unwrap();
+        geometry.advance(Duration::from_millis(100), SpringConfig::default(), true);
+        let visual_before_commit = geometry.visual;
+
+        assert!(geometry.client.commit(requested));
+        assert_eq!(geometry.visual, visual_before_commit);
+        assert!(!geometry.client.timed_out(Duration::from_secs(1)));
+    }
+
+    #[test]
+    fn slow_client_times_out_after_half_a_second() {
+        let rect = Rect::new(0.0, 0.0, 800.0, 600.0);
+        let mut client = ClientGeometry::default();
+        client.request_size(ClientSize::from_rect(rect), Duration::ZERO);
+
+        assert!(!client.timed_out(Duration::from_millis(499)));
+        assert!(client.timed_out(Duration::from_millis(500)));
+        assert_eq!(
+            client.expire_wait(Duration::from_millis(500)),
+            Some(ClientSize::from_rect(rect))
+        );
+        assert!(!client.timed_out(Duration::from_secs(1)));
+    }
+
+    #[test]
+    fn inverse_visual_point_matches_stretched_transform() {
+        let initial = Rect::new(100.0, 50.0, 400.0, 300.0);
+        let mut geometry = WindowGeometry::new(initial, Some(ClientSize::from_rect(initial)));
+        geometry.visual.current = Rect::new(200.0, 100.0, 600.0, 600.0);
+
+        assert_eq!(
+            geometry.inverse_visual_point(600.0, 500.0),
+            Some((400.0 * 2.0 / 3.0, 200.0))
+        );
+    }
+
+    #[test]
+    fn default_spring_is_stable_across_refresh_rates_and_does_not_overshoot() {
+        let start = Rect::new(0.0, 0.0, 100.0, 100.0);
+        let target = Rect::new(500.0, 300.0, 900.0, 700.0);
+        let mut sixty = AnimatedRect::new(start);
+        let mut one_forty_four = AnimatedRect::new(start);
+        sixty.set_target(target);
+        one_forty_four.set_target(target);
+
+        for _ in 0..120 {
+            sixty.advance(Duration::from_secs_f64(1.0 / 60.0), SpringConfig::default());
+            assert!(sixty.current.x <= target.x);
+            assert!(sixty.current.width <= target.width);
+        }
+        for _ in 0..288 {
+            one_forty_four.advance(
+                Duration::from_secs_f64(1.0 / 144.0),
+                SpringConfig::default(),
+            );
+        }
+
+        assert!(sixty.is_settled(SpringConfig::default()));
+        assert!(one_forty_four.is_settled(SpringConfig::default()));
+        assert_eq!(sixty.current, target);
+        assert_eq!(one_forty_four.current, target);
+    }
+
+    #[test]
+    fn default_spring_completes_most_motion_within_two_hundred_milliseconds() {
+        let start = Rect::new(0.0, 0.0, 100.0, 100.0);
+        let target = Rect::new(500.0, 300.0, 900.0, 700.0);
+        let mut animated = AnimatedRect::new(start);
+        animated.set_target(target);
+
+        for _ in 0..12 {
+            animated.advance(Duration::from_secs_f64(1.0 / 60.0), SpringConfig::default());
+        }
+
+        assert!(animated.current.x >= 475.0);
+        assert!(animated.current.y >= 285.0);
+        assert!(animated.current.width >= 860.0);
+        assert!(animated.current.height >= 670.0);
+        assert!(animated.current.x <= target.x);
+        assert!(animated.current.y <= target.y);
+        assert!(animated.current.width <= target.width);
+        assert!(animated.current.height <= target.height);
+    }
+
+    #[test]
+    fn disabled_animation_snaps_to_target() {
+        let mut geometry = WindowGeometry::new(Rect::new(0.0, 0.0, 100.0, 100.0), None);
+        let target = Rect::new(100.0, 100.0, 500.0, 400.0);
+        geometry.set_logical_target(target, Duration::ZERO);
+
+        assert!(!geometry.advance(Duration::from_millis(16), SpringConfig::default(), false));
+        assert_eq!(geometry.visual.current, target);
+    }
+}
+
+#[cfg(test)]
+mod traces;
diff --git a/crates/ferese-animation/src/traces.rs b/crates/ferese-animation/src/window_geometry/traces.rs
similarity index 100%
rename from crates/ferese-animation/src/traces.rs
rename to crates/ferese-animation/src/window_geometry/traces.rs
diff --git a/crates/ferese-config/src/activities.rs b/crates/ferese-config/src/activities.rs
index 572461a..29f846b 100644
--- a/crates/ferese-config/src/activities.rs
+++ b/crates/ferese-config/src/activities.rs
@@ -1,30 +1,11 @@
 //! Activity rules are matched in declaration order, followed by unreplaced
 //! built-ins. Matching metadata is bounded and never stored in the result.
+use crate::document;
 use kdl::KdlNode;
 use regex::Regex;
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value, json};
 
-/// Enable installation defaults without overriding an explicit user opt-out.
-pub fn setup_shell_hook(document: &mut crate::Document) -> Result<bool, crate::Error> {
-    let explicit = document
-        .doc
-        .get("activities")
-        .and_then(kdl::KdlNode::children)
-        .and_then(|sources| sources.get("sources"))
-        .and_then(kdl::KdlNode::children)
-        .and_then(|sources| sources.get("shell-hook"))
-        .and_then(|node| node.get(0))
-        .and_then(kdl::KdlValue::as_bool);
-    if explicit == Some(false) {
-        return Ok(false);
-    }
-    if explicit.is_none() {
-        document.set("activities.sources.shell_hook", json!(true))?;
-    }
-    Ok(true)
-}
-
 use crate::Error;
 
 #[derive(Clone, Debug, Deserialize, Serialize)]
@@ -215,7 +196,7 @@ impl Settings {
 }
 
 fn diagnostic(node: &KdlNode, message: impl std::fmt::Display) -> Error {
-    Error(format!(
+    Error::from(format!(
         "activities at byte {}: {message}",
         node.span().offset()
     ))
@@ -270,11 +251,11 @@ pub(crate) fn parse(node: &KdlNode) -> Result<Value, Error> {
                         property
                             .entries()
                             .iter()
-                            .map(|entry| crate::scalar(entry.value()))
+                            .map(|entry| document::scalar(entry.value()))
                             .collect::<Result<_, _>>()?,
                     )
                 } else {
-                    crate::node_value(property, &key, "rule")
+                    document::node_value(property, &key, "rule")
                         .map_err(|error| diagnostic(property, error))?
                 };
                 if value.insert(key, parsed).is_some() {
@@ -316,7 +297,7 @@ pub(crate) fn parse(node: &KdlNode) -> Result<Value, Error> {
                 return Err(diagnostic(child, "unknown activity node"));
             }
             let field = key.replace('-', "_");
-            let value = crate::node_value(child, &field, "activities")
+            let value = document::node_value(child, &field, "activities")
                 .map_err(|error| diagnostic(child, error))?;
             if values.insert(field, value).is_some() {
                 return Err(diagnostic(child, "duplicate activity setting"));
diff --git a/crates/ferese-config/src/document.rs b/crates/ferese-config/src/document.rs
new file mode 100644
index 0000000..0e51e9d
--- /dev/null
+++ b/crates/ferese-config/src/document.rs
@@ -0,0 +1,1171 @@
+use crate::{activities, theme};
+
+use std::fmt;
+use std::path::PathBuf;
+
+use kdl::{KdlDocument, KdlEntry, KdlNode, KdlValue};
+use serde::de::DeserializeOwned;
+use serde_json::{Map, Value};
+
+pub const DEFAULT_MATERIAL_OPACITY: f64 = 0.78;
+
+#[derive(Debug)]
+pub struct Error(String);
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(&self.0)
+    }
+}
+
+impl std::error::Error for Error {}
+
+impl From<String> for Error {
+    fn from(value: String) -> Self {
+        Self(value)
+    }
+}
+
+pub fn config_path() -> Option<PathBuf> {
+    std::env::var_os("XDG_CONFIG_HOME")
+        .map(PathBuf::from)
+        .or_else(|| std::env::var_os("HOME").map(|p| PathBuf::from(p).join(".config")))
+        .map(|p| p.join("ferese/config.kdl"))
+}
+
+pub fn default_wallpaper() -> &'static str {
+    default_wallpaper_for(theme::Appearance::Dark)
+}
+
+pub fn default_wallpaper_for(appearance: theme::Appearance) -> &'static str {
+    static LIGHT: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+    static DARK: std::sync::OnceLock<String> = std::sync::OnceLock::new();
+
+    let (slot, name) = match appearance {
+        theme::Appearance::Light => (&LIGHT, "ferese-wallpaper-light.png"),
+        theme::Appearance::Dark => (&DARK, "ferese-wallpaper-dark.png"),
+    };
+
+    slot.get_or_init(|| {
+        let path = std::env::current_exe()
+            .ok()
+            .and_then(|path| path.parent().map(|dir| dir.join("wallpapers").join(name)))
+            .filter(|path| path.is_file())
+            .unwrap_or_else(|| {
+                PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+                    .join("../../assets/wallpapers")
+                    .join(name)
+            });
+
+        path.canonicalize()
+            .unwrap_or(path)
+            .to_string_lossy()
+            .into_owned()
+    })
+}
+
+fn field(name: &str, parent: &str) -> String {
+    if matches!(parent, "commands" | "custom_themes") {
+        return name.to_owned();
+    }
+
+    match name {
+        "binding" => "bindings".into(),
+        "binding-mode" => "binding_modes".into(),
+        "window-rule" => "window_rules".into(),
+        "output-profile" => "output_profiles".into(),
+        "output" => "outputs".into(),
+        "panel" => "panels".into(),
+        "group" => "groups".into(),
+        "item" => "items".into(),
+        _ => name.replace('-', "_"),
+    }
+}
+
+fn is_records(key: &str, parent: &str) -> bool {
+    matches!(
+        (parent, key),
+        (
+            "",
+            "bindings"
+                | "binding_modes"
+                | "window_rules"
+                | "output_profiles"
+                | "autostart"
+                | "panels"
+        ) | ("output_profiles", "outputs")
+            | ("binding_modes", "bindings")
+            | ("start" | "center" | "end", "groups")
+            | ("groups", "items")
+    )
+}
+
+fn is_array(key: &str, parent: &str) -> bool {
+    parent == "commands"
+        || matches!(
+            key,
+            "command"
+                | "position"
+                | "padding"
+                | "width_presets"
+                | "xkb_options"
+                | "settings_command"
+                | "outputs"
+        )
+}
+
+pub(crate) fn scalar(value: &KdlValue) -> Result<Value, Error> {
+    Ok(match value {
+        KdlValue::String(s) => Value::String(s.clone()),
+        KdlValue::Bool(v) => Value::Bool(*v),
+        KdlValue::Null => {
+            return Err(Error(
+                "Omit optional settings instead of using #null".into(),
+            ));
+        }
+        KdlValue::Integer(n) => {
+            if let Ok(n) = i64::try_from(*n) {
+                n.into()
+            } else if let Ok(n) = u64::try_from(*n) {
+                n.into()
+            } else {
+                return Err(Error("Integer is outside the supported range".into()));
+            }
+        }
+        KdlValue::Float(n) => serde_json::Number::from_f64(*n)
+            .map(Value::Number)
+            .ok_or_else(|| Error("Configuration numbers must be finite".into()))?,
+    })
+}
+
+fn insert(map: &mut Map<String, Value>, key: String, value: Value) -> Result<(), Error> {
+    if map.insert(key.clone(), value).is_some() {
+        return Err(Error(format!("Duplicate setting: {key}")));
+    }
+    Ok(())
+}
+
+fn object(doc: &KdlDocument, parent: &str) -> Result<Map<String, Value>, Error> {
+    let mut result = Map::new();
+
+    for node in doc.nodes() {
+        let key = field(node.name().value(), parent);
+        if parent.is_empty() && key == "desktop_widgets" {
+            // Retired widgets stay in the source for edits but have no runtime effect.
+            continue;
+        }
+
+        let value = if parent.is_empty() && key == "activities" {
+            activities::parse(node)?
+        } else {
+            node_value(node, &key, parent)?
+        };
+        if is_records(&key, parent) {
+            let records = result
+                .entry(key)
+                .or_insert_with(|| Value::Array(Vec::new()));
+            records.as_array_mut().unwrap().push(value);
+        } else {
+            insert(&mut result, key, value)?;
+        }
+    }
+
+    Ok(result)
+}
+
+pub(crate) fn node_value(node: &KdlNode, key: &str, parent: &str) -> Result<Value, Error> {
+    if node.ty().is_some() || node.entries().iter().any(|e| e.ty().is_some()) {
+        return Err(Error(
+            "Type annotations are not supported in configuration".into(),
+        ));
+    }
+
+    let args = node
+        .entries()
+        .iter()
+        .filter(|e| e.name().is_none())
+        .map(|e| scalar(e.value()))
+        .collect::<Result<Vec<_>, _>>()?;
+    let props = node
+        .entries()
+        .iter()
+        .filter_map(|e| e.name().map(|n| (field(n.value(), key), e)))
+        .collect::<Vec<_>>();
+
+    if is_records(key, parent) {
+        let mut map = node
+            .children()
+            .map(|d| object(d, key))
+            .transpose()?
+            .unwrap_or_default();
+        for (name, entry) in props {
+            insert(&mut map, name, scalar(entry.value())?)?;
+        }
+        let positional: &[&str] = match key {
+            "bindings" => &["keys", "action", "argument"],
+            "binding_modes" => &["name"],
+            "output_profiles" => &["name"],
+            "outputs" => &["match"],
+            "panels" | "groups" | "items" => &["id"],
+            "autostart" => &[],
+            "window_rules" => &[],
+            _ => unreachable!(),
+        };
+
+        if key == "autostart" && !args.is_empty() {
+            insert(&mut map, "command".into(), args.into())?;
+        } else {
+            if args.len() > positional.len() {
+                return Err(Error(format!("Too many arguments for {}", node.name())));
+            }
+            for (name, value) in positional.iter().zip(args) {
+                insert(&mut map, (*name).into(), value)?;
+            }
+        }
+
+        return Ok(Value::Object(map));
+    }
+
+    if node.children().is_some() || !props.is_empty() {
+        if !args.is_empty() {
+            return Err(Error(format!(
+                "{} cannot combine scalar arguments with a section",
+                node.name()
+            )));
+        }
+
+        let mut map = node
+            .children()
+            .map(|d| object(d, key))
+            .transpose()?
+            .unwrap_or_default();
+        for (name, entry) in props {
+            insert(&mut map, name, scalar(entry.value())?)?;
+        }
+        return Ok(Value::Object(map));
+    }
+
+    if is_array(key, parent) {
+        return Ok(Value::Array(args));
+    }
+
+    if args.len() != 1 {
+        return Err(Error(format!("{} requires one value", node.name())));
+    }
+
+    Ok(args.into_iter().next().unwrap())
+}
+
+#[derive(Clone, Debug)]
+pub struct Document {
+    doc: KdlDocument,
+    value: Value,
+}
+
+impl Document {
+    /// Enable installation defaults without overriding an explicit user opt-out.
+    pub fn setup_shell_hook(&mut self) -> Result<bool, Error> {
+        let explicit = self
+            .doc
+            .get("activities")
+            .and_then(kdl::KdlNode::children)
+            .and_then(|sources| sources.get("sources"))
+            .and_then(kdl::KdlNode::children)
+            .and_then(|sources| sources.get("shell-hook"))
+            .and_then(|node| node.get(0))
+            .and_then(kdl::KdlValue::as_bool);
+        if explicit == Some(false) {
+            return Ok(false);
+        }
+        if explicit.is_none() {
+            self.set("activities.sources.shell_hook", serde_json::json!(true))?;
+        }
+        Ok(true)
+    }
+
+    pub fn parse(source: &str) -> Result<Self, Error> {
+        let doc = source
+            .parse::<KdlDocument>()
+            .map_err(|e| Error(format!("{e:?}")))?;
+        let value = Value::Object(object(&doc, "")?);
+
+        Ok(Self { doc, value })
+    }
+
+    pub fn value(&self) -> &Value {
+        &self.value
+    }
+
+    /// A runtime view; the original KDL remains available for comment-preserving edits.
+    pub fn with_theme(&self, theme: &theme::ResolvedTheme) -> Self {
+        let mut document = self.clone();
+        document.value["theme"] =
+            serde_json::to_value(&theme.tokens).expect("serializable theme tokens");
+        document.value["theme"]["appearance"] = serde_json::to_value(theme.appearance).unwrap();
+        document
+    }
+
+    pub fn get(&self, path: &str) -> Option<&Value> {
+        let mut value = &self.value;
+
+        for part in path.split('.') {
+            value = if let Ok(index) = part.parse::<usize>() {
+                value.get(index)?
+            } else {
+                value.get(part)?
+            };
+        }
+        Some(value)
+    }
+
+    fn refresh(&mut self) -> Result<(), Error> {
+        self.value = Value::Object(object(&self.doc, "")?);
+        Ok(())
+    }
+
+    pub fn set(&mut self, path: &str, value: Value) -> Result<(), Error> {
+        if value.as_str() == Some("")
+            && matches!(
+                path,
+                "theme.file" | "theme.light.file" | "theme.dark.file" | "theme.accent"
+            )
+        {
+            return self.unset(path);
+        }
+
+        let mut candidate = self.clone();
+        if matches!(
+            path,
+            "theme.mode"
+                | "theme.family"
+                | "theme.light.family"
+                | "theme.dark.family"
+                | "theme.light.preset"
+                | "theme.dark.preset"
+        ) {
+            candidate.migrate_theme_selection()?;
+        }
+
+        let parts = path.split('.').collect::<Vec<_>>();
+        set_in(&mut candidate.doc, &parts, "", value)?;
+        format_document(&mut candidate.doc);
+
+        candidate.refresh()?;
+        *self = candidate;
+
+        Ok(())
+    }
+
+    pub fn add(&mut self, path: &str, fields: Vec<(String, Value)>) -> Result<(), Error> {
+        let mut candidate = self.clone();
+        let (last, parents) = path.rsplit_once('.').map_or((path, ""), |(p, l)| (l, p));
+        let parent = parents
+            .rsplit('.')
+            .find(|s| s.parse::<usize>().is_err())
+            .unwrap_or("");
+
+        if !is_records(last, parent) {
+            return Err(Error("Expected a list of records".into()));
+        }
+
+        let doc = section_mut(
+            &mut candidate.doc,
+            &parents
+                .split('.')
+                .filter(|s| !s.is_empty())
+                .collect::<Vec<_>>(),
+            "",
+        )?;
+
+        doc.nodes_mut().push(value_node(
+            last,
+            &Value::Object(fields.into_iter().collect()),
+            parent,
+        )?);
+        format_document(&mut candidate.doc);
+        candidate.refresh()?;
+        *self = candidate;
+
+        Ok(())
+    }
+
+    fn migrate_theme_selection(&mut self) -> Result<(), Error> {
+        if self.get("theme.mode").is_some() {
+            return Ok(());
+        }
+
+        if self.get("theme.light").is_some() || self.get("theme.dark").is_some() {
+            set_in(
+                &mut self.doc,
+                &["theme", "mode"],
+                "",
+                Value::String("dark".into()),
+            )?;
+            return self.refresh();
+        }
+
+        let Some(index) = self
+            .doc
+            .nodes()
+            .iter()
+            .position(|node| node.name().value() == "theme")
+        else {
+            return Ok(());
+        };
+
+        if let Some(children) = self.doc.nodes_mut()[index].children_mut().as_mut() {
+            let mut moved = Vec::new();
+
+            for name in ["colors", "surface", "border", "focus-ring"] {
+                if let Some(index) = children
+                    .nodes()
+                    .iter()
+                    .position(|node| node.name().value() == name)
+                {
+                    moved.push(children.nodes_mut().remove(index));
+                }
+            }
+
+            if !moved.is_empty() {
+                let dark = section_mut(children, &["dark"], "theme")?;
+                dark.nodes_mut().extend(moved);
+            }
+        }
+
+        set_in(
+            &mut self.doc,
+            &["theme", "mode"],
+            "",
+            Value::String("dark".into()),
+        )?;
+        self.refresh()
+    }
+
+    pub fn unset(&mut self, path: &str) -> Result<(), Error> {
+        if self.get(path).is_none() {
+            return Ok(());
+        }
+
+        let mut candidate = self.clone();
+        let (name, parents) = path.rsplit_once('.').map_or((path, ""), |(p, n)| (n, p));
+
+        if unset_property(&mut candidate.doc, &path.split('.').collect::<Vec<_>>(), "")? {
+            format_document(&mut candidate.doc);
+            candidate.refresh()?;
+            *self = candidate;
+            return Ok(());
+        }
+
+        let doc = section_mut(
+            &mut candidate.doc,
+            &parents
+                .split('.')
+                .filter(|s| !s.is_empty())
+                .collect::<Vec<_>>(),
+            "",
+        )?;
+        if let Some(index) = doc.nodes().iter().position(|node| {
+            field(
+                node.name().value(),
+                parents.rsplit('.').next().unwrap_or(""),
+            ) == name
+        }) {
+            let node = doc.nodes_mut().remove(index);
+            let mut comments = String::new();
+
+            collect_comments(&node, &mut comments);
+
+            if let Some(format) = doc.format_mut() {
+                format.trailing.push_str(&comments);
+            } else {
+                doc.set_format(kdl::KdlDocumentFormat {
+                    leading: String::new(),
+                    trailing: comments,
+                });
+            }
+        }
+
+        format_document(&mut candidate.doc);
+        candidate.refresh()?;
+        *self = candidate;
+
+        Ok(())
+    }
+
+    pub fn remove(&mut self, path: &str, index: usize) -> Result<(), Error> {
+        let mut candidate = self.clone();
+        let (last, parents) = path.rsplit_once('.').map_or((path, ""), |(p, l)| (l, p));
+        let doc = section_mut(
+            &mut candidate.doc,
+            &parents
+                .split('.')
+                .filter(|s| !s.is_empty())
+                .collect::<Vec<_>>(),
+            "",
+        )?;
+        let i = doc
+            .nodes()
+            .iter()
+            .enumerate()
+            .filter(|(_, n)| {
+                field(n.name().value(), parents.rsplit('.').next().unwrap_or("")) == last
+            })
+            .nth(index)
+            .map(|(i, _)| i)
+            .ok_or_else(|| Error("This item no longer exists. Reload settings.".into()))?;
+
+        doc.nodes_mut().remove(i);
+        format_document(&mut candidate.doc);
+        candidate.refresh()?;
+        *self = candidate;
+
+        Ok(())
+    }
+}
+
+fn collect_comments(node: &KdlNode, output: &mut String) {
+    let mut keep = |text: &str| {
+        if text.contains("//") || text.contains("/*") {
+            output.push_str(text);
+            output.push('\n');
+        }
+    };
+
+    if let Some(format) = node.format() {
+        keep(&format.leading);
+        keep(&format.before_children);
+        keep(&format.before_terminator);
+        keep(&format.terminator);
+        keep(&format.trailing);
+    }
+
+    for entry in node.entries() {
+        if let Some(format) = entry.format() {
+            keep(&format.leading);
+            keep(&format.trailing);
+        }
+    }
+
+    if let Some(children) = node.children() {
+        if let Some(format) = children.format() {
+            keep(&format.leading);
+            keep(&format.trailing);
+        }
+
+        for child in children.nodes() {
+            collect_comments(child, output);
+        }
+    }
+}
+
+impl fmt::Display for Document {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.doc.fmt(f)
+    }
+}
+
+fn set_entry_value(entry: &mut KdlEntry, value: KdlValue) {
+    let representation = value.to_string();
+    entry.set_value(value);
+
+    if let Some(format) = entry.format_mut() {
+        format.value_repr = representation;
+    }
+}
+
+type NodeFormat = (Vec<Option<kdl::KdlEntryFormat>>, Option<String>);
+
+fn collect_node_formats(doc: &KdlDocument, formats: &mut Vec<NodeFormat>) {
+    for node in doc.nodes() {
+        let entries = node
+            .entries()
+            .iter()
+            .map(|entry| entry.format().cloned())
+            .collect();
+        let terminator = node
+            .format()
+            .map(|format| format.terminator.clone())
+            .filter(|text| text.contains("//") || text.contains("/*"));
+
+        formats.push((entries, terminator));
+
+        if let Some(children) = node.children() {
+            collect_node_formats(children, formats);
+        }
+    }
+}
+
+fn restore_node_formats(doc: &mut KdlDocument, formats: &mut impl Iterator<Item = NodeFormat>) {
+    for node in doc.nodes_mut() {
+        if let Some((entries, terminator)) = formats.next() {
+            for (entry, format) in node.entries_mut().iter_mut().zip(entries) {
+                if let Some(format) = format {
+                    entry.set_format(format);
+                }
+            }
+
+            if let Some(terminator) = terminator
+                && let Some(format) = node.format_mut()
+            {
+                format.before_terminator = " ".into();
+                format.terminator = terminator;
+            }
+        }
+
+        if let Some(children) = node.children_mut() {
+            restore_node_formats(children, formats);
+        }
+    }
+}
+
+fn format_document(doc: &mut KdlDocument) {
+    let mut formats = Vec::new();
+    collect_node_formats(doc, &mut formats);
+    doc.autoformat();
+    restore_node_formats(doc, &mut formats.into_iter());
+}
+
+fn node_index(doc: &mut KdlDocument, key: &str, parent: &str) -> usize {
+    if let Some(i) = doc
+        .nodes()
+        .iter()
+        .position(|n| field(n.name().value(), parent) == key)
+    {
+        return i;
+    }
+
+    doc.nodes_mut().push(KdlNode::new(node_name(key, parent)));
+    doc.nodes().len() - 1
+}
+
+fn section_mut<'a>(
+    doc: &'a mut KdlDocument,
+    parts: &[&str],
+    parent: &str,
+) -> Result<&'a mut KdlDocument, Error> {
+    if parts.is_empty() {
+        return Ok(doc);
+    }
+
+    let key = parts[0];
+    let i = node_index(doc, key, parent);
+    let mut used = 1;
+    let i = if is_records(key, parent) {
+        let index = parts
+            .get(1)
+            .and_then(|s| s.parse::<usize>().ok())
+            .ok_or_else(|| Error("Record index missing".into()))?;
+        used = 2;
+        doc.nodes()
+            .iter()
+            .enumerate()
+            .filter(|(_, n)| field(n.name().value(), parent) == key)
+            .nth(index)
+            .map(|(i, _)| i)
+            .ok_or_else(|| Error("This item no longer exists. Reload settings.".into()))?
+    } else {
+        i
+    };
+    let node = &mut doc.nodes_mut()[i];
+    let child = node.children_mut().get_or_insert_with(KdlDocument::new);
+
+    section_mut(child, &parts[used..], key)
+}
+
+/// Scalar settings in record nodes can be KDL properties rather than children.
+fn unset_property(doc: &mut KdlDocument, parts: &[&str], parent: &str) -> Result<bool, Error> {
+    if parts.len() < 2 {
+        return Ok(false);
+    }
+    let key = parts[0];
+    let record = is_records(key, parent);
+    let used = if record { 2 } else { 1 };
+    let index = if record {
+        parts
+            .get(1)
+            .and_then(|part| part.parse::<usize>().ok())
+            .ok_or_else(|| Error("Record index missing".into()))?
+    } else {
+        0
+    };
+    let Some(node) = doc
+        .nodes_mut()
+        .iter_mut()
+        .filter(|node| field(node.name().value(), parent) == key)
+        .nth(index)
+    else {
+        return Ok(false);
+    };
+    if parts.len() == used + 1
+        && let Some(index) = node.entries().iter().position(|entry| {
+            entry
+                .name()
+                .is_some_and(|name| field(name.value(), key) == parts[used])
+        })
+    {
+        let entry = node.entries_mut().remove(index);
+        if let Some(format) = entry.format() {
+            let comments = [&format.leading, &format.trailing]
+                .into_iter()
+                .filter(|part| part.contains("//") || part.contains("/*"))
+                .cloned()
+                .collect::<String>();
+            if !comments.is_empty() {
+                let mut format = node.format().cloned().unwrap_or_default();
+                format.leading.push_str(&comments);
+                node.set_format(format);
+            }
+        }
+        return Ok(true);
+    }
+    if let Some(children) = node.children_mut() {
+        unset_property(children, &parts[used..], key)
+    } else {
+        Ok(false)
+    }
+}
+
+fn set_in(doc: &mut KdlDocument, parts: &[&str], parent: &str, value: Value) -> Result<(), Error> {
+    if parts.is_empty() {
+        return Err(Error("Missing setting path".into()));
+    }
+
+    let key = parts[0];
+    if parts.len() == 1 && is_records(key, parent) {
+        let records = value
+            .as_array()
+            .ok_or_else(|| Error("Expected a list of records".into()))?;
+        let mut nodes = records
+            .iter()
+            .map(|value| value_node(key, value, parent))
+            .collect::<Result<Vec<_>, _>>()?;
+        let at = doc
+            .nodes()
+            .iter()
+            .position(|node| field(node.name().value(), parent) == key)
+            .unwrap_or(doc.nodes().len());
+        let mut comments = String::new();
+        for node in doc
+            .nodes()
+            .iter()
+            .filter(|node| field(node.name().value(), parent) == key)
+        {
+            collect_comments(node, &mut comments);
+        }
+        doc.nodes_mut()
+            .retain(|node| field(node.name().value(), parent) != key);
+        if let Some(first) = nodes.first_mut() {
+            first.set_format(kdl::KdlNodeFormat {
+                leading: comments,
+                ..Default::default()
+            });
+        } else if !comments.is_empty() {
+            let mut format = doc.format().cloned().unwrap_or_default();
+            format.trailing.push_str(&comments);
+            doc.set_format(format);
+        }
+        doc.nodes_mut().splice(at..at, nodes);
+        return Ok(());
+    }
+    let i = node_index(doc, key, parent);
+
+    if parts.len() == 1 {
+        let new = value_node(key, &value, parent)?;
+        let node = &mut doc.nodes_mut()[i];
+        if new.entries().len() == 1 && node.entries().len() == 1 && node.children().is_none() {
+            set_entry_value(&mut node.entries_mut()[0], new.entries()[0].value().clone());
+            node.entries_mut()[0].set_name(None::<String>);
+        } else {
+            *node.entries_mut() = new.entries().to_vec();
+            *node.children_mut() = new.children().cloned();
+        }
+
+        return Ok(());
+    }
+
+    if is_records(key, parent) {
+        let index = parts[1]
+            .parse::<usize>()
+            .map_err(|_| Error("Record index missing".into()))?;
+        let i = doc
+            .nodes()
+            .iter()
+            .enumerate()
+            .filter(|(_, n)| field(n.name().value(), parent) == key)
+            .nth(index)
+            .map(|(i, _)| i)
+            .ok_or_else(|| Error("This item no longer exists. Reload settings.".into()))?;
+        let node = &mut doc.nodes_mut()[i];
+        let rest = &parts[2..];
+
+        if rest.len() == 1 {
+            let positions: &[&str] = match key {
+                "bindings" => &["keys", "action", "argument"],
+                "binding_modes" => &["name"],
+                "outputs" => &["match"],
+                "output_profiles" => &["name"],
+                "panels" | "groups" | "items" => &["id"],
+                _ => &[],
+            };
+            let position = positions.iter().position(|p| *p == rest[0]);
+            let mut arg_index = 0;
+
+            for entry in node.entries_mut() {
+                let matches = if let Some(name) = entry.name() {
+                    field(name.value(), key) == rest[0]
+                } else {
+                    let matches = Some(arg_index) == position;
+                    arg_index += 1;
+                    matches
+                };
+
+                if matches {
+                    set_entry_value(entry, kdl_value(&value)?);
+                    return Ok(());
+                }
+            }
+
+            if key == "autostart"
+                && rest[0] == "command"
+                && node.children().is_none_or(|d| d.get("command").is_none())
+            {
+                node.entries_mut().retain(|e| e.name().is_some());
+                for value in value
+                    .as_array()
+                    .ok_or_else(|| Error("Command must be an array".into()))?
+                {
+                    node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
+                }
+                return Ok(());
+            }
+        }
+
+        return set_in(
+            node.children_mut().get_or_insert_with(KdlDocument::new),
+            rest,
+            key,
+            value,
+        );
+    }
+    let node = &mut doc.nodes_mut()[i];
+
+    if parts.len() == 2
+        && let Some(entry) = node
+            .entries_mut()
+            .iter_mut()
+            .find(|e| e.name().is_some_and(|n| field(n.value(), key) == parts[1]))
+    {
+        set_entry_value(entry, kdl_value(&value)?);
+        return Ok(());
+    }
+
+    set_in(
+        node.children_mut().get_or_insert_with(KdlDocument::new),
+        &parts[1..],
+        key,
+        value,
+    )
+}
+
+fn kdl_value(value: &Value) -> Result<KdlValue, Error> {
+    Ok(match value {
+        Value::String(s) => KdlValue::String(s.clone()),
+        Value::Bool(b) => KdlValue::Bool(*b),
+        Value::Number(n) => {
+            if let Some(i) = n.as_i64() {
+                KdlValue::Integer(i.into())
+            } else if let Some(i) = n.as_u64() {
+                KdlValue::Integer(i.into())
+            } else {
+                KdlValue::Float(n.as_f64().unwrap())
+            }
+        }
+        _ => return Err(Error("Expected a scalar value".into())),
+    })
+}
+
+fn node_name(key: &str, parent: &str) -> String {
+    if matches!(parent, "commands" | "custom_themes") {
+        return key.into();
+    }
+
+    if !is_records(key, parent) {
+        return key.replace('_', "-");
+    }
+
+    match key {
+        "bindings" => "binding".into(),
+        "binding_modes" => "binding-mode".into(),
+        "window_rules" => "window-rule".into(),
+        "output_profiles" => "output-profile".into(),
+        "outputs" => "output".into(),
+        "panels" => "panel".into(),
+        "groups" => "group".into(),
+        "items" => "item".into(),
+        _ => key.replace('_', "-"),
+    }
+}
+
+fn value_node(key: &str, value: &Value, parent: &str) -> Result<KdlNode, Error> {
+    let mut node = KdlNode::new(node_name(key, parent));
+
+    match value {
+        Value::Object(map) => {
+            let positions: &[&str] = match key {
+                "bindings" => &["keys", "action", "argument"],
+                "binding_modes" => &["name"],
+                "output_profiles" => &["name"],
+                "outputs" => &["match"],
+                "panels" | "groups" | "items" => &["id"],
+                _ => &[],
+            };
+            let mut child = KdlDocument::new();
+            let mut consumed = Vec::new();
+
+            for name in positions {
+                if let Some(value) = map.get(*name) {
+                    node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
+                    consumed.push(*name);
+                } else {
+                    break;
+                }
+            }
+
+            for (name, value) in map {
+                if consumed.contains(&name.as_str()) {
+                    continue;
+                }
+                if key == "autostart" && name == "command" {
+                    for value in value
+                        .as_array()
+                        .ok_or_else(|| Error("Command must be an array".into()))?
+                    {
+                        node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
+                    }
+                } else if is_records(key, parent)
+                    && map.len() <= 4
+                    && !value.is_array()
+                    && !value.is_object()
+                {
+                    node.entries_mut().push(KdlEntry::new_prop(
+                        name.replace('_', "-"),
+                        kdl_value(value)?,
+                    ));
+                } else {
+                    append(&mut child, name, value, key)?;
+                }
+            }
+
+            if !child.nodes().is_empty() || node.entries().is_empty() {
+                node.set_children(child);
+            }
+        }
+        Value::Array(array) => {
+            for value in array {
+                node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
+            }
+        }
+        _ => node.entries_mut().push(KdlEntry::new(kdl_value(value)?)),
+    }
+    Ok(node)
+}
+
+fn append(doc: &mut KdlDocument, key: &str, value: &Value, parent: &str) -> Result<(), Error> {
+    if is_records(key, parent) {
+        for record in value
+            .as_array()
+            .ok_or_else(|| Error("Expected records".into()))?
+        {
+            doc.nodes_mut().push(value_node(key, record, parent)?);
+        }
+    } else {
+        doc.nodes_mut().push(value_node(key, value, parent)?);
+    }
+    Ok(())
+}
+
+pub fn from_str<T: DeserializeOwned>(source: &str) -> Result<T, Error> {
+    serde_json::from_value(Document::parse(source)?.value).map_err(|e| Error(e.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn named_binding_modes_round_trip_and_keep_nested_bindings_editable() {
+        let mut document = super::Document::parse(
+            "binding-mode resize { binding h resize left; binding l resize right; }\nbinding-mode launch { binding t spawn terminal; }\n",
+        ).unwrap();
+        assert_eq!(document.get("binding_modes.0.name").unwrap(), "resize");
+        assert_eq!(
+            document.get("binding_modes.1.bindings.0.argument").unwrap(),
+            "terminal"
+        );
+        document
+            .set("binding_modes.0.bindings.0.argument", "up".into())
+            .unwrap();
+        let reparsed = super::Document::parse(&document.to_string()).unwrap();
+        assert_eq!(
+            reparsed.get("binding_modes.0.bindings.0.argument").unwrap(),
+            "up"
+        );
+        assert_eq!(
+            reparsed.get("binding_modes.0.bindings.1.argument").unwrap(),
+            "right"
+        );
+    }
+    #[test]
+    fn adopting_appearance_modes_preserves_legacy_colors_and_comments() {
+        let mut document = Document::parse(
+            "// my desktop\ntheme {\n    colors {\n        accent \"#123456\" // my accent\n    }\n}\n",
+        )
+        .unwrap();
+        document
+            .set("theme.mode", serde_json::json!("light"))
+            .unwrap();
+        assert_eq!(
+            document.get("theme.dark.colors.accent"),
+            Some(&serde_json::json!("#123456"))
+        );
+        assert!(document.get("theme.colors").is_none());
+        assert!(document.to_string().contains("// my accent"));
+        document.unset("theme.dark.colors").unwrap();
+        assert!(document.to_string().contains("// my accent"));
+        assert!(document.to_string().contains("// my desktop"));
+        Document::parse(&document.to_string()).unwrap();
+    }
+
+    #[test]
+    fn clearing_optional_theme_references_removes_them_without_empty_paths() {
+        let mut document = Document::parse("theme { file \"custom_theme.kdl\"; } ").unwrap();
+        document.set("theme.file", serde_json::json!("")).unwrap();
+        assert!(document.get("theme.file").is_none());
+        document.set("theme.file", serde_json::json!("")).unwrap();
+    }
+
+    #[test]
+    fn inline_comments_and_failed_edits_leave_document_intact() {
+        let mut doc =
+            Document::parse("// header\nanimations {\n    speed 0.75 // keep inline\n}\n").unwrap();
+        doc.set("animations.speed", 0.8.into()).unwrap();
+        assert!(doc.to_string().contains("// keep inline"));
+        assert_eq!(
+            Document::parse(&doc.to_string())
+                .unwrap()
+                .get("animations.speed")
+                .unwrap(),
+            0.8
+        );
+        let previous = doc.to_string();
+        assert!(doc.set("bindings.4.keys", "X".into()).is_err());
+        assert_eq!(doc.to_string(), previous);
+    }
+
+    #[test]
+    fn editing_autostart_commands_handles_both_representations() {
+        for source in [
+            "autostart \"old\" enabled=#true\n",
+            "autostart { command \"old\"; enabled #true; }\n",
+        ] {
+            let mut doc = Document::parse(source).unwrap();
+            doc.set("autostart.0.command", serde_json::json!(["new", "arg"]))
+                .unwrap();
+            let reparsed = Document::parse(&doc.to_string()).unwrap();
+            assert_eq!(
+                reparsed.get("autostart.0.command").unwrap(),
+                &serde_json::json!(["new", "arg"])
+            );
+        }
+    }
+
+    #[test]
+    fn compact_syntax_and_nested_arrays_roundtrip() {
+        let source = r#"input repeat-rate=30 { xkb-options "compose:ralt"; }
+binding "Swipe3Up" "toggle-overview"
+output-profile "desk" { output "HDMI-A-1" scale=1.5 { position 0 0; }; }
+autostart "program" "two words" enabled=#false
+"#;
+        let mut doc = Document::parse(source).unwrap();
+        assert_eq!(doc.get("bindings.0.action").unwrap(), "toggle-overview");
+        doc.set("bindings.0.action", "none".into()).unwrap();
+        doc.set("input.repeat_rate", 25.into()).unwrap();
+        doc.set("output_profiles.0.outputs.0.scale", 2.0.into())
+            .unwrap();
+        let reparsed = Document::parse(&doc.to_string()).unwrap();
+        assert_eq!(reparsed.get("bindings.0.action").unwrap(), "none");
+        assert_eq!(reparsed.get("input.repeat_rate").unwrap(), 25);
+        assert_eq!(
+            reparsed.get("output_profiles.0.outputs.0.scale").unwrap(),
+            2.0
+        );
+    }
+
+    #[test]
+    fn output_arrays_and_command_names_survive_edits() {
+        let mut doc = Document::parse(
+            "output-profile desk { output match=\"DP-1\" { position 0 0; }; }\ncommands { lock-screen \"locker\"; }\n",
+        )
+        .unwrap();
+        doc.set(
+            "output_profiles.0.outputs.0.position",
+            serde_json::json!([100, 200]),
+        )
+        .unwrap();
+        doc.set(
+            "commands.lock-screen",
+            serde_json::json!(["ferese-lock", "--lock"]),
+        )
+        .unwrap();
+        let reparsed = Document::parse(&doc.to_string()).unwrap();
+        assert_eq!(
+            reparsed
+                .get("output_profiles.0.outputs.0.position")
+                .unwrap(),
+            &serde_json::json!([100, 200])
+        );
+        assert_eq!(
+            reparsed.get("commands.lock-screen").unwrap(),
+            &serde_json::json!(["ferese-lock", "--lock"])
+        );
+    }
+
+    #[test]
+    fn edits_preserve_comments_and_multiline_authored_metadata() {
+        let mut doc = Document::parse("// keep this\ncustom { text \"old\"; }\n").unwrap();
+        doc.set("custom.text", "one\ntwo".into()).unwrap();
+        assert!(doc.to_string().contains("// keep this"));
+        let reparsed = Document::parse(&doc.to_string()).unwrap();
+        assert_eq!(reparsed.get("custom.text").unwrap(), "one\ntwo");
+    }
+
+    #[test]
+    fn removed_desktop_widgets_are_ignored_without_affecting_authored_metadata() {
+        for section in ["desktop-widgets", "desktop_widgets"] {
+            let source = format!("{section} {{ clock {{ enabled #true; }}; }}");
+            let doc = Document::parse(&source).unwrap();
+            assert!(doc.get("desktop_widgets").is_none());
+            assert_eq!(doc.to_string(), source);
+            assert_eq!(
+                crate::from_str::<serde_json::Value>(&source).unwrap(),
+                serde_json::json!({})
+            );
+        }
+        assert!(
+            Document::parse("panel main { metadata { desktop-widgets \"custom\"; }; }").is_ok()
+        );
+    }
+
+    #[test]
+    fn rejects_duplicate_fields_ambiguous_syntax_and_nonfinite_values() {
+        for source in [
+            "input { repeat-rate 25; repeat_rate 30; }",
+            "binding \"X\" keys=\"Y\"",
+            "input 1 { repeat-rate 25; }",
+            "layout { inner-gap #inf; }",
+            "layout { inner-gap #null; }",
+        ] {
+            assert!(Document::parse(source).is_err(), "{source}");
+        }
+    }
+}
diff --git a/crates/ferese-config/src/lib.rs b/crates/ferese-config/src/lib.rs
index e6966f1..db8ebd1 100644
--- a/crates/ferese-config/src/lib.rs
+++ b/crates/ferese-config/src/lib.rs
@@ -1,1160 +1,13 @@
+//! KDL documents, validation and persisted configuration values.
 pub mod activities;
+mod document;
 pub mod families;
 pub mod file;
 pub mod night_light;
 pub mod notifications;
-pub use ferese_panel::panel;
 pub mod presets;
 pub mod theme;
 
-use std::fmt;
-use std::path::PathBuf;
-
-use kdl::{KdlDocument, KdlEntry, KdlNode, KdlValue};
-use serde::de::DeserializeOwned;
-use serde_json::{Map, Value};
-
-pub const DEFAULT_MATERIAL_OPACITY: f64 = 0.78;
-
+pub use document::*;
+pub use ferese_panel::panel;
 pub use ferese_panel::{PanelStyle, default_island_padding};
-
-#[derive(Debug)]
-pub struct Error(String);
-
-impl fmt::Display for Error {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        f.write_str(&self.0)
-    }
-}
-
-impl std::error::Error for Error {}
-
-impl From<String> for Error {
-    fn from(value: String) -> Self {
-        Self(value)
-    }
-}
-
-pub fn config_path() -> Option<PathBuf> {
-    std::env::var_os("XDG_CONFIG_HOME")
-        .map(PathBuf::from)
-        .or_else(|| std::env::var_os("HOME").map(|p| PathBuf::from(p).join(".config")))
-        .map(|p| p.join("ferese/config.kdl"))
-}
-
-pub fn default_wallpaper() -> &'static str {
-    default_wallpaper_for(theme::Appearance::Dark)
-}
-
-pub fn default_wallpaper_for(appearance: theme::Appearance) -> &'static str {
-    static LIGHT: std::sync::OnceLock<String> = std::sync::OnceLock::new();
-    static DARK: std::sync::OnceLock<String> = std::sync::OnceLock::new();
-
-    let (slot, name) = match appearance {
-        theme::Appearance::Light => (&LIGHT, "ferese-wallpaper-light.png"),
-        theme::Appearance::Dark => (&DARK, "ferese-wallpaper-dark.png"),
-    };
-
-    slot.get_or_init(|| {
-        let path = std::env::current_exe()
-            .ok()
-            .and_then(|path| path.parent().map(|dir| dir.join("wallpapers").join(name)))
-            .filter(|path| path.is_file())
-            .unwrap_or_else(|| {
-                PathBuf::from(env!("CARGO_MANIFEST_DIR"))
-                    .join("../../assets/wallpapers")
-                    .join(name)
-            });
-
-        path.canonicalize()
-            .unwrap_or(path)
-            .to_string_lossy()
-            .into_owned()
-    })
-}
-
-fn field(name: &str, parent: &str) -> String {
-    if matches!(parent, "commands" | "custom_themes") {
-        return name.to_owned();
-    }
-
-    match name {
-        "binding" => "bindings".into(),
-        "binding-mode" => "binding_modes".into(),
-        "window-rule" => "window_rules".into(),
-        "output-profile" => "output_profiles".into(),
-        "output" => "outputs".into(),
-        "panel" => "panels".into(),
-        "group" => "groups".into(),
-        "item" => "items".into(),
-        _ => name.replace('-', "_"),
-    }
-}
-
-fn is_records(key: &str, parent: &str) -> bool {
-    matches!(
-        (parent, key),
-        (
-            "",
-            "bindings"
-                | "binding_modes"
-                | "window_rules"
-                | "output_profiles"
-                | "autostart"
-                | "panels"
-        ) | ("output_profiles", "outputs")
-            | ("binding_modes", "bindings")
-            | ("start" | "center" | "end", "groups")
-            | ("groups", "items")
-    )
-}
-
-fn is_array(key: &str, parent: &str) -> bool {
-    parent == "commands"
-        || matches!(
-            key,
-            "command"
-                | "position"
-                | "padding"
-                | "width_presets"
-                | "xkb_options"
-                | "settings_command"
-                | "outputs"
-        )
-}
-
-fn scalar(value: &KdlValue) -> Result<Value, Error> {
-    Ok(match value {
-        KdlValue::String(s) => Value::String(s.clone()),
-        KdlValue::Bool(v) => Value::Bool(*v),
-        KdlValue::Null => {
-            return Err(Error(
-                "Omit optional settings instead of using #null".into(),
-            ));
-        }
-        KdlValue::Integer(n) => {
-            if let Ok(n) = i64::try_from(*n) {
-                n.into()
-            } else if let Ok(n) = u64::try_from(*n) {
-                n.into()
-            } else {
-                return Err(Error("Integer is outside the supported range".into()));
-            }
-        }
-        KdlValue::Float(n) => serde_json::Number::from_f64(*n)
-            .map(Value::Number)
-            .ok_or_else(|| Error("Configuration numbers must be finite".into()))?,
-    })
-}
-
-fn insert(map: &mut Map<String, Value>, key: String, value: Value) -> Result<(), Error> {
-    if map.insert(key.clone(), value).is_some() {
-        return Err(Error(format!("Duplicate setting: {key}")));
-    }
-    Ok(())
-}
-
-fn object(doc: &KdlDocument, parent: &str) -> Result<Map<String, Value>, Error> {
-    let mut result = Map::new();
-
-    for node in doc.nodes() {
-        let key = field(node.name().value(), parent);
-        if parent.is_empty() && key == "desktop_widgets" {
-            // Retired widgets stay in the source for edits but have no runtime effect.
-            continue;
-        }
-
-        let value = if parent.is_empty() && key == "activities" {
-            activities::parse(node)?
-        } else {
-            node_value(node, &key, parent)?
-        };
-        if is_records(&key, parent) {
-            let records = result
-                .entry(key)
-                .or_insert_with(|| Value::Array(Vec::new()));
-            records.as_array_mut().unwrap().push(value);
-        } else {
-            insert(&mut result, key, value)?;
-        }
-    }
-
-    Ok(result)
-}
-
-fn node_value(node: &KdlNode, key: &str, parent: &str) -> Result<Value, Error> {
-    if node.ty().is_some() || node.entries().iter().any(|e| e.ty().is_some()) {
-        return Err(Error(
-            "Type annotations are not supported in configuration".into(),
-        ));
-    }
-
-    let args = node
-        .entries()
-        .iter()
-        .filter(|e| e.name().is_none())
-        .map(|e| scalar(e.value()))
-        .collect::<Result<Vec<_>, _>>()?;
-    let props = node
-        .entries()
-        .iter()
-        .filter_map(|e| e.name().map(|n| (field(n.value(), key), e)))
-        .collect::<Vec<_>>();
-
-    if is_records(key, parent) {
-        let mut map = node
-            .children()
-            .map(|d| object(d, key))
-            .transpose()?
-            .unwrap_or_default();
-        for (name, entry) in props {
-            insert(&mut map, name, scalar(entry.value())?)?;
-        }
-        let positional: &[&str] = match key {
-            "bindings" => &["keys", "action", "argument"],
-            "binding_modes" => &["name"],
-            "output_profiles" => &["name"],
-            "outputs" => &["match"],
-            "panels" | "groups" | "items" => &["id"],
-            "autostart" => &[],
-            "window_rules" => &[],
-            _ => unreachable!(),
-        };
-
-        if key == "autostart" && !args.is_empty() {
-            insert(&mut map, "command".into(), args.into())?;
-        } else {
-            if args.len() > positional.len() {
-                return Err(Error(format!("Too many arguments for {}", node.name())));
-            }
-            for (name, value) in positional.iter().zip(args) {
-                insert(&mut map, (*name).into(), value)?;
-            }
-        }
-
-        return Ok(Value::Object(map));
-    }
-
-    if node.children().is_some() || !props.is_empty() {
-        if !args.is_empty() {
-            return Err(Error(format!(
-                "{} cannot combine scalar arguments with a section",
-                node.name()
-            )));
-        }
-
-        let mut map = node
-            .children()
-            .map(|d| object(d, key))
-            .transpose()?
-            .unwrap_or_default();
-        for (name, entry) in props {
-            insert(&mut map, name, scalar(entry.value())?)?;
-        }
-        return Ok(Value::Object(map));
-    }
-
-    if is_array(key, parent) {
-        return Ok(Value::Array(args));
-    }
-
-    if args.len() != 1 {
-        return Err(Error(format!("{} requires one value", node.name())));
-    }
-
-    Ok(args.into_iter().next().unwrap())
-}
-
-#[derive(Clone, Debug)]
-pub struct Document {
-    doc: KdlDocument,
-    value: Value,
-}
-
-impl Document {
-    pub fn parse(source: &str) -> Result<Self, Error> {
-        let doc = source
-            .parse::<KdlDocument>()
-            .map_err(|e| Error(format!("{e:?}")))?;
-        let value = Value::Object(object(&doc, "")?);
-
-        Ok(Self { doc, value })
-    }
-
-    pub fn value(&self) -> &Value {
-        &self.value
-    }
-
-    /// A runtime view; the original KDL remains available for comment-preserving edits.
-    pub fn with_theme(&self, theme: &theme::ResolvedTheme) -> Self {
-        let mut document = self.clone();
-        document.value["theme"] =
-            serde_json::to_value(&theme.tokens).expect("serializable theme tokens");
-        document.value["theme"]["appearance"] = serde_json::to_value(theme.appearance).unwrap();
-        document
-    }
-
-    pub fn get(&self, path: &str) -> Option<&Value> {
-        let mut value = &self.value;
-
-        for part in path.split('.') {
-            value = if let Ok(index) = part.parse::<usize>() {
-                value.get(index)?
-            } else {
-                value.get(part)?
-            };
-        }
-        Some(value)
-    }
-
-    fn refresh(&mut self) -> Result<(), Error> {
-        self.value = Value::Object(object(&self.doc, "")?);
-        Ok(())
-    }
-
-    pub fn set(&mut self, path: &str, value: Value) -> Result<(), Error> {
-        if value.as_str() == Some("")
-            && matches!(
-                path,
-                "theme.file" | "theme.light.file" | "theme.dark.file" | "theme.accent"
-            )
-        {
-            return self.unset(path);
-        }
-
-        let mut candidate = self.clone();
-        if matches!(
-            path,
-            "theme.mode"
-                | "theme.family"
-                | "theme.light.family"
-                | "theme.dark.family"
-                | "theme.light.preset"
-                | "theme.dark.preset"
-        ) {
-            candidate.migrate_theme_selection()?;
-        }
-
-        let parts = path.split('.').collect::<Vec<_>>();
-        set_in(&mut candidate.doc, &parts, "", value)?;
-        format_document(&mut candidate.doc);
-
-        candidate.refresh()?;
-        *self = candidate;
-
-        Ok(())
-    }
-
-    pub fn add(&mut self, path: &str, fields: Vec<(String, Value)>) -> Result<(), Error> {
-        let mut candidate = self.clone();
-        let (last, parents) = path.rsplit_once('.').map_or((path, ""), |(p, l)| (l, p));
-        let parent = parents
-            .rsplit('.')
-            .find(|s| s.parse::<usize>().is_err())
-            .unwrap_or("");
-
-        if !is_records(last, parent) {
-            return Err(Error("Expected a list of records".into()));
-        }
-
-        let doc = section_mut(
-            &mut candidate.doc,
-            &parents
-                .split('.')
-                .filter(|s| !s.is_empty())
-                .collect::<Vec<_>>(),
-            "",
-        )?;
-
-        doc.nodes_mut().push(value_node(
-            last,
-            &Value::Object(fields.into_iter().collect()),
-            parent,
-        )?);
-        format_document(&mut candidate.doc);
-        candidate.refresh()?;
-        *self = candidate;
-
-        Ok(())
-    }
-
-    fn migrate_theme_selection(&mut self) -> Result<(), Error> {
-        if self.get("theme.mode").is_some() {
-            return Ok(());
-        }
-
-        if self.get("theme.light").is_some() || self.get("theme.dark").is_some() {
-            set_in(
-                &mut self.doc,
-                &["theme", "mode"],
-                "",
-                Value::String("dark".into()),
-            )?;
-            return self.refresh();
-        }
-
-        let Some(index) = self
-            .doc
-            .nodes()
-            .iter()
-            .position(|node| node.name().value() == "theme")
-        else {
-            return Ok(());
-        };
-
-        if let Some(children) = self.doc.nodes_mut()[index].children_mut().as_mut() {
-            let mut moved = Vec::new();
-
-            for name in ["colors", "surface", "border", "focus-ring"] {
-                if let Some(index) = children
-                    .nodes()
-                    .iter()
-                    .position(|node| node.name().value() == name)
-                {
-                    moved.push(children.nodes_mut().remove(index));
-                }
-            }
-
-            if !moved.is_empty() {
-                let dark = section_mut(children, &["dark"], "theme")?;
-                dark.nodes_mut().extend(moved);
-            }
-        }
-
-        set_in(
-            &mut self.doc,
-            &["theme", "mode"],
-            "",
-            Value::String("dark".into()),
-        )?;
-        self.refresh()
-    }
-
-    pub fn unset(&mut self, path: &str) -> Result<(), Error> {
-        if self.get(path).is_none() {
-            return Ok(());
-        }
-
-        let mut candidate = self.clone();
-        let (name, parents) = path.rsplit_once('.').map_or((path, ""), |(p, n)| (n, p));
-
-        if unset_property(&mut candidate.doc, &path.split('.').collect::<Vec<_>>(), "")? {
-            format_document(&mut candidate.doc);
-            candidate.refresh()?;
-            *self = candidate;
-            return Ok(());
-        }
-
-        let doc = section_mut(
-            &mut candidate.doc,
-            &parents
-                .split('.')
-                .filter(|s| !s.is_empty())
-                .collect::<Vec<_>>(),
-            "",
-        )?;
-        if let Some(index) = doc.nodes().iter().position(|node| {
-            field(
-                node.name().value(),
-                parents.rsplit('.').next().unwrap_or(""),
-            ) == name
-        }) {
-            let node = doc.nodes_mut().remove(index);
-            let mut comments = String::new();
-
-            collect_comments(&node, &mut comments);
-
-            if let Some(format) = doc.format_mut() {
-                format.trailing.push_str(&comments);
-            } else {
-                doc.set_format(kdl::KdlDocumentFormat {
-                    leading: String::new(),
-                    trailing: comments,
-                });
-            }
-        }
-
-        format_document(&mut candidate.doc);
-        candidate.refresh()?;
-        *self = candidate;
-
-        Ok(())
-    }
-
-    pub fn remove(&mut self, path: &str, index: usize) -> Result<(), Error> {
-        let mut candidate = self.clone();
-        let (last, parents) = path.rsplit_once('.').map_or((path, ""), |(p, l)| (l, p));
-        let doc = section_mut(
-            &mut candidate.doc,
-            &parents
-                .split('.')
-                .filter(|s| !s.is_empty())
-                .collect::<Vec<_>>(),
-            "",
-        )?;
-        let i = doc
-            .nodes()
-            .iter()
-            .enumerate()
-            .filter(|(_, n)| {
-                field(n.name().value(), parents.rsplit('.').next().unwrap_or("")) == last
-            })
-            .nth(index)
-            .map(|(i, _)| i)
-            .ok_or_else(|| Error("This item no longer exists. Reload settings.".into()))?;
-
-        doc.nodes_mut().remove(i);
-        format_document(&mut candidate.doc);
-        candidate.refresh()?;
-        *self = candidate;
-
-        Ok(())
-    }
-}
-
-fn collect_comments(node: &KdlNode, output: &mut String) {
-    let mut keep = |text: &str| {
-        if text.contains("//") || text.contains("/*") {
-            output.push_str(text);
-            output.push('\n');
-        }
-    };
-
-    if let Some(format) = node.format() {
-        keep(&format.leading);
-        keep(&format.before_children);
-        keep(&format.before_terminator);
-        keep(&format.terminator);
-        keep(&format.trailing);
-    }
-
-    for entry in node.entries() {
-        if let Some(format) = entry.format() {
-            keep(&format.leading);
-            keep(&format.trailing);
-        }
-    }
-
-    if let Some(children) = node.children() {
-        if let Some(format) = children.format() {
-            keep(&format.leading);
-            keep(&format.trailing);
-        }
-
-        for child in children.nodes() {
-            collect_comments(child, output);
-        }
-    }
-}
-
-impl fmt::Display for Document {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        self.doc.fmt(f)
-    }
-}
-
-fn set_entry_value(entry: &mut KdlEntry, value: KdlValue) {
-    let representation = value.to_string();
-    entry.set_value(value);
-
-    if let Some(format) = entry.format_mut() {
-        format.value_repr = representation;
-    }
-}
-
-type NodeFormat = (Vec<Option<kdl::KdlEntryFormat>>, Option<String>);
-
-fn collect_node_formats(doc: &KdlDocument, formats: &mut Vec<NodeFormat>) {
-    for node in doc.nodes() {
-        let entries = node
-            .entries()
-            .iter()
-            .map(|entry| entry.format().cloned())
-            .collect();
-        let terminator = node
-            .format()
-            .map(|format| format.terminator.clone())
-            .filter(|text| text.contains("//") || text.contains("/*"));
-
-        formats.push((entries, terminator));
-
-        if let Some(children) = node.children() {
-            collect_node_formats(children, formats);
-        }
-    }
-}
-
-fn restore_node_formats(doc: &mut KdlDocument, formats: &mut impl Iterator<Item = NodeFormat>) {
-    for node in doc.nodes_mut() {
-        if let Some((entries, terminator)) = formats.next() {
-            for (entry, format) in node.entries_mut().iter_mut().zip(entries) {
-                if let Some(format) = format {
-                    entry.set_format(format);
-                }
-            }
-
-            if let Some(terminator) = terminator
-                && let Some(format) = node.format_mut()
-            {
-                format.before_terminator = " ".into();
-                format.terminator = terminator;
-            }
-        }
-
-        if let Some(children) = node.children_mut() {
-            restore_node_formats(children, formats);
-        }
-    }
-}
-
-fn format_document(doc: &mut KdlDocument) {
-    let mut formats = Vec::new();
-    collect_node_formats(doc, &mut formats);
-    doc.autoformat();
-    restore_node_formats(doc, &mut formats.into_iter());
-}
-
-fn node_index(doc: &mut KdlDocument, key: &str, parent: &str) -> usize {
-    if let Some(i) = doc
-        .nodes()
-        .iter()
-        .position(|n| field(n.name().value(), parent) == key)
-    {
-        return i;
-    }
-
-    doc.nodes_mut().push(KdlNode::new(node_name(key, parent)));
-    doc.nodes().len() - 1
-}
-
-fn section_mut<'a>(
-    doc: &'a mut KdlDocument,
-    parts: &[&str],
-    parent: &str,
-) -> Result<&'a mut KdlDocument, Error> {
-    if parts.is_empty() {
-        return Ok(doc);
-    }
-
-    let key = parts[0];
-    let i = node_index(doc, key, parent);
-    let mut used = 1;
-    let i = if is_records(key, parent) {
-        let index = parts
-            .get(1)
-            .and_then(|s| s.parse::<usize>().ok())
-            .ok_or_else(|| Error("Record index missing".into()))?;
-        used = 2;
-        doc.nodes()
-            .iter()
-            .enumerate()
-            .filter(|(_, n)| field(n.name().value(), parent) == key)
-            .nth(index)
-            .map(|(i, _)| i)
-            .ok_or_else(|| Error("This item no longer exists. Reload settings.".into()))?
-    } else {
-        i
-    };
-    let node = &mut doc.nodes_mut()[i];
-    let child = node.children_mut().get_or_insert_with(KdlDocument::new);
-
-    section_mut(child, &parts[used..], key)
-}
-
-/// Scalar settings in record nodes can be KDL properties rather than children.
-fn unset_property(doc: &mut KdlDocument, parts: &[&str], parent: &str) -> Result<bool, Error> {
-    if parts.len() < 2 {
-        return Ok(false);
-    }
-    let key = parts[0];
-    let record = is_records(key, parent);
-    let used = if record { 2 } else { 1 };
-    let index = if record {
-        parts
-            .get(1)
-            .and_then(|part| part.parse::<usize>().ok())
-            .ok_or_else(|| Error("Record index missing".into()))?
-    } else {
-        0
-    };
-    let Some(node) = doc
-        .nodes_mut()
-        .iter_mut()
-        .filter(|node| field(node.name().value(), parent) == key)
-        .nth(index)
-    else {
-        return Ok(false);
-    };
-    if parts.len() == used + 1
-        && let Some(index) = node.entries().iter().position(|entry| {
-            entry
-                .name()
-                .is_some_and(|name| field(name.value(), key) == parts[used])
-        })
-    {
-        let entry = node.entries_mut().remove(index);
-        if let Some(format) = entry.format() {
-            let comments = [&format.leading, &format.trailing]
-                .into_iter()
-                .filter(|part| part.contains("//") || part.contains("/*"))
-                .cloned()
-                .collect::<String>();
-            if !comments.is_empty() {
-                let mut format = node.format().cloned().unwrap_or_default();
-                format.leading.push_str(&comments);
-                node.set_format(format);
-            }
-        }
-        return Ok(true);
-    }
-    if let Some(children) = node.children_mut() {
-        unset_property(children, &parts[used..], key)
-    } else {
-        Ok(false)
-    }
-}
-
-fn set_in(doc: &mut KdlDocument, parts: &[&str], parent: &str, value: Value) -> Result<(), Error> {
-    if parts.is_empty() {
-        return Err(Error("Missing setting path".into()));
-    }
-
-    let key = parts[0];
-    if parts.len() == 1 && is_records(key, parent) {
-        let records = value
-            .as_array()
-            .ok_or_else(|| Error("Expected a list of records".into()))?;
-        let mut nodes = records
-            .iter()
-            .map(|value| value_node(key, value, parent))
-            .collect::<Result<Vec<_>, _>>()?;
-        let at = doc
-            .nodes()
-            .iter()
-            .position(|node| field(node.name().value(), parent) == key)
-            .unwrap_or(doc.nodes().len());
-        let mut comments = String::new();
-        for node in doc
-            .nodes()
-            .iter()
-            .filter(|node| field(node.name().value(), parent) == key)
-        {
-            collect_comments(node, &mut comments);
-        }
-        doc.nodes_mut()
-            .retain(|node| field(node.name().value(), parent) != key);
-        if let Some(first) = nodes.first_mut() {
-            first.set_format(kdl::KdlNodeFormat {
-                leading: comments,
-                ..Default::default()
-            });
-        } else if !comments.is_empty() {
-            let mut format = doc.format().cloned().unwrap_or_default();
-            format.trailing.push_str(&comments);
-            doc.set_format(format);
-        }
-        doc.nodes_mut().splice(at..at, nodes);
-        return Ok(());
-    }
-    let i = node_index(doc, key, parent);
-
-    if parts.len() == 1 {
-        let new = value_node(key, &value, parent)?;
-        let node = &mut doc.nodes_mut()[i];
-        if new.entries().len() == 1 && node.entries().len() == 1 && node.children().is_none() {
-            set_entry_value(&mut node.entries_mut()[0], new.entries()[0].value().clone());
-            node.entries_mut()[0].set_name(None::<String>);
-        } else {
-            *node.entries_mut() = new.entries().to_vec();
-            *node.children_mut() = new.children().cloned();
-        }
-
-        return Ok(());
-    }
-
-    if is_records(key, parent) {
-        let index = parts[1]
-            .parse::<usize>()
-            .map_err(|_| Error("Record index missing".into()))?;
-        let i = doc
-            .nodes()
-            .iter()
-            .enumerate()
-            .filter(|(_, n)| field(n.name().value(), parent) == key)
-            .nth(index)
-            .map(|(i, _)| i)
-            .ok_or_else(|| Error("This item no longer exists. Reload settings.".into()))?;
-        let node = &mut doc.nodes_mut()[i];
-        let rest = &parts[2..];
-
-        if rest.len() == 1 {
-            let positions: &[&str] = match key {
-                "bindings" => &["keys", "action", "argument"],
-                "binding_modes" => &["name"],
-                "outputs" => &["match"],
-                "output_profiles" => &["name"],
-                "panels" | "groups" | "items" => &["id"],
-                _ => &[],
-            };
-            let position = positions.iter().position(|p| *p == rest[0]);
-            let mut arg_index = 0;
-
-            for entry in node.entries_mut() {
-                let matches = if let Some(name) = entry.name() {
-                    field(name.value(), key) == rest[0]
-                } else {
-                    let matches = Some(arg_index) == position;
-                    arg_index += 1;
-                    matches
-                };
-
-                if matches {
-                    set_entry_value(entry, kdl_value(&value)?);
-                    return Ok(());
-                }
-            }
-
-            if key == "autostart"
-                && rest[0] == "command"
-                && node.children().is_none_or(|d| d.get("command").is_none())
-            {
-                node.entries_mut().retain(|e| e.name().is_some());
-                for value in value
-                    .as_array()
-                    .ok_or_else(|| Error("Command must be an array".into()))?
-                {
-                    node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
-                }
-                return Ok(());
-            }
-        }
-
-        return set_in(
-            node.children_mut().get_or_insert_with(KdlDocument::new),
-            rest,
-            key,
-            value,
-        );
-    }
-    let node = &mut doc.nodes_mut()[i];
-
-    if parts.len() == 2
-        && let Some(entry) = node
-            .entries_mut()
-            .iter_mut()
-            .find(|e| e.name().is_some_and(|n| field(n.value(), key) == parts[1]))
-    {
-        set_entry_value(entry, kdl_value(&value)?);
-        return Ok(());
-    }
-
-    set_in(
-        node.children_mut().get_or_insert_with(KdlDocument::new),
-        &parts[1..],
-        key,
-        value,
-    )
-}
-
-fn kdl_value(value: &Value) -> Result<KdlValue, Error> {
-    Ok(match value {
-        Value::String(s) => KdlValue::String(s.clone()),
-        Value::Bool(b) => KdlValue::Bool(*b),
-        Value::Number(n) => {
-            if let Some(i) = n.as_i64() {
-                KdlValue::Integer(i.into())
-            } else if let Some(i) = n.as_u64() {
-                KdlValue::Integer(i.into())
-            } else {
-                KdlValue::Float(n.as_f64().unwrap())
-            }
-        }
-        _ => return Err(Error("Expected a scalar value".into())),
-    })
-}
-
-fn node_name(key: &str, parent: &str) -> String {
-    if matches!(parent, "commands" | "custom_themes") {
-        return key.into();
-    }
-
-    if !is_records(key, parent) {
-        return key.replace('_', "-");
-    }
-
-    match key {
-        "bindings" => "binding".into(),
-        "binding_modes" => "binding-mode".into(),
-        "window_rules" => "window-rule".into(),
-        "output_profiles" => "output-profile".into(),
-        "outputs" => "output".into(),
-        "panels" => "panel".into(),
-        "groups" => "group".into(),
-        "items" => "item".into(),
-        _ => key.replace('_', "-"),
-    }
-}
-
-fn value_node(key: &str, value: &Value, parent: &str) -> Result<KdlNode, Error> {
-    let mut node = KdlNode::new(node_name(key, parent));
-
-    match value {
-        Value::Object(map) => {
-            let positions: &[&str] = match key {
-                "bindings" => &["keys", "action", "argument"],
-                "binding_modes" => &["name"],
-                "output_profiles" => &["name"],
-                "outputs" => &["match"],
-                "panels" | "groups" | "items" => &["id"],
-                _ => &[],
-            };
-            let mut child = KdlDocument::new();
-            let mut consumed = Vec::new();
-
-            for name in positions {
-                if let Some(value) = map.get(*name) {
-                    node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
-                    consumed.push(*name);
-                } else {
-                    break;
-                }
-            }
-
-            for (name, value) in map {
-                if consumed.contains(&name.as_str()) {
-                    continue;
-                }
-                if key == "autostart" && name == "command" {
-                    for value in value
-                        .as_array()
-                        .ok_or_else(|| Error("Command must be an array".into()))?
-                    {
-                        node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
-                    }
-                } else if is_records(key, parent)
-                    && map.len() <= 4
-                    && !value.is_array()
-                    && !value.is_object()
-                {
-                    node.entries_mut().push(KdlEntry::new_prop(
-                        name.replace('_', "-"),
-                        kdl_value(value)?,
-                    ));
-                } else {
-                    append(&mut child, name, value, key)?;
-                }
-            }
-
-            if !child.nodes().is_empty() || node.entries().is_empty() {
-                node.set_children(child);
-            }
-        }
-        Value::Array(array) => {
-            for value in array {
-                node.entries_mut().push(KdlEntry::new(kdl_value(value)?));
-            }
-        }
-        _ => node.entries_mut().push(KdlEntry::new(kdl_value(value)?)),
-    }
-    Ok(node)
-}
-
-fn append(doc: &mut KdlDocument, key: &str, value: &Value, parent: &str) -> Result<(), Error> {
-    if is_records(key, parent) {
-        for record in value
-            .as_array()
-            .ok_or_else(|| Error("Expected records".into()))?
-        {
-            doc.nodes_mut().push(value_node(key, record, parent)?);
-        }
-    } else {
-        doc.nodes_mut().push(value_node(key, value, parent)?);
-    }
-    Ok(())
-}
-
-pub fn from_str<T: DeserializeOwned>(source: &str) -> Result<T, Error> {
-    serde_json::from_value(Document::parse(source)?.value).map_err(|e| Error(e.to_string()))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn named_binding_modes_round_trip_and_keep_nested_bindings_editable() {
-        let mut document = super::Document::parse(
-            "binding-mode resize { binding h resize left; binding l resize right; }\nbinding-mode launch { binding t spawn terminal; }\n",
-        ).unwrap();
-        assert_eq!(document.get("binding_modes.0.name").unwrap(), "resize");
-        assert_eq!(
-            document.get("binding_modes.1.bindings.0.argument").unwrap(),
-            "terminal"
-        );
-        document
-            .set("binding_modes.0.bindings.0.argument", "up".into())
-            .unwrap();
-        let reparsed = super::Document::parse(&document.to_string()).unwrap();
-        assert_eq!(
-            reparsed.get("binding_modes.0.bindings.0.argument").unwrap(),
-            "up"
-        );
-        assert_eq!(
-            reparsed.get("binding_modes.0.bindings.1.argument").unwrap(),
-            "right"
-        );
-    }
-    #[test]
-    fn adopting_appearance_modes_preserves_legacy_colors_and_comments() {
-        let mut document = Document::parse(
-            "// my desktop\ntheme {\n    colors {\n        accent \"#123456\" // my accent\n    }\n}\n",
-        )
-        .unwrap();
-        document
-            .set("theme.mode", serde_json::json!("light"))
-            .unwrap();
-        assert_eq!(
-            document.get("theme.dark.colors.accent"),
-            Some(&serde_json::json!("#123456"))
-        );
-        assert!(document.get("theme.colors").is_none());
-        assert!(document.to_string().contains("// my accent"));
-        document.unset("theme.dark.colors").unwrap();
-        assert!(document.to_string().contains("// my accent"));
-        assert!(document.to_string().contains("// my desktop"));
-        Document::parse(&document.to_string()).unwrap();
-    }
-
-    #[test]
-    fn clearing_optional_theme_references_removes_them_without_empty_paths() {
-        let mut document = Document::parse("theme { file \"custom_theme.kdl\"; } ").unwrap();
-        document.set("theme.file", serde_json::json!("")).unwrap();
-        assert!(document.get("theme.file").is_none());
-        document.set("theme.file", serde_json::json!("")).unwrap();
-    }
-
-    #[test]
-    fn inline_comments_and_failed_edits_leave_document_intact() {
-        let mut doc =
-            Document::parse("// header\nanimations {\n    speed 0.75 // keep inline\n}\n").unwrap();
-        doc.set("animations.speed", 0.8.into()).unwrap();
-        assert!(doc.to_string().contains("// keep inline"));
-        assert_eq!(
-            Document::parse(&doc.to_string())
-                .unwrap()
-                .get("animations.speed")
-                .unwrap(),
-            0.8
-        );
-        let previous = doc.to_string();
-        assert!(doc.set("bindings.4.keys", "X".into()).is_err());
-        assert_eq!(doc.to_string(), previous);
-    }
-
-    #[test]
-    fn editing_autostart_commands_handles_both_representations() {
-        for source in [
-            "autostart \"old\" enabled=#true\n",
-            "autostart { command \"old\"; enabled #true; }\n",
-        ] {
-            let mut doc = Document::parse(source).unwrap();
-            doc.set("autostart.0.command", serde_json::json!(["new", "arg"]))
-                .unwrap();
-            let reparsed = Document::parse(&doc.to_string()).unwrap();
-            assert_eq!(
-                reparsed.get("autostart.0.command").unwrap(),
-                &serde_json::json!(["new", "arg"])
-            );
-        }
-    }
-
-    #[test]
-    fn compact_syntax_and_nested_arrays_roundtrip() {
-        let source = r#"input repeat-rate=30 { xkb-options "compose:ralt"; }
-binding "Swipe3Up" "toggle-overview"
-output-profile "desk" { output "HDMI-A-1" scale=1.5 { position 0 0; }; }
-autostart "program" "two words" enabled=#false
-"#;
-        let mut doc = Document::parse(source).unwrap();
-        assert_eq!(doc.get("bindings.0.action").unwrap(), "toggle-overview");
-        doc.set("bindings.0.action", "none".into()).unwrap();
-        doc.set("input.repeat_rate", 25.into()).unwrap();
-        doc.set("output_profiles.0.outputs.0.scale", 2.0.into())
-            .unwrap();
-        let reparsed = Document::parse(&doc.to_string()).unwrap();
-        assert_eq!(reparsed.get("bindings.0.action").unwrap(), "none");
-        assert_eq!(reparsed.get("input.repeat_rate").unwrap(), 25);
-        assert_eq!(
-            reparsed.get("output_profiles.0.outputs.0.scale").unwrap(),
-            2.0
-        );
-    }
-
-    #[test]
-    fn output_arrays_and_command_names_survive_edits() {
-        let mut doc = Document::parse(
-            "output-profile desk { output match=\"DP-1\" { position 0 0; }; }\ncommands { lock-screen \"locker\"; }\n",
-        )
-        .unwrap();
-        doc.set(
-            "output_profiles.0.outputs.0.position",
-            serde_json::json!([100, 200]),
-        )
-        .unwrap();
-        doc.set(
-            "commands.lock-screen",
-            serde_json::json!(["ferese-lock", "--lock"]),
-        )
-        .unwrap();
-        let reparsed = Document::parse(&doc.to_string()).unwrap();
-        assert_eq!(
-            reparsed
-                .get("output_profiles.0.outputs.0.position")
-                .unwrap(),
-            &serde_json::json!([100, 200])
-        );
-        assert_eq!(
-            reparsed.get("commands.lock-screen").unwrap(),
-            &serde_json::json!(["ferese-lock", "--lock"])
-        );
-    }
-
-    #[test]
-    fn edits_preserve_comments_and_multiline_authored_metadata() {
-        let mut doc = Document::parse("// keep this\ncustom { text \"old\"; }\n").unwrap();
-        doc.set("custom.text", "one\ntwo".into()).unwrap();
-        assert!(doc.to_string().contains("// keep this"));
-        let reparsed = Document::parse(&doc.to_string()).unwrap();
-        assert_eq!(reparsed.get("custom.text").unwrap(), "one\ntwo");
-    }
-
-    #[test]
-    fn removed_desktop_widgets_are_ignored_without_affecting_authored_metadata() {
-        for section in ["desktop-widgets", "desktop_widgets"] {
-            let source = format!("{section} {{ clock {{ enabled #true; }}; }}");
-            let doc = Document::parse(&source).unwrap();
-            assert!(doc.get("desktop_widgets").is_none());
-            assert_eq!(doc.to_string(), source);
-            assert_eq!(
-                crate::from_str::<serde_json::Value>(&source).unwrap(),
-                serde_json::json!({})
-            );
-        }
-        assert!(
-            Document::parse("panel main { metadata { desktop-widgets \"custom\"; }; }").is_ok()
-        );
-    }
-
-    #[test]
-    fn rejects_duplicate_fields_ambiguous_syntax_and_nonfinite_values() {
-        for source in [
-            "input { repeat-rate 25; repeat_rate 30; }",
-            "binding \"X\" keys=\"Y\"",
-            "input 1 { repeat-rate 25; }",
-            "layout { inner-gap #inf; }",
-            "layout { inner-gap #null; }",
-        ] {
-            assert!(Document::parse(source).is_err(), "{source}");
-        }
-    }
-}
diff --git a/crates/ferese-ipc/src/frame.rs b/crates/ferese-ipc/src/frame.rs
new file mode 100644
index 0000000..8b0e94f
--- /dev/null
+++ b/crates/ferese-ipc/src/frame.rs
@@ -0,0 +1,206 @@
+use std::error::Error;
+use std::io::{Read, Write};
+use std::{fmt, io};
+
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+pub const VERSION: u32 = 1;
+pub const MAX_PAYLOAD_SIZE: usize = 1024 * 1024;
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct Request {
+    pub version: u32,
+    pub id: u64,
+    #[serde(rename = "type")]
+    pub kind: String,
+    pub command: String,
+    #[serde(default)]
+    pub args: Value,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct Response {
+    pub version: u32,
+    pub id: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub result: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<ResponseError>,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct ResponseError {
+    pub code: String,
+    pub message: String,
+}
+
+impl Response {
+    pub fn success(id: u64, result: Value) -> Self {
+        Self {
+            version: VERSION,
+            id,
+            result: Some(result),
+            error: None,
+        }
+    }
+
+    pub fn error(id: u64, code: impl Into<String>, message: impl Into<String>) -> Self {
+        Self {
+            version: VERSION,
+            id,
+            result: None,
+            error: Some(ResponseError {
+                code: code.into(),
+                message: message.into(),
+            }),
+        }
+    }
+}
+
+#[derive(Debug)]
+pub enum FrameError {
+    Io(io::Error),
+    Oversized(usize),
+    InvalidJson(serde_json::Error),
+}
+
+impl fmt::Display for FrameError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Io(error) => error.fmt(formatter),
+            Self::Oversized(size) => write!(
+                formatter,
+                "IPC payload is {size} bytes; maximum is {MAX_PAYLOAD_SIZE}"
+            ),
+            Self::InvalidJson(error) => write!(formatter, "invalid IPC JSON: {error}"),
+        }
+    }
+}
+
+impl Error for FrameError {
+    fn source(&self) -> Option<&(dyn Error + 'static)> {
+        match self {
+            Self::Io(error) => Some(error),
+            Self::InvalidJson(error) => Some(error),
+            Self::Oversized(_) => None,
+        }
+    }
+}
+
+impl From<io::Error> for FrameError {
+    fn from(error: io::Error) -> Self {
+        Self::Io(error)
+    }
+}
+
+pub fn read_frame<T: for<'de> Deserialize<'de>>(reader: &mut impl Read) -> Result<T, FrameError> {
+    let mut header = [0_u8; 4];
+    reader.read_exact(&mut header)?;
+    let size = u32::from_be_bytes(header) as usize;
+    if size > MAX_PAYLOAD_SIZE {
+        return Err(FrameError::Oversized(size));
+    }
+
+    let mut payload = vec![0; size];
+    reader.read_exact(&mut payload)?;
+    serde_json::from_slice(&payload).map_err(FrameError::InvalidJson)
+}
+
+pub fn write_frame<T: Serialize>(writer: &mut impl Write, value: &T) -> Result<(), FrameError> {
+    let payload = serde_json::to_vec(value).map_err(FrameError::InvalidJson)?;
+    if payload.len() > MAX_PAYLOAD_SIZE {
+        return Err(FrameError::Oversized(payload.len()));
+    }
+
+    writer.write_all(&(payload.len() as u32).to_be_bytes())?;
+    writer.write_all(&payload)?;
+    writer.flush()?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::io::Cursor;
+
+    use super::*;
+
+    struct ChunkedReader<R> {
+        inner: R,
+        chunk_size: usize,
+    }
+
+    impl<R: Read> Read for ChunkedReader<R> {
+        fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
+            let limit = buffer.len().min(self.chunk_size);
+            self.inner.read(&mut buffer[..limit])
+        }
+    }
+
+    fn request(id: u64, command: &str) -> Request {
+        Request {
+            version: VERSION,
+            id,
+            kind: "command".to_owned(),
+            command: command.to_owned(),
+            args: serde_json::json!({}),
+        }
+    }
+
+    #[test]
+    fn framed_json_round_trips() {
+        let mut request = request(42, "focus");
+        request.args = serde_json::json!({ "direction": "left" });
+        let mut bytes = Vec::new();
+        write_frame(&mut bytes, &request).unwrap();
+        let decoded: Request = read_frame(&mut bytes.as_slice()).unwrap();
+
+        assert_eq!(decoded.version, VERSION);
+        assert_eq!(decoded.id, 42);
+        assert_eq!(decoded.command, "focus");
+        assert_eq!(decoded.args["direction"], "left");
+    }
+
+    #[test]
+    fn reads_fragmented_frames_and_preserves_frame_boundaries() {
+        let mut bytes = Vec::new();
+        write_frame(&mut bytes, &request(1, "get-workspaces")).unwrap();
+        write_frame(&mut bytes, &request(2, "get-outputs")).unwrap();
+        let mut reader = ChunkedReader {
+            inner: Cursor::new(bytes),
+            chunk_size: 3,
+        };
+
+        let first: Request = read_frame(&mut reader).unwrap();
+        let second: Request = read_frame(&mut reader).unwrap();
+
+        assert_eq!((first.id, first.command.as_str()), (1, "get-workspaces"));
+        assert_eq!((second.id, second.command.as_str()), (2, "get-outputs"));
+    }
+
+    #[test]
+    fn rejects_invalid_and_truncated_payloads_without_panicking() {
+        let invalid = b"not-json";
+        let mut invalid_frame = Vec::from((invalid.len() as u32).to_be_bytes());
+        invalid_frame.extend_from_slice(invalid);
+        assert!(matches!(
+            read_frame::<Request>(&mut invalid_frame.as_slice()),
+            Err(FrameError::InvalidJson(_))
+        ));
+
+        let mut truncated = Vec::from(32_u32.to_be_bytes());
+        truncated.extend_from_slice(b"short");
+        assert!(matches!(
+            read_frame::<Request>(&mut truncated.as_slice()),
+            Err(FrameError::Io(error)) if error.kind() == io::ErrorKind::UnexpectedEof
+        ));
+    }
+
+    #[test]
+    fn rejects_oversized_frames_before_allocating_payload() {
+        let size = (MAX_PAYLOAD_SIZE as u32 + 1).to_be_bytes();
+        let error = read_frame::<Request>(&mut size.as_slice()).unwrap_err();
+
+        assert!(matches!(error, FrameError::Oversized(_)));
+    }
+}
diff --git a/crates/ferese-ipc/src/lib.rs b/crates/ferese-ipc/src/lib.rs
index ca58ef3..47aa7ba 100644
--- a/crates/ferese-ipc/src/lib.rs
+++ b/crates/ferese-ipc/src/lib.rs
@@ -1,216 +1,13 @@
+//! Framed IPC messages and the services exposed over compositor connections.
 pub mod activities;
 mod connection;
-pub use connection::{Cancellation, Connection, socket_path};
-use std::error::Error;
-use std::io::{Read, Write};
-use std::{fmt, io};
-
-use serde::{Deserialize, Serialize};
-use serde_json::Value;
-
 pub mod events;
+mod frame;
 pub mod media;
 pub mod night_light;
 pub mod socket;
 pub mod theme;
 pub mod xwayland;
 
-pub const VERSION: u32 = 1;
-pub const MAX_PAYLOAD_SIZE: usize = 1024 * 1024;
-
-#[derive(Clone, Debug, Deserialize, Serialize)]
-pub struct Request {
-    pub version: u32,
-    pub id: u64,
-    #[serde(rename = "type")]
-    pub kind: String,
-    pub command: String,
-    #[serde(default)]
-    pub args: Value,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize)]
-pub struct Response {
-    pub version: u32,
-    pub id: u64,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub result: Option<Value>,
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub error: Option<ResponseError>,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize)]
-pub struct ResponseError {
-    pub code: String,
-    pub message: String,
-}
-
-impl Response {
-    pub fn success(id: u64, result: Value) -> Self {
-        Self {
-            version: VERSION,
-            id,
-            result: Some(result),
-            error: None,
-        }
-    }
-
-    pub fn error(id: u64, code: impl Into<String>, message: impl Into<String>) -> Self {
-        Self {
-            version: VERSION,
-            id,
-            result: None,
-            error: Some(ResponseError {
-                code: code.into(),
-                message: message.into(),
-            }),
-        }
-    }
-}
-
-#[derive(Debug)]
-pub enum FrameError {
-    Io(io::Error),
-    Oversized(usize),
-    InvalidJson(serde_json::Error),
-}
-
-impl fmt::Display for FrameError {
-    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            Self::Io(error) => error.fmt(formatter),
-            Self::Oversized(size) => write!(
-                formatter,
-                "IPC payload is {size} bytes; maximum is {MAX_PAYLOAD_SIZE}"
-            ),
-            Self::InvalidJson(error) => write!(formatter, "invalid IPC JSON: {error}"),
-        }
-    }
-}
-
-impl Error for FrameError {
-    fn source(&self) -> Option<&(dyn Error + 'static)> {
-        match self {
-            Self::Io(error) => Some(error),
-            Self::InvalidJson(error) => Some(error),
-            Self::Oversized(_) => None,
-        }
-    }
-}
-
-impl From<io::Error> for FrameError {
-    fn from(error: io::Error) -> Self {
-        Self::Io(error)
-    }
-}
-
-pub fn read_frame<T: for<'de> Deserialize<'de>>(reader: &mut impl Read) -> Result<T, FrameError> {
-    let mut header = [0_u8; 4];
-    reader.read_exact(&mut header)?;
-    let size = u32::from_be_bytes(header) as usize;
-    if size > MAX_PAYLOAD_SIZE {
-        return Err(FrameError::Oversized(size));
-    }
-
-    let mut payload = vec![0; size];
-    reader.read_exact(&mut payload)?;
-    serde_json::from_slice(&payload).map_err(FrameError::InvalidJson)
-}
-
-pub fn write_frame<T: Serialize>(writer: &mut impl Write, value: &T) -> Result<(), FrameError> {
-    let payload = serde_json::to_vec(value).map_err(FrameError::InvalidJson)?;
-    if payload.len() > MAX_PAYLOAD_SIZE {
-        return Err(FrameError::Oversized(payload.len()));
-    }
-
-    writer.write_all(&(payload.len() as u32).to_be_bytes())?;
-    writer.write_all(&payload)?;
-    writer.flush()?;
-    Ok(())
-}
-
-#[cfg(test)]
-mod tests {
-    use std::io::Cursor;
-
-    use super::*;
-
-    struct ChunkedReader<R> {
-        inner: R,
-        chunk_size: usize,
-    }
-
-    impl<R: Read> Read for ChunkedReader<R> {
-        fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
-            let limit = buffer.len().min(self.chunk_size);
-            self.inner.read(&mut buffer[..limit])
-        }
-    }
-
-    fn request(id: u64, command: &str) -> Request {
-        Request {
-            version: VERSION,
-            id,
-            kind: "command".to_owned(),
-            command: command.to_owned(),
-            args: serde_json::json!({}),
-        }
-    }
-
-    #[test]
-    fn framed_json_round_trips() {
-        let mut request = request(42, "focus");
-        request.args = serde_json::json!({ "direction": "left" });
-        let mut bytes = Vec::new();
-        write_frame(&mut bytes, &request).unwrap();
-        let decoded: Request = read_frame(&mut bytes.as_slice()).unwrap();
-
-        assert_eq!(decoded.version, VERSION);
-        assert_eq!(decoded.id, 42);
-        assert_eq!(decoded.command, "focus");
-        assert_eq!(decoded.args["direction"], "left");
-    }
-
-    #[test]
-    fn reads_fragmented_frames_and_preserves_frame_boundaries() {
-        let mut bytes = Vec::new();
-        write_frame(&mut bytes, &request(1, "get-workspaces")).unwrap();
-        write_frame(&mut bytes, &request(2, "get-outputs")).unwrap();
-        let mut reader = ChunkedReader {
-            inner: Cursor::new(bytes),
-            chunk_size: 3,
-        };
-
-        let first: Request = read_frame(&mut reader).unwrap();
-        let second: Request = read_frame(&mut reader).unwrap();
-
-        assert_eq!((first.id, first.command.as_str()), (1, "get-workspaces"));
-        assert_eq!((second.id, second.command.as_str()), (2, "get-outputs"));
-    }
-
-    #[test]
-    fn rejects_invalid_and_truncated_payloads_without_panicking() {
-        let invalid = b"not-json";
-        let mut invalid_frame = Vec::from((invalid.len() as u32).to_be_bytes());
-        invalid_frame.extend_from_slice(invalid);
-        assert!(matches!(
-            read_frame::<Request>(&mut invalid_frame.as_slice()),
-            Err(FrameError::InvalidJson(_))
-        ));
-
-        let mut truncated = Vec::from(32_u32.to_be_bytes());
-        truncated.extend_from_slice(b"short");
-        assert!(matches!(
-            read_frame::<Request>(&mut truncated.as_slice()),
-            Err(FrameError::Io(error)) if error.kind() == io::ErrorKind::UnexpectedEof
-        ));
-    }
-
-    #[test]
-    fn rejects_oversized_frames_before_allocating_payload() {
-        let size = (MAX_PAYLOAD_SIZE as u32 + 1).to_be_bytes();
-        let error = read_frame::<Request>(&mut size.as_slice()).unwrap_err();
-
-        assert!(matches!(error, FrameError::Oversized(_)));
-    }
-}
+pub use connection::{Cancellation, Connection, socket_path};
+pub use frame::*;
diff --git a/crates/ferese-layout/src/layout_tree.rs b/crates/ferese-layout/src/layout_tree.rs
new file mode 100644
index 0000000..fcf9b6c
--- /dev/null
+++ b/crates/ferese-layout/src/layout_tree.rs
@@ -0,0 +1,1929 @@
+use std::collections::{HashMap, HashSet};
+use std::error::Error;
+use std::fmt;
+
+pub const TAB_BAR_HEIGHT: f64 = 24.0;
+
+const MIN_SPLIT_RATIO: f64 = 0.05;
+const MAX_SPLIT_RATIO: f64 = 0.95;
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct WindowId(pub u64);
+
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
+pub struct NodeId(u64);
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct TabGroup {
+    pub windows: Vec<WindowId>,
+    pub active: WindowId,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct TabBar {
+    pub group: TabGroup,
+    pub rect: Rect,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Axis {
+    Horizontal,
+    Vertical,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Direction {
+    Left,
+    Right,
+    Up,
+    Down,
+}
+
+#[derive(Clone, Debug, PartialEq)]
+pub enum Node {
+    Window(WindowId),
+    Split {
+        axis: Axis,
+        ratio: f64,
+        first: NodeId,
+        second: NodeId,
+    },
+    Stack {
+        children: Vec<NodeId>,
+        active: usize,
+    },
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq)]
+pub struct Rect {
+    pub x: f64,
+    pub y: f64,
+    pub width: f64,
+    pub height: f64,
+}
+
+impl Rect {
+    pub const fn new(x: f64, y: f64, width: f64, height: f64) -> Self {
+        Self {
+            x,
+            y,
+            width,
+            height,
+        }
+    }
+
+    fn center(self) -> (f64, f64) {
+        (self.x + self.width / 2.0, self.y + self.height / 2.0)
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct GapConfig {
+    pub inner: f64,
+    pub outer: f64,
+    pub smart: bool,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct SizeConstraints {
+    pub min_width: f64,
+    pub min_height: f64,
+    pub max_width: Option<f64>,
+    pub max_height: Option<f64>,
+}
+
+impl Default for SizeConstraints {
+    fn default() -> Self {
+        Self {
+            min_width: 1.0,
+            min_height: 1.0,
+            max_width: None,
+            max_height: None,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ConstraintKind {
+    MinimumWidth,
+    MinimumHeight,
+    MaximumWidth,
+    MaximumHeight,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct ConstraintWarning {
+    pub window: WindowId,
+    pub kind: ConstraintKind,
+    pub requested: f64,
+    pub assigned: f64,
+}
+
+#[derive(Debug, Default, PartialEq)]
+pub struct LayoutResult {
+    pub geometry: HashMap<WindowId, Rect>,
+    pub warnings: Vec<ConstraintWarning>,
+    pub tab_bars: Vec<TabBar>,
+}
+
+impl Default for GapConfig {
+    fn default() -> Self {
+        Self {
+            inner: 10.0,
+            outer: 4.0,
+            smart: false,
+        }
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum LayoutError {
+    DuplicateWindow(WindowId),
+    UnknownWindow(WindowId),
+    InvalidTree(&'static str),
+}
+
+impl fmt::Display for LayoutError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::DuplicateWindow(window) => write!(formatter, "duplicate window {window:?}"),
+            Self::UnknownWindow(window) => write!(formatter, "unknown window {window:?}"),
+            Self::InvalidTree(reason) => write!(formatter, "invalid layout tree: {reason}"),
+        }
+    }
+}
+
+impl Error for LayoutError {}
+
+#[derive(Clone, Debug, Default, PartialEq)]
+pub struct LayoutTree {
+    root: Option<NodeId>,
+    nodes: HashMap<NodeId, Node>,
+    parents: HashMap<NodeId, NodeId>,
+    windows: HashMap<WindowId, NodeId>,
+    next_node: u64,
+}
+
+impl LayoutTree {
+    pub fn root(&self) -> Option<NodeId> {
+        self.root
+    }
+
+    pub fn node(&self, id: NodeId) -> Option<&Node> {
+        self.nodes.get(&id)
+    }
+
+    pub fn contains(&self, window: WindowId) -> bool {
+        self.windows.contains_key(&window)
+    }
+
+    pub fn window_ids(&self) -> impl Iterator<Item = WindowId> + '_ {
+        self.windows.keys().copied()
+    }
+
+    pub fn visible_window_count(&self) -> usize {
+        fn count(tree: &LayoutTree, node: NodeId) -> usize {
+            match tree.nodes.get(&node) {
+                Some(Node::Window(_)) => 1,
+                Some(Node::Split { first, second, .. }) => {
+                    count(tree, *first) + count(tree, *second)
+                }
+                Some(Node::Stack { children, active }) => {
+                    children.get(*active).map_or(0, |child| count(tree, *child))
+                }
+                None => 0,
+            }
+        }
+        self.root.map_or(0, |root| count(self, root))
+    }
+
+    pub fn preferred_window(&self) -> Option<WindowId> {
+        let leaf = self.first_window(self.root?).ok()?;
+        match self.nodes.get(&leaf)? {
+            Node::Window(window) => Some(*window),
+            _ => None,
+        }
+    }
+
+    /// Include every structural leaf, even inactive stack members. Preserve
+    /// stack child order when their positions coincide.
+    pub fn window_ids_in_reading_order(&self, bounds: Rect) -> Result<Vec<WindowId>, LayoutError> {
+        self.validate()?;
+        let mut windows = Vec::with_capacity(self.windows.len());
+        if let Some(root) = self.root {
+            self.collect_window_positions(root, bounds, &mut windows)?;
+        }
+        windows.sort_by(|(_, left), (_, right)| {
+            left.x
+                .total_cmp(&right.x)
+                .then_with(|| left.y.total_cmp(&right.y))
+        });
+        Ok(windows.into_iter().map(|(window, _)| window).collect())
+    }
+
+    pub fn insert(
+        &mut self,
+        window: WindowId,
+        focused: Option<WindowId>,
+        axis: Axis,
+        ratio: f64,
+    ) -> Result<NodeId, LayoutError> {
+        if self.contains(window) {
+            return Err(LayoutError::DuplicateWindow(window));
+        }
+
+        let Some(root) = self.root else {
+            let window_node = self.insert_node(Node::Window(window));
+            self.windows.insert(window, window_node);
+            self.root = Some(window_node);
+            return Ok(window_node);
+        };
+
+        let target = match focused {
+            Some(focused) => self
+                .windows
+                .get(&focused)
+                .copied()
+                .ok_or(LayoutError::UnknownWindow(focused))?,
+            None => self.first_window(root)?,
+        };
+        // A new split belongs beside the whole tab group, not inside one tab.
+        let target = self.tab_parent(target).unwrap_or(target);
+        let old_parent = self.parents.get(&target).copied();
+        let window_node = self.insert_node(Node::Window(window));
+        self.windows.insert(window, window_node);
+        let split = self.insert_node(Node::Split {
+            axis,
+            ratio: normalized_ratio(ratio),
+            first: target,
+            second: window_node,
+        });
+
+        self.parents.insert(target, split);
+        self.parents.insert(window_node, split);
+
+        if let Some(parent) = old_parent {
+            self.replace_child(parent, target, split)?;
+            self.parents.insert(split, parent);
+        } else {
+            self.root = Some(split);
+        }
+
+        debug_assert!(self.validate().is_ok());
+        Ok(window_node)
+    }
+
+    pub fn remove(&mut self, window: WindowId) -> Result<(), LayoutError> {
+        let leaf = self
+            .windows
+            .get(&window)
+            .copied()
+            .ok_or(LayoutError::UnknownWindow(window))?;
+        let Some(parent) = self.parents.get(&leaf).copied() else {
+            self.windows.remove(&window);
+            self.nodes.remove(&leaf);
+            self.root = None;
+            return Ok(());
+        };
+
+        match self.nodes.get(&parent).cloned() {
+            Some(Node::Split { first, second, .. }) => {
+                let sibling = if first == leaf {
+                    second
+                } else if second == leaf {
+                    first
+                } else {
+                    return Err(LayoutError::InvalidTree("split does not contain window"));
+                };
+
+                self.collapse_parent(parent, leaf, sibling)?;
+            }
+            Some(Node::Stack {
+                mut children,
+                mut active,
+            }) => {
+                let position = children
+                    .iter()
+                    .position(|child| *child == leaf)
+                    .ok_or(LayoutError::InvalidTree("stack does not contain window"))?;
+
+                if children.len() == 2 {
+                    let sibling = children[1 - position];
+                    self.collapse_parent(parent, leaf, sibling)?;
+                } else {
+                    children.remove(position);
+                    if position < active {
+                        active -= 1;
+                    } else if position == active {
+                        active = active.min(children.len() - 1);
+                    }
+
+                    self.windows.remove(&window);
+                    self.parents.remove(&leaf);
+                    self.nodes.remove(&leaf);
+                    self.nodes.insert(parent, Node::Stack { children, active });
+                }
+            }
+            Some(Node::Window(_)) => {
+                return Err(LayoutError::InvalidTree("window parent is a window"));
+            }
+            None => return Err(LayoutError::InvalidTree("window parent is missing")),
+        }
+
+        debug_assert!(self.validate().is_ok());
+        Ok(())
+    }
+
+    pub fn stack_window(&mut self, window: WindowId, target: WindowId) -> Result<(), LayoutError> {
+        if window == target {
+            return Ok(());
+        }
+        if !self.contains(target) {
+            return Err(LayoutError::UnknownWindow(target));
+        }
+        if !self.contains(window) {
+            return Err(LayoutError::UnknownWindow(window));
+        }
+
+        if self
+            .tab_group(window)
+            .is_some_and(|group| group.windows.contains(&target))
+        {
+            return self.activate_window(window);
+        }
+
+        self.remove(window)?;
+
+        let target_node = self
+            .windows
+            .get(&target)
+            .copied()
+            .ok_or(LayoutError::UnknownWindow(target))?;
+        let old_parent = self.parents.get(&target_node).copied();
+        let window_node = self.insert_node(Node::Window(window));
+        if let Some(parent) = self.tab_parent(target_node) {
+            let Some(Node::Stack { children, active }) = self.nodes.get_mut(&parent) else {
+                unreachable!()
+            };
+            children.push(window_node);
+            *active = children.len() - 1;
+            self.windows.insert(window, window_node);
+            self.parents.insert(window_node, parent);
+            debug_assert!(self.validate().is_ok());
+            return Ok(());
+        }
+        let stack = self.insert_node(Node::Stack {
+            children: vec![target_node, window_node],
+            active: 1,
+        });
+
+        self.windows.insert(window, window_node);
+        self.parents.insert(target_node, stack);
+        self.parents.insert(window_node, stack);
+
+        if let Some(parent) = old_parent {
+            self.replace_child(parent, target_node, stack)?;
+            self.parents.insert(stack, parent);
+        } else {
+            self.root = Some(stack);
+        }
+
+        debug_assert!(self.validate().is_ok());
+        Ok(())
+    }
+
+    fn tab_parent(&self, leaf: NodeId) -> Option<NodeId> {
+        let parent = *self.parents.get(&leaf)?;
+        match self.nodes.get(&parent)? {
+            Node::Stack { children, .. }
+                if children
+                    .iter()
+                    .all(|id| matches!(self.nodes.get(id), Some(Node::Window(_)))) =>
+            {
+                Some(parent)
+            }
+            _ => None,
+        }
+    }
+
+    fn group_at(&self, node: NodeId) -> Option<TabGroup> {
+        let Node::Stack { children, active } = self.nodes.get(&node)? else {
+            return None;
+        };
+        let windows: Option<Vec<_>> = children
+            .iter()
+            .map(|id| match self.nodes.get(id) {
+                Some(Node::Window(window)) => Some(*window),
+                _ => None,
+            })
+            .collect();
+        let windows = windows?;
+        Some(TabGroup {
+            active: *windows.get(*active)?,
+            windows,
+        })
+    }
+
+    pub fn tab_group(&self, window: WindowId) -> Option<TabGroup> {
+        self.group_at(*self.parents.get(self.windows.get(&window)?)?)
+    }
+
+    pub fn tab_groups(&self) -> Vec<TabGroup> {
+        let mut groups: Vec<_> = self
+            .nodes
+            .keys()
+            .filter_map(|id| self.group_at(*id))
+            .collect();
+        groups.sort_by_key(|group| group.windows[0].0);
+        groups
+    }
+
+    pub fn adjacent_tab(&self, window: WindowId, previous: bool) -> Option<WindowId> {
+        let group = self.tab_group(window)?;
+        let index = group.windows.iter().position(|id| *id == window)?;
+        let step = if previous { group.windows.len() - 1 } else { 1 };
+        Some(group.windows[(index + step) % group.windows.len()])
+    }
+
+    /// Leave the group in place and split the departing window to its right.
+    pub fn leave_tab_group(&mut self, window: WindowId) -> Result<bool, LayoutError> {
+        if !self.contains(window) {
+            return Err(LayoutError::UnknownWindow(window));
+        }
+        let Some(group) = self.tab_group(window) else {
+            return Ok(false);
+        };
+        let target = group
+            .windows
+            .into_iter()
+            .find(|id| *id != window)
+            .expect("group has at least two tabs");
+        self.remove(window)?;
+        self.insert(window, Some(target), Axis::Horizontal, 0.5)?;
+        Ok(true)
+    }
+
+    pub fn activate_window(&mut self, window: WindowId) -> Result<(), LayoutError> {
+        let mut child = self
+            .windows
+            .get(&window)
+            .copied()
+            .ok_or(LayoutError::UnknownWindow(window))?;
+
+        while let Some(parent) = self.parents.get(&child).copied() {
+            if let Some(Node::Stack { children, active }) = self.nodes.get_mut(&parent) {
+                *active = children
+                    .iter()
+                    .position(|candidate| *candidate == child)
+                    .ok_or(LayoutError::InvalidTree("stack does not contain child"))?;
+            }
+
+            child = parent;
+        }
+
+        debug_assert!(self.validate().is_ok());
+        Ok(())
+    }
+
+    pub fn geometry(&self, bounds: Rect) -> Result<HashMap<WindowId, Rect>, LayoutError> {
+        let mut geometry = HashMap::new();
+
+        if let Some(root) = self.root {
+            self.layout_node(root, bounds, &mut geometry)?;
+        }
+
+        Ok(geometry)
+    }
+
+    pub fn geometry_with_gaps(
+        &self,
+        bounds: Rect,
+        gaps: GapConfig,
+    ) -> Result<HashMap<WindowId, Rect>, LayoutError> {
+        let mut geometry = self.geometry(bounds)?;
+        apply_gaps(&mut geometry, bounds, gaps);
+
+        Ok(geometry)
+    }
+
+    pub fn geometry_with_constraints(
+        &self,
+        bounds: Rect,
+        gaps: GapConfig,
+        constraints: &HashMap<WindowId, SizeConstraints>,
+        focused: Option<WindowId>,
+    ) -> Result<LayoutResult, LayoutError> {
+        let mut result = LayoutResult::default();
+
+        if let Some(root) = self.root {
+            self.layout_node_constrained(root, bounds, constraints, focused, &mut result.geometry)?;
+        }
+
+        apply_gaps(&mut result.geometry, bounds, gaps);
+
+        for (window, rect) in &mut result.geometry {
+            let constraint = constraints.get(window).copied().unwrap_or_default();
+            let constraint = normalized_constraints(constraint);
+
+            record_minimum_warnings(*window, *rect, constraint, &mut result.warnings);
+
+            if let Some(maximum) = constraint.max_width
+                && rect.width > maximum
+            {
+                result.warnings.push(ConstraintWarning {
+                    window: *window,
+                    kind: ConstraintKind::MaximumWidth,
+                    requested: maximum,
+                    assigned: rect.width,
+                });
+                rect.width = maximum;
+            }
+            if let Some(maximum) = constraint.max_height
+                && rect.height > maximum
+            {
+                result.warnings.push(ConstraintWarning {
+                    window: *window,
+                    kind: ConstraintKind::MaximumHeight,
+                    requested: maximum,
+                    assigned: rect.height,
+                });
+                rect.height = maximum;
+            }
+        }
+
+        result.warnings.sort_by_key(|warning| {
+            let kind = match warning.kind {
+                ConstraintKind::MinimumWidth => 0,
+                ConstraintKind::MinimumHeight => 1,
+                ConstraintKind::MaximumWidth => 2,
+                ConstraintKind::MaximumHeight => 3,
+            };
+            (warning.window.0, kind)
+        });
+
+        Ok(result)
+    }
+
+    pub fn automatic_axis(
+        &self,
+        focused: Option<WindowId>,
+        bounds: Rect,
+    ) -> Result<Axis, LayoutError> {
+        let Some(root) = self.root else {
+            return Ok(Axis::Horizontal);
+        };
+        let target = match focused {
+            Some(window) => window,
+            None => match self.nodes.get(&self.first_window(root)?) {
+                Some(Node::Window(window)) => *window,
+                _ => return Err(LayoutError::InvalidTree("leaf is not a window")),
+            },
+        };
+        let rect = self
+            .geometry(bounds)?
+            .remove(&target)
+            .ok_or(LayoutError::UnknownWindow(target))?;
+
+        Ok(if rect.width > rect.height {
+            Axis::Horizontal
+        } else {
+            Axis::Vertical
+        })
+    }
+
+    pub fn directional_neighbor(
+        &self,
+        window: WindowId,
+        direction: Direction,
+        bounds: Rect,
+    ) -> Result<Option<WindowId>, LayoutError> {
+        let geometry = self.geometry(bounds)?;
+        let target = geometry
+            .get(&window)
+            .copied()
+            .ok_or(LayoutError::UnknownWindow(window))?;
+        let (target_x, target_y) = target.center();
+
+        Ok(geometry
+            .into_iter()
+            .filter(|(candidate, _)| *candidate != window)
+            .filter_map(|(candidate, rect)| {
+                let (candidate_x, candidate_y) = rect.center();
+                let (primary, secondary, aligned) = match direction {
+                    Direction::Left if candidate_x < target_x => (
+                        target_x - candidate_x,
+                        (target_y - candidate_y).abs(),
+                        intervals_overlap(target.y, target.height, rect.y, rect.height),
+                    ),
+                    Direction::Right if candidate_x > target_x => (
+                        candidate_x - target_x,
+                        (target_y - candidate_y).abs(),
+                        intervals_overlap(target.y, target.height, rect.y, rect.height),
+                    ),
+                    Direction::Up if candidate_y < target_y => (
+                        target_y - candidate_y,
+                        (target_x - candidate_x).abs(),
+                        intervals_overlap(target.x, target.width, rect.x, rect.width),
+                    ),
+                    Direction::Down if candidate_y > target_y => (
+                        candidate_y - target_y,
+                        (target_x - candidate_x).abs(),
+                        intervals_overlap(target.x, target.width, rect.x, rect.width),
+                    ),
+                    _ => return None,
+                };
+
+                Some((candidate, primary, secondary, aligned))
+            })
+            .min_by(|left, right| {
+                right
+                    .3
+                    .cmp(&left.3)
+                    .then_with(|| left.1.total_cmp(&right.1))
+                    .then_with(|| left.2.total_cmp(&right.2))
+                    .then_with(|| left.0.0.cmp(&right.0.0))
+            })
+            .map(|(candidate, _, _, _)| candidate))
+    }
+
+    pub fn move_window(
+        &mut self,
+        window: WindowId,
+        direction: Direction,
+        bounds: Rect,
+    ) -> Result<bool, LayoutError> {
+        let Some(neighbor) = self.directional_neighbor(window, direction, bounds)? else {
+            return Ok(false);
+        };
+        let window_node = self
+            .windows
+            .get(&window)
+            .copied()
+            .ok_or(LayoutError::UnknownWindow(window))?;
+        let neighbor_node = self
+            .windows
+            .get(&neighbor)
+            .copied()
+            .ok_or(LayoutError::UnknownWindow(neighbor))?;
+
+        self.nodes.insert(window_node, Node::Window(neighbor));
+        self.nodes.insert(neighbor_node, Node::Window(window));
+        self.windows.insert(window, neighbor_node);
+        self.windows.insert(neighbor, window_node);
+
+        debug_assert!(self.validate().is_ok());
+        Ok(true)
+    }
+
+    pub fn resize_window(
+        &mut self,
+        window: WindowId,
+        direction: Direction,
+        amount: f64,
+    ) -> Result<bool, LayoutError> {
+        let mut child = self
+            .windows
+            .get(&window)
+            .copied()
+            .ok_or(LayoutError::UnknownWindow(window))?;
+        let amount = valid_resize_amount(amount);
+
+        if amount == 0.0 {
+            return Ok(false);
+        }
+
+        while let Some(parent) = self.parents.get(&child).copied() {
+            let adjustment = match self.nodes.get(&parent) {
+                Some(Node::Split {
+                    axis: Axis::Horizontal,
+                    first,
+                    ..
+                }) if direction == Direction::Right && *first == child => Some(amount),
+                Some(Node::Split {
+                    axis: Axis::Horizontal,
+                    second,
+                    ..
+                }) if direction == Direction::Left && *second == child => Some(-amount),
+                Some(Node::Split {
+                    axis: Axis::Vertical,
+                    first,
+                    ..
+                }) if direction == Direction::Down && *first == child => Some(amount),
+                Some(Node::Split {
+                    axis: Axis::Vertical,
+                    second,
+                    ..
+                }) if direction == Direction::Up && *second == child => Some(-amount),
+                Some(Node::Split { .. } | Node::Stack { .. }) => None,
+                Some(Node::Window(_)) => {
+                    return Err(LayoutError::InvalidTree("window cannot be a parent"));
+                }
+                None => return Err(LayoutError::InvalidTree("parent node is missing")),
+            };
+
+            if let Some(adjustment) = adjustment {
+                let Some(Node::Split { ratio, .. }) = self.nodes.get_mut(&parent) else {
+                    return Err(LayoutError::InvalidTree("resize target is not a split"));
+                };
+                let resized = normalized_ratio(*ratio + adjustment);
+                let changed = resized != *ratio;
+                *ratio = resized;
+
+                debug_assert!(self.validate().is_ok());
+                return Ok(changed);
+            }
+
+            child = parent;
+        }
+
+        Ok(false)
+    }
+
+    pub fn validate(&self) -> Result<(), LayoutError> {
+        let Some(root) = self.root else {
+            return if self.nodes.is_empty() && self.parents.is_empty() && self.windows.is_empty() {
+                Ok(())
+            } else {
+                Err(LayoutError::InvalidTree("empty root retains nodes"))
+            };
+        };
+        if self.parents.contains_key(&root) {
+            return Err(LayoutError::InvalidTree("root has a parent"));
+        }
+
+        let mut visited = HashSet::new();
+        self.validate_node(root, None, &mut visited)?;
+
+        if visited.len() != self.nodes.len() {
+            return Err(LayoutError::InvalidTree("tree contains unreachable nodes"));
+        }
+        if self.windows.len()
+            != self
+                .nodes
+                .values()
+                .filter(|node| matches!(node, Node::Window(_)))
+                .count()
+        {
+            return Err(LayoutError::InvalidTree("window index is inconsistent"));
+        }
+
+        Ok(())
+    }
+
+    fn insert_node(&mut self, node: Node) -> NodeId {
+        let id = NodeId(self.next_node);
+        self.next_node += 1;
+        self.nodes.insert(id, node);
+        id
+    }
+
+    fn collect_window_positions(
+        &self,
+        node: NodeId,
+        bounds: Rect,
+        windows: &mut Vec<(WindowId, Rect)>,
+    ) -> Result<(), LayoutError> {
+        match self.nodes.get(&node) {
+            Some(Node::Window(window)) => windows.push((*window, bounds)),
+            Some(Node::Split {
+                axis,
+                ratio,
+                first,
+                second,
+            }) => {
+                let (first_bounds, second_bounds) = split_rect(bounds, *axis, *ratio);
+                self.collect_window_positions(*first, first_bounds, windows)?;
+                self.collect_window_positions(*second, second_bounds, windows)?;
+            }
+            Some(Node::Stack { children, .. }) => {
+                for child in children {
+                    self.collect_window_positions(*child, bounds, windows)?;
+                }
+            }
+            None => return Err(LayoutError::InvalidTree("node is missing")),
+        }
+        Ok(())
+    }
+
+    fn first_window(&self, node: NodeId) -> Result<NodeId, LayoutError> {
+        match self.nodes.get(&node) {
+            Some(Node::Window(_)) => Ok(node),
+            Some(Node::Split { first, .. }) => self.first_window(*first),
+            Some(Node::Stack {
+                children, active, ..
+            }) => children
+                .get(*active)
+                .copied()
+                .ok_or(LayoutError::InvalidTree("stack active index is invalid"))
+                .and_then(|child| self.first_window(child)),
+            None => Err(LayoutError::InvalidTree("node is missing")),
+        }
+    }
+
+    fn replace_child(
+        &mut self,
+        parent: NodeId,
+        old: NodeId,
+        new: NodeId,
+    ) -> Result<(), LayoutError> {
+        match self.nodes.get_mut(&parent) {
+            Some(Node::Split { first, .. }) if *first == old => *first = new,
+            Some(Node::Split { second, .. }) if *second == old => *second = new,
+            Some(Node::Stack { children, .. }) => {
+                let child = children
+                    .iter_mut()
+                    .find(|child| **child == old)
+                    .ok_or(LayoutError::InvalidTree("parent does not contain child"))?;
+                *child = new;
+            }
+            _ => return Err(LayoutError::InvalidTree("parent does not contain child")),
+        }
+
+        Ok(())
+    }
+
+    fn collapse_parent(
+        &mut self,
+        parent: NodeId,
+        leaf: NodeId,
+        sibling: NodeId,
+    ) -> Result<(), LayoutError> {
+        let window = match self.nodes.get(&leaf) {
+            Some(Node::Window(window)) => *window,
+            _ => return Err(LayoutError::InvalidTree("removed leaf is not a window")),
+        };
+        let grandparent = self.parents.get(&parent).copied();
+
+        self.windows.remove(&window);
+        self.parents.remove(&leaf);
+        self.parents.remove(&parent);
+        self.nodes.remove(&leaf);
+        self.nodes.remove(&parent);
+
+        if let Some(grandparent) = grandparent {
+            self.replace_child(grandparent, parent, sibling)?;
+            self.parents.insert(sibling, grandparent);
+        } else {
+            self.parents.remove(&sibling);
+            self.root = Some(sibling);
+        }
+
+        Ok(())
+    }
+
+    fn layout_node(
+        &self,
+        node: NodeId,
+        bounds: Rect,
+        geometry: &mut HashMap<WindowId, Rect>,
+    ) -> Result<(), LayoutError> {
+        match self.nodes.get(&node) {
+            Some(Node::Window(window)) => {
+                geometry.insert(*window, bounds);
+            }
+            Some(Node::Split {
+                axis,
+                ratio,
+                first,
+                second,
+            }) => {
+                let (first_bounds, second_bounds) = split_rect(bounds, *axis, *ratio);
+                self.layout_node(*first, first_bounds, geometry)?;
+                self.layout_node(*second, second_bounds, geometry)?;
+            }
+            Some(Node::Stack { children, active }) => {
+                let child = children
+                    .get(*active)
+                    .ok_or(LayoutError::InvalidTree("stack active index is invalid"))?;
+                self.layout_node(*child, bounds, geometry)?;
+            }
+            None => return Err(LayoutError::InvalidTree("node is missing")),
+        }
+
+        Ok(())
+    }
+
+    fn layout_node_constrained(
+        &self,
+        node: NodeId,
+        bounds: Rect,
+        constraints: &HashMap<WindowId, SizeConstraints>,
+        focused: Option<WindowId>,
+        geometry: &mut HashMap<WindowId, Rect>,
+    ) -> Result<(), LayoutError> {
+        match self.nodes.get(&node) {
+            Some(Node::Window(window)) => {
+                geometry.insert(*window, bounds);
+            }
+            Some(Node::Split {
+                axis,
+                ratio,
+                first,
+                second,
+            }) => {
+                let first_minimum = self.minimum_size(*first, constraints)?;
+                let second_minimum = self.minimum_size(*second, constraints)?;
+                let available = match axis {
+                    Axis::Horizontal => bounds.width,
+                    Axis::Vertical => bounds.height,
+                }
+                .max(0.0);
+                let first_required = match axis {
+                    Axis::Horizontal => first_minimum.0,
+                    Axis::Vertical => first_minimum.1,
+                };
+                let second_required = match axis {
+                    Axis::Horizontal => second_minimum.0,
+                    Axis::Vertical => second_minimum.1,
+                };
+                let desired = available * ratio;
+                let first_extent = if first_required + second_required <= available {
+                    desired.clamp(first_required, available - second_required)
+                } else if focused.is_some_and(|window| self.contains_window(*first, window)) {
+                    first_required.min(available)
+                } else {
+                    (available - second_required).max(0.0)
+                };
+                let adjusted_ratio = if available > 0.0 {
+                    first_extent / available
+                } else {
+                    0.5
+                };
+                let (first_bounds, second_bounds) = split_rect(bounds, *axis, adjusted_ratio);
+
+                self.layout_node_constrained(*first, first_bounds, constraints, focused, geometry)?;
+                self.layout_node_constrained(
+                    *second,
+                    second_bounds,
+                    constraints,
+                    focused,
+                    geometry,
+                )?;
+            }
+            Some(Node::Stack { children, active }) => {
+                let child = children
+                    .get(*active)
+                    .ok_or(LayoutError::InvalidTree("stack active index is invalid"))?;
+                self.layout_node_constrained(*child, bounds, constraints, focused, geometry)?;
+            }
+            None => return Err(LayoutError::InvalidTree("node is missing")),
+        }
+
+        Ok(())
+    }
+
+    fn minimum_size(
+        &self,
+        node: NodeId,
+        constraints: &HashMap<WindowId, SizeConstraints>,
+    ) -> Result<(f64, f64), LayoutError> {
+        match self.nodes.get(&node) {
+            Some(Node::Window(window)) => {
+                let constraint = constraints.get(window).copied().unwrap_or_default();
+                let constraint = normalized_constraints(constraint);
+                Ok((constraint.min_width, constraint.min_height))
+            }
+            Some(Node::Split {
+                axis,
+                first,
+                second,
+                ..
+            }) => {
+                let first = self.minimum_size(*first, constraints)?;
+                let second = self.minimum_size(*second, constraints)?;
+
+                Ok(match axis {
+                    Axis::Horizontal => (first.0 + second.0, first.1.max(second.1)),
+                    Axis::Vertical => (first.0.max(second.0), first.1 + second.1),
+                })
+            }
+            Some(Node::Stack { children, .. }) => {
+                let mut minimum = (1.0_f64, 1.0_f64);
+
+                for child in children {
+                    let child = self.minimum_size(*child, constraints)?;
+                    minimum.0 = minimum.0.max(child.0);
+                    minimum.1 = minimum.1.max(child.1);
+                }
+
+                Ok(minimum)
+            }
+            None => Err(LayoutError::InvalidTree("node is missing")),
+        }
+    }
+
+    fn contains_window(&self, node: NodeId, window: WindowId) -> bool {
+        match self.nodes.get(&node) {
+            Some(Node::Window(candidate)) => *candidate == window,
+            Some(Node::Split { first, second, .. }) => {
+                self.contains_window(*first, window) || self.contains_window(*second, window)
+            }
+            Some(Node::Stack { children, .. }) => children
+                .iter()
+                .any(|child| self.contains_window(*child, window)),
+            None => false,
+        }
+    }
+
+    fn validate_node(
+        &self,
+        node: NodeId,
+        expected_parent: Option<NodeId>,
+        visited: &mut HashSet<NodeId>,
+    ) -> Result<(), LayoutError> {
+        if !visited.insert(node) {
+            return Err(LayoutError::InvalidTree("tree contains a cycle"));
+        }
+        if self.parents.get(&node).copied() != expected_parent {
+            return Err(LayoutError::InvalidTree("parent index is inconsistent"));
+        }
+
+        match self.nodes.get(&node) {
+            Some(Node::Window(window)) => {
+                if self.windows.get(window) != Some(&node) {
+                    return Err(LayoutError::InvalidTree("window index is inconsistent"));
+                }
+            }
+            Some(Node::Split {
+                ratio,
+                first,
+                second,
+                ..
+            }) => {
+                if first == second
+                    || !ratio.is_finite()
+                    || !(MIN_SPLIT_RATIO..=MAX_SPLIT_RATIO).contains(ratio)
+                {
+                    return Err(LayoutError::InvalidTree("split is invalid"));
+                }
+
+                self.validate_node(*first, Some(node), visited)?;
+                self.validate_node(*second, Some(node), visited)?;
+            }
+            Some(Node::Stack { children, active }) => {
+                if children.len() < 2 || *active >= children.len() {
+                    return Err(LayoutError::InvalidTree("stack is invalid"));
+                }
+
+                for child in children {
+                    self.validate_node(*child, Some(node), visited)?;
+                }
+            }
+            None => return Err(LayoutError::InvalidTree("node is missing")),
+        }
+
+        Ok(())
+    }
+}
+
+fn normalized_ratio(ratio: f64) -> f64 {
+    if ratio.is_finite() {
+        ratio.clamp(MIN_SPLIT_RATIO, MAX_SPLIT_RATIO)
+    } else {
+        0.5
+    }
+}
+
+fn valid_gap(gap: f64) -> f64 {
+    if gap.is_finite() { gap.max(0.0) } else { 0.0 }
+}
+
+fn valid_resize_amount(amount: f64) -> f64 {
+    if amount.is_finite() {
+        amount.abs()
+    } else {
+        0.0
+    }
+}
+
+pub(super) fn normalized_constraints(constraints: SizeConstraints) -> SizeConstraints {
+    let min_width = finite_positive(constraints.min_width).unwrap_or(1.0);
+    let min_height = finite_positive(constraints.min_height).unwrap_or(1.0);
+    let max_width = constraints
+        .max_width
+        .and_then(finite_positive)
+        .map(|maximum| maximum.max(min_width));
+    let max_height = constraints
+        .max_height
+        .and_then(finite_positive)
+        .map(|maximum| maximum.max(min_height));
+
+    SizeConstraints {
+        min_width,
+        min_height,
+        max_width,
+        max_height,
+    }
+}
+
+fn finite_positive(value: f64) -> Option<f64> {
+    (value.is_finite() && value > 0.0).then_some(value)
+}
+
+pub(super) fn record_minimum_warnings(
+    window: WindowId,
+    rect: Rect,
+    constraints: SizeConstraints,
+    warnings: &mut Vec<ConstraintWarning>,
+) {
+    if rect.width < constraints.min_width {
+        warnings.push(ConstraintWarning {
+            window,
+            kind: ConstraintKind::MinimumWidth,
+            requested: constraints.min_width,
+            assigned: rect.width,
+        });
+    }
+    if rect.height < constraints.min_height {
+        warnings.push(ConstraintWarning {
+            window,
+            kind: ConstraintKind::MinimumHeight,
+            requested: constraints.min_height,
+            assigned: rect.height,
+        });
+    }
+}
+
+fn apply_gaps(geometry: &mut HashMap<WindowId, Rect>, bounds: Rect, gaps: GapConfig) {
+    let outer = if gaps.smart && geometry.len() == 1 {
+        0.0
+    } else {
+        valid_gap(gaps.outer)
+    };
+    let half_inner = valid_gap(gaps.inner) / 2.0;
+    let right = bounds.x + bounds.width;
+    let bottom = bounds.y + bounds.height;
+
+    for rect in geometry.values_mut() {
+        let left_inset = if nearly_equal(rect.x, bounds.x) {
+            outer
+        } else {
+            half_inner
+        };
+        let top_inset = if nearly_equal(rect.y, bounds.y) {
+            outer
+        } else {
+            half_inner
+        };
+        let right_inset = if nearly_equal(rect.x + rect.width, right) {
+            outer
+        } else {
+            half_inner
+        };
+        let bottom_inset = if nearly_equal(rect.y + rect.height, bottom) {
+            outer
+        } else {
+            half_inner
+        };
+
+        rect.x += left_inset;
+        rect.y += top_inset;
+        rect.width = (rect.width - left_inset - right_inset).max(1.0);
+        rect.height = (rect.height - top_inset - bottom_inset).max(1.0);
+    }
+}
+
+fn nearly_equal(left: f64, right: f64) -> bool {
+    (left - right).abs() < f64::EPSILON * left.abs().max(right.abs()).max(1.0)
+}
+
+fn intervals_overlap(
+    first_start: f64,
+    first_size: f64,
+    second_start: f64,
+    second_size: f64,
+) -> bool {
+    first_start < second_start + second_size && second_start < first_start + first_size
+}
+
+fn split_rect(bounds: Rect, axis: Axis, ratio: f64) -> (Rect, Rect) {
+    match axis {
+        Axis::Horizontal => {
+            let boundary = bounds.x + bounds.width * ratio;
+            let first = Rect::new(bounds.x, bounds.y, boundary - bounds.x, bounds.height);
+            let second = Rect::new(
+                boundary,
+                bounds.y,
+                bounds.x + bounds.width - boundary,
+                bounds.height,
+            );
+
+            (first, second)
+        }
+        Axis::Vertical => {
+            let boundary = bounds.y + bounds.height * ratio;
+            let first = Rect::new(bounds.x, bounds.y, bounds.width, boundary - bounds.y);
+            let second = Rect::new(
+                bounds.x,
+                boundary,
+                bounds.width,
+                bounds.y + bounds.height - boundary,
+            );
+
+            (first, second)
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn insertion_splits_the_focused_leaf() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Vertical, 0.5)
+            .unwrap();
+
+        assert!(tree.validate().is_ok());
+        assert_eq!(
+            tree.geometry(Rect::new(0.0, 0.0, 100.0, 80.0))
+                .unwrap()
+                .len(),
+            3
+        );
+    }
+
+    #[test]
+    fn removal_collapses_the_parent_split() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.remove(WindowId(1)).unwrap();
+
+        assert!(tree.validate().is_ok());
+        assert_eq!(
+            tree.node(tree.root().unwrap()),
+            Some(&Node::Window(WindowId(2)))
+        );
+    }
+
+    #[test]
+    fn shared_split_boundary_is_exact() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 1.0 / 3.0)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 1.0 / 3.0)
+            .unwrap();
+
+        let geometry = tree.geometry(Rect::new(0.0, 0.0, 101.0, 80.0)).unwrap();
+        let first = geometry[&WindowId(1)];
+        let second = geometry[&WindowId(2)];
+
+        assert_eq!(first.x + first.width, second.x);
+        assert_eq!(second.x + second.width, 101.0);
+    }
+
+    #[test]
+    fn rejects_duplicate_and_unknown_windows() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+
+        assert_eq!(
+            tree.insert(WindowId(1), None, Axis::Horizontal, 0.5),
+            Err(LayoutError::DuplicateWindow(WindowId(1)))
+        );
+        assert_eq!(
+            tree.insert(WindowId(2), Some(WindowId(9)), Axis::Horizontal, 0.5,),
+            Err(LayoutError::UnknownWindow(WindowId(9)))
+        );
+    }
+
+    #[test]
+    fn non_finite_ratio_uses_balanced_split() {
+        assert_eq!(normalized_ratio(f64::NAN), 0.5);
+        assert_eq!(normalized_ratio(f64::INFINITY), 0.5);
+    }
+
+    #[test]
+    fn automatic_axis_follows_focused_tile_shape() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+
+        let wide = Rect::new(0.0, 0.0, 1_920.0, 1_080.0);
+        assert_eq!(
+            tree.automatic_axis(Some(WindowId(1)), wide).unwrap(),
+            Axis::Horizontal
+        );
+
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        assert_eq!(
+            tree.automatic_axis(Some(WindowId(1)), wide).unwrap(),
+            Axis::Vertical
+        );
+    }
+
+    #[test]
+    fn gaps_preserve_outer_and_shared_spacing() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+
+        let geometry = tree
+            .geometry_with_gaps(Rect::new(0.0, 0.0, 100.0, 80.0), GapConfig::default())
+            .unwrap();
+        let first = geometry[&WindowId(1)];
+        let second = geometry[&WindowId(2)];
+
+        assert_eq!(first.x, 4.0);
+        assert_eq!(second.x + second.width, 96.0);
+        assert_eq!(second.x - (first.x + first.width), 10.0);
+    }
+
+    #[test]
+    fn smart_gaps_remove_outer_gap_for_one_window() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+
+        let bounds = Rect::new(0.0, 0.0, 100.0, 80.0);
+        let geometry = tree
+            .geometry_with_gaps(
+                bounds,
+                GapConfig {
+                    smart: true,
+                    ..GapConfig::default()
+                },
+            )
+            .unwrap();
+
+        assert_eq!(geometry[&WindowId(1)], bounds);
+    }
+
+    #[test]
+    fn default_gaps_keep_outer_spacing_for_one_window() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+
+        let geometry = tree
+            .geometry_with_gaps(Rect::new(0.0, 0.0, 100.0, 80.0), GapConfig::default())
+            .unwrap();
+
+        assert_eq!(geometry[&WindowId(1)], Rect::new(4.0, 4.0, 92.0, 72.0));
+    }
+
+    #[test]
+    fn directional_neighbor_prefers_primary_distance() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(3), Some(WindowId(2)), Axis::Vertical, 0.5)
+            .unwrap();
+
+        let bounds = Rect::new(0.0, 0.0, 100.0, 100.0);
+        assert_eq!(
+            tree.directional_neighbor(WindowId(1), Direction::Right, bounds)
+                .unwrap(),
+            Some(WindowId(2))
+        );
+        assert_eq!(
+            tree.directional_neighbor(WindowId(2), Direction::Down, bounds)
+                .unwrap(),
+            Some(WindowId(3))
+        );
+        assert_eq!(
+            tree.directional_neighbor(WindowId(1), Direction::Left, bounds)
+                .unwrap(),
+            None
+        );
+    }
+
+    #[test]
+    fn directional_move_swaps_window_leaves() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        let bounds = Rect::new(0.0, 0.0, 100.0, 80.0);
+
+        assert!(
+            tree.move_window(WindowId(1), Direction::Right, bounds)
+                .unwrap()
+        );
+
+        let geometry = tree.geometry(bounds).unwrap();
+        assert_eq!(geometry[&WindowId(2)].x, 0.0);
+        assert_eq!(geometry[&WindowId(1)].x, 50.0);
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn directional_move_at_boundary_is_a_noop() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+
+        assert!(
+            !tree
+                .move_window(
+                    WindowId(1),
+                    Direction::Left,
+                    Rect::new(0.0, 0.0, 100.0, 80.0),
+                )
+                .unwrap()
+        );
+    }
+
+    #[test]
+    fn directional_resize_changes_the_nearest_matching_split() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        let bounds = Rect::new(0.0, 0.0, 100.0, 100.0);
+
+        assert!(
+            tree.resize_window(WindowId(1), Direction::Right, 0.1)
+                .unwrap()
+        );
+
+        let geometry = tree.geometry(bounds).unwrap();
+        assert_eq!(geometry[&WindowId(1)].width, 30.0);
+        assert_eq!(geometry[&WindowId(3)].x, 30.0);
+        assert_eq!(geometry[&WindowId(2)].x, 50.0);
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn directional_resize_walks_to_an_ancestor_and_clamps() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Vertical, 0.5)
+            .unwrap();
+        let bounds = Rect::new(0.0, 0.0, 100.0, 100.0);
+
+        assert!(
+            tree.resize_window(WindowId(3), Direction::Right, 1.0)
+                .unwrap()
+        );
+        assert!(
+            !tree
+                .resize_window(WindowId(3), Direction::Right, 1.0)
+                .unwrap()
+        );
+
+        let geometry = tree.geometry(bounds).unwrap();
+        assert_eq!(geometry[&WindowId(2)].x, 95.0);
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn directional_resize_at_an_outer_edge_is_a_noop() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+
+        assert!(
+            !tree
+                .resize_window(WindowId(1), Direction::Left, 0.05)
+                .unwrap()
+        );
+        assert!(
+            !tree
+                .resize_window(WindowId(1), Direction::Right, f64::NAN)
+                .unwrap()
+        );
+    }
+
+    #[test]
+    fn stacking_windows_shows_only_the_active_child() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.stack_window(WindowId(2), WindowId(1)).unwrap();
+
+        let geometry = tree.geometry(Rect::new(0.0, 0.0, 100.0, 80.0)).unwrap();
+        assert_eq!(geometry.len(), 1);
+        assert_eq!(geometry[&WindowId(2)], Rect::new(0.0, 0.0, 100.0, 80.0));
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn structural_reading_order_includes_all_stack_members_independently_of_activation() {
+        let mut tree = LayoutTree::default();
+        let ids = [WindowId(30), WindowId(10), WindowId(20), WindowId(5)];
+        tree.insert(ids[0], None, Axis::Horizontal, 0.5).unwrap();
+        for pair in ids.windows(2) {
+            tree.insert(pair[1], Some(pair[0]), Axis::Horizontal, 0.5)
+                .unwrap();
+            tree.stack_window(pair[1], pair[0]).unwrap();
+        }
+        let bounds = Rect::new(0.0, 0.0, 1_000.0, 800.0);
+        for active in ids {
+            tree.activate_window(active).unwrap();
+            assert_eq!(
+                tree.geometry(bounds)
+                    .unwrap()
+                    .keys()
+                    .copied()
+                    .collect::<Vec<_>>(),
+                vec![active]
+            );
+            assert_eq!(tree.window_ids_in_reading_order(bounds).unwrap(), ids);
+            assert_eq!(tree.preferred_window(), Some(active));
+            assert!(tree.validate().is_ok());
+        }
+    }
+
+    #[test]
+    fn flat_stack_reading_order_preserves_every_inactive_member() {
+        let mut tree = LayoutTree::default();
+        let ids = [WindowId(900), WindowId(7), WindowId(400), WindowId(10)];
+        let children = ids
+            .iter()
+            .map(|window| {
+                let leaf = tree.insert_node(Node::Window(*window));
+                tree.windows.insert(*window, leaf);
+                leaf
+            })
+            .collect::<Vec<_>>();
+        let root = tree.insert_node(Node::Stack {
+            children: children.clone(),
+            active: 2,
+        });
+        for child in children {
+            tree.parents.insert(child, root);
+        }
+        tree.root = Some(root);
+        let bounds = Rect::new(0.0, 0.0, 1_000.0, 800.0);
+        assert!(tree.validate().is_ok());
+        assert_eq!(tree.geometry(bounds).unwrap().len(), 1);
+        assert_eq!(tree.preferred_window(), Some(ids[2]));
+        assert_eq!(tree.window_ids_in_reading_order(bounds).unwrap(), ids);
+    }
+
+    #[test]
+    fn structural_reading_order_retains_xy_order_through_splits_and_stacks() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(40), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(10), Some(WindowId(40)), Axis::Vertical, 0.5)
+            .unwrap();
+        tree.insert(WindowId(30), Some(WindowId(40)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(20), Some(WindowId(40)), Axis::Vertical, 0.5)
+            .unwrap();
+        tree.stack_window(WindowId(20), WindowId(40)).unwrap();
+        tree.insert(WindowId(50), Some(WindowId(10)), Axis::Horizontal, 0.5)
+            .unwrap();
+        let bounds = Rect::new(25.0, 40.0, 1_000.0, 800.0);
+        let expected = [40, 20, 10, 30, 50].map(WindowId);
+        assert_eq!(tree.window_ids_in_reading_order(bounds).unwrap(), expected);
+        assert_eq!(tree.geometry(bounds).unwrap().len(), 4);
+        let collapsed = tree.window_ids_in_reading_order(Rect::default()).unwrap();
+        assert_eq!(collapsed.len(), expected.len());
+        assert_eq!(
+            collapsed.into_iter().collect::<HashSet<_>>(),
+            expected.into_iter().collect()
+        );
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn tree_preference_follows_first_split_branch_and_active_stack_children() {
+        let mut tree = LayoutTree::default();
+        assert_eq!(tree.preferred_window(), None);
+        assert!(
+            tree.window_ids_in_reading_order(Rect::default())
+                .unwrap()
+                .is_empty()
+        );
+        tree.insert(WindowId(30), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(10), Some(WindowId(30)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(20), Some(WindowId(30)), Axis::Vertical, 0.5)
+            .unwrap();
+        tree.stack_window(WindowId(20), WindowId(30)).unwrap();
+        assert_eq!(tree.preferred_window(), Some(WindowId(20)));
+        tree.activate_window(WindowId(30)).unwrap();
+        assert_eq!(tree.preferred_window(), Some(WindowId(30)));
+        tree.activate_window(WindowId(10)).unwrap();
+        assert_eq!(tree.preferred_window(), Some(WindowId(30)));
+    }
+
+    #[test]
+    fn activating_a_hidden_stack_child_changes_visible_geometry() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.stack_window(WindowId(2), WindowId(1)).unwrap();
+        tree.activate_window(WindowId(1)).unwrap();
+
+        let geometry = tree.geometry(Rect::new(0.0, 0.0, 100.0, 80.0)).unwrap();
+        assert_eq!(geometry.len(), 1);
+        assert_eq!(geometry[&WindowId(1)], Rect::new(0.0, 0.0, 100.0, 80.0));
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn removing_from_a_stack_collapses_or_preserves_cardinality() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.stack_window(WindowId(2), WindowId(1)).unwrap();
+        tree.insert(WindowId(3), Some(WindowId(2)), Axis::Vertical, 0.5)
+            .unwrap();
+
+        tree.remove(WindowId(3)).unwrap();
+        tree.remove(WindowId(2)).unwrap();
+
+        assert_eq!(
+            tree.node(tree.root().unwrap()),
+            Some(&Node::Window(WindowId(1)))
+        );
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn randomized_operation_sequences_preserve_tree_invariants() {
+        let mut tree = LayoutTree::default();
+        let mut windows = Vec::new();
+        let mut next_window = 1;
+        let mut random = 0x5eed_u64;
+        let bounds = Rect::new(0.0, 0.0, 1_920.0, 1_080.0);
+
+        for _ in 0..2_000 {
+            random = random
+                .wrapping_mul(6_364_136_223_846_793_005)
+                .wrapping_add(1);
+            let operation = random % 6;
+
+            match operation {
+                0 if windows.len() < 32 => {
+                    let window = WindowId(next_window);
+                    next_window += 1;
+                    let focused = choose_window(&windows, random.rotate_left(7));
+                    let axis = if random & 1 == 0 {
+                        Axis::Horizontal
+                    } else {
+                        Axis::Vertical
+                    };
+
+                    tree.insert(window, focused, axis, ratio_from_random(random))
+                        .unwrap();
+                    windows.push(window);
+                }
+                1 if !windows.is_empty() => {
+                    let index = random as usize % windows.len();
+                    let window = windows.swap_remove(index);
+                    tree.remove(window).unwrap();
+                }
+                2 if windows.len() >= 2 => {
+                    let first = random as usize % windows.len();
+                    let mut second = random.rotate_left(13) as usize % windows.len();
+                    if first == second {
+                        second = (second + 1) % windows.len();
+                    }
+
+                    tree.stack_window(windows[first], windows[second]).unwrap();
+                }
+                3 if !windows.is_empty() => {
+                    let window = windows[random as usize % windows.len()];
+                    tree.activate_window(window).unwrap();
+                }
+                4 if !windows.is_empty() => {
+                    let window = windows[random as usize % windows.len()];
+                    let _ = tree.move_window(window, random_direction(random), bounds);
+                }
+                5 if !windows.is_empty() => {
+                    let window = windows[random as usize % windows.len()];
+                    tree.resize_window(window, random_direction(random), 0.03)
+                        .unwrap();
+                }
+                _ => {}
+            }
+
+            assert!(tree.validate().is_ok());
+        }
+    }
+
+    #[test]
+    fn constraints_adjust_split_boundaries_when_space_is_available() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.2)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.2)
+            .unwrap();
+        let constraints = HashMap::from([
+            (
+                WindowId(1),
+                SizeConstraints {
+                    min_width: 40.0,
+                    ..SizeConstraints::default()
+                },
+            ),
+            (
+                WindowId(2),
+                SizeConstraints {
+                    min_width: 30.0,
+                    ..SizeConstraints::default()
+                },
+            ),
+        ]);
+        let result = tree
+            .geometry_with_constraints(
+                Rect::new(0.0, 0.0, 100.0, 80.0),
+                GapConfig {
+                    inner: 0.0,
+                    outer: 0.0,
+                    smart: false,
+                },
+                &constraints,
+                Some(WindowId(1)),
+            )
+            .unwrap();
+
+        assert_eq!(result.geometry[&WindowId(1)].width, 40.0);
+        assert_eq!(result.geometry[&WindowId(2)].width, 60.0);
+        assert!(result.warnings.is_empty());
+    }
+
+    #[test]
+    fn focused_window_wins_an_impossible_minimum_constraint_conflict() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
+            .unwrap();
+        let constraints = HashMap::from([
+            (
+                WindowId(1),
+                SizeConstraints {
+                    min_width: 80.0,
+                    ..SizeConstraints::default()
+                },
+            ),
+            (
+                WindowId(2),
+                SizeConstraints {
+                    min_width: 80.0,
+                    ..SizeConstraints::default()
+                },
+            ),
+        ]);
+        let result = tree
+            .geometry_with_constraints(
+                Rect::new(0.0, 0.0, 100.0, 80.0),
+                GapConfig {
+                    inner: 0.0,
+                    outer: 0.0,
+                    smart: false,
+                },
+                &constraints,
+                Some(WindowId(1)),
+            )
+            .unwrap();
+
+        assert_eq!(result.geometry[&WindowId(1)].width, 80.0);
+        assert_eq!(result.geometry[&WindowId(2)].width, 20.0);
+        assert_eq!(result.warnings.len(), 1);
+        assert_eq!(result.warnings[0].window, WindowId(2));
+        assert_eq!(result.warnings[0].kind, ConstraintKind::MinimumWidth);
+    }
+
+    #[test]
+    fn maximum_constraints_clip_without_overlapping_neighbors() {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        let constraints = HashMap::from([(
+            WindowId(1),
+            SizeConstraints {
+                max_width: Some(60.0),
+                max_height: Some(40.0),
+                ..SizeConstraints::default()
+            },
+        )]);
+        let result = tree
+            .geometry_with_constraints(
+                Rect::new(0.0, 0.0, 100.0, 80.0),
+                GapConfig::default(),
+                &constraints,
+                Some(WindowId(1)),
+            )
+            .unwrap();
+
+        assert_eq!(
+            result.geometry[&WindowId(1)],
+            Rect::new(4.0, 4.0, 60.0, 40.0)
+        );
+        assert_eq!(result.warnings.len(), 2);
+    }
+
+    fn choose_window(windows: &[WindowId], random: u64) -> Option<WindowId> {
+        (!windows.is_empty()).then(|| windows[random as usize % windows.len()])
+    }
+
+    fn ratio_from_random(random: u64) -> f64 {
+        0.2 + (random.rotate_left(19) % 601) as f64 / 1_000.0
+    }
+
+    fn random_direction(random: u64) -> Direction {
+        match random.rotate_left(29) % 4 {
+            0 => Direction::Left,
+            1 => Direction::Right,
+            2 => Direction::Up,
+            _ => Direction::Down,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tab_tests {
+    use super::*;
+
+    fn nested() -> LayoutTree {
+        let mut tree = LayoutTree::default();
+        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
+            .unwrap();
+        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.6)
+            .unwrap();
+        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Vertical, 0.4)
+            .unwrap();
+        tree.insert(WindowId(4), Some(WindowId(3)), Axis::Horizontal, 0.5)
+            .unwrap();
+        tree
+    }
+
+    #[test]
+    fn joining_and_leaving_tabs_preserve_neighboring_splits() {
+        let mut tree = nested();
+        let bounds = Rect::new(0., 0., 1000., 800.);
+        let neighbor = tree.geometry(bounds).unwrap()[&WindowId(2)];
+        tree.stack_window(WindowId(4), WindowId(3)).unwrap();
+        tree.stack_window(WindowId(1), WindowId(3)).unwrap();
+        assert_eq!(
+            tree.tab_group(WindowId(1)).unwrap().windows,
+            [WindowId(3), WindowId(4), WindowId(1)]
+        );
+        assert_eq!(tree.geometry(bounds).unwrap()[&WindowId(2)], neighbor);
+        assert_eq!(tree.visible_window_count(), 2);
+        let before = tree.clone();
+        tree.stack_window(WindowId(1), WindowId(4)).unwrap();
+        assert_eq!(tree, before, "joining the same group must not reorder it");
+        assert_eq!(tree.adjacent_tab(WindowId(1), false), Some(WindowId(3)));
+        assert_eq!(tree.adjacent_tab(WindowId(3), true), Some(WindowId(1)));
+        assert!(tree.leave_tab_group(WindowId(1)).unwrap());
+        assert_eq!(tree.geometry(bounds).unwrap()[&WindowId(2)], neighbor);
+        assert_eq!(
+            tree.tab_group(WindowId(4)).unwrap().windows,
+            [WindowId(3), WindowId(4)]
+        );
+        assert!(tree.tab_group(WindowId(1)).is_none());
+        assert!(!tree.leave_tab_group(WindowId(1)).unwrap());
+        tree.remove(WindowId(4)).unwrap();
+        assert!(tree.tab_groups().is_empty());
+        assert!(tree.validate().is_ok());
+    }
+
+    #[test]
+    fn opening_beside_a_group_and_removing_active_tabs_keep_all_members_reachable() {
+        let mut tree = nested();
+        tree.stack_window(WindowId(4), WindowId(3)).unwrap();
+        tree.stack_window(WindowId(1), WindowId(3)).unwrap();
+        tree.insert(WindowId(5), Some(WindowId(1)), Axis::Vertical, 0.3)
+            .unwrap();
+        assert_eq!(tree.tab_groups().len(), 1);
+        let bounds = Rect::new(0., 0., 1000., 800.);
+        for id in [WindowId(3), WindowId(4), WindowId(1)] {
+            tree.activate_window(id).unwrap();
+            let geometry = tree.geometry(bounds).unwrap();
+            assert!(geometry.contains_key(&WindowId(5)));
+            assert!(geometry.contains_key(&id));
+            assert_eq!(geometry.len(), 3);
+        }
+        tree.remove(WindowId(1)).unwrap();
+        assert_eq!(tree.tab_group(WindowId(3)).unwrap().active, WindowId(4));
+        tree.remove(WindowId(3)).unwrap();
+        assert!(tree.tab_groups().is_empty());
+        assert!(tree.validate().is_ok());
+    }
+}
diff --git a/crates/ferese-layout/src/lib.rs b/crates/ferese-layout/src/lib.rs
index e65bb67..adad43d 100644
--- a/crates/ferese-layout/src/lib.rs
+++ b/crates/ferese-layout/src/lib.rs
@@ -1,1935 +1,8 @@
-use std::collections::{HashMap, HashSet};
-use std::error::Error;
-use std::fmt;
-
+//! Tree and scrolling layouts share window identities, constraints and geometry.
+mod layout_tree;
 mod scrolling;
 
+pub use layout_tree::*;
 pub use scrolling::{
     Column, ColumnDisplay, ColumnWidth, ScrollingLayout, ViewportFocusStrategy, ViewportTarget,
 };
-
-pub const TAB_BAR_HEIGHT: f64 = 24.0;
-
-const MIN_SPLIT_RATIO: f64 = 0.05;
-const MAX_SPLIT_RATIO: f64 = 0.95;
-
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-pub struct WindowId(pub u64);
-
-#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
-pub struct NodeId(u64);
-
-#[derive(Clone, Debug, PartialEq)]
-pub struct TabGroup {
-    pub windows: Vec<WindowId>,
-    pub active: WindowId,
-}
-
-#[derive(Clone, Debug, PartialEq)]
-pub struct TabBar {
-    pub group: TabGroup,
-    pub rect: Rect,
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub enum Axis {
-    Horizontal,
-    Vertical,
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub enum Direction {
-    Left,
-    Right,
-    Up,
-    Down,
-}
-
-#[derive(Clone, Debug, PartialEq)]
-pub enum Node {
-    Window(WindowId),
-    Split {
-        axis: Axis,
-        ratio: f64,
-        first: NodeId,
-        second: NodeId,
-    },
-    Stack {
-        children: Vec<NodeId>,
-        active: usize,
-    },
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq)]
-pub struct Rect {
-    pub x: f64,
-    pub y: f64,
-    pub width: f64,
-    pub height: f64,
-}
-
-impl Rect {
-    pub const fn new(x: f64, y: f64, width: f64, height: f64) -> Self {
-        Self {
-            x,
-            y,
-            width,
-            height,
-        }
-    }
-
-    fn center(self) -> (f64, f64) {
-        (self.x + self.width / 2.0, self.y + self.height / 2.0)
-    }
-}
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct GapConfig {
-    pub inner: f64,
-    pub outer: f64,
-    pub smart: bool,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct SizeConstraints {
-    pub min_width: f64,
-    pub min_height: f64,
-    pub max_width: Option<f64>,
-    pub max_height: Option<f64>,
-}
-
-impl Default for SizeConstraints {
-    fn default() -> Self {
-        Self {
-            min_width: 1.0,
-            min_height: 1.0,
-            max_width: None,
-            max_height: None,
-        }
-    }
-}
-
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub enum ConstraintKind {
-    MinimumWidth,
-    MinimumHeight,
-    MaximumWidth,
-    MaximumHeight,
-}
-
-#[derive(Clone, Copy, Debug, PartialEq)]
-pub struct ConstraintWarning {
-    pub window: WindowId,
-    pub kind: ConstraintKind,
-    pub requested: f64,
-    pub assigned: f64,
-}
-
-#[derive(Debug, Default, PartialEq)]
-pub struct LayoutResult {
-    pub geometry: HashMap<WindowId, Rect>,
-    pub warnings: Vec<ConstraintWarning>,
-    pub tab_bars: Vec<TabBar>,
-}
-
-impl Default for GapConfig {
-    fn default() -> Self {
-        Self {
-            inner: 10.0,
-            outer: 4.0,
-            smart: false,
-        }
-    }
-}
-
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub enum LayoutError {
-    DuplicateWindow(WindowId),
-    UnknownWindow(WindowId),
-    InvalidTree(&'static str),
-}
-
-impl fmt::Display for LayoutError {
-    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
-        match self {
-            Self::DuplicateWindow(window) => write!(formatter, "duplicate window {window:?}"),
-            Self::UnknownWindow(window) => write!(formatter, "unknown window {window:?}"),
-            Self::InvalidTree(reason) => write!(formatter, "invalid layout tree: {reason}"),
-        }
-    }
-}
-
-impl Error for LayoutError {}
-
-#[derive(Clone, Debug, Default, PartialEq)]
-pub struct LayoutTree {
-    root: Option<NodeId>,
-    nodes: HashMap<NodeId, Node>,
-    parents: HashMap<NodeId, NodeId>,
-    windows: HashMap<WindowId, NodeId>,
-    next_node: u64,
-}
-
-impl LayoutTree {
-    pub fn root(&self) -> Option<NodeId> {
-        self.root
-    }
-
-    pub fn node(&self, id: NodeId) -> Option<&Node> {
-        self.nodes.get(&id)
-    }
-
-    pub fn contains(&self, window: WindowId) -> bool {
-        self.windows.contains_key(&window)
-    }
-
-    pub fn window_ids(&self) -> impl Iterator<Item = WindowId> + '_ {
-        self.windows.keys().copied()
-    }
-
-    pub fn visible_window_count(&self) -> usize {
-        fn count(tree: &LayoutTree, node: NodeId) -> usize {
-            match tree.nodes.get(&node) {
-                Some(Node::Window(_)) => 1,
-                Some(Node::Split { first, second, .. }) => {
-                    count(tree, *first) + count(tree, *second)
-                }
-                Some(Node::Stack { children, active }) => {
-                    children.get(*active).map_or(0, |child| count(tree, *child))
-                }
-                None => 0,
-            }
-        }
-        self.root.map_or(0, |root| count(self, root))
-    }
-
-    pub fn preferred_window(&self) -> Option<WindowId> {
-        let leaf = self.first_window(self.root?).ok()?;
-        match self.nodes.get(&leaf)? {
-            Node::Window(window) => Some(*window),
-            _ => None,
-        }
-    }
-
-    /// Include every structural leaf, even inactive stack members. Preserve
-    /// stack child order when their positions coincide.
-    pub fn window_ids_in_reading_order(&self, bounds: Rect) -> Result<Vec<WindowId>, LayoutError> {
-        self.validate()?;
-        let mut windows = Vec::with_capacity(self.windows.len());
-        if let Some(root) = self.root {
-            self.collect_window_positions(root, bounds, &mut windows)?;
-        }
-        windows.sort_by(|(_, left), (_, right)| {
-            left.x
-                .total_cmp(&right.x)
-                .then_with(|| left.y.total_cmp(&right.y))
-        });
-        Ok(windows.into_iter().map(|(window, _)| window).collect())
-    }
-
-    pub fn insert(
-        &mut self,
-        window: WindowId,
-        focused: Option<WindowId>,
-        axis: Axis,
-        ratio: f64,
-    ) -> Result<NodeId, LayoutError> {
-        if self.contains(window) {
-            return Err(LayoutError::DuplicateWindow(window));
-        }
-
-        let Some(root) = self.root else {
-            let window_node = self.insert_node(Node::Window(window));
-            self.windows.insert(window, window_node);
-            self.root = Some(window_node);
-            return Ok(window_node);
-        };
-
-        let target = match focused {
-            Some(focused) => self
-                .windows
-                .get(&focused)
-                .copied()
-                .ok_or(LayoutError::UnknownWindow(focused))?,
-            None => self.first_window(root)?,
-        };
-        // A new split belongs beside the whole tab group, not inside one tab.
-        let target = self.tab_parent(target).unwrap_or(target);
-        let old_parent = self.parents.get(&target).copied();
-        let window_node = self.insert_node(Node::Window(window));
-        self.windows.insert(window, window_node);
-        let split = self.insert_node(Node::Split {
-            axis,
-            ratio: normalized_ratio(ratio),
-            first: target,
-            second: window_node,
-        });
-
-        self.parents.insert(target, split);
-        self.parents.insert(window_node, split);
-
-        if let Some(parent) = old_parent {
-            self.replace_child(parent, target, split)?;
-            self.parents.insert(split, parent);
-        } else {
-            self.root = Some(split);
-        }
-
-        debug_assert!(self.validate().is_ok());
-        Ok(window_node)
-    }
-
-    pub fn remove(&mut self, window: WindowId) -> Result<(), LayoutError> {
-        let leaf = self
-            .windows
-            .get(&window)
-            .copied()
-            .ok_or(LayoutError::UnknownWindow(window))?;
-        let Some(parent) = self.parents.get(&leaf).copied() else {
-            self.windows.remove(&window);
-            self.nodes.remove(&leaf);
-            self.root = None;
-            return Ok(());
-        };
-
-        match self.nodes.get(&parent).cloned() {
-            Some(Node::Split { first, second, .. }) => {
-                let sibling = if first == leaf {
-                    second
-                } else if second == leaf {
-                    first
-                } else {
-                    return Err(LayoutError::InvalidTree("split does not contain window"));
-                };
-
-                self.collapse_parent(parent, leaf, sibling)?;
-            }
-            Some(Node::Stack {
-                mut children,
-                mut active,
-            }) => {
-                let position = children
-                    .iter()
-                    .position(|child| *child == leaf)
-                    .ok_or(LayoutError::InvalidTree("stack does not contain window"))?;
-
-                if children.len() == 2 {
-                    let sibling = children[1 - position];
-                    self.collapse_parent(parent, leaf, sibling)?;
-                } else {
-                    children.remove(position);
-                    if position < active {
-                        active -= 1;
-                    } else if position == active {
-                        active = active.min(children.len() - 1);
-                    }
-
-                    self.windows.remove(&window);
-                    self.parents.remove(&leaf);
-                    self.nodes.remove(&leaf);
-                    self.nodes.insert(parent, Node::Stack { children, active });
-                }
-            }
-            Some(Node::Window(_)) => {
-                return Err(LayoutError::InvalidTree("window parent is a window"));
-            }
-            None => return Err(LayoutError::InvalidTree("window parent is missing")),
-        }
-
-        debug_assert!(self.validate().is_ok());
-        Ok(())
-    }
-
-    pub fn stack_window(&mut self, window: WindowId, target: WindowId) -> Result<(), LayoutError> {
-        if window == target {
-            return Ok(());
-        }
-        if !self.contains(target) {
-            return Err(LayoutError::UnknownWindow(target));
-        }
-        if !self.contains(window) {
-            return Err(LayoutError::UnknownWindow(window));
-        }
-
-        if self
-            .tab_group(window)
-            .is_some_and(|group| group.windows.contains(&target))
-        {
-            return self.activate_window(window);
-        }
-
-        self.remove(window)?;
-
-        let target_node = self
-            .windows
-            .get(&target)
-            .copied()
-            .ok_or(LayoutError::UnknownWindow(target))?;
-        let old_parent = self.parents.get(&target_node).copied();
-        let window_node = self.insert_node(Node::Window(window));
-        if let Some(parent) = self.tab_parent(target_node) {
-            let Some(Node::Stack { children, active }) = self.nodes.get_mut(&parent) else {
-                unreachable!()
-            };
-            children.push(window_node);
-            *active = children.len() - 1;
-            self.windows.insert(window, window_node);
-            self.parents.insert(window_node, parent);
-            debug_assert!(self.validate().is_ok());
-            return Ok(());
-        }
-        let stack = self.insert_node(Node::Stack {
-            children: vec![target_node, window_node],
-            active: 1,
-        });
-
-        self.windows.insert(window, window_node);
-        self.parents.insert(target_node, stack);
-        self.parents.insert(window_node, stack);
-
-        if let Some(parent) = old_parent {
-            self.replace_child(parent, target_node, stack)?;
-            self.parents.insert(stack, parent);
-        } else {
-            self.root = Some(stack);
-        }
-
-        debug_assert!(self.validate().is_ok());
-        Ok(())
-    }
-
-    fn tab_parent(&self, leaf: NodeId) -> Option<NodeId> {
-        let parent = *self.parents.get(&leaf)?;
-        match self.nodes.get(&parent)? {
-            Node::Stack { children, .. }
-                if children
-                    .iter()
-                    .all(|id| matches!(self.nodes.get(id), Some(Node::Window(_)))) =>
-            {
-                Some(parent)
-            }
-            _ => None,
-        }
-    }
-
-    fn group_at(&self, node: NodeId) -> Option<TabGroup> {
-        let Node::Stack { children, active } = self.nodes.get(&node)? else {
-            return None;
-        };
-        let windows: Option<Vec<_>> = children
-            .iter()
-            .map(|id| match self.nodes.get(id) {
-                Some(Node::Window(window)) => Some(*window),
-                _ => None,
-            })
-            .collect();
-        let windows = windows?;
-        Some(TabGroup {
-            active: *windows.get(*active)?,
-            windows,
-        })
-    }
-
-    pub fn tab_group(&self, window: WindowId) -> Option<TabGroup> {
-        self.group_at(*self.parents.get(self.windows.get(&window)?)?)
-    }
-
-    pub fn tab_groups(&self) -> Vec<TabGroup> {
-        let mut groups: Vec<_> = self
-            .nodes
-            .keys()
-            .filter_map(|id| self.group_at(*id))
-            .collect();
-        groups.sort_by_key(|group| group.windows[0].0);
-        groups
-    }
-
-    pub fn adjacent_tab(&self, window: WindowId, previous: bool) -> Option<WindowId> {
-        let group = self.tab_group(window)?;
-        let index = group.windows.iter().position(|id| *id == window)?;
-        let step = if previous { group.windows.len() - 1 } else { 1 };
-        Some(group.windows[(index + step) % group.windows.len()])
-    }
-
-    /// Leave the group in place and split the departing window to its right.
-    pub fn leave_tab_group(&mut self, window: WindowId) -> Result<bool, LayoutError> {
-        if !self.contains(window) {
-            return Err(LayoutError::UnknownWindow(window));
-        }
-        let Some(group) = self.tab_group(window) else {
-            return Ok(false);
-        };
-        let target = group
-            .windows
-            .into_iter()
-            .find(|id| *id != window)
-            .expect("group has at least two tabs");
-        self.remove(window)?;
-        self.insert(window, Some(target), Axis::Horizontal, 0.5)?;
-        Ok(true)
-    }
-
-    pub fn activate_window(&mut self, window: WindowId) -> Result<(), LayoutError> {
-        let mut child = self
-            .windows
-            .get(&window)
-            .copied()
-            .ok_or(LayoutError::UnknownWindow(window))?;
-
-        while let Some(parent) = self.parents.get(&child).copied() {
-            if let Some(Node::Stack { children, active }) = self.nodes.get_mut(&parent) {
-                *active = children
-                    .iter()
-                    .position(|candidate| *candidate == child)
-                    .ok_or(LayoutError::InvalidTree("stack does not contain child"))?;
-            }
-
-            child = parent;
-        }
-
-        debug_assert!(self.validate().is_ok());
-        Ok(())
-    }
-
-    pub fn geometry(&self, bounds: Rect) -> Result<HashMap<WindowId, Rect>, LayoutError> {
-        let mut geometry = HashMap::new();
-
-        if let Some(root) = self.root {
-            self.layout_node(root, bounds, &mut geometry)?;
-        }
-
-        Ok(geometry)
-    }
-
-    pub fn geometry_with_gaps(
-        &self,
-        bounds: Rect,
-        gaps: GapConfig,
-    ) -> Result<HashMap<WindowId, Rect>, LayoutError> {
-        let mut geometry = self.geometry(bounds)?;
-        apply_gaps(&mut geometry, bounds, gaps);
-
-        Ok(geometry)
-    }
-
-    pub fn geometry_with_constraints(
-        &self,
-        bounds: Rect,
-        gaps: GapConfig,
-        constraints: &HashMap<WindowId, SizeConstraints>,
-        focused: Option<WindowId>,
-    ) -> Result<LayoutResult, LayoutError> {
-        let mut result = LayoutResult::default();
-
-        if let Some(root) = self.root {
-            self.layout_node_constrained(root, bounds, constraints, focused, &mut result.geometry)?;
-        }
-
-        apply_gaps(&mut result.geometry, bounds, gaps);
-
-        for (window, rect) in &mut result.geometry {
-            let constraint = constraints.get(window).copied().unwrap_or_default();
-            let constraint = normalized_constraints(constraint);
-
-            record_minimum_warnings(*window, *rect, constraint, &mut result.warnings);
-
-            if let Some(maximum) = constraint.max_width
-                && rect.width > maximum
-            {
-                result.warnings.push(ConstraintWarning {
-                    window: *window,
-                    kind: ConstraintKind::MaximumWidth,
-                    requested: maximum,
-                    assigned: rect.width,
-                });
-                rect.width = maximum;
-            }
-            if let Some(maximum) = constraint.max_height
-                && rect.height > maximum
-            {
-                result.warnings.push(ConstraintWarning {
-                    window: *window,
-                    kind: ConstraintKind::MaximumHeight,
-                    requested: maximum,
-                    assigned: rect.height,
-                });
-                rect.height = maximum;
-            }
-        }
-
-        result.warnings.sort_by_key(|warning| {
-            let kind = match warning.kind {
-                ConstraintKind::MinimumWidth => 0,
-                ConstraintKind::MinimumHeight => 1,
-                ConstraintKind::MaximumWidth => 2,
-                ConstraintKind::MaximumHeight => 3,
-            };
-            (warning.window.0, kind)
-        });
-
-        Ok(result)
-    }
-
-    pub fn automatic_axis(
-        &self,
-        focused: Option<WindowId>,
-        bounds: Rect,
-    ) -> Result<Axis, LayoutError> {
-        let Some(root) = self.root else {
-            return Ok(Axis::Horizontal);
-        };
-        let target = match focused {
-            Some(window) => window,
-            None => match self.nodes.get(&self.first_window(root)?) {
-                Some(Node::Window(window)) => *window,
-                _ => return Err(LayoutError::InvalidTree("leaf is not a window")),
-            },
-        };
-        let rect = self
-            .geometry(bounds)?
-            .remove(&target)
-            .ok_or(LayoutError::UnknownWindow(target))?;
-
-        Ok(if rect.width > rect.height {
-            Axis::Horizontal
-        } else {
-            Axis::Vertical
-        })
-    }
-
-    pub fn directional_neighbor(
-        &self,
-        window: WindowId,
-        direction: Direction,
-        bounds: Rect,
-    ) -> Result<Option<WindowId>, LayoutError> {
-        let geometry = self.geometry(bounds)?;
-        let target = geometry
-            .get(&window)
-            .copied()
-            .ok_or(LayoutError::UnknownWindow(window))?;
-        let (target_x, target_y) = target.center();
-
-        Ok(geometry
-            .into_iter()
-            .filter(|(candidate, _)| *candidate != window)
-            .filter_map(|(candidate, rect)| {
-                let (candidate_x, candidate_y) = rect.center();
-                let (primary, secondary, aligned) = match direction {
-                    Direction::Left if candidate_x < target_x => (
-                        target_x - candidate_x,
-                        (target_y - candidate_y).abs(),
-                        intervals_overlap(target.y, target.height, rect.y, rect.height),
-                    ),
-                    Direction::Right if candidate_x > target_x => (
-                        candidate_x - target_x,
-                        (target_y - candidate_y).abs(),
-                        intervals_overlap(target.y, target.height, rect.y, rect.height),
-                    ),
-                    Direction::Up if candidate_y < target_y => (
-                        target_y - candidate_y,
-                        (target_x - candidate_x).abs(),
-                        intervals_overlap(target.x, target.width, rect.x, rect.width),
-                    ),
-                    Direction::Down if candidate_y > target_y => (
-                        candidate_y - target_y,
-                        (target_x - candidate_x).abs(),
-                        intervals_overlap(target.x, target.width, rect.x, rect.width),
-                    ),
-                    _ => return None,
-                };
-
-                Some((candidate, primary, secondary, aligned))
-            })
-            .min_by(|left, right| {
-                right
-                    .3
-                    .cmp(&left.3)
-                    .then_with(|| left.1.total_cmp(&right.1))
-                    .then_with(|| left.2.total_cmp(&right.2))
-                    .then_with(|| left.0.0.cmp(&right.0.0))
-            })
-            .map(|(candidate, _, _, _)| candidate))
-    }
-
-    pub fn move_window(
-        &mut self,
-        window: WindowId,
-        direction: Direction,
-        bounds: Rect,
-    ) -> Result<bool, LayoutError> {
-        let Some(neighbor) = self.directional_neighbor(window, direction, bounds)? else {
-            return Ok(false);
-        };
-        let window_node = self
-            .windows
-            .get(&window)
-            .copied()
-            .ok_or(LayoutError::UnknownWindow(window))?;
-        let neighbor_node = self
-            .windows
-            .get(&neighbor)
-            .copied()
-            .ok_or(LayoutError::UnknownWindow(neighbor))?;
-
-        self.nodes.insert(window_node, Node::Window(neighbor));
-        self.nodes.insert(neighbor_node, Node::Window(window));
-        self.windows.insert(window, neighbor_node);
-        self.windows.insert(neighbor, window_node);
-
-        debug_assert!(self.validate().is_ok());
-        Ok(true)
-    }
-
-    pub fn resize_window(
-        &mut self,
-        window: WindowId,
-        direction: Direction,
-        amount: f64,
-    ) -> Result<bool, LayoutError> {
-        let mut child = self
-            .windows
-            .get(&window)
-            .copied()
-            .ok_or(LayoutError::UnknownWindow(window))?;
-        let amount = valid_resize_amount(amount);
-
-        if amount == 0.0 {
-            return Ok(false);
-        }
-
-        while let Some(parent) = self.parents.get(&child).copied() {
-            let adjustment = match self.nodes.get(&parent) {
-                Some(Node::Split {
-                    axis: Axis::Horizontal,
-                    first,
-                    ..
-                }) if direction == Direction::Right && *first == child => Some(amount),
-                Some(Node::Split {
-                    axis: Axis::Horizontal,
-                    second,
-                    ..
-                }) if direction == Direction::Left && *second == child => Some(-amount),
-                Some(Node::Split {
-                    axis: Axis::Vertical,
-                    first,
-                    ..
-                }) if direction == Direction::Down && *first == child => Some(amount),
-                Some(Node::Split {
-                    axis: Axis::Vertical,
-                    second,
-                    ..
-                }) if direction == Direction::Up && *second == child => Some(-amount),
-                Some(Node::Split { .. } | Node::Stack { .. }) => None,
-                Some(Node::Window(_)) => {
-                    return Err(LayoutError::InvalidTree("window cannot be a parent"));
-                }
-                None => return Err(LayoutError::InvalidTree("parent node is missing")),
-            };
-
-            if let Some(adjustment) = adjustment {
-                let Some(Node::Split { ratio, .. }) = self.nodes.get_mut(&parent) else {
-                    return Err(LayoutError::InvalidTree("resize target is not a split"));
-                };
-                let resized = normalized_ratio(*ratio + adjustment);
-                let changed = resized != *ratio;
-                *ratio = resized;
-
-                debug_assert!(self.validate().is_ok());
-                return Ok(changed);
-            }
-
-            child = parent;
-        }
-
-        Ok(false)
-    }
-
-    pub fn validate(&self) -> Result<(), LayoutError> {
-        let Some(root) = self.root else {
-            return if self.nodes.is_empty() && self.parents.is_empty() && self.windows.is_empty() {
-                Ok(())
-            } else {
-                Err(LayoutError::InvalidTree("empty root retains nodes"))
-            };
-        };
-        if self.parents.contains_key(&root) {
-            return Err(LayoutError::InvalidTree("root has a parent"));
-        }
-
-        let mut visited = HashSet::new();
-        self.validate_node(root, None, &mut visited)?;
-
-        if visited.len() != self.nodes.len() {
-            return Err(LayoutError::InvalidTree("tree contains unreachable nodes"));
-        }
-        if self.windows.len()
-            != self
-                .nodes
-                .values()
-                .filter(|node| matches!(node, Node::Window(_)))
-                .count()
-        {
-            return Err(LayoutError::InvalidTree("window index is inconsistent"));
-        }
-
-        Ok(())
-    }
-
-    fn insert_node(&mut self, node: Node) -> NodeId {
-        let id = NodeId(self.next_node);
-        self.next_node += 1;
-        self.nodes.insert(id, node);
-        id
-    }
-
-    fn collect_window_positions(
-        &self,
-        node: NodeId,
-        bounds: Rect,
-        windows: &mut Vec<(WindowId, Rect)>,
-    ) -> Result<(), LayoutError> {
-        match self.nodes.get(&node) {
-            Some(Node::Window(window)) => windows.push((*window, bounds)),
-            Some(Node::Split {
-                axis,
-                ratio,
-                first,
-                second,
-            }) => {
-                let (first_bounds, second_bounds) = split_rect(bounds, *axis, *ratio);
-                self.collect_window_positions(*first, first_bounds, windows)?;
-                self.collect_window_positions(*second, second_bounds, windows)?;
-            }
-            Some(Node::Stack { children, .. }) => {
-                for child in children {
-                    self.collect_window_positions(*child, bounds, windows)?;
-                }
-            }
-            None => return Err(LayoutError::InvalidTree("node is missing")),
-        }
-        Ok(())
-    }
-
-    fn first_window(&self, node: NodeId) -> Result<NodeId, LayoutError> {
-        match self.nodes.get(&node) {
-            Some(Node::Window(_)) => Ok(node),
-            Some(Node::Split { first, .. }) => self.first_window(*first),
-            Some(Node::Stack {
-                children, active, ..
-            }) => children
-                .get(*active)
-                .copied()
-                .ok_or(LayoutError::InvalidTree("stack active index is invalid"))
-                .and_then(|child| self.first_window(child)),
-            None => Err(LayoutError::InvalidTree("node is missing")),
-        }
-    }
-
-    fn replace_child(
-        &mut self,
-        parent: NodeId,
-        old: NodeId,
-        new: NodeId,
-    ) -> Result<(), LayoutError> {
-        match self.nodes.get_mut(&parent) {
-            Some(Node::Split { first, .. }) if *first == old => *first = new,
-            Some(Node::Split { second, .. }) if *second == old => *second = new,
-            Some(Node::Stack { children, .. }) => {
-                let child = children
-                    .iter_mut()
-                    .find(|child| **child == old)
-                    .ok_or(LayoutError::InvalidTree("parent does not contain child"))?;
-                *child = new;
-            }
-            _ => return Err(LayoutError::InvalidTree("parent does not contain child")),
-        }
-
-        Ok(())
-    }
-
-    fn collapse_parent(
-        &mut self,
-        parent: NodeId,
-        leaf: NodeId,
-        sibling: NodeId,
-    ) -> Result<(), LayoutError> {
-        let window = match self.nodes.get(&leaf) {
-            Some(Node::Window(window)) => *window,
-            _ => return Err(LayoutError::InvalidTree("removed leaf is not a window")),
-        };
-        let grandparent = self.parents.get(&parent).copied();
-
-        self.windows.remove(&window);
-        self.parents.remove(&leaf);
-        self.parents.remove(&parent);
-        self.nodes.remove(&leaf);
-        self.nodes.remove(&parent);
-
-        if let Some(grandparent) = grandparent {
-            self.replace_child(grandparent, parent, sibling)?;
-            self.parents.insert(sibling, grandparent);
-        } else {
-            self.parents.remove(&sibling);
-            self.root = Some(sibling);
-        }
-
-        Ok(())
-    }
-
-    fn layout_node(
-        &self,
-        node: NodeId,
-        bounds: Rect,
-        geometry: &mut HashMap<WindowId, Rect>,
-    ) -> Result<(), LayoutError> {
-        match self.nodes.get(&node) {
-            Some(Node::Window(window)) => {
-                geometry.insert(*window, bounds);
-            }
-            Some(Node::Split {
-                axis,
-                ratio,
-                first,
-                second,
-            }) => {
-                let (first_bounds, second_bounds) = split_rect(bounds, *axis, *ratio);
-                self.layout_node(*first, first_bounds, geometry)?;
-                self.layout_node(*second, second_bounds, geometry)?;
-            }
-            Some(Node::Stack { children, active }) => {
-                let child = children
-                    .get(*active)
-                    .ok_or(LayoutError::InvalidTree("stack active index is invalid"))?;
-                self.layout_node(*child, bounds, geometry)?;
-            }
-            None => return Err(LayoutError::InvalidTree("node is missing")),
-        }
-
-        Ok(())
-    }
-
-    fn layout_node_constrained(
-        &self,
-        node: NodeId,
-        bounds: Rect,
-        constraints: &HashMap<WindowId, SizeConstraints>,
-        focused: Option<WindowId>,
-        geometry: &mut HashMap<WindowId, Rect>,
-    ) -> Result<(), LayoutError> {
-        match self.nodes.get(&node) {
-            Some(Node::Window(window)) => {
-                geometry.insert(*window, bounds);
-            }
-            Some(Node::Split {
-                axis,
-                ratio,
-                first,
-                second,
-            }) => {
-                let first_minimum = self.minimum_size(*first, constraints)?;
-                let second_minimum = self.minimum_size(*second, constraints)?;
-                let available = match axis {
-                    Axis::Horizontal => bounds.width,
-                    Axis::Vertical => bounds.height,
-                }
-                .max(0.0);
-                let first_required = match axis {
-                    Axis::Horizontal => first_minimum.0,
-                    Axis::Vertical => first_minimum.1,
-                };
-                let second_required = match axis {
-                    Axis::Horizontal => second_minimum.0,
-                    Axis::Vertical => second_minimum.1,
-                };
-                let desired = available * ratio;
-                let first_extent = if first_required + second_required <= available {
-                    desired.clamp(first_required, available - second_required)
-                } else if focused.is_some_and(|window| self.contains_window(*first, window)) {
-                    first_required.min(available)
-                } else {
-                    (available - second_required).max(0.0)
-                };
-                let adjusted_ratio = if available > 0.0 {
-                    first_extent / available
-                } else {
-                    0.5
-                };
-                let (first_bounds, second_bounds) = split_rect(bounds, *axis, adjusted_ratio);
-
-                self.layout_node_constrained(*first, first_bounds, constraints, focused, geometry)?;
-                self.layout_node_constrained(
-                    *second,
-                    second_bounds,
-                    constraints,
-                    focused,
-                    geometry,
-                )?;
-            }
-            Some(Node::Stack { children, active }) => {
-                let child = children
-                    .get(*active)
-                    .ok_or(LayoutError::InvalidTree("stack active index is invalid"))?;
-                self.layout_node_constrained(*child, bounds, constraints, focused, geometry)?;
-            }
-            None => return Err(LayoutError::InvalidTree("node is missing")),
-        }
-
-        Ok(())
-    }
-
-    fn minimum_size(
-        &self,
-        node: NodeId,
-        constraints: &HashMap<WindowId, SizeConstraints>,
-    ) -> Result<(f64, f64), LayoutError> {
-        match self.nodes.get(&node) {
-            Some(Node::Window(window)) => {
-                let constraint = constraints.get(window).copied().unwrap_or_default();
-                let constraint = normalized_constraints(constraint);
-                Ok((constraint.min_width, constraint.min_height))
-            }
-            Some(Node::Split {
-                axis,
-                first,
-                second,
-                ..
-            }) => {
-                let first = self.minimum_size(*first, constraints)?;
-                let second = self.minimum_size(*second, constraints)?;
-
-                Ok(match axis {
-                    Axis::Horizontal => (first.0 + second.0, first.1.max(second.1)),
-                    Axis::Vertical => (first.0.max(second.0), first.1 + second.1),
-                })
-            }
-            Some(Node::Stack { children, .. }) => {
-                let mut minimum = (1.0_f64, 1.0_f64);
-
-                for child in children {
-                    let child = self.minimum_size(*child, constraints)?;
-                    minimum.0 = minimum.0.max(child.0);
-                    minimum.1 = minimum.1.max(child.1);
-                }
-
-                Ok(minimum)
-            }
-            None => Err(LayoutError::InvalidTree("node is missing")),
-        }
-    }
-
-    fn contains_window(&self, node: NodeId, window: WindowId) -> bool {
-        match self.nodes.get(&node) {
-            Some(Node::Window(candidate)) => *candidate == window,
-            Some(Node::Split { first, second, .. }) => {
-                self.contains_window(*first, window) || self.contains_window(*second, window)
-            }
-            Some(Node::Stack { children, .. }) => children
-                .iter()
-                .any(|child| self.contains_window(*child, window)),
-            None => false,
-        }
-    }
-
-    fn validate_node(
-        &self,
-        node: NodeId,
-        expected_parent: Option<NodeId>,
-        visited: &mut HashSet<NodeId>,
-    ) -> Result<(), LayoutError> {
-        if !visited.insert(node) {
-            return Err(LayoutError::InvalidTree("tree contains a cycle"));
-        }
-        if self.parents.get(&node).copied() != expected_parent {
-            return Err(LayoutError::InvalidTree("parent index is inconsistent"));
-        }
-
-        match self.nodes.get(&node) {
-            Some(Node::Window(window)) => {
-                if self.windows.get(window) != Some(&node) {
-                    return Err(LayoutError::InvalidTree("window index is inconsistent"));
-                }
-            }
-            Some(Node::Split {
-                ratio,
-                first,
-                second,
-                ..
-            }) => {
-                if first == second
-                    || !ratio.is_finite()
-                    || !(MIN_SPLIT_RATIO..=MAX_SPLIT_RATIO).contains(ratio)
-                {
-                    return Err(LayoutError::InvalidTree("split is invalid"));
-                }
-
-                self.validate_node(*first, Some(node), visited)?;
-                self.validate_node(*second, Some(node), visited)?;
-            }
-            Some(Node::Stack { children, active }) => {
-                if children.len() < 2 || *active >= children.len() {
-                    return Err(LayoutError::InvalidTree("stack is invalid"));
-                }
-
-                for child in children {
-                    self.validate_node(*child, Some(node), visited)?;
-                }
-            }
-            None => return Err(LayoutError::InvalidTree("node is missing")),
-        }
-
-        Ok(())
-    }
-}
-
-fn normalized_ratio(ratio: f64) -> f64 {
-    if ratio.is_finite() {
-        ratio.clamp(MIN_SPLIT_RATIO, MAX_SPLIT_RATIO)
-    } else {
-        0.5
-    }
-}
-
-fn valid_gap(gap: f64) -> f64 {
-    if gap.is_finite() { gap.max(0.0) } else { 0.0 }
-}
-
-fn valid_resize_amount(amount: f64) -> f64 {
-    if amount.is_finite() {
-        amount.abs()
-    } else {
-        0.0
-    }
-}
-
-fn normalized_constraints(constraints: SizeConstraints) -> SizeConstraints {
-    let min_width = finite_positive(constraints.min_width).unwrap_or(1.0);
-    let min_height = finite_positive(constraints.min_height).unwrap_or(1.0);
-    let max_width = constraints
-        .max_width
-        .and_then(finite_positive)
-        .map(|maximum| maximum.max(min_width));
-    let max_height = constraints
-        .max_height
-        .and_then(finite_positive)
-        .map(|maximum| maximum.max(min_height));
-
-    SizeConstraints {
-        min_width,
-        min_height,
-        max_width,
-        max_height,
-    }
-}
-
-fn finite_positive(value: f64) -> Option<f64> {
-    (value.is_finite() && value > 0.0).then_some(value)
-}
-
-fn record_minimum_warnings(
-    window: WindowId,
-    rect: Rect,
-    constraints: SizeConstraints,
-    warnings: &mut Vec<ConstraintWarning>,
-) {
-    if rect.width < constraints.min_width {
-        warnings.push(ConstraintWarning {
-            window,
-            kind: ConstraintKind::MinimumWidth,
-            requested: constraints.min_width,
-            assigned: rect.width,
-        });
-    }
-    if rect.height < constraints.min_height {
-        warnings.push(ConstraintWarning {
-            window,
-            kind: ConstraintKind::MinimumHeight,
-            requested: constraints.min_height,
-            assigned: rect.height,
-        });
-    }
-}
-
-fn apply_gaps(geometry: &mut HashMap<WindowId, Rect>, bounds: Rect, gaps: GapConfig) {
-    let outer = if gaps.smart && geometry.len() == 1 {
-        0.0
-    } else {
-        valid_gap(gaps.outer)
-    };
-    let half_inner = valid_gap(gaps.inner) / 2.0;
-    let right = bounds.x + bounds.width;
-    let bottom = bounds.y + bounds.height;
-
-    for rect in geometry.values_mut() {
-        let left_inset = if nearly_equal(rect.x, bounds.x) {
-            outer
-        } else {
-            half_inner
-        };
-        let top_inset = if nearly_equal(rect.y, bounds.y) {
-            outer
-        } else {
-            half_inner
-        };
-        let right_inset = if nearly_equal(rect.x + rect.width, right) {
-            outer
-        } else {
-            half_inner
-        };
-        let bottom_inset = if nearly_equal(rect.y + rect.height, bottom) {
-            outer
-        } else {
-            half_inner
-        };
-
-        rect.x += left_inset;
-        rect.y += top_inset;
-        rect.width = (rect.width - left_inset - right_inset).max(1.0);
-        rect.height = (rect.height - top_inset - bottom_inset).max(1.0);
-    }
-}
-
-fn nearly_equal(left: f64, right: f64) -> bool {
-    (left - right).abs() < f64::EPSILON * left.abs().max(right.abs()).max(1.0)
-}
-
-fn intervals_overlap(
-    first_start: f64,
-    first_size: f64,
-    second_start: f64,
-    second_size: f64,
-) -> bool {
-    first_start < second_start + second_size && second_start < first_start + first_size
-}
-
-fn split_rect(bounds: Rect, axis: Axis, ratio: f64) -> (Rect, Rect) {
-    match axis {
-        Axis::Horizontal => {
-            let boundary = bounds.x + bounds.width * ratio;
-            let first = Rect::new(bounds.x, bounds.y, boundary - bounds.x, bounds.height);
-            let second = Rect::new(
-                boundary,
-                bounds.y,
-                bounds.x + bounds.width - boundary,
-                bounds.height,
-            );
-
-            (first, second)
-        }
-        Axis::Vertical => {
-            let boundary = bounds.y + bounds.height * ratio;
-            let first = Rect::new(bounds.x, bounds.y, bounds.width, boundary - bounds.y);
-            let second = Rect::new(
-                bounds.x,
-                boundary,
-                bounds.width,
-                bounds.y + bounds.height - boundary,
-            );
-
-            (first, second)
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn insertion_splits_the_focused_leaf() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Vertical, 0.5)
-            .unwrap();
-
-        assert!(tree.validate().is_ok());
-        assert_eq!(
-            tree.geometry(Rect::new(0.0, 0.0, 100.0, 80.0))
-                .unwrap()
-                .len(),
-            3
-        );
-    }
-
-    #[test]
-    fn removal_collapses_the_parent_split() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.remove(WindowId(1)).unwrap();
-
-        assert!(tree.validate().is_ok());
-        assert_eq!(
-            tree.node(tree.root().unwrap()),
-            Some(&Node::Window(WindowId(2)))
-        );
-    }
-
-    #[test]
-    fn shared_split_boundary_is_exact() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 1.0 / 3.0)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 1.0 / 3.0)
-            .unwrap();
-
-        let geometry = tree.geometry(Rect::new(0.0, 0.0, 101.0, 80.0)).unwrap();
-        let first = geometry[&WindowId(1)];
-        let second = geometry[&WindowId(2)];
-
-        assert_eq!(first.x + first.width, second.x);
-        assert_eq!(second.x + second.width, 101.0);
-    }
-
-    #[test]
-    fn rejects_duplicate_and_unknown_windows() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-
-        assert_eq!(
-            tree.insert(WindowId(1), None, Axis::Horizontal, 0.5),
-            Err(LayoutError::DuplicateWindow(WindowId(1)))
-        );
-        assert_eq!(
-            tree.insert(WindowId(2), Some(WindowId(9)), Axis::Horizontal, 0.5,),
-            Err(LayoutError::UnknownWindow(WindowId(9)))
-        );
-    }
-
-    #[test]
-    fn non_finite_ratio_uses_balanced_split() {
-        assert_eq!(normalized_ratio(f64::NAN), 0.5);
-        assert_eq!(normalized_ratio(f64::INFINITY), 0.5);
-    }
-
-    #[test]
-    fn automatic_axis_follows_focused_tile_shape() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-
-        let wide = Rect::new(0.0, 0.0, 1_920.0, 1_080.0);
-        assert_eq!(
-            tree.automatic_axis(Some(WindowId(1)), wide).unwrap(),
-            Axis::Horizontal
-        );
-
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        assert_eq!(
-            tree.automatic_axis(Some(WindowId(1)), wide).unwrap(),
-            Axis::Vertical
-        );
-    }
-
-    #[test]
-    fn gaps_preserve_outer_and_shared_spacing() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-
-        let geometry = tree
-            .geometry_with_gaps(Rect::new(0.0, 0.0, 100.0, 80.0), GapConfig::default())
-            .unwrap();
-        let first = geometry[&WindowId(1)];
-        let second = geometry[&WindowId(2)];
-
-        assert_eq!(first.x, 4.0);
-        assert_eq!(second.x + second.width, 96.0);
-        assert_eq!(second.x - (first.x + first.width), 10.0);
-    }
-
-    #[test]
-    fn smart_gaps_remove_outer_gap_for_one_window() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-
-        let bounds = Rect::new(0.0, 0.0, 100.0, 80.0);
-        let geometry = tree
-            .geometry_with_gaps(
-                bounds,
-                GapConfig {
-                    smart: true,
-                    ..GapConfig::default()
-                },
-            )
-            .unwrap();
-
-        assert_eq!(geometry[&WindowId(1)], bounds);
-    }
-
-    #[test]
-    fn default_gaps_keep_outer_spacing_for_one_window() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-
-        let geometry = tree
-            .geometry_with_gaps(Rect::new(0.0, 0.0, 100.0, 80.0), GapConfig::default())
-            .unwrap();
-
-        assert_eq!(geometry[&WindowId(1)], Rect::new(4.0, 4.0, 92.0, 72.0));
-    }
-
-    #[test]
-    fn directional_neighbor_prefers_primary_distance() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(3), Some(WindowId(2)), Axis::Vertical, 0.5)
-            .unwrap();
-
-        let bounds = Rect::new(0.0, 0.0, 100.0, 100.0);
-        assert_eq!(
-            tree.directional_neighbor(WindowId(1), Direction::Right, bounds)
-                .unwrap(),
-            Some(WindowId(2))
-        );
-        assert_eq!(
-            tree.directional_neighbor(WindowId(2), Direction::Down, bounds)
-                .unwrap(),
-            Some(WindowId(3))
-        );
-        assert_eq!(
-            tree.directional_neighbor(WindowId(1), Direction::Left, bounds)
-                .unwrap(),
-            None
-        );
-    }
-
-    #[test]
-    fn directional_move_swaps_window_leaves() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        let bounds = Rect::new(0.0, 0.0, 100.0, 80.0);
-
-        assert!(
-            tree.move_window(WindowId(1), Direction::Right, bounds)
-                .unwrap()
-        );
-
-        let geometry = tree.geometry(bounds).unwrap();
-        assert_eq!(geometry[&WindowId(2)].x, 0.0);
-        assert_eq!(geometry[&WindowId(1)].x, 50.0);
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn directional_move_at_boundary_is_a_noop() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-
-        assert!(
-            !tree
-                .move_window(
-                    WindowId(1),
-                    Direction::Left,
-                    Rect::new(0.0, 0.0, 100.0, 80.0),
-                )
-                .unwrap()
-        );
-    }
-
-    #[test]
-    fn directional_resize_changes_the_nearest_matching_split() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        let bounds = Rect::new(0.0, 0.0, 100.0, 100.0);
-
-        assert!(
-            tree.resize_window(WindowId(1), Direction::Right, 0.1)
-                .unwrap()
-        );
-
-        let geometry = tree.geometry(bounds).unwrap();
-        assert_eq!(geometry[&WindowId(1)].width, 30.0);
-        assert_eq!(geometry[&WindowId(3)].x, 30.0);
-        assert_eq!(geometry[&WindowId(2)].x, 50.0);
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn directional_resize_walks_to_an_ancestor_and_clamps() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Vertical, 0.5)
-            .unwrap();
-        let bounds = Rect::new(0.0, 0.0, 100.0, 100.0);
-
-        assert!(
-            tree.resize_window(WindowId(3), Direction::Right, 1.0)
-                .unwrap()
-        );
-        assert!(
-            !tree
-                .resize_window(WindowId(3), Direction::Right, 1.0)
-                .unwrap()
-        );
-
-        let geometry = tree.geometry(bounds).unwrap();
-        assert_eq!(geometry[&WindowId(2)].x, 95.0);
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn directional_resize_at_an_outer_edge_is_a_noop() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-
-        assert!(
-            !tree
-                .resize_window(WindowId(1), Direction::Left, 0.05)
-                .unwrap()
-        );
-        assert!(
-            !tree
-                .resize_window(WindowId(1), Direction::Right, f64::NAN)
-                .unwrap()
-        );
-    }
-
-    #[test]
-    fn stacking_windows_shows_only_the_active_child() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.stack_window(WindowId(2), WindowId(1)).unwrap();
-
-        let geometry = tree.geometry(Rect::new(0.0, 0.0, 100.0, 80.0)).unwrap();
-        assert_eq!(geometry.len(), 1);
-        assert_eq!(geometry[&WindowId(2)], Rect::new(0.0, 0.0, 100.0, 80.0));
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn structural_reading_order_includes_all_stack_members_independently_of_activation() {
-        let mut tree = LayoutTree::default();
-        let ids = [WindowId(30), WindowId(10), WindowId(20), WindowId(5)];
-        tree.insert(ids[0], None, Axis::Horizontal, 0.5).unwrap();
-        for pair in ids.windows(2) {
-            tree.insert(pair[1], Some(pair[0]), Axis::Horizontal, 0.5)
-                .unwrap();
-            tree.stack_window(pair[1], pair[0]).unwrap();
-        }
-        let bounds = Rect::new(0.0, 0.0, 1_000.0, 800.0);
-        for active in ids {
-            tree.activate_window(active).unwrap();
-            assert_eq!(
-                tree.geometry(bounds)
-                    .unwrap()
-                    .keys()
-                    .copied()
-                    .collect::<Vec<_>>(),
-                vec![active]
-            );
-            assert_eq!(tree.window_ids_in_reading_order(bounds).unwrap(), ids);
-            assert_eq!(tree.preferred_window(), Some(active));
-            assert!(tree.validate().is_ok());
-        }
-    }
-
-    #[test]
-    fn flat_stack_reading_order_preserves_every_inactive_member() {
-        let mut tree = LayoutTree::default();
-        let ids = [WindowId(900), WindowId(7), WindowId(400), WindowId(10)];
-        let children = ids
-            .iter()
-            .map(|window| {
-                let leaf = tree.insert_node(Node::Window(*window));
-                tree.windows.insert(*window, leaf);
-                leaf
-            })
-            .collect::<Vec<_>>();
-        let root = tree.insert_node(Node::Stack {
-            children: children.clone(),
-            active: 2,
-        });
-        for child in children {
-            tree.parents.insert(child, root);
-        }
-        tree.root = Some(root);
-        let bounds = Rect::new(0.0, 0.0, 1_000.0, 800.0);
-        assert!(tree.validate().is_ok());
-        assert_eq!(tree.geometry(bounds).unwrap().len(), 1);
-        assert_eq!(tree.preferred_window(), Some(ids[2]));
-        assert_eq!(tree.window_ids_in_reading_order(bounds).unwrap(), ids);
-    }
-
-    #[test]
-    fn structural_reading_order_retains_xy_order_through_splits_and_stacks() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(40), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(10), Some(WindowId(40)), Axis::Vertical, 0.5)
-            .unwrap();
-        tree.insert(WindowId(30), Some(WindowId(40)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(20), Some(WindowId(40)), Axis::Vertical, 0.5)
-            .unwrap();
-        tree.stack_window(WindowId(20), WindowId(40)).unwrap();
-        tree.insert(WindowId(50), Some(WindowId(10)), Axis::Horizontal, 0.5)
-            .unwrap();
-        let bounds = Rect::new(25.0, 40.0, 1_000.0, 800.0);
-        let expected = [40, 20, 10, 30, 50].map(WindowId);
-        assert_eq!(tree.window_ids_in_reading_order(bounds).unwrap(), expected);
-        assert_eq!(tree.geometry(bounds).unwrap().len(), 4);
-        let collapsed = tree.window_ids_in_reading_order(Rect::default()).unwrap();
-        assert_eq!(collapsed.len(), expected.len());
-        assert_eq!(
-            collapsed.into_iter().collect::<HashSet<_>>(),
-            expected.into_iter().collect()
-        );
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn tree_preference_follows_first_split_branch_and_active_stack_children() {
-        let mut tree = LayoutTree::default();
-        assert_eq!(tree.preferred_window(), None);
-        assert!(
-            tree.window_ids_in_reading_order(Rect::default())
-                .unwrap()
-                .is_empty()
-        );
-        tree.insert(WindowId(30), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(10), Some(WindowId(30)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(20), Some(WindowId(30)), Axis::Vertical, 0.5)
-            .unwrap();
-        tree.stack_window(WindowId(20), WindowId(30)).unwrap();
-        assert_eq!(tree.preferred_window(), Some(WindowId(20)));
-        tree.activate_window(WindowId(30)).unwrap();
-        assert_eq!(tree.preferred_window(), Some(WindowId(30)));
-        tree.activate_window(WindowId(10)).unwrap();
-        assert_eq!(tree.preferred_window(), Some(WindowId(30)));
-    }
-
-    #[test]
-    fn activating_a_hidden_stack_child_changes_visible_geometry() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.stack_window(WindowId(2), WindowId(1)).unwrap();
-        tree.activate_window(WindowId(1)).unwrap();
-
-        let geometry = tree.geometry(Rect::new(0.0, 0.0, 100.0, 80.0)).unwrap();
-        assert_eq!(geometry.len(), 1);
-        assert_eq!(geometry[&WindowId(1)], Rect::new(0.0, 0.0, 100.0, 80.0));
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn removing_from_a_stack_collapses_or_preserves_cardinality() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.stack_window(WindowId(2), WindowId(1)).unwrap();
-        tree.insert(WindowId(3), Some(WindowId(2)), Axis::Vertical, 0.5)
-            .unwrap();
-
-        tree.remove(WindowId(3)).unwrap();
-        tree.remove(WindowId(2)).unwrap();
-
-        assert_eq!(
-            tree.node(tree.root().unwrap()),
-            Some(&Node::Window(WindowId(1)))
-        );
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn randomized_operation_sequences_preserve_tree_invariants() {
-        let mut tree = LayoutTree::default();
-        let mut windows = Vec::new();
-        let mut next_window = 1;
-        let mut random = 0x5eed_u64;
-        let bounds = Rect::new(0.0, 0.0, 1_920.0, 1_080.0);
-
-        for _ in 0..2_000 {
-            random = random
-                .wrapping_mul(6_364_136_223_846_793_005)
-                .wrapping_add(1);
-            let operation = random % 6;
-
-            match operation {
-                0 if windows.len() < 32 => {
-                    let window = WindowId(next_window);
-                    next_window += 1;
-                    let focused = choose_window(&windows, random.rotate_left(7));
-                    let axis = if random & 1 == 0 {
-                        Axis::Horizontal
-                    } else {
-                        Axis::Vertical
-                    };
-
-                    tree.insert(window, focused, axis, ratio_from_random(random))
-                        .unwrap();
-                    windows.push(window);
-                }
-                1 if !windows.is_empty() => {
-                    let index = random as usize % windows.len();
-                    let window = windows.swap_remove(index);
-                    tree.remove(window).unwrap();
-                }
-                2 if windows.len() >= 2 => {
-                    let first = random as usize % windows.len();
-                    let mut second = random.rotate_left(13) as usize % windows.len();
-                    if first == second {
-                        second = (second + 1) % windows.len();
-                    }
-
-                    tree.stack_window(windows[first], windows[second]).unwrap();
-                }
-                3 if !windows.is_empty() => {
-                    let window = windows[random as usize % windows.len()];
-                    tree.activate_window(window).unwrap();
-                }
-                4 if !windows.is_empty() => {
-                    let window = windows[random as usize % windows.len()];
-                    let _ = tree.move_window(window, random_direction(random), bounds);
-                }
-                5 if !windows.is_empty() => {
-                    let window = windows[random as usize % windows.len()];
-                    tree.resize_window(window, random_direction(random), 0.03)
-                        .unwrap();
-                }
-                _ => {}
-            }
-
-            assert!(tree.validate().is_ok());
-        }
-    }
-
-    #[test]
-    fn constraints_adjust_split_boundaries_when_space_is_available() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.2)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.2)
-            .unwrap();
-        let constraints = HashMap::from([
-            (
-                WindowId(1),
-                SizeConstraints {
-                    min_width: 40.0,
-                    ..SizeConstraints::default()
-                },
-            ),
-            (
-                WindowId(2),
-                SizeConstraints {
-                    min_width: 30.0,
-                    ..SizeConstraints::default()
-                },
-            ),
-        ]);
-        let result = tree
-            .geometry_with_constraints(
-                Rect::new(0.0, 0.0, 100.0, 80.0),
-                GapConfig {
-                    inner: 0.0,
-                    outer: 0.0,
-                    smart: false,
-                },
-                &constraints,
-                Some(WindowId(1)),
-            )
-            .unwrap();
-
-        assert_eq!(result.geometry[&WindowId(1)].width, 40.0);
-        assert_eq!(result.geometry[&WindowId(2)].width, 60.0);
-        assert!(result.warnings.is_empty());
-    }
-
-    #[test]
-    fn focused_window_wins_an_impossible_minimum_constraint_conflict() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.5)
-            .unwrap();
-        let constraints = HashMap::from([
-            (
-                WindowId(1),
-                SizeConstraints {
-                    min_width: 80.0,
-                    ..SizeConstraints::default()
-                },
-            ),
-            (
-                WindowId(2),
-                SizeConstraints {
-                    min_width: 80.0,
-                    ..SizeConstraints::default()
-                },
-            ),
-        ]);
-        let result = tree
-            .geometry_with_constraints(
-                Rect::new(0.0, 0.0, 100.0, 80.0),
-                GapConfig {
-                    inner: 0.0,
-                    outer: 0.0,
-                    smart: false,
-                },
-                &constraints,
-                Some(WindowId(1)),
-            )
-            .unwrap();
-
-        assert_eq!(result.geometry[&WindowId(1)].width, 80.0);
-        assert_eq!(result.geometry[&WindowId(2)].width, 20.0);
-        assert_eq!(result.warnings.len(), 1);
-        assert_eq!(result.warnings[0].window, WindowId(2));
-        assert_eq!(result.warnings[0].kind, ConstraintKind::MinimumWidth);
-    }
-
-    #[test]
-    fn maximum_constraints_clip_without_overlapping_neighbors() {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        let constraints = HashMap::from([(
-            WindowId(1),
-            SizeConstraints {
-                max_width: Some(60.0),
-                max_height: Some(40.0),
-                ..SizeConstraints::default()
-            },
-        )]);
-        let result = tree
-            .geometry_with_constraints(
-                Rect::new(0.0, 0.0, 100.0, 80.0),
-                GapConfig::default(),
-                &constraints,
-                Some(WindowId(1)),
-            )
-            .unwrap();
-
-        assert_eq!(
-            result.geometry[&WindowId(1)],
-            Rect::new(4.0, 4.0, 60.0, 40.0)
-        );
-        assert_eq!(result.warnings.len(), 2);
-    }
-
-    fn choose_window(windows: &[WindowId], random: u64) -> Option<WindowId> {
-        (!windows.is_empty()).then(|| windows[random as usize % windows.len()])
-    }
-
-    fn ratio_from_random(random: u64) -> f64 {
-        0.2 + (random.rotate_left(19) % 601) as f64 / 1_000.0
-    }
-
-    fn random_direction(random: u64) -> Direction {
-        match random.rotate_left(29) % 4 {
-            0 => Direction::Left,
-            1 => Direction::Right,
-            2 => Direction::Up,
-            _ => Direction::Down,
-        }
-    }
-}
-
-#[cfg(test)]
-mod tab_tests {
-    use super::*;
-
-    fn nested() -> LayoutTree {
-        let mut tree = LayoutTree::default();
-        tree.insert(WindowId(1), None, Axis::Horizontal, 0.5)
-            .unwrap();
-        tree.insert(WindowId(2), Some(WindowId(1)), Axis::Horizontal, 0.6)
-            .unwrap();
-        tree.insert(WindowId(3), Some(WindowId(1)), Axis::Vertical, 0.4)
-            .unwrap();
-        tree.insert(WindowId(4), Some(WindowId(3)), Axis::Horizontal, 0.5)
-            .unwrap();
-        tree
-    }
-
-    #[test]
-    fn joining_and_leaving_tabs_preserve_neighboring_splits() {
-        let mut tree = nested();
-        let bounds = Rect::new(0., 0., 1000., 800.);
-        let neighbor = tree.geometry(bounds).unwrap()[&WindowId(2)];
-        tree.stack_window(WindowId(4), WindowId(3)).unwrap();
-        tree.stack_window(WindowId(1), WindowId(3)).unwrap();
-        assert_eq!(
-            tree.tab_group(WindowId(1)).unwrap().windows,
-            [WindowId(3), WindowId(4), WindowId(1)]
-        );
-        assert_eq!(tree.geometry(bounds).unwrap()[&WindowId(2)], neighbor);
-        assert_eq!(tree.visible_window_count(), 2);
-        let before = tree.clone();
-        tree.stack_window(WindowId(1), WindowId(4)).unwrap();
-        assert_eq!(tree, before, "joining the same group must not reorder it");
-        assert_eq!(tree.adjacent_tab(WindowId(1), false), Some(WindowId(3)));
-        assert_eq!(tree.adjacent_tab(WindowId(3), true), Some(WindowId(1)));
-        assert!(tree.leave_tab_group(WindowId(1)).unwrap());
-        assert_eq!(tree.geometry(bounds).unwrap()[&WindowId(2)], neighbor);
-        assert_eq!(
-            tree.tab_group(WindowId(4)).unwrap().windows,
-            [WindowId(3), WindowId(4)]
-        );
-        assert!(tree.tab_group(WindowId(1)).is_none());
-        assert!(!tree.leave_tab_group(WindowId(1)).unwrap());
-        tree.remove(WindowId(4)).unwrap();
-        assert!(tree.tab_groups().is_empty());
-        assert!(tree.validate().is_ok());
-    }
-
-    #[test]
-    fn opening_beside_a_group_and_removing_active_tabs_keep_all_members_reachable() {
-        let mut tree = nested();
-        tree.stack_window(WindowId(4), WindowId(3)).unwrap();
-        tree.stack_window(WindowId(1), WindowId(3)).unwrap();
-        tree.insert(WindowId(5), Some(WindowId(1)), Axis::Vertical, 0.3)
-            .unwrap();
-        assert_eq!(tree.tab_groups().len(), 1);
-        let bounds = Rect::new(0., 0., 1000., 800.);
-        for id in [WindowId(3), WindowId(4), WindowId(1)] {
-            tree.activate_window(id).unwrap();
-            let geometry = tree.geometry(bounds).unwrap();
-            assert!(geometry.contains_key(&WindowId(5)));
-            assert!(geometry.contains_key(&id));
-            assert_eq!(geometry.len(), 3);
-        }
-        tree.remove(WindowId(1)).unwrap();
-        assert_eq!(tree.tab_group(WindowId(3)).unwrap().active, WindowId(4));
-        tree.remove(WindowId(3)).unwrap();
-        assert!(tree.tab_groups().is_empty());
-        assert!(tree.validate().is_ok());
-    }
-}
diff --git a/crates/ferese-layout/src/scrolling.rs b/crates/ferese-layout/src/scrolling.rs
index b5f66cc..160a37a 100644
--- a/crates/ferese-layout/src/scrolling.rs
+++ b/crates/ferese-layout/src/scrolling.rs
@@ -1,8 +1,9 @@
+use crate::layout_tree;
 use std::collections::{HashMap, HashSet};
 
 use crate::{
     ConstraintKind, ConstraintWarning, Direction, GapConfig, LayoutError, LayoutResult, Rect,
-    SizeConstraints, WindowId, normalized_constraints, record_minimum_warnings,
+    SizeConstraints, WindowId,
 };
 
 const DEFAULT_WIDTH: f64 = 0.5;
@@ -670,7 +671,7 @@ impl ScrollingLayout {
                 constraints
                     .get(&window)
                     .copied()
-                    .map(normalized_constraints)
+                    .map(layout_tree::normalized_constraints)
                     .unwrap_or_default()
                     .max_width
                     .map(|maximum| {
@@ -678,7 +679,7 @@ impl ScrollingLayout {
                             constraints
                                 .get(&window)
                                 .copied()
-                                .map(normalized_constraints)
+                                .map(layout_tree::normalized_constraints)
                                 .unwrap_or_default()
                                 .min_width,
                         )
@@ -854,7 +855,7 @@ impl ScrollingLayout {
                     constraints
                         .get(window)
                         .copied()
-                        .map(normalized_constraints)
+                        .map(layout_tree::normalized_constraints)
                         .unwrap_or_default()
                         .min_width
                 })
@@ -948,8 +949,9 @@ impl ScrollingLayout {
                 // Keep the column allocation stable and honor compatible maximums.
                 let mut common = SizeConstraints::default();
                 for id in &column.windows {
-                    let c =
-                        normalized_constraints(constraints.get(id).copied().unwrap_or_default());
+                    let c = layout_tree::normalized_constraints(
+                        constraints.get(id).copied().unwrap_or_default(),
+                    );
                     common.min_width = common.min_width.max(c.min_width);
                     common.min_height = common.min_height.max(c.min_height);
                     common.max_width = match (common.max_width, c.max_width) {
@@ -961,8 +963,8 @@ impl ScrollingLayout {
                         (a, b) => a.or(b),
                     };
                 }
-                let common = normalized_constraints(common);
-                record_minimum_warnings(window, rect, common, &mut result.warnings);
+                let common = layout_tree::normalized_constraints(common);
+                layout_tree::record_minimum_warnings(window, rect, common, &mut result.warnings);
                 apply_maximums(window, &mut rect, common, &mut result.warnings);
                 if column.windows.len() > 1 {
                     result.tab_bars.push(crate::TabBar {
@@ -984,7 +986,9 @@ impl ScrollingLayout {
                 .windows
                 .iter()
                 .map(|window| {
-                    normalized_constraints(constraints.get(window).copied().unwrap_or_default())
+                    layout_tree::normalized_constraints(
+                        constraints.get(window).copied().unwrap_or_default(),
+                    )
                 })
                 .collect::<Vec<_>>();
             let row_heights = constrained_row_heights(column, available_height, &row_constraints);
@@ -998,7 +1002,12 @@ impl ScrollingLayout {
                     row_heights[window_index],
                 );
                 let constraint = row_constraints[window_index];
-                record_minimum_warnings(*window, rect, constraint, &mut result.warnings);
+                layout_tree::record_minimum_warnings(
+                    *window,
+                    rect,
+                    constraint,
+                    &mut result.warnings,
+                );
                 apply_maximums(*window, &mut rect, constraint, &mut result.warnings);
                 y += row_heights[window_index] + inner;
                 result.geometry.insert(*window, rect);
diff --git a/crates/ferese-panel/src/panel.rs b/crates/ferese-panel/src/panel.rs
index ab3a676..a88cabd 100644
--- a/crates/ferese-panel/src/panel.rs
+++ b/crates/ferese-panel/src/panel.rs
@@ -1,926 +1,9 @@
+//! Panel composition, geometry and allocation share stable group and item identities.
+mod composition;
 pub(crate) mod geometry;
 pub mod layout;
-pub use geometry::{GeometryIntent, PanelGeometry};
 mod radius;
-use crate::PanelStyle;
+
+pub use composition::*;
+pub use geometry::{GeometryIntent, PanelGeometry};
 pub use radius::CornerRadii;
-use serde::{Deserialize, Serialize};
-use std::collections::{BTreeMap, HashSet};
-
-/// The effects protocol accepts 32 regions; reserve one for the overflow group.
-pub const MAX_GROUPS: usize = 31;
-
-fn yes() -> bool {
-    true
-}
-fn priority() -> u8 {
-    50
-}
-fn spacing() -> f32 {
-    1.0
-}
-fn padding() -> [u16; 2] {
-    [2, 3]
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(transparent)]
-pub struct PanelId(pub String);
-
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(rename_all = "lowercase")]
-pub enum Edge {
-    #[default]
-    Top,
-    Bottom,
-}
-
-impl Edge {
-    pub fn key(self) -> &'static str {
-        match self {
-            Self::Top => "top",
-            Self::Bottom => "bottom",
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(transparent)]
-pub struct GroupId(pub String);
-
-#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize)]
-#[serde(transparent)]
-pub struct ItemId(pub String);
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum Representation {
-    Wide,
-    Compact,
-    Icon,
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum OverflowPolicy {
-    #[default]
-    Auto,
-    Never,
-    Always,
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum WorkspaceStyle {
-    Numbers,
-    #[default]
-    Dots,
-    Tabs,
-    WindowStacks,
-    AppIcons,
-}
-
-impl WorkspaceStyle {
-    pub const ALL: [Self; 5] = [
-        Self::Numbers,
-        Self::Dots,
-        Self::Tabs,
-        Self::WindowStacks,
-        Self::AppIcons,
-    ];
-
-    pub fn key(self) -> &'static str {
-        match self {
-            Self::Numbers => "numbers",
-            Self::Dots => "dots",
-            Self::Tabs => "tabs",
-            Self::WindowStacks => "window-stacks",
-            Self::AppIcons => "app-icons",
-        }
-    }
-
-    pub fn label(self) -> &'static str {
-        match self {
-            Self::Numbers => "Numbers",
-            Self::Dots => "Dots",
-            Self::Tabs => "Tabs",
-            Self::WindowStacks => "Window stacks",
-            Self::AppIcons => "App icons",
-        }
-    }
-}
-
-#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(tag = "kind", rename_all = "kebab-case")]
-pub enum ItemKind {
-    Overview,
-    Workspaces {
-        #[serde(default)]
-        style: WorkspaceStyle,
-    },
-    FocusedWindow,
-    Media,
-    Activities,
-    QuickSettings,
-    NightLight,
-    Network,
-    Audio,
-    Recording,
-    Notifications,
-    Battery {
-        #[serde(default = "yes")]
-        percentage: bool,
-    },
-    Clock,
-    DisplayMode,
-    Overflow,
-}
-
-impl ItemKind {
-    /// Smallest useful allocation before a flexible control moves into overflow.
-    pub fn minimum_width(self) -> Option<f32> {
-        match self {
-            Self::FocusedWindow => Some(48.),
-            Self::Workspaces { .. } => Some(24.),
-            Self::Media => Some(112.),
-            _ => None,
-        }
-    }
-
-    pub fn label(self) -> &'static str {
-        match self {
-            Self::Overview => "Overview",
-            Self::Workspaces { .. } => "Workspaces",
-            Self::FocusedWindow => "Focused window",
-            Self::Media => "Media",
-            Self::Activities => "Activities",
-            Self::QuickSettings => "Quick Settings",
-            Self::NightLight => "Night light",
-            Self::Network => "Network",
-            Self::Audio => "Audio",
-            Self::Recording => "Recording",
-            Self::Notifications => "Notifications",
-            Self::Battery { .. } => "Battery",
-            Self::Clock => "Clock",
-            Self::DisplayMode => "Display mode",
-            Self::Overflow => "Overflow",
-        }
-    }
-    pub fn representations(self) -> &'static [Representation] {
-        use Representation::*;
-        match self {
-            Self::Activities | Self::Media | Self::Clock => &[Wide, Compact, Icon],
-            Self::Battery { percentage: true } => &[Wide, Icon],
-            Self::Workspaces { .. } | Self::FocusedWindow => &[Wide],
-            _ => &[Icon],
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Serialize)]
-pub struct Item {
-    pub id: ItemId,
-    #[serde(flatten)]
-    pub kind: ItemKind,
-    // Preserve the existing gap between status controls and the clock/display.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub gap_before: Option<f32>,
-    #[serde(default)]
-    pub overflow: OverflowPolicy,
-    #[serde(default = "priority")]
-    pub priority: u8,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub representation: Option<Representation>,
-    #[serde(default = "yes")]
-    pub visible: bool,
-    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
-    pub metadata: BTreeMap<String, serde_json::Value>,
-}
-
-impl<'de> Deserialize<'de> for Item {
-    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
-        let value = serde_json::Value::deserialize(deserializer)?;
-        let fields = value
-            .as_object()
-            .ok_or_else(|| serde::de::Error::custom("expected a panel item"))?;
-        const OPTIONS: &[&str] = &[
-            "id",
-            "kind",
-            "gap_before",
-            "overflow",
-            "priority",
-            "representation",
-            "visible",
-            "metadata",
-            "style",
-            "percentage",
-        ];
-        for key in fields.keys() {
-            if !OPTIONS.contains(&key.as_str()) {
-                return Err(serde::de::Error::unknown_field(key, OPTIONS));
-            }
-        }
-        if fields.contains_key("style")
-            && fields.get("kind").and_then(serde_json::Value::as_str) != Some("workspaces")
-        {
-            return Err(serde::de::Error::custom(
-                "style is only supported by Workspaces items",
-            ));
-        }
-        if fields.contains_key("percentage")
-            && fields.get("kind").and_then(serde_json::Value::as_str) != Some("battery")
-        {
-            return Err(serde::de::Error::custom(
-                "percentage is only supported by Battery items",
-            ));
-        }
-        #[derive(Deserialize)]
-        struct Fields {
-            id: ItemId,
-            #[serde(flatten)]
-            kind: ItemKind,
-            #[serde(default)]
-            gap_before: Option<f32>,
-            #[serde(default)]
-            overflow: OverflowPolicy,
-            #[serde(default = "priority")]
-            priority: u8,
-            #[serde(default)]
-            representation: Option<Representation>,
-            #[serde(default = "yes")]
-            visible: bool,
-            #[serde(default)]
-            metadata: BTreeMap<String, serde_json::Value>,
-        }
-        let item: Fields = serde_json::from_value(value).map_err(serde::de::Error::custom)?;
-        Ok(Self {
-            id: item.id,
-            kind: item.kind,
-            gap_before: item.gap_before,
-            overflow: item.overflow,
-            priority: item.priority,
-            representation: item.representation,
-            visible: item.visible,
-            metadata: item.metadata,
-        })
-    }
-}
-
-impl Item {
-    /// Start at the configured preference and retain supported smaller forms.
-    pub fn representations(&self) -> Vec<Representation> {
-        let supported = self.kind.representations();
-        let preferred = self.representation.unwrap_or(supported[0]);
-        let alternatives: Vec<_> = supported
-            .iter()
-            .copied()
-            .filter(|representation| *representation as u8 >= preferred as u8)
-            .collect();
-        if alternatives.is_empty() {
-            vec![supported[0]]
-        } else {
-            alternatives
-        }
-    }
-    pub fn new(id: &str, kind: ItemKind) -> Self {
-        Self {
-            id: ItemId(id.into()),
-            kind,
-            gap_before: None,
-            representation: None,
-            visible: true,
-            metadata: BTreeMap::new(),
-            overflow: if matches!(
-                kind,
-                ItemKind::Overview | ItemKind::Workspaces { .. } | ItemKind::FocusedWindow
-            ) {
-                OverflowPolicy::Never
-            } else {
-                OverflowPolicy::Auto
-            },
-            priority: if matches!(kind, ItemKind::Overview | ItemKind::Workspaces { .. }) {
-                100
-            } else if kind == ItemKind::Activities {
-                20
-            } else {
-                50
-            },
-        }
-    }
-
-    pub fn available(&self, availability: Availability) -> bool {
-        if !self.visible {
-            return false;
-        }
-        match self.kind {
-            ItemKind::Activities => availability.activities,
-            ItemKind::Media => availability.media,
-            ItemKind::Network => availability.network,
-            ItemKind::Audio => availability.audio,
-            ItemKind::Notifications => availability.notifications,
-            ItemKind::Battery { .. } => availability.battery,
-            ItemKind::DisplayMode => availability.external_display,
-            _ => true,
-        }
-    }
-}
-
-#[derive(Clone, Copy, Debug, Default)]
-pub struct Availability {
-    pub media: bool,
-    pub activities: bool,
-    pub network: bool,
-    pub audio: bool,
-    pub notifications: bool,
-    pub battery: bool,
-    pub external_display: bool,
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum PanelSurface {
-    None,
-    #[default]
-    Solid,
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum GroupSurface {
-    #[default]
-    None,
-    Inset,
-    Island,
-}
-
-impl GroupSurface {
-    pub fn key(self) -> &'static str {
-        match self {
-            Self::None => "none",
-            Self::Inset => "inset",
-            Self::Island => "island",
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
-#[serde(deny_unknown_fields)]
-pub struct Group {
-    pub id: GroupId,
-    #[serde(default)]
-    pub items: Vec<Item>,
-    #[serde(default = "spacing")]
-    pub spacing: f32,
-    #[serde(default = "padding")]
-    pub padding: [u16; 2],
-    #[serde(default = "crate::default_island_padding")]
-    pub island_padding: f32,
-}
-
-impl Group {
-    fn new(id: &str, items: Vec<Item>, padding: [u16; 2], island_padding: f32) -> Self {
-        Self {
-            id: GroupId(id.into()),
-            items,
-            spacing: 1.0,
-            padding,
-            island_padding,
-        }
-    }
-}
-
-#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
-#[serde(default, deny_unknown_fields)]
-pub struct Zone {
-    pub groups: Vec<Group>,
-    pub spacing: f32,
-}
-
-#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
-#[serde(deny_unknown_fields)]
-pub struct Panel {
-    pub id: PanelId,
-    #[serde(default)]
-    pub edge: Edge,
-    #[serde(default)]
-    pub geometry: GeometryIntent,
-    #[serde(default)]
-    pub style: PanelStyle,
-    #[serde(default, skip_serializing_if = "default_morph")]
-    pub morph: crate::morph::Profile,
-    #[serde(default)]
-    pub border: bool,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub background_opacity: Option<f32>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub corner_radius: Option<CornerRadii>,
-    #[serde(default)]
-    pub start: Zone,
-    #[serde(default)]
-    pub center: Zone,
-    #[serde(default)]
-    pub end: Zone,
-}
-
-impl Default for Zone {
-    fn default() -> Self {
-        Self {
-            groups: Vec::new(),
-            spacing: 8.0,
-        }
-    }
-}
-
-fn default_morph(profile: &crate::morph::Profile) -> bool {
-    *profile == crate::morph::Profile::default()
-}
-
-pub fn validate(panels: &[Panel]) -> Result<(), String> {
-    if panels.len() != 1 {
-        return Err("configure exactly one panel; multiple panels are not supported yet".into());
-    }
-    let valid_id = |value: &str| {
-        !value.is_empty()
-            && value.len() <= 128
-            && value
-                .bytes()
-                .all(|byte| byte.is_ascii_alphanumeric() || b"-_.:@".contains(&byte))
-            && !value.starts_with('_')
-    };
-    let mut panel_ids = HashSet::new();
-    for panel in panels {
-        if !PanelStyle::AVAILABLE.contains(&panel.style) {
-            return Err(format!(
-                "panel style {} is not available yet",
-                panel.style.key()
-            ));
-        }
-        panel.geometry.validate()?;
-        panel.morph.validate()?;
-        if panel.group_count() > MAX_GROUPS {
-            return Err(format!(
-                "a panel supports at most {MAX_GROUPS} groups, reserving one region for overflow"
-            ));
-        }
-        if let Some(opacity) = panel.background_opacity
-            && (!opacity.is_finite() || !(0.0..=1.0).contains(&opacity))
-        {
-            return Err("panel background opacity must be between 0 and 1".into());
-        }
-        if let Some(radius) = panel.corner_radius {
-            radius.validate()?;
-        }
-        if !valid_id(&panel.id.0) || !panel_ids.insert(&panel.id.0) {
-            return Err(format!("invalid or duplicate panel ID {:?}", panel.id.0));
-        }
-        let mut group_ids = HashSet::new();
-        let mut item_ids = HashSet::new();
-        for zone in [&panel.start, &panel.center, &panel.end] {
-            if !zone.spacing.is_finite() || !(0.0..=64.0).contains(&zone.spacing) {
-                return Err("panel zone spacing must be between 0 and 64".into());
-            }
-            for group in &zone.groups {
-                if !valid_id(&group.id.0) || !group_ids.insert(&group.id.0) {
-                    return Err(format!("invalid or duplicate group ID {:?}", group.id.0));
-                }
-                if !group.spacing.is_finite()
-                    || !(0.0..=64.0).contains(&group.spacing)
-                    || !group.island_padding.is_finite()
-                    || !(0.0..=32.0).contains(&group.island_padding)
-                    || group.padding.iter().any(|value| *value > 32)
-                {
-                    return Err("invalid panel group spacing or padding".into());
-                }
-                for item in &group.items {
-                    if !valid_id(&item.id.0) || !item_ids.insert(&item.id.0) {
-                        return Err(format!("invalid or duplicate item ID {:?}", item.id.0));
-                    }
-                    if item.priority > 100
-                        || item
-                            .gap_before
-                            .is_some_and(|gap| !gap.is_finite() || !(0.0..=64.0).contains(&gap))
-                    {
-                        return Err("panel item priority must be 0..100 and gaps 0..64".into());
-                    }
-                    if item.kind == ItemKind::Overflow {
-                        return Err(
-                            "overflow is supplied by the panel; it cannot be configured as an item"
-                                .into(),
-                        );
-                    }
-                }
-            }
-        }
-    }
-    Ok(())
-}
-
-impl Default for Panel {
-    fn default() -> Self {
-        Self::from_preset(PanelStyle::Flat)
-    }
-}
-
-impl Panel {
-    pub fn preset(&self) -> Option<PanelStyle> {
-        Some(self.style)
-    }
-
-    pub fn apply_preset(&mut self, style: PanelStyle) {
-        self.style = style;
-    }
-
-    pub fn surface(&self) -> PanelSurface {
-        if matches!(self.style, PanelStyle::Flat | PanelStyle::Frame) {
-            PanelSurface::Solid
-        } else {
-            PanelSurface::None
-        }
-    }
-
-    pub fn group_surface(&self) -> GroupSurface {
-        if self.surface() == PanelSurface::Solid {
-            GroupSurface::None
-        } else {
-            GroupSurface::Island
-        }
-    }
-
-    pub fn zone_spacing(&self, zone: &Zone) -> f32 {
-        if self.style.connected() {
-            0.
-        } else {
-            zone.spacing
-        }
-    }
-
-    pub fn shape_parameters(&self) -> crate::scene::Parameters {
-        crate::scene::Parameters {
-            style: self.style,
-            attached: self.style == PanelStyle::Morph && self.morph.attached,
-            fillet: if self.style == PanelStyle::Morph {
-                12.
-            } else {
-                crate::scene::Parameters::default().fillet
-            },
-            edge: self.edge,
-            height: self.resolved_geometry().height.into(),
-            radius: self.corner_radius.map(|r| crate::shape::AnchoredRadii(r.0)),
-            ..Default::default()
-        }
-    }
-
-    pub fn resolved_geometry(&self) -> PanelGeometry {
-        let mut geometry = self.geometry.resolve(self.style);
-        if self.style == PanelStyle::Morph && self.morph.attached {
-            geometry.edge_margin = 0;
-        }
-        geometry
-    }
-
-    pub fn exclusive_zone(&self, hidden: bool) -> i32 {
-        if hidden {
-            0
-        } else {
-            let geometry = self.resolved_geometry();
-            (geometry.height.round() as i32).saturating_add(geometry.window_clearance)
-        }
-    }
-
-    pub fn group_count(&self) -> usize {
-        [&self.start, &self.center, &self.end]
-            .into_iter()
-            .map(|zone| zone.groups.len())
-            .sum()
-    }
-
-    /// Appearance changes do not replace item ownership or measured allocation.
-    pub fn same_composition(&self, other: &Self) -> bool {
-        let same_zone = |left: &Zone, right: &Zone| {
-            left.spacing == right.spacing
-                && left.groups.len() == right.groups.len()
-                && left.groups.iter().zip(&right.groups).all(|(left, right)| {
-                    left.id == right.id
-                        && left.items == right.items
-                        && left.spacing == right.spacing
-                        && left.padding == right.padding
-                        && left.island_padding == right.island_padding
-                        && (self.group_surface() == GroupSurface::Island)
-                            == (other.group_surface() == GroupSurface::Island)
-                })
-        };
-        self.id == other.id
-            && self.edge == other.edge
-            && self.style == other.style
-            && self.morph == other.morph
-            && same_zone(&self.start, &other.start)
-            && same_zone(&self.center, &other.center)
-            && same_zone(&self.end, &other.end)
-    }
-
-    pub fn resolved_radius(&self, shell_radius: f32) -> CornerRadii {
-        self.corner_radius
-            .unwrap_or_else(|| CornerRadii::uniform(shell_radius))
-    }
-
-    /// The overflow trigger is generated, never persisted as a configured item.
-    pub fn overflow_group(&self) -> Group {
-        Group {
-            id: GroupId("_overflow".into()),
-            items: vec![Item {
-                id: ItemId("_overflow".into()),
-                kind: ItemKind::Overflow,
-                gap_before: None,
-                representation: None,
-                visible: true,
-                metadata: BTreeMap::new(),
-                overflow: OverflowPolicy::Never,
-                priority: 100,
-            }],
-            spacing: 0.0,
-            padding: [2, 3],
-            island_padding: self
-                .end
-                .groups
-                .first()
-                .map_or(crate::default_island_padding(), |group| {
-                    group.island_padding
-                }),
-        }
-    }
-
-    pub fn item(&self, id: &ItemId) -> Option<&Item> {
-        [&self.start, &self.center, &self.end]
-            .into_iter()
-            .flat_map(|zone| &zone.groups)
-            .flat_map(|group| &group.items)
-            .find(|item| &item.id == id)
-    }
-
-    /// Build a stable initial composition; presets are an editor convenience.
-    pub fn from_preset(preset: PanelStyle) -> Self {
-        use ItemKind::*;
-
-        let item = Item::new;
-        let padding = crate::default_island_padding();
-        let overview = item("overview", Overview);
-        let workspaces = item(
-            "workspaces",
-            Workspaces {
-                style: WorkspaceStyle::default(),
-            },
-        );
-        let title = item("focused-window", FocusedWindow);
-        let controls = vec![
-            item("media", Media),
-            item("quick-settings", QuickSettings),
-            item("night-light", NightLight),
-            item("network", Network),
-            item("audio", Audio),
-            item("recording", Recording),
-            item("notifications", Notifications),
-            item("battery", Battery { percentage: true }),
-        ];
-        let clock = item("clock", Clock);
-        let display = item("display-mode", DisplayMode);
-
-        let (start, center, end) = match preset {
-            PanelStyle::Flat => (
-                vec![
-                    Group::new("overview", vec![overview], [0, 0], padding),
-                    Group::new("workspaces", vec![workspaces], [2, 3], padding),
-                ],
-                Group::new("title", vec![title], [0, 0], padding),
-                vec![
-                    Group::new("status", controls, [2, 3], padding),
-                    Group::new("time", vec![clock], [2, 3], padding),
-                    Group::new("display", vec![display], [0, 0], padding),
-                ],
-            ),
-            _ => {
-                let mut controls = controls;
-                controls.extend([clock, display]);
-                (
-                    vec![Group::new(
-                        "navigation",
-                        vec![overview, workspaces],
-                        [2, 3],
-                        padding,
-                    )],
-                    Group::new("title", vec![title], [0, 0], padding),
-                    vec![Group::new("status", controls, [2, 3], padding)],
-                )
-            }
-        };
-
-        Self {
-            id: PanelId("main".into()),
-            edge: Edge::Top,
-            geometry: GeometryIntent::default(),
-            style: preset,
-            morph: Default::default(),
-            border: false,
-            background_opacity: Option::None,
-            corner_radius: Option::None,
-            start: Zone {
-                groups: start,
-                spacing: if preset == PanelStyle::Floating {
-                    8.0
-                } else {
-                    3.0
-                },
-            },
-            center: Zone {
-                groups: vec![center],
-                spacing: 8.0,
-            },
-            end: Zone {
-                groups: end,
-                spacing: 8.0,
-            },
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn fullscreen_releases_the_entire_reservation_without_discarding_pins() {
-        let mut panel = Panel::from_preset(PanelStyle::Floating);
-        panel.geometry.height = Some(36.);
-        panel.geometry.window_clearance = Some(4);
-        assert_eq!(panel.exclusive_zone(false), 40);
-        assert_eq!(panel.exclusive_zone(true), 0);
-        assert_eq!(panel.geometry.window_clearance, Some(4));
-    }
-
-    fn items(panel: &Panel) -> Vec<&Item> {
-        [&panel.start, &panel.center, &panel.end]
-            .into_iter()
-            .flat_map(|zone| &zone.groups)
-            .flat_map(|group| &group.items)
-            .collect()
-    }
-
-    #[test]
-    fn group_capacity_reserves_overflow_even_for_empty_groups() {
-        for background in [PanelStyle::Flat, PanelStyle::Floating] {
-            let mut panel = Panel::from_preset(background);
-            panel.start.groups.clear();
-            panel.center.groups.clear();
-            panel.end.groups = (0..MAX_GROUPS)
-                .map(|i| Group::new(&format!("group-{i}"), Vec::new(), [2, 3], 4.))
-                .collect();
-            assert_eq!(panel.group_count(), MAX_GROUPS);
-            validate(std::slice::from_ref(&panel)).unwrap();
-            panel
-                .start
-                .groups
-                .push(Group::new("one-too-many", Vec::new(), [2, 3], 4.));
-            assert!(validate(&[panel]).unwrap_err().contains("31 groups"));
-        }
-    }
-
-    #[test]
-    fn defaults_preserve_order_and_ids_across_background_changes() {
-        let continuous = Panel::default();
-        let islands = Panel::from_preset(PanelStyle::Floating);
-        let expected = [
-            "overview",
-            "workspaces",
-            "focused-window",
-            "media",
-            "quick-settings",
-            "night-light",
-            "network",
-            "audio",
-            "recording",
-            "notifications",
-            "battery",
-            "clock",
-            "display-mode",
-        ];
-        for panel in [&continuous, &islands] {
-            let ids: Vec<_> = items(panel).iter().map(|item| item.id.0.as_str()).collect();
-            assert_eq!(ids, expected);
-            assert_eq!(Panel::from_preset(panel.preset().unwrap()), *panel);
-        }
-        assert_eq!(continuous.start.groups.len(), 2);
-        assert_eq!(continuous.end.groups.len(), 3);
-        assert_eq!(islands.start.groups.len(), 1);
-        assert_eq!(islands.end.groups.len(), 1);
-        assert!(!islands.border && !continuous.border);
-    }
-
-    #[test]
-    fn availability_filters_without_removing_or_reidentifying_instances() {
-        let panel = Panel::default();
-        let all = items(&panel);
-        let visible = |availability| {
-            all.iter()
-                .filter(|item| item.available(availability))
-                .map(|item| item.id.0.as_str())
-                .collect::<Vec<_>>()
-        };
-        assert_eq!(
-            visible(Availability::default()),
-            [
-                "overview",
-                "workspaces",
-                "focused-window",
-                "quick-settings",
-                "night-light",
-                "recording",
-                "clock"
-            ]
-        );
-        assert_eq!(
-            visible(Availability {
-                activities: true,
-                media: true,
-                network: true,
-                audio: true,
-                notifications: true,
-                battery: true,
-                external_display: true
-            }),
-            all.iter()
-                .map(|item| item.id.0.as_str())
-                .collect::<Vec<_>>()
-        );
-        assert_eq!(items(&panel).len(), 13);
-    }
-
-    #[test]
-    fn settings_map_to_instances_and_group_presentation() {
-        let mut panel = Panel::from_preset(PanelStyle::Floating);
-        panel.center.groups[0].items[0].visible = false;
-        let battery = panel.end.groups[0]
-            .items
-            .iter_mut()
-            .find(|item| item.id.0 == "battery")
-            .unwrap();
-        battery.kind = ItemKind::Battery { percentage: false };
-        for group in [&mut panel.start, &mut panel.center, &mut panel.end]
-            .into_iter()
-            .flat_map(|zone| &mut zone.groups)
-        {
-            group.island_padding = 13.;
-        }
-        assert_eq!(
-            panel.center.groups[0].items[0].kind,
-            ItemKind::FocusedWindow
-        );
-        assert!(!panel.center.groups[0].items[0].visible);
-        let all = items(&panel);
-        assert_eq!(
-            all.iter().find(|item| item.id.0 == "battery").unwrap().kind,
-            ItemKind::Battery { percentage: false }
-        );
-        for zone in [&panel.start, &panel.center, &panel.end] {
-            for group in &zone.groups {
-                assert_eq!(group.island_padding, 13.0);
-            }
-        }
-        assert_eq!(
-            all.iter()
-                .find(|item| item.id.0 == "clock")
-                .unwrap()
-                .gap_before,
-            None
-        );
-    }
-
-    #[test]
-    fn two_clock_instances_have_distinct_identity() {
-        let first = Item::new("main-clock", ItemKind::Clock);
-        let second = Item::new("other-clock", ItemKind::Clock);
-        assert_eq!(first.kind, second.kind);
-        assert_ne!(first.id, second.id);
-    }
-    #[test]
-    fn removed_item_fields_are_rejected() {
-        for value in [
-            serde_json::json!({"id":"title", "kind":"focused-window", "enabled":false}),
-            serde_json::json!({"id":"spaces", "kind":"workspaces", "workspace_style":"numbers"}),
-        ] {
-            assert!(serde_json::from_value::<Item>(value).is_err());
-        }
-    }
-
-    #[test]
-    fn surface_changes_only_replace_composition_when_item_geometry_changes() {
-        let panel = Panel::default();
-        let mut changed = panel.clone();
-        changed.style = PanelStyle::Flat;
-        assert!(panel.same_composition(&changed));
-        changed.style = PanelStyle::Floating;
-        assert!(!panel.same_composition(&changed));
-        changed.style = PanelStyle::Flat;
-        assert!(panel.same_composition(&changed));
-        changed.end.groups[0].padding[1] += 1;
-        assert!(!panel.same_composition(&changed));
-    }
-}
diff --git a/crates/ferese-panel/src/panel/composition.rs b/crates/ferese-panel/src/panel/composition.rs
new file mode 100644
index 0000000..0357066
--- /dev/null
+++ b/crates/ferese-panel/src/panel/composition.rs
@@ -0,0 +1,923 @@
+use super::{CornerRadii, GeometryIntent, PanelGeometry};
+use crate::PanelStyle;
+
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, HashSet};
+
+/// The effects protocol accepts 32 regions; reserve one for the overflow group.
+pub const MAX_GROUPS: usize = 31;
+
+fn yes() -> bool {
+    true
+}
+fn priority() -> u8 {
+    50
+}
+fn spacing() -> f32 {
+    1.0
+}
+fn padding() -> [u16; 2] {
+    [2, 3]
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(transparent)]
+pub struct PanelId(pub String);
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Edge {
+    #[default]
+    Top,
+    Bottom,
+}
+
+impl Edge {
+    pub fn key(self) -> &'static str {
+        match self {
+            Self::Top => "top",
+            Self::Bottom => "bottom",
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(transparent)]
+pub struct GroupId(pub String);
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize)]
+#[serde(transparent)]
+pub struct ItemId(pub String);
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Representation {
+    Wide,
+    Compact,
+    Icon,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum OverflowPolicy {
+    #[default]
+    Auto,
+    Never,
+    Always,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum WorkspaceStyle {
+    Numbers,
+    #[default]
+    Dots,
+    Tabs,
+    WindowStacks,
+    AppIcons,
+}
+
+impl WorkspaceStyle {
+    pub const ALL: [Self; 5] = [
+        Self::Numbers,
+        Self::Dots,
+        Self::Tabs,
+        Self::WindowStacks,
+        Self::AppIcons,
+    ];
+
+    pub fn key(self) -> &'static str {
+        match self {
+            Self::Numbers => "numbers",
+            Self::Dots => "dots",
+            Self::Tabs => "tabs",
+            Self::WindowStacks => "window-stacks",
+            Self::AppIcons => "app-icons",
+        }
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Numbers => "Numbers",
+            Self::Dots => "Dots",
+            Self::Tabs => "Tabs",
+            Self::WindowStacks => "Window stacks",
+            Self::AppIcons => "App icons",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(tag = "kind", rename_all = "kebab-case")]
+pub enum ItemKind {
+    Overview,
+    Workspaces {
+        #[serde(default)]
+        style: WorkspaceStyle,
+    },
+    FocusedWindow,
+    Media,
+    Activities,
+    QuickSettings,
+    NightLight,
+    Network,
+    Audio,
+    Recording,
+    Notifications,
+    Battery {
+        #[serde(default = "yes")]
+        percentage: bool,
+    },
+    Clock,
+    DisplayMode,
+    Overflow,
+}
+
+impl ItemKind {
+    /// Smallest useful allocation before a flexible control moves into overflow.
+    pub fn minimum_width(self) -> Option<f32> {
+        match self {
+            Self::FocusedWindow => Some(48.),
+            Self::Workspaces { .. } => Some(24.),
+            Self::Media => Some(112.),
+            _ => None,
+        }
+    }
+
+    pub fn label(self) -> &'static str {
+        match self {
+            Self::Overview => "Overview",
+            Self::Workspaces { .. } => "Workspaces",
+            Self::FocusedWindow => "Focused window",
+            Self::Media => "Media",
+            Self::Activities => "Activities",
+            Self::QuickSettings => "Quick Settings",
+            Self::NightLight => "Night light",
+            Self::Network => "Network",
+            Self::Audio => "Audio",
+            Self::Recording => "Recording",
+            Self::Notifications => "Notifications",
+            Self::Battery { .. } => "Battery",
+            Self::Clock => "Clock",
+            Self::DisplayMode => "Display mode",
+            Self::Overflow => "Overflow",
+        }
+    }
+    pub fn representations(self) -> &'static [Representation] {
+        use Representation::*;
+        match self {
+            Self::Activities | Self::Media | Self::Clock => &[Wide, Compact, Icon],
+            Self::Battery { percentage: true } => &[Wide, Icon],
+            Self::Workspaces { .. } | Self::FocusedWindow => &[Wide],
+            _ => &[Icon],
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct Item {
+    pub id: ItemId,
+    #[serde(flatten)]
+    pub kind: ItemKind,
+    // Preserve the existing gap between status controls and the clock/display.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gap_before: Option<f32>,
+    #[serde(default)]
+    pub overflow: OverflowPolicy,
+    #[serde(default = "priority")]
+    pub priority: u8,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub representation: Option<Representation>,
+    #[serde(default = "yes")]
+    pub visible: bool,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub metadata: BTreeMap<String, serde_json::Value>,
+}
+
+impl<'de> Deserialize<'de> for Item {
+    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+        let value = serde_json::Value::deserialize(deserializer)?;
+        let fields = value
+            .as_object()
+            .ok_or_else(|| serde::de::Error::custom("expected a panel item"))?;
+        const OPTIONS: &[&str] = &[
+            "id",
+            "kind",
+            "gap_before",
+            "overflow",
+            "priority",
+            "representation",
+            "visible",
+            "metadata",
+            "style",
+            "percentage",
+        ];
+        for key in fields.keys() {
+            if !OPTIONS.contains(&key.as_str()) {
+                return Err(serde::de::Error::unknown_field(key, OPTIONS));
+            }
+        }
+        if fields.contains_key("style")
+            && fields.get("kind").and_then(serde_json::Value::as_str) != Some("workspaces")
+        {
+            return Err(serde::de::Error::custom(
+                "style is only supported by Workspaces items",
+            ));
+        }
+        if fields.contains_key("percentage")
+            && fields.get("kind").and_then(serde_json::Value::as_str) != Some("battery")
+        {
+            return Err(serde::de::Error::custom(
+                "percentage is only supported by Battery items",
+            ));
+        }
+        #[derive(Deserialize)]
+        struct Fields {
+            id: ItemId,
+            #[serde(flatten)]
+            kind: ItemKind,
+            #[serde(default)]
+            gap_before: Option<f32>,
+            #[serde(default)]
+            overflow: OverflowPolicy,
+            #[serde(default = "priority")]
+            priority: u8,
+            #[serde(default)]
+            representation: Option<Representation>,
+            #[serde(default = "yes")]
+            visible: bool,
+            #[serde(default)]
+            metadata: BTreeMap<String, serde_json::Value>,
+        }
+        let item: Fields = serde_json::from_value(value).map_err(serde::de::Error::custom)?;
+        Ok(Self {
+            id: item.id,
+            kind: item.kind,
+            gap_before: item.gap_before,
+            overflow: item.overflow,
+            priority: item.priority,
+            representation: item.representation,
+            visible: item.visible,
+            metadata: item.metadata,
+        })
+    }
+}
+
+impl Item {
+    /// Start at the configured preference and retain supported smaller forms.
+    pub fn representations(&self) -> Vec<Representation> {
+        let supported = self.kind.representations();
+        let preferred = self.representation.unwrap_or(supported[0]);
+        let alternatives: Vec<_> = supported
+            .iter()
+            .copied()
+            .filter(|representation| *representation as u8 >= preferred as u8)
+            .collect();
+        if alternatives.is_empty() {
+            vec![supported[0]]
+        } else {
+            alternatives
+        }
+    }
+    pub fn new(id: &str, kind: ItemKind) -> Self {
+        Self {
+            id: ItemId(id.into()),
+            kind,
+            gap_before: None,
+            representation: None,
+            visible: true,
+            metadata: BTreeMap::new(),
+            overflow: if matches!(
+                kind,
+                ItemKind::Overview | ItemKind::Workspaces { .. } | ItemKind::FocusedWindow
+            ) {
+                OverflowPolicy::Never
+            } else {
+                OverflowPolicy::Auto
+            },
+            priority: if matches!(kind, ItemKind::Overview | ItemKind::Workspaces { .. }) {
+                100
+            } else if kind == ItemKind::Activities {
+                20
+            } else {
+                50
+            },
+        }
+    }
+
+    pub fn available(&self, availability: Availability) -> bool {
+        if !self.visible {
+            return false;
+        }
+        match self.kind {
+            ItemKind::Activities => availability.activities,
+            ItemKind::Media => availability.media,
+            ItemKind::Network => availability.network,
+            ItemKind::Audio => availability.audio,
+            ItemKind::Notifications => availability.notifications,
+            ItemKind::Battery { .. } => availability.battery,
+            ItemKind::DisplayMode => availability.external_display,
+            _ => true,
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Availability {
+    pub media: bool,
+    pub activities: bool,
+    pub network: bool,
+    pub audio: bool,
+    pub notifications: bool,
+    pub battery: bool,
+    pub external_display: bool,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum PanelSurface {
+    None,
+    #[default]
+    Solid,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum GroupSurface {
+    #[default]
+    None,
+    Inset,
+    Island,
+}
+
+impl GroupSurface {
+    pub fn key(self) -> &'static str {
+        match self {
+            Self::None => "none",
+            Self::Inset => "inset",
+            Self::Island => "island",
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Group {
+    pub id: GroupId,
+    #[serde(default)]
+    pub items: Vec<Item>,
+    #[serde(default = "spacing")]
+    pub spacing: f32,
+    #[serde(default = "padding")]
+    pub padding: [u16; 2],
+    #[serde(default = "crate::default_island_padding")]
+    pub island_padding: f32,
+}
+
+impl Group {
+    pub(super) fn new(id: &str, items: Vec<Item>, padding: [u16; 2], island_padding: f32) -> Self {
+        Self {
+            id: GroupId(id.into()),
+            items,
+            spacing: 1.0,
+            padding,
+            island_padding,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(default, deny_unknown_fields)]
+pub struct Zone {
+    pub groups: Vec<Group>,
+    pub spacing: f32,
+}
+
+#[derive(Clone, Debug, PartialEq, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct Panel {
+    pub id: PanelId,
+    #[serde(default)]
+    pub edge: Edge,
+    #[serde(default)]
+    pub geometry: GeometryIntent,
+    #[serde(default)]
+    pub style: PanelStyle,
+    #[serde(default, skip_serializing_if = "default_morph")]
+    pub morph: crate::morph::Profile,
+    #[serde(default)]
+    pub border: bool,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub background_opacity: Option<f32>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub corner_radius: Option<CornerRadii>,
+    #[serde(default)]
+    pub start: Zone,
+    #[serde(default)]
+    pub center: Zone,
+    #[serde(default)]
+    pub end: Zone,
+}
+
+impl Default for Zone {
+    fn default() -> Self {
+        Self {
+            groups: Vec::new(),
+            spacing: 8.0,
+        }
+    }
+}
+
+fn default_morph(profile: &crate::morph::Profile) -> bool {
+    *profile == crate::morph::Profile::default()
+}
+
+pub fn validate(panels: &[Panel]) -> Result<(), String> {
+    if panels.len() != 1 {
+        return Err("configure exactly one panel; multiple panels are not supported yet".into());
+    }
+    let valid_id = |value: &str| {
+        !value.is_empty()
+            && value.len() <= 128
+            && value
+                .bytes()
+                .all(|byte| byte.is_ascii_alphanumeric() || b"-_.:@".contains(&byte))
+            && !value.starts_with('_')
+    };
+    let mut panel_ids = HashSet::new();
+    for panel in panels {
+        if !PanelStyle::AVAILABLE.contains(&panel.style) {
+            return Err(format!(
+                "panel style {} is not available yet",
+                panel.style.key()
+            ));
+        }
+        panel.geometry.validate()?;
+        panel.morph.validate()?;
+        if panel.group_count() > MAX_GROUPS {
+            return Err(format!(
+                "a panel supports at most {MAX_GROUPS} groups, reserving one region for overflow"
+            ));
+        }
+        if let Some(opacity) = panel.background_opacity
+            && (!opacity.is_finite() || !(0.0..=1.0).contains(&opacity))
+        {
+            return Err("panel background opacity must be between 0 and 1".into());
+        }
+        if let Some(radius) = panel.corner_radius {
+            radius.validate()?;
+        }
+        if !valid_id(&panel.id.0) || !panel_ids.insert(&panel.id.0) {
+            return Err(format!("invalid or duplicate panel ID {:?}", panel.id.0));
+        }
+        let mut group_ids = HashSet::new();
+        let mut item_ids = HashSet::new();
+        for zone in [&panel.start, &panel.center, &panel.end] {
+            if !zone.spacing.is_finite() || !(0.0..=64.0).contains(&zone.spacing) {
+                return Err("panel zone spacing must be between 0 and 64".into());
+            }
+            for group in &zone.groups {
+                if !valid_id(&group.id.0) || !group_ids.insert(&group.id.0) {
+                    return Err(format!("invalid or duplicate group ID {:?}", group.id.0));
+                }
+                if !group.spacing.is_finite()
+                    || !(0.0..=64.0).contains(&group.spacing)
+                    || !group.island_padding.is_finite()
+                    || !(0.0..=32.0).contains(&group.island_padding)
+                    || group.padding.iter().any(|value| *value > 32)
+                {
+                    return Err("invalid panel group spacing or padding".into());
+                }
+                for item in &group.items {
+                    if !valid_id(&item.id.0) || !item_ids.insert(&item.id.0) {
+                        return Err(format!("invalid or duplicate item ID {:?}", item.id.0));
+                    }
+                    if item.priority > 100
+                        || item
+                            .gap_before
+                            .is_some_and(|gap| !gap.is_finite() || !(0.0..=64.0).contains(&gap))
+                    {
+                        return Err("panel item priority must be 0..100 and gaps 0..64".into());
+                    }
+                    if item.kind == ItemKind::Overflow {
+                        return Err(
+                            "overflow is supplied by the panel; it cannot be configured as an item"
+                                .into(),
+                        );
+                    }
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+impl Default for Panel {
+    fn default() -> Self {
+        Self::from_preset(PanelStyle::Flat)
+    }
+}
+
+impl Panel {
+    pub fn preset(&self) -> Option<PanelStyle> {
+        Some(self.style)
+    }
+
+    pub fn apply_preset(&mut self, style: PanelStyle) {
+        self.style = style;
+    }
+
+    pub fn surface(&self) -> PanelSurface {
+        if matches!(self.style, PanelStyle::Flat | PanelStyle::Frame) {
+            PanelSurface::Solid
+        } else {
+            PanelSurface::None
+        }
+    }
+
+    pub fn group_surface(&self) -> GroupSurface {
+        if self.surface() == PanelSurface::Solid {
+            GroupSurface::None
+        } else {
+            GroupSurface::Island
+        }
+    }
+
+    pub fn zone_spacing(&self, zone: &Zone) -> f32 {
+        if self.style.connected() {
+            0.
+        } else {
+            zone.spacing
+        }
+    }
+
+    pub fn shape_parameters(&self) -> crate::scene::Parameters {
+        crate::scene::Parameters {
+            style: self.style,
+            attached: self.style == PanelStyle::Morph && self.morph.attached,
+            fillet: if self.style == PanelStyle::Morph {
+                12.
+            } else {
+                crate::scene::Parameters::default().fillet
+            },
+            edge: self.edge,
+            height: self.resolved_geometry().height.into(),
+            radius: self.corner_radius.map(|r| crate::shape::AnchoredRadii(r.0)),
+            ..Default::default()
+        }
+    }
+
+    pub fn resolved_geometry(&self) -> PanelGeometry {
+        let mut geometry = self.geometry.resolve(self.style);
+        if self.style == PanelStyle::Morph && self.morph.attached {
+            geometry.edge_margin = 0;
+        }
+        geometry
+    }
+
+    pub fn exclusive_zone(&self, hidden: bool) -> i32 {
+        if hidden {
+            0
+        } else {
+            let geometry = self.resolved_geometry();
+            (geometry.height.round() as i32).saturating_add(geometry.window_clearance)
+        }
+    }
+
+    pub fn group_count(&self) -> usize {
+        [&self.start, &self.center, &self.end]
+            .into_iter()
+            .map(|zone| zone.groups.len())
+            .sum()
+    }
+
+    /// Appearance changes do not replace item ownership or measured allocation.
+    pub fn same_composition(&self, other: &Self) -> bool {
+        let same_zone = |left: &Zone, right: &Zone| {
+            left.spacing == right.spacing
+                && left.groups.len() == right.groups.len()
+                && left.groups.iter().zip(&right.groups).all(|(left, right)| {
+                    left.id == right.id
+                        && left.items == right.items
+                        && left.spacing == right.spacing
+                        && left.padding == right.padding
+                        && left.island_padding == right.island_padding
+                        && (self.group_surface() == GroupSurface::Island)
+                            == (other.group_surface() == GroupSurface::Island)
+                })
+        };
+        self.id == other.id
+            && self.edge == other.edge
+            && self.style == other.style
+            && self.morph == other.morph
+            && same_zone(&self.start, &other.start)
+            && same_zone(&self.center, &other.center)
+            && same_zone(&self.end, &other.end)
+    }
+
+    pub fn resolved_radius(&self, shell_radius: f32) -> CornerRadii {
+        self.corner_radius
+            .unwrap_or_else(|| CornerRadii::uniform(shell_radius))
+    }
+
+    /// The overflow trigger is generated, never persisted as a configured item.
+    pub fn overflow_group(&self) -> Group {
+        Group {
+            id: GroupId("_overflow".into()),
+            items: vec![Item {
+                id: ItemId("_overflow".into()),
+                kind: ItemKind::Overflow,
+                gap_before: None,
+                representation: None,
+                visible: true,
+                metadata: BTreeMap::new(),
+                overflow: OverflowPolicy::Never,
+                priority: 100,
+            }],
+            spacing: 0.0,
+            padding: [2, 3],
+            island_padding: self
+                .end
+                .groups
+                .first()
+                .map_or(crate::default_island_padding(), |group| {
+                    group.island_padding
+                }),
+        }
+    }
+
+    pub fn item(&self, id: &ItemId) -> Option<&Item> {
+        [&self.start, &self.center, &self.end]
+            .into_iter()
+            .flat_map(|zone| &zone.groups)
+            .flat_map(|group| &group.items)
+            .find(|item| &item.id == id)
+    }
+
+    /// Build a stable initial composition; presets are an editor convenience.
+    pub fn from_preset(preset: PanelStyle) -> Self {
+        use ItemKind::*;
+
+        let item = Item::new;
+        let padding = crate::default_island_padding();
+        let overview = item("overview", Overview);
+        let workspaces = item(
+            "workspaces",
+            Workspaces {
+                style: WorkspaceStyle::default(),
+            },
+        );
+        let title = item("focused-window", FocusedWindow);
+        let controls = vec![
+            item("media", Media),
+            item("quick-settings", QuickSettings),
+            item("night-light", NightLight),
+            item("network", Network),
+            item("audio", Audio),
+            item("recording", Recording),
+            item("notifications", Notifications),
+            item("battery", Battery { percentage: true }),
+        ];
+        let clock = item("clock", Clock);
+        let display = item("display-mode", DisplayMode);
+
+        let (start, center, end) = match preset {
+            PanelStyle::Flat => (
+                vec![
+                    Group::new("overview", vec![overview], [0, 0], padding),
+                    Group::new("workspaces", vec![workspaces], [2, 3], padding),
+                ],
+                Group::new("title", vec![title], [0, 0], padding),
+                vec![
+                    Group::new("status", controls, [2, 3], padding),
+                    Group::new("time", vec![clock], [2, 3], padding),
+                    Group::new("display", vec![display], [0, 0], padding),
+                ],
+            ),
+            _ => {
+                let mut controls = controls;
+                controls.extend([clock, display]);
+                (
+                    vec![Group::new(
+                        "navigation",
+                        vec![overview, workspaces],
+                        [2, 3],
+                        padding,
+                    )],
+                    Group::new("title", vec![title], [0, 0], padding),
+                    vec![Group::new("status", controls, [2, 3], padding)],
+                )
+            }
+        };
+
+        Self {
+            id: PanelId("main".into()),
+            edge: Edge::Top,
+            geometry: GeometryIntent::default(),
+            style: preset,
+            morph: Default::default(),
+            border: false,
+            background_opacity: Option::None,
+            corner_radius: Option::None,
+            start: Zone {
+                groups: start,
+                spacing: if preset == PanelStyle::Floating {
+                    8.0
+                } else {
+                    3.0
+                },
+            },
+            center: Zone {
+                groups: vec![center],
+                spacing: 8.0,
+            },
+            end: Zone {
+                groups: end,
+                spacing: 8.0,
+            },
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn fullscreen_releases_the_entire_reservation_without_discarding_pins() {
+        let mut panel = Panel::from_preset(PanelStyle::Floating);
+        panel.geometry.height = Some(36.);
+        panel.geometry.window_clearance = Some(4);
+        assert_eq!(panel.exclusive_zone(false), 40);
+        assert_eq!(panel.exclusive_zone(true), 0);
+        assert_eq!(panel.geometry.window_clearance, Some(4));
+    }
+
+    fn items(panel: &Panel) -> Vec<&Item> {
+        [&panel.start, &panel.center, &panel.end]
+            .into_iter()
+            .flat_map(|zone| &zone.groups)
+            .flat_map(|group| &group.items)
+            .collect()
+    }
+
+    #[test]
+    fn group_capacity_reserves_overflow_even_for_empty_groups() {
+        for background in [PanelStyle::Flat, PanelStyle::Floating] {
+            let mut panel = Panel::from_preset(background);
+            panel.start.groups.clear();
+            panel.center.groups.clear();
+            panel.end.groups = (0..MAX_GROUPS)
+                .map(|i| Group::new(&format!("group-{i}"), Vec::new(), [2, 3], 4.))
+                .collect();
+            assert_eq!(panel.group_count(), MAX_GROUPS);
+            validate(std::slice::from_ref(&panel)).unwrap();
+            panel
+                .start
+                .groups
+                .push(Group::new("one-too-many", Vec::new(), [2, 3], 4.));
+            assert!(validate(&[panel]).unwrap_err().contains("31 groups"));
+        }
+    }
+
+    #[test]
+    fn defaults_preserve_order_and_ids_across_background_changes() {
+        let continuous = Panel::default();
+        let islands = Panel::from_preset(PanelStyle::Floating);
+        let expected = [
+            "overview",
+            "workspaces",
+            "focused-window",
+            "media",
+            "quick-settings",
+            "night-light",
+            "network",
+            "audio",
+            "recording",
+            "notifications",
+            "battery",
+            "clock",
+            "display-mode",
+        ];
+        for panel in [&continuous, &islands] {
+            let ids: Vec<_> = items(panel).iter().map(|item| item.id.0.as_str()).collect();
+            assert_eq!(ids, expected);
+            assert_eq!(Panel::from_preset(panel.preset().unwrap()), *panel);
+        }
+        assert_eq!(continuous.start.groups.len(), 2);
+        assert_eq!(continuous.end.groups.len(), 3);
+        assert_eq!(islands.start.groups.len(), 1);
+        assert_eq!(islands.end.groups.len(), 1);
+        assert!(!islands.border && !continuous.border);
+    }
+
+    #[test]
+    fn availability_filters_without_removing_or_reidentifying_instances() {
+        let panel = Panel::default();
+        let all = items(&panel);
+        let visible = |availability| {
+            all.iter()
+                .filter(|item| item.available(availability))
+                .map(|item| item.id.0.as_str())
+                .collect::<Vec<_>>()
+        };
+        assert_eq!(
+            visible(Availability::default()),
+            [
+                "overview",
+                "workspaces",
+                "focused-window",
+                "quick-settings",
+                "night-light",
+                "recording",
+                "clock"
+            ]
+        );
+        assert_eq!(
+            visible(Availability {
+                activities: true,
+                media: true,
+                network: true,
+                audio: true,
+                notifications: true,
+                battery: true,
+                external_display: true
+            }),
+            all.iter()
+                .map(|item| item.id.0.as_str())
+                .collect::<Vec<_>>()
+        );
+        assert_eq!(items(&panel).len(), 13);
+    }
+
+    #[test]
+    fn settings_map_to_instances_and_group_presentation() {
+        let mut panel = Panel::from_preset(PanelStyle::Floating);
+        panel.center.groups[0].items[0].visible = false;
+        let battery = panel.end.groups[0]
+            .items
+            .iter_mut()
+            .find(|item| item.id.0 == "battery")
+            .unwrap();
+        battery.kind = ItemKind::Battery { percentage: false };
+        for group in [&mut panel.start, &mut panel.center, &mut panel.end]
+            .into_iter()
+            .flat_map(|zone| &mut zone.groups)
+        {
+            group.island_padding = 13.;
+        }
+        assert_eq!(
+            panel.center.groups[0].items[0].kind,
+            ItemKind::FocusedWindow
+        );
+        assert!(!panel.center.groups[0].items[0].visible);
+        let all = items(&panel);
+        assert_eq!(
+            all.iter().find(|item| item.id.0 == "battery").unwrap().kind,
+            ItemKind::Battery { percentage: false }
+        );
+        for zone in [&panel.start, &panel.center, &panel.end] {
+            for group in &zone.groups {
+                assert_eq!(group.island_padding, 13.0);
+            }
+        }
+        assert_eq!(
+            all.iter()
+                .find(|item| item.id.0 == "clock")
+                .unwrap()
+                .gap_before,
+            None
+        );
+    }
+
+    #[test]
+    fn two_clock_instances_have_distinct_identity() {
+        let first = Item::new("main-clock", ItemKind::Clock);
+        let second = Item::new("other-clock", ItemKind::Clock);
+        assert_eq!(first.kind, second.kind);
+        assert_ne!(first.id, second.id);
+    }
+    #[test]
+    fn removed_item_fields_are_rejected() {
+        for value in [
+            serde_json::json!({"id":"title", "kind":"focused-window", "enabled":false}),
+            serde_json::json!({"id":"spaces", "kind":"workspaces", "workspace_style":"numbers"}),
+        ] {
+            assert!(serde_json::from_value::<Item>(value).is_err());
+        }
+    }
+
+    #[test]
+    fn surface_changes_only_replace_composition_when_item_geometry_changes() {
+        let panel = Panel::default();
+        let mut changed = panel.clone();
+        changed.style = PanelStyle::Flat;
+        assert!(panel.same_composition(&changed));
+        changed.style = PanelStyle::Floating;
+        assert!(!panel.same_composition(&changed));
+        changed.style = PanelStyle::Flat;
+        assert!(panel.same_composition(&changed));
+        changed.end.groups[0].padding[1] += 1;
+        assert!(!panel.same_composition(&changed));
+    }
+}
diff --git a/crates/ferese-theme-model/src/lib.rs b/crates/ferese-theme-model/src/lib.rs
index dd4f0c2..d70d53c 100644
--- a/crates/ferese-theme-model/src/lib.rs
+++ b/crates/ferese-theme-model/src/lib.rs
@@ -1,179 +1,7 @@
-use serde::{Deserialize, Serialize};
-use std::path::PathBuf;
+//! Theme values shared by the compositor, shell and Settings.
 mod color;
 pub mod families;
+mod resolved_theme;
+
 pub use color::*;
-
-#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
-#[serde(rename_all = "lowercase")]
-pub enum Appearance {
-    Light,
-    #[default]
-    Dark,
-}
-
-#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
-#[serde(rename_all = "lowercase")]
-pub enum Mode {
-    Light,
-    #[default]
-    Dark,
-    Auto,
-}
-
-#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
-#[serde(default)]
-pub struct Accessibility {
-    pub increase_contrast: bool,
-    pub reduce_transparency: bool,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Colors {
-    pub surface_base: String,
-    pub surface_raised: String,
-    pub application_background: String,
-    pub text_primary: String,
-    pub text_muted: String,
-    pub accent: String,
-    pub on_accent: String,
-    pub border: String,
-    pub shadow: String,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Material {
-    pub style: String,
-    pub opacity: f64,
-    pub blur_radius: f64,
-    pub tint_strength: f64,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Geometry {
-    pub border_width: f64,
-    pub focus_ring_width: f64,
-    pub window_radius: f64,
-    pub shell_radius: f64,
-    pub control_gap: f64,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Typography {
-    pub font_family: String,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Background {
-    pub path: Option<PathBuf>,
-    pub lock_path: Option<PathBuf>,
-    pub mode: String,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct BarSurface {
-    pub background: String,
-    pub text_primary: String,
-    pub text_muted: String,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Surfaces {
-    pub bar: BarSurface,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct SoftShadow {
-    pub offset_y: f64,
-    pub blur: f64,
-    pub opacity: f64,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Shadows {
-    pub soft: SoftShadow,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Gradient {
-    pub from: String,
-    pub to: String,
-    pub angle: f64,
-}
-
-#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
-#[serde(rename_all = "lowercase")]
-pub enum PaintStyle {
-    #[default]
-    Auto,
-    Solid,
-}
-
-impl PaintStyle {
-    fn is_auto(&self) -> bool {
-        *self == Self::Auto
-    }
-}
-
-#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq)]
-pub struct Paint {
-    #[serde(default, skip_serializing_if = "PaintStyle::is_auto")]
-    pub style: PaintStyle,
-    pub gradient: Option<Gradient>,
-}
-
-impl Paint {
-    pub fn effective_gradient(&self) -> Option<&Gradient> {
-        if self.style == PaintStyle::Solid {
-            None
-        } else {
-            self.gradient.as_ref()
-        }
-    }
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct Tokens {
-    pub colors: Colors,
-    pub material: Material,
-    pub geometry: Geometry,
-    pub typography: Typography,
-    pub background: Background,
-    pub surface: Surfaces,
-    pub shadow: Shadows,
-    pub border: Paint,
-    pub focus_ring: Paint,
-}
-
-#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
-pub struct ResolvedTheme {
-    pub appearance: Appearance,
-    pub tokens: Tokens,
-    pub requested_accent: String,
-    pub accessibility: Accessibility,
-    pub reduced_motion: bool,
-}
-
-/// Accessibility takes precedence over a panel's authored opacity.
-pub fn effective_panel_opacity(
-    inherited: f32,
-    custom: Option<f32>,
-    reduce_transparency: bool,
-) -> f32 {
-    if reduce_transparency {
-        1.0
-    } else {
-        custom.unwrap_or(inherited)
-    }
-}
-
-impl ResolvedTheme {
-    pub fn panel_opacity(&self, custom: Option<f32>) -> f32 {
-        let inherited = if self.tokens.material.style == "translucent" {
-            self.tokens.material.opacity as f32
-        } else {
-            1.0
-        };
-        effective_panel_opacity(inherited, custom, self.accessibility.reduce_transparency)
-    }
-}
+pub use resolved_theme::*;
diff --git a/crates/ferese-theme-model/src/resolved_theme.rs b/crates/ferese-theme-model/src/resolved_theme.rs
new file mode 100644
index 0000000..3cfa504
--- /dev/null
+++ b/crates/ferese-theme-model/src/resolved_theme.rs
@@ -0,0 +1,177 @@
+use std::path::PathBuf;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Appearance {
+    Light,
+    #[default]
+    Dark,
+}
+
+#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum Mode {
+    Light,
+    #[default]
+    Dark,
+    Auto,
+}
+
+#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(default)]
+pub struct Accessibility {
+    pub increase_contrast: bool,
+    pub reduce_transparency: bool,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Colors {
+    pub surface_base: String,
+    pub surface_raised: String,
+    pub application_background: String,
+    pub text_primary: String,
+    pub text_muted: String,
+    pub accent: String,
+    pub on_accent: String,
+    pub border: String,
+    pub shadow: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Material {
+    pub style: String,
+    pub opacity: f64,
+    pub blur_radius: f64,
+    pub tint_strength: f64,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Geometry {
+    pub border_width: f64,
+    pub focus_ring_width: f64,
+    pub window_radius: f64,
+    pub shell_radius: f64,
+    pub control_gap: f64,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Typography {
+    pub font_family: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Background {
+    pub path: Option<PathBuf>,
+    pub lock_path: Option<PathBuf>,
+    pub mode: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct BarSurface {
+    pub background: String,
+    pub text_primary: String,
+    pub text_muted: String,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Surfaces {
+    pub bar: BarSurface,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct SoftShadow {
+    pub offset_y: f64,
+    pub blur: f64,
+    pub opacity: f64,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Shadows {
+    pub soft: SoftShadow,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Gradient {
+    pub from: String,
+    pub to: String,
+    pub angle: f64,
+}
+
+#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
+#[serde(rename_all = "lowercase")]
+pub enum PaintStyle {
+    #[default]
+    Auto,
+    Solid,
+}
+
+impl PaintStyle {
+    fn is_auto(&self) -> bool {
+        *self == Self::Auto
+    }
+}
+
+#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq)]
+pub struct Paint {
+    #[serde(default, skip_serializing_if = "PaintStyle::is_auto")]
+    pub style: PaintStyle,
+    pub gradient: Option<Gradient>,
+}
+
+impl Paint {
+    pub fn effective_gradient(&self) -> Option<&Gradient> {
+        if self.style == PaintStyle::Solid {
+            None
+        } else {
+            self.gradient.as_ref()
+        }
+    }
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct Tokens {
+    pub colors: Colors,
+    pub material: Material,
+    pub geometry: Geometry,
+    pub typography: Typography,
+    pub background: Background,
+    pub surface: Surfaces,
+    pub shadow: Shadows,
+    pub border: Paint,
+    pub focus_ring: Paint,
+}
+
+#[derive(Clone, Debug, Deserialize, Serialize, PartialEq)]
+pub struct ResolvedTheme {
+    pub appearance: Appearance,
+    pub tokens: Tokens,
+    pub requested_accent: String,
+    pub accessibility: Accessibility,
+    pub reduced_motion: bool,
+}
+
+/// Accessibility takes precedence over a panel's authored opacity.
+pub fn effective_panel_opacity(
+    inherited: f32,
+    custom: Option<f32>,
+    reduce_transparency: bool,
+) -> f32 {
+    if reduce_transparency {
+        1.0
+    } else {
+        custom.unwrap_or(inherited)
+    }
+}
+
+impl ResolvedTheme {
+    pub fn panel_opacity(&self, custom: Option<f32>) -> f32 {
+        let inherited = if self.tokens.material.style == "translucent" {
+            self.tokens.material.opacity as f32
+        } else {
+            1.0
+        };
+        effective_panel_opacity(inherited, custom, self.accessibility.reduce_transparency)
+    }
+}
diff --git a/docs/animation-model.md b/docs/animation-model.md
index 6280436..dad7f65 100644
--- a/docs/animation-model.md
+++ b/docs/animation-model.md
@@ -6,7 +6,7 @@ How that movement behaves depends on what you’re doing. While dragging, the wi
 
 ## Keeping layout, animation, and application buffers in step
 
-The resize example explains why [WindowGeometry](../crates/ferese-animation/src/lib.rs) keeps three states. Its logical rectangle records the destination requested by layout or a presentation mode, such as fullscreen. Its visual rectangle records what is moving toward that destination, including the current bounds and velocity. Client geometry tracks the size Ferese requested from the application and the size the application has committed.
+The resize example explains why [WindowGeometry](../crates/ferese-animation/src/window_geometry.rs) keeps three states. Its logical rectangle records the destination requested by layout or a presentation mode, such as fullscreen. Its visual rectangle records what is moving toward that destination, including the current bounds and velocity. Client geometry tracks the size Ferese requested from the application and the size the application has committed.
 
 Keeping these separate means the compositor can request the destination size as soon as the layout changes. It does not have to wait for the animation to finish before asking the application to draw. The new buffer might arrive before or after the visible rectangle settles, so retained images cover the resize handoff while presentation continues independently.
 
@@ -130,7 +130,7 @@ After settlement, hover redraws reuse animation content when the motion sample h
 
 ## Checking the model against what is drawn
 
-The [animation trace tests](../crates/ferese-animation/src/traces.rs) follow motion through stalls, changing frame cadence, retargeting, resize interruption, and gesture release. Solver tests compare the results with an independent characteristic-root reference, while gesture tests check projection and the rubber-band derivative. Compositor tests then check how that motion is used for presentation ownership, predicted geometry, workspace switching, and reduced motion.
+The [animation trace tests](../crates/ferese-animation/src/window_geometry/traces.rs) follow motion through stalls, changing frame cadence, retargeting, resize interruption, and gesture release. Solver tests compare the results with an independent characteristic-root reference, while gesture tests check projection and the rubber-band derivative. Compositor tests then check how that motion is used for presentation ownership, predicted geometry, workspace switching, and reduced motion.
 
 Rendering checks need to follow the interruptions people can make while using the desktop: reversing a transition, clicking several overview workspaces, closing during resize, or selecting a shell panel before the previous motion settles. At fractional output scales, those checks must also look for separation between content, clip, and border, and for background or blur remaining after shell content exits. Frame traces should confirm that animation requests stop after settlement.
 
diff --git a/feresectl/src/activities/setup.rs b/feresectl/src/activities/setup.rs
index 8dc2e29..c49961d 100644
--- a/feresectl/src/activities/setup.rs
+++ b/feresectl/src/activities/setup.rs
@@ -6,7 +6,7 @@ use std::path::Path;
 
 fn prepare(source: &str) -> Result<String, Box<dyn Error>> {
     let mut doc = Document::parse(source)?;
-    if !ferese_config::activities::setup_shell_hook(&mut doc)? {
+    if !doc.setup_shell_hook()? {
         return Ok(source.into());
     }
     if doc.get("panels").is_none() {