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

src/widget/button/mod.rs

@@ -2,7 +2,7 @@
 // Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>
 
 use std::sync::Arc;
-use crate::types::{ Color, Rect, WidgetId };
+use crate::types::{ Color, Length, Rect, WidgetId };
 use crate::render::Canvas;
 use super::Element;
 
@@ -47,34 +47,45 @@ pub enum ButtonContent
 pub struct Button<Msg: Clone>
 {
 	/// The visual content of this button.
-	pub content:   ButtonContent,
+	pub( crate ) content:   ButtonContent,
 	/// Message emitted when the button is pressed, or `None` if disabled.
-	pub on_press:  Option<Msg>,
+	pub( crate ) on_press:  Option<Msg>,
 	/// Message emitted when the user holds the button for
 	/// [`App::long_press_duration`](crate::app::App::long_press_duration)
 	/// without moving past the tolerance, OR when the user right-clicks
 	/// with the mouse. `None` leaves the button without a context-menu
 	/// equivalent. The fire does NOT by itself put the gesture into
 	/// drag mode — that is governed by [`Self::on_drag_start`].
-	pub on_long_press: Option<Msg>,
+	pub( crate ) on_long_press: Option<Msg>,
 	/// Drag-arm message. Fires when the press transitions into a drag:
 	/// touch on hold-timer expiry (in addition to `on_long_press`),
 	/// mouse on motion past the drag-promotion threshold (without
 	/// firing the menu). Independent of `on_long_press` so a button
 	/// can open a menu without becoming draggable, or be draggable
 	/// without showing a menu.
-	pub on_drag_start: Option<Msg>,
+	pub( crate ) on_drag_start: Option<Msg>,
 	/// Visual variant controlling colors and borders.
-	pub variant:   ButtonVariant,
-	/// Width and height in pixels for icon buttons. Defaults to `48.0`.
-	pub icon_size: f32,
+	pub( crate ) variant:   ButtonVariant,
+	/// Width and height in pixels for icon buttons. The `0.0` default
+	/// follows the process [`crate::WidgetScaling`] mode (via
+	/// [`crate::Canvas::geom_px`]); any positive value pins an explicit size.
+	pub( crate ) icon_size: f32,
+	/// Optional label font size for text buttons. `None` uses the theme's
+	/// default (`theme::FONT_SIZE`); a [`Length`] scales the label with the
+	/// surface (e.g. `Length::vmin( 2.2 ).clamp( 14.0, 22.0 )`).
+	pub( crate ) font_size: Option<Length>,
+	/// Optional height for text buttons. `None` uses the theme's default
+	/// (`theme::HEIGHT`); a [`Length`] scales the button box with the
+	/// surface so it does not stay frozen while the rest of a fluid layout
+	/// grows. Resolved in physical layout space, like all geometry.
+	pub( crate ) height:    Option<Length>,
 	/// Optional stable identifier for focus management.
-	pub id:        Option<WidgetId>,
+	pub( crate ) id:        Option<WidgetId>,
 	/// Whether this button participates in keyboard focus (Tab). Default: `true`.
-	pub focusable: bool,
+	pub( crate ) focusable: bool,
 	/// Override the pointer cursor shape on hover. `None` falls back
 	/// to the `Pointer` (hand) default for clickable widgets.
-	pub cursor:    Option<crate::types::CursorShape>,
+	pub( crate ) cursor:    Option<crate::types::CursorShape>,
 	/// When `true`, holding the button down auto-fires the
 	/// `on_press` message: one immediate fire on press, then an
 	/// initial delay (≈ 500 ms — same as the keyboard) followed by
@@ -83,8 +94,8 @@ pub struct Button<Msg: Clone>
 	/// target). The runtime cancels the timer on release, on touch
 	/// cancel, and on long-press promotion. Default `false` — most
 	/// buttons fire on tap only.
-	pub repeating: bool,
-	pub tooltip:   Option<String>,
+	pub( crate ) repeating: bool,
+	pub( crate ) tooltip:   Option<String>,
 }
 
 impl<Msg: Clone> Button<Msg>
@@ -99,7 +110,9 @@ impl<Msg: Clone> Button<Msg>
 			on_long_press: None,
 			on_drag_start: None,
 			variant:       ButtonVariant::Primary,
-			icon_size:     theme::HEIGHT,
+			icon_size:     0.0,
+			font_size:     None,
+			height:        None,
 			id:            None,
 			focusable:     true,
 			cursor:        None,
@@ -134,7 +147,9 @@ impl<Msg: Clone> Button<Msg>
 			on_long_press: None,
 			on_drag_start: None,
 			variant:       ButtonVariant::Tertiary,
-			icon_size:     theme::HEIGHT,
+			icon_size:     0.0,
+			font_size:     None,
+			height:        None,
 			id:            None,
 			focusable:     true,
 			cursor:        None,
@@ -222,6 +237,52 @@ impl<Msg: Clone> Button<Msg>
 		self
 	}
 
+	/// Set the label font size for text buttons. Accepts logical `f32`
+	/// pixels or any [`Length`] (e.g. `Length::vmin( 2.2 ).clamp( 14.0,
+	/// 22.0 )` to scale with the surface). No-op for icon buttons.
+	pub fn font_size( mut self, size: impl Into<Length> ) -> Self
+	{
+		self.font_size = Some( size.into() );
+		self
+	}
+
+	/// Set the button height for text buttons. Accepts logical `f32` pixels
+	/// or any [`Length`] (e.g. `Length::vmin( 7.0 ).clamp( 40.0, 64.0 )` to
+	/// scale the box with the surface). No-op for icon buttons, which are
+	/// sized by [`Self::icon_size`].
+	pub fn height( mut self, h: impl Into<Length> ) -> Self
+	{
+		self.height = Some( h.into() );
+		self
+	}
+
+	/// Resolve the label font size against the canvas viewport, matching how
+	/// [`text`](crate::text) sizes its glyphs. An explicit override bypasses
+	/// the mode; the default follows the process [`crate::WidgetScaling`].
+	fn label_font_size( &self, canvas: &Canvas ) -> f32
+	{
+		self.font_size
+			.map( |l| l.resolve( canvas.viewport_logical(), Length::EM_BASE_DEFAULT ) )
+			.unwrap_or_else( || canvas.font_px( theme::FONT_SIZE ) )
+	}
+
+	/// Resolve the button height against the physical layout viewport (like
+	/// all geometry). An explicit override bypasses the mode; the default
+	/// follows the process [`crate::WidgetScaling`].
+	fn resolved_height( &self, canvas: &Canvas ) -> f32
+	{
+		self.height
+			.map( |l| l.resolve( canvas.viewport_layout(), Length::EM_BASE_DEFAULT ) )
+			.unwrap_or_else( || canvas.geom_px( theme::HEIGHT ) )
+	}
+
+	/// Resolve the icon-button size: a positive [`Self::icon_size`] pins it,
+	/// the `0.0` sentinel follows the widget-scaling mode.
+	fn resolved_icon_size( &self, canvas: &Canvas ) -> f32
+	{
+		if self.icon_size > 0.0 { self.icon_size } else { canvas.geom_px( theme::HEIGHT ) }
+	}
+
 	/// Assign a stable identifier for focus management.
 	pub fn id( mut self, id: WidgetId ) -> Self
 	{
@@ -268,13 +329,13 @@ impl<Msg: Clone> Button<Msg>
 		{
 			ButtonContent::Text( label ) =>
 			{
-				let text_w = canvas.measure_text( label, theme::FONT_SIZE );
-				let w = (text_w + theme::PAD_H * 2.0).min( max_width );
-				( w, theme::HEIGHT )
+				let text_w = canvas.measure_text( label, self.label_font_size( canvas ) );
+				let w = (text_w + canvas.geom_px( theme::PAD_H ) * 2.0).min( max_width );
+				( w, self.resolved_height( canvas ) )
 			}
 			ButtonContent::Icon { .. } =>
 			{
-				let s = self.icon_size.min( max_width );
+				let s = self.resolved_icon_size( canvas ).min( max_width );
 				( s, s )
 			}
 		}
@@ -302,7 +363,8 @@ impl<Msg: Clone> Button<Msg>
 	fn draw_text_button( &self, canvas: &mut Canvas, rect: Rect, focused: bool, label: &str )
 	{
 		let is_disabled = self.on_press.is_none();
-		let text_y      = rect.y + (rect.height + theme::FONT_SIZE) / 2.0 - 2.0;
+		let fs          = self.label_font_size( canvas );
+		let text_y      = rect.y + (rect.height + fs) / 2.0 - 2.0;
 
 		match self.variant
 		{
@@ -326,12 +388,12 @@ impl<Msg: Clone> Button<Msg>
 						theme::RADIUS + theme::FOCUS_W + 2.0,
 					);
 				}
-				let text_w = canvas.measure_text( label, theme::FONT_SIZE );
+				let text_w = canvas.measure_text( label, fs );
 				canvas.draw_text(
 					label,
 					rect.x + (rect.width - text_w) / 2.0,
 					text_y,
-					theme::FONT_SIZE,
+					fs,
 					text_c,
 				);
 			}
@@ -352,12 +414,12 @@ impl<Msg: Clone> Button<Msg>
 						theme::RADIUS + theme::FOCUS_W + 2.0,
 					);
 				}
-				let text_w = canvas.measure_text( label, theme::FONT_SIZE );
+				let text_w = canvas.measure_text( label, fs );
 				canvas.draw_text(
 					label,
 					rect.x + (rect.width - text_w) / 2.0,
 					text_y,
-					theme::FONT_SIZE,
+					fs,
 					text_c,
 				);
 			}
@@ -369,12 +431,12 @@ impl<Msg: Clone> Button<Msg>
 					let ring = rect.expand( 2.0 );
 					canvas.stroke_rect( ring, theme::focus_color(), theme::FOCUS_W, theme::RADIUS );
 				}
-				let text_w = canvas.measure_text( label, theme::FONT_SIZE );
+				let text_w = canvas.measure_text( label, fs );
 				canvas.draw_text(
 					label,
 					rect.x + (rect.width - text_w) / 2.0,
 					text_y,
-					theme::FONT_SIZE,
+					fs,
 					text_c,
 				);
 			}
@@ -446,6 +508,8 @@ impl<Msg: Clone> Button<Msg>
 			on_drag_start: self.on_drag_start.map( |m| ( *f )( m ) ),
 			variant:       self.variant,
 			icon_size:     self.icon_size,
+			font_size:     self.font_size,
+			height:        self.height,
 			id:            self.id,
 			focusable:     self.focusable,
 			cursor:        self.cursor,