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`.

docs/architecture.md

@@ -151,6 +151,19 @@ For many third-party apps, theming is optional at first. It is reasonable to
 start with the default theme and come back to the runtime theme APIs later as
 part of the `ltk::runtime` layer.
 
+## Responsive sizing
+
+Every size in a widget tree is a `Length`, resolved to concrete pixels at layout time against the surface. Two coordinate spaces matter. **Geometry** (widths, heights, paddings, gaps, box sizes) is computed in *physical* pixels — the layout root rect is `pw × ph` — so geometry `Length` values resolve against `Canvas::viewport_layout()` (physical). **Font sizes** are the exception: they resolve against `Canvas::viewport_logical()` (physical ÷ `dpi_scale`) and are multiplied by `dpi_scale` again at raster time, so a `vmin` font ends up as a fraction of the *physical* short side regardless of `dpi_scale`. Keep this split in mind when adding a widget: resolve a geometry constant with `Canvas::geom_px(n)` and a font constant with `Canvas::font_px(n)` — the two helpers hide the difference.
+
+`ltk` offers two adaptation strategies, and both live in the same `Length` type so an app can mix them per value:
+
+- **Fluid** (`Length::fluid(n)`, and the raw `vmin` / `vmax` / `vw` / `vh` / `orient` units): surface-proportional. `fluid(n)` reads a single design pixel `n` as `vmin(n / fluid_reference() * 100).clamp(n * FLUID_MIN, n * FLUID_MAX)` — at a surface whose short side equals the reference (412 px by default) it is exactly `n`, and it scales with the short side elsewhere, auto-clamped to `[0.7n, 1.5n]`. This tracks the width in portrait and the height in landscape, because the short side *is* the width in portrait and the height in landscape. `orient(portrait, landscape)` is the escape hatch for a different percentage per orientation.
+- **Physical** (`Length::dp(n)`): constant physical size. `dp(n)` is `n × density()`, where `density()` is a process-wide factor (default `1.0`, typically set from the output DPI via `set_density`). It does not scale with the surface, only with pixel density — the mainstream HiDPI `dp`.
+
+Stock widgets do not hard-code either strategy. Each carries a design pixel per dimension (e.g. `button` height 48, font 16) and resolves it through the process-wide `WidgetScaling` mode: `Length::widget(n)` returns `fluid(n)` under `WidgetScaling::Fluid` (the default) or `dp(n)` under `WidgetScaling::Physical`. `set_widget_scaling(mode)` flips it once for the whole app. An explicit `Length` on an individual widget (`button.height(...)`, `text_edit.height(...)`, `font_size(...)`) bypasses the mode entirely — the mode only decides the meaning of the *default* design pixels, never an override the app wrote on purpose.
+
+Both `density()` and `widget_scaling()` are process globals read during layout; set them at startup (or, for density, whenever the surface moves to an output with a different DPI). Because they are global, ltk's own test suite serialises the tests that touch them.
+
 ## Animations
 
 The render loop is event-driven by default: it sleeps until input arrives, a `poll_interval` ticks, or `set_channel_sender` is woken from a thread. To run a tween, override `is_animating()`:
@@ -228,10 +241,12 @@ The cheap things and the expensive things, in rough order:
 - *Avoid `is_animating() = true` when nothing is moving.* It pegs the loop at 60 Hz and burns battery on the mobile target.
 - *Lower `poll_interval()` is not free.* Crustace polls every 30 s because the clock only shows HH:MM. If your UI shows seconds, `Some(Duration::from_secs(1))` is fine; if it shows nothing time-sensitive, leave it `None`.
 - *Scroll viewports own a sub-canvas.* They're slightly more expensive to draw than a plain column. Use them when you need clipping or actual scrolling, not as a wrapper.
-- *GPU vs software*: the GLES path is selected automatically when EGL is available; both render the same pixels (see the recent commits for the alpha/SDF parity work). There is no API-level difference for the application.
+- *GPU vs software*: the GLES path is selected automatically when EGL is available, with no API-level difference for the application. The two backends are not yet pixel-identical — gradients and the shadow / backdrop pipeline degrade under software; the authoritative list of gaps is the README's *Backend Differences* section.
 
 When a redraw feels sluggish: add a one-line print at the top of `view()` and confirm it's not being called more often than expected. The single most common mistake is leaving `is_animating()` returning `true` after the animation finished.
 
+**Runtime guardrails.** The rules above are the app's responsibility, but the runtime also helps catch and blunt the common footguns. Set `LTK_PERF_WARN=1` to get one-shot stderr diagnostics during development when `is_animating()` stays true for 10 s (a settled animation that forgot to return `false`), when `poll_interval()` is under 100 ms (defeats the idle model), or when the software backend animates continuously for seconds (mobile CPU sink). Independently, animation on the **software** renderer is capped to ~30 Hz by default — GLES is never capped — since 60 fps software rasterization is a battery drain with no GPU offload; override [`App::cap_software_animation`] to keep the full rate. These live in `event_loop/perf.rs`.
+
 ## Where to look in the consumer repos
 
 | Pattern | File |

docs/cookbook.md

@@ -13,6 +13,7 @@ reference, see [`docs/widgets.md`](./widgets.md). For theme JSON, see
 
 ## Table of contents
 
+- [Responsive sizing across mobile / tablet / desktop](#responsive-sizing-across-mobile--tablet--desktop)
 - [Slide-in panel](#slide-in-panel)
 - [Password field with PAM submit](#password-field-with-pam-submit)
 - [Swipe-to-dismiss overlay](#swipe-to-dismiss-overlay)
@@ -28,6 +29,45 @@ reference, see [`docs/widgets.md`](./widgets.md). For theme JSON, see
 
 ---
 
+## Responsive sizing across mobile / tablet / desktop
+
+Size everything as a fraction of the surface so one view reads
+coherently from a portrait phone to a landscape desktop window,
+without per-target forks. The rule is *fluid but clamped*: a `vmin`
+percentage tracks the surface's smaller side, and a px `clamp` keeps
+it from collapsing on a tiny screen or ballooning on a 4K monitor.
+Use `Length::orient( portrait, landscape )` when the *proportion*
+itself should differ between orientations, and `Image::short_side` to
+size a logo along the screen's short side while preserving its aspect
+ratio.
+
+```rust,no_run
+# use std::sync::Arc;
+# use ltk::{ column, img_widget, text, Length, Element };
+# #[ derive( Clone ) ] enum Msg {}
+# fn _ex( logo: Arc<Vec<u8>>, lw: u32, lh: u32 ) -> Element<Msg> {
+column::<Msg>()
+    .padding( Length::vmin( 4.0 ).clamp( 16.0, 48.0 ) )
+    .spacing( Length::vmin( 2.0 ).clamp( 8.0, 24.0 ) )
+    // Logo: 40 % of the width in portrait, 5 % of the height in landscape.
+    .push( img_widget( logo, lw, lh ).short_side( Length::orient( 40.0, 5.0 ) ) )
+    // Heading: fluid, but never below 20 px nor above 44 px.
+    .push( text( "Welcome" ).size( Length::vmin( 6.0 ).clamp( 20.0, 44.0 ) ) )
+    .into()
+# }
+```
+
+Fluid units scale with the screen's pixels, not real-world
+millimetres. For body text that must stay physically legible and
+honour the user's font-size preference across an open-ended device
+set, prefer `Length::dp` or `Length::em` over raw `vmin`; the
+[`typography`](../src/theme/typography.rs) scale (`h0`…`body_xs`)
+gives clamped-`vmin` sizes tuned for running text. Reserve
+`view()`-level branching on `surface_width` / `surface_height` for
+genuine layout restructuring (sidebar → bottom tabs), not for sizing.
+
+---
+
 ## Slide-in panel
 
 A quick-settings or notification panel that slides down from the top of
@@ -36,7 +76,7 @@ edge does not knife-cut against the layer below.
 
 ```rust,no_run
 # use std::time::Instant;
-# use ltk::{ container, text, viewport, Anchor, Element, Layer, OverlayId, OverlaySpec };
+# use ltk::{ container, text, viewport, Anchor, Element, Layer, Length, OverlayId, OverlaySpec };
 # const OVERLAY_QS: OverlayId = OverlayId( 1 );
 # const SLIDE_DURATION: f32 = 0.25;
 # #[ derive( Clone ) ] enum Msg { CloseQs }
@@ -71,7 +111,7 @@ fn build_quick_settings_overlay( &self ) -> OverlaySpec<Msg>
         id:                 OVERLAY_QS,
         layer:              Layer::Overlay,
         anchor:             Anchor::TOP,
-        size:               ( self.surface_width, visible_h as u32 ),
+        size:               ( Length::px( self.surface_width as f32 ), Length::px( visible_h ) ),
         exclusive_zone:     0,
         keyboard_exclusive: false,
         input_region:       None,
@@ -211,7 +251,7 @@ A modal panel that closes when the user swipes down past a threshold or
 taps outside the panel.
 
 ```rust,no_run
-# use ltk::{ column, container, spacer, text, Anchor, Element, Layer, OverlayId, OverlaySpec };
+# use ltk::{ column, container, spacer, text, Anchor, Element, Layer, Length, OverlayId, OverlaySpec };
 # const OVERLAY_MODAL: OverlayId = OverlayId( 2 );
 # #[ derive( Clone ) ] enum Msg { CloseModal }
 # struct App { modal_open: bool, modal_drag_progress: f32 }
@@ -239,7 +279,7 @@ fn overlays( &self ) -> Vec<OverlaySpec<Msg>>
             id:                 OVERLAY_MODAL,
             layer:              Layer::Overlay,
             anchor:             Anchor::ALL,
-            size:               ( 0, 0 ),
+            size:               ( Length::px( 0.0 ), Length::px( 0.0 ) ),
             exclusive_zone:     0,
             keyboard_exclusive: false,
             input_region:       None,                   // accept input
@@ -488,7 +528,7 @@ blocking other UI.
 
 ```rust,no_run
 # use std::time::Instant;
-# use ltk::{ container, text, App, Anchor, Color, Element, Layer, OverlayId, OverlaySpec };
+# use ltk::{ container, text, App, Anchor, Color, Element, Layer, Length, OverlayId, OverlaySpec };
 # const OVERLAY_TOAST: OverlayId = OverlayId( 3 );
 # #[ derive( Clone ) ] enum Msg {}
 struct AppState
@@ -539,7 +579,7 @@ impl App for AppState
                 id:                 OVERLAY_TOAST,
                 layer:              Layer::Overlay,
                 anchor:             Anchor::BOTTOM,
-                size:               ( 0, 0 ),
+                size:               ( Length::px( 0.0 ), Length::px( 0.0 ) ),
                 exclusive_zone:     0,
                 keyboard_exclusive: false,
                 input_region:       Some( vec![] ),                 // pass-through

docs/onboarding.md

@@ -322,6 +322,28 @@ enum AppMsg
 
 This is the pattern used by `examples/mini_shell.rs`.
 
+## Responsive sizing: fluid vs physical
+
+`ltk` gives you two ways to make an interface adapt to the display, and you can
+mix them per value. **Fluid** sizes are a fraction of the surface (best for
+full-screen system surfaces); **physical** sizes stay a constant real-world
+size (best for conventional windowed apps). In practice you write a size as a
+`Length` and bound it with `.clamp`:
+
+```rust
+use ltk::{ text, Length };
+
+// Fluid: 6 % of the surface's short side, never below 20 px nor above 44 px.
+text("Welcome").size(Length::vmin(6.0).clamp(20.0, 44.0));
+```
+
+Stock widgets follow a process-wide mode (`set_widget_scaling`, fluid by
+default); an explicit `Length` on a widget overrides it. For the units
+(`vmin` / `orient` / `dp` / …), the clamp discipline and how it all resolves,
+see the *Responsive sizing* section of
+[`architecture.md`](architecture.md#responsive-sizing) and the `Length`
+rustdoc.
+
 ## Recommended learning order
 
 If you are new to the library, this order minimizes confusion: