docs overhaul, orientation API, fluid-sizing fixes, examples made honest

Documentation pass: every claim in docs/ and the meta files was audited against the source and the drift fixed — around ninety corrections. CONTRIBUTING and the CI workflow now run cargo test with --features test-support (the gated test_support module made both the documented commands and the CI build fail to compile), make example becomes make examples, make doctest-md and the debhelper requirement of make clean are documented, and patch shape asks for a CHANGELOG entry. theming.md loses the nonexistent surface.backdrop, gains the real gradient defaults (linear-rgb, oklab), the six slot variants including typography, the ten-field palette, a truthful effects-consumer table, the ThemePreference/from_hour API and a responsive-sizing note; the stale docstrings in src/theme that fed the drift are fixed too. architecture.md's "Known gaps" section is rewritten against reality (multi-touch slots, xdg-activation, a11y live regions and SetValue/Increment/Decrement are implemented), gains a module map, subsurfaces and window-lifecycle coverage, and correct crustace/loginmanager paths. widgets.md fixes the ten factual errors (stateless spinner, toast/combo via overlays(), tooltip hover contract, row has no max_width, scroll axes, multiline text_edit, dialog panic wording) and now states the column() 16 px default padding — the recurring ambush — plus row's differing 0 default and dialog's max_width. onboarding, README and cookbook get the remaining sweep: build/test instructions, complete example lists, img_widget, clipping-parity honesty, ~30 Hz software cap, read_rgba_pixels signature, tab indentation in snippets, and rustdoc-style links that rendered literally are gone everywhere. CHANGELOG is restructured per Keep a Changelog with the missing entries (window_resizable, claims_raw_touch, Row::align_top/fill_height, caret fixes, dependency pins) and the pad_v Added/Changed contradiction resolved.
New adaptive-layout API: ltk::orientation() with the Orientation enum, backed by viewport_size()/set_viewport_size — the runtime records the main surface's physical dimensions on every configure, before App::on_resize, so view() can branch a layout on portrait vs landscape without hand-tracking resizes. The portrait rule matches Length::orient (square counts as portrait); embedders driving core::UiSurface call set_viewport_size themselves. Documented in the crate root's responsive-design section and architecture.md.
Fluid-vs-fixed sizing fixes in widgets, all the same disease — fluid content inside a fixed-pixel box. TextEdit::fixed_width takes impl Into<Length> (f32 call sites keep compiling as px) and the time picker's digit fields move to Length::fluid( 72.0 ), matching their fluid font so digits can no longer outgrow the box. Dialog::max_width takes impl Into<Length> with a Length::fluid( 480.0 ) default so the card scales with the stock buttons inside it, and the card's interior no longer stacks the column() default 16 px padding on top of CARD_PADDING — that double inset squeezed the action row until its buttons clipped on narrow windows. App::on_pointer_axis now triggers a view rebuild and repaint; previously state mutated in the hook did not paint until the next unrelated event.
Examples reworked to be honest demos: responsive's mode/density controls become stock buttons in a grid/column so they follow the modes they demonstrate instead of overflowing; dialog's openers stack vertically, and the example gains the app-level ESC handler so the ESC chain closes an open dialog first and quits second; widgets' tab strip now switches real per-tab pages; carousel gains pointer/touch drag through the horizontal-swipe hooks (crustace's pager pattern), one-tile-per-detent mouse wheel, and snap math driven by the real surface width from on_resize instead of a hardcoded 800; clip_path arranges its cells by ltk::orientation() and sizes them from the counter-axis of the flow.

examples/carousel.rs

@@ -9,11 +9,14 @@
 //!
 //! The carousel widget itself is a stateless layout primitive — the
 //! `offset` (positive shifts content right) is owned by the host. The
-//! example mutates that offset directly when Prev / Next / arrow keys
-//! change the focused index; in a real touch-driven app the host would
-//! drive it from drag / inertia / snap-ease.
+//! example drives it three ways: Prev / Next buttons and arrow keys
+//! snap to an index, and a pointer / touch drag pans it live through
+//! the `App` horizontal-swipe hooks (`on_swipe_horizontal_progress`
+//! for follow-the-finger, `on_swipe_left` / `on_swipe_right` for the
+//! commit) — the same pattern crustace's homescreen pager uses.
 //!
-//! Esc quits. Arrow keys = Prev / Next.
+//! Esc quits. Arrow keys = Prev / Next. Drag horizontally to pan, or
+//! step tile by tile with the mouse wheel.
 //!
 //! NOTE: ltk is a Wayland layer-shell toolkit. This example needs a
 //! running Wayland compositor.
@@ -33,17 +36,19 @@ enum Message
 
 struct CarouselApp
 {
-	focused:  usize,
-	offset:   f32,
-	last_msg: String,
+	focused:     usize,
+	offset:      f32,
+	last_msg:    String,
+	viewport_w:  f32,
+	wheel_accum: f32,
 }
 
 const TILE_COUNT: usize = 7;
 
-/// Approximate viewport width used to translate "focused index → offset".
-/// Real apps would derive this from the laid-out viewport rect; for an
-/// example the constant keeps the focus / step math obvious.
-const VIEWPORT_W: f32 = 800.0;
+/// Horizontal padding around the carousel (the root column's 16 px per
+/// side) — subtracted from the surface width to get the carousel's real
+/// viewport, so the snap / drag math matches what the widget draws.
+const H_PADDING: f32 = 32.0;
 const FOCUSED_FRAC: f32 = 0.7;
 const GAP: f32 = 16.0;
 
@@ -61,12 +66,12 @@ impl CarouselApp
 {
 	fn new() -> Self
 	{
-		Self { focused: 0, offset: 0.0, last_msg: String::new() }
+		Self { focused: 0, offset: 0.0, last_msg: String::new(), viewport_w: 800.0 - H_PADDING, wheel_accum: 0.0 }
 	}
 
 	fn snap_offset_for( &self, focused: usize ) -> f32
 	{
-		let stride = VIEWPORT_W * FOCUSED_FRAC + GAP;
+		let stride = self.viewport_w * FOCUSED_FRAC + GAP;
 		-( focused as f32 ) * stride
 	}
 }
@@ -108,7 +113,7 @@ impl App for CarouselApp
 
 		let status_line = if self.last_msg.is_empty()
 		{
-			text( "← / → cycle  ·  click Activate to fire Message::Tile  ·  Esc quits" )
+			text( "← / → cycle  ·  drag or wheel to pan  ·  click Activate to fire Message::Tile  ·  Esc quits" )
 				.size( 12.0 )
 				.color( secondary )
 				.align_center()
@@ -146,16 +151,18 @@ impl App for CarouselApp
 				if self.focused > 0
 				{
 					self.focused -= 1;
-					self.offset = self.snap_offset_for( self.focused );
 				}
+				// Always re-snap: a drag committed at the first / last
+				// tile leaves the strip displaced otherwise.
+				self.offset = self.snap_offset_for( self.focused );
 			}
 			Message::Next =>
 			{
 				if self.focused + 1 < TILE_COUNT
 				{
 					self.focused += 1;
-					self.offset = self.snap_offset_for( self.focused );
 				}
+				self.offset = self.snap_offset_for( self.focused );
 			}
 			Message::Tile( i ) =>
 			{
@@ -174,6 +181,62 @@ impl App for CarouselApp
 			_              => None,
 		}
 	}
+
+	fn on_resize( &mut self, width: u32, _height: u32 )
+	{
+		self.viewport_w = width as f32 - H_PADDING;
+		// Keep the focused tile centred through window resizes.
+		self.offset = self.snap_offset_for( self.focused );
+	}
+
+	// Wheel / touchpad scroll steps the strip one tile at a time. One
+	// wheel detent arrives as ~100-150 units (the compositor's ~10-15
+	// per detent times the runtime's wheel multiplier), touchpads as a
+	// continuous stream of small deltas — so accumulate up to a detent
+	// and step at most once per event, resetting the residue so a
+	// coarse wheel cannot burst through several tiles.
+	fn on_pointer_axis( &mut self, _x: f32, _y: f32, dx: f32, dy: f32 )
+	{
+		const DETENT: f32 = 100.0;
+		// Wheels report one axis at a time; take the dominant one so a
+		// tilt-wheel or horizontal touchpad flick also pans the strip.
+		self.wheel_accum += if dx.abs() > dy.abs() { dx } else { dy };
+		if self.wheel_accum.abs() < DETENT { return; }
+		let forward = self.wheel_accum > 0.0;
+		self.wheel_accum = 0.0;
+		if forward
+		{
+			if self.focused + 1 < TILE_COUNT { self.focused += 1; }
+		} else if self.focused > 0 {
+			self.focused -= 1;
+		}
+		self.offset = self.snap_offset_for( self.focused );
+	}
+
+	// Pointer / touch drag, the same pattern crustace's homescreen pager
+	// uses: live progress pans the strip, a committed swipe steps the
+	// focus, and the cancellation sample (0.0) snaps back.
+
+	fn swipe_horizontal_threshold( &self ) -> f32 { 0.35 }
+
+	fn on_swipe_horizontal_progress( &mut self, progress: f32 )
+	{
+		// `progress` is dx / (threshold × width): ±1.0 marks the commit
+		// threshold. A release without commit delivers one final 0.0.
+		let dx  = progress * ( self.viewport_w + H_PADDING ) * self.swipe_horizontal_threshold();
+		let min = self.snap_offset_for( TILE_COUNT - 1 );
+		self.offset = ( self.snap_offset_for( self.focused ) + dx ).clamp( min, 0.0 );
+	}
+
+	fn on_swipe_left( &mut self ) -> Option<Message>
+	{
+		Some( Message::Next )
+	}
+
+	fn on_swipe_right( &mut self ) -> Option<Message>
+	{
+		Some( Message::Prev )
+	}
 }
 
 fn main()

examples/clip_path.rs

@@ -17,7 +17,9 @@ enum Msg {}
 
 struct Demo;
 
-const CELL:   f32 = 220.0;
+/// Floor for the square cells — the orientation-derived size never
+/// shrinks below this, so the shapes stay readable on tiny windows.
+const CELL_MIN: f32 = 120.0;
 const MARGIN: f32 = 24.0;
 
 fn bg() -> Color { Color::rgba( 0.16, 0.18, 0.22, 1.0 ) }
@@ -76,9 +78,9 @@ fn triangle_path( r: Rect ) -> Vec<PathCmd>
 /// A cell that paints `bg()` everywhere, then `fg()` clipped to `shape`. The
 /// previous clip is snapshotted and restored so the clip does not leak to the
 /// rest of the frame.
-fn clipped_cell( shape: fn( Rect ) -> Vec<PathCmd> ) -> Element<Msg>
+fn clipped_cell( size: f32, shape: fn( Rect ) -> Vec<PathCmd> ) -> Element<Msg>
 {
-	External::cpu( CELL, CELL, move |canvas, rect|
+	External::cpu( size, size, move |canvas, rect|
 	{
 		canvas.fill_rect( rect, bg(), 0.0 );
 		let saved = canvas.clip_bounds();
@@ -94,17 +96,45 @@ impl App for Demo
 
 	fn view( &self ) -> Element<Msg>
 	{
+		// Cells side by side in landscape, stacked in portrait; the
+		// runtime rebuilds the view on every configure, so both the
+		// arrangement and the cell size follow the window live. The
+		// square side comes from the axis the cells do NOT flow along
+		// (the height in landscape, the width in portrait), capped so
+		// the three of them also fit along the flow axis with the
+		// paddings and gaps accounted for.
+		let ( vw, vh ) = ltk::viewport_size();
+		let ( vw, vh ) = ( vw as f32, vh as f32 );
+		let cells: Element<Msg> = match ltk::orientation()
+		{
+			ltk::Orientation::Landscape =>
+			{
+				let cell = ( vh * 0.5 ).min( ( vw - 80.0 ) / 3.0 ).max( CELL_MIN );
+				row()
+					.spacing( 16.0 )
+					.push( clipped_cell( cell, |r| rounded_rect_path( r, 32.0 ) ) )
+					.push( clipped_cell( cell, circle_path ) )
+					.push( clipped_cell( cell, triangle_path ) )
+					.into()
+			}
+			ltk::Orientation::Portrait =>
+			{
+				let cell = ( vw * 0.55 ).min( ( vh - 130.0 ) / 3.0 ).max( CELL_MIN );
+				column()
+					.padding( 0.0 )
+					.spacing( 16.0 )
+					.push( clipped_cell( cell, |r| rounded_rect_path( r, 32.0 ) ) )
+					.push( clipped_cell( cell, circle_path ) )
+					.push( clipped_cell( cell, triangle_path ) )
+					.into()
+			}
+		};
+
 		column()
 			.spacing( 16.0 )
 			.padding( 24.0 )
 			.push( text( "Canvas::set_clip_path — rounded rect, circle, triangle" ) )
-			.push(
-				row()
-					.spacing( 16.0 )
-					.push( clipped_cell( |r| rounded_rect_path( r, 32.0 ) ) )
-					.push( clipped_cell( circle_path ) )
-					.push( clipped_cell( triangle_path ) )
-			)
+			.push( cells )
 			.into()
 	}
 

examples/dialog.rs

@@ -13,8 +13,8 @@
 //!   between the subtitle and the action row.
 
 use ltk::{
-	App, ButtonVariant, Element,
-	button, column, dialog, row, slider, spacer, stack, text,
+	App, ButtonVariant, Element, Keysym,
+	button, column, dialog, slider, spacer, stack, text,
 };
 
 #[ derive( Clone, Copy, PartialEq, Eq ) ]
@@ -76,7 +76,11 @@ impl App for DialogApp
 				.color( secondary )
 				.wrap( true ) );
 
-		let openers = row::<Msg>()
+		// Stacked, not a row: a centered row overflows both edges as
+		// soon as the fluid button sizes outgrow the window, while a
+		// column clamps each button to the available width.
+		let openers = column::<Msg>()
+			.padding( 0.0 )
 			.spacing( 12.0 )
 			.push(
 				button::<Msg>( "Modal confirm" )
@@ -144,6 +148,15 @@ impl App for DialogApp
 			Msg::BrightnessChanged( v )   => { self.brightness = v; }
 		}
 	}
+
+	// Only reached when no dialog is open: with one on screen, the ESC
+	// dispatch chain fires the scrim's `on_escape` (the dialog's cancel)
+	// before the app ever sees the key. First ESC closes, second quits.
+	fn on_key( &mut self, keysym: Keysym ) -> Option<Msg>
+	{
+		if keysym == Keysym::Escape { std::process::exit( 0 ); }
+		None
+	}
 }
 
 fn modal_confirm() -> Element<Msg>

examples/responsive.rs

@@ -19,7 +19,7 @@
 use ltk::
 {
 	App, Element, Keysym, ButtonVariant, WidgetScaling,
-	button, checkbox, column, progress_bar, row, separator, slider, spacer, text, text_edit, toggle,
+	button, checkbox, column, grid, progress_bar, separator, slider, spacer, text, text_edit, toggle,
 	set_widget_scaling, set_density, density,
 };
 
@@ -81,21 +81,22 @@ impl App for ResponsiveApp
 
 		// Mode + density controls. Explicit sizes here so the controls stay
 		// stable while the demo widgets below react to the mode.
-		let controls = row::<Message>()
-			.spacing( 12.0 )
+		// Mode + density controls. Stock buttons like the demo widgets
+		// below, so they follow the active mode too. The switch gets the
+		// full width and the density pair half a cell each: every button
+		// clamps to its slot instead of overflowing a shared row, and the
+		// slots leave room for Physical-mode text at raised densities.
+		let controls = column::<Message>()
+			.padding( 0.0 )
+			.spacing( 8.0 )
 			.push( button::<Message>( "Switch mode".to_string() )
 				.variant( ButtonVariant::Primary )
-				.font_size( 16.0 )
-				.height( 44.0 )
 				.on_press( Message::SwitchMode ) )
-			.push( button::<Message>( "− density".to_string() )
-				.font_size( 16.0 )
-				.height( 44.0 )
-				.on_press( Message::DensityDown ) )
-			.push( button::<Message>( "＋ density".to_string() )
-				.font_size( 16.0 )
-				.height( 44.0 )
-				.on_press( Message::DensityUp ) );
+			.push( grid::<Message>( 2 )
+				.push( button::<Message>( "− density".to_string() )
+					.on_press( Message::DensityDown ) )
+				.push( button::<Message>( "＋ density".to_string() )
+					.on_press( Message::DensityUp ) ) );
 
 		// The demo widgets — NO explicit sizes, so they follow the mode.
 		let demo = column::<Message>()

examples/widgets.rs

@@ -75,15 +75,11 @@ impl App for WidgetsApp
 
 		let title = text( "ltk widgets" ).size( 24.0 ).color( primary ).align_center();
 
-		// Segmented tab strip — selection just rendered as a banner below.
+		// Segmented tab strip — each tab shows its own page below.
 		let tabs_strip: Element<Msg> = tabs( [ "General", "Audio", "Network" ] )
 			.selected( self.tab )
 			.on_select( Msg::SelectTab )
 			.into();
-		let tab_label = format!(
-			"Active tab: {}",
-			[ "General", "Audio", "Network" ][ self.tab.min( 2 ) ],
-		);
 
 		let toggles = column::<Msg>()
 			.spacing( 0.0 )
@@ -124,29 +120,44 @@ impl App for WidgetsApp
 			.id( WidgetId( "widgets/note" ) )
 			.on_change( Msg::NoteChanged );
 
+		// One page per tab, so selecting a tab visibly swaps the content.
+		let page: Element<Msg> = match self.tab.min( 2 )
+		{
+			0 => column::<Msg>()
+				.padding( 0.0 )
+				.spacing( 12.0 )
+				.push( toggles )
+				.push( separator() )
+				.push( checkboxes )
+				.push( separator() )
+				.push( radios )
+				.into(),
+			1 => column::<Msg>()
+				.padding( 0.0 )
+				.spacing( 12.0 )
+				.push( text( vol_label ).size( 13.0 ).color( secondary ) )
+				.push( slider( self.volume ).on_change( Msg::SliderChanged ) )
+				.push( text( prog_label ).size( 13.0 ).color( secondary ) )
+				.push( progress_bar( self.progress ) )
+				.into(),
+			_ => column::<Msg>()
+				.padding( 0.0 )
+				.spacing( 12.0 )
+				.push( text( "Spinner" ).size( 13.0 ).color( secondary ) )
+				.push( spin_row )
+				.push( separator() )
+				.push( text( "Multiline text edit" ).size( 13.0 ).color( secondary ) )
+				.push( textarea )
+				.into(),
+		};
+
 		let content = column::<Msg>()
 			.padding( 32.0 )
 			.spacing( 12.0 )
 			.push( title )
 			.push( tabs_strip )
-			.push( text( tab_label ).size( 13.0 ).color( secondary ) )
 			.push( separator() )
-			.push( toggles )
-			.push( separator() )
-			.push( checkboxes )
-			.push( separator() )
-			.push( radios )
-			.push( separator() )
-			.push( text( vol_label ).size( 13.0 ).color( secondary ) )
-			.push( slider( self.volume ).on_change( Msg::SliderChanged ) )
-			.push( text( prog_label ).size( 13.0 ).color( secondary ) )
-			.push( progress_bar( self.progress ) )
-			.push( separator() )
-			.push( text( "Spinner" ).size( 13.0 ).color( secondary ) )
-			.push( spin_row )
-			.push( separator() )
-			.push( text( "Multiline text edit" ).size( 13.0 ).color( secondary ) )
-			.push( textarea )
+			.push( page )
 			.push( spacer() )
 			.push(
 				text( "Esc = quit" )