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/render/mod.rs

@@ -39,7 +39,7 @@ use tiny_skia::{ Mask, Pixmap };
 
 use crate::gles_render::{ BorrowedGlesTexture, GlesCanvas, GlesVersion };
 use crate::theme::{ FontRegistry, FontStyle, InsetShadow, Paint as ThemePaint, Shadow };
-use crate::types::{ Color, Corners, Rect };
+use crate::types::{ Color, Corners, Length, Rect, WidgetScaling };
 
 pub( crate ) mod setup;
 pub( crate ) mod clip;
@@ -239,6 +239,45 @@ impl Canvas
 		( pw as f32, ph as f32 )
 	}
 
+	/// Resolve a stock-widget **geometry** design pixel (height, padding,
+	/// box size, gap…) through the process-wide [`crate::WidgetScaling`]
+	/// mode, into a concrete physical-pixel value for the layout tree.
+	/// Widgets call this instead of using a raw `theme::` constant so their
+	/// intrinsic geometry follows the app's chosen adaptation strategy
+	/// ([`crate::WidgetScaling::Fluid`] → surface-proportional,
+	/// [`crate::WidgetScaling::Physical`] → constant physical size). Geometry
+	/// lives in physical space, so this resolves against
+	/// [`Self::viewport_layout`].
+	pub fn geom_px( &self, design_px: f32 ) -> f32
+	{
+		Length::widget( design_px ).resolve( self.viewport_layout(), Length::EM_BASE_DEFAULT )
+	}
+
+	/// Resolve a stock-widget **font** design pixel through the process-wide
+	/// [`crate::WidgetScaling`] mode. Font sizes are handed to the raster
+	/// path pre-`dpi_scale`, so this bridges the logical/physical split for
+	/// each mode: in [`crate::WidgetScaling::Fluid`] it resolves the fluid
+	/// size against [`Self::viewport_logical`] (so `× dpi_scale` at raster
+	/// yields a surface-proportional physical size); in
+	/// [`crate::WidgetScaling::Physical`] it divides the density-scaled size
+	/// by `dpi_scale` (so `× dpi_scale` yields a constant physical size).
+	pub fn font_px( &self, design_px: f32 ) -> f32
+	{
+		match crate::types::widget_scaling()
+		{
+			WidgetScaling::Fluid =>
+			{
+				Length::fluid( design_px ).resolve( self.viewport_logical(), Length::EM_BASE_DEFAULT )
+			}
+			WidgetScaling::Physical =>
+			{
+				let scale = self.dpi_scale();
+				let scale = if scale > 0.0 { scale } else { 1.0 };
+				design_px * crate::types::density() / scale
+			}
+		}
+	}
+
 	/// Borrow the GLES texture backing this canvas, when the canvas
 	/// is GPU-backed.
 	pub fn borrowed_gles_texture( &self ) -> Option<BorrowedGlesTexture>
@@ -805,6 +844,45 @@ mod viewport_tests
 		c.set_dpi_scale( 2.0 );
 		assert_eq!( c.viewport_layout(), ( 720.0, 1440.0 ) );
 	}
+
+	#[ test ]
+	fn geom_px_resolves_widget_design_pixel_per_mode()
+	{
+		use crate::types::{ set_widget_scaling, set_density, WidgetScaling, Length };
+		let _g = crate::TEST_GLOBALS_LOCK.lock().unwrap_or_else( |e| e.into_inner() );
+
+		// Fluid (default): geom_px == fluid( n ) against the physical viewport.
+		set_widget_scaling( WidgetScaling::Fluid );
+		let c = Canvas::new( 412, 900 );
+		assert_eq!( c.geom_px( 48.0 ), Length::fluid( 48.0 ).resolve( ( 412.0, 900.0 ), Length::EM_BASE_DEFAULT ) );
+
+		// Physical: geom_px == n * density, independent of surface size.
+		set_widget_scaling( WidgetScaling::Physical );
+		set_density( 2.0 );
+		assert_eq!( c.geom_px( 48.0 ), 96.0 );
+
+		set_density( 1.0 );
+		set_widget_scaling( WidgetScaling::Fluid );
+	}
+
+	#[ test ]
+	fn font_px_is_constant_physical_in_physical_mode()
+	{
+		use crate::types::{ set_widget_scaling, set_density, WidgetScaling };
+		let _g = crate::TEST_GLOBALS_LOCK.lock().unwrap_or_else( |e| e.into_inner() );
+
+		// Physical mode divides by dpi_scale so `× dpi_scale` at raster yields
+		// a constant physical size (n * density).
+		set_widget_scaling( WidgetScaling::Physical );
+		set_density( 2.0 );
+		let mut c = Canvas::new( 720, 1440 );
+		c.set_dpi_scale( 2.0 );
+		// 16 * 2 (density) / 2 (dpi_scale) = 16 logical → 32 physical after raster.
+		assert_eq!( c.font_px( 16.0 ), 16.0 );
+
+		set_density( 1.0 );
+		set_widget_scaling( WidgetScaling::Fluid );
+	}
 }
 
 #[ cfg( test ) ]