spike libcosmic shell lifecycle

Cargo.toml

@@ -9,6 +9,7 @@ members = [
     "crates/ferese-protocols",
     "tools/ferese-effects-probe",
     "tools/ferese-malformed-client",
+    "tools/ferese-shell-spike",
 ]
 resolver = "3"
 

docs/adr/0001-shell-toolkit.md

@@ -0,0 +1,68 @@
+# ADR 0001: libcosmic for the Ferese shell
+
+Status: provisional, pending the M8 lifecycle spike
+Date: 2026-09-25
+
+## Decision
+
+Use libcosmic for the Ferese shell UI if the M8 lifecycle spike passes. Pin the
+dependency to commit `03d7dcb832bc6d15bc1bb07327a1aa426b2d5bc0` until a suitable
+stable release exists.
+
+Keep the spike in `tools/ferese-shell-spike`; it is not the production shell.
+The production shell will continue to use public layer-shell for surface roles
+and Ferese-private protocols only for control and semantic effects.
+
+## Why
+
+libcosmic is a Rust-native toolkit designed for Wayland desktop components. Its
+current API can create layer-shell surfaces without an ordinary xdg-toplevel,
+select an active or explicit output, request keyboard interactivity, observe
+configure/focus/output events, and destroy surfaces through the runtime.
+
+The previous GPUI direction depended on an older release and did not provide a
+convincing first-class path for Ferese shell surfaces.
+
+## Constraints found during source review
+
+- The selected revision declares Rust 1.93, so the isolated spike overrides the
+  workspace's Rust 1.87 minimum. Ferese core crates keep their existing MSRV.
+- libcosmic exposes the created `WlSurface` in public Wayland layer events. This
+  is necessary but may not be sufficient to bind `ferese-effects-v1` on the
+  toolkit's event queue.
+- The spike must therefore prove private semantic-effects attachment before the
+  production shell adopts libcosmic. If that cannot be done through supported
+  APIs, Ferese will place a thin native Wayland surface adapter beneath the UI
+  or revisit this decision; it will not replace public layer-shell with a
+  private surface role.
+
+## Validation gate
+
+The provisional decision becomes accepted only after the spike demonstrates:
+
+1. public layer-surface creation on the intended output;
+2. output discovery and updates;
+3. configure and resize delivery;
+4. on-demand keyboard focus and focus release;
+5. clean compositor-driven and application-driven shutdown; and
+6. `ferese-effects-v1` attachment to the toolkit-owned surface without an
+   unsupported libcosmic or Iced fork.
+
+## Spike result
+
+Items 1 through 5 pass against nested Ferese. Item 6 passes after libcosmic
+publishes the surface in a focus event: the spike reconstructs a supported
+`wayland-client` connection handle, binds the capability-filtered effects
+global, and assigns `panel` to the same `wl_surface`.
+
+The decision remains provisional because libcosmic does not currently publish
+its layer-surface creation event to the application. A normal non-focusable top
+bar therefore has no deterministic pre-map surface handle. Production work may
+proceed with libcosmic widgets and application state, but the top-bar surface
+path must first gain either:
+
+1. a supported upstream surface-created callback; or
+2. the thin native Wayland surface adapter already allowed by the M8 plan.
+
+Ferese will not make the persistent top bar steal keyboard focus merely to
+obtain its surface handle.

docs/ferese-window-manager-spec.md

@@ -1591,9 +1591,11 @@ budget on the reference integrated GPU.
 
 ### M8: Overview and shell
 
-First spike GPUI layer-surface creation, output discovery, focus, configure, and
-shutdown behavior. If the spike fails its lifecycle tests, use a thin native
-Wayland shell adapter or record a toolkit decision before proceeding. Implement
+First spike the selected shell toolkit's layer-surface creation, output discovery,
+focus, configure, and shutdown behavior. The initial selection is libcosmic,
+pinned to a reviewed Git revision because it has not published a current crates.io
+release. If the spike fails its lifecycle tests, use a thin native Wayland shell
+adapter or record a new toolkit decision before proceeding. Implement
 the compositor overview scene, minimal `ferese-shell-v1` control/metadata
 protocol, top bar, apps-only launcher UI, workspace UI, OSD, and the standard
 notifications D-Bus service.

tools/ferese-shell-spike/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "ferese-shell-spike"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version = "1.93"
+
+[dependencies]
+ferese-protocols = { path = "../../crates/ferese-protocols", default-features = false, features = ["client"] }
+libcosmic = { git = "https://github.com/pop-os/libcosmic", rev = "03d7dcb832bc6d15bc1bb07327a1aa426b2d5bc0", default-features = false, features = ["multi-window", "tokio", "wayland"] }
+wayland-client.workspace = true

tools/ferese-shell-spike/README.md

@@ -0,0 +1,44 @@
+# Ferese libcosmic shell spike
+
+This disposable M8 probe validates libcosmic's Wayland lifecycle before Ferese
+uses it for production shell components. It creates one top layer-shell surface
+on the active output and reports:
+
+- output discovery and updates;
+- the initial configure and later resizes;
+- keyboard focus changes; and
+- compositor close or application shutdown.
+
+Run it inside Ferese with:
+
+```sh
+cargo run -p ferese -- --backend nested -- cargo run -p ferese-shell-spike
+```
+
+Click the surface to exercise on-demand keyboard focus. Press Escape or click
+`Exit spike` to exercise clean shutdown.
+
+For an unattended shutdown check, set an exit delay in milliseconds:
+
+```sh
+FERESE_SHELL_SPIKE_EXIT_AFTER_MS=1000 \
+  FERESE_SHELL_SPIKE_EXCLUSIVE_FOCUS=1 \
+  cargo run -p ferese -- --backend nested --grant-effects -- \
+  target/debug/ferese-shell-spike
+```
+
+The spike intentionally uses public layer-shell. The production shell must use
+Ferese's private protocols only for control and semantic effects, never as a
+replacement surface role.
+
+The spike can attach the semantic `panel` role to libcosmic's own `wl_surface`
+through a supported `wayland-client` connection handle. Run with
+`--grant-effects` and `FERESE_SHELL_SPIKE_EXCLUSIVE_FOCUS=1` to make libcosmic
+expose the surface deterministically through its public focus event. An
+attachment failure is reported without replacing the public layer-shell role.
+
+Source and runtime testing found that libcosmic does not currently forward its
+layer-surface creation event to the application. A non-focusable top bar
+therefore cannot attach the private effect before mapping through this API.
+Production must add a supported upstream creation hook or use the thin native
+surface adapter described in the toolkit ADR.

tools/ferese-shell-spike/src/main.rs

@@ -0,0 +1,293 @@
+use cosmic::Element;
+use cosmic::app::{Core, Settings, Task};
+use cosmic::iced::event::{self, PlatformSpecific, wayland};
+use cosmic::iced::keyboard::{self, Key, key::Named};
+use cosmic::iced::platform_specific::{
+    runtime::wayland::layer_surface::{IcedOutput, SctkLayerSurfaceSettings},
+    shell::commands::layer_surface::{Anchor, KeyboardInteractivity, Layer},
+};
+use cosmic::iced::{Event, Length, Subscription, window};
+use cosmic::widget::{button, column, container, text};
+use ferese_protocols::effects::v1::client::{
+    ferese_effects_manager_v1::FereseEffectsManagerV1,
+    ferese_surface_effects_v1::{self, FereseSurfaceEffectsV1},
+};
+use std::time::Duration;
+use wayland_client::{
+    Connection, Dispatch, EventQueue, Proxy, QueueHandle, delegate_noop,
+    globals::{GlobalListContents, registry_queue_init},
+    protocol::{wl_registry, wl_surface},
+};
+
+const APP_ID: &str = "dev.ferese.ShellSpike";
+const BAR_HEIGHT: u32 = 48;
+
+fn main() -> cosmic::iced::Result {
+    let settings = Settings::default()
+        .no_main_window(true)
+        .client_decorations(false)
+        .transparent(true)
+        .is_daemon(true);
+
+    cosmic::app::run::<ShellSpike>(settings, ())
+}
+
+struct ShellSpike {
+    core: Core,
+    surface_id: window::Id,
+    configured: bool,
+    focused: bool,
+    outputs: usize,
+    exit_after: Option<Duration>,
+    effects: Option<EffectsBinding>,
+}
+
+#[derive(Clone, Debug)]
+enum Message {
+    Event(Event, window::Id),
+    Exit,
+}
+
+impl cosmic::Application for ShellSpike {
+    type Executor = cosmic::executor::Default;
+    type Flags = ();
+    type Message = Message;
+
+    const APP_ID: &'static str = APP_ID;
+
+    fn core(&self) -> &Core {
+        &self.core
+    }
+
+    fn core_mut(&mut self) -> &mut Core {
+        &mut self.core
+    }
+
+    fn init(core: Core, _flags: Self::Flags) -> (Self, Task<Self::Message>) {
+        let surface_id = window::Id::unique();
+        let force_focus = std::env::var_os("FERESE_SHELL_SPIKE_EXCLUSIVE_FOCUS").is_some();
+        let app = Self {
+            core,
+            surface_id,
+            configured: false,
+            focused: false,
+            outputs: 0,
+            exit_after: std::env::var("FERESE_SHELL_SPIKE_EXIT_AFTER_MS")
+                .ok()
+                .and_then(|value| value.parse().ok())
+                .map(Duration::from_millis),
+            effects: None,
+        };
+        let action = cosmic::surface::action::app_layer_shell::<Self>(
+            |_| Default::default(),
+            move |_| SctkLayerSurfaceSettings {
+                id: surface_id,
+                layer: Layer::Top,
+                keyboard_interactivity: if force_focus {
+                    KeyboardInteractivity::Exclusive
+                } else {
+                    KeyboardInteractivity::OnDemand
+                },
+                anchor: Anchor::TOP | Anchor::LEFT | Anchor::RIGHT,
+                output: IcedOutput::Active,
+                namespace: "ferese-shell-spike".to_owned(),
+                size: Some((None, Some(BAR_HEIGHT))),
+                exclusive_zone: BAR_HEIGHT as i32,
+                ..Default::default()
+            },
+            Some(Box::new(Self::view_layer)),
+        );
+
+        println!(
+            "PASS startup requested active-output layer surface focus={}",
+            if force_focus {
+                "exclusive"
+            } else {
+                "on-demand"
+            }
+        );
+
+        (app, cosmic::task::message(cosmic::Action::Surface(action)))
+    }
+
+    fn subscription(&self) -> Subscription<Self::Message> {
+        let events = event::listen_with(|event, _status, id| Some(Message::Event(event, id)));
+        let mut subscriptions = vec![events];
+        if let Some(delay) = self.exit_after {
+            subscriptions.push(cosmic::iced::time::every(delay).map(|_| Message::Exit));
+        }
+        Subscription::batch(subscriptions)
+    }
+
+    fn update(&mut self, message: Self::Message) -> Task<Self::Message> {
+        match message {
+            Message::Event(event, id) => self.handle_event(event, id),
+            Message::Exit => {
+                println!("PASS clean shutdown requested");
+                cosmic::iced::exit()
+            }
+        }
+    }
+
+    fn view(&self) -> Element<'_, Self::Message> {
+        text("").into()
+    }
+
+    fn view_window(&self, _id: window::Id) -> Element<'_, Self::Message> {
+        text("").into()
+    }
+}
+
+impl ShellSpike {
+    fn handle_event(&mut self, event: Event, id: window::Id) -> Task<Message> {
+        match event {
+            Event::Window(window::Event::Opened { size, .. }) if id == self.surface_id => {
+                self.configured = true;
+                println!(
+                    "PASS configure surface={} size={}x{}",
+                    id, size.width, size.height
+                );
+            }
+            Event::Window(window::Event::Resized(size)) if id == self.surface_id => {
+                println!(
+                    "PASS reconfigure surface={} size={}x{}",
+                    id, size.width, size.height
+                );
+            }
+            Event::Window(window::Event::Focused) if id == self.surface_id => {
+                self.focused = true;
+                println!("PASS keyboard focus acquired surface={id}");
+            }
+            Event::Window(window::Event::Unfocused) if id == self.surface_id => {
+                self.focused = false;
+                println!("PASS keyboard focus released surface={id}");
+            }
+            Event::Window(window::Event::Closed) if id == self.surface_id => {
+                println!("PASS compositor closed layer surface={id}");
+                return cosmic::iced::exit();
+            }
+            Event::Keyboard(keyboard::Event::KeyPressed {
+                key: Key::Named(Named::Escape),
+                ..
+            }) if id == self.surface_id => return cosmic::task::message(Message::Exit),
+            Event::PlatformSpecific(PlatformSpecific::Wayland(wayland::Event::Output(
+                output_event,
+                output,
+            ))) => match output_event {
+                wayland::OutputEvent::Created(info) => {
+                    self.outputs += 1;
+                    println!(
+                        "PASS output discovered output={output:?} info={info:?} count={}",
+                        self.outputs,
+                    );
+                }
+                wayland::OutputEvent::InfoUpdate(info) => {
+                    println!("PASS output updated output={output:?} info={info:?}");
+                }
+                wayland::OutputEvent::Removed => {
+                    self.outputs = self.outputs.saturating_sub(1);
+                    println!(
+                        "PASS output removed output={output:?} count={}",
+                        self.outputs,
+                    );
+                }
+            },
+            Event::PlatformSpecific(PlatformSpecific::Wayland(wayland::Event::Frame(
+                _,
+                surface,
+                frame_id,
+            ))) if frame_id == self.surface_id => self.attach_effects(&surface),
+            Event::PlatformSpecific(PlatformSpecific::Wayland(wayland::Event::Layer(
+                layer_event,
+                surface,
+                layer_id,
+            ))) if layer_id == self.surface_id => {
+                self.attach_effects(&surface);
+                println!(
+                    "PASS layer event={layer_event:?} surface={surface:?} configured={} focused={}",
+                    self.configured, self.focused
+                );
+            }
+            _ => {}
+        }
+
+        Task::none()
+    }
+
+    fn attach_effects(&mut self, surface: &wl_surface::WlSurface) {
+        if self.effects.is_some() {
+            return;
+        }
+
+        match EffectsBinding::attach(surface) {
+            Ok(binding) => {
+                self.effects = Some(binding);
+                println!("PASS ferese-effects-v1 attached role=panel");
+            }
+            Err(error) => eprintln!("FAIL ferese-effects-v1 attachment: {error}"),
+        }
+    }
+
+    fn view_layer(&self) -> Element<'_, cosmic::Action<Message>> {
+        let status = format!(
+            "Ferese shell spike  |  configured: {}  |  focused: {}  |  outputs: {}",
+            self.configured, self.focused, self.outputs
+        );
+        let content = column![
+            text(status),
+            button::standard("Exit spike").on_press(cosmic::Action::App(Message::Exit))
+        ]
+        .spacing(4)
+        .padding([4, 16]);
+
+        container(content)
+            .width(Length::Fill)
+            .height(Length::Fill)
+            .into()
+    }
+}
+
+struct EffectsBinding {
+    _manager: FereseEffectsManagerV1,
+    _surface: FereseSurfaceEffectsV1,
+    _queue: EventQueue<EffectsState>,
+}
+
+impl EffectsBinding {
+    fn attach(surface: &wl_surface::WlSurface) -> Result<Self, Box<dyn std::error::Error>> {
+        let backend = surface
+            .backend()
+            .upgrade()
+            .ok_or("libcosmic Wayland connection is no longer alive")?;
+        let connection = Connection::from_backend(backend);
+        let (globals, queue) = registry_queue_init::<EffectsState>(&connection)?;
+        let qh = queue.handle();
+        let manager = globals.bind::<FereseEffectsManagerV1, _, _>(&qh, 1..=1, ())?;
+        let effects = manager.get_surface_effects(surface, &qh, ());
+        effects.set_role(ferese_surface_effects_v1::Role::Panel);
+        connection.flush()?;
+
+        Ok(Self {
+            _manager: manager,
+            _surface: effects,
+            _queue: queue,
+        })
+    }
+}
+
+struct EffectsState;
+
+impl Dispatch<wl_registry::WlRegistry, GlobalListContents> for EffectsState {
+    fn event(
+        _state: &mut Self,
+        _registry: &wl_registry::WlRegistry,
+        _event: wl_registry::Event,
+        _data: &GlobalListContents,
+        _connection: &Connection,
+        _qh: &QueueHandle<Self>,
+    ) {
+    }
+}
+
+delegate_noop!(EffectsState: ignore FereseEffectsManagerV1);
+delegate_noop!(EffectsState: ignore FereseSurfaceEffectsV1);