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.

CONTRIBUTING.md

@@ -37,20 +37,29 @@ sudo apt-get install \
 git clone <repo>
 cd ltk
 cargo build
-cargo test
+cargo test --features test-support
 ```
 
+Tests require the `test-support` feature: the `test_support` module is
+feature-gated in `src/lib.rs`, and the code under `tests/` and
+`benches/` imports it, so a bare `cargo test` fails to compile.
+
 The `Makefile` wraps the common targets:
 
 ```bash
 make all          # cargo build --release
-make test         # cargo test
+make test         # cargo test --features test-support
+make doctest-md   # typecheck the Rust snippets in docs/*.md
 make audit        # cargo audit (installs cargo-audit on first run)
 make doc          # cargo doc --no-deps
-make example      # run every example under examples/ in turn
-make clean
+make examples     # run every example under examples/ in turn
+make clean        # runs dh_clean, so it needs debhelper installed
 ```
 
+Run `make doctest-md` after editing any file under `docs/` — it feeds
+each markdown file to `rustdoc --test` to catch API drift in the
+snippets.
+
 Running the examples requires a Wayland session and the default theme
 on disk:
 
@@ -83,7 +92,7 @@ Match the surrounding code when in doubt.
 
 - Keep changes focused: one logical change per pull request. A bug fix
   and a refactor go in separate PRs.
-- Add tests. The repository has ~400 tests covering the existing
+- Add tests. The repository has ~680 tests covering the existing
   surface, and a contribution that adds behaviour without test
   coverage will get review pushback. See [`tests/`](tests/) for
   examples of integration tests via `UiSurface`, and the inline
@@ -96,20 +105,23 @@ Match the surrounding code when in doubt.
   crate hits `1.0`, breaking changes go in minor versions
   (`0.x.0 → 0.(x+1).0`); patch versions (`0.x.y → 0.x.(y+1)`) keep
   source compatibility.
-- Run `cargo test` and `make audit` before sending. CI will run them
+- Give user-visible changes a `CHANGELOG.md` entry under
+  `[Unreleased]`.
+- Run `cargo test --features test-support` and `make audit` before
+  sending. CI will run them
   again, but it is faster for both of us if your local run is clean.
 
 ## Architectural decisions worth knowing
 
 A few patterns recur across the codebase:
 
-- **Builder methods consume `self`** (`pub fn padding( mut self, p: f32 ) -> Self`).
+- **Builder methods consume `self`** (`pub fn padding( mut self, p: impl Into<Length> ) -> Self`).
   Chaining works because every builder returns `Self`. Don't introduce
   setters that take `&mut self`.
 - **Layouts and widgets share `Element<Msg>`.** Anything that converts
   to `Element` can be pushed into any layout. The split between
-  [`crate::layout`] and [`crate::widget`] is documentation, not
-  architecture.
+  [`src/layout/`](src/layout/) and [`src/widget/`](src/widget/) is
+  documentation, not architecture.
 - **The runtime is single-threaded.** Use `RefCell` for caches inside
   `App` state, never `Mutex`. Cross-thread communication goes through
   [`ChannelSender`](src/app.rs).
@@ -119,7 +131,7 @@ A few patterns recur across the codebase:
 - **Theming is process-global.** There is no per-app theme; the active
   document and mode live in a `RwLock<Arc<…>>`. `view()` reads the
   state, never writes it. Mode flips and document swaps go through
-  [`crate::set_active_mode`] and [`crate::set_active_document`].
+  `ltk::set_active_mode` and `ltk::set_active_document`.
 - **Per-frame allocations are fine.** Building the `Element` tree on
   every render is the supported model. Don't try to retain widgets
   across frames.