advance shell integration and session support

docs/ferese-theme-ui-spec.md

@@ -240,10 +240,10 @@ base_unit = 8.0
 
 window_radius = 14.0
 
-top_bar_height = 32.0
+top_bar_height = 38.0
 top_bar_margin_top = 4.0
 top_bar_margin_horizontal = 10.0
-top_bar_radius = 16.0
+top_bar_radius = 19.0
 
 launcher_width = 560.0
 launcher_radius = 20.0
@@ -724,8 +724,8 @@ noise = 0.012
 
 [theme.geometry]
 window_radius = 14.0
-top_bar_height = 32.0
-top_bar_radius = 16.0
+top_bar_height = 38.0
+top_bar_radius = 19.0
 launcher_width = 560.0
 launcher_radius = 20.0
 

docs/ferese-window-manager-spec.md

@@ -1127,7 +1127,7 @@ mass = 1.0
 [layout]
 mode = "scrolling"
 inner_gap = 10.0
-outer_gap = 10.0
+outer_gap = 4.0
 smart_gaps = false
 
 [scrolling]

docs/installation.md

@@ -0,0 +1,53 @@
+# Fedora / SDDM installation
+
+Build and test in the checkout:
+
+```sh
+cargo test -p ferese -p feresectl -p ferese-animation -p ferese-core -p ferese-layout -p ferese-shell --locked
+cargo build --release --locked -p ferese -p ferese-shell -p feresectl
+sudo bash scripts/install-session.sh YOUR_RELEASE_ID
+```
+
+The installer adds **Ferese** to SDDM without changing Plasma or
+the default session. It installs immutable, versioned directories in
+`/usr/local/lib/ferese/releases/` and launchers in `/usr/local/bin/`.
+`current` selects the installed build; `previous` records the prior selection
+on upgrades. Installation refuses to replace unmanaged launchers/session files.
+
+Keep your existing `~/.config/ferese/config.toml`. For a new configuration, copy
+`/usr/local/lib/ferese/current/config.example.toml` there. The existing compositor
+defaults handle connected monitors automatically; add output profiles only after
+checking `feresectl get-outputs` on the actual DRM session.
+
+Use `ferese-session --nested` for an installed-build preview. Log out of Plasma
+and select Ferese in SDDM for real hardware use. `ferese-session` can also run
+from a spare logged-in TTY. It must run as your normal user, never as root.
+Foot and `dbus-run-session` must be installed.
+
+Session logs are written under `${XDG_STATE_HOME:-~/.local/state}/ferese/`.
+The launcher sets Wayland desktop variables, starts D-Bus if none is available,
+and grants shell capabilities only to the compositor-launched shell process.
+It does not enable public screencopy, privileged input methods, or shortcut
+inhibition by default.
+
+## Logout and recovery
+
+Save your work, then press **Super+Shift+E** or run `feresectl exit` to log out.
+Ferese stops its event loop and terminates its shell child during shutdown.
+This is immediate logout, without a save-confirmation dialog.
+
+If the compositor becomes unresponsive, switch to another TTY using
+Ctrl+Alt+F1–F12 and terminate that specific Ferese process. Select Plasma on the
+next login. Do not restart SDDM while a desktop contains unsaved work.
+
+For a binary rollback, inspect `/usr/local/lib/ferese/previous` and select that
+release with the `current` symlink while Ferese is stopped. Existing releases
+are retained. To hide the login option, move
+`/usr/share/wayland-sessions/ferese.desktop` out of that directory.
+
+## First hardware session
+
+Verify terminal/editor/browser, clipboard, fullscreen, fractional scaling,
+monitor disconnect/reconnect, VT switching away/back, and logout. Suspend/resume
+and session locking are not certified by the nested smoke test. Keep Plasma
+available until real development sessions and these checks pass.

docs/nested-resize-testing.md

@@ -0,0 +1,61 @@
+# Nested live-resize regression check
+
+The shell enables libcosmic's `wgpu` feature. Without it, iced uses tiny-skia
+to resample and rasterize the wallpaper on the CPU. In an unoptimized build,
+this blocks the UI/render thread shared with the top bar for seconds. Prompt
+layer configures, buffer stretching, and compositor vsync cannot fix that
+client-side bottleneck. Software rendering remains available as a fallback.
+
+## Reproduce and compare
+
+```sh
+cargo build --locked -p ferese -p ferese-shell
+WAYLAND_DEBUG=1 FERESE_TRACE_PERFORMANCE=1 \
+  target/debug/ferese --backend nested --grant-effects --grant-shell-control -- \
+  target/debug/ferese-shell 2>/tmp/ferese-resize.log
+```
+
+Use a configured wallpaper. Drag the host window's edges in both directions,
+then maximize/restore it repeatedly. Check that the wallpaper and bar follow
+the window, including at fractional host scaling. Repeat with
+`ICED_BACKEND=wgpu` to require GPU rendering (rather than silently accepting
+fallback), and with `ICED_BACKEND=tiny-skia` to compare software rendering.
+Use a release build if software fallback is needed for regular use.
+
+Trace the chain, not just the compositor's frame rate:
+
+1. Host `xdg_toplevel.configure` becomes Winit `Resized`.
+2. Ferese updates the output, arranges layers, and sends
+   `zwlr_layer_surface_v1.configure` for the new logical dimensions.
+3. The shell acknowledges configure and eventually attaches/commits a new
+   buffer. A fast acknowledgement does **not** imply a finished render.
+4. Committed buffers change surface damage; Ferese renders the damaged output
+   and submits through EGL to the host compositor.
+
+`FERESE_TRACE_PERFORMANCE` measures Ferese's rendering/submission, not shell
+rasterization. Wayland traces distinguish software SHM buffers from GPU
+buffers (Mesa Vulkan on the tested system).
+
+## Measured validation (KDE Wayland, 175% scale)
+
+With temporary instrumentation, 24 host maximize/restore requests spaced
+250 ms apart generated 26 Winit resize events including initialization. The
+same debug binaries were tested with each renderer forced:
+
+| Measurement | tiny-skia | wgpu |
+| --- | ---: | ---: |
+| Median configure acknowledgement | 1.35 ms | 2.27 ms |
+| Median Ferese render + submit | 0.82 ms | 1.10 ms |
+| Wallpaper buffer interval | 5919 ms (only two buffers) | 9.85 ms median |
+| Bar buffers observed | 1 | 996 |
+
+The CPU capture ran for 14 seconds and the GPU capture for 18 seconds;
+counts are diagnostic, not equal-duration throughput benchmarks. GPU maximum
+buffer intervals were about 200 ms for wallpaper and 158 ms for the bar, so
+the median does not imply every frame met a refresh deadline. These figures
+include protocol tracing overhead. The temporary resize/timing hooks were
+removed after testing; no synthetic resizing runs in production.
+
+The fix does not alter output coordinates, layer exclusion, damage tracking,
+frame scheduling, or EGL swap settings. It also applies to the same shell
+running under DRM, though this validation used the nested backend.