teksilo_scene/items/

text.rs

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! [`TextItem`] — text in a local-coord rectangle, with alignment + rotation.
//!
//! `TextItem` renders text that wraps within a caller-specified rectangle in
//! local item coordinates. Text can be a static localized string (constructed
//! via `TextItem::new`) or a live `Signal<String>` (constructed via
//! `TextItem::with_signal_text`). Signal-bound and locale-reactive text both
//! register bindings at `RepaintOnly` so changes dirty the `SceneView`'s
//! paint pass without triggering a full rebuild.
//!
//! The foreground colour is a [`ColorProp`], so it accepts a plain
//! [`Color`], a theme role
//! ([`TextRole`](teksilo_tokens::TextRole)), a reactive `Signal<Color>`, or a
//! `Signal<Role>` — resolved against the active theme at paint time.
//!
//! Horizontal [alignment](TextAlign) (leading / center / trailing) and a free
//! [rotation](TextItem::rotation) let a text item self-place value tags, axis
//! labels, and rotated titles without the caller hand-measuring; [`measure`]
//! reports the item's single-line intrinsic size when the caller does want to
//! size around it.
//!
//! Text scale: the global accessibility "grow all text" setting is **off** by
//! default for scene text, since a scene has its own pan/zoom. Opt in via
//! `.follow_text_scale(true)` for labels that should track the app-wide
//! setting instead.
//!
//! ## Accessibility
//!
//! The item emits a `Role::Label` carrying `Role::TextRun` children, so a
//! screen reader can review it by character, word and line, braille can be
//! routed into it, and a magnifier can follow it. The per-character extents
//! are the layout the last paint drew, in scene coordinates — real when the
//! item is upright under a pan/zoom view, degenerate (present but
//! zero-width) when it is rotated, when a label override announces a
//! different string from the one that was measured, or before the first
//! paint.
//!
//! ## When to use
//!
//! Use `TextItem` for card labels, node titles, annotation text, or any text
//! decoration in the lightweight tier. For editable text or text that needs
//! focus, selection, and full accessibility, embed a `RichTextEditor` or
//! `TextInput` as a heavyweight scene widget instead.
//!
//! ## Example
//!
//! ```ignore
//! use teksilo_scene::{SceneModel, TextItem, TextAlign};
//! use teksilo_canvas::{Point, Rect};
//! use teksilo_tokens::Color;
//! use teksilo_i18n::lit;
//!
//! let model = SceneModel::new();
//!
//! let item = TextItem::new(lit!("Scene node"), Rect::new(0.0, 0.0, 120.0, 30.0))
//!     .color(Color::new(0.1, 0.1, 0.1, 1.0))
//!     .align(TextAlign::Center);
//!
//! model.add_item(item, Point::new(40.0, 40.0));
//! ```
//!
//! [`measure`]: TextItem::measure

use std::cell::RefCell;
use std::rc::Rc;

use accesskit::Role;
use teksilo_canvas::text_backend::{
    CharGeom, LineTruncation, TextGeometry, TextLine, TextLineSegment,
};
use teksilo_canvas::{Canvas, Point, Rect, Size, TextBackend, Transform2D};
use teksilo_core::accessibility::AccessNodeBuilder;
use teksilo_core::accessibility::text_runs::{TextRunSource, push_text_runs};
use teksilo_core::binding::BindingLevel;
use teksilo_core::build_context::BuildContext;
use teksilo_core::color_prop::ColorProp;
use teksilo_core::signal::Signal;
use teksilo_core::widget_id::WidgetId;
use teksilo_tokens::Color;

use crate::flags::ItemFlags;
use crate::item::{AppearanceWrite, SceneItem, SceneItemA11yContext, SceneItemPaintContext};
use crate::items::{AccessSubtreeMode, ItemA11yOverrides};
use teksilo_i18n::LocalizedString;

/// Horizontal alignment of a [`TextItem`] within its `local_bounds`.
///
/// Alignment shifts the text's draw origin by the leftover width
/// (`bounds.width − measured_width`); it needs a text backend to measure, so a
/// mock/headless canvas with no backend renders leading-aligned regardless.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum TextAlign {
    /// Left edge in LTR (the default).
    #[default]
    Leading,
    /// Centred within the bounds.
    Center,
    /// Right edge in LTR.
    Trailing,
}

/// Text source for [`TextItem`]: either a static string or a live
/// `Signal<String>`. Signal-bound text refreshes on each paint and
/// dirties the SceneView via `register_bindings`.
#[derive(Debug)]
enum TextSource {
    Bound(Signal<String>),
    /// Localized text; resolved against the active locale on each paint.
    /// `register_bindings` ties the locale signal to the SceneView so a
    /// locale switch repaints and re-resolves.
    Localized(LocalizedString),
}

impl TextSource {
    fn current(&self) -> String {
        match self {
            TextSource::Bound(signal) => signal.get(),
            TextSource::Localized(ls) => ls.resolve_now(),
        }
    }
}

/// Leftover-width offset for a horizontal [`TextAlign`]. Pure so it is unit
/// testable in isolation from the text backend.
fn align_offset(align: TextAlign, available: f32, text_width: f32) -> f32 {
    let extra = (available - text_width).max(0.0);
    match align {
        TextAlign::Leading => 0.0,
        TextAlign::Center => extra * 0.5,
        TextAlign::Trailing => extra,
    }
}

/// The layout one paint produced, kept for the accessibility pass.
///
/// AccessKit's text runs carry a position and a width per character, and
/// [`SceneItem::accessibility`] runs with neither a text backend nor a
/// draw rect to derive them from. Paint is the one place both are in
/// hand.
#[derive(Debug)]
struct PlacedText {
    /// The string that was drawn.
    text: String,
    /// Per-character geometry, in coordinates local to `origin`.
    geometry: Rc<TextGeometry>,
    /// Draw origin in the item's own coordinates.
    origin: Point,
}

/// The scale factor of a transform that is a translation plus a uniform
/// positive scale, or `None` for anything else.
///
/// A text run describes its characters as offsets along one reading
/// direction inside one axis-aligned box, which cannot express a rotated
/// baseline, a shear, or a mirrored axis. Under any of those the honest
/// answer is a degenerate box: a wrong rectangle sends a magnifier
/// somewhere the text is not, while a zero-width one only stops it
/// magnifying.
fn uniform_scale(transform: &Transform2D) -> Option<f32> {
    let [a, b, c, d, _, _] = transform.m;
    if !a.is_finite() || a <= 0.0 {
        return None;
    }
    let tolerance = 1e-4 * a;
    if b.abs() > tolerance || c.abs() > tolerance || (a - d).abs() > tolerance {
        return None;
    }
    Some(a)
}

/// The same geometry with every coordinate multiplied by `scale`.
///
/// A scale never reflows scene text — one logical layout is painted
/// larger — so the scene-space extents AT reads are the layout's own,
/// scaled by the item's own `local_to_scene`.
fn scale_geometry(geometry: &TextGeometry, scale: f32) -> TextGeometry {
    let scale_rect = |r: [f32; 4]| [r[0] * scale, r[1] * scale, r[2] * scale, r[3] * scale];
    TextGeometry {
        lines: geometry
            .lines
            .iter()
            .map(|line| TextLine {
                index: line.index,
                byte_range: line.byte_range.clone(),
                char_range: line.char_range.clone(),
                rect: scale_rect(line.rect),
                baseline: line.baseline * scale,
                caret_x: line.caret_x * scale,
                segments: line
                    .segments
                    .iter()
                    .map(|segment| TextLineSegment {
                        byte_range: segment.byte_range.clone(),
                        char_range: segment.char_range.clone(),
                        direction: segment.direction,
                        rect: scale_rect(segment.rect),
                        characters: segment
                            .characters
                            .iter()
                            .map(|c| CharGeom {
                                position: c.position * scale,
                                width: c.width * scale,
                            })
                            .collect(),
                    })
                    .collect(),
                end: line.end,
                truncation: line.truncation.map(|t| LineTruncation {
                    ellipsis_x: t.ellipsis_x * scale,
                    ellipsis_width: t.ellipsis_width * scale,
                }),
            })
            .collect(),
        dropped_lines: geometry.dropped_lines,
        source_len: geometry.source_len,
        rendered_text: geometry.rendered_text.clone(),
        links: geometry.links.clone(),
    }
}

/// Text in a local-coord rectangle, with optional alignment and rotation.
///
/// Text wraps within the `local_bounds` rectangle; the caller is responsible
/// for sizing the rect so all text is visible. Content is either a static
/// localized string (see [`TextItem::new`]) or a reactive `Signal<String>`
/// (see [`TextItem::with_signal_text`]). Both sources trigger a repaint on
/// change without rebuilding the scene.
#[derive(Debug)]
pub struct TextItem {
    text: TextSource,
    local_bounds: Rect,
    color: ColorProp,
    align: TextAlign,
    /// Rotation about the item's centre, in radians. `0.0` = upright.
    rotation: f32,
    label: Option<LocalizedString>,
    flags: ItemFlags,
    a11y: ItemA11yOverrides,
    /// When `true`, the font size grows with the global accessibility text
    /// scale (`ctx.text_scale`). Off by default: a scene has its own pan/zoom,
    /// so most scene text should stay at its authored size. Opt in via
    /// [`follow_text_scale`](Self::follow_text_scale) for labels that should
    /// track the app-wide "grow all text" setting.
    follow_text_scale: bool,
    /// What the last paint laid out. Feeds the AccessKit text runs; see
    /// [`PlacedText`].
    placed: RefCell<Option<PlacedText>>,
}

impl TextItem {
    /// A static-text item in local coordinates. The `text` is
    /// resolved against the active locale on each paint;
    /// `register_bindings` ties the locale signal to the SceneView at
    /// `BindingLevel::RepaintOnly`, so a locale switch repaints and
    /// re-resolves without rebuilding the composite parent.
    pub fn new(text: impl Into<LocalizedString>, local_bounds: Rect) -> Self {
        let ls: LocalizedString = text.into();
        Self {
            text: TextSource::Localized(ls),
            local_bounds,
            color: ColorProp::Static(Color::BLACK),
            align: TextAlign::Leading,
            rotation: 0.0,
            label: None,
            flags: ItemFlags::default(),
            a11y: ItemA11yOverrides::default(),
            follow_text_scale: false,
            placed: RefCell::new(None),
        }
    }

    /// A text item whose content is driven by a `Signal<String>`.
    /// `register_bindings` ties the signal to the SceneView at
    /// `BindingLevel::RepaintOnly` so changes dirty paint and the
    /// next walk reads the current value.
    pub fn with_signal_text(text: Signal<String>, local_bounds: Rect) -> Self {
        Self {
            text: TextSource::Bound(text),
            local_bounds,
            color: ColorProp::Static(Color::BLACK),
            align: TextAlign::Leading,
            rotation: 0.0,
            label: None,
            flags: ItemFlags::default(),
            a11y: ItemA11yOverrides::default(),
            follow_text_scale: false,
            placed: RefCell::new(None),
        }
    }

    /// Opt the text into drag-to-move.
    pub fn draggable(mut self, draggable: bool) -> Self {
        self.flags.set(ItemFlags::IS_DRAGGABLE, draggable);
        self
    }

    /// Override the foreground colour. Accepts a plain [`Color`], a theme role,
    /// a `Signal<Color>`, or a `Signal<Role>` — resolved against the active
    /// theme at paint time.
    pub fn color(mut self, color: impl Into<ColorProp>) -> Self {
        self.color = color.into();
        self
    }

    /// Horizontal alignment within `local_bounds`. Default
    /// [`TextAlign::Leading`]. Needs a text backend to measure the text width;
    /// a headless canvas with no backend renders leading-aligned.
    pub fn align(mut self, align: TextAlign) -> Self {
        self.align = align;
        self
    }

    /// Rotate the text about the item's centre by `radians`. Default `0.0`
    /// (upright). Pair with `Signal::animate_to` on a driving signal for
    /// animated rotation, or set a fixed angle for a vertical axis title.
    pub fn rotation(mut self, radians: f32) -> Self {
        self.rotation = radians;
        self
    }

    /// Opt this text into the global accessibility text scale, so it grows with
    /// the app-wide "grow all text" setting. Off by default — the scene's own
    /// pan/zoom usually governs scene text size.
    pub fn follow_text_scale(mut self, follow: bool) -> Self {
        self.follow_text_scale = follow;
        self
    }

    /// Override the AT label (defaults to the current text content).
    pub fn label(mut self, label: impl Into<LocalizedString>) -> Self {
        let ls: LocalizedString = label.into();
        self.label = Some(ls);
        self
    }

    /// Measure the current text's single-line intrinsic size against `backend`
    /// at the authored [`TextStyle`](teksilo_tokens::TextStyle). Lets a
    /// consumer size a slot around a label (axis labels, value tags) before
    /// placing it. Does not apply the global text scale — measure at the
    /// authored size.
    pub fn measure(&self, backend: &mut dyn TextBackend) -> Size {
        let text = self.text.current();
        let style = teksilo_tokens::TextStyle::default();
        let layout = backend.layout_single_line(&text, &style, None);
        Size::new(layout.width, layout.height)
    }

    crate::items::item_a11y_builders!();
}

impl SceneItem for TextItem {
    fn local_bounds(&self) -> Rect {
        self.local_bounds
    }

    fn set_local_bounds(&mut self, bounds: Rect) {
        self.local_bounds = bounds;
    }

    fn paint(&self, canvas: &mut Canvas, ctx: &SceneItemPaintContext<'_>) {
        let text = self.text.current();
        let mut style = teksilo_tokens::TextStyle::default();
        if self.follow_text_scale {
            style.size *= ctx.text_scale;
        }
        let color = self.color.resolve(ctx.theme, ctx.enabled);
        let lb = self.local_bounds;

        // One `text_backend()` query serves both the alignment measure and the
        // paragraph-vs-plain draw choice. Scoped so the `&self` canvas borrow
        // is released before the `&mut self` draw calls below.
        let (has_backend, x_offset) = {
            let backend = canvas.text_backend();
            let has_backend = backend.is_some();
            // Horizontal alignment: shift the draw rect by the leftover width.
            // Needs a backend to measure; leading needs no measure at all.
            let x_offset = if self.align != TextAlign::Leading {
                backend
                    .map(|tb| {
                        let w = tb
                            .borrow_mut()
                            .layout_single_line(&text, &style, None)
                            .width;
                        align_offset(self.align, lb.width, w)
                    })
                    .unwrap_or(0.0)
            } else {
                0.0
            };
            (has_backend, x_offset)
        };
        let draw_rect = Rect::new(
            lb.x + x_offset,
            lb.y,
            (lb.width - x_offset).max(0.0),
            lb.height,
        );

        // Retain what is about to be drawn, for the accessibility pass.
        // The layout call is `draw_paragraph`'s own, argument for
        // argument, so the backend answers the draw from its layout
        // cache and the geometry AT reports is the geometry of the
        // glyphs on screen.
        // Cleared when there is no backend, or none that measures
        // characters: an item that painted nothing must not keep
        // advertising a previous frame's extents.
        {
            let placed = canvas.text_backend().and_then(|backend| {
                let layout = backend.borrow_mut().layout_paragraph(
                    &text,
                    &style,
                    (draw_rect.width + 0.5).max(0.0),
                    None,
                );
                layout.geometry.map(|geometry| PlacedText {
                    text: text.clone(),
                    geometry,
                    origin: draw_rect.origin(),
                })
            });
            *self.placed.borrow_mut() = placed;
        }

        // Rotation about the item's centre wraps the whole draw.
        //
        // This MUST compose in the item's **local** space: `paint_band` has
        // already pushed the item's scene→screen transform onto the canvas, and
        // `Canvas::translate`/`rotate` POST-multiply (they compose in *output*
        // space). Using them here would rotate about the screen origin offset by
        // a local-coordinate amount — the wrong pivot for any item that isn't at
        // the scene origin at zoom 1. `apply_transform` PRE-multiplies
        // (`new = t.then(current)`), so the rotate-about-centre matrix is applied
        // to local points *before* the outer transform, keeping the item's centre
        // a fixed point at any placement, pan, or zoom.
        let rotated = self.rotation.abs() > f32::EPSILON;
        if rotated {
            let cx = lb.x + lb.width * 0.5;
            let cy = lb.y + lb.height * 0.5;
            canvas.save();
            canvas.apply_transform(
                Transform2D::translate(-cx, -cy)
                    .then(&Transform2D::rotate(self.rotation))
                    .then(&Transform2D::translate(cx, cy)),
            );
        }
        if has_backend {
            canvas.draw_paragraph(&text, draw_rect, &style, color, None);
        } else {
            canvas.draw_text(&text, draw_rect, &style, color);
        }
        if rotated {
            canvas.restore();
        }
    }

    fn set_fill(&mut self, fill: Option<ColorProp>) -> AppearanceWrite<ColorProp> {
        // A text item's "fill" is its foreground colour — it always has one,
        // so a `None` (clear) is rejected. The colour it replaces is never
        // absent, so the accepted branch always reports `Some`.
        match fill {
            Some(c) => AppearanceWrite::replaced(std::mem::replace(&mut self.color, c)),
            None => AppearanceWrite::Refused,
        }
    }

    fn label(&self) -> Option<String> {
        self.label
            .as_ref()
            .map(|l| l.resolve_now())
            .or_else(|| Some(self.text.current()))
    }

    fn initial_flags(&self) -> ItemFlags {
        self.flags
    }

    fn access_subtree_mode(&self) -> AccessSubtreeMode {
        self.a11y.subtree_mode()
    }

    /// A `Role::Label` carrying `Role::TextRun` children — what makes the
    /// item reviewable by character, word and line, braille-routable, and
    /// trackable by a magnifier. The runs are direct children of the
    /// label: `accesskit_consumer` routes a run's update to its filtered
    /// parent, and any node between them that does not support text
    /// ranges makes every platform drop the text-change event.
    fn accessibility(&self, builder: &mut AccessNodeBuilder, ctx: &SceneItemA11yContext) {
        builder.set_role(Role::Label);

        // What AT announces: an `access_label` override, else the item's
        // own label override, else the painted text. The runs must spell
        // out that same string — a consumer derives the node's document
        // text from its runs, so any divergence is a place where what a
        // reader reviews and what it hears disagree.
        let painted = self.text.current();
        let announced = self
            .a11y
            .label
            .as_ref()
            .or(self.label.as_ref())
            .map(|l| l.resolve_now())
            .unwrap_or_else(|| painted.clone());

        let placed = self.placed.borrow();
        // Real extents only when they describe *this* string, under a mapping
        // a text run can express. A label override announces a different
        // string from the one that was measured, and an axis-aligned run of
        // character boxes cannot say where a rotated item's characters are.
        //
        // The *camera* is not part of this test. Runs are emitted in scene
        // coordinates like every other rectangle in the scene subtree, and the
        // view transform is declared once on the node above — so a rotated or
        // non-uniformly zoomed camera is expressed exactly rather than ruling
        // real geometry out. Only the item's own `scene_transform` has to be
        // expressible here, and it almost always is: a plain placement.
        let measured = placed
            .as_ref()
            .filter(|p| p.text == announced && self.rotation.abs() <= f32::EPSILON)
            .zip(uniform_scale(&ctx.local_to_scene));

        // Rects are absolute (scene-space) here, and the nested builder a
        // scene item is emitted through discards local ones — a run with
        // no box at all would empty `bounding_boxes()` for every range
        // touching it.
        let scaled;
        let source = match measured {
            Some((p, scale)) => {
                scaled = scale_geometry(&p.geometry, scale);
                TextRunSource::from_geometry(
                    &announced,
                    &scaled,
                    ctx.local_to_scene.apply_point(p.origin),
                    ctx.item_id.as_u64(),
                )
                .with_absolute_rects()
            }
            None => TextRunSource::flat(&announced, ctx.item_id.as_u64())
                .with_fallback_rect(ctx.scene_bounds)
                .with_absolute_rects(),
        };

        let emission = push_text_runs(builder, None, &source);
        builder.set_name(&emission.value);

        self.a11y.apply(builder);
    }

    fn register_bindings(&self, ctx: &mut BuildContext, view_id: WidgetId) {
        let registry = ctx.binding_registry();
        if let TextSource::Bound(signal) = &self.text {
            signal.bind_to(view_id, registry, BindingLevel::RepaintOnly);
        }
        if matches!(self.text, TextSource::Localized(_)) {
            ctx.locale_signal()
                .bind_to(view_id, ctx.binding_registry(), BindingLevel::RepaintOnly);
        }
        // A signal-/role-bound foreground colour repaints on change too.
        self.color
            .register_if_bound(view_id, ctx.binding_registry(), BindingLevel::RepaintOnly);
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use teksilo_canvas::{DrawCommand, Point};
    use teksilo_i18n::lit;

    /// Minimal fixed-metrics text backend (8px per char) for align / measure /
    /// rotation tests. Mirrors the stub in `view/tests/raster_scale_tests.rs`.
    #[derive(Default)]
    struct StubBackend {
        raster_scale: f32,
    }

    impl TextBackend for StubBackend {
        fn set_raster_scale(&mut self, raster_scale: f32) {
            self.raster_scale = raster_scale;
        }
        fn raster_scale(&self) -> f32 {
            self.raster_scale
        }
        fn layout_single_line(
            &mut self,
            text: &str,
            _style: &teksilo_tokens::TextStyle,
            _max_width: Option<f32>,
        ) -> teksilo_canvas::TextLayout {
            teksilo_canvas::TextLayout {
                width: text.chars().count() as f32 * 8.0,
                height: 16.0,
                ascent: 12.0,
                descent: 4.0,
                underline_offset: 1.0,
                underline_thickness: 1.0,
                layout_key: 1,
                line_count: 1,
                spans: Vec::new(),
                raster_scale: self.raster_scale,
                geometry: None,
            }
        }
        fn ensure_glyphs(
            &mut self,
            _layout: &teksilo_canvas::TextLayout,
        ) -> Vec<teksilo_canvas::GlyphQuad> {
            Vec::new()
        }
    }

    fn ctx<'a>(theme: &'a teksilo_core::styles::Theme) -> SceneItemPaintContext<'a> {
        SceneItemPaintContext::new(Transform2D::identity(), None, theme)
    }

    #[test]
    fn text_item_label_falls_back_to_text() {
        let item = TextItem::new(lit!("Hello"), Rect::new(0.0, 0.0, 100.0, 30.0));
        assert_eq!(SceneItem::label(&item).as_deref(), Some("Hello"));
    }

    #[test]
    fn follow_text_scale_defaults_off_and_opts_in() {
        let item = TextItem::new(lit!("Hi"), Rect::new(0.0, 0.0, 100.0, 30.0));
        assert!(!item.follow_text_scale);
        let opted = item.follow_text_scale(true);
        assert!(opted.follow_text_scale);
    }

    #[test]
    fn align_offset_centers_and_trails() {
        // #7: pure alignment maths.
        assert_eq!(align_offset(TextAlign::Leading, 100.0, 40.0), 0.0);
        assert_eq!(align_offset(TextAlign::Center, 100.0, 40.0), 30.0);
        assert_eq!(align_offset(TextAlign::Trailing, 100.0, 40.0), 60.0);
        // No negative offset when the text overflows.
        assert_eq!(align_offset(TextAlign::Center, 30.0, 40.0), 0.0);
    }

    #[test]
    fn measure_reports_single_line_size() {
        // #7: measure against a fixed-metrics backend.
        let item = TextItem::new(lit!("abcd"), Rect::new(0.0, 0.0, 200.0, 30.0));
        let mut backend = StubBackend::default();
        let size = item.measure(&mut backend);
        assert_eq!(size.width, 32.0); // 4 chars × 8px
        assert_eq!(size.height, 16.0);
    }

    #[test]
    fn rotation_emits_a_transform_command() {
        // #7: a rotated text item wraps its draw in a transform scope.
        let theme = teksilo_core::presets::intui::light();
        let item = TextItem::new(lit!("Title"), Rect::new(0.0, 0.0, 100.0, 20.0))
            .rotation(std::f32::consts::FRAC_PI_2);
        let mut canvas = Canvas::new();
        item.paint(&mut canvas, &ctx(&theme));
        let frame = canvas.into_render_frame();
        assert!(
            frame
                .draw_order
                .iter()
                .any(|c| matches!(c, DrawCommand::SetTransform(_))),
            "rotation must push a transform"
        );
    }

    #[test]
    fn rotation_pivots_about_the_item_centre() {
        // #7 regression guard: the rotation must keep the item's OWN centre a
        // fixed point. `Canvas::translate`/`rotate` post-multiply (compose in
        // output space), so the naive translate/rotate/translate idiom pivots
        // about the wrong point for any item not at the origin — this asserts
        // the composed transform actually fixes the centre.
        let theme = teksilo_core::presets::intui::light();
        // Deliberately off-origin bounds so a wrong pivot moves the centre.
        let lb = Rect::new(120.0, 60.0, 100.0, 40.0);
        let (cx, cy) = (lb.x + lb.width * 0.5, lb.y + lb.height * 0.5);

        for angle in [0.25_f32, std::f32::consts::FRAC_PI_2, 2.4] {
            let item = TextItem::new(lit!("Axis label"), lb).rotation(angle);
            let mut canvas = Canvas::new();
            item.paint(&mut canvas, &ctx(&theme));
            let frame = canvas.into_render_frame();
            let xform = frame
                .draw_order
                .iter()
                .find_map(|c| match c {
                    DrawCommand::SetTransform(t) => Some(*t),
                    _ => None,
                })
                .expect("rotation must push a transform");
            let centre = xform.apply_point(Point::new(cx, cy));
            assert!(
                (centre.x - cx).abs() < 0.01 && (centre.y - cy).abs() < 0.01,
                "centre must be a fixed point of the rotation (angle {angle}): \
                 expected ({cx}, {cy}), got ({}, {})",
                centre.x,
                centre.y
            );
        }
    }

    #[test]
    fn no_rotation_emits_no_transform_command() {
        let theme = teksilo_core::presets::intui::light();
        let item = TextItem::new(lit!("Title"), Rect::new(0.0, 0.0, 100.0, 20.0));
        let mut canvas = Canvas::new();
        item.paint(&mut canvas, &ctx(&theme));
        let frame = canvas.into_render_frame();
        assert!(
            !frame
                .draw_order
                .iter()
                .any(|c| matches!(c, DrawCommand::SetTransform(_))),
            "upright text must not push a transform"
        );
    }

    #[test]
    fn uniform_scale_accepts_translation_and_scale_and_nothing_else() {
        // The predicate that decides whether a text run can express the
        // mapping at all. Anything it lets through is reported as real
        // per-character geometry, so a false positive puts a magnifier
        // somewhere the text is not.
        assert_eq!(uniform_scale(&Transform2D::identity()), Some(1.0));
        assert_eq!(
            uniform_scale(&Transform2D::translate(10.0, -4.0)),
            Some(1.0)
        );
        assert_eq!(
            uniform_scale(&Transform2D::scale(2.0, 2.0).then(&Transform2D::translate(5.0, 5.0))),
            Some(2.0)
        );
        assert_eq!(uniform_scale(&Transform2D::scale(2.0, 3.0)), None);
        assert_eq!(uniform_scale(&Transform2D::scale(-1.0, -1.0)), None);
        assert_eq!(uniform_scale(&Transform2D::scale(0.0, 0.0)), None);
        assert_eq!(
            uniform_scale(&Transform2D::rotate(std::f32::consts::FRAC_PI_2)),
            None
        );
        assert_eq!(uniform_scale(&Transform2D::rotate(0.4)), None);
    }

    #[test]
    fn scale_geometry_multiplies_every_coordinate() {
        let mut backend = teksilo_canvas::MockTextBackend::new();
        let layout = backend.layout_single_line("ab", &teksilo_tokens::TextStyle::default(), None);
        let geometry = layout.geometry.expect("the mock measures characters");
        let scaled = scale_geometry(&geometry, 2.0);

        let before = &geometry.lines[0];
        let after = &scaled.lines[0];
        assert_eq!(after.rect[2], before.rect[2] * 2.0);
        assert_eq!(after.rect[3], before.rect[3] * 2.0);
        assert_eq!(after.baseline, before.baseline * 2.0);
        for (a, b) in after.segments[0]
            .characters
            .iter()
            .zip(&before.segments[0].characters)
        {
            assert_eq!(a.position, b.position * 2.0);
            assert_eq!(a.width, b.width * 2.0);
        }
        // Byte and character ranges index the text, not the screen.
        assert_eq!(after.byte_range, before.byte_range);
        assert_eq!(after.char_range, before.char_range);
    }

    #[test]
    fn paint_retains_the_layout_it_drew() {
        // `accessibility` has neither a text backend nor a draw rect;
        // paint is the one place both are in hand.
        let theme = teksilo_core::presets::intui::light();
        let item = TextItem::new(lit!("abcd"), Rect::new(4.0, 6.0, 100.0, 30.0));
        let backend: std::rc::Rc<std::cell::RefCell<dyn TextBackend>> = std::rc::Rc::new(
            std::cell::RefCell::new(teksilo_canvas::MockTextBackend::new()),
        );
        let mut canvas = Canvas::with_text_backend(backend);
        item.paint(&mut canvas, &ctx(&theme));

        let placed = item.placed.borrow();
        let placed = placed.as_ref().expect("a measuring backend was present");
        assert_eq!(placed.text, "abcd");
        assert_eq!(placed.origin, Point::new(4.0, 6.0));
        assert_eq!(placed.geometry.lines.len(), 1);
    }

    #[test]
    fn paint_without_a_measuring_backend_retains_nothing() {
        // A stale layout would keep advertising extents for glyphs that
        // are no longer on screen.
        let theme = teksilo_core::presets::intui::light();
        let item = TextItem::new(lit!("abcd"), Rect::new(0.0, 0.0, 100.0, 30.0));
        let mut canvas = Canvas::new();
        item.paint(&mut canvas, &ctx(&theme));
        assert!(item.placed.borrow().is_none());

        // A backend that measures but reports no geometry is the same
        // case: there is nothing to report per character.
        let backend: std::rc::Rc<std::cell::RefCell<dyn TextBackend>> =
            std::rc::Rc::new(std::cell::RefCell::new(StubBackend::default()));
        let mut canvas = Canvas::with_text_backend(backend);
        item.paint(&mut canvas, &ctx(&theme));
        assert!(item.placed.borrow().is_none());
    }

    #[test]
    fn set_fill_maps_to_foreground_colour() {
        // #2: the SceneItem fill hook sets the text colour; None is rejected.
        let mut item = TextItem::new(lit!("Hi"), Rect::new(0.0, 0.0, 100.0, 30.0));
        assert!(item.set_fill(Some(ColorProp::from(Color::RED))).accepted());
        assert!(!item.set_fill(None).accepted());
    }

    #[test]
    fn signal_colour_re_resolves() {
        // #2: a Signal<Color> foreground re-resolves each paint.
        let theme = teksilo_core::presets::intui::light();
        let sig = Signal::new(Color::RED);
        let item = TextItem::new(lit!("Hi"), Rect::new(0.0, 0.0, 100.0, 30.0)).color(sig.clone());
        // Paint twice with different signal values; both must succeed without
        // panicking and read the current value (visual assertion lives at the
        // view level where a real backend emits glyph colours).
        let mut c1 = Canvas::new();
        item.paint(&mut c1, &ctx(&theme));
        sig.set(Color::BLUE);
        let mut c2 = Canvas::new();
        item.paint(&mut c2, &ctx(&theme));
        assert_eq!(sig.get(), Color::BLUE);
    }
}