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`.

src/event_loop/app_data.rs

@@ -103,6 +103,11 @@ pub struct AppData<A: App>
 	/// (resizes, scale changes) must not re-activate.
 	pub activation_token_pending: Option<String>,
 
+	/// `xdg-session-management-v1` proxies plus the on-disk store; the
+	/// store is `None` when persistence is off (layer / lock surfaces,
+	/// unusable app_id, concurrent instance, or after `replaced`).
+	pub session: super::session::SessionRuntime,
+
 	/// `wl_data_device_manager` binding. `None` when the compositor
 	/// does not advertise the global, in which case copy / paste stays
 	/// process-local and inbound selections from other clients are

src/event_loop/mod.rs

@@ -11,6 +11,7 @@ pub( crate ) mod focus;
 mod handlers;
 pub( crate ) mod perf;
 pub( crate ) mod repeat;
+pub( crate ) mod session;
 pub( crate ) mod subsurface;
 pub( crate ) mod surface;
 pub( crate ) mod text_editing;

src/event_loop/run.rs

@@ -51,7 +51,7 @@ pub( crate ) fn run<A: App>( app: A )
 /// The dispatch loop's runtime errors still panic — they are non-
 /// recoverable once the surface is on screen, and the surface state
 /// machine cannot be unwound cleanly from this entry point.
-pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
+pub( crate ) fn try_run<A: App>( mut app: A ) -> Result<(), RunError>
 {
 	let conn = Connection::connect_to_env()
 		.map_err( |e| RunError::NoWaylandConnection( format!( "{e}" ) ) )?;
@@ -66,6 +66,10 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 		.insert( event_loop.handle() )
 		.map_err( |e| RunError::EventLoop( format!( "WaylandSource::insert: {e:?}" ) ) )?;
 
+	// Before any thread exists: signalfd only sees signals blocked in the
+	// thread that created it, and the mask is inherited by later threads.
+	super::session::install_signal_source( &event_loop.handle() )?;
+
 	let compositor = CompositorState::bind( &globals, &qh )
 		.map_err( |e| RunError::MissingProtocol { name: "wl_compositor", detail: format!( "{e:?}" ) } )?;
 	let shm        = Shm::bind( &globals, &qh )
@@ -98,6 +102,26 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 	let force_window = app.window_config()
 		.map( |( t, id )| ( t.to_string(), id.to_string() ) );
 
+	let session_enabled = force_window.is_some() || matches!( app.shell_mode(), crate::app::ShellMode::Window );
+	let mut session = if session_enabled
+	{
+		super::session::SessionRuntime::bootstrap( &mut app )
+	} else {
+		super::session::SessionRuntime::disabled()
+	};
+	if session_enabled
+	{
+		session.bind( &globals, &qh );
+	}
+	let app_id = app.app_id().to_string();
+	if let Some( ( _, ref cfg_id ) ) = force_window
+	{
+		if cfg_id != &app_id
+		{
+			eprintln!( "ltk: window_config app_id {cfg_id:?} differs from App::app_id {app_id:?}; App::app_id wins" );
+		}
+	}
+
 	let bind_xdg = |globals: &smithay_client_toolkit::reexports::client::globals::GlobalList, qh: &smithay_client_toolkit::reexports::client::QueueHandle<AppData<A>>|
 		-> Result<XdgShell, RunError>
 	{
@@ -132,16 +156,28 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 		}
 	};
 
-	let ( surface_kind, xdg_shell ) = if let Some( ( ref title, ref app_id ) ) = force_window
+	// `restore_toplevel` must precede the first commit, so the session
+	// attach sits right before `commit()`.
+	let make_window = |xdg: &XdgShell, title: &str, session: &mut super::session::SessionRuntime, attach: bool|
 	{
-		let xdg     = bind_xdg( &globals, &qh )?;
 		let surface = compositor.create_surface( &qh );
 		let window  = xdg.create_window( surface, WindowDecorations::RequestServer, &qh );
-		window.set_title( title.as_str() );
+		window.set_title( title );
 		window.set_app_id( app_id.as_str() );
 		apply_size_hint( &window );
 		apply_fullscreen( &window );
+		if attach
+		{
+			session.attach_toplevel( &window, &qh );
+		}
 		window.commit();
+		window
+	};
+
+	let ( surface_kind, xdg_shell ) = if let Some( ( ref title, _ ) ) = force_window
+	{
+		let xdg    = bind_xdg( &globals, &qh )?;
+		let window = make_window( &xdg, title.as_str(), &mut session, true );
 		( SurfaceKind::Window( window ), Some( xdg ) )
 	} else {
 		// Use shell_mode() to determine surface type
@@ -154,13 +190,8 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 				( SurfaceKind::PendingLock, None )
 			}
 			ShellMode::Window => {
-				let xdg     = bind_xdg( &globals, &qh )?;
-				let surface = compositor.create_surface( &qh );
-				let window  = xdg.create_window( surface, WindowDecorations::RequestServer, &qh );
-				window.set_title( "ltk" );
-				window.set_app_id( "ltk" );
-				apply_size_hint( &window );
-				window.commit();
+				let xdg    = bind_xdg( &globals, &qh )?;
+				let window = make_window( &xdg, "ltk", &mut session, true );
 				( SurfaceKind::Window( window ), Some( xdg ) )
 			}
 			ShellMode::Layer( layer ) => {
@@ -180,13 +211,8 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 					( SurfaceKind::Pending( cfg ), None )
 				} else {
 					eprintln!( "ltk: wlr-layer-shell not available, falling back to xdg window" );
-					let xdg     = bind_xdg( &globals, &qh )?;
-					let surface = compositor.create_surface( &qh );
-					let window  = xdg.create_window( surface, WindowDecorations::RequestServer, &qh );
-					window.set_title( "ltk" );
-					window.set_app_id( "ltk" );
-					apply_size_hint( &window );
-					window.commit();
+					let xdg    = bind_xdg( &globals, &qh )?;
+					let window = make_window( &xdg, "ltk", &mut session, false );
 					( SurfaceKind::Window( window ), Some( xdg ) )
 				}
 			}
@@ -218,9 +244,7 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 	// platform adapter cannot be created (no daemon on the bus,
 	// headless CI, etc.) — the runtime then runs with no
 	// accessibility tree, which is the previous behaviour.
-	let a11y_app_name = "ltk-app";
-	let a11y_app_id   = "net.liberux.ltk";
-	let a11y = crate::a11y::A11yState::try_new( a11y_app_name, a11y_app_id );
+	let a11y = crate::a11y::A11yState::try_new( &app_id, &app_id );
 	// xdg-activation-v1: optional. Compositors that don't carry the
 	// global leave `activation_state` as `None` and the inbound /
 	// outbound activation paths silently degrade to no-ops.
@@ -286,6 +310,7 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 		text_input_secure:  false,
 		activation_state,
 		activation_token_pending,
+		session,
 		data_device_manager,
 		data_device:        None,
 		clipboard_source:   None,
@@ -407,6 +432,11 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 			.map_err( |e| RunError::EventLoop( format!( "poll timer insert_source: {e:?}" ) ) )?;
 	}
 
+	if data.session.store.is_some()
+	{
+		super::session::install_save_timer( &event_loop.handle() )?;
+	}
+
 	while !data.exit_requested
 	{
 		// Sleep until something interesting fires:
@@ -702,7 +732,7 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 						offset_y:            *oy,
 					} );
 				}
-				let app_name = "ltk-app";
+				let app_name = data.app.app_id();
 				a.update( || crate::a11y::tree::build_tree( &surfaces, kb_focus_id, app_name ) );
 			}
 			data.a11y = a11y_taken;
@@ -912,5 +942,7 @@ pub( crate ) fn try_run<A: App>( app: A ) -> Result<(), RunError>
 		}
 	}
 
+	data.session.on_exit( &data.app );
+
 	Ok( () )
 }

src/event_loop/session.rs

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: LGPL-2.1-only
+// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>
+
+//! `xdg-session-management-v1` client glue plus the runtime hooks that
+//! persist `App::save_state` and turn signals into a clean exit.
+
+use std::time::Duration;
+
+use calloop::timer::{ TimeoutAction, Timer };
+use calloop::LoopHandle;
+use smithay_client_toolkit::reexports::client::globals::GlobalList;
+use smithay_client_toolkit::reexports::client::{ Connection, Dispatch, QueueHandle };
+use smithay_client_toolkit::shell::xdg::window::Window;
+
+use crate::app::App;
+use crate::protocol::xdg_session_management_v1::
+{
+	xdg_session_manager_v1::{ self, XdgSessionManagerV1 },
+	xdg_session_v1::{ self, XdgSessionV1 },
+	xdg_toplevel_session_v1::{ self, XdgToplevelSessionV1 },
+};
+use crate::session_state::{ RestoreReason, Startup, StateStore };
+
+use super::error::RunError;
+use super::AppData;
+
+pub( crate ) const TOPLEVEL_NAME: &str = "main";
+pub( crate ) const SAVE_INTERVAL: Duration = Duration::from_secs( 30 );
+pub( crate ) const RESTORE_ENV: &str = "LTK_SESSION_RESTORE";
+
+pub( crate ) struct SessionRuntime
+{
+	pub session:          Option<XdgSessionV1>,
+	pub toplevel_session: Option<XdgToplevelSessionV1>,
+	/// `None` when persistence is off: layer / lock surfaces, an unusable
+	/// app_id, a concurrent instance, or after `replaced`.
+	pub store:            Option<StateStore>,
+	pub reason:           RestoreReason,
+	pub replaced:         bool,
+}
+
+impl SessionRuntime
+{
+	pub fn disabled() -> Self
+	{
+		Self {
+			session:          None,
+			toplevel_session: None,
+			store:            None,
+			reason:           RestoreReason::Launch,
+			replaced:         false,
+		}
+	}
+
+	/// Phase 1, before any window exists: read the restore hint from the
+	/// environment, decide the reason, hand saved bytes to the app and mark
+	/// the run as live.
+	pub fn bootstrap<A: App>( app: &mut A ) -> Self
+	{
+		let env_restore = std::env::var_os( RESTORE_ENV ).is_some_and( |v| v == "1" );
+		if std::env::var_os( RESTORE_ENV ).is_some()
+		{
+			// SAFETY: removing an env var is sound only when no other thread
+			// is reading the environment concurrently. We are still in the
+			// init phase before `set_channel_sender`, so the app has had
+			// no opportunity to spawn worker threads yet.
+			unsafe { std::env::remove_var( RESTORE_ENV ); }
+		}
+
+		let mut rt = Self::disabled();
+		let Some( mut store ) = StateStore::open( app.app_id() ) else { return rt };
+		match store.decide( env_restore )
+		{
+			Startup::Concurrent =>
+			{
+				eprintln!( "ltk: another instance of {} is running; session persistence disabled", app.app_id() );
+				return rt;
+			}
+			Startup::Reason( reason ) => rt.reason = reason,
+		}
+		if rt.reason != RestoreReason::Launch
+		{
+			if let Some( bytes ) = store.load_state()
+			{
+				app.restore_state( bytes );
+			}
+		}
+		store.mark_running();
+		rt.store = Some( store );
+		rt
+	}
+
+	/// Phase 2: bind the manager and open the session. Silent when the
+	/// compositor lacks the global. The manager proxy is not kept: it has
+	/// no state of its own and the session outlives it server-side.
+	pub fn bind<A: App>( &mut self, globals: &GlobalList, qh: &QueueHandle<AppData<A>> )
+	{
+		let Some( store ) = &self.store else { return };
+		let manager: Option<XdgSessionManagerV1> = globals.bind( qh, 1..=1, () ).ok();
+		let Some( manager ) = manager else { return };
+		let reason = match self.reason
+		{
+			RestoreReason::Launch         => xdg_session_manager_v1::Reason::Launch,
+			RestoreReason::Recover        => xdg_session_manager_v1::Reason::Recover,
+			RestoreReason::SessionRestore => xdg_session_manager_v1::Reason::SessionRestore,
+		};
+		self.session = Some( manager.get_session( reason, store.session_id(), qh, () ) );
+	}
+
+	/// Phase 3: register the main toplevel. Must run before the window's
+	/// first commit or the compositor raises `already_mapped`.
+	pub fn attach_toplevel<A: App>( &mut self, window: &Window, qh: &QueueHandle<AppData<A>> )
+	{
+		let Some( session ) = &self.session else { return };
+		self.toplevel_session =
+			Some( session.restore_toplevel( window.xdg_toplevel(), TOPLEVEL_NAME.to_string(), qh, () ) );
+	}
+
+	pub fn periodic_save<A: App>( &mut self, app: &A )
+	{
+		if self.replaced { return; }
+		if let Some( store ) = &mut self.store
+		{
+			store.save_state_if_changed( app.save_state() );
+		}
+	}
+
+	pub fn on_exit<A: App>( &mut self, app: &A )
+	{
+		if self.replaced { return; }
+		if let Some( store ) = &mut self.store
+		{
+			store.mark_clean_exit( app.save_state() );
+		}
+	}
+
+	pub fn on_replaced( &mut self )
+	{
+		eprintln!( "ltk: session taken over by another instance; this one stops persisting state" );
+		if let Some( t ) = self.toplevel_session.take() { t.destroy(); }
+		if let Some( s ) = self.session.take() { s.destroy(); }
+		self.replaced = true;
+		self.store = None;
+	}
+}
+
+pub( crate ) fn install_signal_source<A: App>( handle: &LoopHandle<'static, AppData<A>> ) -> Result<(), RunError>
+{
+	use calloop::signals::{ Signal, Signals };
+	let signals = Signals::new( &[ Signal::SIGTERM, Signal::SIGINT ] )
+		.map_err( |e| RunError::EventLoop( format!( "Signals::new: {e}" ) ) )?;
+	handle
+		.insert_source( signals, |event, _, data: &mut AppData<A>|
+		{
+			eprintln!( "ltk: {:?} received, exiting cleanly", event.signal() );
+			data.exit_requested = true;
+		} )
+		.map_err( |e| RunError::EventLoop( format!( "signals insert_source: {e:?}" ) ) )?;
+	Ok( () )
+}
+
+pub( crate ) fn install_save_timer<A: App>( handle: &LoopHandle<'static, AppData<A>> ) -> Result<(), RunError>
+{
+	handle
+		.insert_source( Timer::from_duration( SAVE_INTERVAL ), |_, _, data: &mut AppData<A>|
+		{
+			data.session.periodic_save( &data.app );
+			TimeoutAction::ToDuration( SAVE_INTERVAL )
+		} )
+		.map_err( |e| RunError::EventLoop( format!( "save timer insert_source: {e:?}" ) ) )?;
+	Ok( () )
+}
+
+impl<A: App> Dispatch<XdgSessionManagerV1, ()> for AppData<A>
+{
+	fn event(
+		_state: &mut Self,
+		_proxy: &XdgSessionManagerV1,
+		_event: xdg_session_manager_v1::Event,
+		_data:  &(),
+		_conn:  &Connection,
+		_qh:    &QueueHandle<Self>,
+	)
+	{
+	}
+}
+
+impl<A: App> Dispatch<XdgSessionV1, ()> for AppData<A>
+{
+	fn event(
+		state:  &mut Self,
+		_proxy: &XdgSessionV1,
+		event:  xdg_session_v1::Event,
+		_data:  &(),
+		_conn:  &Connection,
+		_qh:    &QueueHandle<Self>,
+	)
+	{
+		match event
+		{
+			xdg_session_v1::Event::Created { session_id } =>
+			{
+				if let Some( store ) = &mut state.session.store
+				{
+					store.set_session_id( session_id );
+				}
+			}
+			xdg_session_v1::Event::Restored => {}
+			xdg_session_v1::Event::Replaced => state.session.on_replaced(),
+		}
+	}
+}
+
+impl<A: App> Dispatch<XdgToplevelSessionV1, ()> for AppData<A>
+{
+	fn event(
+		_state: &mut Self,
+		_proxy: &XdgToplevelSessionV1,
+		_event: xdg_toplevel_session_v1::Event,
+		_data:  &(),
+		_conn:  &Connection,
+		_qh:    &QueueHandle<Self>,
+	)
+	{
+	}
+}