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.

README.md

@@ -87,6 +87,8 @@ Add `ltk` to your `Cargo.toml`:
 ltk = { path = "../ltk" }
 ```
 
+If you consume `ltk` from outside this workspace, replace the `path` dependency with a versioned one.
+
 Minimal app:
 
 ```rust
@@ -183,6 +185,8 @@ Useful entry points in this repository:
 - `cargo run --example dialog`
 - `cargo run --example sliders`
 - `cargo run --example pickers`
+- `cargo run --example carousel`
+- `cargo run --example clip_path`
 - `cargo run --example mini_shell`
 
 In general:
@@ -199,7 +203,7 @@ Most applications should start with this subset:
 
 - `App`
 - `Element<Msg>`
-- widgets such as `button`, `text`, `text_edit`, `image`
+- widgets such as `button`, `text`, `text_edit`, `img_widget`
 - layouts such as `column`, `row`, `stack`, `grid`, `spacer`
 - `Color`
 - `run`
@@ -265,9 +269,11 @@ The main rules for downstream applications are:
 - keep `view()` pure and cheap
 - do not perform I/O inside `view()`
 - use `poll_interval()` sparingly
-- return `true` from `is_animating()` only while something is actually moving
+- return `true` from `is_animating()` only while something is actually moving — note that on the software backend animation redraws are capped at ~30 Hz by default (override with `App::cap_software_animation`)
 - cache decoded images and expensive derived state in your app
 
+Set `LTK_PERF_WARN=1` during development for opt-in diagnostics: it warns about stuck animations, sustained software-render animation, and low `poll_interval` values.
+
 The library already provides:
 
 - event-driven redraw scheduling
@@ -279,8 +285,11 @@ The library already provides:
 
 The public API is the same across backends, but visual parity is not perfect
 yet. The widget tree, layout, hit-testing, text, images, fills, strokes and
-clipping all paint identically on both paths. The gaps are in gradients and the
-shadow / backdrop pipeline.
+single-rect / path clipping all paint identically on both paths. The gaps are in
+gradients, the shadow / backdrop pipeline, and multi-rect clipping: the GLES
+backend installs the bounding-box union of the rects as its `glScissor` — a
+coarse clip that does not cull pixels between disjoint rects — while the
+software backend clips each rect exactly.
 
 Effects that currently render only on the **GLES** backend, and degrade on the
 **Software** backend:
@@ -311,7 +320,7 @@ LTK_FORCE_SOFTWARE=1 cargo run --example showcase
 ```
 
 Closing this gap (porting the shadow / inset-shadow pipeline to tiny-skia) is
-on the post-v0.1 roadmap.
+on the roadmap.
 
 ## Documentation
 
@@ -323,6 +332,8 @@ on the post-v0.1 roadmap.
 | [`docs/theming.md`](docs/theming.md) | JSON theme schema, slot conventions, runtime APIs. |
 | [`docs/cookbook.md`](docs/cookbook.md) | Concrete recipes — slide-in panels, password fields, runtime theme toggle, channel-driven state, embedding without `ltk::run`. |
 | `cargo doc --open` | Per-item rustdoc for the public API. |
+| [`CHANGELOG.md`](CHANGELOG.md) | What changed in each release, and what is pending unreleased. |
+| [`code_style_guide.md`](code_style_guide.md) | The Modified Allman style rules the codebase follows. |
 | [`SECURITY.md`](SECURITY.md) | How to report a vulnerability and what is in / out of scope. |
 | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Build, test, code style, patch shape. |