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

@@ -149,6 +149,61 @@ impl SurfaceKind
 	}
 }
 
+/// The subset of per-surface state the draw pass owns and threads through
+/// [`crate::draw::DrawCtx`]: the laid-out widget rects it produces, the scroll /
+/// text-edit / a11y state carried across frames, and the previous frame's
+/// interaction indices for damage tracking. Grouped into its own struct so the
+/// draw helpers can borrow it as one unit, disjoint from `canvas` / `pool`.
+pub( crate ) struct FrameState<Msg: Clone>
+{
+	pub widget_rects:       Vec<LaidOutWidget<Msg>>,
+	pub cursor_state:       HashMap<usize, usize>,
+	/// Selection anchor (byte offset). When equal to the cursor, there is no
+	/// active selection. Mutated jointly with `cursor_state`: plain arrow keys
+	/// collapse the selection by setting anchor = cursor; Shift+arrow extends by
+	/// leaving anchor put while moving cursor; pointer drags set both ends.
+	pub selection_anchor:   HashMap<usize, usize>,
+	pub accessible_extras:  Vec<crate::a11y::tree::AccessibleExtra>,
+	/// Per-scroll-viewport offset, indexed by `flat_idx` of the `Scroll` widget.
+	/// Tuple is `(x, y)` in physical pixels: x is applied only when the widget's
+	/// axis allows horizontal scroll (and stays at `0` otherwise), y mirrors the
+	/// historic single-f32 behaviour for vertical scrolls.
+	pub scroll_offsets:     HashMap<usize, ( f32, f32 )>,
+	pub scroll_rects:       Vec<( Rect, usize, crate::widget::scroll::ScrollAxis )>,
+	pub scroll_canvases:    HashMap<usize, Canvas>,
+	/// Per-scroll list of `(flat_idx, content_y, height)` entries for every
+	/// interactive item the scroll's child laid out, in document order. Includes
+	/// items currently scrolled off-screen so keyboard arrow handlers can step
+	/// `hovered_idx` item-by-item without regenerating the layout pass. Y is in
+	/// pre-translation, pre-offset content coordinates.
+	pub scroll_navigable_items: HashMap<usize, Vec<( usize, f32, f32 )>>,
+	/// Previous frame interaction state for damage tracking.
+	pub prev_focused:       Option<usize>,
+	pub prev_hovered:       Option<usize>,
+	pub prev_pressed:       Option<usize>,
+}
+
+impl<Msg: Clone> FrameState<Msg>
+{
+	pub( crate ) fn new() -> Self
+	{
+		Self
+		{
+			widget_rects:       Vec::new(),
+			cursor_state:       HashMap::new(),
+			selection_anchor:   HashMap::new(),
+			accessible_extras:  Vec::new(),
+			scroll_offsets:     HashMap::new(),
+			scroll_rects:       Vec::new(),
+			scroll_canvases:    HashMap::new(),
+			scroll_navigable_items: HashMap::new(),
+			prev_focused:       None,
+			prev_hovered:       None,
+			prev_pressed:       None,
+		}
+	}
+}
+
 /// Per-surface render + interaction state.
 ///
 /// Each Wayland surface managed by the event loop (main surface and any
@@ -177,31 +232,11 @@ pub( crate ) struct SurfaceState<Msg: Clone>
 	pub focused_idx:        Option<usize>,
 	pub focused_id:         Option<WidgetId>,
 	pub hovered_idx:        Option<usize>,
-	pub widget_rects:       Vec<LaidOutWidget<Msg>>,
-	pub cursor_state:       HashMap<usize, usize>,
-	/// Selection anchor (byte offset). When equal to the cursor, there
-	/// is no active selection. Mutated jointly with `cursor_state`:
-	/// plain arrow keys collapse the selection by setting anchor =
-	/// cursor; Shift+arrow extends by leaving anchor put while moving
-	/// cursor; pointer drags set both ends.
-	pub selection_anchor:   HashMap<usize, usize>,
 	pub pending_text_values: HashMap<usize, String>,
-	/// Per-scroll-viewport offset, indexed by `flat_idx` of the
-	/// `Scroll` widget. Tuple is `(x, y)` in physical pixels: x is
-	/// applied only when the widget's axis allows horizontal scroll
-	/// (and stays at `0` otherwise), y mirrors the historic single-f32
-	/// behaviour for vertical scrolls.
-	pub accessible_extras: Vec<crate::a11y::tree::AccessibleExtra>,
-	pub scroll_offsets:     HashMap<usize, ( f32, f32 )>,
-	pub scroll_rects:       Vec<( Rect, usize, crate::widget::scroll::ScrollAxis )>,
-	pub scroll_canvases:    HashMap<usize, Canvas>,
-	/// Per-scroll list of `(flat_idx, content_y, height)` entries for
-	/// every interactive item the scroll's child laid out, in document
-	/// order. Includes items currently scrolled off-screen so keyboard
-	/// arrow handlers can step `hovered_idx` item-by-item without
-	/// regenerating the layout pass. Y is in pre-translation,
-	/// pre-offset content coordinates.
-	pub scroll_navigable_items: HashMap<usize, Vec<( usize, f32, f32 )>>,
+	/// Per-frame draw state: laid-out rects, carried scroll / text-edit / a11y
+	/// state, and the previous frame's interaction indices. Grouped so the draw
+	/// helpers can borrow it as one unit, disjoint from `canvas` / `pool`.
+	pub frame:              FrameState<Msg>,
 	/// Built-in Copy / Cut / Paste context menu when shown on this
 	/// surface. `None` means no menu is up.
 	pub context_menu:           Option<super::context_menu::ContextMenu>,
@@ -223,10 +258,6 @@ pub( crate ) struct SurfaceState<Msg: Clone>
 	/// `wl_touch.up` does not carry a position) and to keep state
 	/// across `motion` events between dispatchers.
 	pub touch_slots:        HashMap<i32, crate::types::Point>,
-	/// Previous frame interaction state for damage tracking
-	pub prev_focused:       Option<usize>,
-	pub prev_hovered:       Option<usize>,
-	pub prev_pressed:       Option<usize>,
 	/// Height of the client-side title bar (0 for layer-shell surfaces).
 	pub titlebar_height:    f32,
 	/// Title text shown in the client-side title bar.
@@ -275,22 +306,12 @@ impl<Msg: Clone> SurfaceState<Msg>
 			focused_idx:         None,
 			focused_id:          None,
 			hovered_idx:         None,
-			widget_rects:        Vec::new(),
-			cursor_state:        HashMap::new(),
-			selection_anchor:    HashMap::new(),
 			pending_text_values: HashMap::new(),
-			accessible_extras: Vec::new(),
-			scroll_offsets:      HashMap::new(),
-			scroll_rects:        Vec::new(),
-			scroll_navigable_items: HashMap::new(),
+			frame:               FrameState::new(),
 			primary_touch_id:    None,
 			touch_slots:         HashMap::new(),
 			context_menu:        None,
-			scroll_canvases:     HashMap::new(),
 			gesture:             GestureState::new(),
-			prev_focused:        None,
-			prev_hovered:        None,
-			prev_pressed:        None,
 			titlebar_height,
 			titlebar_title,
 			titlebar_close_rect: Rect::default(),