iris is the framework alone; the app is one crate in app-rust/

Iris: "the organization of the rust rewrite is a mess right now... there
shouldn't be anything related to the app inside of iris. Iris is supposed
to be the UI framework alone." And, on the crate count: "I'm confused why
the app only code needs more than one crate though."

Nine cargo workspaces become three, and the port's project code -- which
sat in five places, four of them inside the framework -- becomes one crate,
`ai-app`, in `app-rust/`:

  client-core                -> app-rust/src/client
  iris/transcript-ui         -> app-rust/src/ui
  iris/transcript-fixture    -> app-rust/src/ui/fixture.rs + tests/ + touch/
  iris/desktop-app           -> app-rust/src/desktop + src/bin_desktop.rs
  iris/android-app           -> app-rust/src/android + android-project/
  android-shell              -> app-rust/src/shell

iris/ keeps core, macro, the iris crate, tabs-ui and rig-input, and now
mentions no session, transcript, setup or server anywhere.

Only two of the old splits had a reason that survived reading. event-model
stays a crate at the repo root because server/ depends on it too, so a
crate is what makes the backend and the app agree by construction. The two
Android .so names looked like a hard constraint -- a package produces one
library artifact -- until P2 turned out to already plan merging those two
Android apps into one; both faces now come out of libai_app.so, picked
apart by features so `--no-default-features --features shell` keeps wgpu,
parley and iris out of the Compose app's APK. docs/RUST.md's "One app
crate" has the rest, including what each remaining feature is for.

DECISIONS.md and SUBAGENTS.md move into docs/ with everything else.

Verified: ./run-tests.sh and `cd iris && cargo test` green, clippy and fmt
clean in all five workspaces, `cargo ndk -t x86_64` links libai_app.so,
build-apk.sh produces an APK that installs and launches on this checkout's
emulator (Gl ... virgl, as expected), and the phone-sized headless
screenshot renders the transcript unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

core/src/primitive/text.rs

@@ -1,60 +1,444 @@
-use crate::{Align, RegionAlign, TextureHandle, Textures, UiColor, util::Vec2};
-use cosmic_text::{
-    Attrs, AttrsList, Buffer, CacheKey, Color, Family, FontSystem, Metrics, Placement, SwashCache,
-    SwashContent,
+use crate::{Align, GlyphAtlas, GlyphKey, PlacedGlyph, RegionAlign, Textures, UiColor, util::Vec2};
+use parley::{
+    Alignment, AlignmentOptions, FontContext, FontFamily, FontFamilyName, FontStyle, FontWeight,
+    GenericFamily, Layout, LayoutContext, LineHeight, PositionedLayoutItem, StyleProperty,
+    fontique::Blob,
+};
+use std::ops::Range;
+use std::sync::Arc;
+use swash::{
+    FontRef,
+    scale::{Render, ScaleContext, Source, StrikeWith},
+    zeno::{Format, Vector},
 };
-use image::{DynamicImage, GenericImageView, RgbaImage};
-use std::simd::{Simd, num::SimdUint};
 
-/// TODO: properly wrap this
-pub mod text_lib {
-    pub use cosmic_text::*;
+/// The icon font iris ships: the Nerd Fonts Symbols **Mono** subset built
+/// by `iris/core/build-icon-font.sh`, holding only the codepoints
+/// `crate::icon` names (992 bytes for three glyphs today).
+///
+/// This is the one font bundled here, and it is not a text font: body and
+/// monospace text still come from the platform's own collection
+/// (DECISIONS.md, 2026-09-07). An icon is the opposite case -- a small,
+/// closed set of codepoints no system font is guaranteed to have -- which
+/// is the same division the Compose app makes.
+const NERD_ICONS: &[u8] = include_bytes!("../../assets/fonts/nerd_icons.ttf");
+
+/// What starting up found about text rendering, for the on-screen
+/// Diagnostics page and the one startup log line (RUST.md's P0 box, "log
+/// once at startup ... the number of font families found, the default
+/// family resolved"). Built once by `TextData::font_diagnostics` --
+/// `Default::default` still exists for callers (tests, examples) that
+/// don't need the report.
+#[derive(Clone, Debug)]
+pub struct FontDiagnostics {
+    /// `Collection::family_names().count()` after registering the bundled
+    /// fonts -- system families plus the two bundled ones.
+    pub families_found: usize,
+    /// The family `GenericFamily::SansSerif` resolves to first -- the
+    /// bundled "Noto Sans" unless registration itself failed.
+    pub default_family: Option<String>,
+    /// The family `GenericFamily::Monospace` resolves to first.
+    pub default_mono_family: Option<String>,
+    /// One resolved family name per style axis this crate actually uses
+    /// (`SpanStyle::bold`/`italic`), so a report can say plainly whether a
+    /// bold/italic request is landing on a real face rather than being
+    /// silently absorbed by whatever the sans-serif default resolves to
+    /// for every weight (RUST.md's P0 box, "bold words render as blank
+    /// gaps" -- a family that resolves but has no distinct bold face is
+    /// exactly what produced that).
+    pub regular_resolved: Option<String>,
+    pub bold_resolved: Option<String>,
+    pub italic_resolved: Option<String>,
+    pub mono_resolved: Option<String>,
+    /// The family the bundled icon font registered under, or `None` if
+    /// registering it failed. Reported rather than assumed: it is the one
+    /// font iris ships, so `None` is a broken build and must not look
+    /// like a device that happens to lack a face.
+    pub icon_family: Option<String>,
 }
 
+/// Everything text needs that outlives one string: the font collection, the
+/// layout scratch space, the glyph rasteriser and the atlas they fill.
 pub struct TextData {
-    pub font_system: FontSystem,
-    pub swash_cache: SwashCache,
-    glyph_cache: Vec<(Placement, CacheKey, Color)>,
+    pub font_cx: FontContext,
+    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,
+    /// The family name [`NERD_ICONS`] registered under, which is what
+    /// [`Family::Icons`] resolves to. `None` only if registering the
+    /// bundled font failed, which is a broken build rather than a
+    /// platform difference -- said in the startup diagnostics rather than
+    /// silently drawn as tofu.
+    pub icon_family: Option<String>,
 }
 
 impl Default for TextData {
+    /// Text comes entirely from the platform's own font collection --
+    /// `FontContext::new()` builds a `fontique::Collection` with
+    /// `CollectionOptions::system_fonts` on by default, which is real
+    /// discovery on both targets this crate ships on: Android's backend
+    /// parses `/system/fonts` and `/system/etc/fonts.xml` and maps
+    /// `SansSerif`/`SystemUi` to `["Roboto Flex", "Roboto", "Noto Sans"]`
+    /// and `Monospace` to the platform's `"monospace"` alias; the desktop
+    /// build's backend is fontconfig. No font is bundled or registered
+    /// here -- see DECISIONS.md's 2026-09-07 entry for why (matching what
+    /// the Compose app does: it takes body/monospace text from
+    /// `FontFamily.Default`/`FontFamily.Monospace`, i.e. Android's Roboto
+    /// and its platform monospace face, and ships no text font of its own,
+    /// only its committed Nerd Fonts icon subset for fixed glyphs).
     fn default() -> Self {
+        let mut font_cx = FontContext::new();
+        patch_android_monospace(&mut font_cx);
+        let icon_family = register_icon_font(&mut font_cx);
         Self {
-            font_system: FontSystem::new(),
-            swash_cache: SwashCache::new(),
-            glyph_cache: Default::default(),
+            font_cx,
+            layout_cx: LayoutContext::new(),
+            scale_cx: ScaleContext::new(),
+            atlas: GlyphAtlas::default(),
+            density: 1.0,
+            icon_family,
         }
     }
 }
 
-#[derive(Clone, Copy)]
+/// Registers the bundled icon font as an ordinary named family and
+/// answers the name it registered under -- read back from the collection
+/// rather than written down here, so the name cannot drift from the file
+/// (`build-icon-font.sh` takes whatever face the Nerd Fonts release
+/// ships).
+///
+/// A *named* family rather than a generic one: nothing should fall back
+/// to it for ordinary text, and nothing should fall back out of it for an
+/// icon -- a system face that happens to have one of these codepoints
+/// would draw somebody else's picture.
+fn register_icon_font(font_cx: &mut FontContext) -> Option<String> {
+    let blob = Blob::new(Arc::new(NERD_ICONS));
+    let id = font_cx
+        .collection
+        .register_fonts(blob, None)
+        .into_iter()
+        .map(|(id, _)| id)
+        .next()?;
+    font_cx.collection.family_name(id).map(str::to_string)
+}
+
+/// Works around `fontique` 0.11.1's Android backend never resolving
+/// `GenericFamily::Monospace` (confirmed against
+/// `fontique-0.11.1/src/backend/android.rs`'s `SystemFonts::new`, and still
+/// present on `linebender/parley`'s `main` as of 2026-09-07, so there is no
+/// released fix to bump to yet -- see DECISIONS.md's 2026-09-07 entry,
+/// "Platform fonts," for the full account). Two bugs stack, not one:
+/// `DEFAULT_GENERIC_FAMILIES` looks up the name `"monospace"` *before*
+/// `fonts.xml` is parsed into that same name map, and even after parsing,
+/// AOSP's `fonts.xml` names it with a `<family name="monospace">` element
+/// (not an `<alias>`) whose `<font>` children the backend's own parser
+/// does not read (a `TODO` in that match arm) -- so the name gets a
+/// `FamilyId` with no font data behind it, and `family_by_name("monospace")`
+/// comes back empty too. Confirmed on this checkout's emulator: `adb pull
+/// /system/etc/fonts.xml` shows
+/// `<family name="monospace"><font weight="400"
+/// style="normal">DroidSansMono.ttf</font></family>` with no matching
+/// alias.
+///
+/// So this reads `fonts.xml` itself (already on-device, already the
+/// authority Compose's own `Typeface.MONOSPACE` resolves through) for the
+/// filename that declaration names, then finds which of fontique's
+/// *actually* scanned families (from `/system/fonts`, which do carry real
+/// font data, just under whatever name the font's own metadata gives it --
+/// "Droid Sans Mono" here, but that name is never hardcoded) owns a font
+/// file with that name, and registers that family as the `Monospace`
+/// generic the way the backend itself would have if its parser had reified
+/// the declaration. A no-op if the family is somehow already resolved
+/// (future fontique) or nothing matches (no `fonts.xml`, e.g. a headless
+/// test, or a device that names it some other way).
+#[cfg(target_os = "android")]
+fn patch_android_monospace(font_cx: &mut FontContext) {
+    use parley::fontique::SourceKind;
+
+    let already_resolved = font_cx
+        .collection
+        .generic_families(GenericFamily::Monospace)
+        .next()
+        .is_some();
+    if already_resolved {
+        return;
+    }
+    let Some(target_file) = android_monospace_font_filename() else {
+        return;
+    };
+    let names: Vec<String> = font_cx
+        .collection
+        .family_names()
+        .map(str::to_string)
+        .collect();
+    for name in names {
+        let Some(id) = font_cx.collection.family_id(&name) else {
+            continue;
+        };
+        let Some(info) = font_cx.collection.family(id) else {
+            continue;
+        };
+        let Some(font) = info.default_font() else {
+            continue;
+        };
+        let SourceKind::Path(path) = font.source().kind() else {
+            continue;
+        };
+        if path.file_name().and_then(|f| f.to_str()) == Some(target_file.as_str()) {
+            font_cx
+                .collection
+                .append_generic_families(GenericFamily::Monospace, std::iter::once(id));
+            return;
+        }
+    }
+}
+
+/// Reads the font filename `fonts.xml` names for its `"monospace"` family
+/// (e.g. `"DroidSansMono.ttf"`), by plain substring search rather than a
+/// real XML parser -- a new dependency for one well-known, stable AOSP file
+/// whose structure fontique itself already parses with a full parser one
+/// module over. Not a general XML reader; assumes the file has exactly one
+/// `<family name="monospace">` element with at least one `<font>` child,
+/// which is the format on every AOSP `fonts.xml` this was checked against.
+#[cfg(target_os = "android")]
+fn android_monospace_font_filename() -> Option<String> {
+    let android_root = std::env::var("ANDROID_ROOT").unwrap_or_else(|_| "/system".to_string());
+    let xml =
+        std::fs::read_to_string(std::path::Path::new(&android_root).join("etc/fonts.xml")).ok()?;
+    let family_start = xml.find("<family name=\"monospace\">")?;
+    let block = &xml[family_start..];
+    let block = &block[..block.find("</family>")?];
+    let font_tag = block.find("<font")?;
+    let after_tag = &block[font_tag..];
+    let content_start = after_tag.find('>')? + 1;
+    let content = &after_tag[content_start..];
+    let filename = content[..content.find('<')?].trim();
+    (!filename.is_empty()).then(|| filename.to_string())
+}
+
+#[cfg(not(target_os = "android"))]
+fn patch_android_monospace(_font_cx: &mut FontContext) {}
+
+impl TextData {
+    /// [`Family::Icons`] as the name the bundled font actually registered
+    /// under; everything else unchanged.
+    ///
+    /// Cloned rather than borrowed because the caller needs it while the
+    /// layout builder holds `&mut self` -- a `String` per shaped icon run,
+    /// paid only when the layout is rebuilt.
+    pub fn resolve_family(&self, family: &Family) -> Family {
+        match family {
+            Family::Icons => self
+                .icon_family
+                .clone()
+                .map_or(Family::Icons, Family::Named),
+            other => other.clone(),
+        }
+    }
+
+    /// Builds the startup report -- see `FontDiagnostics`. Queries the
+    /// collection directly (`fontique::Query`) rather than shaping a real
+    /// string, since all that's needed is which family each axis lands on.
+    pub fn font_diagnostics(&mut self) -> FontDiagnostics {
+        use parley::fontique::{Attributes, FontWidth, QueryStatus};
+        let families_found = self.font_cx.collection.family_names().count();
+        let default_family_id = self
+            .font_cx
+            .collection
+            .generic_families(GenericFamily::SansSerif)
+            .next();
+        let default_family = default_family_id
+            .and_then(|id| self.font_cx.collection.family_name(id).map(str::to_string));
+        let default_mono_family_id = self
+            .font_cx
+            .collection
+            .generic_families(GenericFamily::Monospace)
+            .next();
+        let default_mono_family = default_mono_family_id
+            .and_then(|id| self.font_cx.collection.family_name(id).map(str::to_string));
+
+        // Resolves the family a (generic family, weight, style) query lands
+        // on, without holding the `Query`'s borrow of `collection` across
+        // the `family_name` lookup that needs it back -- the `FamilyId` is
+        // captured out of the closure first, then looked up once `query`
+        // (and its borrow) has been dropped.
+        let mut resolve_family =
+            |generic: GenericFamily, weight: FontWeight, style: FontStyle| -> Option<String> {
+                let mut family_id = None;
+                {
+                    let mut query = self
+                        .font_cx
+                        .collection
+                        .query(&mut self.font_cx.source_cache);
+                    query.set_families([generic]);
+                    query.set_attributes(Attributes {
+                        width: FontWidth::NORMAL,
+                        style,
+                        weight,
+                    });
+                    query.matches_with(|font| {
+                        family_id = Some(font.family.0);
+                        QueryStatus::Stop
+                    });
+                }
+                family_id.and_then(|id| self.font_cx.collection.family_name(id).map(str::to_string))
+            };
+
+        let regular_resolved = resolve_family(
+            GenericFamily::SansSerif,
+            FontWeight::NORMAL,
+            FontStyle::Normal,
+        );
+        let bold_resolved = resolve_family(
+            GenericFamily::SansSerif,
+            FontWeight::BOLD,
+            FontStyle::Normal,
+        );
+        let italic_resolved = resolve_family(
+            GenericFamily::SansSerif,
+            FontWeight::NORMAL,
+            FontStyle::Italic,
+        );
+        let mono_resolved = resolve_family(
+            GenericFamily::Monospace,
+            FontWeight::NORMAL,
+            FontStyle::Normal,
+        );
+
+        FontDiagnostics {
+            families_found,
+            default_family,
+            default_mono_family,
+            regular_resolved,
+            bold_resolved,
+            italic_resolved,
+            mono_resolved,
+            icon_family: self.icon_family.clone(),
+        }
+    }
+}
+
+/// Which family to ask for. Kept as an owned name rather than parley's
+/// borrowed `FontFamily<'_>` so that a widget can hold one without a lifetime.
+#[derive(Clone, PartialEq)]
+pub enum Family {
+    SansSerif,
+    Serif,
+    Monospace,
+    /// The bundled icon font -- see [`crate::icon`] for what is in it.
+    /// Named as an intention rather than as a font name because only
+    /// [`TextData`] knows what the file registered as; it resolves this
+    /// during shaping ([`TextData::resolve_family`]).
+    Icons,
+    Named(String),
+}
+
+impl Family {
+    fn family(&self) -> FontFamily<'_> {
+        let name = match self {
+            Self::SansSerif => FontFamilyName::Generic(GenericFamily::SansSerif),
+            Self::Serif => FontFamilyName::Generic(GenericFamily::Serif),
+            Self::Monospace => FontFamilyName::Generic(GenericFamily::Monospace),
+            // Only reachable if `resolve_family` did not run, which no
+            // shaping path allows -- and sans-serif is the honest answer
+            // for a build whose icon font failed to register: the reader
+            // gets the platform's own tofu rather than a wrong picture.
+            Self::Icons => FontFamilyName::Generic(GenericFamily::SansSerif),
+            Self::Named(name) => FontFamilyName::Named(name.as_str().into()),
+        };
+        FontFamily::Single(name)
+    }
+}
+
+/// One styled run inside a `TextBuffer`, overriding `TextAttrs`' base style
+/// over `range` (a byte range into the buffer's text). Every field is
+/// optional so a span only says what it changes -- e.g. a link span sets
+/// `color` and `underline` and leaves weight/family at the paragraph's own
+/// default. This is I5's answer to RUST.md's inline-rich-text ceiling
+/// (`masonry/src/widgets/text_area.rs`'s `StyleSet` is one style for the
+/// whole editor, with `// TODO: RichTextInput` beside it): parley's own
+/// `RangedBuilder::push` already takes a style and a range, so per-span
+/// bold/italic/monospace/colour/underline only needed plumbing this struct
+/// through to it and giving each glyph its own colour at draw time (see
+/// `PlacedGlyph::color` and `TextData::place` below) instead of the one
+/// `RenderedText::color` every glyph used to share.
+#[derive(Clone, PartialEq)]
+pub struct SpanStyle {
+    pub range: Range<usize>,
+    pub color: Option<UiColor>,
+    pub family: Option<Family>,
+    /// Overrides `TextAttrs::font_size` for just this range -- what lets a
+    /// heading inside a transcript row's single `TextEdit` be bigger than
+    /// the paragraph text around it, so a whole markdown-folded row (block
+    /// and inline styling both) can stay one selectable text buffer instead
+    /// of one widget per block.
+    pub font_size: Option<f32>,
+    pub bold: bool,
+    pub italic: bool,
+    pub underline: bool,
+}
+
+impl SpanStyle {
+    pub fn new(range: Range<usize>) -> Self {
+        Self {
+            range,
+            color: None,
+            family: None,
+            font_size: None,
+            bold: false,
+            italic: false,
+            underline: false,
+        }
+    }
+    pub fn color(mut self, color: UiColor) -> Self {
+        self.color = Some(color);
+        self
+    }
+    pub fn family(mut self, family: Family) -> Self {
+        self.family = Some(family);
+        self
+    }
+    pub fn font_size(mut self, size: f32) -> Self {
+        self.font_size = Some(size);
+        self
+    }
+    pub fn bold(mut self) -> Self {
+        self.bold = true;
+        self
+    }
+    pub fn italic(mut self) -> Self {
+        self.italic = true;
+        self
+    }
+    pub fn underline(mut self) -> Self {
+        self.underline = true;
+        self
+    }
+}
+
+#[derive(Clone, PartialEq)]
 pub struct TextAttrs {
     pub color: UiColor,
     pub font_size: f32,
     pub line_height: f32,
-    pub family: Family<'static>,
+    pub family: Family,
     pub wrap: bool,
     /// inner alignment of text region (within where it's drawn)
     pub align: RegionAlign,
 }
 
-impl TextAttrs {
-    pub fn apply(&self, font_system: &mut FontSystem, buf: &mut Buffer, width: Option<f32>) {
-        buf.set_metrics_and_size(
-            font_system,
-            Metrics::new(self.font_size, self.line_height),
-            width,
-            None,
-        );
-        let attrs = Attrs::new().family(self.family);
-        let list = AttrsList::new(&attrs);
-        for line in &mut buf.lines {
-            line.set_attrs_list(list.clone());
-        }
-    }
-}
-
-pub type TextBuffer = Buffer;
+pub const LINE_HEIGHT_MULT: f32 = 1.1;
 
 impl Default for TextAttrs {
     fn default() -> Self {
@@ -70,122 +454,324 @@ impl Default for TextAttrs {
     }
 }
 
-pub const LINE_HEIGHT_MULT: f32 = 1.1;
+/// A string together with its laid-out form.
+///
+/// The text and the layout live in one place because parley's `Layout` borrows
+/// nothing but is only meaningful against the string it was built from: keeping
+/// them apart is how they get out of step.
+pub struct TextBuffer {
+    text: String,
+    layout: Layout<UiColor>,
+    spans: Vec<SpanStyle>,
+    /// What the current layout was built for, so `shape` can decline to redo
+    /// work that would come out the same. Spans are not part of this key --
+    /// `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>, f32)>,
+}
+
+impl TextBuffer {
+    pub fn new(text: impl Into<String>) -> Self {
+        Self {
+            text: text.into(),
+            layout: Layout::new(),
+            spans: Vec::new(),
+            shaped: None,
+        }
+    }
+
+    /// Replace this buffer's per-range style overrides (I5's rich text --
+    /// see `SpanStyle`). Invalidates the layout unconditionally, mirroring
+    /// `set_text`.
+    pub fn set_spans(&mut self, spans: Vec<SpanStyle>) {
+        self.spans = spans;
+        self.shaped = None;
+    }
+
+    pub fn new_empty() -> Self {
+        Self::new("")
+    }
+
+    pub fn text(&self) -> &str {
+        &self.text
+    }
+
+    pub fn layout(&self) -> &Layout<UiColor> {
+        &self.layout
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.text.is_empty()
+    }
+
+    pub fn set_text(&mut self, text: impl Into<String>) {
+        let text = text.into();
+        if text != self.text {
+            self.text = text;
+            self.shaped = None;
+        }
+    }
+
+    /// Edit the string in place; invalidates the layout unconditionally, since
+    /// the caller is assumed to have changed something.
+    pub fn edit(&mut self) -> &mut String {
+        self.shaped = None;
+        &mut self.text
+    }
+
+    pub fn size(&self) -> Vec2 {
+        Vec2::new(self.layout.width(), self.layout.height())
+    }
+
+    /// 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;
+        }
+        // Resolved before the builder borrows `data`: `Family::Icons`
+        // names an intention, and the name behind it lives on `TextData`.
+        let base_family = data.resolve_family(&attrs.family);
+        let span_families: Vec<Option<Family>> = self
+            .spans
+            .iter()
+            .map(|span| span.family.as_ref().map(|f| data.resolve_family(f)))
+            .collect();
+        let mut builder = data
+            .layout_cx
+            .ranged_builder(&mut data.font_cx, &self.text, 1.0, true);
+        builder.push_default(StyleProperty::FontFamily(base_family.family()));
+        builder.push_default(StyleProperty::FontSize(attrs.font_size * density));
+        builder.push_default(StyleProperty::LineHeight(LineHeight::Absolute(
+            attrs.line_height * density,
+        )));
+        builder.push_default(StyleProperty::Brush(attrs.color));
+        for (span, family) in self.spans.iter().zip(&span_families) {
+            let range = span.range.clone();
+            if let Some(color) = span.color {
+                builder.push(StyleProperty::Brush(color), range.clone());
+            }
+            if let Some(family) = family {
+                builder.push(StyleProperty::FontFamily(family.family()), range.clone());
+            }
+            if let Some(size) = span.font_size {
+                builder.push(StyleProperty::FontSize(size * density), range.clone());
+            }
+            if span.bold {
+                builder.push(StyleProperty::FontWeight(FontWeight::BOLD), range.clone());
+            }
+            if span.italic {
+                builder.push(StyleProperty::FontStyle(FontStyle::Italic), range.clone());
+            }
+            if span.underline {
+                builder.push(StyleProperty::Underline(true), range.clone());
+            }
+        }
+        builder.build_into(&mut self.layout, &self.text);
+        self.layout.break_all_lines(width);
+        self.layout
+            .align(Alignment::Start, AlignmentOptions::default());
+        self.shaped = Some((attrs.clone(), width, density));
+    }
+}
 
 impl TextData {
-    pub fn draw(
+    /// Rasterise whatever of `buffer` is not in the atlas yet, and return where
+    /// each glyph goes relative to the text's top-left.
+    ///
+    /// Nothing is uploaded for a glyph already in the atlas, which is the point
+    /// of having one: a resize re-runs this and touches the GPU only if the new
+    /// width brought genuinely new glyphs into view.
+    pub fn place(&mut self, buffer: &TextBuffer, textures: &mut Textures) -> Vec<PlacedGlyph> {
+        let mut placed = Vec::new();
+        for line in buffer.layout.lines() {
+            for item in line.items() {
+                let PositionedLayoutItem::GlyphRun(run) = item else {
+                    continue;
+                };
+                let font = run.run().font();
+                let font_size = run.run().font_size();
+                let coords = run.run().normalized_coords();
+                let run_color = run.style().brush;
+                let Some(font_ref) = FontRef::from_index(font.data.as_ref(), font.index as usize)
+                else {
+                    continue;
+                };
+                let coords_hash = hash_coords(coords);
+                // `font.data.id()` rather than the pointer, so the same font
+                // loaded twice is still one set of entries.
+                let font_id = font.data.id();
+
+                for glyph in run.positioned_glyphs() {
+                    let subpixel = ((glyph.x.fract() * 4.0).round() as i32).rem_euclid(4) as u8;
+                    let key = GlyphKey {
+                        font: font_id,
+                        glyph: glyph.id,
+                        size: (font_size * 16.0).round() as u32,
+                        subpixel,
+                        coords: coords_hash,
+                    };
+                    let entry = match self.atlas.get(&key) {
+                        Some(entry) => entry,
+                        None => {
+                            let mut scaler = self
+                                .scale_cx
+                                .builder(font_ref)
+                                .size(font_size)
+                                .hint(true)
+                                .normalized_coords(coords)
+                                .build();
+                            let image = Render::new(&[
+                                Source::ColorOutline(0),
+                                Source::ColorBitmap(StrikeWith::BestFit),
+                                Source::Outline,
+                            ])
+                            .format(Format::Alpha)
+                            .offset(Vector::new(subpixel as f32 / 4.0, 0.0))
+                            .render(&mut scaler, glyph.id as u16);
+                            match image {
+                                Some(image) => self.atlas.insert(key, &image, textures),
+                                None => {
+                                    self.atlas.insert_empty(key);
+                                    None
+                                }
+                            }
+                        }
+                    };
+                    let Some(entry) = entry else { continue };
+                    placed.push(PlacedGlyph {
+                        entry,
+                        offset: Vec2::new(
+                            glyph.x.floor() + entry.left as f32,
+                            glyph.y.floor() - entry.top as f32,
+                        ),
+                        color: run_color,
+                    });
+                }
+            }
+        }
+        placed
+    }
+}
+
+fn hash_coords(coords: &[i16]) -> u64 {
+    // FxHash over the coordinates; they are short and change rarely.
+    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
+    for c in coords {
+        h ^= *c as u16 as u64;
+        h = h.wrapping_mul(0x1000_0000_01b3);
+    }
+    h
+}
+
+/// A laid-out string, ready to draw: where each glyph goes and how big the
+/// whole thing is.
+///
+/// Cheap to clone and to keep, which is the point -- a widget holds one across
+/// frames and re-emits its quads without going near the rasteriser. `color`
+/// is the buffer's *base* colour (`TextAttrs::color`) for a caller that wants
+/// it as a whole (e.g. tinting a cursor to match); the colour each glyph is
+/// actually drawn in is `PlacedGlyph::color`, which a `SpanStyle` can
+/// override per range.
+#[derive(Clone)]
+pub struct RenderedText {
+    pub glyphs: std::sync::Arc<Vec<PlacedGlyph>>,
+    pub size: Vec2,
+    pub color: UiColor,
+    /// The [`GlyphAtlas::generation`] the glyphs above were placed against.
+    /// A holder must re-render rather than re-emit these quads once the
+    /// atlas has moved on (`GlyphAtlas::clear`'s doc says what happens
+    /// otherwise); `Painter::glyphs` debug-asserts it.
+    pub generation: u64,
+}
+
+impl TextData {
+    /// Lay out and place in one step, which is what a widget wants.
+    pub fn render(
         &mut self,
         buffer: &mut TextBuffer,
         attrs: &TextAttrs,
+        width: Option<f32>,
         textures: &mut Textures,
+        density: f32,
     ) -> RenderedText {
-        // TODO: either this or the layout stuff (or both) is super slow,
-        // should probably do texture packing and things if possible.
-        // very visible if you add just a couple of wrapping texts and resize window
-        // should also be timed to figure out exactly what points need to be sped up
-        // let mut pixels = HashMap::<_, [u8; 4]>::default();
-        let mut min_x = 0;
-        let mut min_y = 0;
-        let mut max_x = 0;
-        let mut max_y = 0;
-        let text_color = {
-            let c = attrs.color;
-            cosmic_text::Color::rgba(c.r, c.g, c.b, c.a)
-        };
-        let mut max_width = 0.0f32;
-        let mut height = 0.0;
-
-        for run in buffer.layout_runs() {
-            for glyph in run.glyphs.iter() {
-                let physical_glyph = glyph.physical((0., 0.), 1.0);
-
-                let glyph_color = match glyph.color_opt {
-                    Some(some) => some,
-                    None => text_color,
-                };
-
-                if let Some(img) = self
-                    .swash_cache
-                    .get_image(&mut self.font_system, physical_glyph.cache_key)
-                {
-                    let mut pos = img.placement;
-                    pos.left += physical_glyph.x;
-                    pos.top = physical_glyph.y + run.line_y as i32 - pos.top;
-                    min_x = min_x.min(pos.left);
-                    min_y = min_y.min(pos.top);
-                    max_x = max_x.max(pos.left + pos.width as i32);
-                    max_y = max_y.max(pos.top + pos.height as i32);
-                    self.glyph_cache
-                        .push((pos, physical_glyph.cache_key, glyph_color));
-                }
-            }
-            max_width = max_width.max(run.line_w);
-            height += run.line_height;
-        }
-        let img_width = (max_x - min_x + 1) as u32;
-        let img_height = (max_y - min_y + 1) as u32;
-        let mut image = RgbaImage::new(img_width, img_height);
-
-        for (pos, key, color) in self.glyph_cache.drain(..) {
-            let img = self
-                .swash_cache
-                .get_image(&mut self.font_system, key)
-                .as_ref()
-                .unwrap();
-            let mut merge = |i, color: [u8; 4]| {
-                let i = i as i32;
-                let x = (i % pos.width as i32 + pos.left - min_x) as u32;
-                let y = (i / pos.width as i32 + pos.top - min_y) as u32;
-                let pixel = &mut image[(x, y)].0;
-                // TODO: no clue if proper alpha blending should be done
-                *pixel = Simd::from(color).saturating_add(Simd::from(*pixel)).into();
-            };
-
-            match img.content {
-                SwashContent::Mask => {
-                    for (i, a) in img.data.iter().enumerate() {
-                        let mut color = color.as_rgba();
-                        color[3] = ((color[3] as u32 * *a as u32) / u8::MAX as u32) as u8;
-                        merge(i, color);
-                    }
-                }
-                SwashContent::SubpixelMask => todo!("subpixel mask text rendering"),
-                SwashContent::Color => {
-                    let (colors, _) = img.data.as_chunks::<4>();
-                    for (i, color) in colors.iter().enumerate() {
-                        merge(i, *color);
-                    }
-                }
-            }
-        }
-
-        let max_dim = 8192;
-        if image.width() > max_dim || image.height() > max_dim {
-            let width = image.width().min(max_dim);
-            let height = image.height().min(max_dim);
-            eprintln!(
-                "WARNING: image of size {:?} cropped to {:?} (texture too big)",
-                image.dimensions(),
-                (width, height)
-            );
-            image = image.view(0, 0, width, height).to_image();
-        }
-
+        buffer.shape(self, attrs, width, density);
+        let glyphs = self.place(buffer, textures);
         RenderedText {
-            handle: textures.add(image),
-            top_left_offset: Vec2::new(min_x as f32, min_y as f32),
-            size: Vec2::new(max_width, height),
+            glyphs: std::sync::Arc::new(glyphs),
+            size: buffer.size(),
+            color: attrs.color,
+            generation: self.atlas.generation(),
         }
     }
 }
 
-#[derive(Clone)]
-pub struct RenderedText {
-    pub handle: TextureHandle,
-    pub top_left_offset: Vec2,
-    pub size: Vec2,
-}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::icon;
 
-pub trait HasTextures {
-    fn add_texture(&mut self, image: DynamicImage) -> TextureHandle;
+    /// Every codepoint `icon` names is actually in the subset the script
+    /// built. This is the failure `build-icon-font.sh`'s own comment warns
+    /// about -- a constant added on one side and not the other is a glyph
+    /// that silently isn't there -- and it is invisible at runtime,
+    /// because a missing glyph draws as nothing rather than as an error.
+    #[test]
+    fn every_icon_is_in_the_bundled_font() {
+        let font = FontRef::from_index(NERD_ICONS, 0).expect("the bundled icon font parses");
+        let charmap = font.charmap();
+        for (name, glyph) in [
+            ("OPEN", icon::OPEN),
+            ("CLOSED", icon::CLOSED),
+            ("COLLAPSE", icon::COLLAPSE),
+        ] {
+            let mut chars = glyph.chars();
+            let ch = chars.next().expect("an icon is one character");
+            assert!(chars.next().is_none(), "{name} is more than one character");
+            assert_ne!(
+                charmap.map(ch),
+                0,
+                "{name} (U+{:04X}) is not in nerd_icons.ttf -- add it to \
+                 build-icon-font.sh's GLYPHS and rerun the script",
+                ch as u32
+            );
+        }
+    }
+
+    /// The font registers, so `Family::Icons` resolves to a real family
+    /// rather than falling through to sans-serif and drawing tofu.
+    #[test]
+    fn the_icon_family_registers_and_resolves() {
+        let data = TextData::default();
+        let family = data.resolve_family(&Family::Icons);
+        assert!(
+            matches!(family, Family::Named(_)),
+            "the bundled icon font did not register: {:?}",
+            data.icon_family
+        );
+    }
 }