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/color.rs

@@ -10,6 +10,15 @@ pub struct Color<T> {
     pub a: T,
 }
 
+/// Required by parley's `Brush`, which every text style is generic over. Opaque
+/// black rather than transparent: a brush that was never set should be visible
+/// and obviously unstyled, not invisible.
+impl<T: ColorNum> Default for Color<T> {
+    fn default() -> Self {
+        Self::BLACK
+    }
+}
+
 impl<T: ColorNum> Color<T> {
     pub const BLACK: Self = Self::rgb(T::MIN, T::MIN, T::MIN);
     pub const WHITE: Self = Self::rgb(T::MAX, T::MAX, T::MAX);
@@ -144,7 +153,7 @@ impl ColorNum for f32 {
 
 unsafe impl bytemuck::Pod for Color<u8> {}
 
-impl const F32Conversion for f32 {
+const impl F32Conversion for f32 {
     fn to(self) -> f32 {
         self
     }
@@ -153,7 +162,7 @@ impl const F32Conversion for f32 {
     }
 }
 
-impl const F32Conversion for u8 {
+const impl F32Conversion for u8 {
     fn to(self) -> f32 {
         self as f32 / 255.0
     }

core/src/primitive/layer.rs

@@ -1,9 +1,6 @@
 use std::ops::{Index, IndexMut};
 
-use crate::{
-    render::{MaskIdx, Primitive, PrimitiveHandle, PrimitiveInst, Primitives},
-    util::to_mut,
-};
+use crate::{render::LayerOrder, util::to_mut};
 
 pub type LayerId = usize;
 
@@ -39,7 +36,10 @@ struct Child {
     tail: usize,
 }
 
-pub type PrimitiveLayers = Layers<Primitives>;
+/// The draw order of every layer. The primitives themselves live in one
+/// arena beside this (`UiRenderState::primitives`); a layer names the
+/// slots it draws, which is what its vertex buffer is.
+pub type PrimitiveLayers = Layers<LayerOrder>;
 
 impl<T: Default> Layers<T> {
     pub fn new() -> Layers<T> {
@@ -119,20 +119,6 @@ impl<T: Default> Layers<T> {
     }
 }
 
-impl PrimitiveLayers {
-    pub fn write<P: Primitive>(
-        &mut self,
-        layer: LayerId,
-        info: PrimitiveInst<P>,
-    ) -> PrimitiveHandle {
-        self[layer].write(layer, info)
-    }
-
-    pub fn free(&mut self, h: &PrimitiveHandle) -> MaskIdx {
-        self[h.layer].free(h)
-    }
-}
-
 impl<T: Default> Default for Layers<T> {
     fn default() -> Self {
         Self::new()

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
+        );
+    }
 }

core/src/primitive/texture.rs

@@ -1,19 +1,44 @@
-use crate::{
-    render::TexturePrimitive,
-    util::{RefCounter, Vec2},
-};
+use crate::util::{RefCounter, Vec2};
 use image::{DynamicImage, GenericImageView};
 use std::{
+    collections::HashMap,
     ops::Index,
     sync::mpsc::{Receiver, Sender, channel},
 };
 
+/// Which of the two things a texture slot holds. See TEXTURES.md's
+/// "Recommended shape" for why these are drawn so differently: a page is a
+/// layer of one shared array texture and never gets its own bind group; a
+/// standalone image is the opposite, one texture and one bind group, never a
+/// layer.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TextureKind {
+    Image,
+    /// The array-texture layer this page was assigned. Chosen synchronously
+    /// by `Textures::add_page` rather than by the renderer, because glyph
+    /// insertion needs it in the same call, before any GPU sync happens.
+    Page {
+        layer: u32,
+    },
+}
+
+/// What a [`Textures::shared`] texture is a picture of -- exactly, not by
+/// hash: `owner` names the widget kind whose description it is, and `id`
+/// packs that description's own fields, so two owners cannot collide and
+/// a debugger shows which picture a slot holds.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub struct SharedTextureKey {
+    pub owner: &'static str,
+    pub id: u64,
+}
+
 #[derive(Debug, Clone)]
 pub struct TextureHandle {
-    inner: TexturePrimitive,
+    slot: u32,
+    kind: TextureKind,
     size: Vec2,
     counter: RefCounter,
-    send: Sender<u32>,
+    send: Sender<(TextureKind, u32)>,
 }
 
 /// a texture manager for a ui
@@ -21,22 +46,47 @@ pub struct TextureHandle {
 pub struct Textures {
     free: Vec<u32>,
     images: Vec<Option<DynamicImage>>,
+    /// What each slot is, kept beside the image so a slot can be pushed
+    /// again without the handle that knows -- see [`Textures::reupload`].
+    kinds: Vec<TextureKind>,
+    /// Textures built from a description rather than from a file, one per
+    /// distinct description: see [`Textures::shared`]. The map holds a
+    /// reference of its own, so a shared texture outlives every widget
+    /// drawing it and its slot is never recycled underneath one.
+    shared: HashMap<SharedTextureKey, TextureHandle>,
+    /// Next layer to hand out to an atlas page. Pages are never freed (no
+    /// atlas eviction), so this only grows and `free` never holds one.
+    next_page_layer: u32,
     updates: Vec<Update>,
-    send: Sender<u32>,
-    recv: Receiver<u32>,
+    send: Sender<(TextureKind, u32)>,
+    recv: Receiver<(TextureKind, u32)>,
 }
 
 pub enum TextureUpdate<'a> {
-    Push(&'a DynamicImage),
-    Set(u32, &'a DynamicImage),
+    Push(TextureKind, &'a DynamicImage),
+    Set(TextureKind, u32, &'a DynamicImage),
+    /// Overwrite a rectangle of an existing texture, rather than replacing it.
+    /// The glyph atlas grows a glyph at a time, and re-uploading a whole atlas
+    /// per glyph is megabytes of copy for a few hundred bytes of change.
+    /// Only ever issued against a page -- a standalone image is never patched.
+    Patch(u32, PatchRect, &'a DynamicImage),
     Free(u32),
-    PushFree,
+    PushFree(TextureKind),
     SetFree,
 }
 
+#[derive(Debug, Clone, Copy)]
+pub struct PatchRect {
+    pub x: u32,
+    pub y: u32,
+    pub width: u32,
+    pub height: u32,
+}
+
 enum Update {
-    Push(u32),
-    Set(u32),
+    Push(TextureKind, u32),
+    Set(TextureKind, u32),
+    Patch(u32, PatchRect),
     Free(u32),
 }
 
@@ -46,58 +96,162 @@ impl Textures {
         Self {
             free: Vec::new(),
             images: Vec::new(),
+            kinds: Vec::new(),
+            shared: HashMap::new(),
+            next_page_layer: 0,
             updates: Vec::new(),
             send,
             recv,
         }
     }
+
     pub fn add(&mut self, image: impl Into<DynamicImage>) -> TextureHandle {
         let image = image.into();
         let size = image.dimensions().into();
-        let view_idx = self.push(image);
-        // 0 == default in renderer; TODO: actually create samplers here
-        let sampler_idx = 0;
+        let kind = TextureKind::Image;
+        let slot = self.push(kind, image);
         TextureHandle {
-            inner: TexturePrimitive {
-                view_idx,
-                sampler_idx,
-            },
+            slot,
+            kind,
             size,
             counter: RefCounter::new(),
             send: self.send.clone(),
         }
     }
 
-    fn push(&mut self, image: DynamicImage) -> u32 {
+    /// Adds a page of the shared glyph atlas array. Only `atlas.rs` should
+    /// call this -- everything else wants `add`.
+    pub fn add_page(&mut self, image: impl Into<DynamicImage>) -> TextureHandle {
+        let image = image.into();
+        let size = image.dimensions().into();
+        let layer = self.next_page_layer;
+        self.next_page_layer += 1;
+        let kind = TextureKind::Page { layer };
+        let slot = self.push(kind, image);
+        TextureHandle {
+            slot,
+            kind,
+            size,
+            counter: RefCounter::new(),
+            send: self.send.clone(),
+        }
+    }
+
+    fn push(&mut self, kind: TextureKind, image: DynamicImage) -> u32 {
         if let Some(i) = self.free.pop() {
             self.images[i as usize] = Some(image);
-            self.updates.push(Update::Set(i));
+            self.kinds[i as usize] = kind;
+            self.updates.push(Update::Set(kind, i));
             i
         } else {
             let i = self.images.len() as u32;
             self.images.push(Some(image));
-            self.updates.push(Update::Push(i));
+            self.kinds.push(kind);
+            self.updates.push(Update::Push(kind, i));
             i
         }
     }
 
+    /// The one texture for `key`, building it on the first ask and handing
+    /// out a further reference to it every time after.
+    ///
+    /// **Why this exists**: a texture rasterised from a *description* --
+    /// `widget::mark`'s triangle, from a direction and a colour -- has as
+    /// many copies as there are widgets asking for it, and each copy is
+    /// its own GPU texture, its own bind group and its own draw call. A
+    /// transcript screen with a folded card per tool call built one per
+    /// card: hundreds of 48x48 textures of three distinct pictures,
+    /// created and freed again as rows recycled. `make` is not called when
+    /// the key is already known, so the rasterising is paid once too.
+    ///
+    /// The map keeps its own reference for the life of the `Textures`, so
+    /// a shared slot is never freed and never reused for something else --
+    /// which is what makes a handle held by a long-lived widget safe.
+    pub fn shared(
+        &mut self,
+        key: SharedTextureKey,
+        make: impl FnOnce() -> DynamicImage,
+    ) -> TextureHandle {
+        if let Some(handle) = self.shared.get(&key) {
+            return handle.clone();
+        }
+        let handle = self.add(make());
+        self.shared.insert(key, handle.clone());
+        handle
+    }
+
+    /// The stored image for a handle, to be written into before `patch`.
+    pub fn image_mut(&mut self, handle: &TextureHandle) -> &mut DynamicImage {
+        self.images[handle.slot as usize]
+            .as_mut()
+            .expect("texture was freed while still held")
+    }
+
+    /// Queue an upload of just `rect`, after writing it with `image_mut`.
+    pub fn patch(&mut self, handle: &TextureHandle, rect: PatchRect) {
+        self.updates.push(Update::Patch(handle.slot, rect));
+    }
+
+    /// Queue every live slot for upload again, in slot order -- what a
+    /// genuinely new GPU device needs, in place of forgetting everything.
+    ///
+    /// A new device starts with no textures, and the renderer-side mirror
+    /// of these slots (`render::texture::GpuTextures`) starts empty with
+    /// it. What it must not do is start empty while the handles widgets
+    /// are still holding name slots by *index*: `Textures::reset` used to
+    /// throw this bookkeeping away, which left every live `TextureHandle`
+    /// -- one per `widget::mark`, hundreds on a transcript screen --
+    /// pointing at a slot nothing recognised, and the first frame after an
+    /// Android surface rebuild panicked in `image_bind_group` ("texture
+    /// slot 89 is not a live standalone image: None"). Re-uploading
+    /// instead keeps every index meaning what it meant, because this side
+    /// still holds the images: the slot list is rebuilt identically,
+    /// including the empty slots, which go across as `PushFree` so the
+    /// ones after them still land where they were.
+    ///
+    /// The glyph atlas comes back with it and is deliberately *not*
+    /// cleared any more: its pages are slots here, this side holds their
+    /// pixels, and re-uploading them restores exactly the atlas that was
+    /// there -- so an app switch no longer costs a re-rasterisation of
+    /// every glyph on screen either.
+    ///
+    /// Pending updates are dropped rather than kept: each is either a push
+    /// or a patch of a slot this replays in full.
+    pub fn reupload(&mut self) {
+        self.updates.clear();
+        self.updates
+            .extend((0..self.images.len() as u32).map(|i| Update::Push(self.kinds[i as usize], i)));
+    }
+
     pub fn free(&mut self) {
-        for idx in self.recv.try_iter() {
+        for (kind, idx) in self.recv.try_iter() {
             self.images[idx as usize] = None;
             self.updates.push(Update::Free(idx));
-            self.free.push(idx);
+            // A page's slot is never reclaimed: `GlyphAtlas` never drops the
+            // handles it holds, and there is no eviction path for a hole in
+            // the middle of the array's layers. If that ever changes, this
+            // is where a freed page's layer would need to go on a free list
+            // of its own, separate from `free`, which only ever holds
+            // ordinary image slots today.
+            if kind == TextureKind::Image {
+                self.free.push(idx);
+            }
         }
     }
 
     pub fn updates(&mut self) -> impl Iterator<Item = TextureUpdate<'_>> {
         self.updates.drain(..).map(|u| match u {
-            Update::Push(i) => self.images[i as usize]
+            Update::Push(kind, i) => self.images[i as usize]
                 .as_ref()
-                .map(TextureUpdate::Push)
-                .unwrap_or(TextureUpdate::PushFree),
-            Update::Set(i) => self.images[i as usize]
+                .map(|img| TextureUpdate::Push(kind, img))
+                .unwrap_or(TextureUpdate::PushFree(kind)),
+            Update::Set(kind, i) => self.images[i as usize]
                 .as_ref()
-                .map(|img| TextureUpdate::Set(i, img))
+                .map(|img| TextureUpdate::Set(kind, i, img))
+                .unwrap_or(TextureUpdate::SetFree),
+            Update::Patch(i, rect) => self.images[i as usize]
+                .as_ref()
+                .map(|img| TextureUpdate::Patch(i, rect, img))
                 .unwrap_or(TextureUpdate::SetFree),
             Update::Free(i) => TextureUpdate::Free(i),
         })
@@ -105,18 +259,36 @@ impl Textures {
 }
 
 impl TextureHandle {
-    pub fn primitive(&self) -> TexturePrimitive {
-        self.inner
-    }
     pub fn size(&self) -> Vec2 {
         self.size
     }
+
+    /// The bind-group index this handle draws with. Only valid for a
+    /// standalone image; an atlas page has no bind group of its own -- it
+    /// samples the shared array via `layer()` instead. Getting this wrong is
+    /// a caller bug (the wrong kind of handle reached the wrong draw path),
+    /// not a recoverable condition, so it panics rather than drawing garbage.
+    pub fn image_index(&self) -> u32 {
+        match self.kind {
+            TextureKind::Image => self.slot,
+            TextureKind::Page { .. } => panic!("image_index() called on an atlas page handle"),
+        }
+    }
+
+    /// The layer this page occupies in the shared atlas array texture.
+    /// Only valid for a page handle; see `image_index`'s note.
+    pub fn layer(&self) -> u32 {
+        match self.kind {
+            TextureKind::Page { layer } => layer,
+            TextureKind::Image => panic!("layer() called on a standalone image handle"),
+        }
+    }
 }
 
 impl Drop for TextureHandle {
     fn drop(&mut self) {
         if self.counter.drop() {
-            let _ = self.send.send(self.inner.view_idx);
+            let _ = self.send.send((self.kind, self.slot));
         }
     }
 }
@@ -125,7 +297,7 @@ impl Index<&TextureHandle> for Textures {
     type Output = DynamicImage;
 
     fn index(&self, index: &TextureHandle) -> &Self::Output {
-        self.images[index.inner.view_idx as usize].as_ref().unwrap()
+        self.images[index.slot as usize].as_ref().unwrap()
     }
 }
 
@@ -134,3 +306,90 @@ impl Default for Textures {
         Self::new()
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use image::RgbaImage;
+
+    fn image(n: u32) -> DynamicImage {
+        RgbaImage::new(n, n).into()
+    }
+
+    fn key(id: u64) -> SharedTextureKey {
+        SharedTextureKey { owner: "test", id }
+    }
+
+    /// What `widget::mark` needs: one texture per description, however
+    /// many widgets ask for it, and a different description is a
+    /// different texture.
+    #[test]
+    fn a_shared_texture_is_built_once_and_handed_out_again() {
+        let mut textures = Textures::new();
+        let built = std::cell::Cell::new(0);
+        let make = |textures: &mut Textures, id: u64| {
+            textures.shared(key(id), || {
+                built.set(built.get() + 1);
+                image(4)
+            })
+        };
+        let first = make(&mut textures, 1);
+        let again = make(&mut textures, 1);
+        let other = make(&mut textures, 2);
+        assert_eq!(built.get(), 2, "the second ask for key 1 rasterised again");
+        assert_eq!(first.image_index(), again.image_index());
+        assert_ne!(first.image_index(), other.image_index());
+    }
+
+    /// The map's own reference is what keeps a shared slot alive: every
+    /// widget holding one can go away and the slot must not be recycled,
+    /// because the next widget to ask gets that same index back.
+    #[test]
+    fn a_shared_slot_is_not_freed_when_the_last_widget_drops_it() {
+        let mut textures = Textures::new();
+        let slot = textures.shared(key(1), || image(4)).image_index();
+        textures.free();
+        let plain = textures.add(image(4));
+        assert_ne!(
+            plain.image_index(),
+            slot,
+            "an ordinary texture was handed the shared mark's slot"
+        );
+    }
+
+    /// A new GPU device gets the same slot numbering back, so a handle a
+    /// widget has been holding all along still names its own texture --
+    /// the crash `reupload` replaced `reset` to fix.
+    #[test]
+    fn reupload_replays_every_slot_in_order_including_the_empty_ones() {
+        let mut textures = Textures::new();
+        let keep_a = textures.add(image(4));
+        let dropped = textures.add(image(4));
+        let keep_b = textures.add(image(4));
+        let (a, gone, b) = (
+            keep_a.image_index(),
+            dropped.image_index(),
+            keep_b.image_index(),
+        );
+        drop(dropped);
+        textures.free();
+        // Drain the updates so far, the way a frame does.
+        assert!(textures.updates().count() > 0);
+
+        textures.reupload();
+        let kinds: Vec<String> = textures
+            .updates()
+            .map(|u| match u {
+                TextureUpdate::Push(..) => "push".to_string(),
+                TextureUpdate::PushFree(..) => "push-free".to_string(),
+                _ => "other".to_string(),
+            })
+            .collect();
+        assert_eq!(
+            kinds,
+            ["push", "push-free", "push"],
+            "slots {a}, {gone} (freed) and {b} must replay in order, so the \
+             indices after a hole still land where they were"
+        );
+    }
+}