responsive fluid/physical scaling, widget-API stabilization, and perf guardrails

Responsive scaling. ltk now offers two first-class ways to size a UI so it adapts across screens, chosen per process via `WidgetScaling { Fluid, Physical }` (`set_widget_scaling` / `widget_scaling`, default `Fluid`). Fluid sizing (`Length::fluid( px )`) makes a design pixel a proportion of the surface's smaller side, calibrated against a reference width (`set_fluid_reference` / `fluid_reference`, 412 px default) and bounded by `FLUID_MIN` / `FLUID_MAX`; physical sizing (`Length::dp( px )`) is a constant-physical-size pixel scaled by display density (`set_density` / `density`). `Length` gains `orient( portrait, landscape )` — resolve one value in portrait, another in landscape — plus `widget( px )`, which picks fluid or dp per the active mode. Canvas exposes `geom_px` (geometry, resolved in physical layout space) and `font_px` (font size, bridging logical / physical per mode) so widgets and apps share one resolution path. Note the rename: `set_design_reference` / `design_reference` became `set_fluid_reference` / `fluid_reference`, and `Length::dp` changed meaning — the old surface-proportional behaviour now lives on `Length::fluid`.
Widgets. Every stock widget resolves its default geometry and font through the widget-scaling mode instead of frozen pixels, so a whole UI scales coherently without per-call units. New size builders where they were missing: `button` gains `font_size` / `height`, `text_edit` gains `height` / `font_size_fluid`, `separator` gains `pad_v`, and assorted widgets accept a `Length` where they previously took only `f32`.
Overlays. `OverlaySpec::size` is now `( Length, Length )` instead of `( u32, u32 )`, resolved against the main surface when the overlay is materialized, so overlays can scale with the display; `Length::px( … )` reproduces the old fixed sizing.
API stabilization (toward 1.0). Widget struct fields are now `pub( crate )` — they are configured through builders, not field access — except the value / state types apps genuinely read or construct (`Time`, `Date`, `ComboState`), which stay public. The internal `test_support` helpers move behind a `test-support` Cargo feature (off by default, so third-party builds never see them; ltk's own `make test` enables it). `Separator` drops its `0.0`-means-mode sentinel for `Option<Length>`, so an explicit `pad_v( 0.0 )` is a real flush divider distinct from the mode-following default.
Performance guardrails. Opt-in diagnostics via `LTK_PERF_WARN=1` warn about stuck animations, sustained software-render animation, and low `poll_interval`; software-rendered animation is capped near 30 Hz to spare CPU on machines that fall back off EGL. Apps can override the cap with `App::cap_software_animation`.
Docs and build. The two scaling modes are documented in README, onboarding and architecture, with the earlier gradient / backdrop doc drift cleaned up. The Makefile now ships the `locales/` directory into the packaged crate (fixing i18n keys rendering raw for downstreams), builds the new `responsive` example, and runs tests with `--features test-support`.

README.md

@@ -175,6 +175,7 @@ cargo run --example showcase
 Useful entry points in this repository:
 
 - `cargo run --example showcase`
+- `cargo run --example responsive`
 - `cargo run --example widgets`
 - `cargo run --example inputs`
 - `cargo run --example scroll`
@@ -187,6 +188,7 @@ Useful entry points in this repository:
 In general:
 
 - start with `showcase` for a regular app window
+- use `responsive` to see the fluid vs physical modes on stock widgets
 - use `widgets` to see the core controls
 - use `mini_shell` if you need overlays, theme switching, or shell-style
   composition
@@ -211,6 +213,25 @@ More advanced APIs are available when needed:
 - `core::UiSurface`
 - runtime theme APIs
 
+## Responsive Design
+
+`ltk` offers **two** first-class ways to make an interface adapt to the
+display, chosen per value or per process:
+
+- **Fluid** — sizes are a fraction of the surface, tracking the short side
+  (width in portrait, height in landscape). Best for full-screen system
+  surfaces. Written with `Length::vmin` / `orient` / `fluid` and bounded with
+  `.clamp`.
+- **Physical** — sizes stay a constant real-world size across displays (the
+  mainstream HiDPI `dp` model). Best for conventional windowed apps. Written
+  with `Length::dp` plus `set_density`.
+
+Stock widgets follow the process-wide mode (`set_widget_scaling`, fluid by
+default); an explicit `Length` on a widget always overrides it. The full
+mechanics live in [`docs/architecture.md`](docs/architecture.md#responsive-sizing),
+a walkthrough in [`docs/onboarding.md`](docs/onboarding.md), and the per-item
+reference in the `Length` / `WidgetScaling` rustdoc.
+
 ## Windows and Shell Surfaces
 
 By default, `ltk` creates a regular `xdg-shell` window.
@@ -257,13 +278,17 @@ The library already provides:
 ## Backend Differences
 
 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,
-clipping and gradients all paint identically on both paths. The gap is in the
+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.
 
-Effects that currently render only on the **GLES** backend, and are silent
-no-ops on the **Software** backend:
+Effects that currently render only on the **GLES** backend, and degrade on the
+**Software** backend:
 
+- **Gradients** (linear and radial, via `Canvas::fill_paint_rect`) — rendered with
+  dedicated shaders on GLES; on software they collapse to a flat fill from the
+  first stop (tiny-skia can render gradients natively, but that is not wired up
+  yet).
 - **Outer drop shadows** (`Canvas::fill_shadow_outer`) — themed surfaces that
   declare a `Shadow` slot show the soft halo on GLES and a flat fill on
   software.