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/event_loop/overlays_reconcile.rs

@@ -24,7 +24,7 @@ use wayland_protocols::xdg::shell::client::xdg_positioner::
 };
 
 use crate::app::App;
-use crate::types::Rect;
+use crate::types::{ Length, Rect };
 use super::{ AppData, LayerConfig, SurfaceFocus, SurfaceKind, SurfaceState };
 
 /// Sync `data.overlays` with the app's current `App::overlays()` spec list:
@@ -106,6 +106,18 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 	};
 	let parent_scale_i = data.main.scale_factor.max( 1 );
 	let parent_scale   = parent_scale_i as f32;
+	// `OverlaySpec::size` carries `Length`s resolved against the main
+	// surface's physical viewport (the app's layout space), so an overlay
+	// sized with `Length::widget( … )` scales with the display exactly like
+	// any other widget. `Length::px( n )` keeps a fixed size.
+	let main_vp        = ( data.main.physical_width() as f32, data.main.physical_height() as f32 );
+	let resolve_size   = move | s: &( Length, Length ) | -> ( u32, u32 )
+	{
+		(
+			s.0.resolve( main_vp, Length::EM_BASE_DEFAULT ).max( 0.0 ).round() as u32,
+			s.1.resolve( main_vp, Length::EM_BASE_DEFAULT ).max( 0.0 ).round() as u32,
+		)
+	};
 	// `OverlaySpec::size` is physical pixels (the app's layout space); the
 	// layer-shell `set_size` is logical. They only coincide at scale 1, so
 	// convert here — without it a scale-2 overlay requests a surface twice
@@ -124,6 +136,7 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 	let overlays_m = &mut data.overlays;
 	for spec in &specs
 	{
+		let resolved_size = resolve_size( &spec.size );
 		if let Some( ss ) = overlays_m.get_mut( &spec.id )
 		{
 			// Already-live overlay: propagate size changes to the layer
@@ -135,14 +148,14 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 			// sends a configure; the usual `on_configure` path picks up the
 			// new dimensions and drives the redraw. Popups don't grow /
 			// shrink mid-life — close and reopen instead.
-			if spec.size != ss.last_requested_size
+			if resolved_size != ss.last_requested_size
 			{
 				if let SurfaceKind::Layer( ref layer_surface ) = ss.surface
 				{
-					let ( lw, lh ) = to_logical_size( spec.size );
+					let ( lw, lh ) = to_logical_size( resolved_size );
 					layer_surface.set_size( lw, lh );
 					layer_surface.commit();
-					ss.last_requested_size = spec.size;
+					ss.last_requested_size = resolved_size;
 				}
 			}
 			// Compare the anchor at integer logical-pixel resolution:
@@ -173,7 +186,7 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 							if let Ok( positioner ) = XdgPositioner::new( xdg_shell )
 							{
 								let ( ax, ay, aw, ah ) = new_q;
-								let ( spec_w, spec_h ) = spec.size;
+								let ( spec_w, spec_h ) = resolved_size;
 								let popup_w = if spec_w == 0 { aw } else { spec_w.max( 1 ) as i32 };
 								let popup_h = spec_h.max( 1 ) as i32;
 								positioner.set_size( popup_w, popup_h );
@@ -236,7 +249,7 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 			let ay = ( anchor_rect.y      / parent_scale ).round() as i32;
 			let aw = ( anchor_rect.width  / parent_scale ).round().max( 1.0 ) as i32;
 			let ah = ( anchor_rect.height / parent_scale ).round().max( 1.0 ) as i32;
-			let ( spec_w, spec_h ) = spec.size;
+			let ( spec_w, spec_h ) = resolved_size;
 			let popup_w = if spec_w == 0 { aw } else { spec_w.max( 1 ) as i32 };
 			let popup_h = spec_h.max( 1 ) as i32;
 			positioner.set_size( popup_w, popup_h );
@@ -274,7 +287,7 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 			}
 			popup.wl_surface().commit();
 			let mut ss = SurfaceState::<A::Message>::new( SurfaceKind::Popup( popup ), 0.0, String::new() );
-			ss.last_requested_size = spec.size;
+			ss.last_requested_size = resolved_size;
 			ss.last_popup_anchor   = Some( anchor_rect );
 			overlays_m.insert( spec.id, ss );
 			continue;
@@ -290,7 +303,7 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 			layer:              spec.layer.to_wlr_layer(),
 			exclusive_zone:     spec.exclusive_zone,
 			anchor:             spec.anchor,
-			size:               to_logical_size( spec.size ),
+			size:               to_logical_size( resolved_size ),
 			keyboard_exclusive: spec.keyboard_exclusive,
 			namespace:          "ltk-overlay",
 		};
@@ -305,7 +318,7 @@ pub( super ) fn reconcile_overlays<A: App>( data: &mut AppData<A> )
 		// instead of rendering at scale 1 until `scale_factor_changed`
 		// lands a frame or two later.
 		ss.scale_factor        = parent_scale_i;
-		ss.last_requested_size = spec.size;
+		ss.last_requested_size = resolved_size;
 		ss.layer_anchor        = Some( spec.anchor );
 		overlays_m.insert( spec.id, ss );
 	}