iris: a dp length unit, resolved against density; crisp glyphs at physical size

Iris asked for this 2026-09-06 (IRIS_TODO.md, "a third length kind beside
relative and pixels ... a unit resolved against the display's density at
layout time"): before this, a Len was abs (physical pixels) or rel/rest
(a fraction of the parent), and the only way to make a design size look
the same physical size on a denser display was a single global multiply
applied after layout -- which the previous commit found is also what
made text blurry.

Len gains a `dp` field, resolved against a `density: f32` (physical
pixels per dp) now carried on UiRenderState/Painter
(`UiRenderState::set_density`/`density()`, `Painter::density()`) and
threaded through every `apply_rest`/`to_uivec2` call site. `len_fns::dp`
/ `Len::dp` construct one, exactly parallel to the existing `abs`/`rel`/
`rest`. A bare number is unaffected (still `abs`, physical pixels) --
`dp` is opt-in.

Text: `TextBuffer::shape` now takes `density` and multiplies
`font_size`/`line_height` (and any span override) by it before handing
them to parley, so the size that reaches the shaper and the rasteriser
(`TextData::place`) is the display's real physical size -- the atlas
holds a bitmap at the resolution it is actually shown at, instead of a
low-resolution one stretched afterward. `GlyphKey.size` already keys on
the resolved `font_size`, so a cache entry is naturally per physical size
with no further change. `TextData` also carries its own `density` copy
for `TextEditCtx::layout` (cursor movement/hit-testing), which shapes
text from an input callback with no `Painter` to read it from.

`Span::gap` and `Padding`'s four sides move from bare `f32` to `Len`, so
`.gap(dp(4))`/`.pad(dp(10))` work the same way any other size does; a
bare number still means physical pixels, unchanged.

Migrated transcript-ui's non-text sizes (row gap/padding, composer
padding) and one example to the new unit, per IRIS_TODO.md's "done when"
list. Android's own density (`DisplayMetrics.density`) is wired to both
copies in `new_peer`; the winit backend has no per-monitor density wired
up yet and stays at the default (1.0).

docs/IRIS.md, docs/LAYOUT.md and IRIS_TODO.md updated next.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

iris/core/src/orientation/len.rs

@@ -9,7 +9,31 @@ pub struct Size {
 
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct Len {
+    /// Physical pixels -- a raw device pixel, unaffected by the display's
+    /// density. Rare to want directly (a hairline border is the usual
+    /// case); most sizes should be `dp` instead. See `dp`'s own doc for why
+    /// the two are kept separate rather than one field a caller has to
+    /// remember to pre-multiply.
     pub abs: f32,
+    /// Density-independent pixels -- Android's `dp` / CSS's reference pixel
+    /// (1 unit = 1/160in), resolved against the display's density at
+    /// layout time (`apply_rest`'s `density` parameter) rather than at the
+    /// point a widget is built, since density is a property of the device
+    /// this ends up running on, not of the widget tree. This is the unit
+    /// IRIS_TODO.md's "a density-independent length unit" item asked for,
+    /// 2026-09-06: before it existed, every size in the tree was `abs`
+    /// (physical pixels), and the only way to make a 16px design draw at
+    /// the right *size* on a denser display was a single global multiply
+    /// applied to the whole rendered scene after layout -- which is also
+    /// what made text blurry (RUST.md's P0 box, "blurry ... glyphs drawn
+    /// at logical size and stretched by the scale"): a glyph rasterised at
+    /// 16 physical px and then stretched 3x by that global multiply is a
+    /// 48px area sampled from a 16px bitmap. Resolving `dp` per-length at
+    /// layout time instead means the font size handed to the text shaper
+    /// is already the physical size (`16.0.dp() * 3.0`), so the glyph
+    /// atlas rasterises at the display's real resolution and nothing
+    /// downstream needs to stretch anything.
+    pub dp: f32,
     pub rel: f32,
     pub rest: f32,
 }
@@ -67,10 +91,10 @@ impl Size {
         }
     }
 
-    pub fn to_uivec2(self) -> UiVec2 {
+    pub fn to_uivec2(self, density: f32) -> UiVec2 {
         UiVec2 {
-            x: self.x.apply_rest(),
-            y: self.y.apply_rest(),
+            x: self.x.apply_rest(density),
+            y: self.y.apply_rest(density),
         }
     }
 
@@ -98,26 +122,43 @@ impl Size {
 impl Len {
     pub const ZERO: Self = Self {
         abs: 0.0,
+        dp: 0.0,
         rel: 0.0,
         rest: 0.0,
     };
 
     pub const REST: Self = Self {
         abs: 0.0,
+        dp: 0.0,
         rel: 0.0,
         rest: 1.0,
     };
 
-    pub fn apply_rest(&self) -> UiScalar {
+    /// Resolves to a `UiScalar`, folding `dp` into `abs` pixels against
+    /// `density` (physical pixels per dp -- 1.0 on a desktop or an
+    /// unscaled display, `content_scale` on Android; see `dp`'s field
+    /// doc). Every other component of `Len` is already resolution-
+    /// independent (`rel` is a fraction of the parent; `rest` becomes a
+    /// fraction too, below), so `density` only ever touches this one term.
+    pub fn apply_rest(&self, density: f32) -> UiScalar {
         UiScalar {
             rel: self.rel + if self.rest > 0.0 { 1.0 } else { 0.0 },
-            abs: self.abs,
+            abs: self.abs + self.dp * density,
         }
     }
 
     pub fn abs(abs: impl UiNum) -> Self {
         Self {
             abs: abs.to_f32(),
+            dp: 0.0,
+            rel: 0.0,
+            rest: 0.0,
+        }
+    }
+    pub fn dp(dp: impl UiNum) -> Self {
+        Self {
+            abs: 0.0,
+            dp: dp.to_f32(),
             rel: 0.0,
             rest: 0.0,
         }
@@ -125,6 +166,7 @@ impl Len {
     pub fn rel(rel: impl UiNum) -> Self {
         Self {
             abs: 0.0,
+            dp: 0.0,
             rel: rel.to_f32(),
             rest: 0.0,
         }
@@ -132,6 +174,7 @@ impl Len {
     pub fn rest(ratio: impl UiNum) -> Self {
         Self {
             abs: 0.0,
+            dp: 0.0,
             rel: 0.0,
             rest: ratio.to_f32(),
         }
@@ -144,6 +187,15 @@ pub mod len_fns {
     pub fn abs(abs: impl UiNum) -> Len {
         Len {
             abs: abs.to_f32(),
+            dp: 0.0,
+            rel: 0.0,
+            rest: 0.0,
+        }
+    }
+    pub fn dp(dp: impl UiNum) -> Len {
+        Len {
+            abs: 0.0,
+            dp: dp.to_f32(),
             rel: 0.0,
             rest: 0.0,
         }
@@ -151,6 +203,7 @@ pub mod len_fns {
     pub fn rel(rel: impl UiNum) -> Len {
         Len {
             abs: 0.0,
+            dp: 0.0,
             rel: rel.to_f32(),
             rest: 0.0,
         }
@@ -158,14 +211,15 @@ pub mod len_fns {
     pub fn rest(ratio: impl UiNum) -> Len {
         Len {
             abs: 0.0,
+            dp: 0.0,
             rel: 0.0,
             rest: ratio.to_f32(),
         }
     }
 }
 
-impl_op!(Len Add add; abs rel rest);
-impl_op!(Len Sub sub; abs rel rest);
+impl_op!(Len Add add; abs dp rel rest);
+impl_op!(Len Sub sub; abs dp rel rest);
 
 impl_op!(Size Add add; x y);
 impl_op!(Size Sub sub; x y);
@@ -187,6 +241,9 @@ impl std::fmt::Display for Len {
         if self.abs != 0.0 {
             write!(f, "{} abs;", self.abs)?;
         }
+        if self.dp != 0.0 {
+            write!(f, "{} dp;", self.dp)?;
+        }
         if self.rel != 0.0 {
             write!(f, "{} rel;", self.rel)?;
         }

iris/core/src/primitive/text.rs

@@ -66,6 +66,17 @@ pub struct TextData {
     pub layout_cx: LayoutContext<UiColor>,
     scale_cx: ScaleContext,
     pub atlas: GlyphAtlas,
+    /// Physical pixels per dp -- a second copy of
+    /// `UiRenderState::density`, kept here too because `TextEditCtx::layout`
+    /// (cursor movement and hit-testing, `widget/text/edit.rs`) shapes text
+    /// from an event callback that has a `TextData` but no `Painter`, so it
+    /// has nowhere else to read the display's density from. Both copies are
+    /// set together, from the one place either backend learns the real
+    /// value (`android::view::new_peer`); this is the same accepted
+    /// duplication as `AndroidRenderer::content_scale`; a single source of
+    /// truth would mean carrying a `Painter` (or output size) into every
+    /// input handler for the sake of one field.
+    pub density: f32,
 }
 
 impl Default for TextData {
@@ -75,6 +86,7 @@ impl Default for TextData {
             layout_cx: LayoutContext::new(),
             scale_cx: ScaleContext::new(),
             atlas: GlyphAtlas::default(),
+            density: 1.0,
         };
         data.register_bundled_fonts();
         data
@@ -363,7 +375,7 @@ pub struct TextBuffer {
     /// `set_spans` forces `shaped` to `None` directly, the same way `edit`
     /// does, since spans change far less often than a naive equality check
     /// on the whole `Vec` would cost to compute every frame.
-    shaped: Option<(TextAttrs, Option<f32>)>,
+    shaped: Option<(TextAttrs, Option<f32>, f32)>,
 }
 
 impl TextBuffer {
@@ -419,19 +431,42 @@ impl TextBuffer {
         Vec2::new(self.layout.width(), self.layout.height())
     }
 
-    /// Lay the text out, unless it is already laid out for these attributes and
-    /// this width.
-    pub fn shape(&mut self, data: &mut TextData, attrs: &TextAttrs, width: Option<f32>) {
-        if self.shaped.as_ref() == Some(&(attrs.clone(), width)) {
+    /// Lay the text out, unless it is already laid out for these
+    /// attributes, this width and this density.
+    ///
+    /// **`attrs.font_size`/`line_height` and every span's own `font_size`
+    /// are density-independent (dp) units, multiplied by `density` here --
+    /// the one place text crosses from the widget tree's dp sizes into the
+    /// physical pixels the shaper and rasteriser (`TextData::place`) both
+    /// then work in.** This is what makes glyphs sharp on a dense display:
+    /// before this existed, `font_size` was already a physical-pixel value
+    /// (RUST.md's P0 box's global-scale stopgap resolved density by
+    /// stretching the whole rendered frame afterward instead), so a glyph
+    /// was rasterised small and then upscaled by whatever the display's
+    /// scale factor was -- exactly the blur Iris's report described.
+    /// Multiplying here instead means the font size hitting `ScaleContext`
+    /// in `place` below is already the display's real physical size, so
+    /// the atlas holds a bitmap at the resolution it is actually shown at.
+    /// `GlyphKey.size` already keys on that resolved `font_size`
+    /// (`(font_size * 16.0).round()`), so a cache entry is naturally per
+    /// physical size with no change needed there.
+    pub fn shape(
+        &mut self,
+        data: &mut TextData,
+        attrs: &TextAttrs,
+        width: Option<f32>,
+        density: f32,
+    ) {
+        if self.shaped.as_ref() == Some(&(attrs.clone(), width, density)) {
             return;
         }
         let mut builder = data
             .layout_cx
             .ranged_builder(&mut data.font_cx, &self.text, 1.0, true);
         builder.push_default(StyleProperty::FontFamily(attrs.family.family()));
-        builder.push_default(StyleProperty::FontSize(attrs.font_size));
+        builder.push_default(StyleProperty::FontSize(attrs.font_size * density));
         builder.push_default(StyleProperty::LineHeight(LineHeight::Absolute(
-            attrs.line_height,
+            attrs.line_height * density,
         )));
         builder.push_default(StyleProperty::Brush(attrs.color));
         for span in &self.spans {
@@ -443,7 +478,7 @@ impl TextBuffer {
                 builder.push(StyleProperty::FontFamily(family.family()), range.clone());
             }
             if let Some(size) = span.font_size {
-                builder.push(StyleProperty::FontSize(size), range.clone());
+                builder.push(StyleProperty::FontSize(size * density), range.clone());
             }
             if span.bold {
                 builder.push(StyleProperty::FontWeight(FontWeight::BOLD), range.clone());
@@ -459,7 +494,7 @@ impl TextBuffer {
         self.layout.break_all_lines(width);
         self.layout
             .align(Alignment::Start, AlignmentOptions::default());
-        self.shaped = Some((attrs.clone(), width));
+        self.shaped = Some((attrs.clone(), width, density));
     }
 }
 
@@ -576,8 +611,9 @@ impl TextData {
         attrs: &TextAttrs,
         width: Option<f32>,
         textures: &mut Textures,
+        density: f32,
     ) -> RenderedText {
-        buffer.shape(self, attrs, width);
+        buffer.shape(self, attrs, width, density);
         let glyphs = self.place(buffer, textures);
         RenderedText {
             glyphs: std::sync::Arc::new(glyphs),

iris/core/src/ui/painter.rs

@@ -165,8 +165,10 @@ impl<'a> Painter<'a> {
         attrs: &TextAttrs,
         width: Option<f32>,
     ) -> RenderedText {
+        let density = self.state.density;
         let ui = self.rsc.ui_mut();
-        ui.text.render(buffer, attrs, width, &mut ui.textures)
+        ui.text
+            .render(buffer, attrs, width, &mut ui.textures, density)
     }
 
     /// Draw a laid-out string: one quad per glyph, all sampling the atlas.
@@ -210,6 +212,12 @@ impl<'a> Painter<'a> {
         self.state.output_size
     }
 
+    /// Physical pixels per `dp` -- see `UiRenderState::density`'s field
+    /// doc. What `Len::dp`'s `apply_rest` call resolves against.
+    pub fn density(&self) -> f32 {
+        self.state.density
+    }
+
     pub fn px_size(&mut self) -> Vec2 {
         self.region.size().to_abs(self.state.output_size)
     }

iris/core/src/ui/render_state.rs

@@ -9,6 +9,12 @@ pub struct UiRenderState {
     pub active: HashMap<WidgetId, ActiveData>,
     pub layers: PrimitiveLayers,
     pub(super) output_size: Vec2,
+    /// Physical pixels per `dp` -- see `Len::dp`'s field doc. `1.0` (an
+    /// unscaled display) until a backend that knows its own density calls
+    /// `set_density` (Android's `content_scale`, read at `surface_changed`
+    /// time); the winit backend has no analogous per-monitor value wired up
+    /// yet and stays at the default.
+    pub(super) density: f32,
 
     old_root: Option<WidgetId>,
     resized: bool,
@@ -35,6 +41,7 @@ impl UiRenderState {
             active: Default::default(),
             layers: Default::default(),
             output_size: Vec2::ZERO,
+            density: 1.0,
             old_root: None,
             resized: false,
             draw_started: Default::default(),
@@ -60,6 +67,20 @@ impl UiRenderState {
         self.resized = true;
     }
 
+    /// Sets the physical-pixels-per-dp ratio every `Len::dp` in the tree
+    /// resolves against from the next layout pass on -- see `density`'s
+    /// field doc. Not folded into `resize` because the two change on
+    /// different triggers (a surface resize on every rotation or keyboard
+    /// open; a density change only if the app follows the display to a
+    /// different screen, which Android surfaces separately).
+    pub fn set_density(&mut self, density: f32) {
+        self.density = density;
+    }
+
+    pub fn density(&self) -> f32 {
+        self.density
+    }
+
     pub fn update<'a>(&mut self, root: impl Into<Option<&'a StrongWidget>>, rsc: &mut dyn UiRsc) {
         // safety mechanism for memory leaks; might wanna return a result instead so user can
         // decide whether to panic or not
@@ -311,7 +332,7 @@ impl UiRenderState {
         };
         let from = active
             .size
-            .to_uivec2()
+            .to_uivec2(self.density)
             .align(RegionAlign::TOP_LEFT)
             .within(&active.region);
         let slot = active.move_slot;