spike libcosmic shell lifecycle

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.