69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 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.
|