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/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()
 	}