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.

docs/widgets.md

@@ -139,8 +139,8 @@ let bar = window_controls(
 `focusable( true )` opts the button into the Tab cycle (off by default
 to match desktop convention).
 
-**See also**: [`crate::theme_window_controls`] for the colour tokens
-each mode supplies.
+**See also**: `theme_window_controls` for the colour tokens each mode
+supplies.
 
 ### `list_item`
 
@@ -148,8 +148,7 @@ A row with a primary label, optional subtitle, optional leading icon,
 optional right-aligned trailing text and/or trailing icon, and a
 tappable surface.
 
-**When**: settings menus, navigation lists, contact rows. Doubles its
-height when a subtitle is set.
+**When**: settings menus, navigation lists, contact rows. Grows taller when a subtitle is set.
 
 ```rust,no_run
 # use ltk::{ list_item, ListItem };
@@ -343,11 +342,11 @@ let hint     = text( "Swipe up or press Enter to unlock" )
 
 ### `text_edit`
 
-A single-line text input with cursor, Backspace, Enter / Submit,
-clipboard support, a `secure( true )` password mode that masks the
-visible characters and zeroizes the buffer on drop, and a
+A text input with cursor, Backspace, Enter / Submit, clipboard
+support, a `secure( true )` password mode that masks the visible
+characters and zeroizes the buffer on drop, and a
 `password_toggle( visible, on_toggle )` builder that pins a show /
-hide-password eye icon to the right edge of the field.
+hide-password eye icon to the right edge of the field. Single-line by default; `multiline( true )` switches to a multi-row editor whose visible height follows `rows( n )`.
 
 **When**: login fields, chat inputs, search boxes.
 
@@ -437,14 +436,12 @@ container( column().push( title ).push( subtitle ) )
 ```
 
 Per-edge padding is available with `padding_top` / `padding_right` /
-`padding_bottom` / `padding_left`. Per-corner radius takes a [`Corners`]
+`padding_bottom` / `padding_left`. Per-corner radius takes a `Corners`
 struct or a tuple.
 
 `max_width(px)` caps the container's outer width — when the parent
 offers a wider rect, the container reports `min( offered, px )` as its
-preferred width instead of stretching to fill. Mirrors the same flag on
-[`column`](#column) and [`row`](#row), so a single decorated child no
-longer needs a `column`-of-one wrap just to access a width cap.
+preferred width instead of stretching to fill. Note the semantics differ from [`column`](#column)'s `max_width`, which caps the *content* width while the column still claims the full available rect ([`row`](#row) has no such flag); the container cap shrinks the widget itself, so a single decorated child gets a real width cap without extra wrapping.
 
 **See also**: [`pressable`](#pressable) wrapping a `container` makes a
 card interactive.
@@ -535,8 +532,7 @@ External::cpu( 120.0, 120.0, |canvas, rect|
 
 ### `scroll`
 
-A vertically-scrollable viewport. Drag the content to scroll; clipping
-is automatic.
+A scrollable viewport — vertical by default, with `.horizontal()` and `.both()` builders switching the axis (`ScrollAxis::{ Vertical, Horizontal, Both }`). Drag the content to scroll; clipping is automatic.
 
 **When**: lists or grids that may overflow the available height.
 
@@ -662,33 +658,41 @@ of arbitrary content; [`tabs`](#tabs) for a non-touch alternative.
 
 ### `spinner`
 
-Indeterminate progress indicator. Animates while in the tree.
+Indeterminate progress indicator. The widget is stateless: the application owns the rotation phase and advances it each frame — any monotonically increasing value works, only the fractional part is used. Pair with `App::is_animating` so the run loop keeps requesting redraws while the spinner is on screen.
 
 **When**: long-running operations with no known fraction
 (network calls, indexing, "waiting for compositor").
 
 ```rust,no_run
 # use ltk::{ spinner, Spinner };
-# fn _ex() -> Spinner {
-spinner().size( 24.0 )
-# }
+# struct App { spinner_phase: f32 }
+# impl App { fn _ex( &self ) -> Spinner {
+spinner().phase( self.spinner_phase ).size( 24.0 )
+# }}
 ```
 
 **See also**: [`progress_bar`](#progress_bar) for determinate progress.
 
 ### `toast`
 
-Transient notification that floats over the surface and dismisses
-itself after a timeout.
+Transient notification pill anchored near the bottom of the surface. Not an `Element` — build it in `App::overlays` and return its `.overlay()` while a toast is pending. Auto-dismissal is the application's responsibility: `duration( secs )` only stores a value read back via `duration_value()`, so the app schedules its own "toast expired" timer and clears the state when it fires.
 
 **When**: confirmation snackbars ("Saved"), non-blocking errors,
 status flashes.
 
 ```rust,no_run
-# use ltk::{ toast, Toast };
+# use ltk::{ toast, OverlaySpec };
 # #[ derive( Clone ) ] enum Msg {}
-# fn _ex() -> Toast<Msg> {
-toast( "Saved" ).duration( 3.0 )
+# struct App { toast_message: Option<String> }
+# impl App {
+fn overlays( &self ) -> Vec<OverlaySpec<Msg>>
+{
+	match &self.toast_message
+	{
+		Some( m ) => vec![ toast( m ).duration( 3.0 ).overlay() ],
+		None      => vec![],
+	}
+}
 # }
 ```
 
@@ -696,7 +700,7 @@ toast( "Saved" ).duration( 3.0 )
 
 ### `tooltip`
 
-Anchored hint that appears next to a target widget on hover or focus.
+Anchored hint rendered below a target widget. Like [`toast`](#toast) it is not an `Element` — return its `.overlay()` from `App::overlays` while the hint should be visible. Hover detection and the show / hide delay are the application's responsibility; the automatic variant is `Button::tooltip( text )`, which shows the hint by itself after a pointer dwell on the button.
 
 **When**: discoverable affordances on icon-only controls, keyboard
 shortcut reminders, helper text that should not occupy permanent
@@ -710,8 +714,8 @@ tooltip( "Ctrl+S", WidgetId( "btn/save" ) ).max_width( 240 )
 # }
 ```
 
-The widget paints next to the widget that registered the matching
-`WidgetId`. See [`docs/cookbook.md`](./cookbook.md) for the full
+The overlay anchors below the widget built with the matching
+`.id( WidgetId )`. See [`docs/cookbook.md`](./cookbook.md) for the full
 overlay wiring.
 
 **See also**: [`toast`](#toast) for transient self-dismissing
@@ -719,26 +723,39 @@ notifications.
 
 ### `combo`
 
-Editable single-select with a popup list. Supports type-to-filter
-and free-text entry.
+Select / dropdown with a popup list — single- or multi-select (`multi_select( true )` adds selection chips), with optional type-to-filter (`searchable( true )`). The widget is a stateless projection over an app-owned `ComboState`, and the app places **two** pieces: the trigger (`Combo::trigger()`) goes in the view tree like any widget, and the open popup is either layered into the same surface via `Combo::popup()` inside a [`stack`](#stack), or returned as a real xdg-popup from `App::overlays` via `Combo::overlay()`.
 
-**When**: pick-one fields with too many options for a row of
-[`radio`](#radio) buttons but where a free typed answer is also
-valid (autocomplete, country list, theme picker).
+**When**: pick-one (or pick-several) fields with too many options for
+a row of [`radio`](#radio) buttons (autocomplete, country list, theme
+picker).
 
 ```rust,no_run
-# use ltk::{ combo, Combo, ComboState };
-# #[ derive( Clone ) ] enum Msg { Pick( usize ) }
-# fn _ex( state: ComboState ) -> Combo<Msg> {
-let items = vec![
-    "One".to_string(),
-    "Two".to_string(),
-    "Three".to_string(),
-];
-combo( state, items ).on_select_idx( Msg::Pick )
+# use ltk::{ column, combo, Combo, ComboState, Element, OverlaySpec };
+# #[ derive( Clone ) ] enum Msg { Pick( usize ), ToggleOpen, Dismiss }
+# struct App { fruits: ComboState }
+# impl App {
+# fn build_combo( &self ) -> Combo<Msg> {
+# let items = vec![ "One".to_string(), "Two".to_string(), "Three".to_string() ];
+combo( self.fruits.clone(), items )
+	.on_toggle_open( Msg::ToggleOpen )
+	.on_select_idx( Msg::Pick )
+	.on_dismiss( Msg::Dismiss )
+# }
+fn view( &self ) -> Element<Msg>
+{
+	column().push( self.build_combo().trigger() ).into()
+}
+
+fn overlays( &self ) -> Vec<OverlaySpec<Msg>>
+{
+	self.build_combo().overlay().into_iter().collect()
+}
 # }
 ```
 
+`update()` then flips `is_open` on `ToggleOpen` / `Dismiss` and writes
+the selection into the `ComboState` on `Pick`.
+
 **See also**: [`radio`](#radio) for small mutually-exclusive sets,
 [`notebook`](#notebook) for tabbed mode switches.
 
@@ -812,10 +829,12 @@ dialog()
 
 `modal( false ) + dismiss_on_scrim( msg )` makes a tap on the dim
 background fire `msg`; combining `dismiss_on_scrim` with `modal( true )`
-panics at lower time (the contracts contradict). `body( elem )`
+panics when the dialog is converted to an `Element` — the `.into()` asserts with "dialog: dismiss_on_scrim is not valid when modal=true", since the two contracts contradict. `body( elem )`
 swaps a custom element in between the subtitle and the action row —
 the example app at `examples/dialog.rs` uses this for an in-dialog
-slider.
+slider. `max_width( … )` caps the card width; it accepts any `Length`
+and defaults to `Length::fluid( 480.0 )` so the card scales with the
+same curve as the stock buttons inside it.
 
 **See also**: [`toast`](#toast) for non-blocking transient
 notifications, [`combo`](#combo) for a single-pick popup that does
@@ -895,9 +914,15 @@ the natural content width to the parent (otherwise the column claims
 the full available width). `center_y( true )` centres the content
 block vertically when there are no spacers.
 
+Watch the defaults: `column()` starts with **16 px padding** on every
+side (and 8 px spacing). A column nested inside an already-padded
+container silently doubles the inset — pass `.padding( 0.0 )` when the
+parent owns the margin.
+
 ### `row`
 
-Horizontal flow. Mirror of [`column`](#column) on the X axis.
+Horizontal flow. Mirror of [`column`](#column) on the X axis — except
+its default padding is `0`, not `column`'s 16 px.
 
 ```rust,no_run
 # use ltk::{ flex, row, Element };