use std::fs;
 use serde_json::Value;
 
 /// A unit-annotated number (`width=(mm)2.0`, `(px)9.3`, `(in)0.5`,
 /// `(pt)6`) becomes the JSON string `"2mm"` — the form
 /// `crate::units::Len::parse` reads — so the unit survives the JSON hop
 /// into the style registry, where it resolves against the live metric at
 /// every read. A bare number stays a number: a logical px, as always.
 fn unit_entry_to_json(value: f64, entry: &kdl::KdlEntry) -> Option<serde_json::Value> {
     let ty = entry.ty()?.value();
     let len = crate::units::Len::from_annotated(value as f32, ty)?;
     Some(serde_json::Value::String(len.serialize()))
 }
 
 fn int_entry_to_json(value: i64, entry: &kdl::KdlEntry) -> serde_json::Value {
     unit_entry_to_json(value as f64, entry)
         .unwrap_or_else(|| serde_json::Value::Number(serde_json::Number::from(value)))
 }
 
 fn float_entry_to_json(value: f64, entry: &kdl::KdlEntry) -> serde_json::Value {
     if let Some(v) = unit_entry_to_json(value, entry) {
         return v;
     }
     let mut val_f = value;
     if let Some(ty) = entry.ty() {
         let ty_str = ty.value();
         if let Some(range_str) = ty_str.strip_prefix("f64:") {
             if let Some(dash_idx) = range_str.find('-') {
                 let min_str = range_str[..dash_idx].trim();
                 let max_str = range_str[dash_idx + 1..].trim();
                 if let (Ok(min_f), Ok(max_f)) = (min_str.parse::<f64>(), max_str.parse::<f64>()) {
                     val_f = val_f.clamp(min_f, max_f);
                 }
             }
         }
     }
     match serde_json::Number::from_f64(val_f) {
         Some(num) => serde_json::Value::Number(num),
         None => serde_json::Value::Null,
     }
 }
 
 fn kdl_to_json(doc: &kdl::KdlDocument) -> serde_json::Value {
     let mut map = serde_json::Map::new();
     for node in doc.nodes() {
         let name = node.name().value().to_string();
         
         let mut node_map = serde_json::Map::new();
         let mut has_props = false;
         for entry in node.entries() {
             if let Some(prop_name) = entry.name() {
                 has_props = true;
                 let j_val = match entry.value() {
                     kdl::KdlValue::Bool(b) => serde_json::Value::Bool(*b),
                     kdl::KdlValue::Base2(i) |
                     kdl::KdlValue::Base8(i) |
                     kdl::KdlValue::Base10(i) |
                     kdl::KdlValue::Base16(i) => int_entry_to_json(*i, entry),
                     kdl::KdlValue::Base10Float(f) => float_entry_to_json(*f, entry),
                     kdl::KdlValue::String(s) |
                     kdl::KdlValue::RawString(s) => serde_json::Value::String(s.clone()),
                     kdl::KdlValue::Null => serde_json::Value::Null,
                 };
                 node_map.insert(prop_name.value().to_string(), j_val);
             }
         }
 
         let val = if name == "key_bindings" {
             if let Some(children) = node.children() {
                 let mut binds = Vec::new();
                 for child in children.nodes() {
                     let mut child_map = serde_json::Map::new();
                     for entry in child.entries() {
                         if let Some(prop_name) = entry.name() {
                             let j_val = match entry.value() {
                                 kdl::KdlValue::Bool(b) => serde_json::Value::Bool(*b),
                                 kdl::KdlValue::Base2(i) |
                                 kdl::KdlValue::Base8(i) |
                                 kdl::KdlValue::Base10(i) |
                                 kdl::KdlValue::Base16(i) => int_entry_to_json(*i, entry),
                                 kdl::KdlValue::Base10Float(f) => float_entry_to_json(*f, entry),
                                 kdl::KdlValue::String(s) |
                                 kdl::KdlValue::RawString(s) => serde_json::Value::String(s.clone()),
                                 kdl::KdlValue::Null => serde_json::Value::Null,
                             };
                             child_map.insert(prop_name.value().to_string(), j_val);
                         }
                     }
                     binds.push(serde_json::Value::Object(child_map));
                 }
                 serde_json::Value::Array(binds)
             } else if has_props {
                 serde_json::Value::Object(node_map)
             } else {
                 serde_json::Value::Null
             }
         } else {
             let mut node_val = serde_json::Value::Null;
             if has_props {
                 node_val = serde_json::Value::Object(node_map);
             } else if node.entries().len() > 1
                 && node.entries().iter().all(|e| matches!(e.value(), kdl::KdlValue::String(_) | kdl::KdlValue::RawString(_)))
             {
                 // A string LIST (`rounded_apps "a" "b"`) is an array, so the
                 // writer can put the args back. Joined into one string, as the
                 // numeric multi-arg case below still is (`(vec2i)100 200`),
                 // it came back as ONE quoted arg — `rounded_apps "a b"` — and
                 // a compositor allowlist silently matched nothing after
                 // every cce-data-editor save.
                 node_val = serde_json::Value::Array(
                     node.entries()
                         .iter()
                         .filter_map(|e| e.value().as_string().map(|s| serde_json::Value::String(s.to_string())))
                         .collect(),
                 );
             } else if node.entries().len() > 1 {
                 let parts: Vec<String> = node.entries().iter().map(|entry| {
                     match entry.value() {
                         kdl::KdlValue::Bool(b) => b.to_string(),
                         kdl::KdlValue::Base2(i) |
                         kdl::KdlValue::Base8(i) |
                         kdl::KdlValue::Base10(i) |
                         kdl::KdlValue::Base16(i) => i.to_string(),
                         kdl::KdlValue::Base10Float(f) => f.to_string(),
                         kdl::KdlValue::String(s) |
                         kdl::KdlValue::RawString(s) => s.clone(),
                         kdl::KdlValue::Null => "null".to_string(),
                     }
                 }).collect();
                 node_val = serde_json::Value::String(parts.join(" "));
             } else if let Some(entry) = node.entries().first() {
                 node_val = match entry.value() {
                     kdl::KdlValue::Bool(b) => serde_json::Value::Bool(*b),
                     kdl::KdlValue::Base2(i) |
                     kdl::KdlValue::Base8(i) |
                     kdl::KdlValue::Base10(i) |
                     kdl::KdlValue::Base16(i) => int_entry_to_json(*i, entry),
                     kdl::KdlValue::Base10Float(f) => float_entry_to_json(*f, entry),
                     kdl::KdlValue::String(s) |
                     kdl::KdlValue::RawString(s) => serde_json::Value::String(s.clone()),
                     kdl::KdlValue::Null => serde_json::Value::Null,
                 };
             }
 
             if let Some(children) = node.children() {
                 let children_val = kdl_to_json(children);
                 if let serde_json::Value::Object(children_map) = children_val {
                     if let serde_json::Value::Object(mut nm) = node_val {
                         for (k, v) in children_map {
                             nm.insert(k, v);
                         }
                         serde_json::Value::Object(nm)
                     } else {
                         serde_json::Value::Object(children_map)
                     }
                 } else {
                     node_val
                 }
             } else {
                 node_val
             }
         };
 
         if let Some(existing) = map.remove(&name) {
             match existing {
                 serde_json::Value::Array(mut arr) => {
                     match val {
                         serde_json::Value::Array(new_arr) => {
                             arr.extend(new_arr);
                         }
                         _ => {
                             arr.push(val);
                         }
                     }
                     map.insert(name, serde_json::Value::Array(arr));
                 }
                 other => {
                     match val {
                         serde_json::Value::Array(new_arr) => {
                             let mut combined = vec![other];
                             combined.extend(new_arr);
                             map.insert(name, serde_json::Value::Array(combined));
                         }
                         _ => {
                             map.insert(name, serde_json::Value::Array(vec![other, val]));
                         }
                     }
                 }
             }
         } else {
             let list_names = ["key_bindings", "pointer_bind", "gesture_bind", "mode_rule", "tag_layout", "startup", "device"];
             if list_names.contains(&name.as_str()) {
                 match val {
                     serde_json::Value::Array(_) => {
                         map.insert(name, val);
                     }
                     _ => {
                         map.insert(name, serde_json::Value::Array(vec![val]));
                     }
                 }
             } else {
                 map.insert(name, val);
             }
         }
     }
     serde_json::Value::Object(map)
 }
 
 /// The calling app's name — the basename of its executable — used to locate
 /// its per-app config (`~/.config/cce/<name>/config.kdl`) and its `input.kdl`
 /// domain.
 ///
 /// Derived from `/proc/self/exe` once per process, which the kernel renders as
 /// `<path> (deleted)` once the binary on disk has been replaced (`ccebuild
 /// install` unlinks before writing). Without the strip, a still-running client
 /// would resolve its override to `~/.config/cce/<name> (deleted)/config.kdl`
 /// on its next config reload and silently lose the whole file — the status
 /// bar's droplet bubbles reverted to square boxes this way on 2026-09-03.
 ///
 /// Cached because every config getter reaches it (through
 /// [`config_files_modified`]), many of them per frame; the stripped basename
 /// cannot change for the life of the process.
 pub fn get_app_name() -> Option<String> {
     app_name().map(str::to_string)
 }
 
 /// [`get_app_name`] without the allocation.
 fn app_name() -> Option<&'static str> {
     static NAME: std::sync::OnceLock<Option<String>> = std::sync::OnceLock::new();
     NAME.get_or_init(|| {
         std::env::current_exe()
             .ok()
             .and_then(|p| p.file_name().and_then(|s| s.to_str().map(app_name_from_exe_basename)))
     })
     .as_deref()
 }
 
 /// [`get_app_name`]'s normalization: the kernel's ` (deleted)` marker on an
 /// unlinked executable is not part of the name.
 fn app_name_from_exe_basename(basename: &str) -> String {
     basename.strip_suffix(" (deleted)").unwrap_or(basename).to_string()
 }
 
 pub fn get_app_config_path(app_name: &str) -> std::path::PathBuf {
     get_config_path().parent().unwrap().join(app_name).join("config.kdl")
 }
 
 fn merge_json(a: &mut serde_json::Value, b: &serde_json::Value) {
     match (a, b) {
         (serde_json::Value::Object(a_map), serde_json::Value::Object(b_map)) => {
             for (k, v) in b_map {
                 if !v.is_null() {
                     merge_json(a_map.entry(k.clone()).or_insert(serde_json::Value::Null), v);
                 }
             }
         }
         (a_val, b_val) => {
             *a_val = b_val.clone();
         }
     }
 }
 
 pub fn parse_kdl_to_json(content: &str) -> serde_json::Value {
     let mut main_val = if let Ok(doc) = content.parse::<kdl::KdlDocument>() {
         kdl_to_json(&doc)
     } else {
         serde_json::json!({})
     };
 
     if let Some(app_name) = app_name() {
         let app_path = get_app_config_path(app_name);
         if let Ok(override_content) = std::fs::read_to_string(&app_path) {
             if let Ok(override_doc) = override_content.parse::<kdl::KdlDocument>() {
                 let override_val = kdl_to_json(&override_doc);
                 merge_json(&mut main_val, &override_val);
             }
         }
     }
 
     main_val
 }
 
 pub fn update_json_in_memory(val_obj: &mut Value, key: &str, value: &str, default_section: &str) -> bool {
     let j_val = if let Ok(parsed_val) = serde_json::from_str::<Value>(value) {
         parsed_val
     } else {
         serde_json::json!(value)
     };
 
     let mut updated = false;
     if let Some(obj) = val_obj.as_object_mut() {
         for (_sec_name, sec_val) in obj.iter_mut() {
             if let Some(sec_obj) = sec_val.as_object_mut() {
                 if sec_obj.contains_key(key) {
                     sec_obj.insert(key.to_string(), j_val.clone());
                     updated = true;
                     break;
                 }
             }
         }
         if !updated {
             if let Some(sec_obj) = obj.get_mut(default_section).and_then(|s| s.as_object_mut()) {
                 sec_obj.insert(key.to_string(), j_val);
                 updated = true;
             } else {
                 let mut map = serde_json::Map::new();
                 map.insert(key.to_string(), j_val);
                 obj.insert(default_section.to_string(), Value::Object(map));
                 updated = true;
             }
         }
     }
     updated
 }
 
 pub fn parse_config_path(key: &str, default_section: &str) -> (String, String, Option<String>) {
     let parts: Vec<&str> = key.split('.').collect();
     if parts.len() == 3 {
         (parts[0].to_string(), parts[1].to_string(), Some(parts[2].to_string()))
     } else if parts.len() == 2 {
         (parts[0].to_string(), parts[1].to_string(), None)
     } else {
         (default_section.to_string(), key.to_string(), None)
     }
 }
 
 const PROP_NODES: &[&str] = &[
     "gestures", "key_bindings", "pointer_bind", "gesture_bind",
     "button", "button_strip", "dropdown", "toggle", "spinbox", "slider", "font_selector",
     "status", "overlay", "root", "desktop", "list", "section", "textbox", "multiline", "editor", "tree",
     "menubar", "statusbar", "node", "relief", "frost", "finish",
     // The relief's two shapes (`relief { wall height=… profile=… knobs=… ; edge … }`).
     "wall", "edge"
 ];
 
 fn get_node_mut<'a>(doc: &'a mut kdl::KdlDocument, path: &[&str]) -> Option<&'a mut kdl::KdlNode> {
     if path.is_empty() {
         return None;
     }
     let idx = doc.nodes().iter().position(|n| n.name().value() == path[0])?;
     let node = &mut doc.nodes_mut()[idx];
     if path.len() == 1 {
         Some(node)
     } else {
         get_node_mut(node.children_mut().as_mut()?, &path[1..])
     }
 }
 
 /// Remove `key` from the document — a property off its `PROP_NODES` node, or
 /// the whole node otherwise — creating nothing on the way. `true` when
 /// something was removed; a key that is not there is `false`, so a writer
 /// can tell "migrated" from "was already clean".
 pub fn remove_kdl_in_memory(doc: &mut kdl::KdlDocument, key: &str) -> bool {
     let parts: Vec<&str> = key.split('.').collect();
     let Some(leaf) = parts.last().copied() else {
         return false;
     };
     // A PROP_NODES parent holds its keys as properties — but it may also
     // hold child NODES (`relief { wall … }`), so a leaf that is not among
     // the properties is looked for among the children before giving up.
     let is_property = parts.len() >= 2 && PROP_NODES.contains(&parts[parts.len() - 2]);
     if is_property {
         let Some(node) = get_node_mut(doc, &parts[..parts.len() - 1]) else {
             return false;
         };
         let before = node.entries().len();
         node.entries_mut().retain(|e| e.name().map(|n| n.value()) != Some(leaf));
         if node.entries().len() != before {
             return true;
         }
     }
     let parent: &mut kdl::KdlDocument = if parts.len() == 1 {
         doc
     } else {
         match get_node_mut(doc, &parts[..parts.len() - 1]).and_then(|n| n.children_mut().as_mut()) {
             Some(children) => children,
             None => return false,
         }
     };
     let before = parent.nodes().len();
     parent.nodes_mut().retain(|n| n.name().value() != leaf);
     parent.nodes().len() != before
 }
 
 fn get_or_create_node_mut<'a>(doc: &'a mut kdl::KdlDocument, path: &[&str]) -> Option<&'a mut kdl::KdlNode> {
     if path.is_empty() {
         return None;
     }
     let segment = path[0];
     let idx = if let Some(i) = doc.nodes().iter().position(|n| n.name().value() == segment) {
         i
     } else {
         let new_node = format!("{}\n", segment).parse::<kdl::KdlNode>().ok()?;
         doc.nodes_mut().push(new_node);
         doc.nodes().len() - 1
     };
     if path.len() == 1 {
         Some(&mut doc.nodes_mut()[idx])
     } else {
         let children = doc.nodes_mut()[idx].ensure_children();
         get_or_create_node_mut(children, &path[1..])
     }
 }
 
 fn get_node_ref<'a>(doc: &'a kdl::KdlDocument, path: &[&str]) -> Option<&'a kdl::KdlNode> {
     if path.is_empty() {
         return None;
     }
     let segment = path[0];
     let node = doc.nodes().iter().find(|n| n.name().value() == segment)?;
     if path.len() == 1 {
         Some(node)
     } else {
         let children = node.children()?;
         get_node_ref(children, &path[1..])
     }
 }
 
 pub fn update_kdl_in_memory(doc: &mut kdl::KdlDocument, key: &str, value: &str, default_section: &str) -> bool {
     update_kdl_in_memory_typed(doc, key, value, default_section, None)
 }
 
 /// [`update_kdl_in_memory`] with an explicit type annotation for the written
 /// entry. `forced_ty` overrides both the value-shape inference and the
 /// preserved existing annotation — how a writer ESTABLISHES a custom type
 /// (e.g. cce-relief writing `(bevel)` knob keys into a config that never had
 /// them; preservation alone can't create the annotation).
 pub fn update_kdl_in_memory_typed(doc: &mut kdl::KdlDocument, key: &str, value: &str, _default_section: &str, forced_ty: Option<&str>) -> bool {
     let parts: Vec<&str> = key.split('.').collect();
     if parts.is_empty() {
         return false;
     }
 
     let is_property = parts.len() >= 2 && PROP_NODES.contains(&parts[parts.len() - 2]);
 
     let (node_path, target_prop) = if is_property {
         (&parts[0..parts.len() - 1], Some(parts[parts.len() - 1].to_string()))
     } else {
         (&parts[0..parts.len()], None)
     };
 
     let child_node = if let Some(node) = get_or_create_node_mut(doc, node_path) {
         node
     } else {
         return false;
     };
 
     let existing_ty = if let Some(ref prop_name) = target_prop {
         child_node.entries().iter()
             .find(|e| e.name().map(|n| n.value()) == Some(prop_name))
             .and_then(|e| e.ty().map(|t| t.value().to_string()))
     } else {
         child_node.entries().first()
             .and_then(|e| e.ty().map(|t| t.value().to_string()))
     };
 
     let (kdl_val, mut kdl_ty) = if let Ok(b) = value.parse::<bool>() {
         (kdl::KdlValue::Bool(b), Some("bool".to_string()))
     } else if let Some(len) = crate::units::Len::parse(value) {
         // `2mm` → `(mm)2.0`: the unit rides as the annotation, the value
         // stays a number the editor's spinbox can step.
         (kdl::KdlValue::Base10Float(len.value as f64), Some(len.unit.suffix().to_string()))
     } else if value.starts_with('#') {
         let s_clean = value.trim_start_matches('#');
         let ty = if s_clean.len() == 8 { "rgba" } else { "rgb" };
         (kdl::KdlValue::String(value.to_string()), Some(ty.to_string()))
     } else if value.contains('.') {
         if let Ok(f) = value.parse::<f64>() {
             (kdl::KdlValue::Base10Float(f), Some("f64".to_string()))
         } else {
             (kdl::KdlValue::String(value.to_string()), None)
         }
     } else if let Ok(i) = value.parse::<i64>() {
         (kdl::KdlValue::Base10(i), Some("i64".to_string()))
     } else {
         let s = value.trim_matches('"').to_string();
         (kdl::KdlValue::String(s), None)
     };
 
     if let Some(ref ext_ty) = existing_ty {
         if ext_ty.starts_with("menu:") || ext_ty == "button" || ext_ty.starts_with("button:") || ext_ty == "vec2i" || ext_ty == "radian" || ext_ty == "bevel" || ext_ty == "keybind" {
             kdl_ty = Some(ext_ty.clone());
         }
         // A bare number written over a unit-annotated slot keeps the unit:
         // typing 3 into a `(mm)` field means 3 mm, not a silent fall back
         // to logical px.
         if crate::units::Unit::parse(ext_ty).is_some() && matches!(kdl_val, kdl::KdlValue::Base10Float(_) | kdl::KdlValue::Base10(_)) && kdl_ty.as_deref().is_none_or(|t| t == "f64" || t == "i64") {
             kdl_ty = Some(ext_ty.clone());
         }
     }
     if let Some(f) = forced_ty {
         kdl_ty = Some(f.to_string());
     }
 
     if let Some(prop_name) = target_prop {
         let mut found = false;
         for entry in child_node.entries_mut() {
             if let Some(id) = entry.name() {
                 if id.value() == prop_name {
                     *entry = kdl::KdlEntry::new_prop(prop_name.clone(), kdl_val.clone());
                     if let Some(ref ty) = kdl_ty {
                         entry.set_ty(ty.as_str());
                     }
                     found = true;
                     break;
                 }
             }
         }
         if !found {
             let mut entry = kdl::KdlEntry::new_prop(prop_name, kdl_val);
             if let Some(ref ty) = kdl_ty {
                 entry.set_ty(ty.as_str());
             }
             child_node.entries_mut().push(entry);
         }
     } else {
         child_node.entries_mut().clear();
         if kdl_ty.as_deref() == Some("vec2i") {
             let parts: Vec<&str> = value.split_whitespace().collect();
             for (idx, part) in parts.iter().enumerate() {
                 if let Ok(i) = part.parse::<i64>() {
                     let mut entry = kdl::KdlEntry::new(kdl::KdlValue::Base10(i));
                     if idx == 0 {
                         entry.set_ty("vec2i");
                     }
                     child_node.entries_mut().push(entry);
                 }
             }
         } else {
             let mut entry = kdl::KdlEntry::new(kdl_val);
             if let Some(ref ty) = kdl_ty {
                 entry.set_ty(ty.as_str());
             }
             child_node.entries_mut().push(entry);
         }
     }
 
     true
 }
 
 /// XDG config base directory: `$XDG_CONFIG_HOME`, else `~/.config`.
 ///
 /// Under this crate's own tests it is a per-process directory nobody
 /// creates, so every config read (`config.kdl`, a per-app override,
 /// `input.kdl`) finds no file and the toolkit's defaults are what a test
 /// sees. Until 2026-10-07 the tests read the machine's `~/.config/cce`:
 /// six of them failed on the user's desktop (a `relief edge height` pinned
 /// the plate rise the heightfield tests set; the frost and blur keys moved
 /// the material ones) and passed on a machine without that config. A test
 /// that wants a configuration loads it from a string (`reload_colors`).
 /// Dependents' tests link the non-test build and are unaffected.
 pub fn config_home() -> std::path::PathBuf {
     #[cfg(any(test, feature = "test-isolation"))]
     {
         return std::env::temp_dir().join(format!("cce-ui-test-config-{}", std::process::id()));
     }
     #[allow(unreachable_code)]
     match std::env::var("XDG_CONFIG_HOME") {
         Ok(x) if !x.is_empty() => std::path::PathBuf::from(x),
         _ => std::path::PathBuf::from(std::env::var("HOME").unwrap_or_default()).join(".config"),
     }
 }
 
 /// XDG data base directory: `$XDG_DATA_HOME`, else `~/.local/share`.
 pub fn data_home() -> std::path::PathBuf {
     match std::env::var("XDG_DATA_HOME") {
         Ok(x) if !x.is_empty() => std::path::PathBuf::from(x),
         _ => std::path::PathBuf::from(std::env::var("HOME").unwrap_or_default())
             .join(".local")
             .join("share"),
     }
 }
 
 /// XDG state base directory: `$XDG_STATE_HOME`, else `~/.local/state`.
 ///
 /// State is what should survive a restart but is not worth backing up or
 /// syncing like data, and is not the user's to edit like config: history,
 /// open tabs, logs, a "never ask again" list. A relative `$XDG_STATE_HOME`
 /// counts as unset, as the XDG spec says it must (an empty one too).
 pub fn state_home() -> std::path::PathBuf {
     match std::env::var_os("XDG_STATE_HOME").map(std::path::PathBuf::from) {
         Some(x) if x.is_absolute() => x,
         _ => std::path::PathBuf::from(std::env::var("HOME").unwrap_or_default())
             .join(".local")
             .join("state"),
     }
 }
 
 /// XDG runtime base directory: `$XDG_RUNTIME_DIR`, else the temp dir.
 ///
 /// Unlike the other bases there is no `~/...` fallback to construct: the
 /// runtime dir is `/run/user/UID`, created by pam_systemd at login and mode
 /// 0700. An unset variable means we are outside a login session, where the
 /// shared temp dir is the honest answer rather than a path we would have to
 /// invent (and could not create with the right ownership anyway).
 pub fn runtime_dir() -> std::path::PathBuf {
     match std::env::var("XDG_RUNTIME_DIR") {
         Ok(x) if !x.is_empty() => std::path::PathBuf::from(x),
         _ => std::env::temp_dir(),
     }
 }
 
 /// The cce config directory (`<config_home>/cce`).
 pub fn cce_config_dir() -> std::path::PathBuf {
     config_home().join("cce")
 }
 
 /// The cce state directory (`<state_home>/cce`); each app keeps its own
 /// subdirectory under it (`cce/browser`, `cce/mail`, …). Not created here:
 /// a caller creates the subdirectory it writes, with the mode it needs.
 pub fn cce_state_dir() -> std::path::PathBuf {
     state_home().join("cce")
 }
 
 /// The cce runtime directory (`<runtime_dir>/cce`), created if absent.
 ///
 /// Session-scoped files — logs, sockets, pid files — belong here rather than
 /// in `/tmp`, which is one namespace shared by every user on the machine: a
 /// fixed `/tmp/cce-*.log` is a path the first user to log in owns, and the
 /// sticky bit then denies everyone else. Creating on demand keeps call sites
 /// to one line; a failure surfaces when the caller opens its file, which it
 /// already has to handle.
 pub fn cce_runtime_dir() -> std::path::PathBuf {
     let dir = runtime_dir().join("cce");
     let _ = std::fs::create_dir_all(&dir);
     dir
 }
 
 pub fn get_config_path() -> std::path::PathBuf {
     cce_config_dir().join("config.kdl")
 }
 
 struct ConfigCache {
     last_modified: Option<std::time::SystemTime>,
     /// Shared, not cloned per read: the getters below run many times a frame,
     /// and a deep copy of the whole tree to read one key was most of their cost.
     parsed: Option<std::sync::Arc<serde_json::Value>>,
     raw_content: String,
 }
 
 static CONFIG_CACHE: std::sync::RwLock<ConfigCache> = std::sync::RwLock::new(ConfigCache {
     last_modified: None,
     parsed: None,
     raw_content: String::new(),
 });
 
 /// The cce config parsed to JSON, cached on the config file's mtime (per process).
 /// Re-reads and re-parses only when `get_config_path()`'s modification time changes.
 /// The newest mtime across the shared config and the calling app's override
 /// file — the cache key for [`cached_config`], and what apps should poll for
 /// live-reload triggers. Compared by EQUALITY, so an app-file deletion (max
 /// drops back to the shared mtime) also invalidates.
 pub fn config_files_modified() -> Option<std::time::SystemTime> {
     let shared = std::fs::metadata(get_config_path()).ok().and_then(|m| m.modified().ok());
     let app = app_name()
         .and_then(|n| std::fs::metadata(get_app_config_path(n)).ok())
         .and_then(|m| m.modified().ok());
     match (shared, app) {
         (Some(a), Some(b)) => Some(a.max(b)),
         (a, b) => a.or(b),
     }
 }
 
 pub fn cached_config() -> serde_json::Value {
     (*cached_config_arc()).clone()
 }
 
 /// [`cached_config`] without the copy — what every getter here reads.
 pub fn cached_config_arc() -> std::sync::Arc<serde_json::Value> {
     let path = get_config_path();
     // Both files participate in the parse (parse_kdl_to_json merges the
     // per-app override), so both participate in the cache key.
     let current_modified = config_files_modified();
 
     if let Ok(cache) = CONFIG_CACHE.read() {
         if cache.last_modified.is_some() && cache.last_modified == current_modified {
             if let Some(ref val) = cache.parsed {
                 return val.clone();
             }
         }
     }
 
     let content = std::fs::read_to_string(&path).unwrap_or_default();
     let val = std::sync::Arc::new(parse_kdl_to_json(&content));
     if let Ok(mut cache) = CONFIG_CACHE.write() {
         cache.last_modified = current_modified;
         cache.parsed = Some(val.clone());
         cache.raw_content = content;
     }
     val
 }
 
 /// The raw text of the cce config, cached alongside [`cached_config`].
 pub fn cached_config_content() -> String {
     let _ = cached_config_arc();
     CONFIG_CACHE.read().map(|c| c.raw_content.clone()).unwrap_or_default()
 }
 
 static SHARED_CONFIG_CACHE: std::sync::RwLock<ConfigCache> = std::sync::RwLock::new(ConfigCache {
     last_modified: None,
     parsed: None,
     raw_content: String::new(),
 });
 
 /// The SHARED config alone — the per-app override is deliberately NOT merged.
 /// For values that describe something outside the app (the compositor's
 /// window silhouette radius), where an app-local override restyles the app
 /// but must not desynchronize it from the DE. Mtime-cached like
 /// [`cached_config`].
 pub fn cached_shared_config() -> serde_json::Value {
     (*cached_shared_config_arc()).clone()
 }
 
 /// [`cached_shared_config`] without the copy.
 pub fn cached_shared_config_arc() -> std::sync::Arc<serde_json::Value> {
     let path = get_config_path();
     let current_modified = std::fs::metadata(&path).ok().and_then(|m| m.modified().ok());
 
     if let Ok(cache) = SHARED_CONFIG_CACHE.read() {
         if cache.last_modified.is_some() && cache.last_modified == current_modified {
             if let Some(ref val) = cache.parsed {
                 return val.clone();
             }
         }
     }
 
     let content = std::fs::read_to_string(&path).unwrap_or_default();
     let val = std::sync::Arc::new(if let Ok(doc) = content.parse::<kdl::KdlDocument>() {
         kdl_to_json(&doc)
     } else {
         serde_json::json!({})
     });
     if let Ok(mut cache) = SHARED_CONFIG_CACHE.write() {
         cache.last_modified = current_modified;
         cache.parsed = Some(val.clone());
         cache.raw_content = content;
     }
     val
 }
 
 /// Read an i64 at `pointer` from the SHARED config only (no per-app merge),
 /// or `default` — see [`cached_shared_config`].
 pub fn get_i64_shared(pointer: &str, default: i64) -> i64 {
     cached_shared_config_arc().pointer(pointer).and_then(|v| v.as_i64()).unwrap_or(default)
 }
 
 /// [`get_i64_shared`] without a default — for canonical-first alias chains
 /// (RFC Phase 7a) where absence must fall through to the next spelling.
 pub fn get_i64_shared_opt(pointer: &str) -> Option<i64> {
     cached_shared_config_arc().pointer(pointer).and_then(|v| v.as_i64())
 }
 
 // ── Typed accessors over the cached config ──────────────────────────────────
 // Each reads the mtime-cached config and extracts a value at a JSON pointer
 // (e.g. "/notifications/enable"), returning the default when absent or mistyped.
 
 /// Read a boolean at `pointer` from the cached config, or `default`.
 pub fn get_bool(pointer: &str, default: bool) -> bool {
     cached_config_arc().pointer(pointer).and_then(|v| v.as_bool()).unwrap_or(default)
 }
 
 /// Read an f32 at `pointer` from the cached config, or `default`.
 pub fn get_f32(pointer: &str, default: f32) -> f32 {
     cached_config_arc()
         .pointer(pointer)
         .and_then(|v| v.as_f64())
         .map(|f| f as f32)
         .unwrap_or(default)
 }
 
 /// Read an i64 at `pointer` from the cached config, or `default`.
 pub fn get_i64(pointer: &str, default: i64) -> i64 {
     cached_config_arc().pointer(pointer).and_then(|v| v.as_i64()).unwrap_or(default)
 }
 
 /// Read a string at `pointer` from the cached config.
 pub fn get_string(pointer: &str) -> Option<String> {
     cached_config_arc().pointer(pointer).and_then(|v| v.as_str()).map(|s| s.to_string())
 }
 
 /// Read a hex color string at `pointer` and parse it to raw sRGB RGBA (`[0,1]`).
 /// Apply [`crate::color::srgb_to_linear`] if your render target expects linear.
 pub fn get_color(pointer: &str) -> Option<[f32; 4]> {
     get_string(pointer).as_deref().and_then(crate::color::parse_hex_rgba)
 }
 
 /// Recursively search a JSON value for the first entry whose object key equals
 /// `key`, returning a reference to its value. Depth-first over objects and arrays.
 pub fn find_key<'a>(val: &'a serde_json::Value, key: &str) -> Option<&'a serde_json::Value> {
     match val {
         serde_json::Value::Object(map) => {
             if let Some(found) = map.get(key) {
                 return Some(found);
             }
             for v in map.values() {
                 if let Some(found) = find_key(v, key) {
                     return Some(found);
                 }
             }
             None
         }
         serde_json::Value::Array(arr) => arr.iter().find_map(|v| find_key(v, key)),
         _ => None,
     }
 }
 
 
 
 fn perform_rolling_backup(path: &str) {
     let config_path = get_config_path();
     if std::path::Path::new(path) != config_path {
         return;
     }
     if !std::path::Path::new(path).exists() {
         return;
     }
     let backup_dir = config_path.parent().unwrap().join("backups");
     if fs::create_dir_all(&backup_dir).is_err() {
         return;
     }
     for i in (1..=4).rev() {
         let src = backup_dir.join(format!("config.kdl.{}.bak", i));
         let dst = backup_dir.join(format!("config.kdl.{}.bak", i + 1));
         if src.exists() {
             let _ = fs::rename(src, dst);
         }
     }
     let dst = backup_dir.join("config.kdl.1.bak");
     let _ = fs::copy(path, dst);
 }
 
 pub(crate) fn safe_write(path: &str, content: &str) -> bool {
     perform_rolling_backup(path);
     if let Some(parent) = std::path::Path::new(path).parent() {
         let _ = fs::create_dir_all(parent);
     }
     let temp_path = format!("{}.tmp", path);
     if fs::write(&temp_path, content).is_ok() {
         if fs::rename(&temp_path, path).is_ok() {
             return true;
         }
         let _ = fs::remove_file(&temp_path);
     }
     false
 }
 
 pub fn write_config_value(path: &str, key: &str, value: &str, default_section: &str) -> bool {
     write_config_value_typed(path, key, value, default_section, None)
 }
 
 /// Remove `key` from the config file at `path` ([`remove_kdl_in_memory`]),
 /// writing only when something was removed. `true` when the key is gone —
 /// absent to begin with, or removed and written — so a writer migrating a
 /// legacy spelling can fold it into its own success.
 pub fn remove_config_value(path: &str, key: &str) -> bool {
     let content = fs::read_to_string(path).unwrap_or_default();
     let mut doc = match content.parse::<kdl::KdlDocument>() {
         Ok(d) => d,
         Err(_) => return true,
     };
     if remove_kdl_in_memory(&mut doc, key) {
         return safe_write(path, &doc.to_string());
     }
     true
 }
 
 /// [`write_config_value`] with an explicit type annotation — see
 /// [`update_kdl_in_memory_typed`].
 pub fn write_config_value_typed(path: &str, key: &str, value: &str, default_section: &str, forced_ty: Option<&str>) -> bool {
     let content = fs::read_to_string(path).unwrap_or_default();
     let mut doc = match content.parse::<kdl::KdlDocument>() {
         Ok(d) => d,
         Err(_) => kdl::KdlDocument::new(),
     };
 
     if update_kdl_in_memory_typed(&mut doc, key, value, default_section, forced_ty) {
         let updated_str = doc.to_string();
         return safe_write(path, &updated_str);
     }
     false
 }
 
 pub fn get_kdl_type_annotation(kdl_content: &str, key_path: &str) -> Option<String> {
     let doc: kdl::KdlDocument = kdl_content.parse().ok()?;
     let parts: Vec<&str> = key_path.split('.').collect();
     if parts.is_empty() {
         return None;
     }
 
     let is_property = parts.len() >= 2 && PROP_NODES.contains(&parts[parts.len() - 2]);
 
     let (node_path, target_prop) = if is_property {
         (&parts[0..parts.len() - 1], Some(parts[parts.len() - 1].to_string()))
     } else {
         (&parts[0..parts.len()], None)
     };
 
     let child_node = get_node_ref(&doc, node_path)?;
 
     if let Some(prop_name) = target_prop {
         let entry = child_node.entries().iter().find(|e| e.name().map(|n| n.value()) == Some(&prop_name))?;
         entry.ty().map(|t| t.value().to_string())
     } else {
         let entry = child_node.entries().first()?;
         entry.ty().map(|t| t.value().to_string())
     }
 }
 
 pub fn get_kdl_type_annotations(kdl_content: &str, key_paths: &[String]) -> Vec<Option<String>> {
     let doc = kdl_content.parse::<kdl::KdlDocument>().ok();
     key_paths.iter().map(|key_path| {
         let doc = doc.as_ref()?;
         let parts: Vec<&str> = key_path.split('.').collect();
         if parts.is_empty() {
             return None;
         }
 
         let is_property = parts.len() >= 2 && PROP_NODES.contains(&parts[parts.len() - 2]);
 
         let (node_path, target_prop) = if is_property {
             (&parts[0..parts.len() - 1], Some(parts[parts.len() - 1].to_string()))
         } else {
             (&parts[0..parts.len()], None)
         };
 
         let child_node = get_node_ref(doc, node_path)?;
 
         if let Some(prop_name) = target_prop {
             let entry = child_node.entries().iter().find(|e| e.name().map(|n| n.value()) == Some(&prop_name))?;
             entry.ty().map(|t| t.value().to_string())
         } else {
             let entry = child_node.entries().first()?;
             entry.ty().map(|t| t.value().to_string())
         }
     }).collect()
 }
 
 /// `s` as a quoted KDL string, escaped as KDL v1 (the `kdl` 4 parser this
 /// reads back with) escapes: a quote, a backslash and the control
 /// characters. Every string the writer emits goes through here — until
 /// 2026-10-01 values were written as `"{s}"` with nothing escaped, so one
 /// quote inside a value made a line no parser reads, and an app whose
 /// settings file fails to parse loads its DEFAULTS.
 pub fn kdl_quote(s: &str) -> String {
     let mut out = String::with_capacity(s.len() + 2);
     out.push('"');
     for c in s.chars() {
         match c {
             '"' => out.push_str("\\\""),
             '\\' => out.push_str("\\\\"),
             '\n' => out.push_str("\\n"),
             '\r' => out.push_str("\\r"),
             '\t' => out.push_str("\\t"),
             '\u{08}' => out.push_str("\\b"),
             '\u{0C}' => out.push_str("\\f"),
             c if c.is_control() => out.push_str(&format!("\\u{{{:x}}}", c as u32)),
             c => out.push(c),
         }
     }
     out.push('"');
     out
 }
 
 fn format_kdl_type(ty: &str) -> String {
     let is_ident = !ty.is_empty()
         && !ty.chars().next().unwrap().is_ascii_digit()
         && ty.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '+' | '?' | '!' | '@' | '*' | '~' | '|' | '.'));
     if is_ident {
         ty.to_string()
     } else {
         kdl_quote(ty)
     }
 }
 
 fn format_kdl_identifier(name: &str) -> String {
     let is_ident = !name.is_empty()
         && !name.chars().next().unwrap().is_ascii_digit()
         && name.chars().all(|c| c.is_ascii_alphanumeric() || matches!(c, '_' | '-' | '+' | '?' | '!' | '@' | '*' | '~' | '|' | '.'));
     if is_ident {
         name.to_string()
     } else {
         kdl_quote(name)
     }
 }
 
 pub fn value_to_kdl(key: &str, val: &serde_json::Value, indent: usize) -> String {
     value_to_kdl_with_annotations(key, val, indent, "", &std::collections::HashMap::new())
 }
 
 pub fn value_to_kdl_with_annotations(
     key: &str,
     val: &serde_json::Value,
     indent: usize,
     parent_path: &str,
     annotations: &std::collections::HashMap<String, String>,
 ) -> String {
     let indent_str = "    ".repeat(indent);
     let current_path = if parent_path.is_empty() {
         key.to_string()
     } else {
         format!("{}.{}", parent_path, key)
     };
 
     match val {
         serde_json::Value::Object(map) => {
             let has_objects = map.values().any(|v| v.is_object());
             if has_objects {
                 let mut out = format!("{}{} {{\n", indent_str, format_kdl_identifier(key));
                 for (k, v) in map {
                     out.push_str(&value_to_kdl_with_annotations(k, v, indent + 1, &current_path, annotations));
                 }
                 out.push_str(&format!("{}}}\n", indent_str));
                 out
             } else {
                 let mut prop_parts = Vec::new();
                 let mut child_parts = Vec::new();
                 for (prop_name, prop_val) in map {
                     let prop_path = format!("{}.{}", current_path, prop_name);
                     let is_vec2i = annotations.get(&prop_path).is_some_and(|a| a == "vec2i");
                     if is_vec2i {
                         if let serde_json::Value::String(ref s) = prop_val {
                             child_parts.push(format!("{}{} (vec2i){}\n", "    ".repeat(indent + 1), format_kdl_identifier(prop_name), s));
                         }
                     } else {
                         let (val_str, val_ty) = match prop_val {
                             serde_json::Value::Bool(b) => (b.to_string(), Some("bool".to_string())),
                             serde_json::Value::Number(num) => {
                                 if prop_name == "light_source_position" {
                                     (num.to_string(), Some("radian".to_string()))
                                 } else if num.is_f64() {
                                     (num.to_string(), Some("f64".to_string()))
                                 } else {
                                     (num.to_string(), Some("i64".to_string()))
                                 }
                             }
                             serde_json::Value::String(s) => {
                                 if let Some(len) = crate::units::Len::parse(s) {
                                     (crate::units::fmt_num(len.value), Some(len.unit.suffix().to_string()))
                                 } else if let Some(anno) = annotations.get(&prop_path) {
                                     if anno == "vec2i" {
                                         (s.clone(), Some(anno.clone()))
                                     } else {
                                         (kdl_quote(s), Some(anno.clone()))
                                     }
                                 } else if s.starts_with('#') {
                                     let s_clean = s.trim_start_matches('#');
                                     let ty = if s_clean.len() == 8 { "rgba" } else { "rgb" };
                                     (kdl_quote(s), Some(ty.to_string()))
                                 } else if prop_name == "key" || prop_name == "keybind" || prop_name == "shortcut" || prop_name == "open_search" || prop_name == "close_search" || prop_name == "delete" || prop_name.ends_with("_key") || prop_name.ends_with(".key") || prop_name.ends_with(".keybind") || prop_name.ends_with(".open_search") || prop_name.ends_with(".close_search") || prop_name == "brightness_up" || prop_name == "brightness_down" || prop_name.ends_with(".brightness_up") || prop_name.ends_with(".brightness_down") {
                                     (kdl_quote(s), Some("keybind".to_string()))
                                 } else {
                                     (kdl_quote(s), None)
                                 }
                             }
                             _ => (prop_val.to_string(), None),
                         };
                         if let Some(ty) = val_ty {
                             prop_parts.push(format!("{}=({}){}", format_kdl_identifier(prop_name), format_kdl_type(&ty), val_str));
                         } else {
                             prop_parts.push(format!("{}={}", format_kdl_identifier(prop_name), val_str));
                         }
                     }
                 }
                 if !child_parts.is_empty() {
                     let mut out = format!("{}{} {{\n", indent_str, format_kdl_identifier(key));
                     if !prop_parts.is_empty() {
                         out.push_str(&format!("{}{}\n", "    ".repeat(indent + 1), prop_parts.join(" ")));
                     }
                     for child in child_parts {
                         out.push_str(&child);
                     }
                     out.push_str(&format!("{}}}\n", indent_str));
                     out
                 } else {
                     format!("{}{} {}\n", indent_str, format_kdl_identifier(key), prop_parts.join(" "))
                 }
             }
         }
         serde_json::Value::Array(arr) => {
             // An array of strings is one node with several positional args
             // (the shape `kdl_to_json` reads `rounded_apps "a" "b"` into);
             // any other array is one node per item (key_bindings' objects).
             if !arr.is_empty() && arr.iter().all(|v| v.is_string()) {
                 let args: Vec<String> = arr
                     .iter()
                     .filter_map(|v| v.as_str().map(kdl_quote))
                     .collect();
                 return format!("{}{} {}\n", indent_str, format_kdl_identifier(key), args.join(" "));
             }
             let mut out = String::new();
             for item in arr {
                 out.push_str(&value_to_kdl_with_annotations(key, item, indent, parent_path, annotations));
             }
             out
         }
         _ => {
             let (val_str, val_ty) = match val {
                 serde_json::Value::Bool(b) => (b.to_string(), Some("bool".to_string())),
                 serde_json::Value::Number(num) => {
                     if key == "light_source_position" {
                         (num.to_string(), Some("radian".to_string()))
                     } else if num.is_f64() {
                         (num.to_string(), Some("f64".to_string()))
                     } else {
                         (num.to_string(), Some("i64".to_string()))
                     }
                 }
                 serde_json::Value::String(s) => {
                     if let Some(len) = crate::units::Len::parse(s) {
                         (crate::units::fmt_num(len.value), Some(len.unit.suffix().to_string()))
                     } else if let Some(anno) = annotations.get(&current_path) {
                         if anno == "vec2i" {
                             (s.clone(), Some(anno.clone()))
                         } else {
                             (kdl_quote(s), Some(anno.clone()))
                         }
                     } else if s.starts_with('#') {
                         let s_clean = s.trim_start_matches('#');
                         let ty = if s_clean.len() == 8 { "rgba" } else { "rgb" };
                         (kdl_quote(s), Some(ty.to_string()))
                     } else if key == "key" || key == "keybind" || key == "shortcut" || key == "open_search" || key == "close_search" || key == "delete" || key.ends_with("_key") || key.ends_with(".key") || key.ends_with(".keybind") || key.ends_with(".open_search") || key.ends_with(".close_search") || key == "brightness_up" || key == "brightness_down" || key.ends_with(".brightness_up") || key.ends_with(".brightness_down") {
                         (kdl_quote(s), Some("keybind".to_string()))
                     } else {
                         (kdl_quote(s), None)
                     }
                 }
                 _ => (val.to_string(), None),
             };
             if let Some(ty) = val_ty {
                 format!("{}{} ({}){}\n", indent_str, format_kdl_identifier(key), format_kdl_type(&ty), val_str)
             } else {
                 format!("{}{} {}\n", indent_str, format_kdl_identifier(key), val_str)
             }
         }
     }
 }
 
 pub fn json_to_kdl_string(val: &serde_json::Value) -> String {
     json_to_kdl_string_with_annotations(val, &std::collections::HashMap::new())
 }
 
 pub fn json_to_kdl_string_with_annotations(
     val: &serde_json::Value,
     annotations: &std::collections::HashMap<String, String>,
 ) -> String {
     let mut out = String::new();
     if let serde_json::Value::Object(map) = val {
         for (sec_name, sec_val) in map {
             if let serde_json::Value::Object(sec_map) = sec_val {
                 out.push_str(&format!("{} {{\n", format_kdl_identifier(sec_name)));
                 for (k, v) in sec_map {
                     out.push_str(&value_to_kdl_with_annotations(k, v, 1, sec_name, annotations));
                 }
                 out.push_str("}\n");
             } else {
                 out.push_str(&value_to_kdl_with_annotations(sec_name, sec_val, 0, "", annotations));
             }
         }
     }
     out
 }
 
 pub fn get_app_recent_files_path() -> std::path::PathBuf {
     let app_name = get_app_name().unwrap_or_else(|| "cce-app".to_string());
     get_config_path().parent().unwrap().join(app_name).join("recent-files.kdl")
 }
 
 pub fn load_recent_files() -> Vec<String> {
     let path = get_app_recent_files_path();
     if path.exists() {
         if let Ok(content) = std::fs::read_to_string(&path) {
             if let Ok(doc) = content.parse::<kdl::KdlDocument>() {
                 if let Some(recent_node) = doc.get("recent") {
                     if let Some(children) = recent_node.children() {
                         let mut files = Vec::new();
                         for node in children.nodes() {
                             if node.name().value() == "file" {
                                 if let Some(entry) = node.entries().first() {
                                     if let kdl::KdlValue::String(s) = entry.value() {
                                         files.push(s.clone());
                                     }
                                 }
                             }
                         }
                         return files;
                     }
                 }
             }
         }
     }
     Vec::new()
 }
 
 pub fn save_recent_files(files: &[String]) {
     let path = get_app_recent_files_path();
     if let Some(parent) = path.parent() {
         let _ = std::fs::create_dir_all(parent);
     }
     let mut kdl_str = "recent {\n".to_string();
     for file in files {
         kdl_str.push_str(&format!("    file {}\n", kdl_quote(file)));
     }
     kdl_str.push_str("}\n");
     let _ = std::fs::write(path, kdl_str);
 }
 
 
 #[cfg(test)]
 mod tests {
     /// `$XDG_STATE_HOME` when it is absolute; `~/.local/state` when it is
     /// unset, empty or relative. Nothing else in the crate reads the
     /// variable, so setting it here cannot race another test.
     #[test]
     fn state_home_follows_xdg_and_falls_back() {
         let home = std::path::PathBuf::from(std::env::var("HOME").unwrap_or_default());
         let fallback = home.join(".local").join("state");
         std::env::set_var("XDG_STATE_HOME", "/srv/state");
         assert_eq!(super::state_home(), std::path::PathBuf::from("/srv/state"));
         assert_eq!(super::cce_state_dir(), std::path::PathBuf::from("/srv/state/cce"));
         for invalid in ["", "relative/state"] {
             std::env::set_var("XDG_STATE_HOME", invalid);
             assert_eq!(super::state_home(), fallback, "{invalid:?}");
         }
         std::env::remove_var("XDG_STATE_HOME");
         assert_eq!(super::state_home(), fallback);
         assert_eq!(super::cce_state_dir(), fallback.join("cce"));
     }
 
     /// A string the writer emits comes back as it went in, quotes,
     /// backslashes and control characters included — as a section value,
     /// a top-level value, a keybind (written with a type annotation), a
     /// list item and a key that is not an identifier. Until 2026-10-01
     /// none of it was escaped, a quote inside a value made a line the
     /// parser refused, and an app whose settings file fails to parse loads
     /// its defaults.
     #[test]
     fn strings_round_trip_through_the_kdl_writer() {
         let odd = "a \"quoted\" \\path\\ with\nnewline,\ttab and \u{1} control";
         let val = serde_json::json!({
             "section": {
                 "plain": odd,
                 "shortcut": "ctrl+\"",
                 "items": [odd, "x"],
                 "not an ident": odd,
             },
             "top": odd,
         });
         let text = super::json_to_kdl_string(&val);
         let doc: kdl::KdlDocument = text.parse().unwrap_or_else(|e| panic!("{e}\n{text}"));
         let back = super::kdl_to_json(&doc);
         assert_eq!(back["section"]["plain"], odd, "{text}");
         assert_eq!(back["section"]["shortcut"], "ctrl+\"", "{text}");
         assert_eq!(back["section"]["items"][0], odd, "{text}");
         assert_eq!(back["section"]["not an ident"], odd, "{text}");
         assert_eq!(back["top"], odd, "{text}");
         assert_eq!(super::kdl_quote("plain"), "\"plain\"", "an ordinary string is unchanged");
     }
 
     /// A material node's frost and finish are written as PROPERTIES of a
     /// `frost` / `finish` child (RFC material § 5), created on demand under
     /// `style.surface.material.<name>`, and read back through the same
     /// pointer the loader uses.
     #[test]
     fn material_keys_write_as_frost_and_finish_props() {
         use super::{parse_kdl_to_json, update_kdl_in_memory};
         let mut doc = kdl::KdlDocument::new();
         assert!(update_kdl_in_memory(&mut doc, "style.surface.material.glass.frost.compression", "0.6", "style"));
         assert!(update_kdl_in_memory(&mut doc, "style.surface.material.glass.frost.refraction", "0.3", "style"));
         assert!(update_kdl_in_memory(&mut doc, "style.surface.material.glass.finish.spec", "0.4", "style"));
         assert!(update_kdl_in_memory(&mut doc, "style.surface.material.glass.color", "#05050840", "style"));
         assert!(update_kdl_in_memory(&mut doc, "style.surface.plate.material", "glass", "style"));
         let text = doc.to_string();
         let val = parse_kdl_to_json(&text);
         assert_eq!(val.pointer("/style/surface/material/glass/frost/compression").and_then(|v| v.as_f64()), Some(0.6), "{text}");
         assert_eq!(val.pointer("/style/surface/material/glass/frost/refraction").and_then(|v| v.as_f64()), Some(0.3));
         assert_eq!(val.pointer("/style/surface/material/glass/finish/spec").and_then(|v| v.as_f64()), Some(0.4));
         assert_eq!(val.pointer("/style/surface/material/glass/color").and_then(|v| v.as_str()), Some("#05050840"));
         assert_eq!(val.pointer("/style/surface/plate/material").and_then(|v| v.as_str()), Some("glass"));
         // One `frost` node with two props, not two `frost` nodes.
         assert_eq!(text.matches("frost").count(), 1, "{text}");
         assert!(text.contains("(rgba)"), "the colour carries its type: {text}");
     }
 
     #[test]
     fn unit_annotations_become_len_strings() {
         let v = parse_kdl_to_json("style {\n    relief width=(mm)2.0 depth=(f64)0.15 lip=(px)6\n    ruler (in)0.5\n}\n");
         assert_eq!(v["style"]["relief"]["width"], serde_json::json!("2mm"));
         assert_eq!(v["style"]["relief"]["depth"], serde_json::json!(0.15));
         assert_eq!(v["style"]["relief"]["lip"], serde_json::json!("6px"));
         assert_eq!(v["style"]["ruler"], serde_json::json!("0.5in"));
     }
 
     #[test]
     fn unit_strings_write_back_annotated() {
         let v = serde_json::json!({"style": {"relief": {"width": "2mm", "depth": 0.15}}});
         let out = json_to_kdl_string(&v);
         assert!(out.contains("width=(mm)2\n") || out.contains("width=(mm)2 "), "{out}");
         assert!(out.contains("depth=(f64)0.15"), "{out}");
         let back = parse_kdl_to_json(&out);
         assert_eq!(back["style"]["relief"]["width"], serde_json::json!("2mm"));
     }
 
     #[test]
     fn typed_write_keeps_and_sets_units() {
         let mut doc: kdl::KdlDocument = "style {\n    relief width=(mm)2.0\n}\n".parse().unwrap();
         // A bare number over a (mm) slot stays mm.
         assert!(update_kdl_in_memory_typed(&mut doc, "style.relief.width", "3", "style", None));
         let v = parse_kdl_to_json(&doc.to_string());
         assert_eq!(v["style"]["relief"]["width"], serde_json::json!("3mm"));
         // A suffixed value sets the unit.
         assert!(update_kdl_in_memory_typed(&mut doc, "style.relief.width", "0.25in", "style", None));
         let v = parse_kdl_to_json(&doc.to_string());
         assert_eq!(v["style"]["relief"]["width"], serde_json::json!("0.25in"));
     }
 
     #[test]
     fn app_name_strips_the_kernels_deleted_marker() {
         use super::app_name_from_exe_basename as name;
         assert_eq!(name("cce-status-interface"), "cce-status-interface");
         assert_eq!(name("cce-status-interface (deleted)"), "cce-status-interface");
         // Only the exact trailing marker: a name that merely contains the
         // word, or an unspaced variant, is left alone.
         assert_eq!(name("cce-deleted-files"), "cce-deleted-files");
         assert_eq!(name("cce-x(deleted)"), "cce-x(deleted)");
     }
 
     use super::*;
 
     #[test]
     fn cce_runtime_dir_sits_under_the_runtime_base_and_is_created() {
         // No env mutation: reading the real base keeps this correct both in a
         // session (XDG_RUNTIME_DIR set) and anywhere it is not (temp dir), and
         // avoids racing every other test in the process.
         let base = runtime_dir();
         assert!(base.is_absolute(), "runtime base must be absolute: {base:?}");
         let dir = cce_runtime_dir();
         assert_eq!(dir, base.join("cce"));
         // The create-on-demand contract callers depend on: they open a file
         // inside this directory without creating it themselves.
         assert!(dir.is_dir(), "cce_runtime_dir must create its directory: {dir:?}");
     }
 
     #[test]
     fn relief_annotated_string_passes_through() {
         // The (relief) custom value type: an annotated string prop must
         // survive kdl_to_json as a plain JSON string at its pointer.
         let content = "style {\n    surface {\n        desktop gap_width=(i64)16 line_relief=(relief)\"w=8 d=0.55 k=0.8,0.2,0.5 p=0.000:0.000,1.000:1.000\"\n    }\n}\n";
         let val = parse_kdl_to_json(content);
         assert_eq!(
             val.pointer("/style/surface/desktop/line_relief").and_then(|v| v.as_str()),
             Some("w=8 d=0.55 k=0.8,0.2,0.5 p=0.000:0.000,1.000:1.000"),
         );
     }
 
     #[test]
     fn test_nested_parsing() {
         let content = "style {\n    status box_opacity=(f64)0.75\n}\n";
         let val = parse_kdl_to_json(content);
         println!("val = {:?}", val);
         let (sec, node, prop) = parse_config_path("style.status.box_opacity", "layout");
         assert_eq!(sec, "style");
         assert_eq!(node, "status");
         assert_eq!(prop, Some("box_opacity".to_string()));
         
         let sec_val = val.get(&sec).unwrap();
         let node_val = sec_val.get(&node).unwrap();
         let prop_val = node_val.get(prop.as_ref().unwrap()).unwrap();
         assert_eq!(prop_val.as_f64().unwrap(), 0.75);
     }
 
     /// The relief's wall and edge keys write as PROPERTIES on `wall` / `edge`
     /// child nodes of the existing `relief` node — the node keeps its own
     /// `depth=` / `width=` properties and grows one child block — and the
     /// reload path reads them back at the nested paths the registry maps.
     /// The legacy flat spellings then come off with `remove_kdl_in_memory`,
     /// which is how cce-relief's Save migrates a file in place.
     #[test]
     fn relief_wall_and_edge_keys_write_as_child_nodes_and_the_flat_ones_come_off() {
         let content = "style {\n    surface {\n        relief light=(f64)0.15 width=(f64)9.3 profile=\"old\" edge_knobs=(bevel)\"0.500,0.500,0.500\"\n    }\n}\n";
         let mut doc = content.parse::<kdl::KdlDocument>().unwrap();
         let spec = "smooth;0.000:0.500,0.400:1.000,1.000:0.000";
         assert!(update_kdl_in_memory(&mut doc, "style.surface.relief.wall.profile", spec, "style"));
         assert!(update_kdl_in_memory_typed(&mut doc, "style.surface.relief.wall.height", "0.3", "style", Some("mm")));
         assert!(update_kdl_in_memory(&mut doc, "style.surface.relief.edge.profile", spec, "style"));
         assert!(update_kdl_in_memory_typed(&mut doc, "style.surface.relief.edge.height", "4", "style", Some("px")));
         // Migrate: the flat spellings come off, and a spelling that is not
         // there reports nothing removed.
         assert!(remove_kdl_in_memory(&mut doc, "style.surface.relief.profile"));
         assert!(remove_kdl_in_memory(&mut doc, "style.surface.relief.edge_knobs"));
         assert!(!remove_kdl_in_memory(&mut doc, "style.surface.relief.edge_height"), "absent: nothing to remove");
         assert!(!remove_kdl_in_memory(&mut doc, "style.surface.nothing.here"), "missing node: nothing to remove");
         let out = doc.to_string();
         assert_eq!(out.matches("relief").count(), 1, "one relief node: {out}");
         assert!(out.contains("light=(f64)0.15"), "the node keeps its properties: {out}");
         assert!(!out.contains("profile=\"old\""), "flat profile migrated: {out}");
         assert!(!out.contains("edge_knobs"), "flat knobs migrated: {out}");
 
         let val = parse_kdl_to_json(&out);
         let relief = val.pointer("/style/surface/relief").unwrap();
         assert_eq!(relief.get("light").and_then(|v| v.as_f64()), Some(0.15));
         assert_eq!(relief.pointer("/wall/profile").and_then(|v| v.as_str()), Some(spec));
         assert_eq!(relief.pointer("/wall/height").and_then(|v| v.as_str()), Some("0.3mm"), "{relief}");
         assert_eq!(relief.pointer("/edge/profile").and_then(|v| v.as_str()), Some(spec));
         assert!(relief.pointer("/edge/height").is_some(), "{relief}");
         assert!(relief.get("profile").is_none() && relief.get("edge_knobs").is_none(), "{relief}");
         // A whole node comes off too.
         assert!(remove_kdl_in_memory(&mut doc, "style.surface.relief.edge"));
         let val = parse_kdl_to_json(&doc.to_string());
         assert!(val.pointer("/style/surface/relief/edge").is_none());
         assert!(val.pointer("/style/surface/relief/wall/profile").is_some());
     }
 
     #[test]
     fn relief_keys_write_as_properties_and_round_trip() {
         // `relief` is a PROP_NODES member: style.surface.relief.* must land as
         // properties on the existing relief node (the config.kdl shape), not
         // as duplicate child nodes shadowing the light=/width= properties.
         let content = "style {\n    surface {\n        relief light=(f64)0.15 width=(f64)9.3\n    }\n}\n";
         let mut doc = content.parse::<kdl::KdlDocument>().unwrap();
         let spec = "smooth;0.000:0.500,0.400:1.000,1.000:0.000";
         assert!(update_kdl_in_memory(&mut doc, "style.surface.relief.profile", spec, "style"));
         assert!(update_kdl_in_memory(&mut doc, "style.surface.relief.light", "0.3", "style"));
         let out = doc.to_string();
         // Still one relief node, no child block grown under it.
         assert_eq!(out.matches("relief").count(), 1, "out: {out}");
         assert!(!out.contains("relief {"), "out: {out}");
 
         // The reload path reads through parse_kdl_to_json: the new property
         // must surface at the same dotted path the style registry maps.
         let val = parse_kdl_to_json(&out);
         let relief = val.get("style").unwrap().get("surface").unwrap().get("relief").unwrap();
         assert_eq!(relief.get("profile").unwrap().as_str().unwrap(), spec);
         assert_eq!(relief.get("light").unwrap().as_f64().unwrap(), 0.3);
         assert_eq!(relief.get("width").unwrap().as_f64().unwrap(), 9.3);
     }
 
     #[test]
     fn test_get_kdl_type_annotation() {
         let content = "input {\n    accel_profile (\"menu:flat,adaptive,none,custom\")\"flat\"\n    touchpad {\n        gestures pinch=(bool)true\n    }\n}\n";
         let ty1 = get_kdl_type_annotation(content, "input.accel_profile");
         assert_eq!(ty1, Some("menu:flat,adaptive,none,custom".to_string()));
         
         let ty2 = get_kdl_type_annotation(content, "input.touchpad.gestures.pinch");
         assert_eq!(ty2, Some("bool".to_string()));
 
         let keys = vec![
             "input.accel_profile".to_string(),
             "input.touchpad.gestures.pinch".to_string(),
             "input.invalid_key".to_string(),
         ];
         let tys = get_kdl_type_annotations(content, &keys);
         assert_eq!(tys.len(), 3);
         assert_eq!(tys[0], Some("menu:flat,adaptive,none,custom".to_string()));
         assert_eq!(tys[1], Some("bool".to_string()));
         assert_eq!(tys[2], None);
     }
 
     #[test]
     fn test_json_to_kdl_with_special_annotations() {
         let mut annotations = std::collections::HashMap::new();
         annotations.insert("style.surface.desktop.mode".to_string(), "menu:grid,solid".to_string());
         
         let mut desktop_map = serde_json::Map::new();
         desktop_map.insert("mode".to_string(), serde_json::Value::String("grid".to_string()));
         
         let mut surface_map = serde_json::Map::new();
         surface_map.insert("desktop".to_string(), serde_json::Value::Object(desktop_map));
         
         let mut style_map = serde_json::Map::new();
         style_map.insert("surface".to_string(), serde_json::Value::Object(surface_map));
         
         let mut root_map = serde_json::Map::new();
         root_map.insert("style".to_string(), serde_json::Value::Object(style_map));
         
         let root = serde_json::Value::Object(root_map);
         let kdl_str = json_to_kdl_string_with_annotations(&root, &annotations);
         println!("Generated KDL:\n{}", kdl_str);
         
         let doc_parsed = kdl_str.parse::<kdl::KdlDocument>();
         assert!(doc_parsed.is_ok(), "Failed to parse KDL: {:?}", doc_parsed.err());
     }
 
     #[test]
     fn test_brightness_annotations() {
         let mut edp_map = serde_json::Map::new();
         edp_map.insert("scale".to_string(), serde_json::Value::Number(serde_json::Number::from_f64(2.0).unwrap()));
         edp_map.insert("brightness_up".to_string(), serde_json::Value::String("XF86MonBrightnessUp".to_string()));
         edp_map.insert("brightness_down".to_string(), serde_json::Value::String("XF86MonBrightnessDown".to_string()));
         edp_map.insert("brightness_interval".to_string(), serde_json::Value::Number(serde_json::Number::from(10)));
 
         let mut output_map = serde_json::Map::new();
         output_map.insert("eDP-1".to_string(), serde_json::Value::Object(edp_map));
 
         let mut root_map = serde_json::Map::new();
         root_map.insert("output".to_string(), serde_json::Value::Object(output_map));
 
         let root = serde_json::Value::Object(root_map);
         let kdl_str = json_to_kdl_string(&root);
         println!("Generated KDL for brightness:\n{}", kdl_str);
 
         let doc_parsed = kdl_str.parse::<kdl::KdlDocument>().unwrap();
         
         let output_node = doc_parsed.nodes().iter().find(|n| n.name().value() == "output").unwrap();
         let edp_node = output_node.children().unwrap().nodes().iter().find(|n| n.name().value() == "eDP-1").unwrap();
         
         let up_entry = edp_node.entries().iter().find(|e| e.name().map(|n| n.value()) == Some("brightness_up")).unwrap();
         assert_eq!(up_entry.ty().unwrap().value(), "keybind");
 
         let down_entry = edp_node.entries().iter().find(|e| e.name().map(|n| n.value()) == Some("brightness_down")).unwrap();
         assert_eq!(down_entry.ty().unwrap().value(), "keybind");
 
         let interval_entry = edp_node.entries().iter().find(|e| e.name().map(|n| n.value()) == Some("brightness_interval")).unwrap();
         assert_eq!(interval_entry.ty().unwrap().value(), "i64");
     }
 
     /// A string list (`rounded_apps "a" "b"`) must survive the JSON round
     /// trip cce-data-editor saves through — it used to come back as ONE arg,
     /// `rounded_apps "a b"`, and the compositor's allowlist then matched
     /// nothing (Claude Desktop lost its corners after every save).
     #[test]
     fn test_string_list_roundtrip() {
         let content = "window_manager {\n    rounded_apps \"claude-desktop\" \"com.anthropic.Claude\"\n    corner_shape (f64)4.5\n}\n";
         let val = parse_kdl_to_json(content);
         let list = val.get("window_manager").unwrap().get("rounded_apps").unwrap();
         assert_eq!(
             list.as_array().unwrap().iter().map(|v| v.as_str().unwrap()).collect::<Vec<_>>(),
             vec!["claude-desktop", "com.anthropic.Claude"]
         );
         let kdl_str = json_to_kdl_string(&val);
         assert!(kdl_str.contains("rounded_apps \"claude-desktop\" \"com.anthropic.Claude\""), "{kdl_str}");
         // And it re-parses to the same two args, not one.
         let doc = kdl_str.parse::<kdl::KdlDocument>().unwrap();
         let wm = doc.nodes().iter().find(|n| n.name().value() == "window_manager").unwrap();
         let ra = wm.children().unwrap().nodes().iter().find(|n| n.name().value() == "rounded_apps").unwrap();
         assert_eq!(ra.entries().len(), 2);
         // A single-arg string node stays a plain string.
         let single = parse_kdl_to_json("window_manager {\n    rounded_apps \"claude-desktop\"\n}\n");
         assert_eq!(single.get("window_manager").unwrap().get("rounded_apps").unwrap().as_str(), Some("claude-desktop"));
     }
 
     #[test]
     fn test_vec2i_lossless_roundtrip() {
         let content = "style {\n    surface {\n        cloud {\n            position_default (vec2i)100 200\n        }\n    }\n}\n";
         let val = parse_kdl_to_json(content);
         println!("Parsed KDL to JSON: {:?}", val);
         
         let position_default_val = val.get("style").unwrap()
             .get("surface").unwrap()
             .get("cloud").unwrap()
             .get("position_default").unwrap();
         assert_eq!(position_default_val.as_str().unwrap(), "100 200");
 
         let mut annotations = std::collections::HashMap::new();
         annotations.insert("style.surface.cloud.position_default".to_string(), "vec2i".to_string());
         
         let kdl_str = json_to_kdl_string_with_annotations(&val, &annotations);
         println!("Generated KDL:\n{}", kdl_str);
         
         // Assert that (vec2i)100 200 is preserved without quotes
         assert!(kdl_str.contains("position_default (vec2i)100 200"));
         
         // Test update_kdl_in_memory preserves and updates the KDL Document correctly
         let mut doc = kdl_str.parse::<kdl::KdlDocument>().unwrap();
         let updated = update_kdl_in_memory(&mut doc, "style.surface.cloud.position_default", "150 250", "layout");
         assert!(updated);
         let updated_kdl = doc.to_string();
         println!("Updated KDL:\n{}", updated_kdl);
         assert!(updated_kdl.contains("position_default (vec2i)150 250"));
     }
 }