Session management: xdg-session-management-v1 client, mandatory App::app_id / save_state / restore_state, runtime-managed state persistence and clean exit on signals (0.3.0)

Applications built on ltk had no way to come back where the user left them: the toolkit hardcoded `app_id = "ltk"` on every toplevel, never wrote anything to disk, and died on SIGTERM without a chance to save. This release gives the runtime the whole plumbing and asks each application only for the bytes worth keeping, in the spirit of Android's saved-instance state.
The `App` trait gains three mandatory methods, deliberately without default bodies so every application states its position: `app_id()` (reverse-DNS, used for `xdg_toplevel.set_app_id`, the AccessKit application name and the state directory — the `app_id` element of the deprecated `window_config` tuple is now ignored and a one-time warning reports a mismatch), `save_state() -> Option<Vec<u8>>` and `restore_state(Vec<u8>)`. The bytes are opaque; the trait carries no serde bound. Their rustdoc is the contract: when the runtime saves, where the files live, when the bytes come back and when they do not, what must never go in them, and a worked serde_json example.
The runtime persists under `$XDG_STATE_HOME/<app_id>/` (falling back to `~/.local/state`): `session.json` holds the compositor session id, a clean-exit marker and the writer's pid; `state.bin` holds the application bytes. Writes are atomic (temp file + rename, mode 0600, directory 0700) and best-effort. State is saved every 30 s when the bytes changed, once after the event loop exits (which covers `on_close_requested`, `requested_exit` and lost connections), and on SIGTERM/SIGINT — a calloop signal source, installed before any thread exists, now turns those into a clean exit of the loop instead of process death. `restore_state` runs synchronously in `try_run` before the window is created and before the first `view()`, and only when the process is relaunched as part of a session restore (`LTK_SESSION_RESTORE=1`, removed from the environment before the app can spawn children) or when the previous run left `clean_exit: false`; a plain launch starts fresh. A second concurrent instance detects the live pid and runs with persistence disabled rather than clobbering the first.
The compositor side of geometry restore goes through `xdg-session-management-v1`. Neither wayland-protocols nor sctk ship generated code for it yet, so the XML is vendored under `protocols/` and `wayland-scanner` generates the client module in-tree (`src/protocol/`), resolving the crate names through sctk's reexports so the bindings stay on the crate instances sctk links. Before the first commit of a `ShellMode::Window` toplevel the runtime binds `xdg_session_manager_v1`, calls `get_session(reason, stored_id)` and `restore_toplevel(toplevel, "main")`; the three window-creation paths in `run.rs` are folded into one `make_window` helper so the attach always sits immediately before `commit()`. `created` persists the id, `replaced` destroys the objects and stops persisting. Compositors without the global lose only the geometry half. Layer-shell and session-lock surfaces skip the whole machinery.
Every `App` implementor in the tree is updated: the twelve examples (`showcase`, `scroll` and `mini_shell` persist real state; the rest return `None`), both integration tests (`event_loop_flow` gains `save_restore_round_trip`), the in-source and markdown doctests, README, onboarding, cookbook (new recipe "Surviving relaunch: session state") and architecture docs, and the changelog. `src/session_state.rs` carries unit tests over a temporary state directory. `Makefile install` now copies `protocols/` into the cargo registry — without it downstream builds would fail inside the proc-macro — and `debian/copyright` covers the vendored XML.
The trait change is breaking, hence 0.3.0. Also fixes the pre-existing `viewport_tests` module in `render/mod.rs`, which used `Length` without importing it and broke `cargo test`.

docs/cookbook.md

@@ -23,6 +23,7 @@ reference, see [`docs/widgets.md`](./widgets.md). For theme JSON, see
 - [Toast / OSD with auto-expiry](#toast--osd-with-auto-expiry)
 - [Tab navigation between widgets](#tab-navigation-between-widgets)
 - [Multi-screen app via sub-state pattern](#multi-screen-app-via-sub-state-pattern)
+- [Surviving relaunch: session state](#surviving-relaunch-session-state)
 - [Embedding ltk without `ltk::run`](#embedding-ltk-without-ltkrun)
 - [Custom CPU drawing and path clipping](#custom-cpu-drawing-and-path-clipping)
 - [Projecting an externally-laid-out view tree](#projecting-an-externally-laid-out-view-tree)
@@ -175,6 +176,10 @@ impl App for LoginApp
 {
 	type Message = Msg;
 
+	fn app_id( &self ) -> &str { "net.example.Login" }
+	fn save_state( &self ) -> Option<Vec<u8>> { None }
+	fn restore_state( &mut self, _state: Vec<u8> ) {}
+
 	fn view( &self ) -> Element<Msg>
 	{
 		column()
@@ -418,6 +423,10 @@ impl App for LauncherApp
 {
 	type Message = Msg;
 
+	fn app_id( &self ) -> &str { "net.example.Launcher" }
+	fn save_state( &self ) -> Option<Vec<u8>> { None }
+	fn restore_state( &mut self, _state: Vec<u8> ) {}
+
 	fn view( &self ) -> Element<Msg>
 	{
 		let mut grid = grid::<Msg>( 4 )
@@ -565,6 +574,10 @@ impl App for AppState
 {
 	type Message = Msg;
 
+	fn app_id( &self ) -> &str { "net.example.Toast" }
+	fn save_state( &self ) -> Option<Vec<u8>> { None }
+	fn restore_state( &mut self, _state: Vec<u8> ) {}
+
 	fn view( &self ) -> Element<Msg> { self.main_view() }
 
 	fn overlays( &self ) -> Vec<OverlaySpec<Msg>>
@@ -665,6 +678,10 @@ impl App for LoginApp
 {
 	type Message = Msg;
 
+	fn app_id( &self ) -> &str { "net.example.Login" }
+	fn save_state( &self ) -> Option<Vec<u8>> { None }
+	fn restore_state( &mut self, _state: Vec<u8> ) {}
+
 	fn view( &self ) -> Element<Msg>
 	{
 		column()
@@ -752,6 +769,26 @@ impl App for AppState
 {
 	type Message = AppMsg;
 
+	fn app_id( &self ) -> &str { "net.example.MultiScreen" }
+
+	// Persist only the routing; each screen would add its own line.
+	fn save_state( &self ) -> Option<Vec<u8>>
+	{
+		let s = match self.current { Screen::Home => "home", Screen::Settings => "settings", Screen::About => "about" };
+		Some( s.as_bytes().to_vec() )
+	}
+
+	fn restore_state( &mut self, state: Vec<u8> )
+	{
+		match state.as_slice()
+		{
+			b"home"     => self.current = Screen::Home,
+			b"settings" => self.current = Screen::Settings,
+			b"about"    => self.current = Screen::About,
+			_           => {}
+		}
+	}
+
 	fn view( &self ) -> Element<AppMsg>
 	{
 		let body = match self.current
@@ -798,6 +835,88 @@ per screen.
 
 ---
 
+## Surviving relaunch: session state
+
+The runtime persists whatever `App::save_state` returns and hands it
+back through `App::restore_state` before the first frame — but only
+when the shell relaunches the app as part of a session restore
+(`LTK_SESSION_RESTORE=1` in the environment) or when the previous run
+did not exit cleanly. A plain launch starts fresh, Android-style;
+window size and position still come back on every launch through
+`xdg-session-management-v1`.
+
+The bytes are yours: version them, and treat a parse failure as "keep
+the defaults". No serde needed for small state.
+
+```rust,no_run
+# use ltk::{ column, text, text_edit, App, Element };
+#[derive(Clone)]
+enum Msg { Tab( usize ), Draft( String ) }
+
+struct Editor { tab: usize, draft: String }
+
+impl App for Editor
+{
+	type Message = Msg;
+
+	fn app_id( &self ) -> &str { "net.example.Editor" }
+
+	fn save_state( &self ) -> Option<Vec<u8>>
+	{
+		// Line 1 is the format version; the draft goes last so it may
+		// contain newlines.
+		Some( format!( "1\n{}\n{}", self.tab, self.draft ).into_bytes() )
+	}
+
+	fn restore_state( &mut self, state: Vec<u8> )
+	{
+		let Ok( text ) = String::from_utf8( state ) else { return };
+		let mut parts = text.splitn( 3, '\n' );
+		if parts.next() != Some( "1" ) { return; }
+		if let Some( tab ) = parts.next().and_then( |t| t.parse().ok() ) { self.tab = tab; }
+		if let Some( draft ) = parts.next() { self.draft = draft.to_string(); }
+	}
+
+	fn view( &self ) -> Element<Msg>
+	{
+		column()
+			.push( text( format!( "tab {}", self.tab ) ) )
+			.push( text_edit( "Draft", &self.draft ).on_change( Msg::Draft ) )
+			.into()
+	}
+
+	fn update( &mut self, msg: Msg )
+	{
+		match msg
+		{
+			Msg::Tab( t )   => self.tab   = t,
+			Msg::Draft( d ) => self.draft = d,
+		}
+	}
+}
+```
+
+The runtime saves in three situations: every ~30 s while the bytes
+differ from the last save, when the window closes, and on `SIGTERM` /
+`SIGINT` (which ltk turns into a clean exit of the event loop). Files
+land in `$XDG_STATE_HOME/<app_id>/` — `state.bin` for your bytes,
+`session.json` for the compositor session id and the clean-exit marker.
+
+To try it: run the app, change something, `kill -TERM $(pidof my-app)`,
+then start it again with `LTK_SESSION_RESTORE=1 my-app` — the state is
+back. Start it without the variable and it opens fresh (the window
+still lands where you left it). `kill -KILL` instead of `-TERM` and the
+next plain launch restores too, because the marker says the last run
+never exited cleanly.
+
+Shell components (layer-shell panels, lock screens) have no toplevel and
+are never persisted: return `None` and leave `restore_state` empty.
+
+**See also**: `App::save_state` / `App::restore_state` rustdoc for the
+full contract, and [`docs/architecture.md`](./architecture.md#known-gaps-and-non-goals) for the protocol status.
+
+---
+
 ## Embedding ltk without `ltk::run`
 
 A compositor or embedder that already owns the Wayland connection and