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

examples/mini_shell.rs

@@ -23,7 +23,7 @@ use std::time::{ Duration, Instant };
 
 use ltk::
 {
-	App, ButtonVariant, Color, Element, Keysym, OverlayId, OverlaySpec,
+	App, ButtonVariant, Color, Element, Keysym, Length, OverlayId, OverlaySpec,
 	ThemeMode,
 	button, column, container, progress_bar, row, slider, spacer, text, toggle,
 };
@@ -190,7 +190,7 @@ impl App for AppState
 				id:                 OVERLAY_QUICK_SETTINGS,
 				layer:              ltk::Layer::Overlay,
 				anchor:             ltk::Anchor::ALL,
-				size:               ( 0, 0 ),
+				size:               ( Length::px( 0.0 ), Length::px( 0.0 ) ),
 				exclusive_zone:     0,
 				keyboard_exclusive: false,
 				input_region:       None,
@@ -207,7 +207,7 @@ impl App for AppState
 				id:                 OVERLAY_CONFIRM,
 				layer:              ltk::Layer::Overlay,
 				anchor:             ltk::Anchor::ALL,
-				size:               ( 0, 0 ),
+				size:               ( Length::px( 0.0 ), Length::px( 0.0 ) ),
 				exclusive_zone:     0,
 				keyboard_exclusive: false,
 				input_region:       None,
@@ -224,7 +224,7 @@ impl App for AppState
 				id:                 OVERLAY_TOAST,
 				layer:              ltk::Layer::Overlay,
 				anchor:             ltk::Anchor::ALL,
-				size:               ( 0, 0 ),
+				size:               ( Length::px( 0.0 ), Length::px( 0.0 ) ),
 				exclusive_zone:     0,
 				keyboard_exclusive: false,
 				// Pass-through: the OSD must not steal taps from anything below.

examples/responsive.rs

@@ -0,0 +1,156 @@
+//! `cargo run --example responsive`
+//!
+//! Demonstrates ltk's two responsive modes side by side on stock widgets.
+//! None of the widgets below set an explicit size — they all follow the
+//! process-wide [`ltk::WidgetScaling`] mode:
+//!
+//! - **Fluid** (the default): sizes are a fraction of the surface, so the
+//!   whole set grows and shrinks as you resize the window.
+//! - **Physical**: sizes are a constant real-world size scaled by
+//!   [`ltk::density`], independent of the surface.
+//!
+//! Tap **Switch mode** to flip between them, and **−／＋ density** to change
+//! the physical density. Watch the button, field, checkbox, switch, slider
+//! and progress bar resize (or not) accordingly. Esc exits.
+//!
+//! NOTE: ltk is a Wayland layer-shell toolkit. This example requires a running
+//! Wayland compositor (e.g. sway, labwc, or a full desktop session).
+
+use ltk::
+{
+	App, Element, Keysym, ButtonVariant, WidgetScaling,
+	button, checkbox, column, progress_bar, row, separator, slider, spacer, text, text_edit, toggle,
+	set_widget_scaling, set_density, density,
+};
+
+#[ derive( Clone ) ]
+enum Message
+{
+	SwitchMode,
+	DensityUp,
+	DensityDown,
+	NameChanged( String ),
+	ToggleCheck,
+	ToggleSwitch,
+	SliderChanged( f32 ),
+}
+
+struct ResponsiveApp
+{
+	physical: bool,
+	name:     String,
+	checked:  bool,
+	switched: bool,
+	volume:   f32,
+}
+
+impl ResponsiveApp
+{
+	fn new() -> Self
+	{
+		// Start in the default fluid mode with a neutral density.
+		set_widget_scaling( WidgetScaling::Fluid );
+		set_density( 1.5 );
+		Self
+		{
+			physical: false,
+			name:     String::new(),
+			checked:  true,
+			switched: false,
+			volume:   0.4,
+		}
+	}
+}
+
+impl App for ResponsiveApp
+{
+	type Message = Message;
+
+	fn view( &self ) -> Element<Message>
+	{
+		let palette   = ltk::theme_palette();
+		let primary   = palette.text_primary;
+		let secondary = palette.text_secondary;
+
+		let mode_label = if self.physical
+		{
+			format!( "Mode: Physical  (density {:.1})", density() )
+		} else {
+			"Mode: Fluid  (resize the window to see it scale)".to_string()
+		};
+
+		// Mode + density controls. Explicit sizes here so the controls stay
+		// stable while the demo widgets below react to the mode.
+		let controls = row::<Message>()
+			.spacing( 12.0 )
+			.push( button::<Message>( "Switch mode".to_string() )
+				.variant( ButtonVariant::Primary )
+				.font_size( 16.0 )
+				.height( 44.0 )
+				.on_press( Message::SwitchMode ) )
+			.push( button::<Message>( "− density".to_string() )
+				.font_size( 16.0 )
+				.height( 44.0 )
+				.on_press( Message::DensityDown ) )
+			.push( button::<Message>( "＋ density".to_string() )
+				.font_size( 16.0 )
+				.height( 44.0 )
+				.on_press( Message::DensityUp ) );
+
+		// The demo widgets — NO explicit sizes, so they follow the mode.
+		let demo = column::<Message>()
+			.spacing( 16.0 )
+			.max_width( 520.0 )
+			.push( button::<Message>( "A stock button".to_string() ).variant( ButtonVariant::Secondary ).on_press( Message::SwitchMode ) )
+			.push( text_edit( "A stock text field".to_string(), self.name.clone() ).on_change( Message::NameChanged ) )
+			.push( checkbox( self.checked ).label( "A stock checkbox".to_string() ).on_toggle( Message::ToggleCheck ) )
+			.push( toggle( self.switched ).label( "A stock switch".to_string() ).on_toggle( Message::ToggleSwitch ) )
+			.push( slider( self.volume ).on_change( Message::SliderChanged ) )
+			.push( progress_bar( self.volume ) );
+
+		column::<Message>()
+			.padding( 32.0 )
+			.spacing( 20.0 )
+			.center_y( true )
+			.push( text( "ltk responsive modes".to_string() ).size( 26.0 ).color( primary ).align_center() )
+			.push( text( mode_label ).size( 15.0 ).color( secondary ).align_center() )
+			.push( controls )
+			.push( separator() )
+			.push( demo )
+			.push( spacer().weight( 1 ) )
+			.push( text( "Esc to exit".to_string() ).size( 12.0 ).color( secondary ).align_center() )
+			.into()
+	}
+
+	fn update( &mut self, msg: Message )
+	{
+		match msg
+		{
+			Message::SwitchMode =>
+			{
+				self.physical = !self.physical;
+				set_widget_scaling( if self.physical { WidgetScaling::Physical } else { WidgetScaling::Fluid } );
+			}
+			Message::DensityUp   => set_density( ( density() + 0.25 ).min( 4.0 ) ),
+			Message::DensityDown => set_density( ( density() - 0.25 ).max( 0.5 ) ),
+			Message::NameChanged( v )   => self.name = v,
+			Message::ToggleCheck        => self.checked = !self.checked,
+			Message::ToggleSwitch       => self.switched = !self.switched,
+			Message::SliderChanged( v ) => self.volume = v,
+		}
+	}
+
+	fn on_key( &mut self, keysym: Keysym ) -> Option<Message>
+	{
+		if keysym == Keysym::Escape
+		{
+			std::process::exit( 0 );
+		}
+		None
+	}
+}
+
+fn main()
+{
+	ltk::run( ResponsiveApp::new() );
+}

examples/showcase.rs

@@ -151,10 +151,22 @@ impl App for ShowcaseApp
 
 		// Viewport-relative image: 30 % of the surface width by 10 % of its
 		// height, so it rescales with the window instead of staying fixed.
+		//
+		// The second image uses the orientation-aware helpers: `short_side`
+		// sizes it along the screen's short side (width in portrait, height
+		// in landscape) while `orient` gives that side a different proportion
+		// per orientation — 40 % of the width in portrait, 8 % of the height
+		// in landscape — with the other axis following the source aspect.
 		let banner = column::<Message>()
 			.spacing( 4.0 )
 			.push( text( "img_widget().size( vw 30, vh 10 )" ).size( 12.0 ).color( secondary ) )
-			.push( img_widget( self.image.clone(), IMG_W, IMG_H ).size( Length::vw( 30.0 ), Length::vh( 10.0 ) ) );
+			.push( img_widget( self.image.clone(), IMG_W, IMG_H ).size( Length::vw( 30.0 ), Length::vh( 10.0 ) ) )
+			.push(
+				text( "short_side( orient( 40 %w, 8 %h ) ) — resize / rotate to compare" )
+					.size( Length::orient( 3.0, 2.2 ).clamp( 11.0, 16.0 ) )
+					.color( secondary )
+			)
+			.push( img_widget( self.image.clone(), IMG_W, IMG_H ).short_side( Length::orient( 40.0, 8.0 ) ) );
 
 		let vol_label = format!( "Volume: {:.0}%", self.slider_value * 100.0 );