Bump to 0.2.0: SW/GLES paint parity, shared font resolution, FrameState refactor, docs and packaging fixes

Rendering parity (software ↔ GLES). The software backend now rounds glyph pen positions and image destinations to the nearest integer pixel, matching what the GLES backend already did; previously it truncated, so text and 1:1 images could land up to half a pixel off between the two backends and the bilinear sample read ~1 px softer than the source. Gradients and shadows are deliberately left unimplemented on the software backend, and the GLES multi-rect `glScissor` clip is left coarse on purpose: making it exact would need stencil bits the EGL config does not carry, or routing the partial-redraw path through the offscreen clip layer, which would break its `fill` / `clear_rects_transparent` scissor semantics. Adds software-backend pixel tests covering the snapping.
Font resolution unification. The system-font candidate chain, `find_font_opt` and `load_default_font_bytes` lived in two copies (`render/helpers` and `gles_render/helpers`) that had already diverged — one resolved through `find_font_opt`, the other inlined the candidate loop — and now live once in `system_fonts`. The two per-backend `OnceLock` default-font caches and `primary_handle` collapse into a single `system_fonts::default_handle`. Module docs and the `font_registry` caller are updated accordingly.
Shared image validation and rect inflation. `draw_image_data`'s dimension check and its one-line warning were byte-duplicated across both backends and are now `render::helpers::validate_rgba_dims`. The six manual symmetric `Rect`-inflate literals in the GLES primitives reuse the existing `Rect::expand`.
FrameState and DrawCtx de-duplication. The eleven `SurfaceState` fields the draw pass owns and threads through `DrawCtx` — `widget_rects`, the cursor / selection maps, the scroll state, `accessible_extras`, `prev_focused` / `prev_hovered` / `prev_pressed` — move into a `FrameState` sub-struct. The per-frame `build_draw_ctx` / `commit_draw_ctx` helpers can then borrow `&mut ss.frame`, disjoint from `ss.canvas` and `ss.pool`, so the four frame paths (software / GLES × full / partial) replace their duplicated `DrawCtx` construction and write-back with a single helper call each. A whole-`SurfaceState` borrow could not express this (partial borrows do not cross function boundaries), which is why the helpers take the sub-struct. `content_dirty` stays on `SurfaceState` — it is an invalidation flag, not frame state — and is reset at the call site.
rich_text tests. Adds the previously-missing `tests.rs` for the `RichText` widget: one hit rect per visual line a link spans (the widget's core invariant), the single-line and no-link cases, preferred-size growth with hard line breaks, and `map_msg` range preservation — all headless against a software `Canvas`, with line counts forced by `\n` so they do not depend on any system font's measured width.
Documentation. Fills the rustdoc gaps on the embedder-facing surface: `core::UiSurface` accessors, the `egl_context` public API, the `GlesCanvas` methods, `theme::typography` and `theme::error`, and the `RichText` / `Text` builders; adds a crate-level "Rendering backends" overview. `CHANGELOG.md` is added (0.2.0 / 0.1.0), and `docs/widgets.md` / `docs/cookbook.md` gain `rich_text`, `external`, and the CPU-draw / path-clip / externally-laid-out-tree recipes. `debian/changelog` gets the 0.2.0-1 entry. Private intra-doc links to `system_fonts` are demoted to code spans so `cargo doc` is warning-free.
Packaging. The `libltk-dev` registry crate shipped a `Cargo.toml` declaring the `lookup` bench while the `Makefile` install copied only `src/`, so Cargo refused to parse the manifest over a missing `benches/lookup.rs`; the install now ships `benches/` as well (the file alone satisfies the parse — criterion is a dev-dependency and is not resolved when the crate is consumed as a library). `Cargo.toml` is bumped to 0.2.0 to match the package version and the `ltk-0.2.0` registry directory.

src/widget/rich_text/mod.rs

@@ -15,6 +15,9 @@ use crate::types::{ Color, Length, Rect };
 use crate::render::Canvas;
 use super::{ Element, MapFn };
 
+#[ cfg( test ) ]
+mod tests;
+
 /// A clickable range `[start, end)` (byte offsets into the content) and the
 /// message to emit when it is tapped.
 pub struct LinkSpan<Msg>
@@ -24,6 +27,10 @@ pub struct LinkSpan<Msg>
 	pub msg:   Msg,
 }
 
+/// A wrapped paragraph with clickable link ranges — the ltk counterpart of an
+/// Android `Spanned` carrying `URLSpan` / `ClickableSpan`. Each [`LinkSpan`]
+/// pairs a byte range with a `Msg` emitted on tap; the layout pass yields one
+/// hit rect per link line so taps land on the link rather than the paragraph.
 pub struct RichText<Msg: Clone>
 {
 	pub content:    String,
@@ -36,6 +43,8 @@ pub struct RichText<Msg: Clone>
 
 impl<Msg: Clone> RichText<Msg>
 {
+	/// A paragraph of `content` with no links: white text, the default blue
+	/// link colour, default 16 px size and the canvas default font.
 	pub fn new( content: impl Into<String> ) -> Self
 	{
 		Self
@@ -49,24 +58,29 @@ impl<Msg: Clone> RichText<Msg>
 		}
 	}
 
+	/// Set the font size.
 	pub fn size( mut self, s: impl Into<Length> ) -> Self
 	{
 		self.size = s.into();
 		self
 	}
 
+	/// Set the colour of non-link text.
 	pub fn color( mut self, c: Color ) -> Self
 	{
 		self.color = c;
 		self
 	}
 
+	/// Set the colour of link ranges (drawn underlined).
 	pub fn link_color( mut self, c: Color ) -> Self
 	{
 		self.link_color = c;
 		self
 	}
 
+	/// Override the font with a `(family, weight, style)` triple resolved
+	/// through the active theme's font registry on draw.
 	pub fn font( mut self, family: impl Into<String>, weight: u16, style: FontStyle ) -> Self
 	{
 		self.font = Some( ( family.into(), weight, style ) );
@@ -316,6 +330,7 @@ impl<Msg: Clone + 'static> From<RichText<Msg>> for Element<Msg>
 	}
 }
 
+/// Free-function shorthand for [`RichText::new`].
 pub fn rich_text<Msg: Clone>( content: impl Into<String> ) -> RichText<Msg>
 {
 	RichText::new( content )

src/widget/rich_text/tests.rs

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: LGPL-2.1-only
+// Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>
+
+//! Headless tests for the `rich_text` layout logic, run against a software
+//! `Canvas` (no GL needed). Line counts are forced with hard `\n` breaks so the
+//! assertions do not depend on the measured width of any particular system font.
+
+use super::*;
+use crate::render::Canvas;
+use crate::types::Rect;
+
+fn canvas() -> Canvas
+{
+	Canvas::new( 800, 600 )
+}
+
+fn rect( w: f32, h: f32 ) -> Rect
+{
+	Rect { x: 0.0, y: 0.0, width: w, height: h }
+}
+
+#[ test ]
+fn link_spanning_two_lines_yields_one_rect_per_line()
+{
+	let c = canvas();
+	// Hard break splits the paragraph into two visual lines regardless of font
+	// metrics; the single link covers both words.
+	let rt = rich_text::<i32>( "first\nsecond" ).link( 0, 12, 7 );
+	let rects = rt.link_rects( rect( 1000.0, 200.0 ), &c );
+
+	assert_eq!( rects.len(), 2, "a link crossing two lines must emit one rect per line" );
+	assert!( rects.iter().all( |( _, m )| *m == 7 ), "every line rect carries the link message" );
+	assert!( rects[ 1 ].0.y > rects[ 0 ].0.y, "the second line's rect sits below the first" );
+}
+
+#[ test ]
+fn single_line_link_yields_one_rect()
+{
+	let c = canvas();
+	// "world" is bytes [6, 11). A generous width keeps the paragraph on one line.
+	let rt = rich_text::<i32>( "hello world" ).link( 6, 11, 1 );
+	let rects = rt.link_rects( rect( 10_000.0, 100.0 ), &c );
+
+	assert_eq!( rects.len(), 1 );
+	assert_eq!( rects[ 0 ].1, 1 );
+	assert!( rects[ 0 ].0.width > 0.0, "the link rect spans the measured substring" );
+}
+
+#[ test ]
+fn paragraph_without_links_has_no_hit_rects()
+{
+	let c = canvas();
+	let rt = rich_text::<i32>( "plain paragraph, no links here" );
+	assert!( rt.link_rects( rect( 1000.0, 100.0 ), &c ).is_empty() );
+}
+
+#[ test ]
+fn link_off_a_line_is_not_reported_on_that_line()
+{
+	let c = canvas();
+	// Link only covers "first" (bytes [0, 5)); the second line must report nothing.
+	let rt = rich_text::<i32>( "first\nsecond" ).link( 0, 5, 9 );
+	let rects = rt.link_rects( rect( 1000.0, 200.0 ), &c );
+	assert_eq!( rects.len(), 1, "a link confined to one line yields exactly one rect" );
+}
+
+#[ test ]
+fn preferred_size_height_grows_with_hard_breaks()
+{
+	let c = canvas();
+	let one   = rich_text::<i32>( "a" ).preferred_size( 1000.0, &c );
+	let three = rich_text::<i32>( "a\nb\nc" ).preferred_size( 1000.0, &c );
+
+	assert_eq!( one.0, 1000.0, "preferred width echoes the max width" );
+	assert!( one.1 > 0.0, "a single line has positive height" );
+	assert!( three.1 > one.1 * 2.0, "three lines are taller than one ({:?} vs {:?})", three.1, one.1 );
+}
+
+#[ test ]
+fn preferred_size_empty_content_is_one_line()
+{
+	let c = canvas();
+	let empty = rich_text::<i32>( "" ).preferred_size( 1000.0, &c );
+	let one   = rich_text::<i32>( "a" ).preferred_size( 1000.0, &c );
+	assert!( empty.1 > 0.0, "empty content still reserves one line" );
+	assert!( ( empty.1 - one.1 ).abs() < 0.5, "empty and single-char are both one line tall" );
+}
+
+#[ test ]
+fn map_msg_preserves_link_ranges_and_count()
+{
+	let rt = rich_text::<i32>( "alpha beta" ).link( 0, 5, 11 ).link( 6, 10, 22 );
+	let f: std::sync::Arc<dyn Fn( i32 ) -> String> = std::sync::Arc::new( |m| format!( "msg-{m}" ) );
+	let mapped = rt.map_msg( &f );
+
+	assert_eq!( mapped.links.len(), 2 );
+	assert_eq!( ( mapped.links[ 0 ].start, mapped.links[ 0 ].end ), ( 0, 5 ) );
+	assert_eq!( ( mapped.links[ 1 ].start, mapped.links[ 1 ].end ), ( 6, 10 ) );
+	assert_eq!( mapped.links[ 0 ].msg, "msg-11" );
+	assert_eq!( mapped.links[ 1 ].msg, "msg-22" );
+}

src/widget/text/mod.rs

@@ -1,6 +1,10 @@
 // SPDX-License-Identifier: LGPL-2.1-only
 // Copyright (C) 2026 Liberux Labs, S. L. <info@liberux.net>
 
+//! Single- or multi-line text: a font-sized, coloured, aligned string that
+//! either stays on one line (truncating with an ellipsis on overflow) or
+//! word-wraps to the layout width.
+
 use std::sync::Arc;
 
 use fontdue::Font;
@@ -13,14 +17,20 @@ use super::Element;
 #[ cfg( test ) ]
 mod tests;
 
+/// Horizontal alignment of text within its layout rect.
 #[ derive( Debug, Clone, Copy, PartialEq ) ]
 pub enum TextAlign
 {
+	/// Align to the left edge.
 	Left,
+	/// Centre within the rect.
 	Center,
+	/// Align to the right edge.
 	Right,
 }
 
+/// A run of text rendered with a size, colour, alignment and optional font,
+/// either word-wrapped or kept on one line with ellipsis truncation.
 pub struct Text
 {
 	pub content:  String,
@@ -45,6 +55,8 @@ pub struct Text
 
 impl Text
 {
+	/// A left-aligned, non-wrapping, ellipsis-truncated white label at the
+	/// default 16 px size with the canvas default font.
 	pub fn new( content: impl Into<String> ) -> Self
 	{
 		Self
@@ -68,6 +80,8 @@ impl Text
 		self.size.resolve( canvas.viewport_logical(), Length::EM_BASE_DEFAULT )
 	}
 
+	/// Paint the full string even when it overflows, instead of truncating
+	/// with an ellipsis.
 	pub fn no_truncate( mut self ) -> Self
 	{
 		self.truncate = false;
@@ -93,24 +107,28 @@ impl Text
 		self
 	}
 
+	/// Set the font size.
 	pub fn size( mut self, s: impl Into<Length> ) -> Self
 	{
 		self.size = s.into();
 		self
 	}
 
+	/// Set the text colour.
 	pub fn color( mut self, c: Color ) -> Self
 	{
 		self.color = c;
 		self
 	}
 
+	/// Set the horizontal alignment.
 	pub fn align( mut self, a: TextAlign ) -> Self
 	{
 		self.align = a;
 		self
 	}
 
+	/// Shorthand for [`Self::align`] with [`TextAlign::Center`].
 	pub fn align_center( mut self ) -> Self
 	{
 		self.align = TextAlign::Center;